Add files using upload-large-folder tool

codex-rs/app-server-client/src/lib.rs

@@ -0,0 +1,2136 @@
+//! Shared in-process app-server client facade for CLI surfaces.
+//!
+//! This crate wraps [`codex_app_server::in_process`] behind a single async API
+//! used by surfaces like TUI and exec. It centralizes:
+//!
+//! - Runtime startup and initialize-capabilities handshake.
+//! - Typed caller-provided startup identity (`SessionSource` + client name).
+//! - Typed and raw request/notification dispatch.
+//! - Server request resolution and rejection.
+//! - Ordered, lossless event consumption that cannot block request processing.
+//! - Bounded graceful shutdown with abort fallback.
+//!
+//! The facade interposes a worker task between the caller and the underlying
+//! [`InProcessClientHandle`](codex_app_server::in_process::InProcessClientHandle),
+//! bridging async `mpsc` channels on both sides. Commands and the underlying
+//! runtime remain bounded; the local consumer event queue is unbounded so
+//! unread notifications cannot prevent request responses from being delivered.
+
+mod path;
+mod remote;
+
+use std::error::Error;
+use std::fmt;
+use std::io::Error as IoError;
+use std::io::ErrorKind;
+use std::io::Result as IoResult;
+use std::sync::Arc;
+use std::time::Duration;
+
+pub use codex_app_server::app_server_control_socket_path;
+pub use codex_app_server::in_process::DEFAULT_IN_PROCESS_CHANNEL_CAPACITY;
+pub use codex_app_server::in_process::InProcessServerEvent;
+use codex_app_server::in_process::InProcessStartArgs;
+use codex_app_server::in_process::LogDbLayer;
+pub use codex_app_server::in_process::StateDbHandle;
+use codex_app_server_protocol::ClientInfo;
+use codex_app_server_protocol::ClientNotification;
+use codex_app_server_protocol::ClientRequest;
+use codex_app_server_protocol::ConfigWarningNotification;
+use codex_app_server_protocol::InitializeCapabilities;
+use codex_app_server_protocol::InitializeParams;
+use codex_app_server_protocol::JSONRPCErrorError;
+use codex_app_server_protocol::RequestId;
+use codex_app_server_protocol::Result as JsonRpcResult;
+use codex_app_server_protocol::ServerNotification;
+use codex_app_server_protocol::ServerRequest;
+use codex_arg0::Arg0DispatchPaths;
+use codex_config::CloudConfigBundleLoader;
+use codex_config::LoaderOverrides;
+use codex_config::NoopThreadConfigLoader;
+use codex_core::config::Config;
+pub use codex_core::otel_init::build_provider as build_otel_provider;
+pub use codex_exec_server::EnvironmentManager;
+pub use codex_exec_server::ExecServerRuntimePaths;
+use codex_feedback::CodexFeedback;
+use codex_protocol::protocol::SessionSource;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use serde::de::DeserializeOwned;
+use tokio::sync::mpsc;
+use tokio::sync::oneshot;
+use tokio::time::timeout;
+use toml::Value as TomlValue;
+use tracing::warn;
+
+pub use crate::path::AppServerPath;
+pub use crate::remote::RemoteAppServerClient;
+pub use crate::remote::RemoteAppServerConnectArgs;
+pub use crate::remote::RemoteAppServerEndpoint;
+
+/// Transitional access to core-only embedded app-server types.
+///
+/// New TUI behavior should prefer the app-server protocol methods. This
+/// module exists so clients can remove a direct `codex-core` dependency
+/// while legacy startup/config paths are migrated to RPCs.
+pub mod legacy_core {
+    pub mod config {
+        pub use codex_core::config::*;
+
+        pub mod edit {
+            pub use codex_core::config::edit::*;
+        }
+    }
+}
+
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+// Covers the embedded drain, its analytics flush, and final task join.
+const IN_PROCESS_SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(45);
+
+/// Raw app-server request result for typed in-process requests.
+///
+/// Even on the in-process path, successful responses still travel back through
+/// the same JSON-RPC result envelope used by socket/stdio transports because
+/// `MessageProcessor` continues to produce that shape internally.
+pub type RequestResult = std::result::Result<JsonRpcResult, JSONRPCErrorError>;
+
+#[derive(Debug, Clone)]
+pub enum AppServerEvent {
+    Lagged { skipped: usize },
+    ServerNotification(Box<ServerNotification>),
+    ServerRequest(Box<ServerRequest>),
+    Disconnected { message: String },
+}
+
+impl From<InProcessServerEvent> for AppServerEvent {
+    fn from(value: InProcessServerEvent) -> Self {
+        match value {
+            InProcessServerEvent::Lagged { skipped } => Self::Lagged { skipped },
+            InProcessServerEvent::ServerNotification(notification) => {
+                Self::ServerNotification(notification)
+            }
+            InProcessServerEvent::ServerRequest(request) => Self::ServerRequest(request),
+        }
+    }
+}
+
+/// Layered error for [`InProcessAppServerClient::request_typed`].
+///
+/// This keeps transport failures, server-side JSON-RPC failures, and response
+/// decode failures distinct so callers can decide whether to retry, surface a
+/// server error, or treat the response as an internal request/response mismatch.
+#[derive(Debug)]
+pub enum TypedRequestError {
+    Transport {
+        method: String,
+        source: IoError,
+    },
+    Server {
+        method: String,
+        source: JSONRPCErrorError,
+    },
+    Deserialize {
+        method: String,
+        source: serde_json::Error,
+    },
+}
+
+impl fmt::Display for TypedRequestError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Transport { method, source } => {
+                write!(f, "{method} transport error: {source}")
+            }
+            Self::Server { method, source } => {
+                write!(
+                    f,
+                    "{method} failed: {} (code {})",
+                    source.message, source.code
+                )?;
+                if let Some(data) = source.data.as_ref() {
+                    write!(f, ", data: {data}")?;
+                }
+                Ok(())
+            }
+            Self::Deserialize { method, source } => {
+                write!(f, "{method} response decode error: {source}")
+            }
+        }
+    }
+}
+
+impl Error for TypedRequestError {
+    fn source(&self) -> Option<&(dyn Error + 'static)> {
+        match self {
+            Self::Transport { source, .. } => Some(source),
+            Self::Server { .. } => None,
+            Self::Deserialize { source, .. } => Some(source),
+        }
+    }
+}
+
+#[derive(Clone)]
+pub struct InProcessClientStartArgs {
+    /// Resolved argv0 dispatch paths used by command execution internals.
+    pub arg0_paths: Arg0DispatchPaths,
+    /// Shared config used to initialize app-server runtime.
+    pub config: Arc<Config>,
+    /// CLI config overrides that are already parsed into TOML values.
+    pub cli_overrides: Vec<(String, TomlValue)>,
+    /// Loader override knobs used by config API paths.
+    pub loader_overrides: LoaderOverrides,
+    /// Whether config API paths should reject unknown config fields.
+    pub strict_config: bool,
+    /// Preloaded cloud config bundle provider.
+    pub cloud_config_bundle: CloudConfigBundleLoader,
+    /// Feedback sink used by app-server/core telemetry and logs.
+    pub feedback: CodexFeedback,
+    /// SQLite tracing layer used to flush recently emitted logs before feedback upload.
+    pub log_db: Option<LogDbLayer>,
+    /// Process-wide SQLite state handle shared with the embedded app-server.
+    pub state_db: Option<StateDbHandle>,
+    /// Environment manager used by core execution and filesystem operations.
+    pub environment_manager: Arc<EnvironmentManager>,
+    /// Startup warnings emitted after initialize succeeds.
+    pub config_warnings: Vec<ConfigWarningNotification>,
+    /// Session source recorded in app-server thread metadata.
+    pub session_source: SessionSource,
+    /// Whether auth loading should honor the `CODEX_API_KEY` environment variable.
+    pub enable_codex_api_key_env: bool,
+    /// Client name reported during initialize.
+    pub client_name: String,
+    /// Client version reported during initialize.
+    pub client_version: String,
+    /// Whether experimental APIs are requested at initialize time.
+    pub experimental_api: bool,
+    /// Whether MCP servers may send `openai/form` elicitation requests.
+    pub mcp_server_openai_form_elicitation: bool,
+    /// Notification methods this client opts out of receiving.
+    pub opt_out_notification_methods: Vec<String>,
+    /// Queue capacity for command and embedded-runtime channels (clamped to at least 1).
+    pub channel_capacity: usize,
+}
+
+impl InProcessClientStartArgs {
+    /// Builds initialize params from caller-provided metadata.
+    pub fn initialize_params(&self) -> InitializeParams {
+        let capabilities = InitializeCapabilities {
+            experimental_api: self.experimental_api,
+            request_attestation: false,
+            extensions: None,
+            opt_out_notification_methods: if self.opt_out_notification_methods.is_empty() {
+                None
+            } else {
+                Some(self.opt_out_notification_methods.clone())
+            },
+            mcp_server_openai_form_elicitation: self.mcp_server_openai_form_elicitation,
+        };
+
+        InitializeParams {
+            client_info: ClientInfo {
+                name: self.client_name.clone(),
+                title: None,
+                version: self.client_version.clone(),
+            },
+            capabilities: Some(capabilities),
+        }
+    }
+
+    fn into_runtime_start_args(self) -> InProcessStartArgs {
+        let initialize = self.initialize_params();
+        InProcessStartArgs {
+            arg0_paths: self.arg0_paths,
+            config: self.config,
+            cli_overrides: self.cli_overrides,
+            loader_overrides: self.loader_overrides,
+            strict_config: self.strict_config,
+            cloud_config_bundle: self.cloud_config_bundle,
+            thread_config_loader: Arc::new(NoopThreadConfigLoader),
+            feedback: self.feedback,
+            log_db: self.log_db,
+            state_db: self.state_db,
+            environment_manager: self.environment_manager,
+            config_warnings: self.config_warnings,
+            session_source: self.session_source,
+            enable_codex_api_key_env: self.enable_codex_api_key_env,
+            initialize,
+            channel_capacity: self.channel_capacity,
+        }
+    }
+}
+
+/// Internal command sent from public facade methods to the worker task.
+///
+/// Each variant carries a oneshot sender so the caller can `await` the
+/// result without holding a mutable reference to the client.
+enum ClientCommand {
+    Request {
+        request: Box<ClientRequest>,
+        response_tx: oneshot::Sender<IoResult<RequestResult>>,
+    },
+    Notify {
+        notification: ClientNotification,
+        response_tx: oneshot::Sender<IoResult<()>>,
+    },
+    ResolveServerRequest {
+        request_id: RequestId,
+        result: JsonRpcResult,
+        response_tx: oneshot::Sender<IoResult<()>>,
+    },
+    RejectServerRequest {
+        request_id: RequestId,
+        error: JSONRPCErrorError,
+        response_tx: oneshot::Sender<IoResult<()>>,
+    },
+    Shutdown {
+        response_tx: oneshot::Sender<IoResult<()>>,
+    },
+}
+
+/// Async facade over the in-process app-server runtime.
+///
+/// This type owns a worker task that bridges between:
+/// - caller-facing async `mpsc` channels used by TUI/exec
+/// - [`codex_app_server::in_process::InProcessClientHandle`], which speaks to
+///   the embedded `MessageProcessor`
+///
+/// The facade intentionally preserves the server's request/notification/event
+/// model instead of exposing direct core runtime handles. That keeps in-process
+/// callers aligned with app-server behavior while still avoiding a process
+/// boundary.
+pub struct InProcessAppServerClient {
+    command_tx: mpsc::Sender<ClientCommand>,
+    event_rx: mpsc::UnboundedReceiver<InProcessServerEvent>,
+    worker_handle: tokio::task::JoinHandle<()>,
+}
+
+#[derive(Clone)]
+pub struct InProcessAppServerRequestHandle {
+    command_tx: mpsc::Sender<ClientCommand>,
+}
+
+#[derive(Clone)]
+pub enum AppServerRequestHandle {
+    InProcess(InProcessAppServerRequestHandle),
+    Remote(crate::remote::RemoteAppServerRequestHandle),
+}
+
+pub enum AppServerClient {
+    InProcess(InProcessAppServerClient),
+    Remote(RemoteAppServerClient),
+}
+
+impl InProcessAppServerClient {
+    /// Starts the in-process runtime and facade worker task.
+    ///
+    /// The returned client is ready for requests and ordered event consumption.
+    /// Request queues remain bounded without blocking on unread notifications.
+    pub async fn start(args: InProcessClientStartArgs) -> IoResult<Self> {
+        let channel_capacity = args.channel_capacity.max(1);
+        let mut handle =
+            codex_app_server::in_process::start(args.into_runtime_start_args()).await?;
+        let request_sender = handle.sender();
+        let (command_tx, mut command_rx) = mpsc::channel::<ClientCommand>(channel_capacity);
+        // e9996ec62a preserved transcript events by awaiting a bounded queue, but that can
+        // deadlock a foreground request whose response is behind unread notifications.
+        // Match the remote-client fix in 79ea57715636: only this local consumer queue is
+        // unbounded; commands and the embedded runtime stay bounded and events remain ordered.
+        let (event_tx, event_rx) = mpsc::unbounded_channel::<InProcessServerEvent>();
+
+        let worker_handle = tokio::spawn(async move {
+            let mut event_stream_enabled = true;
+            loop {
+                tokio::select! {
+                    command = command_rx.recv() => {
+                        match command {
+                            Some(ClientCommand::Request { request, response_tx }) => {
+                                let request_sender = request_sender.clone();
+                                // Request waits happen on a detached task so
+                                // this loop can keep draining runtime events
+                                // while the request is blocked on client input.
+                                tokio::spawn(async move {
+                                    // Device ceremonies belong to the waiting UI. Preserve
+                                    // its cancellation through this buffering task.
+                                    let cancellable = matches!(*request,
+                                        ClientRequest::UserVerificationStatus { .. }
+                                        | ClientRequest::UserVerificationEnroll { .. }
+                                        | ClientRequest::UserVerificationDelete { .. }
+                                        | ClientRequest::UserVerificationVerify { .. });
+                                    let mut response_tx = response_tx;
+                                    tokio::select! {
+                                        _ = response_tx.closed(), if cancellable => {}
+                                        result = request_sender.request(*request) => {
+                                            let _ = response_tx.send(result);
+                                        }
+                                    }
+                                });
+                            }
+                            Some(ClientCommand::Notify {
+                                notification,
+                                response_tx,
+                            }) => {
+                                let result = request_sender.notify(notification);
+                                let _ = response_tx.send(result);
+                            }
+                            Some(ClientCommand::ResolveServerRequest {
+                                request_id,
+                                result,
+                                response_tx,
+                            }) => {
+                                let send_result =
+                                    request_sender.respond_to_server_request(request_id, result);
+                                let _ = response_tx.send(send_result);
+                            }
+                            Some(ClientCommand::RejectServerRequest {
+                                request_id,
+                                error,
+                                response_tx,
+                            }) => {
+                                let send_result = request_sender.fail_server_request(request_id, error);
+                                let _ = response_tx.send(send_result);
+                            }
+                            Some(ClientCommand::Shutdown { response_tx }) => {
+                                let shutdown_result = handle.shutdown().await;
+                                let _ = response_tx.send(shutdown_result);
+                                break;
+                            }
+                            None => {
+                                let _ = handle.shutdown().await;
+                                break;
+                            }
+                        }
+                    }
+                    event = handle.next_event(), if event_stream_enabled => {
+                        let Some(event) = event else {
+                            break;
+                        };
+                        if let InProcessServerEvent::ServerRequest(request) = &event
+                            && let ServerRequest::ChatgptAuthTokensRefresh { request_id, .. } =
+                                request.as_ref()
+                        {
+                            let send_result = request_sender.fail_server_request(
+                                request_id.clone(),
+                                JSONRPCErrorError {
+                                    code: -32000,
+                                    message: "chatgpt auth token refresh is not supported for in-process app-server clients".to_string(),
+                                    data: None,
+                                },
+                            );
+                            if let Err(err) = send_result {
+                                warn!(
+                                    "failed to reject unsupported chatgpt auth token refresh request: {err}"
+                                );
+                            }
+                            continue;
+                        }
+
+                        if event_tx.send(event).is_err() {
+                            event_stream_enabled = false;
+                        }
+                    }
+                }
+            }
+        });
+
+        Ok(Self {
+            command_tx,
+            event_rx,
+            worker_handle,
+        })
+    }
+
+    pub fn request_handle(&self) -> InProcessAppServerRequestHandle {
+        InProcessAppServerRequestHandle {
+            command_tx: self.command_tx.clone(),
+        }
+    }
+
+    /// Sends a typed client request and returns raw JSON-RPC result.
+    ///
+    /// Callers that expect a concrete response type should usually prefer
+    /// [`request_typed`](Self::request_typed).
+    pub async fn request(&self, request: ClientRequest) -> IoResult<RequestResult> {
+        let (response_tx, response_rx) = oneshot::channel();
+        self.command_tx
+            .send(ClientCommand::Request {
+                request: Box::new(request),
+                response_tx,
+            })
+            .await
+            .map_err(|_| {
+                IoError::new(
+                    ErrorKind::BrokenPipe,
+                    "in-process app-server worker channel is closed",
+                )
+            })?;
+        response_rx.await.map_err(|_| {
+            IoError::new(
+                ErrorKind::BrokenPipe,
+                "in-process app-server request channel is closed",
+            )
+        })?
+    }
+
+    /// Sends a typed client request and decodes the successful response body.
+    ///
+    /// This still deserializes from a JSON value produced by app-server's
+    /// JSON-RPC result envelope. Because the caller chooses `T`, `Deserialize`
+    /// failures indicate an internal request/response mismatch at the call site
+    /// (or an in-process bug), not transport skew from an external client.
+    pub async fn request_typed<T>(&self, request: ClientRequest) -> Result<T, TypedRequestError>
+    where
+        T: DeserializeOwned,
+    {
+        let method = request.method_name();
+        let response =
+            self.request(request)
+                .await
+                .map_err(|source| TypedRequestError::Transport {
+                    method: method.to_string(),
+                    source,
+                })?;
+        let result = response.map_err(|source| TypedRequestError::Server {
+            method: method.to_string(),
+            source,
+        })?;
+        serde_json::from_value(result).map_err(|source| TypedRequestError::Deserialize {
+            method: method.to_string(),
+            source,
+        })
+    }
+
+    /// Sends a typed client notification.
+    pub async fn notify(&self, notification: ClientNotification) -> IoResult<()> {
+        let (response_tx, response_rx) = oneshot::channel();
+        self.command_tx
+            .send(ClientCommand::Notify {
+                notification,
+                response_tx,
+            })
+            .await
+            .map_err(|_| {
+                IoError::new(
+                    ErrorKind::BrokenPipe,
+                    "in-process app-server worker channel is closed",
+                )
+            })?;
+        response_rx.await.map_err(|_| {
+            IoError::new(
+                ErrorKind::BrokenPipe,
+                "in-process app-server notify channel is closed",
+            )
+        })?
+    }
+
+    /// Resolves a pending server request.
+    ///
+    /// This should only be called with request IDs obtained from the current
+    /// client's event stream.
+    pub async fn resolve_server_request(
+        &self,
+        request_id: RequestId,
+        result: JsonRpcResult,
+    ) -> IoResult<()> {
+        let (response_tx, response_rx) = oneshot::channel();
+        self.command_tx
+            .send(ClientCommand::ResolveServerRequest {
+                request_id,
+                result,
+                response_tx,
+            })
+            .await
+            .map_err(|_| {
+                IoError::new(
+                    ErrorKind::BrokenPipe,
+                    "in-process app-server worker channel is closed",
+                )
+            })?;
+        response_rx.await.map_err(|_| {
+            IoError::new(
+                ErrorKind::BrokenPipe,
+                "in-process app-server resolve channel is closed",
+            )
+        })?
+    }
+
+    /// Rejects a pending server request with JSON-RPC error payload.
+    pub async fn reject_server_request(
+        &self,
+        request_id: RequestId,
+        error: JSONRPCErrorError,
+    ) -> IoResult<()> {
+        let (response_tx, response_rx) = oneshot::channel();
+        self.command_tx
+            .send(ClientCommand::RejectServerRequest {
+                request_id,
+                error,
+                response_tx,
+            })
+            .await
+            .map_err(|_| {
+                IoError::new(
+                    ErrorKind::BrokenPipe,
+                    "in-process app-server worker channel is closed",
+                )
+            })?;
+        response_rx.await.map_err(|_| {
+            IoError::new(
+                ErrorKind::BrokenPipe,
+                "in-process app-server reject channel is closed",
+            )
+        })?
+    }
+
+    /// Returns the next in-process event, or `None` when worker exits.
+    ///
+    /// Events remain ordered and are retained while callers await requests.
+    pub async fn next_event(&mut self) -> Option<InProcessServerEvent> {
+        self.event_rx.recv().await
+    }
+
+    /// Shuts down worker and in-process runtime with bounded wait.
+    ///
+    /// If graceful shutdown exceeds timeout, the worker task is aborted to
+    /// avoid leaking background tasks in embedding callers.
+    pub async fn shutdown(self) -> IoResult<()> {
+        let Self {
+            command_tx,
+            event_rx,
+            worker_handle,
+        } = self;
+        let mut worker_handle = worker_handle;
+        // Stop forwarding caller-facing events before asking the worker to shut down.
+        drop(event_rx);
+        let (response_tx, response_rx) = oneshot::channel();
+        if command_tx
+            .send(ClientCommand::Shutdown { response_tx })
+            .await
+            .is_ok()
+            && let Ok(command_result) = timeout(IN_PROCESS_SHUTDOWN_TIMEOUT, response_rx).await
+        {
+            command_result.map_err(|_| {
+                IoError::new(
+                    ErrorKind::BrokenPipe,
+                    "in-process app-server shutdown channel is closed",
+                )
+            })??;
+        }
+
+        if let Err(_elapsed) = timeout(IN_PROCESS_SHUTDOWN_TIMEOUT, &mut worker_handle).await {
+            worker_handle.abort();
+            let _ = worker_handle.await;
+        }
+        Ok(())
+    }
+}
+
+impl InProcessAppServerRequestHandle {
+    pub async fn request(&self, request: ClientRequest) -> IoResult<RequestResult> {
+        let (response_tx, response_rx) = oneshot::channel();
+        self.command_tx
+            .send(ClientCommand::Request {
+                request: Box::new(request),
+                response_tx,
+            })
+            .await
+            .map_err(|_| {
+                IoError::new(
+                    ErrorKind::BrokenPipe,
+                    "in-process app-server worker channel is closed",
+                )
+            })?;
+        response_rx.await.map_err(|_| {
+            IoError::new(
+                ErrorKind::BrokenPipe,
+                "in-process app-server request channel is closed",
+            )
+        })?
+    }
+
+    pub async fn request_typed<T>(&self, request: ClientRequest) -> Result<T, TypedRequestError>
+    where
+        T: DeserializeOwned,
+    {
+        let method = request.method_name();
+        let response =
+            self.request(request)
+                .await
+                .map_err(|source| TypedRequestError::Transport {
+                    method: method.to_string(),
+                    source,
+                })?;
+        let result = response.map_err(|source| TypedRequestError::Server {
+            method: method.to_string(),
+            source,
+        })?;
+        serde_json::from_value(result).map_err(|source| TypedRequestError::Deserialize {
+            method: method.to_string(),
+            source,
+        })
+    }
+}
+
+impl AppServerRequestHandle {
+    pub async fn request(&self, request: ClientRequest) -> IoResult<RequestResult> {
+        match self {
+            Self::InProcess(handle) => handle.request(request).await,
+            Self::Remote(handle) => handle.request(request).await,
+        }
+    }
+
+    pub async fn request_typed<T>(&self, request: ClientRequest) -> Result<T, TypedRequestError>
+    where
+        T: DeserializeOwned,
+    {
+        match self {
+            Self::InProcess(handle) => handle.request_typed(request).await,
+            Self::Remote(handle) => handle.request_typed(request).await,
+        }
+    }
+}
+
+impl AppServerClient {
+    /// App-server platform family, which can differ from the executor's platform.
+    /// Older remote servers may omit this metadata.
+    pub fn platform_family(&self) -> Option<&str> {
+        match self {
+            Self::InProcess(_) => Some(std::env::consts::FAMILY),
+            Self::Remote(client) => client.platform_family(),
+        }
+    }
+
+    /// App-server operating system as reported at initialization, including unknown values.
+    pub fn platform_os(&self) -> Option<&str> {
+        match self {
+            Self::InProcess(_) => Some(std::env::consts::OS),
+            Self::Remote(client) => client.platform_os(),
+        }
+    }
+
+    pub fn codex_home(&self, local_codex_home: &AbsolutePathBuf) -> Option<AppServerPath> {
+        match self {
+            Self::InProcess(_) => Some(AppServerPath::from_app_server(
+                local_codex_home.display().to_string(),
+            )),
+            Self::Remote(client) => client.codex_home().map(AppServerPath::from_app_server),
+        }
+    }
+
+    pub async fn request(&self, request: ClientRequest) -> IoResult<RequestResult> {
+        match self {
+            Self::InProcess(client) => client.request(request).await,
+            Self::Remote(client) => client.request(request).await,
+        }
+    }
+
+    pub async fn request_typed<T>(&self, request: ClientRequest) -> Result<T, TypedRequestError>
+    where
+        T: DeserializeOwned,
+    {
+        match self {
+            Self::InProcess(client) => client.request_typed(request).await,
+            Self::Remote(client) => client.request_typed(request).await,
+        }
+    }
+
+    pub async fn notify(&self, notification: ClientNotification) -> IoResult<()> {
+        match self {
+            Self::InProcess(client) => client.notify(notification).await,
+            Self::Remote(client) => client.notify(notification).await,
+        }
+    }
+
+    pub async fn resolve_server_request(
+        &self,
+        request_id: RequestId,
+        result: JsonRpcResult,
+    ) -> IoResult<()> {
+        match self {
+            Self::InProcess(client) => client.resolve_server_request(request_id, result).await,
+            Self::Remote(client) => client.resolve_server_request(request_id, result).await,
+        }
+    }
+
+    pub async fn reject_server_request(
+        &self,
+        request_id: RequestId,
+        error: JSONRPCErrorError,
+    ) -> IoResult<()> {
+        match self {
+            Self::InProcess(client) => client.reject_server_request(request_id, error).await,
+            Self::Remote(client) => client.reject_server_request(request_id, error).await,
+        }
+    }
+
+    pub async fn next_event(&mut self) -> Option<AppServerEvent> {
+        match self {
+            Self::InProcess(client) => client.next_event().await.map(Into::into),
+            Self::Remote(client) => client.next_event().await,
+        }
+    }
+
+    pub async fn shutdown(self) -> IoResult<()> {
+        match self {
+            Self::InProcess(client) => client.shutdown().await,
+            Self::Remote(client) => client.shutdown().await,
+        }
+    }
+
+    pub fn request_handle(&self) -> AppServerRequestHandle {
+        match self {
+            Self::InProcess(client) => AppServerRequestHandle::InProcess(client.request_handle()),
+            Self::Remote(client) => AppServerRequestHandle::Remote(client.request_handle()),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use codex_app_server_protocol::AccountUpdatedNotification;
+    use codex_app_server_protocol::ConfigRequirementsReadResponse;
+    use codex_app_server_protocol::GetAccountResponse;
+    use codex_app_server_protocol::JSONRPCMessage;
+    use codex_app_server_protocol::JSONRPCRequest;
+    use codex_app_server_protocol::JSONRPCResponse;
+    use codex_app_server_protocol::ServerNotification;
+    use codex_app_server_protocol::SessionSource as ApiSessionSource;
+    use codex_app_server_protocol::ThreadSettingsUpdateParams;
+    use codex_app_server_protocol::ThreadSettingsUpdateResponse;
+    use codex_app_server_protocol::ThreadStartParams;
+    use codex_app_server_protocol::ThreadStartResponse;
+    use codex_app_server_protocol::ToolRequestUserInputParams;
+    use codex_app_server_protocol::ToolRequestUserInputQuestion;
+    use codex_core::config::ConfigBuilder;
+    use codex_core::init_state_db;
+    use codex_protocol::config_types::Personality;
+    use codex_uds::UnixListener;
+    use codex_utils_absolute_path::AbsolutePathBuf;
+    use futures::SinkExt;
+    use futures::StreamExt;
+    use pretty_assertions::assert_eq;
+    use std::ops::Deref;
+    use std::path::Path;
+    use tempfile::TempDir;
+    use tokio::net::TcpListener;
+    use tokio::time::Duration;
+    use tokio::time::timeout;
+    use tokio_tungstenite::accept_async;
+    use tokio_tungstenite::accept_hdr_async;
+    use tokio_tungstenite::tungstenite::Message;
+    use tokio_tungstenite::tungstenite::handshake::server::Request as WebSocketRequest;
+    use tokio_tungstenite::tungstenite::handshake::server::Response as WebSocketResponse;
+    use tokio_tungstenite::tungstenite::http::header::AUTHORIZATION;
+
+    async fn build_test_config() -> Config {
+        match ConfigBuilder::default().build().await {
+            Ok(config) => config,
+            Err(_) => Config::load_default_with_cli_overrides(Vec::new())
+                .await
+                .expect("default config should load"),
+        }
+    }
+
+    async fn build_test_config_for_codex_home(codex_home: &Path) -> Config {
+        match ConfigBuilder::default()
+            .codex_home(codex_home.to_path_buf())
+            .build()
+            .await
+        {
+            Ok(config) => config,
+            Err(_) => Config::load_default_with_cli_overrides_for_codex_home(
+                codex_home.to_path_buf(),
+                Vec::new(),
+            )
+            .await
+            .expect("default config should load"),
+        }
+    }
+
+    struct TestClient {
+        _codex_home: TempDir,
+        client: InProcessAppServerClient,
+    }
+
+    impl Deref for TestClient {
+        type Target = InProcessAppServerClient;
+
+        fn deref(&self) -> &Self::Target {
+            &self.client
+        }
+    }
+
+    impl TestClient {
+        async fn shutdown(self) -> IoResult<()> {
+            self.client.shutdown().await
+        }
+    }
+
+    async fn start_test_client_with_capacity(
+        session_source: SessionSource,
+        channel_capacity: usize,
+    ) -> TestClient {
+        let codex_home = TempDir::new().expect("temp dir");
+        let config = Arc::new(build_test_config_for_codex_home(codex_home.path()).await);
+        let state_db = init_state_db(config.as_ref())
+            .await
+            .expect("state db should initialize for in-process test");
+        let client = InProcessAppServerClient::start(InProcessClientStartArgs {
+            arg0_paths: Arg0DispatchPaths::default(),
+            config,
+            cli_overrides: Vec::new(),
+            loader_overrides: LoaderOverrides::default(),
+            strict_config: false,
+            cloud_config_bundle: CloudConfigBundleLoader::default(),
+            feedback: CodexFeedback::new(),
+            log_db: None,
+            state_db: Some(state_db),
+            environment_manager: Arc::new(EnvironmentManager::default_for_tests()),
+            config_warnings: Vec::new(),
+            session_source,
+            enable_codex_api_key_env: false,
+            client_name: "codex-app-server-client-test".to_string(),
+            client_version: "0.0.0-test".to_string(),
+            experimental_api: true,
+            mcp_server_openai_form_elicitation: false,
+            opt_out_notification_methods: Vec::new(),
+            channel_capacity,
+        })
+        .await
+        .expect("in-process app-server client should start");
+
+        TestClient {
+            _codex_home: codex_home,
+            client,
+        }
+    }
+
+    async fn start_test_client(session_source: SessionSource) -> TestClient {
+        start_test_client_with_capacity(session_source, DEFAULT_IN_PROCESS_CHANNEL_CAPACITY).await
+    }
+
+    async fn start_test_remote_server<F, Fut>(handler: F) -> String
+    where
+        F: FnOnce(tokio_tungstenite::WebSocketStream<tokio::net::TcpStream>) -> Fut
+            + Send
+            + 'static,
+        Fut: std::future::Future<Output = ()> + Send + 'static,
+    {
+        start_test_remote_server_with_auth(/*expected_auth_token*/ None, handler).await
+    }
+
+    async fn start_test_remote_server_with_auth<F, Fut>(
+        expected_auth_token: Option<String>,
+        handler: F,
+    ) -> String
+    where
+        F: FnOnce(tokio_tungstenite::WebSocketStream<tokio::net::TcpStream>) -> Fut
+            + Send
+            + 'static,
+        Fut: std::future::Future<Output = ()> + Send + 'static,
+    {
+        let listener = TcpListener::bind("127.0.0.1:0")
+            .await
+            .expect("listener should bind");
+        let addr = listener.local_addr().expect("listener address");
+        tokio::spawn(async move {
+            let (stream, _) = listener.accept().await.expect("accept should succeed");
+            let websocket = accept_hdr_async(
+                stream,
+                move |request: &WebSocketRequest, response: WebSocketResponse| {
+                    let provided_auth_token = request
+                        .headers()
+                        .get(AUTHORIZATION)
+                        .and_then(|value| value.to_str().ok())
+                        .map(str::to_owned);
+                    let expected_auth_token = expected_auth_token
+                        .as_ref()
+                        .map(|token| format!("Bearer {token}"));
+                    assert_eq!(provided_auth_token, expected_auth_token);
+                    Ok(response)
+                },
+            )
+            .await
+            .expect("websocket upgrade should succeed");
+            handler(websocket).await;
+        });
+        format!("ws://{addr}")
+    }
+
+    async fn expect_remote_initialize<S>(websocket: &mut tokio_tungstenite::WebSocketStream<S>)
+    where
+        S: tokio::io::AsyncRead + tokio::io::AsyncWrite + Unpin,
+    {
+        expect_remote_initialize_with_metadata(
+            websocket,
+            serde_json::json!({
+                "userAgent": "codex_cli_rs/9.8.7-test (Test OS; x86_64) rust",
+                "codexHome": "/server/.codex",
+            }),
+        )
+        .await;
+    }
+
+    async fn expect_remote_initialize_with_metadata<S>(
+        websocket: &mut tokio_tungstenite::WebSocketStream<S>,
+        metadata: serde_json::Value,
+    ) where
+        S: tokio::io::AsyncRead + tokio::io::AsyncWrite + Unpin,
+    {
+        let JSONRPCMessage::Request(request) = read_websocket_message(websocket).await else {
+            panic!("expected initialize request");
+        };
+        assert_eq!(request.method, "initialize");
+        write_websocket_message(
+            websocket,
+            JSONRPCMessage::Response(JSONRPCResponse {
+                id: request.id,
+                result: metadata,
+            }),
+        )
+        .await;
+
+        let JSONRPCMessage::Notification(notification) = read_websocket_message(websocket).await
+        else {
+            panic!("expected initialized notification");
+        };
+        assert_eq!(notification.method, "initialized");
+    }
+
+    async fn read_websocket_message<S>(
+        websocket: &mut tokio_tungstenite::WebSocketStream<S>,
+    ) -> JSONRPCMessage
+    where
+        S: tokio::io::AsyncRead + tokio::io::AsyncWrite + Unpin,
+    {
+        loop {
+            let frame = websocket
+                .next()
+                .await
+                .expect("frame should be available")
+                .expect("frame should decode");
+            match frame {
+                Message::Text(text) => {
+                    return serde_json::from_str::<JSONRPCMessage>(&text)
+                        .expect("text frame should be valid JSON-RPC");
+                }
+                Message::Binary(_) | Message::Ping(_) | Message::Pong(_) | Message::Frame(_) => {
+                    continue;
+                }
+                Message::Close(_) => panic!("unexpected close frame"),
+            }
+        }
+    }
+
+    async fn write_websocket_message<S>(
+        websocket: &mut tokio_tungstenite::WebSocketStream<S>,
+        message: JSONRPCMessage,
+    ) where
+        S: tokio::io::AsyncRead + tokio::io::AsyncWrite + Unpin,
+    {
+        websocket
+            .send(Message::Text(
+                serde_json::to_string(&message)
+                    .expect("message should serialize")
+                    .into(),
+            ))
+            .await
+            .expect("message should send");
+    }
+
+    fn command_execution_output_delta_notification(delta: &str) -> ServerNotification {
+        ServerNotification::CommandExecutionOutputDelta(
+            codex_app_server_protocol::CommandExecutionOutputDeltaNotification {
+                thread_id: "thread".to_string(),
+                turn_id: "turn".to_string(),
+                item_id: "item".to_string(),
+                delta: delta.to_string(),
+            },
+        )
+    }
+
+    fn agent_message_delta_notification(delta: &str) -> ServerNotification {
+        ServerNotification::AgentMessageDelta(
+            codex_app_server_protocol::AgentMessageDeltaNotification {
+                thread_id: "thread".to_string(),
+                turn_id: "turn".to_string(),
+                item_id: "item".to_string(),
+                delta: delta.to_string(),
+            },
+        )
+    }
+
+    fn item_completed_notification(text: &str) -> ServerNotification {
+        ServerNotification::ItemCompleted(codex_app_server_protocol::ItemCompletedNotification {
+            thread_id: "thread".to_string(),
+            turn_id: "turn".to_string(),
+            completed_at_ms: 0,
+            item: codex_app_server_protocol::ThreadItem::AgentMessage {
+                id: "item".to_string(),
+                text: text.to_string(),
+                phase: None,
+                memory_citation: None,
+                delivery: None,
+                questions: None,
+            },
+        })
+    }
+
+    fn turn_completed_notification() -> ServerNotification {
+        ServerNotification::TurnCompleted(codex_app_server_protocol::TurnCompletedNotification {
+            thread_id: "thread".to_string(),
+            turn: codex_app_server_protocol::Turn {
+                id: "turn".to_string(),
+                items_view: codex_app_server_protocol::TurnItemsView::Full,
+                items: Vec::new(),
+                status: codex_app_server_protocol::TurnStatus::Completed,
+                error: None,
+                started_at: None,
+                completed_at: Some(0),
+                duration_ms: Some(1),
+            },
+        })
+    }
+
+    fn test_remote_connect_args(websocket_url: String) -> RemoteAppServerConnectArgs {
+        RemoteAppServerConnectArgs {
+            endpoint: RemoteAppServerEndpoint::WebSocket {
+                websocket_url,
+                auth_token: None,
+            },
+            client_name: "codex-app-server-client-test".to_string(),
+            client_version: "0.0.0-test".to_string(),
+            experimental_api: true,
+            mcp_server_openai_form_elicitation: false,
+            opt_out_notification_methods: Vec::new(),
+            channel_capacity: 8,
+        }
+    }
+
+    #[test]
+    fn remote_initialize_params_forward_openai_form_capability() {
+        let mut args = test_remote_connect_args("ws://localhost/rpc".to_string());
+        args.mcp_server_openai_form_elicitation = true;
+
+        assert!(
+            args.initialize_params()
+                .capabilities
+                .expect("initialize capabilities")
+                .mcp_server_openai_form_elicitation
+        );
+    }
+
+    #[tokio::test]
+    async fn typed_request_roundtrip_works() {
+        let TestClient {
+            _codex_home,
+            client,
+        } = start_test_client(SessionSource::Exec).await;
+        let client = AppServerClient::InProcess(client);
+        assert_eq!(
+            (client.platform_family(), client.platform_os()),
+            (Some(std::env::consts::FAMILY), Some(std::env::consts::OS))
+        );
+        let _response: ConfigRequirementsReadResponse = client
+            .request_typed(ClientRequest::ConfigRequirementsRead {
+                request_id: RequestId::Integer(1),
+                params: None,
+            })
+            .await
+            .expect("typed request should succeed");
+        client.shutdown().await.expect("shutdown should complete");
+    }
+
+    #[tokio::test]
+    async fn typed_request_reports_json_rpc_errors() {
+        let client = start_test_client(SessionSource::Exec).await;
+        let err = client
+            .request_typed::<ConfigRequirementsReadResponse>(ClientRequest::ThreadRead {
+                request_id: RequestId::Integer(99),
+                params: codex_app_server_protocol::ThreadReadParams {
+                    thread_id: "missing-thread".to_string(),
+                    include_turns: false,
+                },
+            })
+            .await
+            .expect_err("missing thread should return a JSON-RPC error");
+        assert!(
+            err.to_string().starts_with("thread/read failed:"),
+            "expected method-qualified JSON-RPC failure message"
+        );
+        client.shutdown().await.expect("shutdown should complete");
+    }
+
+    #[tokio::test]
+    async fn caller_provided_session_source_is_applied() {
+        for (session_source, expected_source) in [
+            (SessionSource::Exec, ApiSessionSource::Exec),
+            (SessionSource::Cli, ApiSessionSource::Cli),
+        ] {
+            let client = start_test_client(session_source).await;
+            let parsed: ThreadStartResponse = client
+                .request_typed(ClientRequest::ThreadStart {
+                    request_id: RequestId::Integer(2),
+                    params: ThreadStartParams {
+                        ephemeral: Some(true),
+                        ..ThreadStartParams::default()
+                    },
+                })
+                .await
+                .expect("thread/start should succeed");
+            assert_eq!(parsed.thread.source, expected_source);
+            client.shutdown().await.expect("shutdown should complete");
+        }
+    }
+
+    #[tokio::test]
+    async fn threads_started_via_app_server_are_visible_through_typed_requests() {
+        let client = start_test_client(SessionSource::Cli).await;
+
+        let response: ThreadStartResponse = client
+            .request_typed(ClientRequest::ThreadStart {
+                request_id: RequestId::Integer(3),
+                params: ThreadStartParams {
+                    ephemeral: Some(true),
+                    ..ThreadStartParams::default()
+                },
+            })
+            .await
+            .expect("thread/start should succeed");
+        let read = client
+            .request_typed::<codex_app_server_protocol::ThreadReadResponse>(
+                ClientRequest::ThreadRead {
+                    request_id: RequestId::Integer(4),
+                    params: codex_app_server_protocol::ThreadReadParams {
+                        thread_id: response.thread.id.clone(),
+                        include_turns: false,
+                    },
+                },
+            )
+            .await
+            .expect("thread/read should return the newly started thread");
+        assert_eq!(read.thread.id, response.thread.id);
+
+        client.shutdown().await.expect("shutdown should complete");
+    }
+
+    #[tokio::test]
+    async fn tiny_channel_capacity_still_supports_request_roundtrip() {
+        let client =
+            start_test_client_with_capacity(SessionSource::Exec, /*channel_capacity*/ 1).await;
+        let _response: ConfigRequirementsReadResponse = client
+            .request_typed(ClientRequest::ConfigRequirementsRead {
+                request_id: RequestId::Integer(1),
+                params: None,
+            })
+            .await
+            .expect("typed request should succeed");
+        client.shutdown().await.expect("shutdown should complete");
+    }
+
+    #[tokio::test]
+    async fn unread_lossless_notifications_do_not_block_in_process_requests() {
+        let mut client =
+            start_test_client_with_capacity(SessionSource::Cli, /*channel_capacity*/ 1).await;
+        let thread: ThreadStartResponse = client
+            .request_typed(ClientRequest::ThreadStart {
+                request_id: RequestId::Integer(1),
+                params: ThreadStartParams {
+                    ephemeral: Some(true),
+                    personality: Some(Personality::None),
+                    ..ThreadStartParams::default()
+                },
+            })
+            .await
+            .expect("thread/start should succeed");
+        let request_handle = client.request_handle();
+
+        timeout(Duration::from_secs(2), async {
+            for (index, personality) in [
+                Personality::Friendly,
+                Personality::Pragmatic,
+                Personality::Friendly,
+                Personality::Pragmatic,
+            ]
+            .into_iter()
+            .enumerate()
+            {
+                let _: ThreadSettingsUpdateResponse = request_handle
+                    .request_typed(ClientRequest::ThreadSettingsUpdate {
+                        request_id: RequestId::Integer((index + 2) as i64),
+                        params: ThreadSettingsUpdateParams {
+                            thread_id: thread.thread.id.clone(),
+                            personality: Some(personality),
+                            ..ThreadSettingsUpdateParams::default()
+                        },
+                    })
+                    .await
+                    .expect("thread/settings/update should succeed");
+            }
+
+            let _: ConfigRequirementsReadResponse = request_handle
+                .request_typed(ClientRequest::ConfigRequirementsRead {
+                    request_id: RequestId::Integer(10),
+                    params: None,
+                })
+                .await
+                .expect("configuration request should succeed");
+        })
+        .await
+        .expect("unread lossless notifications must not block app-server requests");
+
+        let mut personalities = Vec::new();
+        timeout(Duration::from_secs(2), async {
+            while personalities.len() < 4 {
+                if let Some(InProcessServerEvent::ServerNotification(notification)) =
+                    client.client.next_event().await
+                    && let ServerNotification::ThreadSettingsUpdated(notification) =
+                        notification.as_ref()
+                {
+                    personalities.push(notification.thread_settings.personality);
+                }
+            }
+        })
+        .await
+        .expect("queued settings notifications should remain readable");
+        assert_eq!(
+            personalities,
+            vec![
+                Some(Personality::Friendly),
+                Some(Personality::Pragmatic),
+                Some(Personality::Friendly),
+                Some(Personality::Pragmatic),
+            ]
+        );
+
+        client.shutdown().await.expect("shutdown should complete");
+    }
+
+    #[tokio::test]
+    async fn remote_platform_metadata_preserves_reported_and_missing_values() {
+        for (family, os) in [
+            (Some("windows"), Some("windows")),
+            (Some("unix"), Some("linux")),
+            (Some("future-family"), Some("future-os")),
+            (Some("unix"), None),
+            (None, Some("linux")),
+            (None, None),
+        ] {
+            let websocket_url = start_test_remote_server(move |mut websocket| async move {
+                let mut metadata = serde_json::json!({});
+                if let Some(family) = family {
+                    metadata["platformFamily"] = family.into();
+                }
+                if let Some(os) = os {
+                    metadata["platformOs"] = os.into();
+                }
+                expect_remote_initialize_with_metadata(&mut websocket, metadata).await;
+                websocket.close(None).await.expect("close should succeed");
+            })
+            .await;
+            let client = AppServerClient::Remote(
+                RemoteAppServerClient::connect(test_remote_connect_args(websocket_url))
+                    .await
+                    .expect("remote client should connect"),
+            );
+            assert_eq!(
+                (client.platform_family(), client.platform_os()),
+                (family, os)
+            );
+            client.shutdown().await.expect("shutdown should complete");
+        }
+    }
+
+    #[tokio::test]
+    async fn remote_typed_request_roundtrip_works() {
+        let websocket_url = start_test_remote_server(|mut websocket| async move {
+            expect_remote_initialize(&mut websocket).await;
+            let JSONRPCMessage::Request(request) = read_websocket_message(&mut websocket).await
+            else {
+                panic!("expected account/read request");
+            };
+            assert_eq!(request.method, "account/read");
+            write_websocket_message(
+                &mut websocket,
+                JSONRPCMessage::Response(JSONRPCResponse {
+                    id: request.id,
+                    result: serde_json::to_value(GetAccountResponse {
+                        workspace_routing: None,
+                        account: None,
+                        requires_openai_auth: false,
+                    })
+                    .expect("response should serialize"),
+                }),
+            )
+            .await;
+            websocket.close(None).await.expect("close should succeed");
+        })
+        .await;
+        let client = RemoteAppServerClient::connect(test_remote_connect_args(websocket_url))
+            .await
+            .expect("remote client should connect");
+
+        assert_eq!(client.server_version(), Some("9.8.7-test"));
+        assert_eq!(client.codex_home(), Some("/server/.codex"));
+        let response: GetAccountResponse = client
+            .request_typed(ClientRequest::GetAccount {
+                request_id: RequestId::Integer(1),
+                params: codex_app_server_protocol::GetAccountParams {
+                    refresh_token: false,
+                },
+            })
+            .await
+            .expect("typed request should succeed");
+        assert_eq!(response.account, None);
+
+        client.shutdown().await.expect("shutdown should complete");
+    }
+
+    #[tokio::test]
+    async fn remote_unix_socket_typed_request_roundtrip_works() {
+        let socket_dir = TempDir::new().expect("socket dir");
+        let socket_path = AbsolutePathBuf::from_absolute_path(socket_dir.path().join("codex.sock"))
+            .expect("socket path should resolve");
+        let mut listener = UnixListener::bind(socket_path.as_path())
+            .await
+            .expect("listener should bind");
+        tokio::spawn(async move {
+            let stream = listener.accept().await.expect("accept should succeed");
+            let mut websocket = accept_async(stream)
+                .await
+                .expect("websocket upgrade should succeed");
+            expect_remote_initialize(&mut websocket).await;
+            let JSONRPCMessage::Request(request) = read_websocket_message(&mut websocket).await
+            else {
+                panic!("expected account/read request");
+            };
+            assert_eq!(request.method, "account/read");
+            write_websocket_message(
+                &mut websocket,
+                JSONRPCMessage::Response(JSONRPCResponse {
+                    id: request.id,
+                    result: serde_json::to_value(GetAccountResponse {
+                        workspace_routing: None,
+                        account: None,
+                        requires_openai_auth: false,
+                    })
+                    .expect("response should serialize"),
+                }),
+            )
+            .await;
+            websocket.close(None).await.expect("close should succeed");
+        });
+        let client = RemoteAppServerClient::connect(RemoteAppServerConnectArgs {
+            endpoint: RemoteAppServerEndpoint::UnixSocket { socket_path },
+            client_name: "codex-app-server-client-test".to_string(),
+            client_version: "0.0.0-test".to_string(),
+            experimental_api: true,
+            mcp_server_openai_form_elicitation: false,
+            opt_out_notification_methods: Vec::new(),
+            channel_capacity: 8,
+        })
+        .await
+        .expect("remote client should connect");
+
+        let response: GetAccountResponse = client
+            .request_typed(ClientRequest::GetAccount {
+                request_id: RequestId::Integer(1),
+                params: codex_app_server_protocol::GetAccountParams {
+                    refresh_token: false,
+                },
+            })
+            .await
+            .expect("typed request should succeed");
+        assert_eq!(response.account, None);
+
+        client.shutdown().await.expect("shutdown should complete");
+    }
+
+    #[tokio::test]
+    async fn remote_typed_request_accepts_large_single_frame_response() {
+        let padding = "x".repeat((17 << 20) + 1024);
+        let websocket_url = start_test_remote_server(move |mut websocket| async move {
+            expect_remote_initialize(&mut websocket).await;
+            let JSONRPCMessage::Request(request) = read_websocket_message(&mut websocket).await
+            else {
+                panic!("expected account/read request");
+            };
+            assert_eq!(request.method, "account/read");
+            write_websocket_message(
+                &mut websocket,
+                JSONRPCMessage::Response(JSONRPCResponse {
+                    id: request.id,
+                    result: serde_json::json!({
+                        "account": null,
+                        "requiresOpenaiAuth": false,
+                        "padding": padding,
+                    }),
+                }),
+            )
+            .await;
+            websocket.close(None).await.expect("close should succeed");
+        })
+        .await;
+        let client = RemoteAppServerClient::connect(test_remote_connect_args(websocket_url))
+            .await
+            .expect("remote client should connect");
+
+        let response: GetAccountResponse = client
+            .request_typed(ClientRequest::GetAccount {
+                request_id: RequestId::Integer(1),
+                params: codex_app_server_protocol::GetAccountParams {
+                    refresh_token: false,
+                },
+            })
+            .await
+            .expect("large typed request should succeed");
+        assert_eq!(
+            response,
+            GetAccountResponse {
+                workspace_routing: None,
+                account: None,
+                requires_openai_auth: false,
+            }
+        );
+
+        client.shutdown().await.expect("shutdown should complete");
+    }
+
+    #[tokio::test]
+    async fn remote_connect_includes_auth_header_when_configured() {
+        let auth_token = "remote-bearer-token".to_string();
+        let websocket_url = start_test_remote_server_with_auth(
+            Some(auth_token.clone()),
+            |mut websocket| async move {
+                expect_remote_initialize(&mut websocket).await;
+                websocket.close(None).await.expect("close should succeed");
+            },
+        )
+        .await;
+        let client = RemoteAppServerClient::connect(RemoteAppServerConnectArgs {
+            endpoint: RemoteAppServerEndpoint::WebSocket {
+                websocket_url,
+                auth_token: Some(auth_token),
+            },
+            client_name: "codex-app-server-client-test".to_string(),
+            client_version: "0.0.0-test".to_string(),
+            experimental_api: true,
+            mcp_server_openai_form_elicitation: false,
+            opt_out_notification_methods: Vec::new(),
+            channel_capacity: 8,
+        })
+        .await
+        .expect("remote client should connect");
+
+        client.shutdown().await.expect("shutdown should complete");
+    }
+
+    #[tokio::test]
+    async fn remote_connect_rejects_non_loopback_ws_when_auth_configured() {
+        let result = RemoteAppServerClient::connect(RemoteAppServerConnectArgs {
+            endpoint: RemoteAppServerEndpoint::WebSocket {
+                websocket_url: "ws://example.com:4500".to_string(),
+                auth_token: Some("remote-bearer-token".to_string()),
+            },
+            client_name: "codex-app-server-client-test".to_string(),
+            client_version: "0.0.0-test".to_string(),
+            experimental_api: true,
+            mcp_server_openai_form_elicitation: false,
+            opt_out_notification_methods: Vec::new(),
+            channel_capacity: 8,
+        })
+        .await;
+        let err = match result {
+            Ok(_) => panic!("non-loopback ws should be rejected before connect"),
+            Err(err) => err,
+        };
+        assert_eq!(err.kind(), ErrorKind::InvalidInput);
+        assert!(
+            err.to_string()
+                .contains("remote auth tokens require `wss://` or loopback `ws://` URLs")
+        );
+    }
+
+    #[test]
+    fn remote_auth_token_transport_policy_allows_wss_and_loopback_ws() {
+        assert!(crate::remote::websocket_url_supports_auth_token(
+            &url::Url::parse("wss://example.com:443").expect("wss URL should parse")
+        ));
+        assert!(crate::remote::websocket_url_supports_auth_token(
+            &url::Url::parse("ws://127.0.0.1:4500").expect("loopback ws URL should parse")
+        ));
+        assert!(!crate::remote::websocket_url_supports_auth_token(
+            &url::Url::parse("ws://example.com:4500").expect("non-loopback ws URL should parse")
+        ));
+    }
+
+    #[tokio::test]
+    async fn remote_duplicate_request_id_keeps_original_waiter() {
+        let (first_request_seen_tx, first_request_seen_rx) = tokio::sync::oneshot::channel();
+        let websocket_url = start_test_remote_server(|mut websocket| async move {
+            expect_remote_initialize(&mut websocket).await;
+            let JSONRPCMessage::Request(request) = read_websocket_message(&mut websocket).await
+            else {
+                panic!("expected account/read request");
+            };
+            assert_eq!(request.method, "account/read");
+            first_request_seen_tx
+                .send(request.id.clone())
+                .expect("request id should send");
+            assert!(
+                timeout(
+                    Duration::from_millis(100),
+                    read_websocket_message(&mut websocket)
+                )
+                .await
+                .is_err(),
+                "duplicate request should not be forwarded to the server"
+            );
+            write_websocket_message(
+                &mut websocket,
+                JSONRPCMessage::Response(JSONRPCResponse {
+                    id: request.id,
+                    result: serde_json::to_value(GetAccountResponse {
+                        workspace_routing: None,
+                        account: None,
+                        requires_openai_auth: false,
+                    })
+                    .expect("response should serialize"),
+                }),
+            )
+            .await;
+            let _ = websocket.next().await;
+        })
+        .await;
+        let client = RemoteAppServerClient::connect(test_remote_connect_args(websocket_url))
+            .await
+            .expect("remote client should connect");
+        let first_request_handle = client.request_handle();
+        let second_request_handle = first_request_handle.clone();
+
+        let first_request = tokio::spawn(async move {
+            first_request_handle
+                .request_typed::<GetAccountResponse>(ClientRequest::GetAccount {
+                    request_id: RequestId::Integer(1),
+                    params: codex_app_server_protocol::GetAccountParams {
+                        refresh_token: false,
+                    },
+                })
+                .await
+        });
+
+        let first_request_id = first_request_seen_rx
+            .await
+            .expect("server should observe the first request");
+        assert_eq!(first_request_id, RequestId::Integer(1));
+
+        let second_err = second_request_handle
+            .request_typed::<GetAccountResponse>(ClientRequest::GetAccount {
+                request_id: RequestId::Integer(1),
+                params: codex_app_server_protocol::GetAccountParams {
+                    refresh_token: false,
+                },
+            })
+            .await
+            .expect_err("duplicate request id should be rejected");
+        assert_eq!(
+            second_err.to_string(),
+            "account/read transport error: duplicate remote app-server request id `1`"
+        );
+
+        let first_response = first_request
+            .await
+            .expect("first request task should join")
+            .expect("first request should succeed");
+        assert_eq!(
+            first_response,
+            GetAccountResponse {
+                workspace_routing: None,
+                account: None,
+                requires_openai_auth: false,
+            }
+        );
+
+        client.shutdown().await.expect("shutdown should complete");
+    }
+
+    #[tokio::test]
+    async fn remote_notifications_arrive_over_websocket() {
+        let websocket_url = start_test_remote_server(|mut websocket| async move {
+            expect_remote_initialize(&mut websocket).await;
+            write_websocket_message(
+                &mut websocket,
+                JSONRPCMessage::Notification(
+                    serde_json::from_value(
+                        serde_json::to_value(ServerNotification::AccountUpdated(
+                            AccountUpdatedNotification {
+                                auth_mode: None,
+                                plan_type: None,
+                            },
+                        ))
+                        .expect("notification should serialize"),
+                    )
+                    .expect("notification should convert to JSON-RPC"),
+                ),
+            )
+            .await;
+        })
+        .await;
+        let mut client = RemoteAppServerClient::connect(test_remote_connect_args(websocket_url))
+            .await
+            .expect("remote client should connect");
+
+        let event = client.next_event().await.expect("event should arrive");
+        assert!(matches!(
+            event,
+            AppServerEvent::ServerNotification(notification)
+                if matches!(notification.as_ref(), ServerNotification::AccountUpdated(_))
+        ));
+
+        client.shutdown().await.expect("shutdown should complete");
+    }
+
+    #[tokio::test]
+    async fn remote_backpressure_preserves_transcript_notifications() {
+        let (done_tx, done_rx) = tokio::sync::oneshot::channel();
+        let websocket_url = start_test_remote_server(|mut websocket| async move {
+            expect_remote_initialize(&mut websocket).await;
+            for notification in [
+                command_execution_output_delta_notification("stdout-1"),
+                command_execution_output_delta_notification("stdout-2"),
+                agent_message_delta_notification("hello"),
+                item_completed_notification("hello"),
+                turn_completed_notification(),
+            ] {
+                write_websocket_message(
+                    &mut websocket,
+                    JSONRPCMessage::Notification(
+                        serde_json::from_value(
+                            serde_json::to_value(notification)
+                                .expect("notification should serialize"),
+                        )
+                        .expect("notification should convert to JSON-RPC"),
+                    ),
+                )
+                .await;
+            }
+            let _ = done_rx.await;
+        })
+        .await;
+        let mut client = RemoteAppServerClient::connect(RemoteAppServerConnectArgs {
+            channel_capacity: 1,
+            ..test_remote_connect_args(websocket_url)
+        })
+        .await
+        .expect("remote client should connect");
+
+        let first_event = timeout(Duration::from_secs(2), client.next_event())
+            .await
+            .expect("first event should arrive before timeout")
+            .expect("event stream should stay open");
+        assert!(matches!(
+            first_event,
+            AppServerEvent::ServerNotification(notification)
+                if matches!(
+                    notification.as_ref(),
+                    ServerNotification::CommandExecutionOutputDelta(notification)
+                        if notification.delta == "stdout-1"
+                )
+        ));
+
+        let mut remaining_events = Vec::new();
+        for _ in 0..4 {
+            remaining_events.push(
+                timeout(Duration::from_secs(2), client.next_event())
+                    .await
+                    .expect("event should arrive before timeout")
+                    .expect("event stream should stay open"),
+            );
+        }
+
+        let mut transcript_event_names = Vec::new();
+        for event in &remaining_events {
+            match event {
+                AppServerEvent::Lagged { skipped: 1 } => {}
+                AppServerEvent::ServerNotification(notification) => match notification.as_ref() {
+                    ServerNotification::CommandExecutionOutputDelta(notification)
+                        if notification.delta == "stdout-2" => {}
+                    ServerNotification::AgentMessageDelta(notification)
+                        if notification.delta == "hello" =>
+                    {
+                        transcript_event_names.push("agent_message_delta");
+                    }
+                    ServerNotification::ItemCompleted(notification)
+                        if matches!(
+                            &notification.item,
+                            codex_app_server_protocol::ThreadItem::AgentMessage { text, .. }
+                                if text == "hello"
+                        ) =>
+                    {
+                        transcript_event_names.push("item_completed");
+                    }
+                    ServerNotification::TurnCompleted(notification)
+                        if notification.turn.status
+                            == codex_app_server_protocol::TurnStatus::Completed =>
+                    {
+                        transcript_event_names.push("turn_completed");
+                    }
+                    _ => panic!("unexpected remaining event: {event:?}"),
+                },
+                _ => panic!("unexpected remaining event: {event:?}"),
+            }
+        }
+        assert_eq!(
+            transcript_event_names,
+            vec!["agent_message_delta", "item_completed", "turn_completed"]
+        );
+
+        done_tx
+            .send(())
+            .expect("server completion signal should send");
+        client.shutdown().await.expect("shutdown should complete");
+    }
+
+    #[tokio::test]
+    async fn remote_server_request_resolution_roundtrip_works() {
+        let websocket_url = start_test_remote_server(|mut websocket| async move {
+            expect_remote_initialize(&mut websocket).await;
+            let request_id = RequestId::String("srv-1".to_string());
+            let server_request = JSONRPCRequest {
+                id: request_id.clone(),
+                method: "item/tool/requestUserInput".to_string(),
+                params: Some(
+                    serde_json::to_value(ToolRequestUserInputParams {
+                        thread_id: "thread-1".to_string(),
+                        turn_id: "turn-1".to_string(),
+                        item_id: "call-1".to_string(),
+                        questions: vec![ToolRequestUserInputQuestion {
+                            id: "question-1".to_string(),
+                            header: "Mode".to_string(),
+                            question: "Pick one".to_string(),
+                            is_other: false,
+                            is_secret: false,
+                            options: Some(vec![]),
+                        }],
+                        is_blocking: true,
+                        auto_resolution_ms: None,
+                    })
+                    .expect("params should serialize"),
+                ),
+                trace: None,
+            };
+            write_websocket_message(&mut websocket, JSONRPCMessage::Request(server_request)).await;
+
+            let JSONRPCMessage::Response(response) = read_websocket_message(&mut websocket).await
+            else {
+                panic!("expected server request response");
+            };
+            assert_eq!(response.id, request_id);
+        })
+        .await;
+        let mut client = RemoteAppServerClient::connect(test_remote_connect_args(websocket_url))
+            .await
+            .expect("remote client should connect");
+
+        let AppServerEvent::ServerRequest(request) = client
+            .next_event()
+            .await
+            .expect("request event should arrive")
+        else {
+            panic!("expected server request event");
+        };
+        client
+            .resolve_server_request(request.id().clone(), serde_json::json!({}))
+            .await
+            .expect("server request should resolve");
+
+        client.shutdown().await.expect("shutdown should complete");
+    }
+
+    #[tokio::test]
+    async fn remote_server_request_received_during_initialize_is_delivered() {
+        let websocket_url = start_test_remote_server(|mut websocket| async move {
+            let JSONRPCMessage::Request(request) = read_websocket_message(&mut websocket).await
+            else {
+                panic!("expected initialize request");
+            };
+            assert_eq!(request.method, "initialize");
+
+            let request_id = RequestId::String("srv-init".to_string());
+            write_websocket_message(
+                &mut websocket,
+                JSONRPCMessage::Request(JSONRPCRequest {
+                    id: request_id.clone(),
+                    method: "item/tool/requestUserInput".to_string(),
+                    params: Some(
+                        serde_json::to_value(ToolRequestUserInputParams {
+                            thread_id: "thread-1".to_string(),
+                            turn_id: "turn-1".to_string(),
+                            item_id: "call-1".to_string(),
+                            questions: vec![ToolRequestUserInputQuestion {
+                                id: "question-1".to_string(),
+                                header: "Mode".to_string(),
+                                question: "Pick one".to_string(),
+                                is_other: false,
+                                is_secret: false,
+                                options: Some(vec![]),
+                            }],
+                            is_blocking: true,
+                            auto_resolution_ms: None,
+                        })
+                        .expect("params should serialize"),
+                    ),
+                    trace: None,
+                }),
+            )
+            .await;
+            write_websocket_message(
+                &mut websocket,
+                JSONRPCMessage::Response(JSONRPCResponse {
+                    id: request.id,
+                    result: serde_json::json!({}),
+                }),
+            )
+            .await;
+
+            let JSONRPCMessage::Notification(notification) =
+                read_websocket_message(&mut websocket).await
+            else {
+                panic!("expected initialized notification");
+            };
+            assert_eq!(notification.method, "initialized");
+
+            let JSONRPCMessage::Response(response) = read_websocket_message(&mut websocket).await
+            else {
+                panic!("expected server request response");
+            };
+            assert_eq!(response.id, request_id);
+        })
+        .await;
+        let mut client = RemoteAppServerClient::connect(test_remote_connect_args(websocket_url))
+            .await
+            .expect("remote client should connect");
+
+        let AppServerEvent::ServerRequest(request) = client
+            .next_event()
+            .await
+            .expect("request event should arrive")
+        else {
+            panic!("expected server request event");
+        };
+        client
+            .resolve_server_request(request.id().clone(), serde_json::json!({}))
+            .await
+            .expect("server request should resolve");
+
+        client.shutdown().await.expect("shutdown should complete");
+    }
+
+    #[tokio::test]
+    async fn remote_unknown_server_request_is_rejected() {
+        let websocket_url = start_test_remote_server(|mut websocket| async move {
+            expect_remote_initialize(&mut websocket).await;
+            let request_id = RequestId::String("srv-unknown".to_string());
+            write_websocket_message(
+                &mut websocket,
+                JSONRPCMessage::Request(JSONRPCRequest {
+                    id: request_id.clone(),
+                    method: "thread/unknown".to_string(),
+                    params: None,
+                    trace: None,
+                }),
+            )
+            .await;
+
+            let JSONRPCMessage::Error(response) = read_websocket_message(&mut websocket).await
+            else {
+                panic!("expected JSON-RPC error response");
+            };
+            assert_eq!(response.id, request_id);
+            assert_eq!(response.error.code, -32601);
+            assert_eq!(
+                response.error.message,
+                "unsupported remote app-server request `thread/unknown`"
+            );
+        })
+        .await;
+        let client = RemoteAppServerClient::connect(test_remote_connect_args(websocket_url))
+            .await
+            .expect("remote client should connect");
+
+        client.shutdown().await.expect("shutdown should complete");
+    }
+
+    #[tokio::test]
+    async fn remote_disconnect_surfaces_as_event() {
+        let websocket_url = start_test_remote_server(|mut websocket| async move {
+            expect_remote_initialize(&mut websocket).await;
+            websocket.close(None).await.expect("close should succeed");
+        })
+        .await;
+        let mut client = RemoteAppServerClient::connect(test_remote_connect_args(websocket_url))
+            .await
+            .expect("remote client should connect");
+
+        let event = client
+            .next_event()
+            .await
+            .expect("disconnect event should arrive");
+        assert!(matches!(event, AppServerEvent::Disconnected { .. }));
+    }
+
+    #[test]
+    fn typed_request_error_exposes_sources() {
+        let transport = TypedRequestError::Transport {
+            method: "config/read".to_string(),
+            source: IoError::new(ErrorKind::BrokenPipe, "closed"),
+        };
+        assert_eq!(std::error::Error::source(&transport).is_some(), true);
+
+        let server = TypedRequestError::Server {
+            method: "thread/read".to_string(),
+            source: JSONRPCErrorError {
+                code: -32603,
+                data: Some(serde_json::json!({"detail": "config lock mismatch"})),
+                message: "internal".to_string(),
+            },
+        };
+        assert_eq!(std::error::Error::source(&server).is_some(), false);
+        assert_eq!(
+            server.to_string(),
+            "thread/read failed: internal (code -32603), data: {\"detail\":\"config lock mismatch\"}"
+        );
+
+        let deserialize = TypedRequestError::Deserialize {
+            method: "thread/start".to_string(),
+            source: serde_json::from_str::<u32>("\"nope\"")
+                .expect_err("invalid integer should return deserialize error"),
+        };
+        assert_eq!(std::error::Error::source(&deserialize).is_some(), true);
+    }
+
+    #[tokio::test]
+    async fn next_event_surfaces_lagged_markers() {
+        let (command_tx, _command_rx) = mpsc::channel(1);
+        let (event_tx, event_rx) = mpsc::unbounded_channel();
+        let worker_handle = tokio::spawn(async {});
+        event_tx
+            .send(InProcessServerEvent::Lagged { skipped: 3 })
+            .expect("lagged marker should enqueue");
+        drop(event_tx);
+
+        let mut client = InProcessAppServerClient {
+            command_tx,
+            event_rx,
+            worker_handle,
+        };
+
+        let event = timeout(Duration::from_secs(2), client.next_event())
+            .await
+            .expect("lagged marker should arrive before timeout");
+        assert!(matches!(
+            event,
+            Some(InProcessServerEvent::Lagged { skipped: 3 })
+        ));
+
+        client.shutdown().await.expect("shutdown should complete");
+    }
+
+    #[tokio::test]
+    async fn runtime_start_args_forward_environment_manager_and_openai_form_capability() {
+        let config = Arc::new(build_test_config().await);
+        let environment_manager = Arc::new(
+            EnvironmentManager::create_for_tests(
+                Some("ws://127.0.0.1:8765".to_string()),
+                Some(
+                    ExecServerRuntimePaths::new(
+                        std::env::current_exe().expect("current exe"),
+                        /*codex_linux_sandbox_exe*/ None,
+                    )
+                    .expect("runtime paths"),
+                ),
+            )
+            .await,
+        );
+
+        let runtime_args = InProcessClientStartArgs {
+            arg0_paths: Arg0DispatchPaths::default(),
+            config: config.clone(),
+            cli_overrides: Vec::new(),
+            loader_overrides: LoaderOverrides::default(),
+            strict_config: false,
+            cloud_config_bundle: CloudConfigBundleLoader::default(),
+            feedback: CodexFeedback::new(),
+            log_db: None,
+            state_db: None,
+            environment_manager: environment_manager.clone(),
+            config_warnings: Vec::new(),
+            session_source: SessionSource::Exec,
+            enable_codex_api_key_env: false,
+            client_name: "codex-app-server-client-test".to_string(),
+            client_version: "0.0.0-test".to_string(),
+            experimental_api: true,
+            mcp_server_openai_form_elicitation: true,
+            opt_out_notification_methods: Vec::new(),
+            channel_capacity: DEFAULT_IN_PROCESS_CHANNEL_CAPACITY,
+        }
+        .into_runtime_start_args();
+
+        assert_eq!(runtime_args.config, config);
+        assert!(
+            runtime_args
+                .initialize
+                .capabilities
+                .expect("initialize capabilities")
+                .mcp_server_openai_form_elicitation
+        );
+        assert!(Arc::ptr_eq(
+            &runtime_args.environment_manager,
+            &environment_manager
+        ));
+        assert!(
+            runtime_args
+                .environment_manager
+                .default_environment()
+                .expect("default environment")
+                .is_remote()
+        );
+    }
+
+    #[tokio::test]
+    async fn shutdown_completes_promptly_without_retained_managers() {
+        let client = start_test_client(SessionSource::Cli).await;
+
+        timeout(Duration::from_secs(1), client.shutdown())
+            .await
+            .expect("shutdown should not wait for the 5s fallback timeout")
+            .expect("shutdown should complete");
+    }
+
+    #[tokio::test(start_paused = true)]
+    async fn shutdown_waits_for_in_process_drain() {
+        use std::sync::atomic::AtomicBool;
+        use std::sync::atomic::Ordering;
+
+        let (command_tx, mut command_rx) = mpsc::channel(1);
+        let (_event_tx, event_rx) = mpsc::unbounded_channel();
+        let completed = Arc::new(AtomicBool::new(false));
+        let worker_completed = Arc::clone(&completed);
+        let worker_handle = tokio::spawn(async move {
+            let response_tx = match command_rx.recv().await {
+                Some(ClientCommand::Shutdown { response_tx }) => response_tx,
+                _ => panic!("expected shutdown command"),
+            };
+            tokio::time::sleep(Duration::from_secs(30)).await;
+            worker_completed.store(true, Ordering::Release);
+            let _ = response_tx.send(Ok(()));
+        });
+        let client = InProcessAppServerClient {
+            command_tx,
+            event_rx,
+            worker_handle,
+        };
+
+        client.shutdown().await.expect("shutdown should complete");
+        assert!(completed.load(Ordering::Acquire));
+    }
+}

codex-rs/app-server-client/src/path.rs

@@ -0,0 +1,58 @@
+//! Paths resolved using the app-server host's platform rules.
+
+use std::fmt;
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct AppServerPath(String);
+
+impl AppServerPath {
+    pub fn from_app_server(path: impl Into<String>) -> Self {
+        Self(path.into())
+    }
+
+    pub fn from_absolute_str(raw: &str) -> Option<Self> {
+        (raw.starts_with('/') || is_windows_absolute_path(raw)).then(|| Self(raw.to_string()))
+    }
+
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+
+    pub fn components(&self) -> Vec<&str> {
+        let separators = if is_windows_absolute_path(&self.0) {
+            &['/', '\\'][..]
+        } else {
+            &['/'][..]
+        };
+        self.0
+            .split(separators)
+            .filter(|part| !part.is_empty())
+            .collect()
+    }
+
+    pub fn join(&self, segment: impl AsRef<str>) -> Self {
+        let is_windows = is_windows_absolute_path(&self.0);
+        let (path, separator) = if is_windows {
+            (self.0.trim_end_matches(['/', '\\']), '\\')
+        } else {
+            (self.0.trim_end_matches('/'), '/')
+        };
+        Self(format!("{path}{separator}{}", segment.as_ref()))
+    }
+}
+
+impl fmt::Display for AppServerPath {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        self.0.fmt(f)
+    }
+}
+
+fn is_windows_absolute_path(path: &str) -> bool {
+    let bytes = path.as_bytes();
+    (bytes.len() >= 3
+        && bytes[0].is_ascii_alphabetic()
+        && bytes[1] == b':'
+        && matches!(bytes[2], b'\\' | b'/'))
+        || path.starts_with("\\\\")
+        || path.starts_with("//")
+}

codex-rs/app-server-client/src/remote.rs

@@ -0,0 +1,1088 @@
+/*
+This module implements the remote app-server client transport.
+
+It owns the remote connection lifecycle, including the initialize/initialized
+handshake, JSON-RPC request/response routing, server-request resolution, and
+notification streaming. Remote connections always carry WebSocket frames, over
+either TCP WebSocket URLs or local Unix sockets. The rest of the crate uses the
+same `AppServerEvent` surface for both in-process and remote transports, so
+callers such as the TUI can switch between them without changing their
+higher-level session logic.
+*/
+
+use std::collections::HashMap;
+use std::collections::VecDeque;
+use std::io::Error as IoError;
+use std::io::ErrorKind;
+use std::io::Result as IoResult;
+use std::time::Duration;
+
+use crate::AppServerEvent;
+use crate::RequestResult;
+use crate::SHUTDOWN_TIMEOUT;
+use crate::TypedRequestError;
+use codex_app_server_protocol::ClientInfo;
+use codex_app_server_protocol::ClientNotification;
+use codex_app_server_protocol::ClientRequest;
+use codex_app_server_protocol::InitializeCapabilities;
+use codex_app_server_protocol::InitializeParams;
+use codex_app_server_protocol::JSONRPCError;
+use codex_app_server_protocol::JSONRPCErrorError;
+use codex_app_server_protocol::JSONRPCMessage;
+use codex_app_server_protocol::JSONRPCNotification;
+use codex_app_server_protocol::JSONRPCRequest;
+use codex_app_server_protocol::JSONRPCResponse;
+use codex_app_server_protocol::RequestId;
+use codex_app_server_protocol::Result as JsonRpcResult;
+use codex_app_server_protocol::ServerNotification;
+use codex_app_server_protocol::ServerRequest;
+use codex_uds::UnixStream;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use codex_utils_rustls_provider::ensure_rustls_crypto_provider;
+use futures::SinkExt;
+use futures::StreamExt;
+use serde::de::DeserializeOwned;
+use tokio::io::AsyncRead;
+use tokio::io::AsyncWrite;
+use tokio::net::TcpStream;
+use tokio::sync::mpsc;
+use tokio::sync::oneshot;
+use tokio::time::timeout;
+use tokio_tungstenite::MaybeTlsStream;
+use tokio_tungstenite::WebSocketStream;
+use tokio_tungstenite::client_async_with_config;
+use tokio_tungstenite::connect_async_with_config;
+use tokio_tungstenite::tungstenite::Error as TungsteniteError;
+use tokio_tungstenite::tungstenite::Message;
+use tokio_tungstenite::tungstenite::client::IntoClientRequest;
+use tokio_tungstenite::tungstenite::http::HeaderValue;
+use tokio_tungstenite::tungstenite::http::header::AUTHORIZATION;
+use tokio_tungstenite::tungstenite::protocol::WebSocketConfig;
+use tracing::warn;
+use url::Url;
+
+const CONNECT_TIMEOUT: Duration = Duration::from_secs(10);
+const INITIALIZE_TIMEOUT: Duration = Duration::from_secs(10);
+const REMOTE_APP_SERVER_MAX_WEBSOCKET_MESSAGE_SIZE: usize = 128 << 20;
+// Tungstenite still needs an HTTP request URI for the WebSocket handshake;
+// the bytes travel over the Unix socket, not TCP.
+const UDS_WEBSOCKET_HANDSHAKE_URL: &str = "ws://localhost/rpc";
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum RemoteAppServerEndpoint {
+    WebSocket {
+        websocket_url: String,
+        auth_token: Option<String>,
+    },
+    UnixSocket {
+        socket_path: AbsolutePathBuf,
+    },
+}
+
+#[derive(Debug, Clone)]
+pub struct RemoteAppServerConnectArgs {
+    pub endpoint: RemoteAppServerEndpoint,
+    pub client_name: String,
+    pub client_version: String,
+    pub experimental_api: bool,
+    pub mcp_server_openai_form_elicitation: bool,
+    pub opt_out_notification_methods: Vec<String>,
+    pub channel_capacity: usize,
+}
+impl RemoteAppServerConnectArgs {
+    pub(crate) fn initialize_params(&self) -> InitializeParams {
+        let capabilities = InitializeCapabilities {
+            experimental_api: self.experimental_api,
+            request_attestation: false,
+            extensions: None,
+            opt_out_notification_methods: if self.opt_out_notification_methods.is_empty() {
+                None
+            } else {
+                Some(self.opt_out_notification_methods.clone())
+            },
+            mcp_server_openai_form_elicitation: self.mcp_server_openai_form_elicitation,
+        };
+
+        InitializeParams {
+            client_info: ClientInfo {
+                name: self.client_name.clone(),
+                title: None,
+                version: self.client_version.clone(),
+            },
+            capabilities: Some(capabilities),
+        }
+    }
+}
+
+pub(crate) fn websocket_url_supports_auth_token(url: &Url) -> bool {
+    match (url.scheme(), url.host()) {
+        ("wss", Some(_)) => true,
+        ("ws", Some(url::Host::Domain(domain))) => domain.eq_ignore_ascii_case("localhost"),
+        ("ws", Some(url::Host::Ipv4(addr))) => addr.is_loopback(),
+        ("ws", Some(url::Host::Ipv6(addr))) => addr.is_loopback(),
+        _ => false,
+    }
+}
+
+enum RemoteClientCommand {
+    Request {
+        request: Box<JSONRPCRequest>,
+        response_tx: oneshot::Sender<IoResult<RequestResult>>,
+    },
+    Notify {
+        notification: ClientNotification,
+        response_tx: oneshot::Sender<IoResult<()>>,
+    },
+    ResolveServerRequest {
+        request_id: RequestId,
+        result: JsonRpcResult,
+        response_tx: oneshot::Sender<IoResult<()>>,
+    },
+    RejectServerRequest {
+        request_id: RequestId,
+        error: JSONRPCErrorError,
+        response_tx: oneshot::Sender<IoResult<()>>,
+    },
+    Shutdown {
+        response_tx: oneshot::Sender<IoResult<()>>,
+    },
+}
+
+#[derive(Default)]
+struct RemoteServerMetadata {
+    server_version: Option<String>,
+    codex_home: Option<String>,
+    platform_family: Option<String>,
+    platform_os: Option<String>,
+}
+
+pub struct RemoteAppServerClient {
+    command_tx: mpsc::Sender<RemoteClientCommand>,
+    event_rx: mpsc::UnboundedReceiver<AppServerEvent>,
+    pending_events: VecDeque<AppServerEvent>,
+    metadata: RemoteServerMetadata,
+    worker_handle: tokio::task::JoinHandle<()>,
+}
+
+#[derive(Clone)]
+pub struct RemoteAppServerRequestHandle {
+    command_tx: mpsc::Sender<RemoteClientCommand>,
+}
+
+enum SocketPeerPolicy {
+    ExplicitEndpoint,
+    #[cfg(windows)]
+    NonElevatedCurrentUser,
+}
+
+impl RemoteAppServerClient {
+    pub async fn connect(args: RemoteAppServerConnectArgs) -> IoResult<Self> {
+        Self::connect_with_policy(args, SocketPeerPolicy::ExplicitEndpoint).await
+    }
+
+    /// Connects to an implicitly discovered Windows daemon, verifying its peer
+    /// token before the WebSocket handshake or any session requests.
+    #[cfg(windows)]
+    pub async fn connect_local_daemon(args: RemoteAppServerConnectArgs) -> IoResult<Self> {
+        if !matches!(args.endpoint, RemoteAppServerEndpoint::UnixSocket { .. }) {
+            return Err(IoError::new(
+                ErrorKind::InvalidInput,
+                "local daemon requires a Unix socket",
+            ));
+        }
+        Self::connect_with_policy(args, SocketPeerPolicy::NonElevatedCurrentUser).await
+    }
+
+    async fn connect_with_policy(
+        args: RemoteAppServerConnectArgs,
+        peer_policy: SocketPeerPolicy,
+    ) -> IoResult<Self> {
+        let channel_capacity = args.channel_capacity.max(1);
+        let initialize_params = args.initialize_params();
+        match args.endpoint {
+            RemoteAppServerEndpoint::WebSocket {
+                websocket_url,
+                auth_token,
+            } => {
+                let (endpoint, stream) =
+                    connect_websocket_endpoint(websocket_url, auth_token).await?;
+                Self::connect_with_stream(channel_capacity, endpoint, stream, initialize_params)
+                    .await
+            }
+            RemoteAppServerEndpoint::UnixSocket { socket_path } => {
+                let (endpoint, stream) =
+                    connect_unix_socket_endpoint(socket_path, peer_policy).await?;
+                Self::connect_with_stream(channel_capacity, endpoint, stream, initialize_params)
+                    .await
+            }
+        }
+    }
+
+    pub fn server_version(&self) -> Option<&str> {
+        self.metadata.server_version.as_deref()
+    }
+
+    pub fn codex_home(&self) -> Option<&str> {
+        self.metadata.codex_home.as_deref()
+    }
+
+    pub fn platform_family(&self) -> Option<&str> {
+        self.metadata.platform_family.as_deref()
+    }
+
+    pub fn platform_os(&self) -> Option<&str> {
+        self.metadata.platform_os.as_deref()
+    }
+
+    async fn connect_with_stream<S>(
+        channel_capacity: usize,
+        endpoint: String,
+        stream: WebSocketStream<S>,
+        initialize_params: InitializeParams,
+    ) -> IoResult<Self>
+    where
+        S: AsyncRead + AsyncWrite + Unpin + Send + 'static,
+    {
+        let mut stream = stream;
+        let (pending_events, metadata) = initialize_remote_connection(
+            &mut stream,
+            &endpoint,
+            initialize_params,
+            INITIALIZE_TIMEOUT,
+        )
+        .await?;
+
+        let (command_tx, mut command_rx) = mpsc::channel::<RemoteClientCommand>(channel_capacity);
+        let (event_tx, event_rx) = mpsc::unbounded_channel::<AppServerEvent>();
+        let worker_handle = tokio::spawn(async move {
+            let mut pending_requests =
+                HashMap::<RequestId, oneshot::Sender<IoResult<RequestResult>>>::new();
+            let mut worker_exit_error: Option<(ErrorKind, String)> = None;
+            loop {
+                tokio::select! {
+                    command = command_rx.recv() => {
+                        let Some(command) = command else {
+                            let _ = stream.close(None).await;
+                            break;
+                        };
+                        match command {
+                            RemoteClientCommand::Request { request, response_tx } => {
+                                let request_id = request.id.clone();
+                                if pending_requests.contains_key(&request_id) {
+                                    let _ = response_tx.send(Err(IoError::new(
+                                        ErrorKind::InvalidInput,
+                                        format!("duplicate remote app-server request id `{request_id}`"),
+                                    )));
+                                    continue;
+                                }
+                                pending_requests.insert(request_id.clone(), response_tx);
+                                if let Err(err) = write_jsonrpc_message(
+                                    &mut stream,
+                                    JSONRPCMessage::Request(*request),
+                                    &endpoint,
+                                )
+                                .await
+                                {
+                                    let err_message = err.to_string();
+                                    let message = format!(
+                                        "remote app server at `{endpoint}` write failed: {err_message}"
+                                    );
+                                    if let Some(response_tx) = pending_requests.remove(&request_id) {
+                                        let _ = response_tx.send(Err(err));
+                                    }
+                                    let _ = deliver_event(
+                                        &event_tx,
+                                        AppServerEvent::Disconnected {
+                                            message: message.clone(),
+                                        },
+                                    );
+                                    worker_exit_error = Some((ErrorKind::BrokenPipe, message));
+                                    break;
+                                }
+                            }
+                            RemoteClientCommand::Notify { notification, response_tx } => {
+                                let result = write_jsonrpc_message(
+                                    &mut stream,
+                                    JSONRPCMessage::Notification(
+                                        jsonrpc_notification_from_client_notification(notification),
+                                    ),
+                                    &endpoint,
+                                )
+                                .await;
+                                let _ = response_tx.send(result);
+                            }
+                            RemoteClientCommand::ResolveServerRequest {
+                                request_id,
+                                result,
+                                response_tx,
+                            } => {
+                                let result = write_jsonrpc_message(
+                                    &mut stream,
+                                    JSONRPCMessage::Response(JSONRPCResponse {
+                                        id: request_id,
+                                        result,
+                                    }),
+                                    &endpoint,
+                                )
+                                .await;
+                                let _ = response_tx.send(result);
+                            }
+                            RemoteClientCommand::RejectServerRequest {
+                                request_id,
+                                error,
+                                response_tx,
+                            } => {
+                                let result = write_jsonrpc_message(
+                                    &mut stream,
+                                    JSONRPCMessage::Error(JSONRPCError {
+                                        error,
+                                        id: request_id,
+                                    }),
+                                    &endpoint,
+                                )
+                                .await;
+                                let _ = response_tx.send(result);
+                            }
+                            RemoteClientCommand::Shutdown { response_tx } => {
+                                let close_result = stream.close(None).await.or_else(|err| {
+                                    if websocket_close_error_is_already_closed(&err) {
+                                        Ok(())
+                                    } else {
+                                        Err(IoError::other(format!(
+                                            "failed to close websocket app server `{endpoint}`: {err}"
+                                        )))
+                                    }
+                                });
+                                let _ = response_tx.send(close_result);
+                                break;
+                            }
+                        }
+                    }
+                    message = stream.next() => {
+                        match message {
+                            Some(Ok(Message::Text(text))) => {
+                                match serde_json::from_str::<JSONRPCMessage>(&text) {
+                                    Ok(JSONRPCMessage::Response(response)) => {
+                                        if let Some(response_tx) = pending_requests.remove(&response.id) {
+                                            let _ = response_tx.send(Ok(Ok(response.result)));
+                                        }
+                                    }
+                                    Ok(JSONRPCMessage::Error(error)) => {
+                                        if let Some(response_tx) = pending_requests.remove(&error.id) {
+                                            let _ = response_tx.send(Ok(Err(error.error)));
+                                        }
+                                    }
+                                    Ok(JSONRPCMessage::Notification(notification)) => {
+                                        if let Some(event) =
+                                            app_server_event_from_notification(notification)
+                                            && let Err(err) = deliver_event(
+                                                &event_tx,
+                                                event,
+                                            )
+                                            {
+                                                warn!(%err, "failed to deliver remote app-server event");
+                                                break;
+                                            }
+                                    }
+                                    Ok(JSONRPCMessage::Request(request)) => {
+                                        let request_id = request.id.clone();
+                                        let method = request.method.clone();
+                                        match ServerRequest::try_from(request) {
+                                            Ok(request) => {
+                                                if let Err(err) = deliver_event(
+                                                    &event_tx,
+                                                    AppServerEvent::ServerRequest(Box::new(request)),
+                                                )
+                                                {
+                                                    warn!(%err, "failed to deliver remote app-server server request");
+                                                    break;
+                                                }
+                                            }
+                                            Err(err) => {
+                                                warn!(%err, method, "rejecting unknown remote app-server request");
+                                                if let Err(reject_err) = write_jsonrpc_message(
+                                                    &mut stream,
+                                                    JSONRPCMessage::Error(JSONRPCError {
+                                                        error: JSONRPCErrorError {
+                                                            code: -32601,
+                                                            message: format!(
+                                                                "unsupported remote app-server request `{method}`"
+                                                            ),
+                                                            data: None,
+                                                        },
+                                                        id: request_id,
+                                                    }),
+                                                    &endpoint,
+                                                )
+                                                .await
+                                                {
+                                                    let err_message = reject_err.to_string();
+                                                    let message = format!(
+                                                        "remote app server at `{endpoint}` write failed: {err_message}"
+                                                    );
+                                                    let _ = deliver_event(
+                                                        &event_tx,
+                                                        AppServerEvent::Disconnected {
+                                                            message: message.clone(),
+                                                        },
+                                                    );
+                                                    worker_exit_error =
+                                                        Some((ErrorKind::BrokenPipe, message));
+                                                    break;
+                                                }
+                                            }
+                                        }
+                                    }
+                                    Err(err) => {
+                                        let message = format!(
+                                            "remote app server at `{endpoint}` sent invalid JSON-RPC: {err}"
+                                        );
+                                        let _ = deliver_event(
+                                            &event_tx,
+                                            AppServerEvent::Disconnected {
+                                                message: message.clone(),
+                                            },
+                                        );
+                                        worker_exit_error =
+                                            Some((ErrorKind::InvalidData, message));
+                                        break;
+                                    }
+                                }
+                            }
+                            Some(Ok(Message::Close(frame))) => {
+                                let reason = frame
+                                    .as_ref()
+                                    .map(|frame| frame.reason.to_string())
+                                    .filter(|reason| !reason.is_empty())
+                                    .unwrap_or_else(|| "connection closed".to_string());
+                                let message = format!(
+                                    "remote app server at `{endpoint}` disconnected: {reason}"
+                                );
+                                let _ = deliver_event(
+                                    &event_tx,
+                                    AppServerEvent::Disconnected {
+                                        message: message.clone(),
+                                    },
+                                );
+                                worker_exit_error = Some((
+                                    ErrorKind::ConnectionAborted,
+                                    message,
+                                ));
+                                break;
+                            }
+                            Some(Ok(Message::Binary(_)))
+                            | Some(Ok(Message::Ping(_)))
+                            | Some(Ok(Message::Pong(_)))
+                            | Some(Ok(Message::Frame(_))) => {}
+                            Some(Err(err)) => {
+                                let message = format!(
+                                    "remote app server at `{endpoint}` transport failed: {err}"
+                                );
+                                let _ = deliver_event(
+                                    &event_tx,
+                                    AppServerEvent::Disconnected {
+                                        message: message.clone(),
+                                    },
+                                );
+                                worker_exit_error = Some((ErrorKind::InvalidData, message));
+                                break;
+                            }
+                            None => {
+                                let message = format!(
+                                    "remote app server at `{endpoint}` closed the connection"
+                                );
+                                let _ = deliver_event(
+                                    &event_tx,
+                                    AppServerEvent::Disconnected {
+                                        message: message.clone(),
+                                    },
+                                );
+                                worker_exit_error = Some((ErrorKind::UnexpectedEof, message));
+                                break;
+                            }
+                        }
+                    }
+                }
+            }
+
+            let (err_kind, err_message) = worker_exit_error.unwrap_or_else(|| {
+                (
+                    ErrorKind::BrokenPipe,
+                    "remote app-server worker channel is closed".to_string(),
+                )
+            });
+            for (_, response_tx) in pending_requests {
+                let _ = response_tx.send(Err(IoError::new(err_kind, err_message.clone())));
+            }
+        });
+
+        Ok(Self {
+            command_tx,
+            event_rx,
+            pending_events: pending_events.into(),
+            metadata,
+            worker_handle,
+        })
+    }
+
+    pub fn request_handle(&self) -> RemoteAppServerRequestHandle {
+        RemoteAppServerRequestHandle {
+            command_tx: self.command_tx.clone(),
+        }
+    }
+
+    pub async fn request(&self, request: ClientRequest) -> IoResult<RequestResult> {
+        self.request_handle().request(request).await
+    }
+
+    pub async fn request_typed<T>(&self, request: ClientRequest) -> Result<T, TypedRequestError>
+    where
+        T: DeserializeOwned,
+    {
+        let method = request.method_name();
+        let response =
+            self.request(request)
+                .await
+                .map_err(|source| TypedRequestError::Transport {
+                    method: method.to_string(),
+                    source,
+                })?;
+        let result = response.map_err(|source| TypedRequestError::Server {
+            method: method.to_string(),
+            source,
+        })?;
+        serde_json::from_value(result).map_err(|source| TypedRequestError::Deserialize {
+            method: method.to_string(),
+            source,
+        })
+    }
+
+    pub async fn notify(&self, notification: ClientNotification) -> IoResult<()> {
+        let (response_tx, response_rx) = oneshot::channel();
+        self.command_tx
+            .send(RemoteClientCommand::Notify {
+                notification,
+                response_tx,
+            })
+            .await
+            .map_err(|_| {
+                IoError::new(
+                    ErrorKind::BrokenPipe,
+                    "remote app-server worker channel is closed",
+                )
+            })?;
+        response_rx.await.map_err(|_| {
+            IoError::new(
+                ErrorKind::BrokenPipe,
+                "remote app-server notify channel is closed",
+            )
+        })?
+    }
+
+    pub async fn resolve_server_request(
+        &self,
+        request_id: RequestId,
+        result: JsonRpcResult,
+    ) -> IoResult<()> {
+        let (response_tx, response_rx) = oneshot::channel();
+        self.command_tx
+            .send(RemoteClientCommand::ResolveServerRequest {
+                request_id,
+                result,
+                response_tx,
+            })
+            .await
+            .map_err(|_| {
+                IoError::new(
+                    ErrorKind::BrokenPipe,
+                    "remote app-server worker channel is closed",
+                )
+            })?;
+        response_rx.await.map_err(|_| {
+            IoError::new(
+                ErrorKind::BrokenPipe,
+                "remote app-server resolve channel is closed",
+            )
+        })?
+    }
+
+    pub async fn reject_server_request(
+        &self,
+        request_id: RequestId,
+        error: JSONRPCErrorError,
+    ) -> IoResult<()> {
+        let (response_tx, response_rx) = oneshot::channel();
+        self.command_tx
+            .send(RemoteClientCommand::RejectServerRequest {
+                request_id,
+                error,
+                response_tx,
+            })
+            .await
+            .map_err(|_| {
+                IoError::new(
+                    ErrorKind::BrokenPipe,
+                    "remote app-server worker channel is closed",
+                )
+            })?;
+        response_rx.await.map_err(|_| {
+            IoError::new(
+                ErrorKind::BrokenPipe,
+                "remote app-server reject channel is closed",
+            )
+        })?
+    }
+
+    pub async fn next_event(&mut self) -> Option<AppServerEvent> {
+        if let Some(event) = self.pending_events.pop_front() {
+            return Some(event);
+        }
+        self.event_rx.recv().await
+    }
+
+    pub async fn shutdown(self) -> IoResult<()> {
+        let Self {
+            command_tx,
+            event_rx,
+            pending_events: _pending_events,
+            metadata: _,
+            worker_handle,
+        } = self;
+        let mut worker_handle = worker_handle;
+        drop(event_rx);
+        let (response_tx, response_rx) = oneshot::channel();
+        if command_tx
+            .send(RemoteClientCommand::Shutdown { response_tx })
+            .await
+            .is_ok()
+            && let Ok(Ok(close_result)) = timeout(SHUTDOWN_TIMEOUT, response_rx).await
+        {
+            close_result?;
+        }
+
+        if let Err(_elapsed) = timeout(SHUTDOWN_TIMEOUT, &mut worker_handle).await {
+            worker_handle.abort();
+            let _ = worker_handle.await;
+        }
+        Ok(())
+    }
+}
+
+impl RemoteAppServerRequestHandle {
+    pub async fn request(&self, request: ClientRequest) -> IoResult<RequestResult> {
+        self.request_json_rpc(jsonrpc_request_from_client_request(request))
+            .await
+    }
+
+    pub async fn request_json_rpc(&self, request: JSONRPCRequest) -> IoResult<RequestResult> {
+        let (response_tx, response_rx) = oneshot::channel();
+        self.command_tx
+            .send(RemoteClientCommand::Request {
+                request: Box::new(request),
+                response_tx,
+            })
+            .await
+            .map_err(|_| {
+                IoError::new(
+                    ErrorKind::BrokenPipe,
+                    "remote app-server worker channel is closed",
+                )
+            })?;
+        response_rx.await.map_err(|_| {
+            IoError::new(
+                ErrorKind::BrokenPipe,
+                "remote app-server request channel is closed",
+            )
+        })?
+    }
+
+    pub async fn request_typed<T>(&self, request: ClientRequest) -> Result<T, TypedRequestError>
+    where
+        T: DeserializeOwned,
+    {
+        let method = request.method_name();
+        let response =
+            self.request(request)
+                .await
+                .map_err(|source| TypedRequestError::Transport {
+                    method: method.to_string(),
+                    source,
+                })?;
+        let result = response.map_err(|source| TypedRequestError::Server {
+            method: method.to_string(),
+            source,
+        })?;
+        serde_json::from_value(result).map_err(|source| TypedRequestError::Deserialize {
+            method: method.to_string(),
+            source,
+        })
+    }
+}
+
+async fn connect_websocket_endpoint(
+    websocket_url: String,
+    auth_token: Option<String>,
+) -> IoResult<(String, WebSocketStream<MaybeTlsStream<TcpStream>>)> {
+    let url = Url::parse(&websocket_url).map_err(|err| {
+        IoError::new(
+            ErrorKind::InvalidInput,
+            format!("invalid websocket URL `{websocket_url}`: {err}"),
+        )
+    })?;
+    if auth_token.is_some() && !websocket_url_supports_auth_token(&url) {
+        return Err(IoError::new(
+            ErrorKind::InvalidInput,
+            format!(
+                "remote auth tokens require `wss://` or loopback `ws://` URLs; got `{websocket_url}`"
+            ),
+        ));
+    }
+
+    let mut request = url.as_str().into_client_request().map_err(|err| {
+        IoError::new(
+            ErrorKind::InvalidInput,
+            format!("invalid websocket URL `{websocket_url}`: {err}"),
+        )
+    })?;
+    if let Some(auth_token) = auth_token.as_deref() {
+        let header_value =
+            HeaderValue::from_str(&format!("Bearer {auth_token}")).map_err(|err| {
+                IoError::new(
+                    ErrorKind::InvalidInput,
+                    format!("invalid remote authorization header value: {err}"),
+                )
+            })?;
+        request.headers_mut().insert(AUTHORIZATION, header_value);
+    }
+
+    ensure_rustls_crypto_provider();
+    let websocket_config = remote_websocket_config();
+    let stream = timeout(
+        CONNECT_TIMEOUT,
+        connect_async_with_config(
+            request,
+            Some(websocket_config),
+            /*disable_nagle*/ false,
+        ),
+    )
+    .await
+    .map_err(|_| {
+        IoError::new(
+            ErrorKind::TimedOut,
+            format!("timed out connecting to remote app server at `{websocket_url}`"),
+        )
+    })?
+    .map(|(stream, _response)| stream)
+    .map_err(|err| {
+        IoError::other(format!(
+            "failed to connect to remote app server at `{websocket_url}`: {err}"
+        ))
+    })?;
+
+    Ok((websocket_url, stream))
+}
+
+async fn connect_unix_socket_endpoint(
+    socket_path: AbsolutePathBuf,
+    peer_policy: SocketPeerPolicy,
+) -> IoResult<(String, WebSocketStream<UnixStream>)> {
+    let endpoint = format!("unix://{}", socket_path.display());
+    let request = UDS_WEBSOCKET_HANDSHAKE_URL
+        .into_client_request()
+        .map_err(|err| {
+            IoError::new(
+                ErrorKind::InvalidInput,
+                format!("invalid UDS websocket handshake URL: {err}"),
+            )
+        })?;
+    let stream = timeout(CONNECT_TIMEOUT, UnixStream::connect(socket_path.as_path()))
+        .await
+        .map_err(|_| {
+            IoError::new(
+                ErrorKind::TimedOut,
+                format!("timed out connecting to remote app server at `{endpoint}`"),
+            )
+        })?
+        .map_err(|err| {
+            IoError::other(format!(
+                "failed to connect to remote app server at `{endpoint}`: {err}"
+            ))
+        })?;
+    match peer_policy {
+        SocketPeerPolicy::ExplicitEndpoint => {}
+        #[cfg(windows)]
+        SocketPeerPolicy::NonElevatedCurrentUser => stream.ensure_non_elevated_peer()?,
+    }
+    let websocket_config = remote_websocket_config();
+    let stream = timeout(
+        CONNECT_TIMEOUT,
+        client_async_with_config(request, stream, Some(websocket_config)),
+    )
+    .await
+    .map_err(|_| {
+        IoError::new(
+            ErrorKind::TimedOut,
+            format!("timed out upgrading remote app server at `{endpoint}`"),
+        )
+    })?
+    .map(|(stream, _response)| stream)
+    .map_err(|err| {
+        IoError::other(format!(
+            "failed to upgrade remote app server at `{endpoint}`: {err}"
+        ))
+    })?;
+
+    Ok((endpoint, stream))
+}
+
+fn remote_websocket_config() -> WebSocketConfig {
+    WebSocketConfig::default()
+        .max_frame_size(Some(REMOTE_APP_SERVER_MAX_WEBSOCKET_MESSAGE_SIZE))
+        .max_message_size(Some(REMOTE_APP_SERVER_MAX_WEBSOCKET_MESSAGE_SIZE))
+}
+
+async fn initialize_remote_connection<S>(
+    stream: &mut WebSocketStream<S>,
+    endpoint: &str,
+    params: InitializeParams,
+    initialize_timeout: Duration,
+) -> IoResult<(Vec<AppServerEvent>, RemoteServerMetadata)>
+where
+    S: AsyncRead + AsyncWrite + Unpin,
+{
+    let initialize_request_id = RequestId::String("initialize".to_string());
+    let mut pending_events = Vec::new();
+    let mut metadata = RemoteServerMetadata::default();
+    write_jsonrpc_message(
+        stream,
+        JSONRPCMessage::Request(jsonrpc_request_from_client_request(
+            ClientRequest::Initialize {
+                request_id: initialize_request_id.clone(),
+                params,
+            },
+        )),
+        endpoint,
+    )
+    .await?;
+
+    timeout(initialize_timeout, async {
+        loop {
+            match stream.next().await {
+                Some(Ok(Message::Text(text))) => {
+                    let message = serde_json::from_str::<JSONRPCMessage>(&text).map_err(|err| {
+                        IoError::other(format!(
+                            "remote app server at `{endpoint}` sent invalid initialize response: {err}"
+                        ))
+                    })?;
+                    match message {
+                        JSONRPCMessage::Response(response) if response.id == initialize_request_id => {
+                            metadata.server_version = response
+                                .result
+                                .get("userAgent")
+                                .and_then(serde_json::Value::as_str)
+                                .and_then(|user_agent| {
+                                    let (_, rest) = user_agent.split_once('/')?;
+                                    rest.split_whitespace().next().map(str::to_string)
+                                });
+                            metadata.codex_home = response
+                                .result
+                                .get("codexHome")
+                                .and_then(serde_json::Value::as_str)
+                                .filter(|codex_home| !codex_home.is_empty())
+                                .map(str::to_string);
+                            metadata.platform_family = response.result.get("platformFamily")
+                                .and_then(serde_json::Value::as_str).map(str::to_string);
+                            metadata.platform_os = response.result.get("platformOs")
+                                .and_then(serde_json::Value::as_str).map(str::to_string);
+                            break Ok(());
+                        }
+                        JSONRPCMessage::Error(error) if error.id == initialize_request_id => {
+                            break Err(IoError::other(format!(
+                                "remote app server at `{endpoint}` rejected initialize: {}",
+                                error.error.message
+                            )));
+                        }
+                        JSONRPCMessage::Notification(notification) => {
+                            if let Some(event) = app_server_event_from_notification(notification) {
+                                pending_events.push(event);
+                            }
+                        }
+                        JSONRPCMessage::Request(request) => {
+                            let request_id = request.id.clone();
+                            let method = request.method.clone();
+                            match ServerRequest::try_from(request) {
+                                Ok(request) => {
+                                    pending_events
+                                        .push(AppServerEvent::ServerRequest(Box::new(request)));
+                                }
+                                Err(err) => {
+                                    warn!(%err, method, "rejecting unknown remote app-server request during initialize");
+                                    write_jsonrpc_message(
+                                        stream,
+                                        JSONRPCMessage::Error(JSONRPCError {
+                                            error: JSONRPCErrorError {
+                                                code: -32601,
+                                                message: format!(
+                                                    "unsupported remote app-server request `{method}`"
+                                                ),
+                                                data: None,
+                                            },
+                                            id: request_id,
+                                        }),
+                                        endpoint,
+                                    )
+                                    .await?;
+                                }
+                            }
+                        }
+                        JSONRPCMessage::Response(_) | JSONRPCMessage::Error(_) => {}
+                    }
+                }
+                Some(Ok(Message::Binary(_)))
+                | Some(Ok(Message::Ping(_)))
+                | Some(Ok(Message::Pong(_)))
+                | Some(Ok(Message::Frame(_))) => {}
+                Some(Ok(Message::Close(frame))) => {
+                    let reason = frame
+                        .as_ref()
+                        .map(|frame| frame.reason.to_string())
+                        .filter(|reason| !reason.is_empty())
+                        .unwrap_or_else(|| "connection closed during initialize".to_string());
+                    break Err(IoError::new(
+                        ErrorKind::ConnectionAborted,
+                        format!(
+                            "remote app server at `{endpoint}` closed during initialize: {reason}"
+                        ),
+                    ));
+                }
+                Some(Err(err)) => {
+                    break Err(IoError::other(format!(
+                        "remote app server at `{endpoint}` transport failed during initialize: {err}"
+                    )));
+                }
+                None => {
+                    break Err(IoError::new(
+                        ErrorKind::UnexpectedEof,
+                        format!("remote app server at `{endpoint}` closed during initialize"),
+                    ));
+                }
+            }
+        }
+    })
+    .await
+    .map_err(|_| {
+        IoError::new(
+            ErrorKind::TimedOut,
+            format!("timed out waiting for initialize response from `{endpoint}`"),
+        )
+    })??;
+
+    write_jsonrpc_message(
+        stream,
+        JSONRPCMessage::Notification(jsonrpc_notification_from_client_notification(
+            ClientNotification::Initialized,
+        )),
+        endpoint,
+    )
+    .await?;
+
+    Ok((pending_events, metadata))
+}
+
+fn app_server_event_from_notification(notification: JSONRPCNotification) -> Option<AppServerEvent> {
+    match ServerNotification::try_from(notification) {
+        Ok(notification) => Some(AppServerEvent::ServerNotification(Box::new(notification))),
+        Err(_) => None,
+    }
+}
+
+fn deliver_event(
+    event_tx: &mpsc::UnboundedSender<AppServerEvent>,
+    event: AppServerEvent,
+) -> IoResult<()> {
+    event_tx.send(event).map_err(|_| {
+        IoError::new(
+            ErrorKind::BrokenPipe,
+            "remote app-server event consumer channel is closed",
+        )
+    })
+}
+
+fn jsonrpc_request_from_client_request(request: ClientRequest) -> JSONRPCRequest {
+    let value = match serde_json::to_value(request) {
+        Ok(value) => value,
+        Err(err) => panic!("client request should serialize: {err}"),
+    };
+    match serde_json::from_value(value) {
+        Ok(request) => request,
+        Err(err) => panic!("client request should encode as JSON-RPC request: {err}"),
+    }
+}
+
+fn jsonrpc_notification_from_client_notification(
+    notification: ClientNotification,
+) -> JSONRPCNotification {
+    let value = match serde_json::to_value(notification) {
+        Ok(value) => value,
+        Err(err) => panic!("client notification should serialize: {err}"),
+    };
+    match serde_json::from_value(value) {
+        Ok(notification) => notification,
+        Err(err) => panic!("client notification should encode as JSON-RPC notification: {err}"),
+    }
+}
+
+async fn write_jsonrpc_message<S>(
+    stream: &mut WebSocketStream<S>,
+    message: JSONRPCMessage,
+    endpoint: &str,
+) -> IoResult<()>
+where
+    S: AsyncRead + AsyncWrite + Unpin,
+{
+    let payload = serde_json::to_string(&message).map_err(IoError::other)?;
+    stream
+        .send(Message::Text(payload.into()))
+        .await
+        .map_err(|err| {
+            IoError::other(format!(
+                "failed to write websocket message to `{endpoint}`: {err}"
+            ))
+        })
+}
+
+fn websocket_close_error_is_already_closed(err: &TungsteniteError) -> bool {
+    match err {
+        TungsteniteError::ConnectionClosed | TungsteniteError::AlreadyClosed => true,
+        TungsteniteError::Io(err) => matches!(
+            err.kind(),
+            ErrorKind::BrokenPipe | ErrorKind::ConnectionReset | ErrorKind::NotConnected
+        ),
+        _ => false,
+    }
+}
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn shutdown_tolerates_worker_exit_after_command_is_queued() {
+        let (command_tx, mut command_rx) = mpsc::channel(1);
+        let (_event_tx, event_rx) = mpsc::unbounded_channel::<AppServerEvent>();
+        let worker_handle = tokio::spawn(async move {
+            let _ = command_rx.recv().await;
+        });
+        let client = RemoteAppServerClient {
+            command_tx,
+            event_rx,
+            pending_events: VecDeque::new(),
+            metadata: RemoteServerMetadata::default(),
+            worker_handle,
+        };
+
+        client
+            .shutdown()
+            .await
+            .expect("shutdown should complete when worker exits first");
+    }
+}

