Lightweight coding agent that runs in your terminal
Rust
Clarify incremental tool namespace updates in Responses Lite (#51119)
Alex Kira402f5b6fdf28
diff --git a/codex-rs/core/src/context/world_state/snapshots/codex_core__context__world_state__top_level_tools__tests__snapshots_namespace_transitions.snap b/codex-rs/core/src/context/world_state/snapshots/codex_core__context__world_state__top_level_tools__tests__snapshots_namespace_transitions.snapindex e6e7956f1d..0684c5eb53 100644--- a/codex-rs/core/src/context/world_state/snapshots/codex_core__context__world_state__top_level_tools__tests__snapshots_namespace_transitions.snap+++ b/codex-rs/core/src/context/world_state/snapshots/codex_core__context__world_state__top_level_tools__tests__snapshots_namespace_transitions.snap@@ -68,7 +68,7 @@ None"role": "developer","tools": [{- "description": "Tools.",+ "description": "Tools.\nThis is an incremental namespace update. Previously declared tools remain available for direct calls unless explicitly marked unavailable. If a tool is redefined here, its latest definition replaces the earlier one.","name": "functions","tools": [{diff --git a/codex-rs/core/src/context/world_state/top_level_tools.rs b/codex-rs/core/src/context/world_state/top_level_tools.rsindex a4b61e9656..873b550040 100644--- a/codex-rs/core/src/context/world_state/top_level_tools.rs+++ b/codex-rs/core/src/context/world_state/top_level_tools.rs@@ -1,5 +1,6 @@//! Diffs the one-level Responses Lite catalog: namespaces of callable tools and built-ins.//! Missing state starts a fresh catalog; this section does not migrate legacy history.+//! Incremental hints decorate emitted declarations only, leaving catalog hashes unchanged.use super::PreviousSectionState;use super::SectionTransition;@@ -15,6 +16,8 @@ use codex_protocol::models::ResponseItem;use serde_json::Value;use std::collections::BTreeMap;+const NAMESPACE_UPDATE_HINT: &str = "This is an incremental namespace update. Previously declared tools remain available for direct calls unless explicitly marked unavailable. If a tool is redefined here, its latest definition replaces the earlier one.";+/// The exact serialized Responses Lite declarations visible in one captured step.pub(crate) struct TopLevelToolsState {definitions: Vec<Value>,@@ -100,6 +103,14 @@ impl WorldStateSection for TopLevelToolsState {if !members.is_empty() {let mut namespace = definition.clone();namespace["tools"] = Value::Array(members);+ if previous.is_some_and(|previous| previous.contains_key(name)) {+ let description = definition["description"].as_str().unwrap_or_default();+ namespace["description"] = Value::String(if description.is_empty() {+ NAMESPACE_UPDATE_HINT.to_string()+ } else {+ format!("{description}\n{NAMESPACE_UPDATE_HINT}")+ });+ }tools.push(namespace);} else if changed(name) {// Namespace declarations require a member. Update metadata as text withoutdiff --git a/codex-rs/core/src/context/world_state/top_level_tools_tests.rs b/codex-rs/core/src/context/world_state/top_level_tools_tests.rsindex 5a35ae9cb1..1145d69340 100644--- a/codex-rs/core/src/context/world_state/top_level_tools_tests.rs+++ b/codex-rs/core/src/context/world_state/top_level_tools_tests.rs@@ -96,6 +96,11 @@ fn initial_catalog_preserves_order_and_unchanged_catalog_emits_nothing() {];let state = TopLevelToolsState::new(definitions.clone()).unwrap();let (snapshot, updates) = state.render_diff(PreviousSectionState::Absent);+ assert_eq!(+ merge_world_state_updates(updates),+ vec![item(definitions.clone())]+ );+ let (_, updates) = state.render_diff(PreviousSectionState::Unknown);assert_eq!(merge_world_state_updates(updates), vec![item(definitions)]);let snapshot = snapshot.unwrap();assert_eq!(@@ -159,10 +164,12 @@ fn namespace_diff_contains_only_changed_and_added_tools() {]).unwrap();let (snapshot, updates) = current.render_diff(PreviousSectionState::Known(&snapshot));+ let mut expected = namespace("functions", vec![changed, added]);+ expected["description"] = json!(format!("Tools.\n{NAMESPACE_UPDATE_HINT}"));assert_eq!(merge_world_state_updates(updates),vec![- item(vec![namespace("functions", vec![changed, added])]),+ item(vec![expected]),ContextualUserFragment::into(RemovedTools(vec!["functions.removed".to_string()])),]);@@ -213,9 +220,10 @@ fn tool_type_change_keeps_the_callable_name_available() {.unwrap();let custom = json!({"type": "custom", "name": "lookup", "description": "Look up a value.","format": {"type": "text"}});- let updated = namespace("functions", vec![custom]);+ let mut updated = namespace("functions", vec![custom]);let current = TopLevelToolsState::new(vec![updated.clone()]).unwrap();let (_, updates) = current.render_diff(PreviousSectionState::Known(&snapshot));+ updated["description"] = json!(format!("Tools.\n{NAMESPACE_UPDATE_HINT}"));assert_eq!(merge_world_state_updates(updates),vec![diff --git a/codex-rs/core/tests/suite/scenarios_incremental_tools.rs b/codex-rs/core/tests/suite/scenarios_incremental_tools.rsindex 6c26a5495b..57c0c3f3ee 100644--- a/codex-rs/core/tests/suite/scenarios_incremental_tools.rs+++ b/codex-rs/core/tests/suite/scenarios_incremental_tools.rs@@ -1,6 +1,7 @@//! Request-history coverage for opt-in incremental tools on Responses Lite.use anyhow::Result;+use codex_core::ConfigRefreshOutcome;use codex_features::Feature;use codex_history::RolloutItem;use codex_protocol::openai_models::CodeModeToolMessages;@@ -11,11 +12,16 @@ use core_test_support::context_snapshot;use core_test_support::context_snapshot::ContextSnapshotOptions;use core_test_support::responses;use core_test_support::skip_if_no_network;+use core_test_support::skip_if_wine_exec;use core_test_support::test_codex::test_codex;+use core_test_support::wait_for_mcp_server;use pretty_assertions::assert_eq;use serde_json::json;use test_case::test_case;+use super::super::rmcp_client::remote_aware_environment_id;+use super::super::rmcp_client::remote_aware_stdio_server_bin;+#[test_case(true; "responses_lite")]#[test_case(false; "responses_api")]#[tokio::test(flavor = "multi_thread", worker_threads = 2)]@@ -26,7 +32,7 @@ async fn incremental_tools_append_changed_catalog_without_rewriting_history(let server = responses::start_mock_server().await;let mock = responses::mount_sse_sequence(&server,- (1..=3)+ (1..=4).map(|index| responses::sse(vec![responses::ev_completed(&format!("resp-{index}"))])).collect(),)@@ -80,9 +86,11 @@ async fn incremental_tools_append_changed_catalog_without_rewriting_history(.await?;test.submit_text_turn("Continue with the updated execution instructions.").await?;+ test.submit_text_turn("Continue with the same updated tools.")+ .await?;let requests = mock.requests();- assert_eq!(requests.len(), 3);+ assert_eq!(requests.len(), 4);if !use_responses_lite {for request in &requests {let body = request.body_json();@@ -104,10 +112,15 @@ async fn incremental_tools_append_changed_catalog_without_rewriting_history(requests[1].body_json()["tools"],requests[2].body_json()["tools"]);+ assert_eq!(+ requests[2].body_json()["tools"],+ requests[3].body_json()["tools"]+ );return Ok(());}assert!(requests[1].input().starts_with(&requests[0].input()));assert!(requests[2].input().starts_with(&requests[1].input()));+ assert!(requests[3].input().starts_with(&requests[2].input()));assert!(requests.iter()@@ -134,6 +147,13 @@ async fn incremental_tools_append_changed_catalog_without_rewriting_history(.expect("changed tool array");assert_eq!(diff.len(), 1);assert_eq!(diff[0]["name"], "functions");+ assert_eq!(initial[0]["tools"][0]["description"], json!(""));+ assert_eq!(+ diff[0]["description"],+ json!(+ "This is an incremental namespace update. Previously declared tools remain available for direct calls unless explicitly marked unavailable. If a tool is redefined here, its latest definition replaces the earlier one."+ )+ );let changed_tools = diff[0]["tools"].as_array().expect("namespace members");assert_eq!(changed_tools.len(), 1);assert_eq!(changed_tools[0]["name"], "exec");@@ -144,6 +164,7 @@ async fn incremental_tools_append_changed_catalog_without_rewriting_history(.to_string().contains("Updated execution instructions."));+ assert_eq!(requests[3].inputs_of_type("additional_tools"), changed);test.codex.ensure_rollout_materialized().await;test.codex.flush_rollout().await?;@@ -181,7 +202,135 @@ async fn incremental_tools_append_changed_catalog_without_rewriting_history(insta::assert_snapshot!("incremental_tools",context_snapshot::format_request_history_snapshot(- "Tool definitions enter history in one batch; a catalog change appends only the changed exec definition.",+ "Tool definitions enter history in one batch; a catalog change appends only the changed exec definition with an incremental namespace hint. The next unchanged turn appends no tool definitions.",+ &requests,+ &ContextSnapshotOptions::default()+ .rewrite_known_segments()+ .include_request_settings(),+ )+ );+ Ok(())+}++#[tokio::test(flavor = "multi_thread", worker_threads = 2)]+async fn tool_removal_appends_a_standalone_notice_without_rewriting_history() -> Result<()> {+ skip_if_wine_exec!(+ Ok(()),+ "requires a Windows test_stdio_server in the Wine-exec environment"+ );+ skip_if_no_network!(Ok(()));+ let server = responses::start_mock_server().await;+ let command = remote_aware_stdio_server_bin()?;+ let environment_id = remote_aware_environment_id();+ let server_config = |enabled_tools: &[&str]| {+ serde_json::from_value(json!({+ "command": command,+ "environment_id": environment_id,+ "env": {"MCP_TEST_SERVER_INSTRUCTIONS": "Echo service instructions."},+ "enabled_tools": enabled_tools,+ "default_tools_approval_mode": "approve",+ }))+ };+ let initial_server = server_config(&["echo", "cwd"])?;+ let reduced_server = server_config(&["echo"])?;+ let test = test_codex()+ .with_model_info_override("gpt-5.5", |model| {+ model.use_responses_lite = true;+ model.supports_search_tool = false;+ model.tool_mode = Some(ToolMode::Direct);+ })+ .with_config(move |config| {+ config+ .features+ .enable(Feature::IncrementalTools)+ .expect("enable incremental tools");+ config+ .mcp_servers+ .set(std::collections::HashMap::from([(+ "echo_service".to_string(),+ initial_server,+ )]))+ .expect("set MCP fixture");+ })+ .build_with_auto_env(&server)+ .await?;+ wait_for_mcp_server(&test.codex, "echo_service").await?;+ let mock = responses::mount_sse_sequence(+ &server,+ (1..=3)+ .map(|index| responses::sse(vec![responses::ev_completed(&format!("resp-{index}"))]))+ .collect(),+ )+ .await;+ test.submit_text_turn("Begin with the echo service.")+ .await?;++ // Remove one member while keeping the namespace instructions and echo schema unchanged.+ let current_config = test.codex.config().await;+ let mut reduced_config = current_config.as_ref().clone();+ reduced_config+ .mcp_servers+ .set(std::collections::HashMap::from([(+ "echo_service".to_string(),+ reduced_server,+ )]))?;+ assert_eq!(+ test.codex+ .refresh_mcp_config(current_config, reduced_config)+ .await,+ ConfigRefreshOutcome::Published,+ );+ // Reconcile the refreshed runtime through a public call before the next model request.+ let result = test+ .codex+ .call_mcp_tool(+ "echo_service",+ "echo",+ Some(json!({"message": "ready after removal"})),+ /*meta*/ None,+ )+ .await?;+ assert_ne!(result.is_error, Some(true));+ test.submit_text_turn("Continue after disabling the cwd tool.")+ .await?;+ test.submit_text_turn("Continue with the remaining echo tool.")+ .await?;++ let requests = mock.requests();+ assert_eq!(requests.len(), 3);+ assert!(requests[1].has_content_kinds(&["tools.removed_definition"]));+ let initial_tools = requests[0].inputs_of_type("additional_tools");+ for pair in requests.windows(2) {+ assert!(pair[1].input().starts_with(&pair[0].input()));+ assert_eq!(pair[1].inputs_of_type("additional_tools"), initial_tools);+ }+ let removed_input = requests[1].input();+ let updates = &removed_input[requests[0].input().len()..];+ assert_eq!(+ updates.len(),+ 2,+ "removal appends a standalone notice and user input"+ );+ assert_eq!(updates[0]["role"], "developer");+ assert_eq!(+ updates[0]["content"],+ json!([{+ "type": "input_text",+ "text": "The following tools are no longer available. Do not call them:\n- mcp__echo_service.cwd",+ }])+ );+ let unchanged_input = requests[2].input();+ let follow_up = &unchanged_input[removed_input.len()..];+ assert_eq!(follow_up.len(), 1, "unchanged turn appends only user input");+ assert_eq!(follow_up[0]["role"], "user");+ assert_eq!(+ follow_up[0]["content"],+ json!([{"type": "input_text", "text": "Continue with the remaining echo tool."}])+ );+ insta::assert_snapshot!(+ "incremental_tool_removals",+ context_snapshot::format_request_history_snapshot(+ "An MCP configuration refresh removes one tool while preserving its namespace and other member. A standalone removal notice preserves earlier declarations and is not repeated on the next turn.",&requests,&ContextSnapshotOptions::default().rewrite_known_segments()diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__incremental_tools__incremental_tool_removals.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__incremental_tools__incremental_tool_removals.snapnew file mode 100644index 0000000000..e531f7f5bf--- /dev/null+++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__incremental_tools__incremental_tool_removals.snap@@ -0,0 +1,54 @@+---+source: core/tests/suite/scenarios_incremental_tools.rs+expression: "context_snapshot::format_request_history_snapshot(\"An MCP configuration refresh removes one tool while preserving its namespace and other member. A standalone removal notice preserves earlier declarations and is not repeated on the next turn.\",\n&requests,\n&ContextSnapshotOptions::default().rewrite_known_segments().include_request_settings(),)"+---+Scenario: An MCP configuration refresh removes one tool while preserving its namespace and other member. A standalone removal notice preserves earlier declarations and is not repeated on the next turn.++## Window 1+Settings:+ include: ["reasoning.encrypted_content"]+ model: "gpt-5.5"+ parallel_tool_calls: false+ prompt_cache_key: "<PROMPT_CACHE_KEY 1>"+ reasoning: {"context":"all_turns","effort":"medium"}+ store: false+ stream: true+ text: {"verbosity":"low"}+ tool_choice: "auto"+-- request 1 (turn) --+00:message/developer:+ <MODEL_INSTRUCTIONS>+01:additional_tools/developer (3; hash=7748a53142f449b7):+ - namespace/functions; hash=124fee69a69ed6b2+ - function/exec_command+ - function/write_stdin+ - function/list_mcp_resources+ - function/list_mcp_resource_templates+ - function/read_mcp_resource+ - function/request_user_input+ - custom/apply_patch+ - function/view_image+ - namespace/multi_agent_v1: Tools for spawning and managing sub-agents.; hash=2327142bda177c50+ - function/close_agent+ - function/resume_agent+ - function/send_input+ - function/spawn_agent+ - function/wait_agent+ - namespace/mcp__echo_service: Echo service instructions.; hash=a5144e5d70d01799+ - function/cwd+ - function/echo+02:message/developer:+ <PERMISSIONS_INSTRUCTIONS>+03:message/user:+ <ENVIRONMENT_CONTEXT>+04:message/user:+ Begin with the echo service.+-- request 2 (turn) --+05:message/developer:+ The following tools are no longer available. Do not call them:+ - mcp__echo_service.cwd+06:message/user:+ Continue after disabling the cwd tool.+-- request 3 (turn) --+07:message/user:+ Continue with the remaining echo tool.diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__incremental_tools__incremental_tools.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__incremental_tools__incremental_tools.snapindex 7af84a0d9b..0e344e1cd7 100644--- a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__incremental_tools__incremental_tools.snap+++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__incremental_tools__incremental_tools.snap@@ -1,8 +1,8 @@---source: core/tests/suite/scenarios_incremental_tools.rs-expression: "context_snapshot::format_request_history_snapshot(\"Tool definitions enter history in one batch; a catalog change appends only the changed exec definition.\",\n&requests,\n&ContextSnapshotOptions::default().rewrite_known_segments().include_request_settings(),)"+expression: "context_snapshot::format_request_history_snapshot(\"Tool definitions enter history in one batch; a catalog change appends only the changed exec definition with an incremental namespace hint. The next unchanged turn appends no tool definitions.\",\n&requests,\n&ContextSnapshotOptions::default().rewrite_known_segments().include_request_settings(),)"----Scenario: Tool definitions enter history in one batch; a catalog change appends only the changed exec definition.+Scenario: Tool definitions enter history in one batch; a catalog change appends only the changed exec definition with an incremental namespace hint. The next unchanged turn appends no tool definitions.## Window 1Settings:@@ -62,10 +62,13 @@ Settings: relative to window 1Begin work.05:message/user:Continue with the same tools.-06:additional_tools/developer (1; hash=26cd263a29587cc7):- - namespace/functions; hash=771cad2ff250d2f3+06:additional_tools/developer (1; hash=fd00dfa0a0c11da2):+ - namespace/functions: This is an incremental namespace update. Previously declared tools remain available for direct ca...; hash=dd09638a0d29d0ca- custom/exec07:message/developer:<MODEL_SWITCH>08:message/user:Continue with the updated execution instructions.+-- request 4 (turn) --+09:message/user:+ Continue with the same updated tools.