Add experimental turn additional context (#24154)

## Summary

Adds experimental `additionalContext` support to `turn/start` and
`turn/steer` so clients can provide ephemeral external context, such as
browser or automation state, without turning that plumbing into a
visible user prompt or triggering user-prompt lifecycle behavior.

## API Shape

The parameter shape is:

```ts
additionalContext?: Record<string, {
  value: string
  kind: "untrusted" | "application"
}> | null
```

Example:

```json
{
  "additionalContext": {
    "browser_info": {
      "value": "Active tab is CI failures.",
      "kind": "untrusted"
    },
    "automation_info": {
      "value": "CI rerun is in progress.",
      "kind": "application"
    }
  }
}
```

The keys are opaque and caller-defined.

## Context Injection

When provided, accepted entries are inserted into model context as
hidden contextual message items, not as visible thread user-message
items.

`kind: "untrusted"` entries are inserted with role `user`:

```text
<external_${key}>${value}</external_${key}>
```

`kind: "application"` entries are inserted with role `developer`:

```text
<${key}>${value}</${key}>
```

Values are not escaped. Each value is truncated to 1k approximate tokens
before wrapping.

For `turn/start`, accepted additional context is inserted before normal
user input. For `turn/steer`, additional context is merged only when the
steer includes non-empty user input; context-only steers still reject as
empty input.

## Dedupe Strategy

`AdditionalContextStore` lives on session state and stores the latest
complete additional-context map.

Each `turn/start` or non-empty `turn/steer` treats its
`additionalContext` as the current complete set of values. Entries are
injected only when the key is new or the exact entry for that key
changed, including `value` or `kind`. After merging, the store is
replaced with the provided map, so omitted keys are removed from the
retained set and can be injected again later if reintroduced.

Omitting `additionalContext`, passing `null`, or passing an empty object
resets the store to empty and injects nothing.

## What Changed

- Threads experimental v2 `additionalContext` through app-server into
core turn start and steer handling.
- Adds separate contextual fragment types for untrusted user-role
context and application developer-role context.
- Uses pending response input items so additional context can be
combined with normal user input without treating it as prompt text.
- Adds integration coverage for start/steer flow, role routing,
dedupe/reset behavior, deletion/re-add behavior, hook-blocked input
behavior, empty context-only steer rejection, external-fragment marker
matching, and truncation.

codex-rs/core/src/context/contextual_user_message.rs

@@ -2,6 +2,7 @@ use codex_protocol::items::HookPromptItem;
 use codex_protocol::items::parse_hook_prompt_fragment;
 use codex_protocol::models::ContentItem;
 
+use super::AdditionalContextUserFragment;
 use super::EnvironmentContext;
 use super::FragmentRegistration;
 use super::FragmentRegistrationProxy;
@@ -19,6 +20,8 @@ static USER_INSTRUCTIONS_REGISTRATION: FragmentRegistrationProxy<UserInstruction
     FragmentRegistrationProxy::new();
 static ENVIRONMENT_CONTEXT_REGISTRATION: FragmentRegistrationProxy<EnvironmentContext> =
     FragmentRegistrationProxy::new();
+static ADDITIONAL_CONTEXT_REGISTRATION: FragmentRegistrationProxy<AdditionalContextUserFragment> =
+    FragmentRegistrationProxy::new();
 static SKILL_INSTRUCTIONS_REGISTRATION: FragmentRegistrationProxy<SkillInstructions> =
     FragmentRegistrationProxy::new();
 static USER_SHELL_COMMAND_REGISTRATION: FragmentRegistrationProxy<UserShellCommand> =
@@ -42,6 +45,7 @@ static LEGACY_MODEL_MISMATCH_WARNING_REGISTRATION: FragmentRegistrationProxy<
 static CONTEXTUAL_USER_FRAGMENTS: &[&dyn FragmentRegistration] = &[
     &USER_INSTRUCTIONS_REGISTRATION,
     &ENVIRONMENT_CONTEXT_REGISTRATION,
+    &ADDITIONAL_CONTEXT_REGISTRATION,
     &SKILL_INSTRUCTIONS_REGISTRATION,
     &USER_SHELL_COMMAND_REGISTRATION,
     &TURN_ABORTED_REGISTRATION,

codex-rs/core/src/context/fragment.rs

@@ -1,4 +1,5 @@
 use codex_protocol::models::ContentItem;
+use codex_protocol::models::ResponseInputItem;
 use codex_protocol::models::ResponseItem;
 use std::marker::PhantomData;
 
@@ -81,6 +82,19 @@ pub trait ContextualUserFragment {
             phase: None,
         }
     }
+
+    fn into_response_input_item(self) -> ResponseInputItem
+    where
+        Self: Sized,
+    {
+        ResponseInputItem::Message {
+            role: Self::role().to_string(),
+            content: vec![ContentItem::InputText {
+                text: self.render(),
+            }],
+            phase: None,
+        }
+    }
 }
 
 fn matches_marked_text(start_marker: &str, end_marker: &str, text: &str) -> bool {

codex-rs/core/src/context/fragments.rs

@@ -0,0 +1,92 @@
+use super::ContextualUserFragment;
+use codex_utils_string::truncate_middle_with_token_budget;
+
+const MAX_ADDITIONAL_CONTEXT_VALUE_TOKENS: usize = 1_000;
+const ADDITIONAL_CONTEXT_END_MARKER_SUFFIX: &str = ">";
+const ADDITIONAL_CONTEXT_START_MARKER_PREFIX: &str = "<external_";
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct AdditionalContextUserFragment {
+    key: String,
+    value: String,
+}
+
+impl AdditionalContextUserFragment {
+    pub(crate) fn new(key: String, value: String) -> Self {
+        Self { key, value }
+    }
+}
+
+impl ContextualUserFragment for AdditionalContextUserFragment {
+    fn role() -> &'static str {
+        "user"
+    }
+
+    fn markers(&self) -> (&'static str, &'static str) {
+        Self::type_markers()
+    }
+
+    fn type_markers() -> (&'static str, &'static str) {
+        (
+            ADDITIONAL_CONTEXT_START_MARKER_PREFIX,
+            ADDITIONAL_CONTEXT_END_MARKER_SUFFIX,
+        )
+    }
+
+    fn matches_text(text: &str) -> bool {
+        let trimmed = text.trim();
+        let Some(rest) = trimmed.strip_prefix(ADDITIONAL_CONTEXT_START_MARKER_PREFIX) else {
+            return false;
+        };
+        let Some((key, value_and_close)) = rest.split_once(ADDITIONAL_CONTEXT_END_MARKER_SUFFIX)
+        else {
+            return false;
+        };
+
+        value_and_close.ends_with(&format!("</external_{key}>"))
+    }
+
+    fn body(&self) -> String {
+        additional_context_body(&self.key, &self.value)
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct AdditionalContextDeveloperFragment {
+    key: String,
+    value: String,
+}
+
+impl AdditionalContextDeveloperFragment {
+    pub(crate) fn new(key: String, value: String) -> Self {
+        Self { key, value }
+    }
+}
+
+impl ContextualUserFragment for AdditionalContextDeveloperFragment {
+    fn role() -> &'static str {
+        "developer"
+    }
+
+    fn markers(&self) -> (&'static str, &'static str) {
+        Self::type_markers()
+    }
+
+    fn type_markers() -> (&'static str, &'static str) {
+        ("", "")
+    }
+
+    fn body(&self) -> String {
+        additional_context_developer_body(&self.key, &self.value)
+    }
+}
+
+fn additional_context_body(key: &str, value: &str) -> String {
+    let value = truncate_middle_with_token_budget(value, MAX_ADDITIONAL_CONTEXT_VALUE_TOKENS).0;
+    format!("{key}>{value}</external_{key}")
+}
+
+fn additional_context_developer_body(key: &str, value: &str) -> String {
+    let value = truncate_middle_with_token_budget(value, MAX_ADDITIONAL_CONTEXT_VALUE_TOKENS).0;
+    format!("<{key}>{value}</{key}>")
+}

codex-rs/core/src/context/goal_context.rs

@@ -1,8 +1,6 @@
 //! Hidden user-context fragment for runtime-owned goal steering prompts.
 
 use super::ContextualUserFragment;
-use codex_protocol::models::ContentItem;
-use codex_protocol::models::ResponseInputItem;
 
 /// Hidden runtime-owned goal steering context injected into model input.
 #[derive(Debug, Clone, PartialEq)]
@@ -17,17 +15,6 @@ impl GoalContext {
             prompt: prompt.into(),
         }
     }