codex-rs/app-server-protocol/schema/json/AttestationGenerateResponse.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "properties": {
+    "token": {
+      "description": "Opaque client attestation token.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "token"
+  ],
+  "title": "AttestationGenerateResponse",
+  "type": "object"
+}

codex-rs/app-server-protocol/schema/json/ClientNotification.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "oneOf": [
+    {
+      "properties": {
+        "method": {
+          "enum": [
+            "initialized"
+          ],
+          "title": "InitializedNotificationMethod",
+          "type": "string"
+        }
+      },
+      "required": [
+        "method"
+      ],
+      "title": "InitializedNotification",
+      "type": "object"
+    }
+  ],
+  "title": "ClientNotification"
+}

codex-rs/app-server-protocol/schema/json/CommandExecutionRequestApprovalResponse.json

@@ -0,0 +1,116 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "CommandExecutionApprovalDecision": {
+      "oneOf": [
+        {
+          "description": "User approved the command.",
+          "enum": [
+            "accept"
+          ],
+          "type": "string"
+        },
+        {
+          "description": "User approved the command and future prompts in the same session-scoped approval cache should run without prompting.",
+          "enum": [
+            "acceptForSession"
+          ],
+          "type": "string"
+        },
+        {
+          "additionalProperties": false,
+          "description": "User approved the command, and wants to apply the proposed execpolicy amendment so future matching commands can run without prompting.",
+          "properties": {
+            "acceptWithExecpolicyAmendment": {
+              "properties": {
+                "execpolicy_amendment": {
+                  "items": {
+                    "type": "string"
+                  },
+                  "type": "array"
+                }
+              },
+              "required": [
+                "execpolicy_amendment"
+              ],
+              "type": "object"
+            }
+          },
+          "required": [
+            "acceptWithExecpolicyAmendment"
+          ],
+          "title": "AcceptWithExecpolicyAmendmentCommandExecutionApprovalDecision",
+          "type": "object"
+        },
+        {
+          "additionalProperties": false,
+          "description": "User chose a persistent network policy rule (allow/deny) for this host.",
+          "properties": {
+            "applyNetworkPolicyAmendment": {
+              "properties": {
+                "network_policy_amendment": {
+                  "$ref": "#/definitions/NetworkPolicyAmendment"
+                }
+              },
+              "required": [
+                "network_policy_amendment"
+              ],
+              "type": "object"
+            }
+          },
+          "required": [
+            "applyNetworkPolicyAmendment"
+          ],
+          "title": "ApplyNetworkPolicyAmendmentCommandExecutionApprovalDecision",
+          "type": "object"
+        },
+        {
+          "description": "User denied the command. The agent will continue the turn.",
+          "enum": [
+            "decline"
+          ],
+          "type": "string"
+        },
+        {
+          "description": "User denied the command. The turn will also be immediately interrupted.",
+          "enum": [
+            "cancel"
+          ],
+          "type": "string"
+        }
+      ]
+    },
+    "NetworkPolicyAmendment": {
+      "properties": {
+        "action": {
+          "$ref": "#/definitions/NetworkPolicyRuleAction"
+        },
+        "host": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "action",
+        "host"
+      ],
+      "type": "object"
+    },
+    "NetworkPolicyRuleAction": {
+      "enum": [
+        "allow",
+        "deny"
+      ],
+      "type": "string"
+    }
+  },
+  "properties": {
+    "decision": {
+      "$ref": "#/definitions/CommandExecutionApprovalDecision"
+    }
+  },
+  "required": [
+    "decision"
+  ],
+  "title": "CommandExecutionRequestApprovalResponse",
+  "type": "object"
+}

