Add thread and child retention policies for injected items (#62654)

## Why

The `always` policy ties retention across context windows to inheritance by
spawned agents. Callers need to control those behaviors independently.

## What changed

- `alwaysInThread` carries items across context windows in the current thread
  and excludes them from spawned agents, including full-history forks.
- `alwaysInChildren` passes items still in the parent's context to spawned
  agents and leaves each thread's context-window retention to the usual rules.
- `always` continues to apply in both scopes, including for items saved by
  older versions. Retained tool calls and outputs must be adjacent, with the
  call first and the same retention policy on both items.

## Testing

Extend integration coverage for retention across remote compaction, inheritance
by spawned agents, and injection through the app server.

GitOrigin-RevId: aafede69cfbe149aa52292e6029d248d4bdf6401
This commit is contained in:
Vivian Fang
2026-11-20 02:59:58 +00:00
committed by copyberry
parent e787cf7024
commit a0a30c40e8
12 changed files with 120 additions and 37 deletions
+9 -3
View File
@@ -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,
+9 -4
View File
@@ -1283,22 +1283,27 @@ impl CodexThread {
));
}
let items: Vec<InjectedResponseItem> = 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"
)));
}
}
+1
View File
@@ -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;
+6 -3
View File
@@ -53,6 +53,7 @@ impl HistoryItemGroup<'_> {
pub(crate) fn newest_history_item_groups(
mut items: &[ResponseItemEnvelope],
is_pinned: fn(&ResponseItemEnvelope) -> bool,
) -> impl Iterator<Item = HistoryItemGroup<'_>> {
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;
}
+23 -8
View File
@@ -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<usize, ResponseItemEnvelope> {
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<ResponseItemEnvelope> {
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<usize, ResponseItemEnvelope> {
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.
+2 -6
View File
@@ -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;