diff --git a/codex-rs/core/config.schema.json b/codex-rs/core/config.schema.json index 7fcf348063..a476a776df 100644 --- a/codex-rs/core/config.schema.json +++ b/codex-rs/core/config.schema.json @@ -5111,6 +5111,10 @@ "maxLength": 2000, "type": "string" }, + "context_window_as_tool_output": { + "description": "Render the context window and its hints as an agent.thread_hint tool output.", + "type": "boolean" + }, "enabled": { "type": "boolean" }, diff --git a/codex-rs/core/src/config/config_tests.rs b/codex-rs/core/src/config/config_tests.rs index e1b9fae84d..31e5022261 100644 --- a/codex-rs/core/src/config/config_tests.rs +++ b/codex-rs/core/src/config/config_tests.rs @@ -772,6 +772,7 @@ auto_compact_fallback_buffer_tokens = 8000 "#, Some(TokenBudgetConfig { use_history_notes_extension: true, + context_window_as_tool_output: false, reminder_threshold_tokens: Some(16_000), reminder_message_template: "Custom reminder: {n_remaining} tokens.".to_string(), guidance_message: Some("Preserve important state before compaction.".to_string()), diff --git a/codex-rs/core/src/config/mod.rs b/codex-rs/core/src/config/mod.rs index 2194413f4c..c1811f362d 100644 --- a/codex-rs/core/src/config/mod.rs +++ b/codex-rs/core/src/config/mod.rs @@ -1288,6 +1288,7 @@ const AUTO_COMPACT_FALLBACK_PROMPT_MAX_BYTES: usize = 2000; #[derive(Debug, Clone, PartialEq, Eq, Serialize)] pub struct TokenBudgetConfig { pub use_history_notes_extension: bool, + pub context_window_as_tool_output: bool, pub reminder_threshold_tokens: Option, pub reminder_message_template: String, pub guidance_message: Option, @@ -1381,6 +1382,7 @@ impl Default for TokenBudgetConfig { fn default() -> Self { Self { use_history_notes_extension: false, + context_window_as_tool_output: false, reminder_threshold_tokens: None, reminder_message_template: ResolvedModelMessages::bundled() .token_budget_reminder_template() @@ -3030,6 +3032,9 @@ pub(crate) fn resolve_token_budget_config( let token_budget = TokenBudgetConfig { use_history_notes_extension, + context_window_as_tool_output: token_budget_config + .and_then(|config| config.context_window_as_tool_output) + .unwrap_or_default(), reminder_threshold_tokens, reminder_message_template, guidance_message, diff --git a/codex-rs/core/src/context/token_budget_context.rs b/codex-rs/core/src/context/token_budget_context.rs index fea07d3385..0f2fe8a36a 100644 --- a/codex-rs/core/src/context/token_budget_context.rs +++ b/codex-rs/core/src/context/token_budget_context.rs @@ -1,14 +1,18 @@ use super::ContextualUserFragment; use super::world_state::PreviousSectionState; use super::world_state::WorldStateSection; +use crate::config::TokenBudgetConfig; +use crate::context::world_state::Placement; use crate::context::world_state::SectionTransition; use crate::context::world_state::WorldStateUpdate; +use crate::context::world_state::WorldStateUpdateContent; +use crate::state::AutoCompactWindowIds; use codex_context_fragments::AnnotatedContent; use codex_context_fragments::message_from_parts; use codex_protocol::AgentPath; -use codex_protocol::ContextWindowId; use codex_protocol::models::ContentItem; use codex_protocol::models::ContentItemKind; +use codex_protocol::models::FunctionCallOutputPayload; use codex_protocol::models::ResponseItem; use codex_protocol::models::input_text; use codex_protocol::protocol::CONTEXT_WINDOW_CLOSE_TAG; @@ -19,28 +23,56 @@ use codex_protocol::protocol::CONTEXT_WINDOW_OPEN_TAG; #[derive(Debug, Clone, PartialEq, Eq)] pub(crate) struct TokenBudgetContext { agent_path: AgentPath, - first_window_id: ContextWindowId, - previous_window_id: Option, - window_id: ContextWindowId, + ids: AutoCompactWindowIds, + as_tool_output: bool, } impl TokenBudgetContext { pub(crate) fn new( agent_path: AgentPath, - first_window_id: ContextWindowId, - previous_window_id: Option, - window_id: ContextWindowId, + ids: AutoCompactWindowIds, + token_budget: Option<&TokenBudgetConfig>, ) -> Self { Self { agent_path, - first_window_id, - previous_window_id, - window_id, + ids, + as_tool_output: token_budget.is_some_and(|budget| budget.context_window_as_tool_output), } } - /// Wraps tool hints without losing their source or changing the concatenated prompt text. + fn description(&self) -> String { + let first_window_id = &self.ids.first_window_id; + let window_id = &self.ids.window_id; + let mut lines = vec![ + format!("Agent name: {}", self.agent_path), + format!("First context window id: {first_window_id}"), + format!("Current context window id: {window_id}"), + ]; + if let Some(previous_window_id) = &self.ids.previous_window_id { + lines.push(format!("Previous context window id: {previous_window_id}")); + } + lines.join("\n") + } + + /// Renders the window fields together with any hints supplied for this window. pub(crate) fn render_with_hints(&self, hints: Vec) -> ResponseItem { + if self.as_tool_output { + let mut text = self.description(); + for hint in hints { + if let Some(hint) = hint.into_parts().0.into_text() { + text.push('\n'); + text.push_str(&hint); + } + } + return ResponseItem::FunctionCallOutput { + id: None, + call_id: None, + namespace: Some("agent".into()), + name: Some("thread_hint".into()), + output: FunctionCallOutputPayload::from_text(text), + internal_chat_message_metadata_passthrough: None, + }; + } let (open, close) = self.markers(); let annotate = |content| { AnnotatedContent::from_parts(content, self.content_kind(), self.content_metadata()) @@ -73,17 +105,7 @@ impl ContextualUserFragment for TokenBudgetContext { } fn body(&self) -> ContentItem { - let first_window_id = &self.first_window_id; - let window_id = &self.window_id; - let mut lines = vec![ - format!("Agent name: {}", self.agent_path), - format!("First context window id: {first_window_id}"), - format!("Current context window id: {window_id}"), - ]; - if let Some(previous_window_id) = &self.previous_window_id { - lines.push(format!("Previous context window id: {previous_window_id}")); - } - input_text(format!("\n{}\n", lines.join("\n"))) + input_text(format!("\n{}\n", self.description())) } } @@ -95,10 +117,20 @@ impl WorldStateSection for TokenBudgetContext { &self, previous: PreviousSectionState<'_, Self::Snapshot>, ) -> SectionTransition { - let current = self.agent_path.clone(); - let fragment = matches!(previous, PreviousSectionState::Known(agent_path) if agent_path != &self.agent_path) - .then(|| WorldStateUpdate::fragment(self.clone()).standalone()); - (Some(current), fragment.into_iter().collect()) + let mut updates = Vec::new(); + if matches!(previous, PreviousSectionState::Known(path) if path != &self.agent_path) { + updates.push(if self.as_tool_output { + WorldStateUpdate { + placement: Placement::Standalone, + content: WorldStateUpdateContent::Item(Box::new( + self.render_with_hints(Vec::new()), + )), + } + } else { + WorldStateUpdate::fragment(self.clone()).standalone() + }); + } + (Some(self.agent_path.clone()), updates) } } diff --git a/codex-rs/core/src/session/mod.rs b/codex-rs/core/src/session/mod.rs index f323f7c850..1d438fce8e 100644 --- a/codex-rs/core/src/session/mod.rs +++ b/codex-rs/core/src/session/mod.rs @@ -5109,7 +5109,7 @@ impl Session { let turn_context = step_context.turn.as_ref(); let mut developer_sections = Vec::::with_capacity(8); let mut contextual_user_sections = Vec::::with_capacity(2); - let mut separate_developer_messages = Vec::::new(); + let mut standalone_items = Vec::::new(); let mut context_window_hints = Vec::new(); let (session_source, auto_compact_window_ids) = { let state = self.state.lock().await; @@ -5233,14 +5233,13 @@ impl Session { ContentItemMetadata::tool(source_tool_namespace.map(Into::into)), )); } - separate_developer_messages.push( + standalone_items.push( crate::context::TokenBudgetContext::new( session_source .get_agent_path() .unwrap_or_else(codex_protocol::AgentPath::root), - auto_compact_window_ids.first_window_id, - auto_compact_window_ids.previous_window_id, - auto_compact_window_ids.window_id, + auto_compact_window_ids, + step_context.token_budget.as_ref(), ) .render_with_hints(context_window_hints), ); @@ -5281,13 +5280,13 @@ impl Session { "developer" if fragment.markers().0 == MultiAgentRoleInstructions::type_markers().0 => { - separate_developer_messages.push(fragment.render_fragment().into()); + standalone_items.push(fragment.render_fragment().into()); } "developer" if update.placement == Placement::Standalone && fragment.markers().0.is_empty() => { - separate_developer_messages.push(fragment.render_fragment().into()); + standalone_items.push(fragment.render_fragment().into()); } "developer" => developer_sections.push(fragment.render_fragment()), "user" => contextual_user_sections.push(fragment.render_fragment()), @@ -5313,7 +5312,7 @@ impl Session { ) { items.push(developer_message); } - items.append(&mut separate_developer_messages); + items.append(&mut standalone_items); if let Some(initial_multi_agent_mode) = initial_multi_agent_mode && let Some(message) = crate::context_manager::updates::build_rendered_message(vec![ diff --git a/codex-rs/core/src/session/token_budget.rs b/codex-rs/core/src/session/token_budget.rs index 6e77a57a36..0f77201d26 100644 --- a/codex-rs/core/src/session/token_budget.rs +++ b/codex-rs/core/src/session/token_budget.rs @@ -64,13 +64,17 @@ pub(super) fn has_explicit_settings(config: &Config) -> bool { .and_then(|features| features.get("token_budget")) .and_then(|token_budget| token_budget.as_table()) .is_some_and(|settings| { - settings - .keys() - .any(|key| !matches!(key.as_str(), "enabled" | "use_history_notes_extension")) + settings.keys().any(|key| { + !matches!( + key.as_str(), + "enabled" | "use_history_notes_extension" | "context_window_as_tool_output" + ) + }) }) || config.token_budget.as_ref().is_some_and(|token_budget| { let mut settings = token_budget.clone(); settings.use_history_notes_extension = false; + settings.context_window_as_tool_output = false; settings != TokenBudgetConfig::default() }) } @@ -94,6 +98,8 @@ pub(super) fn resolve_token_budget( }; let token_budget = TokenBudgetConfig { + context_window_as_tool_output: configured_token_budget + .is_some_and(|budget| budget.context_window_as_tool_output), use_history_notes_extension: configured_token_budget .is_some_and(|token_budget| token_budget.use_history_notes_extension), reminder_threshold_tokens: Some(model_defaults.reminder_threshold_tokens), diff --git a/codex-rs/core/src/session/world_state.rs b/codex-rs/core/src/session/world_state.rs index fa02844b5e..b0a8c7d44c 100644 --- a/codex-rs/core/src/session/world_state.rs +++ b/codex-rs/core/src/session/world_state.rs @@ -233,9 +233,8 @@ impl Session { .session_source .get_agent_path() .unwrap_or_else(codex_protocol::AgentPath::root), - window_ids.first_window_id, - window_ids.previous_window_id, - window_ids.window_id, + window_ids, + step_context.token_budget.as_ref(), )); } let guidance = step_context diff --git a/codex-rs/core/tests/common/test_codex.rs b/codex-rs/core/tests/common/test_codex.rs index 68f76f2d6d..2ce2fccba9 100644 --- a/codex-rs/core/tests/common/test_codex.rs +++ b/codex-rs/core/tests/common/test_codex.rs @@ -19,6 +19,8 @@ use codex_agent_graph_store::AgentGraphStore; use codex_analytics::AnalyticsEventsClient; use codex_attachment_store::AttachmentStore; use codex_config::CloudConfigBundleLoader; +use codex_config::ConfigLayerSource; +use codex_config::ConfigLayerStack; use codex_core::CodexThread; pub use codex_core::StartThreadOptions; use codex_core::ThreadManager; @@ -1072,6 +1074,24 @@ impl TestCodexBuilder { } } +pub fn configure_scenario_catalog(config: &mut Config) { + // Keep the fixture independent of the checkout's project configuration. + let stack = &config.config_layer_stack; + config.config_layer_stack = ConfigLayerStack::new( + stack + .all_layers_low_to_high() + .filter(|layer| !matches!(&layer.name, ConfigLayerSource::Project { .. })) + .cloned() + .collect(), + stack.requirements().clone(), + stack.requirements_toml().clone(), + ) + .expect("fixture config layers") + .with_cloud_config_binding(stack.cloud_config_binding().cloned()); + config.model_catalog = Some(bundled_models_response().expect("bundled model catalog")); + config.cloud_skill_enabled = false; +} + fn ensure_test_model_catalog(config: &mut Config) -> Result<()> { if config.model.as_deref() != Some(TEST_MODEL_WITH_EXPERIMENTAL_TOOLS) || config.model_catalog.is_some() diff --git a/codex-rs/core/tests/suite/mcp_tool_cache.rs b/codex-rs/core/tests/suite/mcp_tool_cache.rs index f62ced8732..f5ef2f6a13 100644 --- a/codex-rs/core/tests/suite/mcp_tool_cache.rs +++ b/codex-rs/core/tests/suite/mcp_tool_cache.rs @@ -615,7 +615,7 @@ pub(super) async fn cached_stdio_first_use_scenario() -> anyhow::Result UserInput { } } -pub(super) fn configure_scenario_catalog(config: &mut Config) { - // Keep the fixture independent of the checkout's project configuration. - let stack = &config.config_layer_stack; - config.config_layer_stack = ConfigLayerStack::new( - stack - .all_layers_low_to_high() - .filter(|layer| !matches!(&layer.name, ConfigLayerSource::Project { .. })) - .cloned() - .collect(), - stack.requirements().clone(), - stack.requirements_toml().clone(), - ) - .expect("fixture config layers") - .with_cloud_config_binding(stack.cloud_config_binding().cloned()); - config.model_catalog = Some(bundled_models_response().expect("bundled model catalog")); - config.cloud_skill_enabled = false; -} - fn configure_catalog_plugin_scenario(config: &mut Config) { configure_scenario_catalog(config); config.workspace_roots = vec![config.cwd.clone()]; @@ -3380,6 +3363,7 @@ async fn prediction_fork_preserves_context_above_compaction_threshold() -> Resul .enable(Feature::TokenBudget) .expect("enable token budget"); config.token_budget = Some(TokenBudgetConfig { + context_window_as_tool_output: true, reminder_threshold_tokens: Some(2_000), ..TokenBudgetConfig::default() }); diff --git a/codex-rs/core/tests/suite/scenarios_partial_answers.rs b/codex-rs/core/tests/suite/scenarios_partial_answers.rs index 02de73308d..8ac350133b 100644 --- a/codex-rs/core/tests/suite/scenarios_partial_answers.rs +++ b/codex-rs/core/tests/suite/scenarios_partial_answers.rs @@ -192,6 +192,14 @@ async fn partial_answers_survive_forked_child_requests( } if preserve_fork_prefix { config.update_plan_enabled = true; + config + .features + .enable(Feature::TokenBudget) + .expect("enable token budget"); + config.token_budget = Some(TokenBudgetConfig { + context_window_as_tool_output: true, + ..Default::default() + }); config.multi_agent_v2.root_agent_usage_hint_text = Some("You are /root. Coordinate the investigation.".into()); config.multi_agent_v2.subagent_usage_hint_text = @@ -325,7 +333,7 @@ async fn partial_answers_survive_forked_child_requests( insta::assert_snapshot!( "preserved_answer_fork", context_snapshot::format_request_history_snapshot( - "A worker inherits the parent prefix unchanged and receives its own instructions. Requests are grouped by parent, then child.", + "A worker inherits the parent prefix, then receives its own window hint and instructions. Requests are grouped by parent, then child.", &requests, &ContextSnapshotOptions::default().rewrite_known_segments() ) diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__partial_answers__preserved_answer_fork.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__partial_answers__preserved_answer_fork.snap index ed680bef91..7de5c6a6f5 100644 --- a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__partial_answers__preserved_answer_fork.snap +++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__partial_answers__preserved_answer_fork.snap @@ -1,16 +1,17 @@ --- source: core/tests/suite/scenarios_partial_answers.rs -expression: "context_snapshot::format_request_history_snapshot(\"A worker inherits the parent prefix unchanged and receives its own instructions. Requests are grouped by parent, then child.\",\n&requests, &ContextSnapshotOptions::default().rewrite_known_segments())" +expression: "context_snapshot::format_request_history_snapshot(\"A worker inherits the parent prefix, then receives its own window hint and instructions. Requests are grouped by parent, then child.\",\n&requests, &ContextSnapshotOptions::default().rewrite_known_segments())" --- -Scenario: A worker inherits the parent prefix unchanged and receives its own instructions. Requests are grouped by parent, then child. +Scenario: A worker inherits the parent prefix, then receives its own window hint and instructions. Requests are grouped by parent, then child. ## Window 1 -- request 1 (turn) -- -00:additional_tools/developer (2; hash=855bf977570202a9): - - namespace/functions; hash=2e61665749f6eed1 +00:additional_tools/developer (2; hash=83c28a07e06c911d): + - namespace/functions; hash=23e0bd95ef50816d - custom/exec - function/wait - function/request_user_input + - function/new_context - namespace/collaboration: Tools for spawning and managing sub-agents.; hash=2c8d6295978dbe63 - function/followup_task - function/interrupt_agent @@ -20,37 +21,51 @@ Scenario: A worker inherits the parent prefix unchanged and receives its own ins - function/wait_agent 01:message/developer: -02:message/developer[2]: +02:message/developer[3]: [01] Coordinate the investigation. - [02] -03:message/developer: - You are /root. Coordinate the investigation. + [02] + For tasks that may span context windows, use `notes` to maintain a concise checkpoint of the goal, decis... notes, but writes are limited to the current thread. [hash=3eea124e6983e23d] + + It is a good idea to take incremental notes while you work so that you do not miss any important info. Y...ver-run the context window without any documentation. [hash=6d014a8420d908e2] + + If Previous context window id is present in ``, it means a context reset occurred and th...tems`, or `search_contents` to locate the item first. [hash=e2d9878e9e72f8c8] + + Treat notes and history as internal bookkeeping. Do not mention them in user-facing messages. + + + [03] +03:function_call_output/agent.thread_hint:Agent name: /root + First context window id: + Current context window id: 04:message/developer: + You are /root. Coordinate the investigation. +05:message/developer: -05:message/user: - 06:message/user: + +07:message/user: Give me both results. -- request 2 (turn) -- -07:message/assistant: - The first result is ready. 08:message/assistant: - Checking the remaining result. + The first result is ready. 09:message/assistant: + Checking the remaining result. +10:message/assistant: The second result is ready. -10:message/user: +11:message/user: Have a worker check both results. -- request 3 (turn) -- -11:function_call/collaboration.spawn_agent:{"fork_turns":"all","message":"Check both inherited results.","task_name":"worker"} -12:function_call_output:{"task_name":"/root/worker"} +12:function_call/collaboration.spawn_agent:{"fork_turns":"all","message":"Check both inherited results.","task_name":"worker"} +13:function_call_output:{"task_name":"/root/worker"} -## Window 2 (after request 3: input diverged at item 12) +## Window 2 (after request 3: input diverged at item 13) -- request 4 (turn) -- -00:additional_tools/developer (2; hash=855bf977570202a9): - - namespace/functions; hash=2e61665749f6eed1 +00:additional_tools/developer (2; hash=83c28a07e06c911d): + - namespace/functions; hash=23e0bd95ef50816d - custom/exec - function/wait - function/request_user_input + - function/new_context - namespace/collaboration: Tools for spawning and managing sub-agents.; hash=2c8d6295978dbe63 - function/followup_task - function/interrupt_agent @@ -60,33 +75,49 @@ Scenario: A worker inherits the parent prefix unchanged and receives its own ins - function/wait_agent 01:message/developer: -02:message/developer[2]: +02:message/developer[3]: [01] Coordinate the investigation. - [02] -03:message/developer: - You are /root. Coordinate the investigation. + [02] + For tasks that may span context windows, use `notes` to maintain a concise checkpoint of the goal, decis... notes, but writes are limited to the current thread. [hash=3eea124e6983e23d] + + It is a good idea to take incremental notes while you work so that you do not miss any important info. Y...ver-run the context window without any documentation. [hash=6d014a8420d908e2] + + If Previous context window id is present in ``, it means a context reset occurred and th...tems`, or `search_contents` to locate the item first. [hash=e2d9878e9e72f8c8] + + Treat notes and history as internal bookkeeping. Do not mention them in user-facing messages. + + + [03] +03:function_call_output/agent.thread_hint:Agent name: /root + First context window id: + Current context window id: 04:message/developer: + You are /root. Coordinate the investigation. +05:message/developer: -05:message/user: - 06:message/user: + +07:message/user: Give me both results. -07:message/assistant: - The first result is ready. 08:message/assistant: - Checking the remaining result. + The first result is ready. 09:message/assistant: + Checking the remaining result. +10:message/assistant: The second result is ready. -10:message/user: +11:message/user: Have a worker check both results. -11:function_call/collaboration.spawn_agent:{"fork_turns":"all","message":"Check both inherited results.","task_name":"worker"} -12:function_call_output:aborted -13:message/developer: - You are now a newly spawned child agent. The preceding conversation is inherited parent context. Follow ...are not inherited. Report your result to your parent. [hash=0e586a5d405d39db] +12:function_call/collaboration.spawn_agent:{"fork_turns":"all","message":"Check both inherited results.","task_name":"worker"} +13:function_call_output:aborted 14:message/developer: - Check both results independently. + You are now a newly spawned child agent. The preceding conversation is inherited parent context. Follow ...are not inherited. Report your result to your parent. [hash=0e586a5d405d39db] 15:message/developer: - You are a worker. Report to your parent. + Check both results independently. 16:message/developer: + You are a worker. Report to your parent. +17:function_call_output/agent.thread_hint:Agent name: /root/worker + First context window id: + Current context window id: +18:message/developer: -17:agent_message +19:agent_message diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__prediction_fork_preserves_context_above_compaction_threshold.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__prediction_fork_preserves_context_above_compaction_threshold.snap index d3a702107c..ef0b795904 100644 --- a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__prediction_fork_preserves_context_above_compaction_threshold.snap +++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__prediction_fork_preserves_context_above_compaction_threshold.snap @@ -71,14 +71,9 @@ Settings: Never use the `request_user_input` tool for permission requests or permission-related escalations. -03:message/developer[3]: - [01] - [02] - Agent name: /root - First context window id: - Current context window id: - - [03] +03:function_call_output/agent.thread_hint:Agent name: /root + First context window id: + Current context window id: 04:message/developer: You are `/root`, the primary agent in a team of agents collaborating to fulfill the user's goals. diff --git a/codex-rs/features/src/feature_configs.rs b/codex-rs/features/src/feature_configs.rs index 0aae84bec9..0c6768f594 100644 --- a/codex-rs/features/src/feature_configs.rs +++ b/codex-rs/features/src/feature_configs.rs @@ -415,6 +415,9 @@ pub struct TokenBudgetConfigToml { /// Whether to expose the built-in history and notes extension. #[serde(skip_serializing_if = "Option::is_none")] pub use_history_notes_extension: Option, + /// Render the context window and its hints as an agent.thread_hint tool output. + #[serde(skip_serializing_if = "Option::is_none")] + pub context_window_as_tool_output: Option, /// Number of tokens remaining before auto-compaction when the wrap-up reminder is emitted. #[serde(skip_serializing_if = "Option::is_none")] #[schemars(range(min = 1))]