codex-rs/app-server-protocol/schema/json/ExecCommandApprovalResponse.json

@@ -0,0 +1,146 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "NetworkPolicyAmendment": {
+      "properties": {
+        "action": {
+          "$ref": "#/definitions/NetworkPolicyRuleAction"
+        },
+        "host": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "action",
+        "host"
+      ],
+      "type": "object"
+    },
+    "NetworkPolicyRuleAction": {
+      "enum": [
+        "allow",
+        "deny"
+      ],
+      "type": "string"
+    },
+    "ReviewDecision": {
+      "description": "User's decision in response to an ExecApprovalRequest.",
+      "oneOf": [
+        {
+          "description": "User has approved this command and the agent should execute it.",
+          "enum": [
+            "approved"
+          ],
+          "type": "string"
+        },
+        {
+          "additionalProperties": false,
+          "description": "User has approved this command and wants to apply the proposed execpolicy amendment so future matching commands are permitted.",
+          "properties": {
+            "approved_execpolicy_amendment": {
+              "properties": {
+                "proposed_execpolicy_amendment": {
+                  "items": {
+                    "type": "string"
+                  },
+                  "type": "array"
+                }
+              },
+              "required": [
+                "proposed_execpolicy_amendment"
+              ],
+              "type": "object"
+            }
+          },
+          "required": [
+            "approved_execpolicy_amendment"
+          ],
+          "title": "ApprovedExecpolicyAmendmentReviewDecision",
+          "type": "object"
+        },
+        {
+          "description": "User has approved this request and wants future prompts in the same session-scoped approval cache to be automatically approved for the remainder of the session.",
+          "enum": [
+            "approved_for_session"
+          ],
+          "type": "string"
+        },
+        {
+          "description": "User has approved this MCP tool call and wants to amend its policy so matching future calls are automatically approved across sessions.",
+          "enum": [
+            "approved_mcp_policy_amendment"
+          ],
+          "type": "string"
+        },
+        {
+          "additionalProperties": false,
+          "description": "User chose to persist a network policy rule (allow/deny) for future requests to the same host.",
+          "properties": {
+            "network_policy_amendment": {
+              "properties": {
+                "network_policy_amendment": {
+                  "$ref": "#/definitions/NetworkPolicyAmendment"
+                }
+              },
+              "required": [
+                "network_policy_amendment"
+              ],
+              "type": "object"
+            }
+          },
+          "required": [
+            "network_policy_amendment"
+          ],
+          "title": "NetworkPolicyAmendmentReviewDecision",
+          "type": "object"
+        },
+        {
+          "additionalProperties": false,
+          "description": "User has denied this command and the agent should not execute it, but it should continue the session and try something else.",
+          "properties": {
+            "denied": {
+              "properties": {
+                "rejection": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "rejection"
+              ],
+              "type": "object"
+            }
+          },
+          "required": [
+            "denied"
+          ],
+          "title": "DeniedReviewDecision",
+          "type": "object"
+        },
+        {
+          "description": "Automatic approval review timed out before reaching a decision.",
+          "enum": [
+            "timed_out"
+          ],
+          "type": "string"
+        },
+        {
+          "description": "User has denied this command and the agent should not do anything until the user's next command.",
+          "enum": [
+            "abort"
+          ],
+          "type": "string"
+        }
+      ]
+    }
+  },
+  "properties": {
+    "decision": {
+      "$ref": "#/definitions/ReviewDecision"
+    }
+  },
+  "required": [
+    "decision"
+  ],
+  "title": "ExecCommandApprovalResponse",
+  "type": "object"
+}

