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
This commit is contained in:
Charlie Marsh
2026-11-16 17:47:49 +00:00
committed by copyberry
parent e0241d4fae
commit fef47a6769
32 changed files with 394 additions and 43 deletions
@@ -73,6 +73,7 @@ async fn tool_call_heartbeats_do_not_enter_callback_admission() {
fn session(client: GrpcClient) -> Arc<SessionInner> {
let client = Arc::new(client);
Arc::new(SessionInner {
catalog: None,
id: "session".to_string(),
output_truncation: CodeModeOutputTruncation::Client,
route: None,
@@ -32,6 +32,7 @@ pub(super) fn execute_request(
request: ExecuteRequest,
) -> Result<grpc::ExecuteRequest, String> {
Ok(grpc::ExecuteRequest {
catalog_revision: None,
session_id: session_id.to_string(),
execution_id,
tool_call_id: request.tool_call_id,
@@ -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(),
@@ -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<Arc<tokio::sync::Mutex<crate::tool_catalog::Catalog>>>,
pub(super) id: String,
output_truncation: CodeModeOutputTruncation,
// Affinity belongs to the session: parents and children may share a transport
@@ -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(
@@ -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(),
+1
View File
@@ -1,5 +1,6 @@
mod grpc_session;
mod remote_session;
mod tool_catalog;
pub use codex_code_mode_protocol::*;
pub use grpc_session::GrpcCodeModeSessionProvider;
+26 -2
View File
@@ -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<tokio::sync::Mutex<crate::tool_catalog::Catalog>>,
connection: Arc<Connection>,
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,
@@ -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<dyn CodeModeSessionDelegate>,
yield_signal: Option<CancellationToken>,
) -> Result<StartedCell, String> {
@@ -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<dyn CodeModeSessionDelegate>,
caller_cancellation: CancellationToken,
yield_signal: Option<CancellationToken>,
@@ -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) => {
@@ -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<dyn CodeModeSessionDelegate>,
request: ExecuteRequest,
request: WireExecuteRequest,
caller_cancellation: CancellationToken,
yield_signal: Option<CancellationToken>,
response_tx: oneshot::Sender<Result<DeliveredExecute, String>>,
@@ -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(),
+58
View File
@@ -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<Vec<Arc<ToolDefinition>>>,
}
pub(crate) struct CatalogAdmission {
cache: OwnedMutexGuard<Catalog>,
replacement: Option<Vec<Arc<ToolDefinition>>>,
}
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<Mutex<Catalog>>, tools: &[ToolDefinition]) -> Option<Self> {
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;
@@ -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()
);
}