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
@@ -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 {
@@ -77,6 +77,7 @@ where
fn execute_request() -> WireExecuteRequest {
WireExecuteRequest {
catalog_revision: None,
tool_call_id: "call-1".to_string(),
enabled_tools: vec![
WireToolDefinition {
@@ -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;
@@ -203,6 +203,9 @@ impl From<WireToolDefinition> 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<u64>,
pub tool_call_id: String,
pub enabled_tools: Vec<WireToolDefinition>,
pub source: String,
@@ -215,6 +218,7 @@ impl TryFrom<ExecuteRequest> for WireExecuteRequest {
fn try_from(value: ExecuteRequest) -> Result<Self, Self::Error> {
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,
+1
View File
@@ -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;
@@ -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<T> = LazyLock<Mutex<HashMap<u64, Vec<Weak<T>>>>>;
impl ToolDefinition {
/// Shares matching definitions while preserving the client's catalog order.
pub fn shared_catalog(tools: &[Self]) -> Vec<Arc<Self>> {
static INDEX: ToolIndex<ToolDefinition> = 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<Self>) -> Vec<Arc<Self>> {
static INDEX: ToolIndex<EnabledToolMetadata> = 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<T>,
tools: impl Iterator<Item = Cow<'a, T>>,
name: impl Fn(&T) -> &ToolName,
) -> Vec<Arc<T>> {
static HASHER: LazyLock<RandomState> = 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()
}