codex-rs/app-server-protocol/schema/json/FileChangeRequestApprovalResponse.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "FileChangeApprovalDecision": {
+      "oneOf": [
+        {
+          "description": "User approved the file changes.",
+          "enum": [
+            "accept"
+          ],
+          "type": "string"
+        },
+        {
+          "description": "User approved the file changes and future changes to the same files should run without prompting.",
+          "enum": [
+            "acceptForSession"
+          ],
+          "type": "string"
+        },
+        {
+          "description": "User denied the file changes. The agent will continue the turn.",
+          "enum": [
+            "decline"
+          ],
+          "type": "string"
+        },
+        {
+          "description": "User denied the file changes. The turn will also be immediately interrupted.",
+          "enum": [
+            "cancel"
+          ],
+          "type": "string"
+        }
+      ]
+    }
+  },
+  "properties": {
+    "decision": {
+      "$ref": "#/definitions/FileChangeApprovalDecision"
+    }
+  },
+  "required": [
+    "decision"
+  ],
+  "title": "FileChangeRequestApprovalResponse",
+  "type": "object"
+}

codex-rs/app-server-protocol/schema/json/FuzzyFileSearchParams.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "properties": {
+    "cancellationToken": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "query": {
+      "type": "string"
+    },
+    "roots": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "query",
+    "roots"
+  ],
+  "title": "FuzzyFileSearchParams",
+  "type": "object"
+}

