diff --git a/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zst b/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zst index 4617198971..e678ee3f35 100644 Binary files a/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zst and b/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zst differ diff --git a/codex-rs/app-server/tests/suite/v2/thread_inject_items.rs b/codex-rs/app-server/tests/suite/v2/thread_inject_items.rs index 41463ba4f8..048262bfa2 100644 --- a/codex-rs/app-server/tests/suite/v2/thread_inject_items.rs +++ b/codex-rs/app-server/tests/suite/v2/thread_inject_items.rs @@ -130,8 +130,8 @@ async fn thread_inject_items_adds_raw_response_items_to_thread_history( items: vec![ serde_json::to_value(&injected_item)?, json!({"item": injected_developer_item, "retention": "default"}), - json!({"item": marker_shaped_developer_item, "retention": "always"}), - json!({"item": named_tool_output, "retention": "always"}), + json!({"item": marker_shaped_developer_item, "retention": "alwaysInThread"}), + json!({"item": named_tool_output, "retention": "alwaysInChildren"}), ], }) .await?; @@ -198,7 +198,7 @@ async fn thread_inject_items_adds_raw_response_items_to_thread_history( (injected_item.clone(), false, None), (injected_developer_item.clone(), false, Some(false)), (marker_shaped_developer_item.clone(), false, Some(true)), - (named_tool_item, false, Some(true)), + (named_tool_item, false, Some(false)), (agent_mail.clone(), false, None), ] ); diff --git a/codex-rs/core/src/agent/history.rs b/codex-rs/core/src/agent/history.rs index 1a2b638180..d6e96794da 100644 --- a/codex-rs/core/src/agent/history.rs +++ b/codex-rs/core/src/agent/history.rs @@ -68,7 +68,11 @@ fn sanitize_forked_rollout_item( return false; } let mut retain_envelope = |envelope: &mut ResponseItemEnvelope| { - let explicitly_retained = envelope.is_always_retained(); + let child_retention = envelope.child_retention(); + if child_retention == Some(false) { + return false; + } + let explicitly_retained = child_retention == Some(true); if preserve_fork_prefix || explicitly_retained || (version == MultiAgentVersion::V2 @@ -212,7 +216,8 @@ impl LocalAgentRuntime { let mut items: Vec<_> = retained_client_items( history.annotated_items(), &history.file_audio_durations, - ResponseItemEnvelope::is_always_retained, + |item| item.child_retention() == Some(true), + /*window_features*/ None, ) .into_values() .collect(); @@ -221,6 +226,7 @@ impl LocalAgentRuntime { // Keep item metadata needed for retention and replay. Checkpoints belong to the child. item.metadata = Some(CodexHarnessMetadata { retain_across_windows: parent_metadata.retain_across_windows, + retain_in_children: parent_metadata.retain_in_children, retained_source: parent_metadata.retained_source, history_truncation_token_limit: parent_metadata.history_truncation_token_limit, image_replay_sources: parent_metadata.image_replay_sources, @@ -234,7 +240,7 @@ impl LocalAgentRuntime { fn keep_forked_rollout_item(item: &RolloutItem, preserve_context_baselines: bool) -> bool { match item { - RolloutItem::ResponseItem(envelope) if envelope.is_always_retained() => true, + RolloutItem::ResponseItem(envelope) if envelope.child_retention() == Some(true) => true, RolloutItem::ResponseItem(envelope) => match &envelope.item { ResponseItem::Message { role, phase, .. } => match role.as_str() { "system" | "developer" | "user" => true, diff --git a/codex-rs/core/src/codex_thread.rs b/codex-rs/core/src/codex_thread.rs index f53e7cb5e7..0ac99f599c 100644 --- a/codex-rs/core/src/codex_thread.rs +++ b/codex-rs/core/src/codex_thread.rs @@ -1283,22 +1283,27 @@ impl CodexThread { )); } let items: Vec = items.into_iter().map(Into::into).collect(); + for item in &items { + validate_injected_response_item(&item.item)?; + } let mut indexed_items = items.iter().enumerate(); while let Some((index, item)) = indexed_items.next() { - validate_injected_response_item(&item.item)?; - if item.retention != ItemRetention::Always { + if matches!( + item.retention, + ItemRetention::Unspecified | ItemRetention::Default + ) { continue; } let needs_call = crate::tools::output_call_id(&item.item).is_some() && !matches!(&item.item, ResponseItem::ToolSearchOutput { execution, .. } if execution == "server"); if (crate::tools::input_call_id(&item.item).is_some() || needs_call) && !indexed_items.next().is_some_and(|(_, output)| { - output.retention == ItemRetention::Always + output.retention == item.retention && crate::tools::is_matching_tool_output(&item.item, &output.item) }) { return Err(CodexErr::InvalidRequest(format!( - "items[{index}]: retained tool calls and outputs must be adjacent in the same request, call first, with both marked always" + "items[{index}]: retained tool calls and outputs must be adjacent in the same request, call first, with the same retention policy" ))); } } diff --git a/codex-rs/core/src/compact.rs b/codex-rs/core/src/compact.rs index 497a8f5fa0..9d00c4ec19 100644 --- a/codex-rs/core/src/compact.rs +++ b/codex-rs/core/src/compact.rs @@ -754,6 +754,7 @@ fn build_compacted_history_with_limit( items, audio_durations, ResponseItemEnvelope::is_always_retained, + /*window_features*/ None, ); if max_tokens > 0 { let mut remaining = max_tokens; diff --git a/codex-rs/core/src/compact_remote_history.rs b/codex-rs/core/src/compact_remote_history.rs index 25321d6464..87ae231bf7 100644 --- a/codex-rs/core/src/compact_remote_history.rs +++ b/codex-rs/core/src/compact_remote_history.rs @@ -53,6 +53,7 @@ impl HistoryItemGroup<'_> { pub(crate) fn newest_history_item_groups( mut items: &[ResponseItemEnvelope], + is_pinned: fn(&ResponseItemEnvelope) -> bool, ) -> impl Iterator> { std::iter::from_fn(move || { let (last, preceding) = items.split_last()?; @@ -64,8 +65,8 @@ pub(crate) fn newest_history_item_groups( // Injection requires explicitly retained exchanges to be adjacent in the request. let (tool_call, rest) = match rest.split_last() { Some((call, rest)) - if source.is_always_retained() - && call.is_always_retained() + if is_pinned(source) + && is_pinned(call) && is_matching_tool_output(&call.item, &source.item) => { (Some(call), rest) @@ -133,7 +134,9 @@ pub(crate) fn trim_function_call_history_to_fit_context_window( } let mut rewritten_items = Vec::new(); let mut retained_len = original_items.len(); - for group in newest_history_item_groups(original_items) { + for group in + newest_history_item_groups(original_items, ResponseItemEnvelope::is_always_retained) + { if i64::try_from(estimated_tokens).unwrap_or(i64::MAX) <= context_window { break; } diff --git a/codex-rs/core/src/compact_remote_v2.rs b/codex-rs/core/src/compact_remote_v2.rs index 7e1cd45d80..01edab2141 100644 --- a/codex-rs/core/src/compact_remote_v2.rs +++ b/codex-rs/core/src/compact_remote_v2.rs @@ -579,6 +579,7 @@ fn build_v2_compacted_history( is_retained_for_remote_compaction_v2(item, features) || pending_sequence.is_some_and(|first| is_retained_pending_mail(item, first)) }, + ResponseItemEnvelope::is_always_retained, RETAINED_MESSAGE_TOKEN_BUDGET, image_budget, audio_durations, @@ -601,14 +602,20 @@ fn build_v2_compacted_history( (retained, retained_image_count) } +/// Select pins for the destination, plus configured client items on a window reset. pub(crate) fn retained_client_items( items: &[ResponseItemEnvelope], audio_durations: &FileAudioDurations, - should_retain: impl Fn(&ResponseItemEnvelope) -> bool, + is_pinned: fn(&ResponseItemEnvelope) -> bool, + window_features: Option<&Features>, ) -> BTreeMap { select_retained_items( items, - should_retain, + |item| { + is_pinned(item) + || window_features.is_some_and(|features| should_retain_client_item(item, features)) + }, + is_pinned, RETAINED_MESSAGE_TOKEN_BUDGET, RetainedImageBudget::Disabled, audio_durations, @@ -716,22 +723,30 @@ fn truncate_retained_messages( image_budget: RetainedImageBudget, audio_durations: &FileAudioDurations, ) -> Vec { - select_retained_items(&items, |_| true, max_tokens, image_budget, audio_durations) - .into_values() - .collect() + select_retained_items( + &items, + |_| true, + ResponseItemEnvelope::is_always_retained, + max_tokens, + image_budget, + audio_durations, + ) + .into_values() + .collect() } /// Select newest first, then return the items at their original positions. fn select_retained_items( items: &[ResponseItemEnvelope], should_retain: impl Fn(&ResponseItemEnvelope) -> bool, + is_pinned: fn(&ResponseItemEnvelope) -> bool, max_tokens: usize, image_budget: RetainedImageBudget, audio_durations: &FileAudioDurations, ) -> BTreeMap { let mut remaining = max_tokens; let mut selected = BTreeMap::new(); - for group in newest_history_item_groups(items) { + for group in newest_history_item_groups(items, is_pinned) { if remaining == 0 { break; } @@ -740,7 +755,7 @@ fn select_retained_items( } let charge_full_item = - group.source.is_always_retained() || is_client_authored_developer_message(group.source); + is_pinned(group.source) || is_client_authored_developer_message(group.source); let image_budget = if charge_full_item { RetainedImageBudget::Disabled } else { @@ -784,7 +799,7 @@ fn select_retained_items( remaining = remaining.saturating_sub(token_count); group.source.clone() } else if is_retained_tool_output(group.source) - || (group.source.is_always_retained() + || (is_pinned(group.source) && !matches!(group.source.item, ResponseItem::Message { .. })) { // Structured items such as tool results must stay whole. diff --git a/codex-rs/core/src/session/mod.rs b/codex-rs/core/src/session/mod.rs index bb8f48c0d1..42763474fc 100644 --- a/codex-rs/core/src/session/mod.rs +++ b/codex-rs/core/src/session/mod.rs @@ -5615,12 +5615,8 @@ impl Session { let retained_client_items = crate::compact_remote_v2::retained_client_items( history.annotated_items(), &history.file_audio_durations, - |item| { - crate::compact_remote_v2::should_retain_client_item( - item, - &turn_context.config.features, - ) - }, + ResponseItemEnvelope::is_always_retained, + Some(&turn_context.config.features), ); // Resolve the roster before allocating a new context window. let rendered = world_state.render_full_with_host_roster().await; diff --git a/codex-rs/core/tests/suite/scenarios_compaction_tests.rs b/codex-rs/core/tests/suite/scenarios_compaction_tests.rs index 61ffaf7104..5e13972b03 100644 --- a/codex-rs/core/tests/suite/scenarios_compaction_tests.rs +++ b/codex-rs/core/tests/suite/scenarios_compaction_tests.rs @@ -225,8 +225,11 @@ async fn interrupt_during_remote_compaction_preserves_summary_on_resume() -> Res Ok(()) } +#[test_case::test_case("always"; "shared")] +#[test_case::test_case("alwaysInThread"; "thread only")] +#[test_case::test_case("alwaysInChildren"; "children only")] #[tokio::test(flavor = "multi_thread", worker_threads = 2)] -async fn remote_slash_compact_preserves_context_across_windows() -> Result<()> { +async fn remote_slash_compact_preserves_context_across_windows(retention: &str) -> Result<()> { skip_if_no_network!(Ok(())); let server = start_mock_server().await; @@ -275,11 +278,11 @@ async fn remote_slash_compact_preserves_context_across_windows() -> Result<()> { }); let call: InjectedResponseItem = serde_json::from_value(json!({ "item": {"type": "function_call", "call_id": "release-check", "name": "check_release", "arguments": "{}"}, - "retention": "always" + "retention": retention }))?; let result: InjectedResponseItem = serde_json::from_value(json!({ "item": {"type": "function_call_output", "call_id": "release-check", "output": "The release candidate passed."}, - "retention": "always" + "retention": retention }))?; test.codex .inject_response_items_with_retention(vec![ @@ -325,6 +328,17 @@ async fn remote_slash_compact_preserves_context_across_windows() -> Result<()> { json!([mail]), ); + assert!( + requests[1] + .function_call_output_text("release-check") + .is_some() + ); + if retention == "alwaysInChildren" { + for request in &requests[2..] { + assert!(request.function_call_output_text("release-check").is_none()); + } + return Ok(()); + } insta::assert_snapshot!( "remote_slash_compact", context_snapshot::format_context_snapshot( diff --git a/codex-rs/core/tests/suite/step_settings/agent_spawn_tests.rs b/codex-rs/core/tests/suite/step_settings/agent_spawn_tests.rs index 899d49f06c..789363f555 100644 --- a/codex-rs/core/tests/suite/step_settings/agent_spawn_tests.rs +++ b/codex-rs/core/tests/suite/step_settings/agent_spawn_tests.rs @@ -5,6 +5,7 @@ use codex_exec_server::CreateDirectoryOptions; use codex_protocol::protocol::EnvironmentConfigState; use codex_protocol::protocol::TurnEnvironmentRequests; use codex_protocol::protocol::TurnEnvironmentSelection; +use codex_protocol::turn_input::InjectedResponseItem; use core_test_support::submit_thread_settings; use core_test_support::test_codex::environment_config_for_selection; use pretty_assertions::assert_eq; @@ -196,6 +197,18 @@ async fn spawn_inherits_captured_settings_after_a_turn_update( .await?; configured[0].config = EnvironmentConfigState::Ready(config); } + let instruction = |text: &str, retention: &str| { + serde_json::from_value::(json!({ + "item": {"type": "message", "role": "developer", "content": [{"type": "input_text", "text": text}]}, + "retention": retention, + })) + }; + test.codex + .inject_response_items_with_retention(vec![ + instruction("Send progress updates.", "alwaysInThread")?, + instruction("Read the worker log.", "alwaysInChildren")?, + ]) + .await?; answer_paused_turn(&test.codex, &request.turn_id).await?; let child_thread_id = tokio::time::timeout( @@ -215,6 +228,13 @@ async fn spawn_inherits_captured_settings_after_a_turn_update( .iter() .find(|request| request.header("thread-id") == Some(child_thread_id.to_string())) .expect("child should make a model request"); + assert!( + requests + .iter() + .any(|request| request.body_contains_text("Send progress updates.")) + ); + assert!(!child_request.body_contains_text("Send progress updates.")); + assert!(child_request.body_contains_text("Read the worker log.")); assert_eq!( request_settings(child_request), json!({ diff --git a/codex-rs/history/src/lib.rs b/codex-rs/history/src/lib.rs index 30f69a11a3..941315b32e 100644 --- a/codex-rs/history/src/lib.rs +++ b/codex-rs/history/src/lib.rs @@ -144,6 +144,11 @@ pub struct CodexHarnessMetadata { #[serde(default, skip_serializing_if = "Option::is_none")] pub retain_across_windows: Option, + /// Override inheritance by spawned agents, including full-history forks. + /// Older rollouts pin items in both scopes when `retain_across_windows` is true. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub retain_in_children: Option, + /// The originating history budget, including any tool-specific allowance. /// Measured in tokens and reused when replaying persisted history. #[serde( @@ -337,13 +342,22 @@ impl ResponseItemEnvelope { }) } - /// Whether the client requested that this item survive context-window changes and forks. + /// Whether the client requested that this item survive context-window changes. pub fn is_always_retained(&self) -> bool { self.metadata .as_ref() .is_some_and(|metadata| metadata.retain_across_windows == Some(true)) } + /// Explicitly include or exclude the item when spawning an agent. With no override, + /// a full fork applies its ordinary history rules and a fresh child skips the item. + pub fn child_retention(&self) -> Option { + let metadata = self.metadata.as_ref()?; + metadata + .retain_in_children + .or_else(|| metadata.retain_across_windows.filter(|retain| *retain)) + } + /// Wraps a raw Responses API item for persisted history. pub fn new(item: ResponseItem) -> Self { Self { @@ -367,12 +381,16 @@ impl From for ResponseItemEnvelope { impl From for ResponseItemEnvelope { fn from(injected: InjectedResponseItem) -> Self { let mut envelope = Self::new(injected.item); - if injected.retention != ItemRetention::Unspecified { - envelope - .metadata - .get_or_insert_default() - .retain_across_windows = Some(injected.retention == ItemRetention::Always); - } + let (across_windows, in_children) = match injected.retention { + ItemRetention::Unspecified => return envelope, + ItemRetention::Default => (false, None), + ItemRetention::Always => (true, None), + ItemRetention::AlwaysInThread => (true, Some(false)), + ItemRetention::AlwaysInChildren => (false, Some(true)), + }; + let metadata = envelope.metadata.get_or_insert_default(); + metadata.retain_across_windows = Some(across_windows); + metadata.retain_in_children = in_children; envelope } } diff --git a/codex-rs/protocol/src/turn_input.rs b/codex-rs/protocol/src/turn_input.rs index cc8759586f..fd58d0eedd 100644 --- a/codex-rs/protocol/src/turn_input.rs +++ b/codex-rs/protocol/src/turn_input.rs @@ -91,6 +91,11 @@ pub enum ItemRetention { Default, /// Carry the item into later context windows and newly spawned children. Always, + /// Carry the item into later windows of this thread and exclude it from spawned agents. + AlwaysInThread, + /// Carry the item into spawned agents while it is in the parent's context. + /// Each thread applies ordinary retention when its own context window changes. + AlwaysInChildren, } impl From for InjectedResponseItem {