-
-    /// Converts the registered fragment into an active-turn injectable item.
-    pub fn into_response_input_item(self) -> ResponseInputItem {
-        ResponseInputItem::Message {
-            role: <Self as ContextualUserFragment>::role().to_string(),
-            content: vec![ContentItem::InputText {
-                text: self.render(),
-            }],
-            phase: None,
-        }
-    }
 }
 
 impl ContextualUserFragment for GoalContext {

codex-rs/core/src/context/mod.rs

@@ -8,6 +8,7 @@ mod collaboration_mode_instructions;
 mod contextual_user_message;
 mod environment_context;
 mod fragment;
+mod fragments;
 mod goal_context;
 mod guardian_followup_review_reminder;
 mod hook_additional_context;
@@ -40,6 +41,8 @@ pub(crate) use environment_context::EnvironmentContext;
 pub use fragment::ContextualUserFragment;
 pub(crate) use fragment::FragmentRegistration;
 pub(crate) use fragment::FragmentRegistrationProxy;
+pub(crate) use fragments::AdditionalContextDeveloperFragment;
+pub(crate) use fragments::AdditionalContextUserFragment;
 pub use goal_context::GoalContext;
 pub(crate) use guardian_followup_review_reminder::GuardianFollowupReviewReminder;
 pub(crate) use hook_additional_context::HookAdditionalContext;