codex-rs/app-server-protocol/schema/json/FuzzyFileSearchSessionUpdatedNotification.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "FuzzyFileSearchMatchType": {
+      "enum": [
+        "file",
+        "directory"
+      ],
+      "type": "string"
+    },
+    "FuzzyFileSearchResult": {
+      "description": "Superset of [`codex_file_search::FileMatch`]",
+      "properties": {
+        "file_name": {
+          "type": "string"
+        },
+        "indices": {
+          "items": {
+            "format": "uint32",
+            "minimum": 0.0,
+            "type": "integer"
+          },
+          "type": [
+            "array",
+            "null"
+          ]
+        },
+        "match_type": {
+          "$ref": "#/definitions/FuzzyFileSearchMatchType"
+        },
+        "path": {
+          "type": "string"
+        },
+        "root": {
+          "type": "string"
+        },
+        "score": {
+          "format": "uint32",
+          "minimum": 0.0,
+          "type": "integer"
+        }
+      },
+      "required": [
+        "file_name",
+        "match_type",
+        "path",
+        "root",
+        "score"
+      ],
+      "type": "object"
+    }
+  },
+  "properties": {
+    "files": {
+      "items": {
+        "$ref": "#/definitions/FuzzyFileSearchResult"
+      },
+      "type": "array"
+    },
+    "query": {
+      "type": "string"
+    },
+    "sessionId": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "files",
+    "query",
+    "sessionId"
+  ],
+  "title": "FuzzyFileSearchSessionUpdatedNotification",
+  "type": "object"
+}

