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
@@ -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(),
+2 -1
View File
@@ -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)?
}
};
@@ -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(),
@@ -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())
@@ -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,
+6 -1
View File
@@ -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<R: AsyncRead + Unpin, W: AsyncWrite + Unpin>(
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();
@@ -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}"),
@@ -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()
}
@@ -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.
///
@@ -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()
);
}