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(),