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
@@ -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(),
@@ -89,7 +89,7 @@ fn catalog_global(
fn build_tools_object<'s>(
scope: &mut v8::PinScope<'s, '_>,
enabled_tools: &[EnabledToolMetadata],
enabled_tools: &[Arc<EnabledToolMetadata>],
) -> Result<v8::Local<'s, v8::Object>, 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<EnabledToolMetadata>],
) -> Result<v8::Local<'s, v8::Value>, String> {
let mut items = Vec::with_capacity(enabled_tools.len());
let name_key = v8::String::new(scope, "name")
+49 -6
View File
@@ -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<u64>,
) -> Result<runtime::CreateCellRequest, String> {
let tools: Vec<EnabledToolMetadata> = 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<dyn CodeModeSessionDelegate>,
preempt: Option<CancellationToken>,
) -> Result<StartedCell, String> {
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<u64>,
delegate: Arc<dyn CodeModeSessionDelegate>,
preempt: Option<CancellationToken>,
) -> Result<StartedCell, String> {
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 }),
)
@@ -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(
@@ -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<codex_code_mode_protocol::EnabledToolMetadata>]>;
/// Transport-neutral input for creating a cell.
///