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:

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

Example:

{
  "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:

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

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

<${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.