From fef47a6769414444b1ce37aa8188b55bf2624f27 Mon Sep 17 00:00:00 2001 From: Charlie Marsh Date: Mon, 16 Nov 2026 16:09:24 +0000 Subject: [PATCH] Reuse code-mode tool catalogs across executions (#61846) ## Why Repeated executions with the same tools resend the full catalog and duplicate tool metadata. Catalog revisions let clients reuse an acknowledged catalog within a session. ## What changed - Negotiate catalog revision support over stdio and gRPC, retaining full requests for hosts without support. - Send tool definitions when installing a revision, then reference that revision for matching executions. Commit client catalog state only after execution admission succeeds; concurrent admissions can send full requests. - Keep immutable tool snapshots for each cell, reject invalid, unknown, or conflicting revisions, and share identical definitions and runtime metadata across sessions in the same process. ## Testing Add tests for acknowledged reuse, abandoned admissions, changed definitions, revision conflicts, session isolation, snapshot lifetimes, and shared metadata. GitOrigin-RevId: d2f29bf668bc2279715f5f1b7d24310923c57d33 --- .../src/grpc/conversions_tests.rs | 1 + codex-rs/code-mode-host/src/grpc/mod.rs | 3 +- .../code-mode-host/src/grpc/service_tests.rs | 1 + codex-rs/code-mode-host/src/grpc/session.rs | 1 + codex-rs/code-mode-host/src/host_tests.rs | 3 + codex-rs/code-mode-host/src/lib.rs | 7 +- codex-rs/code-mode-host/tests/grpc_timing.rs | 1 + .../src/grpc/codex.code_mode.v1.proto | 4 ++ .../code-mode-protocol/src/host/host_tests.rs | 1 + codex-rs/code-mode-protocol/src/host/mod.rs | 2 + .../code-mode-protocol/src/host/payload.rs | 4 ++ codex-rs/code-mode-protocol/src/lib.rs | 1 + .../code-mode-protocol/src/shared_catalog.rs | 70 +++++++++++++++++++ .../src/runtime/callbacks_tests.rs | 4 +- .../code-mode-runtime/src/runtime/globals.rs | 4 +- codex-rs/code-mode-runtime/src/service.rs | 55 +++++++++++++-- .../code-mode-runtime/src/service_tests.rs | 57 +++++++++++++++ .../src/session_runtime/types.rs | 4 +- .../src/grpc_session/callbacks_tests.rs | 1 + .../code-mode/src/grpc_session/conversion.rs | 1 + .../src/grpc_session/conversion_tests.rs | 1 + codex-rs/code-mode/src/grpc_session/mod.rs | 2 + .../code-mode/src/grpc_session/operations.rs | 19 ++++- .../code-mode/src/grpc_session/state_tests.rs | 1 + codex-rs/code-mode/src/lib.rs | 1 + codex-rs/code-mode/src/remote_session.rs | 28 +++++++- .../src/remote_session/connection.rs | 10 ++- .../connection/driver/commands.rs | 13 +--- .../remote_session/connection/driver/types.rs | 4 +- .../remote_session/connection/driver_tests.rs | 23 +++--- codex-rs/code-mode/src/tool_catalog.rs | 58 +++++++++++++++ codex-rs/code-mode/src/tool_catalog_tests.rs | 52 ++++++++++++++ 32 files changed, 394 insertions(+), 43 deletions(-) create mode 100644 codex-rs/code-mode-protocol/src/shared_catalog.rs create mode 100644 codex-rs/code-mode/src/tool_catalog.rs create mode 100644 codex-rs/code-mode/src/tool_catalog_tests.rs diff --git a/codex-rs/code-mode-host/src/grpc/conversions_tests.rs b/codex-rs/code-mode-host/src/grpc/conversions_tests.rs index 0a0441ec17..2df9610a16 100644 --- a/codex-rs/code-mode-host/src/grpc/conversions_tests.rs +++ b/codex-rs/code-mode-host/src/grpc/conversions_tests.rs @@ -25,6 +25,7 @@ fn rejects_missing_names_unknown_tool_kinds_and_invalid_json_schemas() { output_schema_json: None, }; let request = |definition| proto::ExecuteRequest { + catalog_revision: None, session_id: "session".to_string(), execution_id: "execution".to_string(), tool_call_id: "call".to_string(), diff --git a/codex-rs/code-mode-host/src/grpc/mod.rs b/codex-rs/code-mode-host/src/grpc/mod.rs index 600016b766..6996fa8282 100644 --- a/codex-rs/code-mode-host/src/grpc/mod.rs +++ b/codex-rs/code-mode-host/src/grpc/mod.rs @@ -219,6 +219,7 @@ impl GrpcCodeModeHost { validation::identifier(&request.execution_id, "execution ID")?; let request_permit = self.state.request_permit()?; let execution_id = request.execution_id.clone(); + let catalog_revision = request.catalog_revision; let request = conversions::execute_request(request)?; let cell_permit = self.state.cell_permit()?; let yield_signal = session.reserve_execution(&execution_id)?; @@ -230,7 +231,7 @@ impl GrpcCodeModeHost { _ = session.closed.cancelled() => { return Err(Status::cancelled("code-mode session is closed")); } - result = session.runtime.execute(request, Arc::new(delegate::GrpcDelegate::new(Arc::downgrade(&session))), Some(yield_signal)) => { + result = session.runtime.execute_with_catalog(request, catalog_revision, Arc::new(delegate::GrpcDelegate::new(Arc::downgrade(&session))), Some(yield_signal)) => { result.map_err(Status::failed_precondition)? } }; diff --git a/codex-rs/code-mode-host/src/grpc/service_tests.rs b/codex-rs/code-mode-host/src/grpc/service_tests.rs index 6407a4bf3f..b1a782d26a 100644 --- a/codex-rs/code-mode-host/src/grpc/service_tests.rs +++ b/codex-rs/code-mode-host/src/grpc/service_tests.rs @@ -99,6 +99,7 @@ pub(super) fn execute_request( source: &str, ) -> proto::ExecuteRequest { proto::ExecuteRequest { + catalog_revision: None, session_id: session_id.to_string(), execution_id: execution_id.to_string(), tool_call_id: "outer-call".to_string(), diff --git a/codex-rs/code-mode-host/src/grpc/session.rs b/codex-rs/code-mode-host/src/grpc/session.rs index 5e76337435..a66c366a0b 100644 --- a/codex-rs/code-mode-host/src/grpc/session.rs +++ b/codex-rs/code-mode-host/src/grpc/session.rs @@ -130,6 +130,7 @@ impl GrpcHostState { .try_send(Ok(proto::SessionEvent { event: Some(proto::session_event::Event::Opened(proto::SessionOpened { session_id: id.to_string(), + supports_catalog_revision: true, output_truncation: match session.runtime.output_truncation() { CodeModeOutputTruncation::Server => { Some(proto::OutputTruncation::Server.into()) diff --git a/codex-rs/code-mode-host/src/host_tests.rs b/codex-rs/code-mode-host/src/host_tests.rs index cf55ff9ce4..67b23b987d 100644 --- a/codex-rs/code-mode-host/src/host_tests.rs +++ b/codex-rs/code-mode-host/src/host_tests.rs @@ -31,6 +31,7 @@ use codex_code_mode_protocol::host::RequestId; use codex_code_mode_protocol::host::SESSION_RESOURCE_LIMITS_CAPABILITY; use codex_code_mode_protocol::host::SessionId; use codex_code_mode_protocol::host::SupportedProtocolVersions; +use codex_code_mode_protocol::host::TOOL_CATALOG_CAPABILITY; use codex_code_mode_protocol::host::WireContentItem; use codex_code_mode_protocol::host::WireExecuteRequest; use codex_code_mode_protocol::host::WireOutputTruncation; @@ -98,6 +99,7 @@ async fn decode_frame(frame: EncodedFrame) -> HostToClient { fn execute_request(source: &str) -> WireExecuteRequest { WireExecuteRequest { + catalog_revision: None, tool_call_id: "call-1".to_string(), enabled_tools: Vec::new(), source: source.to_string(), @@ -284,6 +286,7 @@ impl AsyncWrite for BlockingWriter { #[tokio::test] async fn supported_capabilities_are_negotiated_when_optional_or_required() { for capability in [ + TOOL_CATALOG_CAPABILITY, SESSION_RESOURCE_LIMITS_CAPABILITY, BOUNDED_OUTPUT_CAPABILITY, LARGE_DELEGATE_CAPACITY_CAPABILITY, diff --git a/codex-rs/code-mode-host/src/lib.rs b/codex-rs/code-mode-host/src/lib.rs index 28120949c8..77eb56d46f 100644 --- a/codex-rs/code-mode-host/src/lib.rs +++ b/codex-rs/code-mode-host/src/lib.rs @@ -36,6 +36,7 @@ use codex_code_mode_protocol::host::RequestId; use codex_code_mode_protocol::host::SESSION_RESOURCE_LIMITS_CAPABILITY; use codex_code_mode_protocol::host::SessionId; use codex_code_mode_protocol::host::SupportedProtocolVersions; +use codex_code_mode_protocol::host::TOOL_CATALOG_CAPABILITY; use codex_code_mode_protocol::host::WireWaitOutcome; use codex_code_mode_protocol::host::YIELD_OBSERVATION_CAPABILITY; use codex_code_mode_runtime::InProcessCodeModeSession; @@ -294,6 +295,7 @@ async fn negotiate( YIELD_OBSERVATION_CAPABILITY, BOUNDED_OUTPUT_CAPABILITY, LARGE_DELEGATE_CAPACITY_CAPABILITY, + TOOL_CATALOG_CAPABILITY, ] .into_iter() .map(Capability::new) @@ -451,6 +453,7 @@ impl HostState { self.respond(request_id, Err("code-mode request cancelled".to_string())); return; } + let catalog_revision = request.catalog_revision; let request = match request.try_into() { Ok(request) => request, Err(err) => { @@ -479,7 +482,9 @@ impl HostState { session_id.clone(), Arc::clone(&self.peer), )); - let result = session.execute(request, delegate, Some(yield_signal)).await; + let result = session + .execute_with_catalog(request, catalog_revision, delegate, Some(yield_signal)) + .await; match result { Ok(started) => { let cell_id = started.cell_id.clone(); diff --git a/codex-rs/code-mode-host/tests/grpc_timing.rs b/codex-rs/code-mode-host/tests/grpc_timing.rs index 057e4aab89..f96a8c6cd5 100644 --- a/codex-rs/code-mode-host/tests/grpc_timing.rs +++ b/codex-rs/code-mode-host/tests/grpc_timing.rs @@ -58,6 +58,7 @@ async fn execution_timing_includes_javascript_but_excludes_delayed_reads() -> Re let observed = Instant::now(); let mut execution = client .execute(grpc::ExecuteRequest { + catalog_revision: None, session_id: opened.session_id.clone(), execution_id: format!("execution-{index}"), tool_call_id: format!("call-{index}"), diff --git a/codex-rs/code-mode-protocol/src/grpc/codex.code_mode.v1.proto b/codex-rs/code-mode-protocol/src/grpc/codex.code_mode.v1.proto index 0cf339a0d9..acf1b72658 100644 --- a/codex-rs/code-mode-protocol/src/grpc/codex.code_mode.v1.proto +++ b/codex-rs/code-mode-protocol/src/grpc/codex.code_mode.v1.proto @@ -95,6 +95,8 @@ message SessionOpened { string session_id = 1; // Absent (including from an older host) means the client owns truncation. optional OutputTruncation output_truncation = 2; + // Clients may send ExecuteRequest.catalog_revision when advertised. + bool supports_catalog_revision = 3; } message CloseSessionRequest { @@ -202,6 +204,8 @@ message ExecuteRequest { repeated ToolDefinition enabled_tools = 5; optional uint64 yield_time_ms = 6; optional uint64 max_output_tokens = 7; + // Nonempty enabled_tools installs a session-local revision. Empty references it. + optional uint64 catalog_revision = 8; } message ExecuteEvent { diff --git a/codex-rs/code-mode-protocol/src/host/host_tests.rs b/codex-rs/code-mode-protocol/src/host/host_tests.rs index 47ae5907d1..4167970dbe 100644 --- a/codex-rs/code-mode-protocol/src/host/host_tests.rs +++ b/codex-rs/code-mode-protocol/src/host/host_tests.rs @@ -77,6 +77,7 @@ where fn execute_request() -> WireExecuteRequest { WireExecuteRequest { + catalog_revision: None, tool_call_id: "call-1".to_string(), enabled_tools: vec![ WireToolDefinition { diff --git a/codex-rs/code-mode-protocol/src/host/mod.rs b/codex-rs/code-mode-protocol/src/host/mod.rs index 817f11dba4..98cd26f6e3 100644 --- a/codex-rs/code-mode-protocol/src/host/mod.rs +++ b/codex-rs/code-mode-protocol/src/host/mod.rs @@ -21,6 +21,8 @@ pub const LARGE_DELEGATE_CAPACITY_CAPABILITY: &str = "delegate-capacity-4096"; /// Stdio connection support for the optional `session/open.outputTruncation` field. /// Each session selects its own setting after the connection hello. pub const BOUNDED_OUTPUT_CAPABILITY: &str = "bounded-output-v1"; +/// Session-local catalog revisions on execute requests. +pub const TOOL_CATALOG_CAPABILITY: &str = "tool-catalog-revision-v1"; /// Maximum aggregate text bytes retained per server-truncated observation. pub const BOUNDED_OUTPUT_MAX_BYTES: usize = 1024 * 1024; diff --git a/codex-rs/code-mode-protocol/src/host/payload.rs b/codex-rs/code-mode-protocol/src/host/payload.rs index 53bbabb2be..e134946dae 100644 --- a/codex-rs/code-mode-protocol/src/host/payload.rs +++ b/codex-rs/code-mode-protocol/src/host/payload.rs @@ -203,6 +203,9 @@ impl From for ToolDefinition { #[derive(Clone, Debug, Deserialize, PartialEq, Serialize)] #[serde(deny_unknown_fields)] pub struct WireExecuteRequest { + /// A nonempty catalog installs this revision. An empty list references it. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub catalog_revision: Option, pub tool_call_id: String, pub enabled_tools: Vec, pub source: String, @@ -215,6 +218,7 @@ impl TryFrom for WireExecuteRequest { fn try_from(value: ExecuteRequest) -> Result { Ok(Self { + catalog_revision: None, tool_call_id: value.tool_call_id, enabled_tools: value.enabled_tools.into_iter().map(Into::into).collect(), source: value.source, diff --git a/codex-rs/code-mode-protocol/src/lib.rs b/codex-rs/code-mode-protocol/src/lib.rs index 81d9c0ae84..818e932535 100644 --- a/codex-rs/code-mode-protocol/src/lib.rs +++ b/codex-rs/code-mode-protocol/src/lib.rs @@ -6,6 +6,7 @@ mod process_metrics; mod response; mod runtime; mod session; +mod shared_catalog; pub use description::CODE_MODE_PRAGMA_PREFIX; pub use description::CodeModeToolKind; diff --git a/codex-rs/code-mode-protocol/src/shared_catalog.rs b/codex-rs/code-mode-protocol/src/shared_catalog.rs new file mode 100644 index 0000000000..352c0f6e67 --- /dev/null +++ b/codex-rs/code-mode-protocol/src/shared_catalog.rs @@ -0,0 +1,70 @@ +//! Shares immutable tool definitions across sessions in the same process. Each session +//! negotiates its own revision and owns its snapshot independently. + +use std::borrow::Cow; +use std::collections::HashMap; +use std::hash::BuildHasher; +use std::hash::RandomState; +use std::sync::Arc; +use std::sync::LazyLock; +use std::sync::Mutex; +use std::sync::PoisonError; +use std::sync::Weak; + +use codex_protocol::ToolName; + +use crate::EnabledToolMetadata; +use crate::ToolDefinition; + +type ToolIndex = LazyLock>>>>; + +impl ToolDefinition { + /// Shares matching definitions while preserving the client's catalog order. + pub fn shared_catalog(tools: &[Self]) -> Vec> { + static INDEX: ToolIndex = LazyLock::new(Mutex::default); + share(&INDEX, tools.iter().map(Cow::Borrowed), |tool| { + &tool.tool_name + }) + } +} + +impl EnabledToolMetadata { + /// Shares matching runtime metadata while preserving the cell's callback indices. + pub fn shared_catalog(tools: Vec) -> Vec> { + static INDEX: ToolIndex = LazyLock::new(Mutex::default); + share(&INDEX, tools.into_iter().map(Cow::Owned), |tool| { + &tool.tool_name + }) + } +} + +fn share<'a, T: 'a + Clone + PartialEq>( + index: &ToolIndex, + tools: impl Iterator>, + name: impl Fn(&T) -> &ToolName, +) -> Vec> { + static HASHER: LazyLock = LazyLock::new(RandomState::new); + let mut index = index.lock().unwrap_or_else(PoisonError::into_inner); + tools + .map(|tool| { + // Hash only the name. Versions of the same tool share a bucket, and + // exact equality checks the descriptions, schemas and other fields. + let hash = HASHER.hash_one(name(&tool)); + if index.len() == index.capacity() && !index.contains_key(&hash) { + index.retain(|_, versions| versions.iter().any(|tool| tool.strong_count() > 0)); + } + let versions = index.entry(hash).or_default(); + if let Some(existing) = versions + .iter() + .filter_map(Weak::upgrade) + .find(|existing| existing.as_ref() == tool.as_ref()) + { + return existing; + } + versions.retain(|tool| tool.strong_count() > 0); + let shared = Arc::new(tool.into_owned()); + versions.push(Arc::downgrade(&shared)); + shared + }) + .collect() +} diff --git a/codex-rs/code-mode-runtime/src/runtime/callbacks_tests.rs b/codex-rs/code-mode-runtime/src/runtime/callbacks_tests.rs index 0ea486dcf5..5ae16de4c6 100644 --- a/codex-rs/code-mode-runtime/src/runtime/callbacks_tests.rs +++ b/codex-rs/code-mode-runtime/src/runtime/callbacks_tests.rs @@ -113,12 +113,12 @@ clearTimeout(earlyTimer); setTimeout(() => {}, 60000); pending_timeouts: HashMap::new(), stored_values: HashMap::new(), stored_value_writes: HashMap::new(), - enabled_tools: Arc::from([EnabledToolMetadata { + enabled_tools: Arc::from([Arc::new(EnabledToolMetadata { global_name: "echo".into(), description: String::new(), tool_name, kind: CodeModeToolKind::Function, - }]), + })]), next_tool_call_id: 1, next_timeout_id: 1, tool_call_id: "cell".to_string(), diff --git a/codex-rs/code-mode-runtime/src/runtime/globals.rs b/codex-rs/code-mode-runtime/src/runtime/globals.rs index 66c09bdfdc..2a8118771f 100644 --- a/codex-rs/code-mode-runtime/src/runtime/globals.rs +++ b/codex-rs/code-mode-runtime/src/runtime/globals.rs @@ -89,7 +89,7 @@ fn catalog_global( fn build_tools_object<'s>( scope: &mut v8::PinScope<'s, '_>, - enabled_tools: &[EnabledToolMetadata], + enabled_tools: &[Arc], ) -> Result, String> { let prototype = v8::Object::new(scope) .get_prototype(scope) @@ -111,7 +111,7 @@ fn build_tools_object<'s>( fn build_all_tools_value<'s>( scope: &mut v8::PinScope<'s, '_>, - enabled_tools: &[EnabledToolMetadata], + enabled_tools: &[Arc], ) -> Result, String> { let mut items = Vec::with_capacity(enabled_tools.len()); let name_key = v8::String::new(scope, "name") diff --git a/codex-rs/code-mode-runtime/src/service.rs b/codex-rs/code-mode-runtime/src/service.rs index 7da6e98e8c..7704d179d1 100644 --- a/codex-rs/code-mode-runtime/src/service.rs +++ b/codex-rs/code-mode-runtime/src/service.rs @@ -1,6 +1,8 @@ use codex_code_mode_protocol::EnabledToolMetadata; use codex_code_mode_protocol::normalize_code_mode_identifier; use std::sync::Arc; +use std::sync::Mutex; +use std::sync::PoisonError; use std::time::Duration; use codex_code_mode_protocol::CellId; @@ -38,6 +40,7 @@ const MIN_YIELD_TIME_FOR_GRACE: Duration = Duration::from_secs(10); pub struct InProcessCodeModeSession { runtime: SessionRuntime, + catalog: Mutex<(u64, runtime::ToolCatalog)>, options: CodeModeSessionOptions, } @@ -64,6 +67,7 @@ impl InProcessCodeModeSession { ) -> Self { Self { runtime: SessionRuntime::new_with_task_failure_handler(task_failure_handler), + catalog: Default::default(), options: CodeModeSessionOptions { cell_execution_limits: CodeModeSessionCellExecutionLimits { max_heap_size_bytes: None, @@ -74,8 +78,12 @@ impl InProcessCodeModeSession { } } - fn runtime_request(&self, request: ExecuteRequest) -> runtime::CreateCellRequest { - let tools = request + fn runtime_request( + &self, + request: ExecuteRequest, + revision: Option, + ) -> Result { + let tools: Vec = request .enabled_tools .into_iter() .map(|tool| EnabledToolMetadata { @@ -85,12 +93,34 @@ impl InProcessCodeModeSession { kind: tool.kind, }) .collect(); - runtime::CreateCellRequest { + let mut tools: runtime::ToolCatalog = if revision.is_some() && !tools.is_empty() { + EnabledToolMetadata::shared_catalog(tools).into() + } else { + tools.into_iter().map(Arc::new).collect() + }; + if let Some(revision) = revision { + let mut cache = self.catalog.lock().unwrap_or_else(PoisonError::into_inner); + if revision == 0 { + return Err("invalid code-mode catalog revision".into()); + } + if tools.is_empty() { + if revision != cache.0 { + return Err("unknown code-mode catalog revision".into()); + } + tools = Arc::clone(&cache.1); + } else if revision > cache.0 { + *cache = (revision, Arc::clone(&tools)); + } else if revision == cache.0 && tools != cache.1 { + return Err("conflicting code-mode catalog revision".into()); + } + // A late full request runs with its own tools after cancellation. + } + Ok(runtime::CreateCellRequest { output_truncation: self.options.output_truncation, tool_call_id: request.tool_call_id, enabled_tools: tools, source: request.source, - } + }) } pub async fn execute( @@ -98,6 +128,19 @@ impl InProcessCodeModeSession { request: ExecuteRequest, delegate: Arc, preempt: Option, + ) -> Result { + self.execute_with_catalog(request, /*catalog_revision*/ None, delegate, preempt) + .await + } + + /// A nonempty catalog installs a session-local revision. Subsequent cells + /// retain that immutable snapshot while newer revisions can change the tools. + pub async fn execute_with_catalog( + &self, + request: ExecuteRequest, + catalog_revision: Option, + delegate: Arc, + preempt: Option, ) -> Result { let yield_time_ms = request.yield_time_ms.unwrap_or(DEFAULT_EXEC_YIELD_TIME_MS); let max_output_tokens = request.max_output_tokens; @@ -105,7 +148,7 @@ impl InProcessCodeModeSession { let started = self .runtime .execute( - self.runtime_request(request), + self.runtime_request(request, catalog_revision)?, runtime::ObserveMode::YieldAfter(self.resolve_yield_timeout(yield_time_ms)) .with_yield_signal(preempt.unwrap_or_default()), Arc::new(ProtocolDelegate { delegate }), @@ -142,7 +185,7 @@ impl InProcessCodeModeSession { let started = self .runtime .execute( - self.runtime_request(request), + self.runtime_request(request, /*revision*/ None)?, runtime::ObserveMode::PendingFrontier, Arc::new(ProtocolDelegate { delegate }), ) diff --git a/codex-rs/code-mode-runtime/src/service_tests.rs b/codex-rs/code-mode-runtime/src/service_tests.rs index 3e1b714618..7f445ed025 100644 --- a/codex-rs/code-mode-runtime/src/service_tests.rs +++ b/codex-rs/code-mode-runtime/src/service_tests.rs @@ -547,6 +547,63 @@ fn echo_tool() -> ToolDefinition { } } +#[test] +fn catalog_revisions_freeze_each_cells_tools_and_isolate_sessions() { + let service = InProcessCodeModeSession::new(); + let register = |service: &InProcessCodeModeSession, revision, description: &str| { + let mut request = execute_request(""); + request.enabled_tools = vec![ToolDefinition { + description: description.to_string(), + ..echo_tool() + }]; + service.runtime_request(request, Some(revision)) + }; + let first = register(&service, 1, "first").unwrap(); + let hit = service + .runtime_request(execute_request(""), Some(1)) + .unwrap(); + assert!(Arc::ptr_eq(&first.enabled_tools, &hit.enabled_tools)); + let second = register(&service, 2, "second").unwrap(); + let late = register(&service, 1, "late").unwrap(); + assert_eq!(late.enabled_tools[0].description, "late"); + assert_eq!(first.enabled_tools[0].description, "first"); + assert!(register(&service, 2, "conflict").is_err()); + assert!( + service + .runtime_request(execute_request(""), Some(1)) + .is_err() + ); + let hit = service + .runtime_request(execute_request(""), Some(2)) + .unwrap(); + assert!(Arc::ptr_eq(&second.enabled_tools, &hit.enabled_tools)); + let other = InProcessCodeModeSession::new(); + assert!(other.runtime_request(execute_request(""), Some(2)).is_err()); + let shared = register(&other, 1, "second").unwrap(); + assert!(Arc::ptr_eq( + &second.enabled_tools[0], + &shared.enabled_tools[0] + )); + assert!(other.runtime_request(execute_request(""), Some(2)).is_err()); + let distinct = register(&other, 2, "distinct").unwrap(); + assert!(!Arc::ptr_eq( + &second.enabled_tools[0], + &distinct.enabled_tools[0] + )); + let weak = Arc::downgrade(&distinct.enabled_tools[0]); + drop(other); + assert!(weak.upgrade().is_some()); + drop(distinct); + assert!(weak.upgrade().is_none()); + assert!( + service + .runtime_request(execute_request(""), /*revision*/ None) + .unwrap() + .enabled_tools + .is_empty() + ); +} + async fn execute(service: &InProcessCodeModeSession, request: ExecuteRequest) -> RuntimeResponse { service .execute( diff --git a/codex-rs/code-mode-runtime/src/session_runtime/types.rs b/codex-rs/code-mode-runtime/src/session_runtime/types.rs index cadc33d7f4..40d80a08de 100644 --- a/codex-rs/code-mode-runtime/src/session_runtime/types.rs +++ b/codex-rs/code-mode-runtime/src/session_runtime/types.rs @@ -80,8 +80,8 @@ pub(crate) enum CellEvent { }, } -/// Tool metadata in callback slot order for the lifetime of a cell. -pub(crate) type ToolCatalog = Arc<[codex_code_mode_protocol::EnabledToolMetadata]>; +/// Ordered callback slots frozen for a cell. Sessions can share individual tool definitions. +pub(crate) type ToolCatalog = Arc<[Arc]>; /// Transport-neutral input for creating a cell. /// diff --git a/codex-rs/code-mode/src/grpc_session/callbacks_tests.rs b/codex-rs/code-mode/src/grpc_session/callbacks_tests.rs index 5d4475b0df..c88d150156 100644 --- a/codex-rs/code-mode/src/grpc_session/callbacks_tests.rs +++ b/codex-rs/code-mode/src/grpc_session/callbacks_tests.rs @@ -73,6 +73,7 @@ async fn tool_call_heartbeats_do_not_enter_callback_admission() { fn session(client: GrpcClient) -> Arc { let client = Arc::new(client); Arc::new(SessionInner { + catalog: None, id: "session".to_string(), output_truncation: CodeModeOutputTruncation::Client, route: None, diff --git a/codex-rs/code-mode/src/grpc_session/conversion.rs b/codex-rs/code-mode/src/grpc_session/conversion.rs index 4120a8b1df..d5a22618d6 100644 --- a/codex-rs/code-mode/src/grpc_session/conversion.rs +++ b/codex-rs/code-mode/src/grpc_session/conversion.rs @@ -32,6 +32,7 @@ pub(super) fn execute_request( request: ExecuteRequest, ) -> Result { Ok(grpc::ExecuteRequest { + catalog_revision: None, session_id: session_id.to_string(), execution_id, tool_call_id: request.tool_call_id, diff --git a/codex-rs/code-mode/src/grpc_session/conversion_tests.rs b/codex-rs/code-mode/src/grpc_session/conversion_tests.rs index c9fbb9f4c1..a7ba49e291 100644 --- a/codex-rs/code-mode/src/grpc_session/conversion_tests.rs +++ b/codex-rs/code-mode/src/grpc_session/conversion_tests.rs @@ -39,6 +39,7 @@ fn execute_request_preserves_tool_schemas_namespaces_and_limits() { assert_eq!( execute_request("session", "execution".to_string(), request), Ok(grpc::ExecuteRequest { + catalog_revision: None, session_id: "session".to_string(), execution_id: "execution".to_string(), tool_call_id: "outer".to_string(), diff --git a/codex-rs/code-mode/src/grpc_session/mod.rs b/codex-rs/code-mode/src/grpc_session/mod.rs index c76a7594f3..07ddf4c8cf 100644 --- a/codex-rs/code-mode/src/grpc_session/mod.rs +++ b/codex-rs/code-mode/src/grpc_session/mod.rs @@ -267,6 +267,7 @@ impl GrpcCodeModeSessionProvider { } let inner = Arc::new(SessionInner { + catalog: opened.supports_catalog_revision.then(Default::default), id: opened.session_id, output_truncation, route, @@ -409,6 +410,7 @@ impl Drop for GrpcCodeModeSession { } pub(super) struct SessionInner { + catalog: Option>>, pub(super) id: String, output_truncation: CodeModeOutputTruncation, // Affinity belongs to the session: parents and children may share a transport diff --git a/codex-rs/code-mode/src/grpc_session/operations.rs b/codex-rs/code-mode/src/grpc_session/operations.rs index 5b60d0434a..5da2713574 100644 --- a/codex-rs/code-mode/src/grpc_session/operations.rs +++ b/codex-rs/code-mode/src/grpc_session/operations.rs @@ -84,11 +84,20 @@ impl SessionInner { call_id = %request.tool_call_id, ); let trace = codex_otel::span_w3c_trace_context(&execute_span); - let request = conversion::execute_request(&self.id, execution_id.clone(), request)?; + let admission = self.catalog.as_ref().and_then(|cache| { + crate::tool_catalog::CatalogAdmission::prepare(cache, &request.enabled_tools) + }); + let mut request = conversion::execute_request(&self.id, execution_id.clone(), request)?; self.state .lock() .unwrap_or_else(PoisonError::into_inner) .begin_execution(&request, delegate)?; + if let Some(admission) = &admission { + request.catalog_revision = Some(admission.revision()); + if admission.reuses_catalog() { + request.enabled_tools.clear(); + } + } let ownership = ExecutionOwnership { session: Arc::clone(self), execution_id: execution_id.clone(), @@ -108,9 +117,13 @@ impl SessionInner { .instrument(execute_span) .await; }); - started_rx + let started = started_rx .await - .map_err(|_| "gRPC code-mode execution driver ended unexpectedly".to_string())? + .map_err(|_| "gRPC code-mode execution driver ended unexpectedly".to_string())??; + if let Some(admission) = admission { + admission.accepted(); + } + Ok(started) } async fn drive_execution( diff --git a/codex-rs/code-mode/src/grpc_session/state_tests.rs b/codex-rs/code-mode/src/grpc_session/state_tests.rs index 1646bd6c65..3df693477e 100644 --- a/codex-rs/code-mode/src/grpc_session/state_tests.rs +++ b/codex-rs/code-mode/src/grpc_session/state_tests.rs @@ -11,6 +11,7 @@ use super::SessionState; fn request(execution_id: &str) -> grpc::ExecuteRequest { grpc::ExecuteRequest { + catalog_revision: None, session_id: "session".to_string(), execution_id: execution_id.to_string(), tool_call_id: "call".to_string(), diff --git a/codex-rs/code-mode/src/lib.rs b/codex-rs/code-mode/src/lib.rs index 9ad685a48c..c3889cdd5a 100644 --- a/codex-rs/code-mode/src/lib.rs +++ b/codex-rs/code-mode/src/lib.rs @@ -1,5 +1,6 @@ mod grpc_session; mod remote_session; +mod tool_catalog; pub use codex_code_mode_protocol::*; pub use grpc_session::GrpcCodeModeSessionProvider; diff --git a/codex-rs/code-mode/src/remote_session.rs b/codex-rs/code-mode/src/remote_session.rs index 55aa16c601..c4366fc362 100644 --- a/codex-rs/code-mode/src/remote_session.rs +++ b/codex-rs/code-mode/src/remote_session.rs @@ -21,11 +21,15 @@ use codex_code_mode_protocol::TerminateRequest; use codex_code_mode_protocol::WaitOutcome; use codex_code_mode_protocol::WaitRequest; use codex_code_mode_protocol::host::SessionId; +use codex_code_mode_protocol::host::TOOL_CATALOG_CAPABILITY; +use codex_code_mode_protocol::host::WireExecuteRequest; use codex_install_context::InstallContext; use tokio::sync::Semaphore; use tokio::sync::watch; use tokio_util::sync::CancellationToken; +use crate::tool_catalog::CatalogAdmission; + use self::connection::Connection; use self::connection::ConnectionError; use self::connection::RemoteSession; @@ -224,6 +228,7 @@ enum SessionState { #[derive(Clone)] struct SessionBinding { + catalog: Arc>, connection: Arc, remote: RemoteSession, cleanup: SessionCleanup, @@ -292,10 +297,28 @@ impl ProcessOwnedCodeModeSession { request.max_output_tokens = self .server_output_budget(request.max_output_tokens) .map(|tokens| tokens.min(i32::MAX as usize)); - binding + let admission = binding + .connection + .supports(TOOL_CATALOG_CAPABILITY) + .then(|| CatalogAdmission::prepare(&binding.catalog, &request.enabled_tools)) + .flatten(); + if admission + .as_ref() + .is_some_and(CatalogAdmission::reuses_catalog) + { + request.enabled_tools.clear(); + } + let mut request = WireExecuteRequest::try_from(request) + .map_err(|error| format!("failed to encode code-mode execute request: {error}"))?; + request.catalog_revision = admission.as_ref().map(CatalogAdmission::revision); + let started = binding .connection .execute(binding.remote, request, delegate, preempt) - .await + .await?; + if let Some(admission) = admission { + admission.accepted(); + } + Ok(started) } pub async fn wait( @@ -382,6 +405,7 @@ impl SessionInner { ) .await; cleanup.map(|cleanup| SessionBinding { + catalog: Default::default(), connection, remote: remote.clone(), cleanup, diff --git a/codex-rs/code-mode/src/remote_session/connection.rs b/codex-rs/code-mode/src/remote_session/connection.rs index 6b59d07cdb..ec728b7451 100644 --- a/codex-rs/code-mode/src/remote_session/connection.rs +++ b/codex-rs/code-mode/src/remote_session/connection.rs @@ -14,7 +14,6 @@ use codex_code_mode_protocol::CodeModeOutputTruncation; use codex_code_mode_protocol::CodeModeSessionCellExecutionLimits; use codex_code_mode_protocol::CodeModeSessionDelegate; use codex_code_mode_protocol::CodeModeSessionOptions; -use codex_code_mode_protocol::ExecuteRequest; use codex_code_mode_protocol::StartedCell; use codex_code_mode_protocol::TerminateRequest; use codex_code_mode_protocol::WaitOutcome; @@ -34,6 +33,8 @@ use codex_code_mode_protocol::host::ProtocolVersion; use codex_code_mode_protocol::host::RequestId; use codex_code_mode_protocol::host::SESSION_RESOURCE_LIMITS_CAPABILITY; use codex_code_mode_protocol::host::SupportedProtocolVersions; +use codex_code_mode_protocol::host::TOOL_CATALOG_CAPABILITY; +use codex_code_mode_protocol::host::WireExecuteRequest; use codex_code_mode_protocol::host::YIELD_OBSERVATION_CAPABILITY; use codex_protocol::shell_environment::scrub_non_inheritable_env_vars; use tokio::io::AsyncBufReadExt; @@ -220,11 +221,14 @@ impl Connection { Capability::new(BOUNDED_OUTPUT_CAPABILITY).map_err(|error| error.to_string())?; let delegate_capacity = Capability::new(LARGE_DELEGATE_CAPACITY_CAPABILITY) .map_err(|error| error.to_string())?; + let catalog_capability = + Capability::new(TOOL_CATALOG_CAPABILITY).map_err(|error| error.to_string())?; let optional_capabilities = CapabilitySet::try_new([ session_limits_capability, yield_capability, output_capability, delegate_capacity, + catalog_capability, ]) .map_err(|error| error.to_string())?; let hello = ClientHello::new( @@ -341,7 +345,7 @@ impl Connection { self.alive.load(Ordering::Acquire) } - fn supports(&self, capability: &str) -> bool { + pub(super) fn supports(&self, capability: &str) -> bool { self.capabilities .iter() .any(|value| value.as_str() == capability) @@ -392,7 +396,7 @@ impl Connection { pub(super) async fn execute( &self, session: RemoteSession, - request: ExecuteRequest, + request: WireExecuteRequest, delegate: Arc, yield_signal: Option, ) -> Result { diff --git a/codex-rs/code-mode/src/remote_session/connection/driver/commands.rs b/codex-rs/code-mode/src/remote_session/connection/driver/commands.rs index bc76df8fdb..2e83c5bd3b 100644 --- a/codex-rs/code-mode/src/remote_session/connection/driver/commands.rs +++ b/codex-rs/code-mode/src/remote_session/connection/driver/commands.rs @@ -3,13 +3,13 @@ use std::sync::Arc; use codex_code_mode_protocol::CodeModeOutputTruncation; use codex_code_mode_protocol::CodeModeSessionDelegate; use codex_code_mode_protocol::CodeModeSessionOptions; -use codex_code_mode_protocol::ExecuteRequest; use codex_code_mode_protocol::TerminateRequest; use codex_code_mode_protocol::WaitOutcome; use codex_code_mode_protocol::WaitRequest; use codex_code_mode_protocol::host::ClientToHost; use codex_code_mode_protocol::host::EncodedFrame; use codex_code_mode_protocol::host::HostRequest; +use codex_code_mode_protocol::host::WireExecuteRequest; use codex_code_mode_protocol::host::WireOutputTruncation; use codex_code_mode_protocol::host::WireSessionCellExecutionLimits; use codex_code_mode_protocol::host::WireWaitRequest; @@ -144,7 +144,7 @@ impl ConnectionDriver { fn execute( &mut self, session: RemoteSession, - request: ExecuteRequest, + request: WireExecuteRequest, delegate: Arc, caller_cancellation: CancellationToken, yield_signal: Option, @@ -154,15 +154,6 @@ impl ConnectionDriver { let _ = response_tx.send(Err(err)); return true; } - let request = match request.try_into() { - Ok(request) => request, - Err(err) => { - let _ = response_tx.send(Err(format!( - "failed to encode code-mode execute request: {err}" - ))); - return true; - } - }; let request_id = match self.requests.allocate_id() { Ok(id) => id, Err(err) => { diff --git a/codex-rs/code-mode/src/remote_session/connection/driver/types.rs b/codex-rs/code-mode/src/remote_session/connection/driver/types.rs index b1bc8862c1..796165f747 100644 --- a/codex-rs/code-mode/src/remote_session/connection/driver/types.rs +++ b/codex-rs/code-mode/src/remote_session/connection/driver/types.rs @@ -2,7 +2,6 @@ use std::sync::Arc; use codex_code_mode_protocol::CodeModeSessionDelegate; use codex_code_mode_protocol::CodeModeSessionOptions; -use codex_code_mode_protocol::ExecuteRequest; use codex_code_mode_protocol::RuntimeResponse; use codex_code_mode_protocol::StartedCell; use codex_code_mode_protocol::TerminateRequest; @@ -14,6 +13,7 @@ use codex_code_mode_protocol::host::HostToClient; use codex_code_mode_protocol::host::RequestId; use codex_code_mode_protocol::host::SessionId; use codex_code_mode_protocol::host::WireCellId; +use codex_code_mode_protocol::host::WireExecuteRequest; use codex_code_mode_protocol::host::WireWaitRequest; use tokio::sync::mpsc; use tokio::sync::oneshot; @@ -39,7 +39,7 @@ pub(in crate::remote_session::connection) enum DriverCommand { Execute { session: RemoteSession, delegate: Arc, - request: ExecuteRequest, + request: WireExecuteRequest, caller_cancellation: CancellationToken, yield_signal: Option, response_tx: oneshot::Sender>, diff --git a/codex-rs/code-mode/src/remote_session/connection/driver_tests.rs b/codex-rs/code-mode/src/remote_session/connection/driver_tests.rs index 7c89483d97..14b0b42abb 100644 --- a/codex-rs/code-mode/src/remote_session/connection/driver_tests.rs +++ b/codex-rs/code-mode/src/remote_session/connection/driver_tests.rs @@ -12,7 +12,6 @@ use codex_code_mode_protocol::CodeModeSession; use codex_code_mode_protocol::CodeModeSessionCellExecutionLimits; use codex_code_mode_protocol::CodeModeSessionDelegate; use codex_code_mode_protocol::CodeModeSessionOptions; -use codex_code_mode_protocol::ExecuteRequest; use codex_code_mode_protocol::NotificationFuture; use codex_code_mode_protocol::TerminateRequest; use codex_code_mode_protocol::ToolInvocationFuture; @@ -30,6 +29,7 @@ use codex_code_mode_protocol::host::HostToClient; use codex_code_mode_protocol::host::MAX_PENDING_DELEGATE_CALLS; use codex_code_mode_protocol::host::RequestId; use codex_code_mode_protocol::host::SessionId; +use codex_code_mode_protocol::host::WireExecuteRequest; use codex_code_mode_protocol::host::WireNestedToolCall; use codex_code_mode_protocol::host::WireResult; use codex_code_mode_protocol::host::WireRuntimeResponse; @@ -154,7 +154,8 @@ impl DriverHarness { .send(DriverCommand::Execute { session, delegate, - request: ExecuteRequest { + request: WireExecuteRequest { + catalog_revision: None, tool_call_id: format!("call-{request_id}"), enabled_tools: Vec::new(), source: "await new Promise(() => {})".to_string(), @@ -585,7 +586,8 @@ async fn deferred_delegates_follow_cell_readiness_and_cancellation() { .send(DriverCommand::Execute { delegate: delegate.clone(), session: session.clone(), - request: ExecuteRequest { + request: WireExecuteRequest { + catalog_revision: None, tool_call_id: tool_call_id.to_string(), enabled_tools: Vec::new(), source: "text('done')".to_string(), @@ -773,7 +775,8 @@ async fn dropped_open_waiter_shuts_down_committed_session() { .send(DriverCommand::Execute { delegate: Arc::new(RecordingDelegate::default()), session: session.clone(), - request: ExecuteRequest { + request: WireExecuteRequest { + catalog_revision: None, tool_call_id: "call-1".to_string(), enabled_tools: Vec::new(), source: "text('ok')".to_string(), @@ -1731,7 +1734,8 @@ async fn abandoned_execute_is_tracked_and_terminated_after_admission() { .send(DriverCommand::Execute { delegate: delegate.clone(), session: session.clone(), - request: ExecuteRequest { + request: WireExecuteRequest { + catalog_revision: None, tool_call_id: "call-1".to_string(), enabled_tools: Vec::new(), source: "await new Promise(() => {})".to_string(), @@ -1830,7 +1834,8 @@ async fn delivered_but_unclaimed_execute_is_terminated_when_the_caller_is_cancel .send(DriverCommand::Execute { delegate: delegate.clone(), session: session.clone(), - request: ExecuteRequest { + request: WireExecuteRequest { + catalog_revision: None, tool_call_id: "call-1".to_string(), enabled_tools: Vec::new(), source: "await new Promise(() => {})".to_string(), @@ -1995,7 +2000,8 @@ async fn connection_failure_closes_every_live_cell_once() { .send(DriverCommand::Execute { delegate: delegate.clone(), session, - request: ExecuteRequest { + request: WireExecuteRequest { + catalog_revision: None, tool_call_id: "call-1".to_string(), enabled_tools: Vec::new(), source: "await new Promise(() => {})".to_string(), @@ -2175,7 +2181,8 @@ async fn dropped_shutdown_waiter_does_not_abort_remote_cleanup() { .send(DriverCommand::Execute { delegate: Arc::new(RecordingDelegate::default()), session, - request: ExecuteRequest { + request: WireExecuteRequest { + catalog_revision: None, tool_call_id: "call-2".to_string(), enabled_tools: Vec::new(), source: "text('unreachable')".to_string(), diff --git a/codex-rs/code-mode/src/tool_catalog.rs b/codex-rs/code-mode/src/tool_catalog.rs new file mode 100644 index 0000000000..72650ba202 --- /dev/null +++ b/codex-rs/code-mode/src/tool_catalog.rs @@ -0,0 +1,58 @@ +//! Negotiates a per-session tool catalog at cell admission. Concurrent admissions +//! can always send a self-contained request without changing the shared catalog. + +use std::sync::Arc; + +use codex_code_mode_protocol::ToolDefinition; +use tokio::sync::Mutex; +use tokio::sync::OwnedMutexGuard; + +#[derive(Default)] +pub(crate) struct Catalog { + revision: u64, + tools: Option>>, +} + +pub(crate) struct CatalogAdmission { + cache: OwnedMutexGuard, + replacement: Option>>, +} + +impl CatalogAdmission { + /// Takes ownership of a new snapshot until the host acknowledges admission. + /// Clearing the old snapshot first keeps cancellation from reusing a stale revision. + pub(crate) fn prepare(cache: &Arc>, tools: &[ToolDefinition]) -> Option { + if tools.is_empty() { + return None; + } + let mut cache = Arc::clone(cache).try_lock_owned().ok()?; + let replacement = if cache.tools.as_ref().is_some_and(|cached| { + cached.len() == tools.len() && cached.iter().map(Arc::as_ref).eq(tools) + }) { + None + } else { + cache.revision = cache.revision.checked_add(1)?; + cache.tools = None; + Some(ToolDefinition::shared_catalog(tools)) + }; + Some(Self { cache, replacement }) + } + + pub(crate) fn revision(&self) -> u64 { + self.cache.revision + } + + pub(crate) fn reuses_catalog(&self) -> bool { + self.replacement.is_none() + } + + pub(crate) fn accepted(mut self) { + if let Some(tools) = self.replacement.take() { + self.cache.tools = Some(tools); + } + } +} + +#[cfg(test)] +#[path = "tool_catalog_tests.rs"] +mod tests; diff --git a/codex-rs/code-mode/src/tool_catalog_tests.rs b/codex-rs/code-mode/src/tool_catalog_tests.rs new file mode 100644 index 0000000000..1fc28951b9 --- /dev/null +++ b/codex-rs/code-mode/src/tool_catalog_tests.rs @@ -0,0 +1,52 @@ +#![cfg(test)] + +use super::*; +use codex_code_mode_protocol::CodeModeToolKind; +use codex_protocol::ToolName; +use pretty_assertions::assert_eq; + +#[test] +fn references_require_an_acknowledged_matching_admission() { + let cache = Arc::new(Mutex::new(Catalog::default())); + let mut tools = [ToolDefinition { + name: "echo".to_string(), + tool_name: ToolName::plain("echo"), + description: String::new(), + kind: CodeModeToolKind::Function, + input_schema: None, + input_schema_max_bytes: None, + output_schema: None, + }]; + let cancelled = CatalogAdmission::prepare(&cache, &tools).unwrap(); + assert!(!cancelled.reuses_catalog()); + assert!(CatalogAdmission::prepare(&cache, &tools).is_none()); + let abandoned_revision = cancelled.revision(); + drop(cancelled); + let registration = CatalogAdmission::prepare(&cache, &tools).unwrap(); + assert!(!registration.reuses_catalog()); + assert!(registration.revision() > abandoned_revision); + let revision = registration.revision(); + registration.accepted(); + let hit = CatalogAdmission::prepare(&cache, &tools).unwrap(); + assert!(hit.reuses_catalog()); + assert_eq!(hit.revision(), revision); + hit.accepted(); + let other = Arc::new(Mutex::new(Catalog::default())); + let registration = CatalogAdmission::prepare(&other, &tools).unwrap(); + assert!(!registration.reuses_catalog()); + registration.accepted(); + { + let first = cache.try_lock().unwrap(); + let second = other.try_lock().unwrap(); + assert!(Arc::ptr_eq( + &first.tools.as_ref().unwrap()[0], + &second.tools.as_ref().unwrap()[0], + )); + } + tools[0].description = "changed".to_string(); + assert!( + !CatalogAdmission::prepare(&cache, &tools) + .unwrap() + .reuses_catalog() + ); +}