codex-rs/app-server-protocol/schema/json/JSONRPCError.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "JSONRPCErrorError": {
+      "properties": {
+        "code": {
+          "format": "int64",
+          "type": "integer"
+        },
+        "data": true,
+        "message": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "code",
+        "message"
+      ],
+      "type": "object"
+    },
+    "RequestId": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "format": "int64",
+          "type": "integer"
+        }
+      ]
+    }
+  },
+  "description": "A response to a request that indicates an error occurred.",
+  "properties": {
+    "error": {
+      "$ref": "#/definitions/JSONRPCErrorError"
+    },
+    "id": {
+      "$ref": "#/definitions/RequestId"
+    }
+  },
+  "required": [
+    "error",
+    "id"
+  ],
+  "title": "JSONRPCError",
+  "type": "object"
+}

codex-rs/app-server-protocol/schema/json/JSONRPCNotification.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "description": "A notification which does not expect a response.",
+  "properties": {
+    "method": {
+      "type": "string"
+    },
+    "params": true
+  },
+  "required": [
+    "method"
+  ],
+  "title": "JSONRPCNotification",
+  "type": "object"
+}

codex-rs/app-server-protocol/schema/json/JSONRPCRequest.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "RequestId": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "format": "int64",
+          "type": "integer"
+        }
+      ]
+    },
+    "W3cTraceContext": {
+      "properties": {
+        "traceparent": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "tracestate": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "type": "object"
+    }
+  },
+  "description": "A request that expects a response.",
+  "properties": {
+    "id": {
+      "$ref": "#/definitions/RequestId"
+    },
+    "method": {
+      "type": "string"
+    },
+    "params": true,
+    "trace": {
+      "anyOf": [
+        {
+          "$ref": "#/definitions/W3cTraceContext"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Optional W3C Trace Context for distributed tracing."
+    }
+  },
+  "required": [
+    "id",
+    "method"
+  ],
+  "title": "JSONRPCRequest",
+  "type": "object"
+}

codex-rs/app-server-protocol/schema/json/McpServerElicitationRequestResponse.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "McpServerElicitationAction": {
+      "enum": [
+        "accept",
+        "decline",
+        "cancel"
+      ],
+      "type": "string"
+    }
+  },
+  "properties": {
+    "_meta": {
+      "description": "Optional client metadata for form-mode action handling."
+    },
+    "action": {
+      "$ref": "#/definitions/McpServerElicitationAction"
+    },
+    "content": {
+      "description": "Structured user input for accepted elicitations, mirroring RMCP `CreateElicitationResult`.\n\nThis is nullable because decline/cancel responses have no content."
+    }
+  },
+  "required": [
+    "action"
+  ],
+  "title": "McpServerElicitationRequestResponse",
+  "type": "object"
+}

