Move code mode behind an IPC host

Split the code-mode protocol and client from the V8-backed runtime so core and app-server no longer link codex-code-mode in production. ThreadManager now provisions durable code-mode sessions through a shared external host process, while tests can still inject the in-process provider. The IPC protocol uses a persistent stdin/stdout transport. Each frame is a 4-byte big-endian length followed by JSON, with a 16 MiB frame limit. Client requests carry u64 request IDs so create, execute, wait, terminate, and shutdown operations can be multiplexed over one process. Session IDs isolate durable stored values. Execute returns an ExecutionStarted response immediately and an asynchronous InitialResponse when the initial yield or completion is available. Nested tool calls and notifications travel from the host back to the client as delegate requests with their own IDs. Delegate responses, cancellation, and cell-closed lifecycle messages use the same framed channel. Wire operations encode errors as Result values. A dead connection fails pending operations, cancels outstanding delegates, and lets the provider spawn a new host for later sessions. Build codex-code-mode-host with V8 pointer-compression sandbox support and add it to canonical primary and app-server packages, legacy Linux and Windows bundles, signing verification, installers, Python runtime packages, and release CI for macOS, Linux, and Windows. The host is discovered next to the current executable, through CODEX_CODE_MODE_HOST_PATH, or on PATH. OS-level seccomp or seatbelt restrictions remain a follow-up to this cross-platform process split. Benchmarks were run from release builds on Linux x86_64 with the V8 sandbox profile and a text('ok') workload. Cold measurements used 30 samples, warm session provisioning used 200, and warm command execution used 500. Values are mean/p50/p95 in milliseconds: - session startup: in-process 0.002/0.002/0.005, IPC 2.623/2.599/2.894 - fresh-session command: in-process 1.831/1.758/1.915, IPC 7.428/7.252/8.306 - warm session provisioning: in-process 0.002/0.002/0.003, IPC 0.471/0.463/0.581 - warm command: in-process 1.759/1.757/1.940, IPC 2.005/2.001/2.166 The steady-state median command overhead is approximately 0.244 ms. The median fresh host plus first command cost is 7.252 ms. Validation: - 62/62 core code-mode integration tests passed against the external host - focused protocol, client, runtime, host, tools, and trace tests passed - Cargo and Bazel real-process host IPC tests passed - 11/11 package builder tests passed - Bazel lock verification, scoped Clippy fixes, and repository formatting passed
2026-11-03 19:53:25 +00:00 · 2026-06-10 14:38:41 -07:00
parent 9dd4e3c06e
commit ef500f4d23
69 changed files with 2304 additions and 445 deletions
@@ -0,0 +1,231 @@
+use std::path::PathBuf;
+use std::sync::Arc;
+use std::sync::atomic::AtomicBool;
+use std::sync::atomic::Ordering;
+
+use codex_code_mode_protocol::CellId;
+use codex_code_mode_protocol::CodeModeSession;
+use codex_code_mode_protocol::CodeModeSessionDelegate;
+use codex_code_mode_protocol::CodeModeSessionProvider;
+use codex_code_mode_protocol::CodeModeSessionProviderFuture;
+use codex_code_mode_protocol::CodeModeSessionResultFuture;
+use codex_code_mode_protocol::ExecuteRequest;
+use codex_code_mode_protocol::StartedCell;
+use codex_code_mode_protocol::WaitOutcome;
+use codex_code_mode_protocol::WaitRequest;
+use codex_code_mode_protocol::wire::HostRequest;
+use codex_code_mode_protocol::wire::HostResponse;
+use codex_code_mode_protocol::wire::SessionId;
+use tokio::sync::Semaphore;
+
+const CODE_MODE_HOST_PATH_ENV: &str = "CODEX_CODE_MODE_HOST_PATH";
+
+mod connection;
+
+use connection::Connection;
+
+#[derive(Clone, Debug)]
+pub struct CodeModeHostCommand {
+    pub program: PathBuf,
+    pub args: Vec<String>,
+}
+
+impl Default for CodeModeHostCommand {
+    fn default() -> Self {
+        Self {
+            program: default_host_program(),
+            args: Vec::new(),
+        }
+    }
+}
+
+pub struct IpcCodeModeSessionProvider {
+    command: CodeModeHostCommand,
+    connection: std::sync::Mutex<Option<Arc<Connection>>>,
+    spawn_permit: Semaphore,
+}
+
+impl Default for IpcCodeModeSessionProvider {
+    fn default() -> Self {
+        Self::new(CodeModeHostCommand::default())
+    }
+}
+
+impl IpcCodeModeSessionProvider {
+    pub fn new(command: CodeModeHostCommand) -> Self {
+        Self {
+            command,
+            connection: std::sync::Mutex::new(None),
+            spawn_permit: Semaphore::new(/*permits*/ 1),
+        }
+    }
+
+    async fn connection(&self) -> Result<Arc<Connection>, String> {
+        if let Some(connection) = {
+            let current = self
+                .connection
+                .lock()
+                .map_err(|_| "code-mode host connection lock poisoned".to_string())?;
+            current
+                .as_ref()
+                .filter(|connection| connection.is_alive())
+                .cloned()
+        } {
+            return Ok(connection);
+        }
+
+        let _spawn_permit = self
+            .spawn_permit
+            .acquire()
+            .await
+            .map_err(|_| "code-mode host spawn coordinator closed".to_string())?;
+        if let Some(connection) = {
+            let current = self
+                .connection
+                .lock()
+                .map_err(|_| "code-mode host connection lock poisoned".to_string())?;
+            current
+                .as_ref()
+                .filter(|connection| connection.is_alive())
+                .cloned()
+        } {
+            return Ok(connection);
+        }
+        let connection = Arc::new(Connection::spawn(&self.command).await?);
+        *self
+            .connection
+            .lock()
+            .map_err(|_| "code-mode host connection lock poisoned".to_string())? =
+            Some(Arc::clone(&connection));
+        Ok(connection)
+    }
+}
+
+impl CodeModeSessionProvider for IpcCodeModeSessionProvider {
+    fn create_session<'a>(
+        &'a self,
+        delegate: Arc<dyn CodeModeSessionDelegate>,
+    ) -> CodeModeSessionProviderFuture<'a> {
+        Box::pin(async move {
+            let connection = self.connection().await?;
+            let response = connection.request(HostRequest::CreateSession).await?;
+            let HostResponse::SessionCreated { session_id } = response else {
+                return Err(
+                    "code-mode host returned an invalid create-session response".to_string()
+                );
+            };
+            connection.register_delegate(session_id, delegate).await;
+            let session: Arc<dyn CodeModeSession> = Arc::new(IpcCodeModeSession {
+                connection,
+                session_id,
+                shutdown: AtomicBool::new(false),
+            });
+            Ok(session)
+        })
+    }
+}
+
+struct IpcCodeModeSession {
+    connection: Arc<Connection>,
+    session_id: SessionId,
+    shutdown: AtomicBool,
+}
+
+impl CodeModeSession for IpcCodeModeSession {
+    fn execute<'a>(
+        &'a self,
+        request: ExecuteRequest,
+    ) -> CodeModeSessionResultFuture<'a, StartedCell> {
+        Box::pin(async move {
+            self.ensure_active()?;
+            self.connection.execute(self.session_id, request).await
+        })
+    }
+
+    fn wait<'a>(&'a self, request: WaitRequest) -> CodeModeSessionResultFuture<'a, WaitOutcome> {
+        Box::pin(async move {
+            self.ensure_active()?;
+            let response = self
+                .connection
+                .request(HostRequest::Wait {
+                    session_id: self.session_id,
+                    request,
+                })
+                .await?;
+            match response {
+                HostResponse::WaitCompleted { outcome } => Ok(outcome),
+                _ => Err("code-mode host returned an invalid wait response".to_string()),
+            }
+        })
+    }
+
+    fn terminate<'a>(&'a self, cell_id: CellId) -> CodeModeSessionResultFuture<'a, WaitOutcome> {
+        Box::pin(async move {
+            self.ensure_active()?;
+            let response = self
+                .connection
+                .request(HostRequest::Terminate {
+                    session_id: self.session_id,
+                    cell_id,
+                })
+                .await?;
+            match response {
+                HostResponse::WaitCompleted { outcome } => Ok(outcome),
+                _ => Err("code-mode host returned an invalid terminate response".to_string()),
+            }
+        })
+    }
+
+    fn shutdown<'a>(&'a self) -> CodeModeSessionResultFuture<'a, ()> {
+        Box::pin(async move {
+            if self.shutdown.swap(true, Ordering::AcqRel) {
+                return Ok(());
+            }
+            let result = self
+                .connection
+                .request(HostRequest::ShutdownSession {
+                    session_id: self.session_id,
+                })
+                .await;
+            self.connection.remove_delegate(self.session_id).await;
+            match result? {
+                HostResponse::SessionShutdown => Ok(()),
+                _ => Err("code-mode host returned an invalid shutdown response".to_string()),
+            }
+        })
+    }
+}
+
+impl IpcCodeModeSession {
+    fn ensure_active(&self) -> Result<(), String> {
+        if self.shutdown.load(Ordering::Acquire) {
+            Err("code mode session is shutting down".to_string())
+        } else {
+            Ok(())
+        }
+    }
+}
+
+fn default_host_program() -> PathBuf {
+    if let Some(path) = std::env::var_os(CODE_MODE_HOST_PATH_ENV) {
+        return PathBuf::from(path);
+    }
+    let executable_name = if cfg!(windows) {
+        "codex-code-mode-host.exe"
+    } else {
+        "codex-code-mode-host"
+    };
+    if let Ok(current_exe) = std::env::current_exe()
+        && let Some(parent) = current_exe.parent()
+    {
+        let sibling = parent.join(executable_name);
+        if sibling.is_file() {
+            return sibling;
+        }
+    }
+    PathBuf::from(executable_name)
+}
+
+#[cfg(test)]
+#[path = "tests.rs"]
+mod tests;