From 4c153c26c0b5c54a22e0e775b46bcc4aa8872c79 Mon Sep 17 00:00:00 2001 From: Dmitriy Kovalenko Date: Fri, 20 Nov 2026 21:56:58 +0000 Subject: [PATCH] Reduce allocations when preparing tool schemas and catalogs (#62849) ## Why Tool schema budget checks cloned the schema and allocated a JSON buffer just to measure its size. Building a Responses Lite catalog also cloned tool definitions before serializing them. ## What changed - Deserialize schemas from borrowed JSON during compaction, count serialized bytes without allocating a buffer, and reuse the parsed schema when it fits the budget. - Serialize borrowed tool specs and namespace members directly, and pass filtered specs as an iterator. Preserve the serialized namespace field order because the bytes contribute to the `additional_tools` item ID. ## Testing - Compare the exact serialized Responses Lite catalog against the expected namespace layout. - Add a `tool_catalog` benchmark for connector schema preparation and Responses Lite catalog encoding with 1 and 64 tool specs. GitOrigin-RevId: 6bd03a12fcedd4abfa8c3a03f298243483e98c63 --- codex-rs/Cargo.lock | 1 + codex-rs/core/src/client.rs | 2 +- codex-rs/core/src/session/world_state.rs | 11 ++- codex-rs/tools/Cargo.toml | 5 ++ codex-rs/tools/benches/tool_catalog.rs | 79 ++++++++++++++++++++ codex-rs/tools/src/json_schema.rs | 11 ++- codex-rs/tools/src/json_schema/compaction.rs | 27 +++---- codex-rs/tools/src/tool_spec.rs | 45 ++++++----- codex-rs/tools/src/tool_spec_tests.rs | 65 ++++++++-------- 9 files changed, 161 insertions(+), 85 deletions(-) create mode 100644 codex-rs/tools/benches/tool_catalog.rs diff --git a/codex-rs/Cargo.lock b/codex-rs/Cargo.lock index e054c4e4a6..75601fb603 100644 --- a/codex-rs/Cargo.lock +++ b/codex-rs/Cargo.lock @@ -5287,6 +5287,7 @@ dependencies = [ "codex-utils-output-truncation", "codex-utils-path-uri", "codex-utils-string", + "divan", "jsonptr", "pretty_assertions", "rmcp", diff --git a/codex-rs/core/src/client.rs b/codex-rs/core/src/client.rs index c233ebdd8c..e29b4af2ee 100644 --- a/codex-rs/core/src/client.rs +++ b/codex-rs/core/src/client.rs @@ -1269,7 +1269,7 @@ impl ModelClient { let mut prefix = Vec::new(); let tools = if model_info.use_responses_lite { if !prompt.tools.is_empty() { - let tools = create_tools_json_for_responses_lite(&prompt.tools)?; + let tools = create_tools_json_for_responses_lite(prompt.tools.iter())?; prefix.push(ResponseItem::AdditionalTools { id: Some(request_ids.id_by_content("at", &serde_json::to_vec(&tools)?)), role: "developer".to_string(), diff --git a/codex-rs/core/src/session/world_state.rs b/codex-rs/core/src/session/world_state.rs index 028212f0d0..1da56cc955 100644 --- a/codex-rs/core/src/session/world_state.rs +++ b/codex-rs/core/src/session/world_state.rs @@ -205,12 +205,11 @@ impl Session { !new_window && self.preserve_parent_tool_declarations(); if incremental_tools && !preserve_parent_tool_declarations { let specs = step_context.tool_router.model_visible_specs(); - let specs = specs - .iter() - .filter(|tool| !matches!(tool, ToolSpec::WebSearch { .. })) - .cloned() - .collect::>(); - let definitions = codex_tools::create_tools_json_for_responses_lite(&specs)?; + let definitions = codex_tools::create_tools_json_for_responses_lite( + specs + .iter() + .filter(|tool| !matches!(tool, ToolSpec::WebSearch { .. })), + )?; let mut top_level = TopLevelToolsState::new( model_messages.incremental_tools(), definitions, diff --git a/codex-rs/tools/Cargo.toml b/codex-rs/tools/Cargo.toml index aa378ff33d..859676291c 100644 --- a/codex-rs/tools/Cargo.toml +++ b/codex-rs/tools/Cargo.toml @@ -34,7 +34,12 @@ urlencoding = { workspace = true } [dev-dependencies] codex-utils-cargo-bin = { workspace = true } +divan = { workspace = true } pretty_assertions = { workspace = true } [lib] doctest = false + +[[bench]] +name = "tool_catalog" +harness = false diff --git a/codex-rs/tools/benches/tool_catalog.rs b/codex-rs/tools/benches/tool_catalog.rs new file mode 100644 index 0000000000..b9a31daeef --- /dev/null +++ b/codex-rs/tools/benches/tool_catalog.rs @@ -0,0 +1,79 @@ +//! Measure connector schema preparation and Responses Lite catalog encoding. +//! Run `cargo bench -p codex-tools --bench tool_catalog` from codex-rs. +//! For a baseline, copy this file and its Cargo bench target and dev-dependency +//! to a checkout of the base revision, then run the same command there. + +#![allow(clippy::expect_used)] + +use codex_tools::ResponsesApiNamespace; +use codex_tools::ResponsesApiNamespaceTool; +use codex_tools::ResponsesApiTool; +use codex_tools::ToolSpec; +use codex_tools::create_tools_json_for_responses_lite; +use codex_tools::parse_tool_input_schema; +use divan::Bencher; +use serde_json::Value; + +const SCHEMAS: [&str; 6] = [ + "google_calendar", + "google_drive", + "microsoft_outlook_email", + "notion", + "slack", + "oversized_notion_create_page_input_schema", +]; + +fn main() { + divan::main(); +} + +fn load_schema(name: &str) -> Value { + let path = format!("tests/fixtures/json_schema_policy/{name}.json"); + let path = codex_utils_cargo_bin::find_resource!(path).expect("resolve connector fixture"); + let fixture = std::fs::read(path).expect("read connector fixture"); + let mut fixture: Value = serde_json::from_slice(&fixture).expect("decode connector fixture"); + fixture["tools"][0]["input_schema"].take() +} + +#[divan::bench(args = SCHEMAS)] +fn prepare_connector_schema(bencher: Bencher, name: &str) { + let schema = load_schema(name); + bencher.bench_local(|| { + parse_tool_input_schema(divan::black_box(&schema)).expect("prepare fixture schema") + }); +} + +#[divan::bench(args = [1, 64])] +fn encode_responses_lite_catalog(bencher: Bencher, count: usize) { + let schema = + parse_tool_input_schema(&load_schema("google_drive")).expect("prepare tool schema"); + let mut specs = Vec::new(); + for i in 0..count { + let tool = ResponsesApiTool { + name: format!("lookup_{i}"), + description: "Look up a file in the selected drive.".to_string(), + strict: false, + defer_loading: None, + parameters: schema.clone(), + output_schema: None, + }; + let spec = match i % 3 { + 0 => ToolSpec::Function(tool), + kind => ToolSpec::Namespace(ResponsesApiNamespace { + name: if kind == 1 { + "functions".to_string() + } else { + format!("provider_{i}") + }, + description: format!("File tools for collection {i}"), + tools: vec![ResponsesApiNamespaceTool::Function(tool)], + }), + }; + specs.push(spec); + } + bencher.bench_local(|| { + let tools = create_tools_json_for_responses_lite(divan::black_box(specs.as_slice())) + .expect("serialize Responses Lite catalog"); + serde_json::to_vec(&tools).expect("encode catalog") + }); +} diff --git a/codex-rs/tools/src/json_schema.rs b/codex-rs/tools/src/json_schema.rs index d4e6990fc6..330c5d1135 100644 --- a/codex-rs/tools/src/json_schema.rs +++ b/codex-rs/tools/src/json_schema.rs @@ -43,16 +43,16 @@ pub(crate) fn parse_tool_input_schema_with_max_bytes( input_schema: &JsonValue, max_bytes: usize, ) -> Result { - let mut input_schema = prepare_tool_input_schema(input_schema); - compact_large_tool_schema(&mut input_schema, max_bytes); - deserialize_tool_input_schema(input_schema) + let schema = compact_large_tool_schema(prepare_tool_input_schema(input_schema), max_bytes)?; + validate_tool_input_schema(schema) } /// Parse a trusted tool `input_schema` without running large-schema compaction. pub fn parse_tool_input_schema_without_compaction( input_schema: &JsonValue, ) -> Result { - deserialize_tool_input_schema(prepare_tool_input_schema(input_schema)) + let schema = serde_json::from_value(prepare_tool_input_schema(input_schema))?; + validate_tool_input_schema(schema) } fn prepare_tool_input_schema(input_schema: &JsonValue) -> JsonValue { @@ -62,8 +62,7 @@ fn prepare_tool_input_schema(input_schema: &JsonValue) -> JsonValue { input_schema } -fn deserialize_tool_input_schema(input_schema: JsonValue) -> Result { - let schema: JsonSchema = serde_json::from_value(input_schema)?; +fn validate_tool_input_schema(schema: JsonSchema) -> Result { if matches!( schema.schema_type, Some(JsonSchemaType::Single(JsonSchemaPrimitiveType::Null)) diff --git a/codex-rs/tools/src/json_schema/compaction.rs b/codex-rs/tools/src/json_schema/compaction.rs index c3ce94898c..7a2376b609 100644 --- a/codex-rs/tools/src/json_schema/compaction.rs +++ b/codex-rs/tools/src/json_schema/compaction.rs @@ -8,6 +8,8 @@ use super::has_composition_keyword; use super::parse_local_definition_ref; use super::traversal::DefinitionTraversal; use super::traversal::for_each_schema_child_mut; +use codex_utils_string::serialized_json_bytes; +use serde::Deserialize; use serde_json::Value as JsonValue; use serde_json::json; @@ -19,13 +21,19 @@ const MAX_COMPACT_TOOL_SCHEMA_DEPTH: usize = 3; /// surface. Compaction is best-effort rather than a hard cap: it runs only /// after schema sanitization/pruning and applies increasingly lossy passes /// while the schema remains over budget. -pub(super) fn compact_large_tool_schema(value: &mut JsonValue, max_bytes: usize) { +pub(super) fn compact_large_tool_schema( + mut value: JsonValue, + max_bytes: usize, +) -> serde_json::Result { for pass in LARGE_SCHEMA_COMPACTION_PASSES { - if compact_schema_fits_budget(value, max_bytes) { - break; + let schema = JsonSchema::deserialize(&value)?; + if serialized_json_bytes(&schema).is_ok_and(|bytes| bytes > max_bytes) { + pass(&mut value); + } else { + return Ok(schema); } - pass(value); } + serde_json::from_value(value) } type LargeSchemaCompactionPass = fn(&mut JsonValue); @@ -41,17 +49,6 @@ fn collapse_deep_schema_objects_from_root(value: &mut JsonValue) { collapse_deep_schema_objects(value, /*depth*/ 0); } -fn compact_schema_fits_budget(value: &JsonValue, max_bytes: usize) -> bool { - compact_normalized_schema_len(value) <= max_bytes -} - -fn compact_normalized_schema_len(value: &JsonValue) -> usize { - serde_json::from_value::(value.clone()) - .and_then(|schema| serde_json::to_vec(&schema)) - .map(|json| json.len()) - .unwrap_or(0) -} - fn strip_schema_descriptions(value: &mut JsonValue) { match value { JsonValue::Array(values) => { diff --git a/codex-rs/tools/src/tool_spec.rs b/codex-rs/tools/src/tool_spec.rs index 530da1be16..69bd5845eb 100644 --- a/codex-rs/tools/src/tool_spec.rs +++ b/codex-rs/tools/src/tool_spec.rs @@ -2,7 +2,6 @@ use crate::FreeformTool; use crate::JsonSchema; use crate::LoadableToolSpec; use crate::ResponsesApiNamespace; -use crate::ResponsesApiNamespaceTool; use crate::ResponsesApiTool; use crate::default_namespace_description; use codex_protocol::DEFAULT_FUNCTION_NAMESPACE; @@ -92,34 +91,26 @@ pub fn create_tools_json_for_responses_api( Ok(tools_json) } -pub fn create_tools_json_for_responses_lite( - tools: &[ToolSpec], +pub fn create_tools_json_for_responses_lite<'a>( + tools: impl IntoIterator, ) -> Result, serde_json::Error> { - let mut functions = ResponsesApiNamespace { - name: DEFAULT_FUNCTION_NAMESPACE.to_string(), - description: default_namespace_description(DEFAULT_FUNCTION_NAMESPACE), - tools: Vec::new(), - }; + let mut members = Vec::new(); + let mut description = None; let mut functions_index = None; let mut tools_json = Vec::new(); for tool in tools { match tool { - ToolSpec::Function(tool) => { - functions - .tools - .push(ResponsesApiNamespaceTool::Function(tool.clone())); - } - ToolSpec::Freeform(tool) => { - functions - .tools - .push(ResponsesApiNamespaceTool::Custom(tool.clone())); + ToolSpec::Function(_) | ToolSpec::Freeform(_) => { + members.push(serde_json::to_value(tool)?); } ToolSpec::Namespace(namespace) if namespace.name == DEFAULT_FUNCTION_NAMESPACE => { if !namespace.description.trim().is_empty() { - functions.description = namespace.description.clone(); + description = Some(&namespace.description); + } + for member in &namespace.tools { + members.push(serde_json::to_value(member)?); } - functions.tools.extend(namespace.tools.clone()); } tool => { tools_json.push(serde_json::to_value(tool)?); @@ -130,12 +121,18 @@ pub fn create_tools_json_for_responses_lite( } if let Some(functions_index) = functions_index - && !functions.tools.is_empty() + && !members.is_empty() { - tools_json.insert( - functions_index, - serde_json::to_value(ToolSpec::Namespace(functions))?, - ); + // The serialized bytes feed the additional_tools ID. Keep the namespace field order. + let mut namespace = serde_json::to_value(ToolSpec::Namespace(ResponsesApiNamespace { + name: DEFAULT_FUNCTION_NAMESPACE.to_string(), + description: description + .cloned() + .unwrap_or_else(|| default_namespace_description(DEFAULT_FUNCTION_NAMESPACE)), + tools: Vec::new(), + }))?; + namespace["tools"] = Value::Array(members); + tools_json.insert(functions_index, namespace); } Ok(tools_json) diff --git a/codex-rs/tools/src/tool_spec_tests.rs b/codex-rs/tools/src/tool_spec_tests.rs index d8fcee9cf8..1f206b2bca 100644 --- a/codex-rs/tools/src/tool_spec_tests.rs +++ b/codex-rs/tools/src/tool_spec_tests.rs @@ -163,7 +163,17 @@ fn responses_lite_function(name: &str) -> ResponsesApiTool { #[test] fn responses_lite_groups_default_function_and_custom_tools() { - let tools = create_tools_json_for_responses_lite(&[ + let custom = FreeformTool { + name: "exec".to_string(), + description: "Run code".to_string(), + defer_loading: None, + format: FreeformToolFormat { + r#type: "grammar".to_string(), + syntax: "lark".to_string(), + definition: "start: /.+/".to_string(), + }, + }; + let specs = [ ToolSpec::ToolSearch { execution: "client".to_string(), description: "Search tools".to_string(), @@ -181,16 +191,7 @@ fn responses_lite_groups_default_function_and_custom_tools() { responses_lite_function("edit"), )], }), - ToolSpec::Freeform(FreeformTool { - name: "exec".to_string(), - description: "Run code".to_string(), - defer_loading: None, - format: FreeformToolFormat { - r#type: "grammar".to_string(), - syntax: "lark".to_string(), - definition: "start: /.+/".to_string(), - }, - }), + ToolSpec::Freeform(custom.clone()), ToolSpec::Namespace(ResponsesApiNamespace { name: "functions".to_string(), description: "Existing default tools".to_string(), @@ -199,30 +200,28 @@ fn responses_lite_groups_default_function_and_custom_tools() { )], }), ToolSpec::Function(responses_lite_function("last")), + ]; + let tools = + create_tools_json_for_responses_lite(&specs).expect("serialize Responses Lite tools"); + let expected = create_tools_json_for_responses_api(&[ + specs[0].clone(), + ToolSpec::Namespace(ResponsesApiNamespace { + name: "functions".to_string(), + description: "Existing default tools".to_string(), + tools: vec![ + ResponsesApiNamespaceTool::Function(responses_lite_function("lookup_order")), + ResponsesApiNamespaceTool::Custom(custom), + ResponsesApiNamespaceTool::Function(responses_lite_function("existing")), + ResponsesApiNamespaceTool::Function(responses_lite_function("last")), + ], + }), + specs[2].clone(), ]) - .expect("serialize Responses Lite tools"); - - assert_eq!(tools.len(), 3); - assert_eq!(tools[0]["type"], "tool_search"); - assert_eq!(tools[2]["type"], "namespace"); - assert_eq!(tools[2]["name"], "editor"); - assert_eq!(tools[2]["tools"][0]["name"], "edit"); - assert_eq!(tools[1]["type"], "namespace"); - assert_eq!(tools[1]["name"], "functions"); - assert_eq!(tools[1]["description"], "Existing default tools"); + .expect("serialize expected tool namespaces"); + // These serialized bytes contribute to the additional_tools item ID. assert_eq!( - tools[1]["tools"] - .as_array() - .expect("functions namespace should contain tools") - .iter() - .map(|tool| (tool["type"].as_str(), tool["name"].as_str())) - .collect::>(), - [ - (Some("function"), Some("lookup_order")), - (Some("custom"), Some("exec")), - (Some("function"), Some("existing")), - (Some("function"), Some("last")), - ] + serde_json::to_string(&tools).unwrap(), + serde_json::to_string(&expected).unwrap(), ); }