[app-server] expose environment info RPC

codex-rs/app-server-protocol/src/export.rs

@@ -43,6 +43,8 @@ pub(crate) const GENERATED_TS_HEADER: &str = "// GENERATED CODE! DO NOT MODIFY B
 const IGNORED_DEFINITIONS: &[&str] = &["Option<()>"];
 const JSON_V1_ALLOWLIST: &[&str] = &["InitializeParams", "InitializeResponse"];
 const EXPERIMENTAL_CLIENT_METHOD_DEPENDENCY_TYPES: &[&str] = &[
+    "EnvironmentShellInfo",
+    "PathUri",
     "RemoteControlClient",
     "RemoteControlClientsListOrder",
     "ThreadBackgroundTerminal",

codex-rs/app-server-protocol/src/protocol/common.rs

@@ -943,6 +943,13 @@ client_request_definitions! {
         serialization: global("environment"),
         response: v2::EnvironmentAddResponse,
     },
+    #[experimental("environment/info")]
+    /// Reads information from a configured execution environment.
+    EnvironmentInfo => "environment/info" {
+        params: v2::EnvironmentInfoParams,
+        serialization: global_shared_read("environment"),
+        response: v2::EnvironmentInfoResponse,
+    },
 
     McpServerOauthLogin => "mcpServer/oauth/login" {
         params: v2::McpServerOauthLoginParams,

codex-rs/app-server-protocol/src/protocol/v2/environment.rs

@@ -1,3 +1,4 @@
+use codex_utils_path_uri::PathUri;
 use schemars::JsonSchema;
 use serde::Deserialize;
 use serde::Serialize;
@@ -19,3 +20,29 @@ pub struct EnvironmentAddParams {
 #[serde(rename_all = "camelCase")]
 #[ts(export_to = "v2/")]
 pub struct EnvironmentAddResponse {}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub struct EnvironmentInfoParams {
+    pub environment_id: String,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub struct EnvironmentInfoResponse {
+    pub shell: EnvironmentShellInfo,
+    /// Default working directory reported by the environment, as a canonical file URI.
+    pub cwd: Option<PathUri>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub struct EnvironmentShellInfo {
+    /// Stable shell name, for example `zsh`, `bash`, `powershell`, `sh`, or `cmd`.
+    pub name: String,
+    /// Target-native shell executable path or command name.
+    pub path: String,
+}

codex-rs/app-server/README.md

@@ -205,6 +205,7 @@ Example with notification opt-out:
 - `permissionProfile/list` — beta; list available permission profile ids with optional display `description` text and an `allowed` flag reflecting effective requirements, using cursor pagination. Pass `cwd` when the caller needs project-local `[permissions.<id>]` entries to be included in the current catalog view.
 - `experimentalFeature/enablement/set` — patch the in-memory process-wide runtime feature enablement for currently supported feature keys. For each feature, precedence is: cloud requirements > --enable <feature_name> > config.toml > experimentalFeature/enablement/set (new) > code default. Invalid keys will be ignored.
 - `environment/add` — experimental; add or replace a named remote environment by `environmentId` and `execServerUrl` for later selection by `thread/start` or `turn/start`; optional `connectTimeoutMs` overrides the WebSocket connection timeout; returns `{}` and does not change the default environment.
+- `environment/info` — experimental; connect to a configured environment by `environmentId` and return its detected `shell` plus its default `cwd` as a canonical environment-native `file:` URI. Connection failures are returned as request errors.
 - `collaborationMode/list` — list available collaboration mode presets (experimental, no pagination). Built-in presets do not select a model; the Plan preset selects medium reasoning effort. This response omits built-in developer instructions; clients should either pass `settings.developer_instructions: null` when setting a mode to use Codex's built-in instructions, or provide their own instructions explicitly.
 - `skills/list` — list skills for one or more `cwd` values (optional `forceReload`).
 - `skills/extraRoots/set` — replace the app-server process runtime extra standalone skill roots. The roots are not persisted; missing directories are accepted and simply load no skills.

codex-rs/app-server/src/message_processor.rs

@@ -1037,6 +1037,9 @@ impl MessageProcessor {
             ClientRequest::EnvironmentAdd { params, .. } => {
                 self.environment_processor.environment_add(params).await
             }
+            ClientRequest::EnvironmentInfo { params, .. } => {
+                self.environment_processor.environment_info(params).await
+            }
             ClientRequest::FsReadFile { params, .. } => self
                 .fs_processor
                 .read_file(params)

codex-rs/app-server/src/request_processors.rs

@@ -62,6 +62,9 @@ use codex_app_server_protocol::DynamicToolNamespaceTool;
 use codex_app_server_protocol::DynamicToolSpec;
 use codex_app_server_protocol::EnvironmentAddParams;
 use codex_app_server_protocol::EnvironmentAddResponse;
+use codex_app_server_protocol::EnvironmentInfoParams;
+use codex_app_server_protocol::EnvironmentInfoResponse;
+use codex_app_server_protocol::EnvironmentShellInfo;
 use codex_app_server_protocol::ExperimentalFeature as ApiExperimentalFeature;
 use codex_app_server_protocol::ExperimentalFeatureListParams;
 use codex_app_server_protocol::ExperimentalFeatureListResponse;

codex-rs/app-server/src/request_processors/environment_processor.rs

@@ -26,4 +26,30 @@ impl EnvironmentRequestProcessor {
             .map_err(|err| invalid_request(err.to_string()))?;
         Ok(Some(EnvironmentAddResponse {}.into()))
     }
+
+    pub(crate) async fn environment_info(
+        &self,
+        params: EnvironmentInfoParams,
+    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError> {
+        let environment_id = params.environment_id;
+        let environment = self
+            .environment_manager
+            .get_environment(&environment_id)
+            .ok_or_else(|| invalid_request(format!("unknown environment id `{environment_id}`")))?;
+        let info = environment.info().await.map_err(|err| {
+            internal_error(format!(
+                "failed to get info for environment `{environment_id}`: {err}"
+            ))
+        })?;
+        Ok(Some(
+            EnvironmentInfoResponse {
+                shell: EnvironmentShellInfo {
+                    name: info.shell.name,
+                    path: info.shell.path,
+                },
+                cwd: info.cwd,
+            }
+            .into(),
+        ))
+    }
 }

codex-rs/app-server/tests/suite/v2/environment_info.rs

@@ -0,0 +1,208 @@
+use std::time::Duration;
+
+use anyhow::Result;
+use app_test_support::TestAppServer;
+use app_test_support::to_response;
+use codex_app_server_protocol::EnvironmentAddResponse;
+use codex_app_server_protocol::EnvironmentInfoResponse;
+use codex_app_server_protocol::EnvironmentShellInfo;
+use codex_app_server_protocol::JSONRPCError;
+use codex_app_server_protocol::JSONRPCErrorError;
+use codex_app_server_protocol::JSONRPCResponse;
+use codex_app_server_protocol::RequestId;
+use codex_utils_path_uri::PathUri;
+use pretty_assertions::assert_eq;
+use serde_json::json;
+use tempfile::TempDir;
+use tokio::net::TcpListener;
+use tokio::time::timeout;
+
+use super::exec_server_test_support::accept_exec_server_environment;
+
+const RPC_TIMEOUT: Duration = Duration::from_secs(10);
+const INVALID_REQUEST_ERROR_CODE: i64 = -32600;
+const INTERNAL_ERROR_CODE: i64 = -32603;
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn environment_info_returns_remote_environment_info() -> Result<()> {
+    let listener = TcpListener::bind("127.0.0.1:0").await?;
+    let exec_server_url = format!("ws://{}", listener.local_addr()?);
+    let exec_server = tokio::spawn(async move {
+        accept_exec_server_environment(
+            listener,
+            json!({
+                "shell": {"name": "zsh", "path": "/bin/zsh"},
+                "cwd": "file:///workspace",
+            }),
+        )
+        .await?;
+        Ok::<_, anyhow::Error>(())
+    });
+
+    let codex_home = TempDir::new()?;
+    let mut app_server = TestAppServer::new(codex_home.path()).await?;
+    timeout(RPC_TIMEOUT, app_server.initialize()).await??;
+    add_environment(
+        &mut app_server,
+        &exec_server_url,
+        /*connect_timeout_ms*/ None,
+    )
+    .await?;
+
+    let request_id = app_server
+        .send_raw_request(
+            "environment/info",
+            Some(json!({"environmentId": "remote-a"})),
+        )
+        .await?;
+    let response: JSONRPCResponse = timeout(
+        RPC_TIMEOUT,
+        app_server.read_stream_until_response_message(RequestId::Integer(request_id)),
+    )
+    .await??;
+    assert_eq!(
+        to_response::<EnvironmentInfoResponse>(response)?,
+        EnvironmentInfoResponse {
+            shell: EnvironmentShellInfo {
+                name: "zsh".to_string(),
+                path: "/bin/zsh".to_string(),
+            },
+            cwd: Some(PathUri::parse("file:///workspace")?),
+        }
+    );
+    timeout(RPC_TIMEOUT, exec_server).await???;
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn environment_info_accepts_missing_cwd() -> Result<()> {
+    let listener = TcpListener::bind("127.0.0.1:0").await?;
+    let exec_server_url = format!("ws://{}", listener.local_addr()?);
+    let exec_server = tokio::spawn(async move {
+        accept_exec_server_environment(
+            listener,
+            json!({"shell": {"name": "zsh", "path": "/bin/zsh"}}),
+        )
+        .await?;
+        Ok::<_, anyhow::Error>(())
+    });
+
+    let codex_home = TempDir::new()?;
+    let mut app_server = TestAppServer::new(codex_home.path()).await?;
+    timeout(RPC_TIMEOUT, app_server.initialize()).await??;
+    add_environment(
+        &mut app_server,
+        &exec_server_url,
+        /*connect_timeout_ms*/ None,
+    )
+    .await?;
+
+    let request_id = app_server
+        .send_raw_request(
+            "environment/info",
+            Some(json!({"environmentId": "remote-a"})),
+        )
+        .await?;
+    let response: JSONRPCResponse = timeout(
+        RPC_TIMEOUT,
+        app_server.read_stream_until_response_message(RequestId::Integer(request_id)),
+    )
+    .await??;
+    assert_eq!(
+        to_response::<EnvironmentInfoResponse>(response)?,
+        EnvironmentInfoResponse {
+            shell: EnvironmentShellInfo {
+                name: "zsh".to_string(),
+                path: "/bin/zsh".to_string(),
+            },
+            cwd: None,
+        }
+    );
+    timeout(RPC_TIMEOUT, exec_server).await???;
+    Ok(())
+}
+
+#[tokio::test]
+async fn environment_info_rejects_unknown_environment() -> Result<()> {
+    let codex_home = TempDir::new()?;
+    let mut app_server = TestAppServer::new(codex_home.path()).await?;
+    timeout(RPC_TIMEOUT, app_server.initialize()).await??;
+
+    let request_id = app_server
+        .send_raw_request(
+            "environment/info",
+            Some(json!({"environmentId": "missing"})),
+        )
+        .await?;
+    let error = timeout(
+        RPC_TIMEOUT,
+        app_server.read_stream_until_error_message(RequestId::Integer(request_id)),
+    )
+    .await??;
+    assert_eq!(
+        error,
+        JSONRPCError {
+            id: RequestId::Integer(request_id),
+            error: JSONRPCErrorError {
+                code: INVALID_REQUEST_ERROR_CODE,
+                message: "unknown environment id `missing`".to_string(),
+                data: None,
+            },
+        }
+    );
+    Ok(())
+}
+
+#[tokio::test]
+async fn environment_info_reports_connection_failure() -> Result<()> {
+    let listener = TcpListener::bind("127.0.0.1:0").await?;
+    let exec_server_url = format!("ws://{}", listener.local_addr()?);
+    let codex_home = TempDir::new()?;
+    let mut app_server = TestAppServer::new(codex_home.path()).await?;
+    timeout(RPC_TIMEOUT, app_server.initialize()).await??;
+    add_environment(&mut app_server, &exec_server_url, Some(50)).await?;
+
+    let request_id = app_server
+        .send_raw_request(
+            "environment/info",
+            Some(json!({"environmentId": "remote-a"})),
+        )
+        .await?;
+    let error = timeout(
+        RPC_TIMEOUT,
+        app_server.read_stream_until_error_message(RequestId::Integer(request_id)),
+    )
+    .await??;
+    assert_eq!(error.error.code, INTERNAL_ERROR_CODE);
+    assert!(
+        error
+            .error
+            .message
+            .contains("failed to get info for environment `remote-a`")
+    );
+    Ok(())
+}
+
+async fn add_environment(
+    app_server: &mut TestAppServer,
+    exec_server_url: &str,
+    connect_timeout_ms: Option<u64>,
+) -> Result<()> {
+    let request_id = app_server
+        .send_raw_request(
+            "environment/add",
+            Some(json!({
+                "environmentId": "remote-a",
+                "execServerUrl": exec_server_url,
+                "connectTimeoutMs": connect_timeout_ms,
+            })),
+        )
+        .await?;
+    let response: JSONRPCResponse = timeout(
+        RPC_TIMEOUT,
+        app_server.read_stream_until_response_message(RequestId::Integer(request_id)),
+    )
+    .await??;
+    let _: EnvironmentAddResponse = to_response(response)?;
+    Ok(())
+}

codex-rs/app-server/tests/suite/v2/exec_server_test_support.rs

@@ -0,0 +1,73 @@
+use anyhow::Result;
+use futures::SinkExt;
+use futures::StreamExt;
+use serde_json::Value;
+use serde_json::json;
+use tokio::net::TcpListener;
+use tokio::net::TcpStream;
+use tokio_tungstenite::WebSocketStream;
+use tokio_tungstenite::accept_async;
+use tokio_tungstenite::tungstenite::Message;
+
+pub(crate) async fn accept_exec_server_environment(
+    listener: TcpListener,
+    environment_info: Value,
+) -> Result<WebSocketStream<TcpStream>> {
+    let mut websocket = accept_initialized_exec_server(listener).await?;
+
+    let request = read_exec_server_json(&mut websocket).await?;
+    assert_eq!(request["method"], "environment/info");
+    websocket
+        .send(Message::Text(
+            json!({
+                "id": request["id"],
+                "result": environment_info,
+            })
+            .to_string()
+            .into(),
+        ))
+        .await?;
+
+    Ok(websocket)
+}
+
+pub(crate) async fn accept_initialized_exec_server(
+    listener: TcpListener,
+) -> Result<WebSocketStream<TcpStream>> {
+    let (stream, _) = listener.accept().await?;
+    let mut websocket = accept_async(stream).await?;
+
+    let initialize = read_exec_server_json(&mut websocket).await?;
+    assert_eq!(initialize["method"], "initialize");
+    websocket
+        .send(Message::Text(
+            json!({
+                "id": initialize["id"],
+                "result": {"sessionId": "test-session"},
+            })
+            .to_string()
+            .into(),
+        ))
+        .await?;
+    let initialized = read_exec_server_json(&mut websocket).await?;
+    assert_eq!(initialized["method"], "initialized");
+
+    Ok(websocket)
+}
+
+pub(crate) async fn read_exec_server_json(
+    websocket: &mut WebSocketStream<TcpStream>,
+) -> Result<Value> {
+    loop {
+        match websocket
+            .next()
+            .await
+            .ok_or_else(|| anyhow::anyhow!("exec-server websocket closed"))??
+        {
+            Message::Text(text) => return Ok(serde_json::from_str(text.as_ref())?),
+            Message::Binary(bytes) => return Ok(serde_json::from_slice(bytes.as_ref())?),
+            Message::Ping(_) | Message::Pong(_) => {}
+            message => anyhow::bail!("expected JSON-RPC message, got {message:?}"),
+        }
+    }
+}