Defer code-mode tool catalog construction until first access (#61845)

## Why

Each cell eagerly built `tools` and `ALL_TOOLS`, even when its code never accessed them.

## What changed

- Initialize each catalog global lazily on its first read, preserving writable values and mutations within each cell.
- Normalize tool metadata at the service boundary and share it through an `Arc`-backed catalog instead of repeatedly converting it between runtime layers.
- Construct catalog properties without invoking inherited setters.

## Testing

Add regression tests for cell-local catalog mutations, fresh catalogs across cells, and catalog construction with inherited setters on `Object.prototype` and `Array.prototype`.

GitOrigin-RevId: 04695c24ff33d3b3a4335558e9c754844f04e9f0
This commit is contained in:
Charlie Marsh
2026-11-16 17:46:42 +00:00
committed by copyberry
parent 090be4df07
commit e0241d4fae
12 changed files with 195 additions and 151 deletions
@@ -1,39 +1,7 @@
use codex_code_mode_protocol::CodeModeToolKind;
use codex_code_mode_protocol::ExecuteRequest;
use codex_code_mode_protocol::ToolDefinition;
use codex_protocol::ToolName;
use crate::session_runtime::CreateCellRequest as CellRequest;
use crate::session_runtime::ToolKind as CellToolKind;
pub(super) fn runtime_request(request: CellRequest) -> ExecuteRequest {
ExecuteRequest {
tool_call_id: request.tool_call_id,
enabled_tools: request
.enabled_tools
.into_iter()
.map(|definition| ToolDefinition {
name: definition.name,
tool_name: ToolName {
name: definition.tool_name.name,
namespace: definition.tool_name.namespace,
},
description: definition.description,
kind: match definition.kind {
CellToolKind::Function => CodeModeToolKind::Function,
CellToolKind::Freeform => CodeModeToolKind::Freeform,
},
input_schema: None,
input_schema_max_bytes: None,
output_schema: None,
})
.collect(),
source: request.source,
yield_time_ms: None,
max_output_tokens: None,
}
}
pub(super) fn cell_tool_kind(kind: CodeModeToolKind) -> CellToolKind {
match kind {
CodeModeToolKind::Function => CellToolKind::Function,
@@ -18,7 +18,6 @@ use self::callbacks::report_task_result;
use self::callbacks::spawn_notification;
use self::callbacks::spawn_tool;
use self::conversions::cell_tool_kind;
use self::conversions::runtime_request;
use self::types::CellCommand;
pub(crate) use self::types::CellError;
pub(crate) use self::types::CellEventFuture;
@@ -68,7 +67,7 @@ impl CellActor {
let (initial_response_tx, initial_response_rx) = oneshot::channel();
let (runtime_tx, runtime_control_tx, runtime_terminate_handle) = spawn_runtime(
stored_values,
runtime_request(request),
request,
event_tx,
PendingRuntimeMode::PauseUntilResumed,
task_failure_handler.clone(),
@@ -6,7 +6,6 @@ use std::sync::mpsc as std_mpsc;
use std::time::Duration;
use codex_code_mode_protocol::CodeModeOutputTruncation;
use codex_code_mode_protocol::ExecuteRequest;
use codex_code_mode_protocol::host::BOUNDED_OUTPUT_MAX_IMAGE_BYTES;
use pretty_assertions::assert_eq;
use serde_json::Value as JsonValue;
@@ -133,12 +132,11 @@ fn spawn_cell_actor_harness_with_host_and_failure_handler<H: CellHost>(
let (runtime_event_tx, runtime_event_rx) = mpsc::unbounded_channel();
let (runtime_tx, _runtime_control_tx, runtime_terminate_handle) = spawn_runtime(
HashMap::new(),
ExecuteRequest {
CellRequest {
tool_call_id: "call-1".to_string(),
enabled_tools: Vec::new(),
enabled_tools: Default::default(),
source: "await new Promise(() => {});".to_string(),
yield_time_ms: None,
max_output_tokens: None,
output_truncation: CodeModeOutputTruncation::Client,
},
runtime_event_tx,
PendingRuntimeMode::PauseUntilResumed,
@@ -14,7 +14,6 @@ use tokio::sync::mpsc;
use super::super::RuntimeEvent;
use super::super::RuntimeState;
use super::super::ToolCallbackMetadata;
use super::super::globals;
use crate::session_runtime::OutputItem;
use crate::v8_init::ensure_v8_initialized;
@@ -107,26 +106,19 @@ clearTimeout(earlyTimer); setTimeout(() => {}, 60000);
let (event_tx, mut event_rx) = mpsc::unbounded_channel();
let (runtime_command_tx, _runtime_command_rx) = std_mpsc::channel();
let tool_name = ToolName::plain("echo");
globals::install_globals(
scope,
&[EnabledToolMetadata {
global_name: "echo".to_string(),
tool_name: tool_name.clone(),
description: String::new(),
kind: CodeModeToolKind::Function,
}],
)
.expect("install globals");
globals::install_globals(scope).expect("install globals");
scope.set_slot(RuntimeState {
event_tx: event_tx.into(),
pending_tool_calls: HashMap::new(),
pending_timeouts: HashMap::new(),
stored_values: HashMap::new(),
stored_value_writes: HashMap::new(),
enabled_tools: vec![ToolCallbackMetadata {
enabled_tools: Arc::from([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(),
@@ -1,3 +1,5 @@
use std::sync::Arc;
use super::callbacks::audio_callback;
use super::callbacks::clear_timeout_callback;
use super::callbacks::content_block_callback;
@@ -13,18 +15,13 @@ use super::callbacks::tool_callback;
use super::callbacks::yield_control_callback;
use codex_code_mode_protocol::EnabledToolMetadata;
pub(super) fn install_globals(
scope: &mut v8::PinScope<'_, '_>,
enabled_tools: &[EnabledToolMetadata],
) -> Result<(), String> {
pub(super) fn install_globals(scope: &mut v8::PinScope<'_, '_>) -> Result<(), String> {
let global = scope.get_current_context().global(scope);
delete_global(scope, global, "console")?;
delete_global(scope, global, "Atomics")?;
delete_global(scope, global, "SharedArrayBuffer")?;
delete_global(scope, global, "WebAssembly")?;
let tools = build_tools_object(scope, enabled_tools)?;
let all_tools = build_all_tools_value(scope, enabled_tools)?;
let clear_timeout = helper_function(scope, "clearTimeout", clear_timeout_callback)?;
let set_timeout = helper_function(scope, "setTimeout", set_timeout_callback)?;
let text = helper_function(scope, "text", text_callback)?;
@@ -38,8 +35,13 @@ pub(super) fn install_globals(
let yield_control = helper_function(scope, "yield_control", yield_control_callback)?;
let exit = helper_function(scope, "exit", exit_callback)?;
set_global(scope, global, "tools", tools.into())?;
set_global(scope, global, "ALL_TOOLS", all_tools)?;
for name in ["tools", "ALL_TOOLS"] {
let key =
v8::String::new(scope, name).ok_or_else(|| format!("failed to allocate {name}"))?;
if global.set_lazy_data_property(scope, key.into(), catalog_global) != Some(true) {
return Err(format!("failed to install {name}"));
}
}
set_global(scope, global, "clearTimeout", clear_timeout.into())?;
set_global(scope, global, "setTimeout", set_timeout.into())?;
set_global(scope, global, "text", text.into())?;
@@ -62,50 +64,80 @@ pub(super) fn install_globals(
Ok(())
}
/// V8 replaces the lazy property with its writable value on the first read.
fn catalog_global(
scope: &mut v8::PinScope<'_, '_>,
key: v8::Local<v8::Name>,
_args: v8::PropertyCallbackArguments,
mut retval: v8::ReturnValue<v8::Value>,
) {
let Some(state) = scope.get_slot::<super::RuntimeState>() else {
super::value::throw_type_error(scope, "code-mode catalog is unavailable");
return;
};
let tools = Arc::clone(&state.enabled_tools);
let value = if key.to_rust_string_lossy(scope) == "tools" {
build_tools_object(scope, &tools).map(Into::into)
} else {
build_all_tools_value(scope, &tools)
};
match value {
Ok(value) => retval.set(value),
Err(message) => super::value::throw_type_error(scope, &message),
}
}
fn build_tools_object<'s>(
scope: &mut v8::PinScope<'s, '_>,
enabled_tools: &[EnabledToolMetadata],
) -> Result<v8::Local<'s, v8::Object>, String> {
let tools = v8::Object::new(scope);
let prototype = v8::Object::new(scope)
.get_prototype(scope)
.ok_or_else(|| "failed to get tool object prototype".to_string())?;
let mut names = Vec::with_capacity(enabled_tools.len());
let mut functions = Vec::with_capacity(enabled_tools.len());
for (tool_index, tool) in enabled_tools.iter().enumerate() {
let name = v8::String::new(scope, &tool.global_name)
.ok_or_else(|| "failed to allocate tool name".to_string())?;
let function = tool_function(scope, tool_index)?;
tools.set(scope, name.into(), function.into());
names.push(name.into());
functions.push(function.into());
}
Ok(tools)
Ok(v8::Object::with_prototype_and_properties(
scope, prototype, &names, &functions,
))
}
fn build_all_tools_value<'s>(
scope: &mut v8::PinScope<'s, '_>,
enabled_tools: &[EnabledToolMetadata],
) -> Result<v8::Local<'s, v8::Value>, String> {
let array = v8::Array::new(scope, enabled_tools.len() as i32);
let mut items = Vec::with_capacity(enabled_tools.len());
let name_key = v8::String::new(scope, "name")
.ok_or_else(|| "failed to allocate ALL_TOOLS name key".to_string())?;
let description_key = v8::String::new(scope, "description")
.ok_or_else(|| "failed to allocate ALL_TOOLS description key".to_string())?;
for (index, tool) in enabled_tools.iter().enumerate() {
for tool in enabled_tools {
let item = v8::Object::new(scope);
let name = v8::String::new(scope, &tool.global_name)
.ok_or_else(|| "failed to allocate ALL_TOOLS name".to_string())?;
let description = v8::String::new(scope, &tool.description)
.ok_or_else(|| "failed to allocate ALL_TOOLS description".to_string())?;
if item.set(scope, name_key.into(), name.into()) != Some(true) {
if item.create_data_property(scope, name_key.into(), name.into()) != Some(true) {
return Err("failed to set ALL_TOOLS name".to_string());
}
if item.set(scope, description_key.into(), description.into()) != Some(true) {
if item.create_data_property(scope, description_key.into(), description.into())
!= Some(true)
{
return Err("failed to set ALL_TOOLS description".to_string());
}
if array.set_index(scope, index as u32, item.into()) != Some(true) {
return Err("failed to append ALL_TOOLS metadata".to_string());
}
items.push(item.into());
}
Ok(array.into())
Ok(v8::Array::new_with_elements(scope, &items).into())
}
fn helper_function<'s, F>(
+13 -38
View File
@@ -14,12 +14,11 @@ use std::sync::mpsc as std_mpsc;
use std::thread;
use crate::TaskFailureHandler;
use crate::session_runtime::CreateCellRequest;
use crate::session_runtime::OutputItem;
use crate::session_runtime::ToolCatalog;
use crate::v8_init::ensure_v8_initialized;
use codex_code_mode_protocol::CodeModeToolKind;
use codex_code_mode_protocol::EnabledToolMetadata;
use codex_code_mode_protocol::ExecuteRequest;
use codex_code_mode_protocol::normalize_code_mode_identifier;
use codex_protocol::ToolName;
pub(crate) use event_channel::RuntimeEventReceiver;
pub(crate) use event_channel::RuntimeEventSender;
@@ -74,7 +73,7 @@ pub(crate) enum RuntimeEvent {
pub(crate) fn spawn_runtime(
stored_values: HashMap<String, Arc<JsonValue>>,
request: ExecuteRequest,
request: CreateCellRequest,
event_tx: impl Into<RuntimeEventSender>,
pending_mode: PendingRuntimeMode,
task_failure_handler: Option<TaskFailureHandler>,
@@ -93,19 +92,9 @@ pub(crate) fn spawn_runtime(
let (control_tx, control_rx) = std_mpsc::channel();
let runtime_command_tx = command_tx.clone();
let (isolate_handle_tx, isolate_handle_rx) = std_mpsc::sync_channel(1);
let enabled_tools = request
.enabled_tools
.into_iter()
.map(|definition| EnabledToolMetadata {
global_name: normalize_code_mode_identifier(&definition.name),
tool_name: definition.tool_name,
description: definition.description,
kind: definition.kind,
})
.collect::<Vec<_>>();
let config = RuntimeConfig {
tool_call_id: request.tool_call_id,
enabled_tools,
enabled_tools: request.enabled_tools,
source: request.source,
stored_values,
};
@@ -149,24 +138,18 @@ fn spawn_supervised_runtime_thread(
#[derive(Clone)]
struct RuntimeConfig {
tool_call_id: String,
enabled_tools: Vec<EnabledToolMetadata>,
enabled_tools: ToolCatalog,
source: String,
stored_values: HashMap<String, Arc<JsonValue>>,
}
// Callback indices refer to this cell's original catalog for its entire lifetime.
struct ToolCallbackMetadata {
tool_name: ToolName,
kind: CodeModeToolKind,
}
pub(super) struct RuntimeState {
event_tx: RuntimeEventSender,
pending_tool_calls: HashMap<String, v8::Global<v8::PromiseResolver>>,
pending_timeouts: HashMap<u64, timers::ScheduledTimeout>,
stored_values: HashMap<String, Arc<JsonValue>>,
stored_value_writes: HashMap<String, Arc<JsonValue>>,
enabled_tools: Vec<ToolCallbackMetadata>,
enabled_tools: ToolCatalog,
next_tool_call_id: u64,
next_timeout_id: u64,
tool_call_id: String,
@@ -199,7 +182,7 @@ fn run_runtime(
let context = v8::Context::new(scope, Default::default());
let scope = &mut v8::ContextScope::new(scope, context);
if let Err(error_text) = globals::install_globals(scope, &config.enabled_tools) {
if let Err(error_text) = globals::install_globals(scope) {
send_result(&event_tx, HashMap::new(), Some(error_text));
return;
}
@@ -210,14 +193,7 @@ fn run_runtime(
pending_timeouts: HashMap::new(),
stored_values: config.stored_values,
stored_value_writes: HashMap::new(),
enabled_tools: config
.enabled_tools
.into_iter()
.map(|tool| ToolCallbackMetadata {
tool_name: tool.tool_name,
kind: tool.kind,
})
.collect(),
enabled_tools: config.enabled_tools,
next_tool_call_id: 1,
next_timeout_id: 1,
tool_call_id: config.tool_call_id,
@@ -352,7 +328,7 @@ mod tests {
use pretty_assertions::assert_eq;
use tokio::sync::mpsc;
use super::ExecuteRequest;
use super::CreateCellRequest;
use super::PendingRuntimeMode;
use super::RuntimeCommand;
use super::RuntimeControlCommand;
@@ -361,13 +337,12 @@ mod tests {
use super::spawn_supervised_runtime_thread;
use crate::session_runtime::OutputItem;
fn execute_request(source: &str) -> ExecuteRequest {
ExecuteRequest {
fn execute_request(source: &str) -> CreateCellRequest {
CreateCellRequest {
tool_call_id: "call_1".to_string(),
enabled_tools: Vec::new(),
enabled_tools: Default::default(),
source: source.to_string(),
yield_time_ms: Some(1),
max_output_tokens: None,
output_truncation: codex_code_mode_protocol::CodeModeOutputTruncation::Client,
}
}
@@ -27,7 +27,7 @@ fn discarded_tool_response_is_collectible_before_cell_ends() {
pending_timeouts: HashMap::new(),
stored_values: HashMap::new(),
stored_value_writes: HashMap::new(),
enabled_tools: Vec::new(),
enabled_tools: Default::default(),
next_tool_call_id: 1,
next_timeout_id: 1,
tool_call_id: "cell".to_string(),
+23 -29
View File
@@ -1,3 +1,5 @@
use codex_code_mode_protocol::EnabledToolMetadata;
use codex_code_mode_protocol::normalize_code_mode_identifier;
use std::sync::Arc;
use std::time::Duration;
@@ -72,6 +74,25 @@ impl InProcessCodeModeSession {
}
}
fn runtime_request(&self, request: ExecuteRequest) -> runtime::CreateCellRequest {
let tools = request
.enabled_tools
.into_iter()
.map(|tool| EnabledToolMetadata {
global_name: normalize_code_mode_identifier(&tool.name),
tool_name: tool.tool_name,
description: tool.description,
kind: tool.kind,
})
.collect();
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(
&self,
request: ExecuteRequest,
@@ -84,7 +105,7 @@ impl InProcessCodeModeSession {
let started = self
.runtime
.execute(
runtime_request(request, self.options.output_truncation),
self.runtime_request(request),
runtime::ObserveMode::YieldAfter(self.resolve_yield_timeout(yield_time_ms))
.with_yield_signal(preempt.unwrap_or_default()),
Arc::new(ProtocolDelegate { delegate }),
@@ -121,7 +142,7 @@ impl InProcessCodeModeSession {
let started = self
.runtime
.execute(
runtime_request(request, self.options.output_truncation),
self.runtime_request(request),
runtime::ObserveMode::PendingFrontier,
Arc::new(ProtocolDelegate { delegate }),
)
@@ -375,33 +396,6 @@ impl runtime::SessionRuntimeDelegate for ProtocolDelegate {
}
}
fn runtime_request(
request: ExecuteRequest,
output_truncation: CodeModeOutputTruncation,
) -> runtime::CreateCellRequest {
runtime::CreateCellRequest {
output_truncation,
tool_call_id: request.tool_call_id,
enabled_tools: request
.enabled_tools
.into_iter()
.map(|definition| runtime::ToolDefinition {
name: definition.name,
tool_name: runtime::ToolName {
name: definition.tool_name.name,
namespace: definition.tool_name.namespace,
},
description: definition.description,
kind: match definition.kind {
CodeModeToolKind::Function => runtime::ToolKind::Function,
CodeModeToolKind::Freeform => runtime::ToolKind::Freeform,
},
})
.collect(),
source: request.source,
}
}
fn runtime_cell_id(cell_id: &CellId) -> runtime::CellId {
runtime::CellId::new(cell_id.as_str())
}
@@ -1363,6 +1363,96 @@ text("done");
);
}
#[tokio::test]
async fn catalog_globals_preserve_mutations_within_each_cell() {
let service = InProcessCodeModeSession::new();
let source = r#"
const entry = ALL_TOOLS[0];
const name = entry.name;
entry.name = "local";
const callback = tools[name];
tools[name] = null;
text(JSON.stringify([name, typeof callback, ALL_TOOLS[0].name, tools[name]]));
"#;
for _ in 0..2 {
let response = execute(
&service,
ExecuteRequest {
enabled_tools: vec![echo_tool()],
yield_time_ms: None,
..execute_request(source)
},
)
.await;
let RuntimeResponse::Result {
content_items,
error_text: None,
..
} = response
else {
panic!("catalog lookup failed: {response:?}");
};
assert_eq!(
content_items,
vec![FunctionCallOutputContentItem::InputText {
text: r#"["echo","function","local",null]"#.into(),
}]
);
}
}
#[tokio::test]
async fn catalog_globals_ignore_inherited_setters() {
let service = InProcessCodeModeSession::new();
let source = r#"
let setterCalls = 0;
Object.defineProperty(Object.prototype, "name", {
configurable: true,
set(value) { setterCalls++; globalThis.ALL_TOOLS = []; }
});
for (const key of ["description", "echo"]) {
Object.defineProperty(Object.prototype, key, {
configurable: true,
set(value) { setterCalls++; }
});
}
Object.defineProperty(Array.prototype, "0", {
configurable: true,
set(value) { setterCalls++; }
});
const entry = ALL_TOOLS[0];
const callback = tools.echo;
delete Object.prototype.name;
delete Object.prototype.description;
delete Object.prototype.echo;
delete Array.prototype[0];
text(JSON.stringify([entry.name, entry.description, typeof callback, setterCalls]));
"#;
let response = execute(
&service,
ExecuteRequest {
enabled_tools: vec![echo_tool()],
yield_time_ms: None,
..execute_request(source)
},
)
.await;
let RuntimeResponse::Result {
content_items,
error_text: None,
..
} = response
else {
panic!("catalog lookup failed: {response:?}");
};
assert_eq!(
content_items,
vec![FunctionCallOutputContentItem::InputText {
text: r#"["echo","","function",0]"#.into(),
}]
);
}
#[tokio::test]
async fn global_scope_contains_only_allowed_items() {
let service = InProcessCodeModeSession::new();
@@ -22,7 +22,7 @@ pub(crate) use self::types::NestedToolCall;
pub(crate) use self::types::Observation;
pub(crate) use self::types::ObserveMode;
pub(crate) use self::types::SessionRuntimeDelegate;
pub(crate) use self::types::ToolDefinition;
pub(crate) use self::types::ToolCatalog;
pub(crate) use self::types::ToolKind;
pub(crate) use self::types::ToolName;
use crate::TaskFailureHandler;
@@ -145,7 +145,7 @@ async fn termination_rejects_a_waiting_store_commit_before_the_next_cell_can_loa
CreateCellRequest {
output_truncation: CodeModeOutputTruncation::Client,
tool_call_id: "reader".to_string(),
enabled_tools: Vec::new(),
enabled_tools: Default::default(),
source: r#"text(String(load("candidate")));"#.to_string(),
},
ObserveMode::YieldAfter(Duration::from_secs(1)),
@@ -170,7 +170,7 @@ fn execute_request(source: &str) -> CreateCellRequest {
CreateCellRequest {
output_truncation: CodeModeOutputTruncation::Client,
tool_call_id: "call-1".to_string(),
enabled_tools: Vec::new(),
enabled_tools: Default::default(),
source: source.to_string(),
}
}
@@ -1,5 +1,6 @@
use std::fmt;
use std::future::Future;
use std::sync::Arc;
use std::time::Duration;
use serde_json::Value as JsonValue;
@@ -79,24 +80,19 @@ 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]>;
/// Transport-neutral input for creating a cell.
///
/// The owning session assigns the cell ID when it admits the request.
pub(crate) struct CreateCellRequest {
pub(crate) output_truncation: codex_code_mode_protocol::CodeModeOutputTruncation,
pub(crate) tool_call_id: String,
pub(crate) enabled_tools: Vec<ToolDefinition>,
pub(crate) enabled_tools: ToolCatalog,
pub(crate) source: String,
}
/// Tool metadata exposed to code running inside a cell.
pub(crate) struct ToolDefinition {
pub(crate) name: String,
pub(crate) tool_name: ToolName,
pub(crate) description: String,
pub(crate) kind: ToolKind,
}
/// A tool name with an optional namespace.
#[derive(Clone, Debug, Eq, PartialEq)]
pub(crate) struct ToolName {