codex-rs/app-server-protocol/schema/json/PermissionsRequestApprovalResponse.json

@@ -0,0 +1,322 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "AdditionalFileSystemPermissions": {
+      "properties": {
+        "entries": {
+          "items": {
+            "$ref": "#/definitions/FileSystemSandboxEntry"
+          },
+          "type": [
+            "array",
+            "null"
+          ]
+        },
+        "globScanMaxDepth": {
+          "format": "uint",
+          "minimum": 1.0,
+          "type": [
+            "integer",
+            "null"
+          ]
+        },
+        "read": {
+          "description": "This will be removed in favor of `entries`.",
+          "items": {
+            "$ref": "#/definitions/LegacyAppPathString"
+          },
+          "type": [
+            "array",
+            "null"
+          ]
+        },
+        "write": {
+          "description": "This will be removed in favor of `entries`.",
+          "items": {
+            "$ref": "#/definitions/LegacyAppPathString"
+          },
+          "type": [
+            "array",
+            "null"
+          ]
+        }
+      },
+      "type": "object"
+    },
+    "AdditionalNetworkPermissions": {
+      "properties": {
+        "enabled": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        }
+      },
+      "type": "object"
+    },
+    "FileSystemAccessMode": {
+      "enum": [
+        "read",
+        "write",
+        "deny"
+      ],
+      "type": "string"
+    },
+    "FileSystemPath": {
+      "oneOf": [
+        {
+          "properties": {
+            "path": {
+              "$ref": "#/definitions/LegacyAppPathString"
+            },
+            "type": {
+              "enum": [
+                "path"
+              ],
+              "title": "PathFileSystemPathType",
+              "type": "string"
+            }
+          },
+          "required": [
+            "path",
+            "type"
+          ],
+          "title": "PathFileSystemPath",
+          "type": "object"
+        },
+        {
+          "properties": {
+            "pattern": {
+              "type": "string"
+            },
+            "type": {
+              "enum": [
+                "glob_pattern"
+              ],
+              "title": "GlobPatternFileSystemPathType",
+              "type": "string"
+            }
+          },
+          "required": [
+            "pattern",
+            "type"
+          ],
+          "title": "GlobPatternFileSystemPath",
+          "type": "object"
+        },
+        {
+          "properties": {
+            "type": {
+              "enum": [
+                "special"
+              ],
+              "title": "SpecialFileSystemPathType",
+              "type": "string"
+            },
+            "value": {
+              "$ref": "#/definitions/FileSystemSpecialPath"
+            }
+          },
+          "required": [
+            "type",
+            "value"
+          ],
+          "title": "SpecialFileSystemPath",
+          "type": "object"
+        }
+      ]
+    },
+    "FileSystemSandboxEntry": {
+      "properties": {
+        "access": {
+          "$ref": "#/definitions/FileSystemAccessMode"
+        },
+        "path": {
+          "$ref": "#/definitions/FileSystemPath"
+        }
+      },
+      "required": [
+        "access",
+        "path"
+      ],
+      "type": "object"
+    },
+    "FileSystemSpecialPath": {
+      "oneOf": [
+        {
+          "properties": {
+            "kind": {
+              "enum": [
+                "root"
+              ],
+              "type": "string"
+            }
+          },
+          "required": [
+            "kind"
+          ],
+          "title": "RootFileSystemSpecialPath",
+          "type": "object"
+        },
+        {
+          "properties": {
+            "kind": {
+              "enum": [
+                "minimal"
+              ],
+              "type": "string"
+            }
+          },
+          "required": [
+            "kind"
+          ],
+          "title": "MinimalFileSystemSpecialPath",
+          "type": "object"
+        },
+        {
+          "properties": {
+            "kind": {
+              "enum": [
+                "project_roots"
+              ],
+              "type": "string"
+            },
+            "subpath": {
+              "anyOf": [
+                {
+                  "$ref": "#/definitions/LegacyAppPathString"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            }
+          },
+          "required": [
+            "kind"
+          ],
+          "title": "KindFileSystemSpecialPath",
+          "type": "object"
+        },
+        {
+          "properties": {
+            "kind": {
+              "enum": [
+                "tmpdir"
+              ],
+              "type": "string"
+            }
+          },
+          "required": [
+            "kind"
+          ],
+          "title": "TmpdirFileSystemSpecialPath",
+          "type": "object"
+        },
+        {
+          "properties": {
+            "kind": {
+              "enum": [
+                "slash_tmp"
+              ],
+              "type": "string"
+            }
+          },
+          "required": [
+            "kind"
+          ],
+          "title": "SlashTmpFileSystemSpecialPath",
+          "type": "object"
+        },
+        {
+          "properties": {
+            "kind": {
+              "enum": [
+                "unknown"
+              ],
+              "type": "string"
+            },
+            "path": {
+              "type": "string"
+            },
+            "subpath": {
+              "anyOf": [
+                {
+                  "$ref": "#/definitions/LegacyAppPathString"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            }
+          },
+          "required": [
+            "kind",
+            "path"
+          ],
+          "type": "object"
+        }
+      ]
+    },
+    "GrantedPermissionProfile": {
+      "properties": {
+        "fileSystem": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/AdditionalFileSystemPermissions"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "network": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/AdditionalNetworkPermissions"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "type": "object"
+    },
+    "LegacyAppPathString": {
+      "type": "string"
+    },
+    "PermissionGrantScope": {
+      "enum": [
+        "turn",
+        "session"
+      ],
+      "type": "string"
+    }
+  },
+  "properties": {
+    "permissions": {
+      "$ref": "#/definitions/GrantedPermissionProfile"
+    },
+    "scope": {
+      "allOf": [
+        {
+          "$ref": "#/definitions/PermissionGrantScope"
+        }
+      ],
+      "default": "turn"
+    },
+    "strictAutoReview": {
+      "description": "Review every subsequent command in this turn before normal sandboxed execution.",
+      "type": [
+        "boolean",
+        "null"
+      ]
+    }
+  },
+  "required": [
+    "permissions"
+  ],
+  "title": "PermissionsRequestApprovalResponse",
+  "type": "object"
+}

codex-rs/app-server-protocol/schema/json/ToolRequestUserInputResponse.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "ToolRequestUserInputAnswer": {
+      "description": "EXPERIMENTAL. Captures a user's answer to a request_user_input question.",
+      "properties": {
+        "answers": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "answers"
+      ],
+      "type": "object"
+    }
+  },
+  "description": "EXPERIMENTAL. Response payload mapping question ids to answers.",
+  "properties": {
+    "answers": {
+      "additionalProperties": {
+        "$ref": "#/definitions/ToolRequestUserInputAnswer"
+      },
+      "type": "object"
+    }
+  },
+  "required": [
+    "answers"
+  ],
+  "title": "ToolRequestUserInputResponse",
+  "type": "object"
+}

codex-rs/app-server-protocol/schema/typescript/AbsolutePathBuf.ts

@@ -0,0 +1,14 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * A path that is guaranteed to be absolute and normalized (though it is not
+ * guaranteed to be canonicalized or exist on the filesystem).
+ *
+ * IMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set
+ * using [AbsolutePathBufGuard::new]. If no base path is set, the
+ * deserialization will fail unless the path being deserialized is already
+ * absolute.
+ */
+export type AbsolutePathBuf = string;

codex-rs/app-server-protocol/schema/typescript/AgentMessageInputContent.ts

@@ -0,0 +1,5 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type AgentMessageInputContent = { "type": "input_text", text: string, } | { "type": "encrypted_content", encrypted_content: string, };

codex-rs/app-server-protocol/schema/typescript/AgentPath.ts

@@ -0,0 +1,5 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type AgentPath = string;

codex-rs/app-server-protocol/schema/typescript/ApplyPatchApprovalParams.ts

@@ -0,0 +1,21 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { FileChange } from "./FileChange";
+import type { ThreadId } from "./ThreadId";
+
+export type ApplyPatchApprovalParams = { conversationId: ThreadId,
+/**
+ * Use to correlate this with [codex_protocol::protocol::PatchApplyBeginEvent]
+ * and [codex_protocol::protocol::PatchApplyEndEvent].
+ */
+callId: string, fileChanges: { [key in string]?: FileChange },
+/**
+ * Optional explanatory reason (e.g. request for extra write access).
+ */
+reason: string | null,
+/**
+ * When set, the agent is asking the user to allow writes under this root
+ * for the remainder of the session (unclear if this is honored today).
+ */
+grantRoot: string | null, };

codex-rs/app-server-protocol/schema/typescript/ApplyPatchApprovalResponse.ts

@@ -0,0 +1,6 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { ReviewDecision } from "./ReviewDecision";
+
+export type ApplyPatchApprovalResponse = { decision: ReviewDecision, };

codex-rs/app-server-protocol/schema/typescript/AuthMode.ts

@@ -0,0 +1,8 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * Authentication mode for OpenAI-backed providers.
+ */
+export type AuthMode = "apikey" | "chatgpt" | "chatgptAuthTokens" | "headers" | "agentIdentity" | "personalAccessToken" | "bedrockApiKey" | "bedrockAccessKeys";

codex-rs/app-server-protocol/schema/typescript/AutoCompactTokenLimitScope.ts

@@ -0,0 +1,9 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * Selects which part of the active context is charged against
+ * `model_auto_compact_token_limit`.
+ */
+export type AutoCompactTokenLimitScope = "total" | "body_after_prefix";

codex-rs/app-server-protocol/schema/typescript/ClientInfo.ts

@@ -0,0 +1,5 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type ClientInfo = { name: string, title: string | null, version: string, };

codex-rs/app-server-protocol/schema/typescript/ClientNotification.ts

@@ -0,0 +1,5 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type ClientNotification = { "method": "initialized" };

codex-rs/app-server-protocol/schema/typescript/ClientRequest.ts

@@ -0,0 +1,107 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { FuzzyFileSearchParams } from "./FuzzyFileSearchParams";
+import type { GetAuthStatusParams } from "./GetAuthStatusParams";
+import type { GetConversationSummaryParams } from "./GetConversationSummaryParams";
+import type { GitDiffToRemoteParams } from "./GitDiffToRemoteParams";
+import type { InitializeParams } from "./InitializeParams";
+import type { RequestId } from "./RequestId";
+import type { AppsInstalledParams } from "./v2/AppsInstalledParams";
+import type { AppsListParams } from "./v2/AppsListParams";
+import type { AppsReadParams } from "./v2/AppsReadParams";
+import type { CancelLoginAccountParams } from "./v2/CancelLoginAccountParams";
+import type { CommandExecParams } from "./v2/CommandExecParams";
+import type { CommandExecResizeParams } from "./v2/CommandExecResizeParams";
+import type { CommandExecTerminateParams } from "./v2/CommandExecTerminateParams";
+import type { CommandExecWriteParams } from "./v2/CommandExecWriteParams";
+import type { ConfigBatchWriteParams } from "./v2/ConfigBatchWriteParams";
+import type { ConfigReadParams } from "./v2/ConfigReadParams";
+import type { ConfigValueWriteParams } from "./v2/ConfigValueWriteParams";
+import type { ConsumeAccountRateLimitResetCreditParams } from "./v2/ConsumeAccountRateLimitResetCreditParams";
+import type { ExperimentalFeatureEnablementSetParams } from "./v2/ExperimentalFeatureEnablementSetParams";
+import type { ExperimentalFeatureListParams } from "./v2/ExperimentalFeatureListParams";
+import type { ExternalAgentConfigDetectParams } from "./v2/ExternalAgentConfigDetectParams";
+import type { ExternalAgentConfigImportHistoryRecordParams } from "./v2/ExternalAgentConfigImportHistoryRecordParams";
+import type { ExternalAgentConfigImportParams } from "./v2/ExternalAgentConfigImportParams";
+import type { FeedbackUploadParams } from "./v2/FeedbackUploadParams";
+import type { FsCopyParams } from "./v2/FsCopyParams";
+import type { FsCreateDirectoryParams } from "./v2/FsCreateDirectoryParams";
+import type { FsGetMetadataParams } from "./v2/FsGetMetadataParams";
+import type { FsReadDirectoryParams } from "./v2/FsReadDirectoryParams";
+import type { FsReadFileParams } from "./v2/FsReadFileParams";
+import type { FsRemoveParams } from "./v2/FsRemoveParams";
+import type { FsUnwatchParams } from "./v2/FsUnwatchParams";
+import type { FsWatchParams } from "./v2/FsWatchParams";
+import type { FsWriteFileParams } from "./v2/FsWriteFileParams";
+import type { GetAccountParams } from "./v2/GetAccountParams";
+import type { GetAccountRateLimitsParams } from "./v2/GetAccountRateLimitsParams";
+import type { GetAccountTokenUsageParams } from "./v2/GetAccountTokenUsageParams";
+import type { HooksListParams } from "./v2/HooksListParams";
+import type { ListMcpServerStatusParams } from "./v2/ListMcpServerStatusParams";
+import type { LoginAccountParams } from "./v2/LoginAccountParams";
+import type { MarketplaceAddParams } from "./v2/MarketplaceAddParams";
+import type { MarketplaceRemoveParams } from "./v2/MarketplaceRemoveParams";
+import type { MarketplaceUpgradeParams } from "./v2/MarketplaceUpgradeParams";
+import type { McpResourceReadParams } from "./v2/McpResourceReadParams";
+import type { McpServerOauthLoginParams } from "./v2/McpServerOauthLoginParams";
+import type { McpServerToolCallParams } from "./v2/McpServerToolCallParams";
+import type { ModelListParams } from "./v2/ModelListParams";
+import type { ModelProviderCapabilitiesReadParams } from "./v2/ModelProviderCapabilitiesReadParams";
+import type { PermissionProfileListParams } from "./v2/PermissionProfileListParams";
+import type { PluginInstallParams } from "./v2/PluginInstallParams";
+import type { PluginInstalledParams } from "./v2/PluginInstalledParams";
+import type { PluginListParams } from "./v2/PluginListParams";
+import type { PluginReadParams } from "./v2/PluginReadParams";
+import type { PluginReconcileParams } from "./v2/PluginReconcileParams";
+import type { PluginShareCheckoutParams } from "./v2/PluginShareCheckoutParams";
+import type { PluginShareDeleteParams } from "./v2/PluginShareDeleteParams";
+import type { PluginShareListParams } from "./v2/PluginShareListParams";
+import type { PluginShareSaveParams } from "./v2/PluginShareSaveParams";
+import type { PluginShareUpdateTargetsParams } from "./v2/PluginShareUpdateTargetsParams";
+import type { PluginSkillReadParams } from "./v2/PluginSkillReadParams";
+import type { PluginUninstallParams } from "./v2/PluginUninstallParams";
+import type { ReviewStartParams } from "./v2/ReviewStartParams";
+import type { SendAddCreditsNudgeEmailParams } from "./v2/SendAddCreditsNudgeEmailParams";
+import type { SkillsConfigWriteParams } from "./v2/SkillsConfigWriteParams";
+import type { SkillsExtraRootsSetParams } from "./v2/SkillsExtraRootsSetParams";
+import type { SkillsListParams } from "./v2/SkillsListParams";
+import type { ThreadApproveGuardianDeniedActionParams } from "./v2/ThreadApproveGuardianDeniedActionParams";
+import type { ThreadArchiveParams } from "./v2/ThreadArchiveParams";
+import type { ThreadAttachmentAddParams } from "./v2/ThreadAttachmentAddParams";
+import type { ThreadAttachmentListParams } from "./v2/ThreadAttachmentListParams";
+import type { ThreadAttachmentRemoveParams } from "./v2/ThreadAttachmentRemoveParams";
+import type { ThreadCompactStartParams } from "./v2/ThreadCompactStartParams";
+import type { ThreadDeleteParams } from "./v2/ThreadDeleteParams";
+import type { ThreadForkParams } from "./v2/ThreadForkParams";
+import type { ThreadGoalClearParams } from "./v2/ThreadGoalClearParams";
+import type { ThreadGoalGetParams } from "./v2/ThreadGoalGetParams";
+import type { ThreadGoalSetParams } from "./v2/ThreadGoalSetParams";
+import type { ThreadInjectItemsParams } from "./v2/ThreadInjectItemsParams";
+import type { ThreadItemsListParams } from "./v2/ThreadItemsListParams";
+import type { ThreadListParams } from "./v2/ThreadListParams";
+import type { ThreadLoadedListParams } from "./v2/ThreadLoadedListParams";
+import type { ThreadMetadataUpdateParams } from "./v2/ThreadMetadataUpdateParams";
+import type { ThreadReadParams } from "./v2/ThreadReadParams";
+import type { ThreadResumeParams } from "./v2/ThreadResumeParams";
+import type { ThreadRevertParams } from "./v2/ThreadRevertParams";
+import type { ThreadSectionCreateParams } from "./v2/ThreadSectionCreateParams";
+import type { ThreadSectionDeleteParams } from "./v2/ThreadSectionDeleteParams";
+import type { ThreadSectionListParams } from "./v2/ThreadSectionListParams";
+import type { ThreadSectionMoveParams } from "./v2/ThreadSectionMoveParams";
+import type { ThreadSectionUpdateParams } from "./v2/ThreadSectionUpdateParams";
+import type { ThreadSetNameParams } from "./v2/ThreadSetNameParams";
+import type { ThreadShellCommandParams } from "./v2/ThreadShellCommandParams";
+import type { ThreadStartParams } from "./v2/ThreadStartParams";
+import type { ThreadTurnsListParams } from "./v2/ThreadTurnsListParams";
+import type { ThreadUnarchiveParams } from "./v2/ThreadUnarchiveParams";
+import type { ThreadUnsubscribeParams } from "./v2/ThreadUnsubscribeParams";
+import type { TurnInterruptParams } from "./v2/TurnInterruptParams";
+import type { TurnStartParams } from "./v2/TurnStartParams";
+import type { TurnSteerParams } from "./v2/TurnSteerParams";
+import type { WindowsSandboxSetupStartParams } from "./v2/WindowsSandboxSetupStartParams";
+
+/**
+ * Request from the client to the server.
+ */
+export type ClientRequest ={ "method": "initialize", id: RequestId, params: InitializeParams, } | { "method": "thread/start", id: RequestId, params: ThreadStartParams, } | { "method": "thread/resume", id: RequestId, params: ThreadResumeParams, } | { "method": "thread/fork", id: RequestId, params: ThreadForkParams, } | { "method": "thread/archive", id: RequestId, params: ThreadArchiveParams, } | { "method": "thread/delete", id: RequestId, params: ThreadDeleteParams, } | { "method": "thread/unsubscribe", id: RequestId, params: ThreadUnsubscribeParams, } | { "method": "thread/name/set", id: RequestId, params: ThreadSetNameParams, } | { "method": "thread/goal/set", id: RequestId, params: ThreadGoalSetParams, } | { "method": "thread/goal/get", id: RequestId, params: ThreadGoalGetParams, } | { "method": "thread/goal/clear", id: RequestId, params: ThreadGoalClearParams, } | { "method": "thread/metadata/update", id: RequestId, params: ThreadMetadataUpdateParams, } | { "method": "thread/attachment/add", id: RequestId, params: ThreadAttachmentAddParams, } | { "method": "thread/attachment/list", id: RequestId, params: ThreadAttachmentListParams, } | { "method": "thread/attachment/remove", id: RequestId, params: ThreadAttachmentRemoveParams, } | { "method": "thread/section/move", id: RequestId, params: ThreadSectionMoveParams, } | { "method": "thread/unarchive", id: RequestId, params: ThreadUnarchiveParams, } | { "method": "thread/compact/start", id: RequestId, params: ThreadCompactStartParams, } | { "method": "thread/shellCommand", id: RequestId, params: ThreadShellCommandParams, } | { "method": "thread/approveGuardianDeniedAction", id: RequestId, params: ThreadApproveGuardianDeniedActionParams, } | { "method": "thread/revert", id: RequestId, params: ThreadRevertParams, } | { "method": "thread/list", id: RequestId, params: ThreadListParams, } | { "method": "threadSection/list", id: RequestId, params: ThreadSectionListParams, } | { "method": "threadSection/create", id: RequestId, params: ThreadSectionCreateParams, } | { "method": "threadSection/update", id: RequestId, params: ThreadSectionUpdateParams, } | { "method": "threadSection/delete", id: RequestId, params: ThreadSectionDeleteParams, } | { "method": "thread/loaded/list", id: RequestId, params: ThreadLoadedListParams, } | { "method": "thread/read", id: RequestId, params: ThreadReadParams, } | { "method": "thread/turns/list", id: RequestId, params: ThreadTurnsListParams, } | { "method": "thread/items/list", id: RequestId, params: ThreadItemsListParams, } | { "method": "thread/inject_items", id: RequestId, params: ThreadInjectItemsParams, } | { "method": "skills/list", id: RequestId, params: SkillsListParams, } | { "method": "skills/extraRoots/set", id: RequestId, params: SkillsExtraRootsSetParams, } | { "method": "hooks/list", id: RequestId, params: HooksListParams, } | { "method": "marketplace/add", id: RequestId, params: MarketplaceAddParams, } | { "method": "marketplace/remove", id: RequestId, params: MarketplaceRemoveParams, } | { "method": "marketplace/upgrade", id: RequestId, params: MarketplaceUpgradeParams, } | { "method": "plugin/list", id: RequestId, params: PluginListParams, } | { "method": "plugin/installed", id: RequestId, params: PluginInstalledParams, } | { "method": "plugin/reconcile", id: RequestId, params: PluginReconcileParams, } | { "method": "plugin/read", id: RequestId, params: PluginReadParams, } | { "method": "plugin/skill/read", id: RequestId, params: PluginSkillReadParams, } | { "method": "plugin/share/save", id: RequestId, params: PluginShareSaveParams, } | { "method": "plugin/share/updateTargets", id: RequestId, params: PluginShareUpdateTargetsParams, } | { "method": "plugin/share/list", id: RequestId, params: PluginShareListParams, } | { "method": "plugin/share/checkout", id: RequestId, params: PluginShareCheckoutParams, } | { "method": "plugin/share/delete", id: RequestId, params: PluginShareDeleteParams, } | { "method": "app/read", id: RequestId, params: AppsReadParams, } | { "method": "app/list", id: RequestId, params: AppsListParams, } | { "method": "app/installed", id: RequestId, params: AppsInstalledParams, } | { "method": "fs/readFile", id: RequestId, params: FsReadFileParams, } | { "method": "fs/writeFile", id: RequestId, params: FsWriteFileParams, } | { "method": "fs/createDirectory", id: RequestId, params: FsCreateDirectoryParams, } | { "method": "fs/getMetadata", id: RequestId, params: FsGetMetadataParams, } | { "method": "fs/readDirectory", id: RequestId, params: FsReadDirectoryParams, } | { "method": "fs/remove", id: RequestId, params: FsRemoveParams, } | { "method": "fs/copy", id: RequestId, params: FsCopyParams, } | { "method": "fs/watch", id: RequestId, params: FsWatchParams, } | { "method": "fs/unwatch", id: RequestId, params: FsUnwatchParams, } | { "method": "skills/config/write", id: RequestId, params: SkillsConfigWriteParams, } | { "method": "plugin/install", id: RequestId, params: PluginInstallParams, } | { "method": "plugin/uninstall", id: RequestId, params: PluginUninstallParams, } | { "method": "turn/start", id: RequestId, params: TurnStartParams, } | { "method": "turn/steer", id: RequestId, params: TurnSteerParams, } | { "method": "turn/interrupt", id: RequestId, params: TurnInterruptParams, } | { "method": "review/start", id: RequestId, params: ReviewStartParams, } | { "method": "model/list", id: RequestId, params: ModelListParams, } | { "method": "modelProvider/capabilities/read", id: RequestId, params: ModelProviderCapabilitiesReadParams, } | { "method": "experimentalFeature/list", id: RequestId, params: ExperimentalFeatureListParams, } | { "method": "permissionProfile/list", id: RequestId, params: PermissionProfileListParams, } | { "method": "experimentalFeature/enablement/set", id: RequestId, params: ExperimentalFeatureEnablementSetParams, } | { "method": "mcpServer/oauth/login", id: RequestId, params: McpServerOauthLoginParams, } | { "method": "config/mcpServer/reload", id: RequestId, params: undefined, } | { "method": "mcpServerStatus/list", id: RequestId, params: ListMcpServerStatusParams, } | { "method": "mcpServer/resource/read", id: RequestId, params: McpResourceReadParams, } | { "method": "mcpServer/tool/call", id: RequestId, params: McpServerToolCallParams, } | { "method": "windowsSandbox/setupStart", id: RequestId, params: WindowsSandboxSetupStartParams, } | { "method": "windowsSandbox/readiness", id: RequestId, params: undefined, } | { "method": "account/login/start", id: RequestId, params: LoginAccountParams, } | { "method": "account/login/cancel", id: RequestId, params: CancelLoginAccountParams, } | { "method": "account/logout", id: RequestId, params: undefined, } | { "method": "account/rateLimits/read", id: RequestId, params?: GetAccountRateLimitsParams | undefined, } | { "method": "account/rateLimitResetCredit/consume", id: RequestId, params: ConsumeAccountRateLimitResetCreditParams, } | { "method": "account/usage/read", id: RequestId, params?: GetAccountTokenUsageParams | undefined, } | { "method": "account/workspaceMessages/read", id: RequestId, params: undefined, } | { "method": "account/sendAddCreditsNudgeEmail", id: RequestId, params: SendAddCreditsNudgeEmailParams, } | { "method": "feedback/upload", id: RequestId, params: FeedbackUploadParams, } | { "method": "command/exec", id: RequestId, params: CommandExecParams, } | { "method": "command/exec/write", id: RequestId, params: CommandExecWriteParams, } | { "method": "command/exec/terminate", id: RequestId, params: CommandExecTerminateParams, } | { "method": "command/exec/resize", id: RequestId, params: CommandExecResizeParams, } | { "method": "config/read", id: RequestId, params: ConfigReadParams, } | { "method": "externalAgentConfig/detect", id: RequestId, params: ExternalAgentConfigDetectParams, } | { "method": "externalAgentConfig/import", id: RequestId, params: ExternalAgentConfigImportParams, } | { "method": "externalAgentConfig/import/recordHistory", id: RequestId, params: ExternalAgentConfigImportHistoryRecordParams, } | { "method": "externalAgentConfig/import/readHistories", id: RequestId, params: undefined, } | { "method": "config/value/write", id: RequestId, params: ConfigValueWriteParams, } | { "method": "config/batchWrite", id: RequestId, params: ConfigBatchWriteParams, } | { "method": "configRequirements/read", id: RequestId, params: undefined, } | { "method": "account/read", id: RequestId, params: GetAccountParams, } | { "method": "getConversationSummary", id: RequestId, params: GetConversationSummaryParams, } | { "method": "gitDiffToRemote", id: RequestId, params: GitDiffToRemoteParams, } | { "method": "getAuthStatus", id: RequestId, params: GetAuthStatusParams, } | { "method": "fuzzyFileSearch", id: RequestId, params: FuzzyFileSearchParams, };

codex-rs/app-server-protocol/schema/typescript/CodexResponseHandoffMode.ts

@@ -0,0 +1,5 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type CodexResponseHandoffMode = "thinking" | "commentary" | "bemTags";

codex-rs/app-server-protocol/schema/typescript/CollaborationMode.ts

@@ -0,0 +1,10 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { ModeKind } from "./ModeKind";
+import type { Settings } from "./Settings";
+
+/**
+ * Collaboration mode for a Codex session.
+ */
+export type CollaborationMode = { mode: ModeKind, settings: Settings, };

codex-rs/app-server-protocol/schema/typescript/ConfigurationReasoning.ts

@@ -0,0 +1,9 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { ReasoningEffort } from "./ReasoningEffort";
+
+/**
+ * Reasoning settings interpreted by the backend for the routed model.
+ */
+export type ConfigurationReasoning = { effort: ReasoningEffort, };

codex-rs/app-server-protocol/schema/typescript/ContentItem.ts

@@ -0,0 +1,6 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { ImageDetail } from "./ImageDetail";
+
+export type ContentItem = { "type": "input_text", text: string, } | { "type": "input_image", detail?: ImageDetail, } & ({ image_url: string, } | { file_id: string, }) | { "type": "input_audio", audio_url: string, } | { "type": "output_text", text: string, };

codex-rs/app-server-protocol/schema/typescript/ConversationGitInfo.ts

@@ -0,0 +1,5 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type ConversationGitInfo = { sha: string | null, branch: string | null, origin_url: string | null, };

codex-rs/app-server-protocol/schema/typescript/ConversationSummary.ts

@@ -0,0 +1,8 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { ConversationGitInfo } from "./ConversationGitInfo";
+import type { SessionSource } from "./SessionSource";
+import type { ThreadId } from "./ThreadId";
+
+export type ConversationSummary = { conversationId: ThreadId, path: string, preview: string, timestamp: string | null, updatedAt: string | null, modelProvider: string, cwd: string, cliVersion: string, source: SessionSource, gitInfo: ConversationGitInfo | null, };

codex-rs/app-server-protocol/schema/typescript/ConversationTextRole.ts

@@ -0,0 +1,5 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type ConversationTextRole = "user" | "developer" | "assistant";

codex-rs/app-server-protocol/schema/typescript/ExecCommandApprovalParams.ts

@@ -0,0 +1,16 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { ParsedCommand } from "./ParsedCommand";
+import type { ThreadId } from "./ThreadId";
+
+export type ExecCommandApprovalParams = { conversationId: ThreadId,
+/**
+ * Use to correlate this with [codex_protocol::protocol::ExecCommandBeginEvent]
+ * and [codex_protocol::protocol::ExecCommandEndEvent].
+ */
+callId: string,
+/**
+ * Identifier for this specific approval callback.
+ */
+approvalId: string | null, command: Array<string>, cwd: string, reason: string | null, parsedCmd: Array<ParsedCommand>, };

codex-rs/app-server-protocol/schema/typescript/ExecCommandApprovalResponse.ts

@@ -0,0 +1,6 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { ReviewDecision } from "./ReviewDecision";
+
+export type ExecCommandApprovalResponse = { decision: ReviewDecision, };

codex-rs/app-server-protocol/schema/typescript/ExecPolicyAmendment.ts

@@ -0,0 +1,12 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * Proposed execpolicy change to allow commands starting with this prefix.
+ *
+ * The `command` tokens form the prefix that would be added as an execpolicy
+ * `prefix_rule(..., decision="allow")`, letting the agent bypass approval for
+ * commands that start with this token sequence.
+ */
+export type ExecPolicyAmendment = Array<string>;

codex-rs/app-server-protocol/schema/typescript/FileChange.ts

@@ -0,0 +1,5 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type FileChange = { "type": "add", content: string, } | { "type": "delete", content: string, } | { "type": "update", unified_diff: string, move_path: string | null, };

codex-rs/app-server-protocol/schema/typescript/ForcedLoginMethod.ts

@@ -0,0 +1,5 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type ForcedLoginMethod = "chatgpt" | "api";

codex-rs/app-server-protocol/schema/typescript/FunctionCallOutputBody.ts

@@ -0,0 +1,6 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { FunctionCallOutputContentItem } from "./FunctionCallOutputContentItem";
+
+export type FunctionCallOutputBody = string | Array<FunctionCallOutputContentItem>;

codex-rs/app-server-protocol/schema/typescript/FunctionCallOutputContentItem.ts

@@ -0,0 +1,10 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { ImageDetail } from "./ImageDetail";
+
+/**
+ * Responses API compatible content items that can be returned by a tool call.
+ * This is a subset of ContentItem with the types we support as function call outputs.
+ */
+export type FunctionCallOutputContentItem = { "type": "input_text", text: string, } | { "type": "input_image", detail?: ImageDetail, } & ({ image_url: string, } | { file_id: string, }) | { "type": "input_audio", audio_url: string, } | { "type": "encrypted_content", encrypted_content: string, };

codex-rs/app-server-protocol/schema/typescript/FuzzyFileSearchMatchType.ts

@@ -0,0 +1,5 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type FuzzyFileSearchMatchType = "file" | "directory";

codex-rs/app-server-protocol/schema/typescript/FuzzyFileSearchParams.ts

@@ -0,0 +1,5 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type FuzzyFileSearchParams = { query: string, roots: Array<string>, cancellationToken: string | null, };

codex-rs/app-server-protocol/schema/typescript/FuzzyFileSearchResponse.ts

@@ -0,0 +1,6 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { FuzzyFileSearchResult } from "./FuzzyFileSearchResult";
+
+export type FuzzyFileSearchResponse = { files: Array<FuzzyFileSearchResult>, };

codex-rs/app-server-protocol/schema/typescript/FuzzyFileSearchResult.ts

@@ -0,0 +1,9 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { FuzzyFileSearchMatchType } from "./FuzzyFileSearchMatchType";
+
+/**
+ * Superset of [`codex_file_search::FileMatch`]
+ */
+export type FuzzyFileSearchResult = { root: string, path: string, match_type: FuzzyFileSearchMatchType, file_name: string, score: number, indices: Array<number> | null, };

codex-rs/app-server-protocol/schema/typescript/FuzzyFileSearchSessionCompletedNotification.ts

@@ -0,0 +1,5 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type FuzzyFileSearchSessionCompletedNotification = { sessionId: string, };

codex-rs/app-server-protocol/schema/typescript/FuzzyFileSearchSessionUpdatedNotification.ts

@@ -0,0 +1,6 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { FuzzyFileSearchResult } from "./FuzzyFileSearchResult";
+
+export type FuzzyFileSearchSessionUpdatedNotification = { sessionId: string, query: string, files: Array<FuzzyFileSearchResult>, };

codex-rs/app-server-protocol/schema/typescript/GetAuthStatusParams.ts

@@ -0,0 +1,5 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type GetAuthStatusParams = { includeToken: boolean | null, refreshToken: boolean | null, };

codex-rs/app-server-protocol/schema/typescript/GetAuthStatusResponse.ts

@@ -0,0 +1,6 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { AuthMode } from "./AuthMode";
+
+export type GetAuthStatusResponse = { authMethod: AuthMode | null, authToken: string | null, requiresOpenaiAuth: boolean | null, };

codex-rs/app-server-protocol/schema/typescript/GetConversationSummaryParams.ts

@@ -0,0 +1,6 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { ThreadId } from "./ThreadId";
+
+export type GetConversationSummaryParams = { rolloutPath: string, } | { conversationId: ThreadId, };