380 Commits

• [codex] core: restore absolute turn context cwd (#28629)

  ## Why
  
  #28152 jumped the gun on moving the rollout format to store URIs, and
  would likely break compat with some features that don't go through the
  same types as the core logic.
  
  ## What
  
  Make `TurnContextItem.cwd` an `AbsolutePathBuf` again, remove test added
  for `PathUri` serialization in rollouts. Also drops a bunch of error
  paths that are no longer needed.

  Adam Perry @ OpenAI · 2026-06-16 19:05:26 -07:00
  3d02c443bc
• core: render remote environment cwd natively (#28152)

  ## Why
  
  Model-visible `<environment_context>` should match the environment of
  the executor, not of the app server.
  
  Stacked on #28146.
  
  ## What
  
  - Keep selected environment cwd values as `PathUri` while building
  environment context.
  - Render cwd text using the path convention represented by the URI, with
  the canonical URI as a fallback.
  - Preserve compatibility with legacy `TurnContextItem.cwd` values when
  reconstructing and diffing context.
  - Extend the Wine-backed remote Windows test to assert that the model
  sees `powershell` and `C:\windows`.

  Adam Perry @ OpenAI · 2026-06-16 16:17:47 -07:00
  4c79527e31
• [codex] [3/4] Activate endpoint plugin recommendations (#27704)

  Summary\n- Await endpoint recommendation selection while constructing
  each authenticated turn, removing the first-turn cache race.\n- Snapshot
  and filter endpoint candidates once per turn, then use that same set for
  the bounded contextual user fragment, tool exposure, and exact install
  validation.\n- Keep recommendation selection ephemeral: do not persist
  recommendation state in or gate resumed threads on prior context.\n-
  Hide the legacy list tool in endpoint mode and preserve legacy discovery
  unchanged when the endpoint is disabled or unavailable.\n- Keep remote
  plugin and connector app identities out of model-visible context and
  attach them only to Codex-owned elicitation metadata.\n\nStack\n- 3/4,
  based on #28400.\n- Endpoint client and cache: #28399.\n- Generalized
  suggestion presentation: #28400.\n- Install-schema follow-up:
  #28403.\n\nValidation\n- \n- \n- \n- \n- Full : 2,649 passed and 88
  environment-dependent tests failed because this sandbox cannot write ,
  nest Seatbelt, or locate auxiliary test binaries.

  Alex Daley · 2026-06-16 23:04:07 +00:00
  a34da3b295
• [codex] [2/4] Generalize plugin suggestion presentation (#28400)

  Summary
  - Add list-backed and developer-context presentations for plugin
  suggestion candidates.
  - Let tool planning, install validation, and request-tool copy follow
  the selected presentation.
  - Keep every production caller on the existing list-backed presentation,
  preserving the current list tool, request schema, connector behavior,
  and model-visible copy.
  - Leave developer-context presentation latent until the final PR in the
  stack.
  
  Stack
  - 2/3, based on #28399.
  - Follow-up: #27704 activates endpoint recommendations.
  
  Validation
  - `just test -p codex-core request_plugin_install`
  - `just test -p codex-core spec_plan`
  - `just fix -p codex-core`
  - `just fmt`
  - `git diff --check`

  Alex Daley · 2026-06-16 22:44:10 +00:00
  587487df9e
• app-server: preserve target-native environment cwd (#28146)

  ## Why
  
  app-server may run on a different OS from the selected exec-server
  environment. Parsing that environment’s cwd with the Codex host’s path
  rules prevents thread startup.
  
  ## What
  
  Carry environment cwd values as `LegacyAppPathString` at the app-server
  boundary and `PathUri` internally. Existing tool-call schemas and
  relative-path behavior stay host-native; remaining local-only consumers
  convert explicitly and leave follow-up TODOs.
  
  The Wine integration test verifies app-server can start a thread and
  complete an ordinary turn with a Windows environment cwd from Linux.
  
  ## Validation
  
  - `bazel test //codex-rs/core/tests/remote_env_windows:smoke-test
  --test_output=errors`
  - focused app-server environment-selection and protocol schema tests
  - scoped Clippy for `codex-core` and `codex-app-server-protocol`

  Adam Perry @ OpenAI · 2026-06-16 21:42:28 +00:00
  f8850cab1d
• core: surface terminal subagent errors to parent agents (#28375)

  ## Why
  
  When a subagent exhausts its retries, it emits an `Error`, but the
  generic task lifecycle then emits `TurnComplete(None)`. That completion
  used to overwrite the subagent's `Errored` status with
  `Completed(None)`, so the parent received an empty completion
  notification.
  
  This made a failed child look indistinguishable from a child that
  completed without an answer. In unattended or long-running multi-agent
  work, the root could silently continue without knowing that delegated
  work failed or how to restart it.
  
  ## Behavior
  
  Before, a terminal stream failure was reduced to an empty completion:
  
  ```text
  <subagent_notification>
  {"agent_path":"/root/worker","status":{"completed":null}}
  </subagent_notification>
  ```
  
  Now the parent receives the actual terminal error, bounded to 1,000
  tokens, together with an actionable recovery hint:
  
  ```text
  <subagent_notification>
  {
    "agent_path": "/root/worker",
    "status": {
      "errored": "stream disconnected before completion: stream closed before response.completed"
    },
    "next_action": "This agent's turn failed. If you still need this agent, use `followup_task` to give it another task."
  }
  </subagent_notification>
  ```
  
  The notification remains queue-only: it does not wake the root or replay
  the failed request. The root sees it at the next sampling boundary and
  can use `followup_task` to start a new turn for that agent.
  
  ## What changed
  
  - Added terminal-error precedence to the [agent status
  reducer](https://github.com/openai/codex/blob/e95fcfe2bb6a02f1a75650afa20048859f556511/codex-rs/core/src/agent/status.rs#L23-L34),
  so a closing `TurnComplete` cannot erase an immediately preceding
  `Errored` status.
  - Made MultiAgentV2 completion forwarding use the retained session
  status instead of re-deriving `Completed(None)` from the final event.
  - Extended the [subagent notification
  fragment](https://github.com/openai/codex/blob/e95fcfe2bb6a02f1a75650afa20048859f556511/codex-rs/core/src/context/subagent_notification.rs#L6-L60)
  with a `next_action` for terminal errors and a hard cap on model-visible
  error text.
  - Kept successful completions and interrupted turns unchanged.
  
  ## Verification
  
  - Added a status-reducer test proving that `Errored` survives the
  trailing `TurnComplete`.
  - Added an integration test that exhausts a subagent's stream retries
  and verifies the exact `agent_message` delivered to the parent,
  including the error and `followup_task` guidance.
  - Re-ran the existing successful-completion and interrupted-turn
  notification tests.

  jif · 2026-06-16 14:34:54 +02:00
  1b24ba912a
• feat: render typed envelopes for multi-agent v2 messages (#28368)

  ## Why
  
  Multi-agent v2 messages need a consistent, model-visible envelope that
  identifies what kind of interaction occurred, who sent it, and which
  agent it targets. Previously, encrypted deliveries exposed only
  `encrypted_content`, while child completion used the legacy
  `<subagent_notification>` shape. That meant the client could not
  consistently present `NEW_TASK`, `MESSAGE`, and `FINAL_ANSWER` using the
  same format.
  
  This change adds the routing envelope as plaintext while keeping task
  and message payloads encrypted. No new Responses API field is required:
  an encrypted delivery is represented as an `input_text` header
  immediately followed by its existing `encrypted_content` item.
  
  Every envelope now follows this shape:
  
  ```text
  Message Type: <NEW_TASK | MESSAGE | FINAL_ANSWER>
  Task name: <recipient agent path>
  Sender: <author agent path>
  Payload:
  <message payload>
  ```
  
  ## Message types
  
  ### `NEW_TASK`
  
  `NEW_TASK` is used when the recipient should begin a new turn, including
  an initial `spawn_agent` task and a later `followup_task`.
  
  For a root agent spawning `/root/worker`, the request contains a
  plaintext envelope followed by the encrypted task:
  
  ```json
  {
    "type": "agent_message",
    "author": "/root",
    "recipient": "/root/worker",
    "content": [
      {
        "type": "input_text",
        "text": "Message Type: NEW_TASK\nTask name: /root/worker\nSender: /root\nPayload:\n"
      },
      {
        "type": "encrypted_content",
        "encrypted_content": "<encrypted task payload>"
      }
    ]
  }
  ```
  
  Conceptually, the model receives:
  
  ```text
  Message Type: NEW_TASK
  Task name: /root/worker
  Sender: /root
  Payload:
  Review the authentication changes and report any regressions.
  ```
  
  ### `MESSAGE`
  
  `MESSAGE` is used for a queued `send_message` delivery. It communicates
  with an existing agent without starting a new turn.
  
  For `/root/worker` reporting progress to the root agent, the request
  contains:
  
  ```json
  {
    "type": "agent_message",
    "author": "/root/worker",
    "recipient": "/root",
    "content": [
      {
        "type": "input_text",
        "text": "Message Type: MESSAGE\nTask name: /root\nSender: /root/worker\nPayload:\n"
      },
      {
        "type": "encrypted_content",
        "encrypted_content": "<encrypted message payload>"
      }
    ]
  }
  ```
  
  Conceptually, the model receives:
  
  ```text
  Message Type: MESSAGE
  Task name: /root
  Sender: /root/worker
  Payload:
  The protocol tests pass; I am checking the resume path now.
  ```
  
  ### `FINAL_ANSWER`
  
  `FINAL_ANSWER` is emitted when a child agent reaches a terminal state
  and reports its result to its parent. Completion payloads are already
  available locally, so the complete envelope is represented as plaintext
  rather than as a plaintext header plus encrypted content.
  
  For `/root/worker` completing work for the root agent, the request
  contains:
  
  ```json
  {
    "type": "agent_message",
    "author": "/root/worker",
    "recipient": "/root",
    "content": [
      {
        "type": "input_text",
        "text": "Message Type: FINAL_ANSWER\nTask name: /root\nSender: /root/worker\nPayload:\nNo regressions found."
      }
    ]
  }
  ```
  
  The model-visible form is:
  
  ```text
  Message Type: FINAL_ANSWER
  Task name: /root
  Sender: /root/worker
  Payload:
  No regressions found.
  ```
  
  Errored, shut down, and missing agents also use `FINAL_ANSWER`, with a
  terminal-status description in the payload.
  
  ## What changed
  
  - Render `NEW_TASK` or `MESSAGE` in
  `InterAgentCommunication::to_model_input_item`, based on whether the
  encrypted delivery starts a turn.
  - Replace the multi-agent v2 `<subagent_notification>` completion
  payload with a model-visible `FINAL_ANSWER` envelope.
  - Document `Task name`, `Sender`, and `Payload` consistently in the
  multi-agent developer instructions.
  - Prevent local-only history projections from treating an encrypted
  message's plaintext header as the complete assistant message.
  - Preserve rollout-trace interaction edges when an agent message
  contains both plaintext and encrypted content.
  
  Legacy multi-agent behavior remains unchanged.
  
  ## Verification
  
  - `just test -p codex-protocol`
  - `just test -p codex-rollout-trace`
  - `just test -p codex-web-search-extension`
  - `just test -p codex-core
  encrypted_multi_agent_v2_spawn_sends_agent_message_to_child`
  - `just test -p codex-core
  plaintext_multi_agent_v2_completion_sends_agent_message`
  - `just test -p codex-core
  multi_agent_v2_followup_task_completion_notifies_parent_on_every_turn`
  - `just test -p codex-core
  multi_agent_v2_completion_queues_message_for_direct_parent`

  jif · 2026-06-16 11:46:59 +02:00
  5b22a8e5b1
• [codex] Use local environment for user shell commands (#28163)

  ## Why
  
  User shell commands still read the legacy turn cwd and session shell
  even though execution context is now owned by selected turn
  environments. App-server also defines `thread/shellCommand` as a
  local-host escape hatch, so it must use an available local environment
  even when a remote environment is primary.
  
  ## What changed
  
  - Add `ResolvedTurnEnvironments::local()` to find the selected local
  environment.
  - Resolve the user shell command cwd and shell from that local
  `TurnEnvironment`.
  - Emit the standard `shell is unavailable in this session` error when no
  selected local environment or resolved local shell is available.
  - Add an integration test covering `/shell` without a local environment.
  
  ## Test plan
  
  - `just test -p codex-core
  user_shell_command_without_local_environment_emits_error`

  pakrym-oai · 2026-06-16 04:55:20 +00:00
  1e015884c5
• [codex] Bind shell snapshots to retained thread environments (#28421)

  ## Why
  
  Shell snapshots are currently session-scoped even though shell and cwd
  are properties of a selected turn environment. That makes snapshot
  refresh depend on separate session-cwd plumbing, prevents retained
  environments from retaining their snapshot work, and can make snapshot
  construction use a different shell than command execution.
  
  This follows #27955 by making the retained thread-environment service
  own environment snapshot lifecycles. Session configuration remains the
  requested selection state, while `ThreadEnvironments` remains the source
  of successfully resolved environments.
  
  ## What changed
  
  - Configure the shell-snapshot builder before initial environment
  resolution.
  - Start each local environment snapshot task when its `TurnEnvironment`
  is built and retain that shared task while environment ID and cwd still
  match.
  - Inherit retained environment snapshots into spawned child threads.
  - Carry the selected `TurnEnvironment` through shell runtimes so
  snapshot construction and command execution use the same
  environment-specific shell and cwd.
  - Load project instructions and warm plugins/skills after initial
  environment resolution.
  - Continue decoding invalid UTF-8 instruction files lossily without
  emitting a startup warning.
  - Keep requested selections in `SessionConfiguration`; failed or
  duplicate resolutions only affect the resolved environment snapshot.
  
  ## Validation
  
  - `cargo check -p codex-core --tests`
  - `just test -p codex-home instructions` (6 passed)
  - Focused environment, instruction, shell-snapshot, and user-shell tests
  (84 passed)
  - Focused shell-snapshot, user-shell, and unified-exec tests (126
  passed; two event-timing tests passed on retry)

  pakrym-oai · 2026-06-15 20:10:53 -07:00
  022f1221e8
• Use PathUri in filesystem permission paths for exec-server (#28165)

  ## Why
  
  Progress towards letting app-server and exec-server run on different
  platforms, specifically for sandbox configuration.
  
  ## What
  
  - Make the filesystem path containment hierarchy generic, defaulting to
  `AbsolutePathBuf` for now.
  - Have clients specify `AbsolutePathBuf` or `PathUri` directly where
  needed.
  - Use `PathUri` throughout exec-server filesystem protocol and trait
  boundaries.
  - Implement `From` for conversion to path URIs and `TryFrom` for
  fallible conversion to absolute paths through the generic type
  hierarchy.

  Adam Perry @ OpenAI · 2026-06-15 23:55:23 +00:00
  46f17930b6
• Add realtime speech append control (#27917)

  ## Why
  
  Realtime voice harness tuning needs app-side control over what backend
  Codex text is spoken. Backend orchestrator text is written for a reading
  UI, so automatically speaking every preamble, progress update, or final
  assistant message can make the realtime voice model too chatty.
  
  For experimentation, clients need two simple controls: keep app/client
  text-item injection on the existing item-create path, and add an
  explicit speakable path that app code can call only when it wants
  realtime to speak. Automatic Codex output also needs an opt-in way to
  switch from the protocol's default speakable path to regular realtime
  items, with a caller-provided prefix so prompt wording can be tuned
  outside core.
  
  The default remains unchanged: if a client omits the new start fields
  and never calls `appendSpeech`, automatic backend output continues down
  the existing speakable path for the selected realtime protocol.
  
  ## What Changed
  
  - Adds experimental `thread/realtime/appendSpeech` for app-provided
  speakable text.
  - Keeps existing `thread/realtime/appendText` as the item-create API for
  app-provided realtime text items.
  - Adds `codexResponsesAsItems` / `codex_responses_as_items` on
  `thread/realtime/start` to send automatic Codex responses with
  `conversation.item.create` instead of the protocol's default speakable
  output path.
  - Adds `codexResponseItemPrefix` / `codex_response_item_prefix` so
  clients can prepend experiment instructions to those automatic Codex
  response items.
  - Keeps literal `conversation.handoff.append` routing scoped to the v1
  speakable path; v2 default speech uses its item/function-output plus
  `response.create` behavior.
  - Removes the earlier public silent-context API and hardcoded
  silent-context prefix.
  - Updates realtime tests to cover default automatic speakable behavior,
  opt-in automatic item-create behavior, and explicit `appendSpeech`
  behavior.
  
  ## Validation
  
  - `cargo check -p codex-core -p codex-app-server -p codex-api`
  - `just test -p codex-app-server realtime_conversation`
  - `just test -p codex-core realtime_conversation` (50/51 passed in the
  filtered parallel run; the lone failure passed when rerun in isolation)
  - `just test -p codex-core
  conversation_mirrors_assistant_message_text_to_realtime_handoff`
  - `just test -p codex-api
  e2e_connect_and_exchange_events_against_mock_ws_server`
  - `just fix -p codex-core`
  - `just fix -p codex-app-server`
  - `cargo build -p codex-cli`

  guinness-oai · 2026-06-15 16:15:58 -07:00
  1d8ff89aa3
• [codex] retain resolved environments across turns (#27955)

  ## Why
  
  Selected execution environments are thread-scoped resources, but startup
  and turn construction repeatedly resolved their IDs and working
  directories. That discarded existing environment handles and shell
  metadata even when a selection had not changed.
  
  Session configuration updates also need to affect future turns without
  changing the resolved environment set already captured by a running
  turn.
  
  ## What changed
  
  - Create a `ThreadEnvironments` service inside `Codex` from the spawned
  `EnvironmentManager` and raw environment selections, then store it on
  `SessionServices`.
  - Split service construction from `update_selections`, allowing session
  configuration updates to mutate the resolved set in place.
  - Retain an existing `TurnEnvironment` when its environment ID and
  working directory match; resolve only added or changed selections and
  remove selections that are no longer present.
  - Normalize duplicate IDs by keeping the first selection and skip
  individual selections that fail to resolve instead of rejecting the
  entire update.
  - Give each `TurnContext` a cloned `TurnEnvironmentSnapshot`, so later
  session configuration updates affect future turns without rewriting an
  active turn.
  - Reuse the service-owned environment manager and resolved snapshot for
  startup work, MCP initialization, and child-thread spawning instead of
  flowing resolved environments through spawn arguments.
  
  ## Test plan
  
  - `cargo check -p codex-core --tests`
  - `just test -p codex-core environment_selection`
  - `just test -p codex-core turn_environments`
  - `just test -p codex-core
  session_update_settings_does_not_rewrite_sticky_environment_cwds`
  - `just test -p codex-core
  default_turn_does_not_overlay_legacy_fallback_cwd_onto_stored_thread_environments`

  pakrym-oai · 2026-06-15 16:15:07 -07:00
  9728992fab
• feat(core): add metadata field to ResponseItem (#28355)

  ## Description
  
  This PR adds an optional `metadata` field to `ResponseItem` for
  Responses API calls. Only mechanical plumbing, no actual values
  populated and sent yet. Turns out just adding a new field to
  `ResponseItem` has quite a large blast radius already.
  
  This change is backwards compatible because `metadata` is optional and
  omitted when absent, so existing response items and rollout history
  without it still deserialize and requests that do not set it keep the
  same wire shape. For provider compatibility, we strip out `metadata`
  before non-OpenAI Responses requests so Azure and AWS Bedrock never see
  this field.
  
  My followup PR here will actually make use of it to start storing and
  passing along `turn_id`: https://github.com/openai/codex/pull/28360
  
  ## What changed
  
  - Added `ResponseItemMetadata` with optional `turn_id`, plus optional
  `metadata` on Responses API item variants and inter-agent communication.
  - Preserved item metadata through response-item rewrites such as
  truncation, missing tool-output synthesis, compaction history
  rebuilding, visible-history conversion, rollout/resume, and generated
  app-server schemas/types.
  - Strip item metadata from non-OpenAI Responses requests while
  preserving it for OpenAI-shaped requests.
  - Updated the mechanical fixture/test construction churn required by the
  new optional field.

  Owen Lin · 2026-06-15 15:05:28 -07:00
  040dafa32d
• core: cache the tool search handler per session (#27258)

  ## Why
  
  Tool router construction rebuilds the deferred-tool BM25 index during
  session initialization and before each sampling continuation, even when
  the searchable tool metadata is unchanged. Local profiling measured
  `append_tool_search_executor` at roughly 113 ms per continuation, making
  repeated index construction the largest measured router-building cost.
  
  ## What changed
  
  - Add a session-scoped `ToolSearchHandlerCache` so continuations and
  user turns can reuse the existing handler.
  - Key reuse on the complete ordered `Vec<ToolSearchInfo>`, rebuilding
  when searchable text, loadable tool specs, source metadata, or ordering
  changes.
  - Build handlers outside the cache lock and recheck before publishing
  them, avoiding holding the mutex during index construction.
  
  ## Verification
  
  - `cache_reuses_identical_search_infos_and_rebuilds_changed_inputs`
  covers exact cache reuse and invalidation when the ordered search
  metadata changes.
  - Local rollout profiling showed the initial router build populating the
  cache and unchanged later continuations reusing it:
    - uncached: 118 ms median across 14 spans from 3 rollouts
    - cached: 4 ms median across 12 spans from 3 rollouts

  mchen-oai · 2026-06-15 14:48:30 -07:00
  af99f6a72f
• core: let steer interrupt wait_agent (#28341)

  ## Why
  
  `wait_agent` can block for a long timeout while waiting for sub-agent
  mailbox activity. Although same-turn user steer is accepted during that
  tool call, the input remains pending until the wait returns, so an
  explicit request to change direction can appear unresponsive.
  
  ## What changed
  
  - Notify active `wait_agent` calls when user input is steered into the
  current turn.
  - Check for already-pending steer input when subscribing so input that
  races with tool startup is not missed.
  - Distinguish mailbox activity, steered input, and timeout outcomes,
  returning `Wait interrupted by new input.` for the steer path.
  - Update the `wait_agent` tool description to document the early-return
  behavior.
  
  ## Testing
  
  - `just test -p codex-core input_queue_`
  - `just test -p codex-core wait_agent`
  
  The coverage includes steer notification before and after subscription,
  plus an end-to-end test that verifies the interrupted wait result and
  steered user input are both included exactly once in the follow-up model
  request.

  jif · 2026-06-15 20:08:15 +02:00
  ee40dddbf6
• guardian: isolate review context from skills and memories (#28285)

  ## Why
  
  Guardian reviews embed the parent session transcript as untrusted
  evidence. Skill or plugin mentions in that transcript must not be
  interpreted as requests to inject more instructions into the Guardian
  request, and memory context adds unrelated model-visible context to an
  approval decision.
  
  Keeping those sources out of the nested review session makes the request
  smaller and preserves the trust boundary around the transcript being
  assessed.
  
  ## What changed
  
  - Skip skill and plugin discovery when building turns for Guardian
  reviewer sessions.
  - Disable memory context and dedicated memory tools in the derived
  Guardian configuration.
  - Extend the Guardian request-layout coverage to verify that a `$skill`
  mention remains visible only as transcript evidence while neither the
  skill body nor memory context is injected.
  - Expand the Guardian configuration test to cover the disabled memory
  settings.
  
  ## Testing
  
  - Updated the Guardian review request snapshot and assertions for skill
  and memory isolation.
  - Extended the Guardian session configuration test to cover memories.

  jif · 2026-06-15 19:24:50 +02:00
  a18de1f3b6
• [codex] preserve explicit environment cwd (#27995)

  ## Why
  
  `TurnEnvironmentSelections::new` rewrote the primary environment's
  explicit `cwd` to the legacy fallback cwd. For a remote-first selection,
  this could replace the remote working directory with a local fallback
  path and made the legacy cwd overlay authoritative over
  environment-owned state.
  
  ## What changed
  
  - Preserve every explicit environment cwd when constructing turn
  environment selections.
  - Keep `cwd`-only app-server updates compatible by rebuilding the
  default environment selections at the requested cwd.
  - Cover both explicit primary cwd preservation and cwd-only updates
  reaching the model-visible execution environment.
  
  ## Testing
  
  - `just test -p codex-core
  session_update_settings_does_not_rewrite_sticky_environment_cwds`
  - `just test -p codex-core
  environment_settings_preserve_explicit_primary_cwd`
  - `just test -p codex-app-server
  thread_settings_update_cwd_retargets_default_environment`

  pakrym-oai · 2026-06-15 17:17:34 +00:00
  bd4fe31c5a
• avoid cloning sampling request input (#28306)

  ## Why
  
  Every model request cloned the full prepared input just to keep it for
  the legacy after-agent hook. That copy gets more expensive as the
  conversation grows.
  
  ## What
  
  Move the prepared input into the sampling loop and return it with the
  result. If the request retries, keep the first input so the hook still
  sees the same data as before.
  
  This removes one `O(n)` clone per sampling request, where `n` is the
  size of the prepared input. It saves `O(n)` copy work and `O(n)`
  temporary memory.
  
  No behavior change is intended.
  
  ## Performance
  
  Local rollout traces show turns reaching roughly 260k input tokens. On
  turns of that size, this removes the only unconditional full
  prepared-input clone on the happy path. That avoids one request-sized
  allocation/copy per sampling attempt for large conversations, and the
  savings scale linearly with request size.
  
  ## Testing
  
  - `just test -p codex-core continue_after_stream_error`
  - `just fix -p codex-core`

  jif · 2026-06-15 18:26:44 +02:00
  e67bc683f3
• [codex] simplify shell snapshot ownership (#27756)

  ## Why
  
  Shell snapshot lifecycle state was split between `Shell` and
  `SessionServices`: `Shell` carried the receiver while session code
  exposed and forwarded the raw sender. That coupled shell identity to
  mutable snapshot state and made refresh, inheritance, and file lifetime
  harder to reason about.
  
  ## What changed
  
  - make each `Arc<ShellSnapshot>` represent one cwd-specific snapshot
  generation
  - store the active generation in `SessionServices` with `ArcSwapOption`
  - have construction start the background build and expose only a
  cwd-validated snapshot path
  - use `ShellSnapshotFile` ownership to delete snapshot files
  automatically
  - pass snapshot paths explicitly to shell runtimes instead of storing
  snapshot state on `Shell`
  - preserve inherited and in-flight generations by pinning their `Arc`
  while they are in use
  
  ## Test plan
  
  - `cargo check -p codex-core --lib`
  - `just test -p codex-core 'shell_snapshot::tests'`
  - `just test -p codex-core
  shell_command_snapshot_still_intercepts_apply_patch`
  - `just test -p codex-core
  shell_snapshot_deleted_after_shutdown_with_skills`

  pakrym-oai · 2026-06-15 08:18:13 -07:00
  1aa3e432cc
• skills: hide orchestrator skills with a local executor (#28333)

  ## Why
  
  App-server threads without a local executor need orchestrator-owned
  skills from the hosted `codex_apps` MCP server. Threads with the local
  executor already discover installed skills from the local filesystem.
  
  After the orchestrator skill provider was enabled for every app-server
  thread, local-executor threads also received the hosted skill catalog
  and the `skills.list` and `skills.read` tools. This changed the existing
  local behavior and could expose a second hosted copy of a skill that was
  already installed locally.
  
  ## What changed
  
  - Expose the thread's selected execution environments to extensions at
  thread startup.
  - Enable orchestrator skills only when the reserved local environment is
  not selected.
  - Apply that decision consistently to hosted skill catalog discovery,
  explicit skill injection, and the `skills.list` and `skills.read` tools.
  
  ## Verification
  
  - The existing no-executor app-server test continues to verify hosted
  skill discovery, invocation, and child-resource reads.
  - A new app-server test verifies that local-executor threads do not
  receive hosted skill context or `skills.*` tools.

  jif · 2026-06-15 17:15:45 +02:00
  6d9df687a5
• [codex] exec-server honors remote environment cwd and shell (#28122)

  ## Why
  
  Next slice needed to make progress on the `remote_env_windows` test is
  to support passing a Windows cwd for the remote environment and using
  that environment's native shell. This lets the test run a real Windows
  process instead of only recording an early path or shell mismatch.
  
  ## What
  
  - change `TurnEnvironmentSelection.cwd` from `AbsolutePathBuf` to
  `PathUri`
  - convert local cwd values to URIs when constructing selections
  - preserve a remote primary cwd instead of replacing it with the local
  legacy fallback
  - prefer the selected environment's discovered shell for unified exec,
  falling back to the session shell when unavailable
  - convert back to a host-native absolute path at current native-only
  consumer boundaries
  - reject or deny unsupported foreign cwd values at the existing
  request-permissions boundary, with TODOs for its future migration
  - extend the hermetic Wine test to execute Windows PowerShell in
  `C:\windows` and verify successful process completion
  - record the current app-server rejection against the same Wine-backed
  remote Windows fixture when its cwd is supplied as a native Windows path

  Adam Perry @ OpenAI · 2026-06-14 06:07:46 +00:00
  efbd00f21f
• [codex] Send turn state through compact requests (#28002)

  ## Context
  
  Inline compaction is part of the active logical turn. Compact requests
  and the sampling requests around them should use the same turn state,
  including when compaction is the first request to establish it.
  
  ## Change
  
  Pass the turn-scoped `OnceLock` directly to inline v1 compaction so
  `/responses/compact` includes an established value in the existing HTTP
  header. Capture `x-codex-turn-state` from the compact response into that
  same lock, allowing pre-turn compact to establish the value that
  subsequent sampling reuses.
  
  V2 compact already uses the normal Responses HTTP/WebSocket path and
  continues to share the same `OnceLock` without separate plumbing. The
  first returned value wins for the logical turn.
  
  ## Test plan
  
  Integration coverage verifies that:
  
  - pre-turn v1 compact can establish state for the first sampling request
  - inline v1 compact receives established state over HTTP
  - inline v2 compact reuses established state over HTTP
  - inline v2 compact reuses established state over WebSocket
  
  CI validates the full change.

  Ahmed Ibrahim · 2026-06-13 01:27:58 -07:00
  f297b9f07d
• [codex] add latency tracing spans (#27710)

  ## Why
  
  We have some large gaps in our thread start, resume, and pre-sampling
  traces that make it hard to tell where latency is coming from.
  
  ## What Changed
  
  - Added coarse spans around thread start/resume, turn context
  construction, rollout reconstruction, skill/plugin loading, and tool
  preparation.
  - Added a breakdown of discoverable-tool preparation across connector
  loading, plugin discovery, and local plugin details.
  
  ## Testing
  
  - `cargo check -p codex-app-server -p codex-core -p codex-core-skills -p
  codex-core-plugins`
  - Built the app-server locally and exercised thread start, first turn,
  follow-up turn, server restart, thread resume, and a resumed turn.

  rphilizaire-openai · 2026-06-12 17:11:32 -07:00
  bacfc5e4c0
• [codex] make PathUri::from_abs_path infallible (#27976)

  ## Why
  
  `PathUri::from_abs_path` can fail for absolute paths that do not have a
  normal `file:` URI representation, forcing filesystem call sites to
  handle a conversion error even though the original path can be preserved
  losslessly.
  
  ## What
  
  Make `from_abs_path` infallible and migrate its callers. Unrepresentable
  paths use `file:///%00/bad/path/<base64>`, encoding Unix bytes or
  Windows UTF-16LE; `to_abs_path` validates and decodes that fallback. The
  leading encoded null reserves a namespace that cannot collide with a
  real Unix or Windows path, and fallback URIs remain opaque to lexical
  path operations.
  
  ## Validation
  
  Added path-URI coverage for Unix null and non-UTF-8 paths, Windows
  device/verbatim and non-Unicode paths, serialization, malformed
  fallbacks, opaque lexical operations, invalid native payloads, and
  literal `/bad/path` collision resistance.

  Adam Perry @ OpenAI · 2026-06-12 16:58:42 -07:00
  968a3ac9c1
• feat: use encrypted local secrets for MCP OAuth (#27541)

  ## Summary
  
  - store MCP OAuth credentials in the configured auth credential backend
  - support encrypted-local OAuth storage, including legacy keyring
  migration
  - propagate the credential backend through MCP refresh, session, CLI,
  and app-server paths
  
  ## Stack
  
  1. #27504 — config and feature flag
  2. #27535 — auth-specific secret namespaces
  3. #27539 — encrypted CLI auth storage
  4. this PR — encrypted MCP OAuth storage
  
  This is a parallel review stack; the original #17931 remains unchanged.
  
  ## Tests
  
  - `just test -p codex-rmcp-client` (the transport round-trip test passed
  after building the required `codex` binary and retrying)
  - `just test -p codex-mcp`
  - `just test -p codex-app-server
  refresh_config_uses_latest_auth_keyring_backend`
  - `just test -p codex-core
  refresh_mcp_servers_is_deferred_until_next_turn`
  - `just test -p codex-cli mcp`
  - `just fix -p codex-rmcp-client -p codex-mcp -p codex-core -p codex-cli
  -p codex-app-server -p codex-protocol`
  - `just bazel-lock-check`

  Celia Chen · 2026-06-12 22:03:51 +00:00
  9915d34684
• Support plaintext agent messages (#27830)

  ## Why
  
  Multi-agent v2 `send_message` deliveries already reach the receiving
  model as typed `agent_message` items with encrypted content.
  Child-completion notifications are generated by Codex itself, so their
  content is plaintext and previously fell back to a serialized JSON
  envelope inside an assistant message.
  
  With plaintext `input_text` supported for `agent_message`, both delivery
  paths can use the same model-visible type while preserving explicit
  author and recipient metadata.
  
  ## What changed
  
  - add plaintext `input_text` support to `AgentMessageInputContent` and
  regenerate the affected app-server schemas
  - preserve `InterAgentCommunication` as structured mailbox input instead
  of converting it to assistant text
  - record delivered communications as typed `agent_message` history items
  - persist a dedicated rollout item so local delivery metadata such as
  `trigger_turn` remains available without leaking into the Responses
  request
  - reconstruct typed agent messages on resume and preserve fork-turn
  truncation behavior
  - remove request-time assistant-content parsing
  - preserve plaintext and encrypted inter-agent deliveries in stage-one
  memory inputs
  - normalize and link plaintext and encrypted agent messages in rollout
  traces without treating inbound messages as child results
  - cover the real MultiAgent V2 child-completion path end to end with
  deterministic mailbox synchronization
  
  ## Verification
  
  - `just test -p codex-core
  plaintext_multi_agent_v2_completion_sends_agent_message`
  - `just test -p codex-core input_queue_drains_mailbox_in_delivery_order
  record_initial_history_reconstructs_typed_inter_agent_message
  fork_turn_positions_use_inter_agent_delivery_metadata`
  - `just test -p codex-memories-write
  serializes_inter_agent_communications_for_memory`
  - `just test -p codex-rollout-trace
  agent_messages_preserve_routing_and_content
  sub_agent_started_activity_creates_spawn_edge`
  - `just test -p codex-rollout-trace
  agent_result_edge_falls_back_to_child_thread_without_result_message`
  - `just test -p codex-protocol -p codex-rollout -p
  codex-app-server-protocol`

  jif · 2026-06-12 13:50:04 -07:00
  8f2d6416ce
• sandboxing: migrate cwd inputs to PathUri (#27816)

  ## Why
  
  Sandbox cwd values can cross app-server and exec-server host boundaries.
  They should retain URI semantics until the receiving host validates them
  instead of being interpreted early as native paths.
  
  ## What
  
  - Carry `PathUri` through filesystem sandbox contexts, sandbox commands,
  and transform inputs.
  - Convert command and policy cwd once in `SandboxManager::transform`,
  then keep launch requests native.
  - Preserve sandbox cwd over remote filesystem transport and reject
  non-native URIs without fallback.
  - Cache paired native/URI turn-environment cwd values during migration,
  with immutable access to keep them synchronized.
  - Extend existing protocol, forwarding, transform, and core runtime
  tests.

  Adam Perry @ OpenAI · 2026-06-12 11:38:01 -07:00
  52a50aec70
• Make MCP server contributions thread-scoped (#27670)

  ## Why
  
  `selectedCapabilityRoots` belongs to one thread, but MCP contributors
  previously received only the global Codex config. That left no clean way
  for a selected executor capability to contribute MCP servers to its own
  thread.
  
  ## What this PR does
  
  - Gives MCP contributors a small context containing the config and, for
  a running thread, its frozen host-seeded inputs.
  - Uses the same thread inputs during startup, status queries, refreshes,
  and skill dependency checks.
  - Keeps threadless MCP operations and the existing hosted Apps behavior
  unchanged.
  - Adds coverage showing that two threads resolve independent
  registrations and that later lifecycle mutations do not change the
  frozen MCP inputs.
  
  This PR does not discover plugin manifests, add MCP servers, or launch
  anything new. It only establishes the thread-scoped registration
  boundary.
  
  ## Follow-ups
  
  - Resolve selected executor plugin roots through their owning
  environment filesystem.
  - Convert their stdio MCP declarations into environment-bound
  registrations and add an executor MCP end-to-end test.
  
  ## Verification
  
  - `just fmt`
  - `cargo check --tests -p codex-protocol -p codex-extension-api -p
  codex-mcp-extension -p codex-core -p codex-app-server`
  
  Tests and Clippy were not run.

  jif · 2026-06-12 11:20:34 +02:00
  693082f3c4
• [codex] Load AGENTS.md from all bound environments (#27696)

  ## Why
  
  We already have the machinery to support multiple environments on a
  single thread, but we only show the model the contents of `AGENTS.md`
  files in the primary environment.
  
  We should show the model all of the relevant project instructions when
  we know there's more than one environment.
  
  ## Known Gaps
  
  As discussed in the RFC, this implementation:
  
  1. doesn't handle environments being added/removed to/from the thread
  after its creation
  2. it doesn't enforce an aggregate context budget across environments,
  and instead applies the configured project maximum independently to each
  environment
  
  ## Implementation
  
  - Discover project instructions in environment order with an independent
  byte budget per environment and preserve source provenance/order.
  - Keep the legacy fragment byte-for-byte when exactly one environment
  contributes project instructions; use environment-labeled sections when
  two or more environments contribute.
  - Freeze the complete rendered fragment in `LoadedAgentsMd`, insert it
  directly into requests, and recognize both layouts in contextual and
  memory filtering.
  - Add exact rendering, independent-budget, source-order,
  creation-snapshot, and consumer coverage without changing app-server
  schemas.

  Adam Perry @ OpenAI · 2026-06-12 00:10:06 -07:00
  bf667c7003
• Add request_user_input auto-resolution window contract (#27256)

  ## Why
  
  `request_user_input` is moving beyond its original plan-mode-only
  workflow, and future default/goal-mode usage needs a way for the model
  to ask helpful but non-blocking questions without forcing the turn to
  wait forever. This PR adds an explicit `autoResolutionMs` contract so a
  later client/runtime change can auto-resolve unanswered prompts after a
  bounded window while leaving truly blocking questions unchanged.
  
  This is contract plumbing only; it does not implement the client-side
  timer or auto-selection behavior, and the model-facing description
  treats the field as reserved unless the current runtime explicitly
  supports auto-resolution.
  
  ## What Changed
  
  - Added optional `autoResolutionMs` to the model-facing
  `request_user_input` args and core `RequestUserInputEvent`.
  - Added model-facing schema text for `autoResolutionMs` while marking it
  reserved for runtimes that explicitly support auto-resolution.
  - Bounds `autoResolutionMs` to `60_000..=240_000` ms during argument
  normalization by clamping out-of-range model-provided values.
  - Propagated the field through app-server v2
  `ToolRequestUserInputParams`, app-server request forwarding, generated
  TypeScript, and JSON schema fixtures.
  - Updated app-server, core, protocol, and TUI call sites/tests so
  omitted values preserve existing `None`/`null` behavior and coverage
  verifies a `Some(60_000)` round trip.
  
  ## Verification
  
  - `just test -p codex-app-server-protocol`
  - `just test -p codex-core request_user_input`
  - `just test -p codex-app-server request_user_input_round_trip`
  - `just test -p codex-tui request_user_input`
  - `just test -p codex-protocol`

  Shijie Rao · 2026-06-11 22:30:41 -07:00
  216ce03031
• [codex] resolve environment shell metadata eagerly (#27709)

  ## Why
  
  Turn construction passed resolved environments through several layers
  while leaving the environment shell unresolved. As a result,
  model-visible environment context could fall back to the session shell
  instead of reporting the selected remote environment's shell.
  
  Resolve environment metadata at the turn-context boundary so each turn
  carries the shell that belongs to its selected environment. Keep request
  validation in app-server, where invalid selections can be returned as
  straightforward JSON-RPC errors without coupling core turn construction
  to that policy.
  
  ## What changed
  
  - resolve environment selections eagerly in
  `new_turn_context_from_configuration`
  - store the full resolved `Shell` on each `TurnEnvironment`
  - simplify the now-redundant resolved-environment constructor plumbing
  - keep duplicate and unknown-environment validation as a small
  app-server preflight
  - add a remote-environment integration test that runs a full
  `test_codex` turn and verifies the model-visible environment message
  reports `bash`
  
  ## Testing
  
  - `cargo check -p codex-core --test all -p codex-app-server`
  - `remote_test_env_exposes_bash_shell_to_model` on the Linux
  remote-executor harness

  pakrym-oai · 2026-06-11 20:35:28 -07:00
  be338ee9a2
• Add spans to turn lifecycle gaps (#27623)

  ## Why
  Codex app-server latency traces do not granularly cover turn task
  startup and inter-request handoffs. These spans help attribute time
  across task execution, startup prewarm, in-flight tool completion, and
  rollout persistence.
  
  ## What changed
  - Add `session_task.run` spans around task execution and
  `session_task.flush_rollout` around flushing pending conversation
  transcript writes to durable storage
  - Add `regular_task.prepare_run_turn` around regular-turn startup (Send
  the `TurnStarted` event, reset turn-specific reasoning state, and
  resolve any startup prewarm)
  - Add `startup_prewarm.resolve` around waiting for background session
  prewarming to finish, fail, time out, or be cancelled
  - Add a function-level trace span around draining in-flight tool calls
  (Wait for tool calls to complete, record tool result in conversation
  history, and other bookkeeping)
  
  ## Verification
  Trigger Codex rollout and observe new spans are included

  mchen-oai · 2026-06-11 16:55:01 -07:00
  92d9036910
• [codex] Move persistence policy application into ThreadStore (#27318)

  Move the application of the persistence policy into the thread store, so
  thread stores can get raw append items rather than canonical append
  items. This will enable store-specific projections over the raw input
  items.

  Tom · 2026-06-11 16:24:12 -07:00
  b2cc01fc7c
• Include thread id in token budget context (#27663)

  ## Why
  
  The token budget full-context fragment identifies the current context
  window, but not the thread that owns that window. Including the thread
  id makes the initial context-window metadata self-contained, and
  `get_context_remaining` also needs to be usable from Code Mode without
  forcing callers to parse the model-facing fragment string.
  
  ## What changed
  
  - Include the session thread id in the initial `<token_budget>` context
  fragment.
  - Expose `get_context_remaining` as a Code Mode nested tool while
  keeping `new_context` direct-model-only.
  - Keep direct model-facing `get_context_remaining` output as the
  existing `<token_budget>` text fragment.
  - Return only `tokens_left` from the Code Mode structured result for
  `get_context_remaining`.
  - Update token-budget integration tests and add Code Mode coverage for
  the structured result.
  
  ## Verification
  
  - `just test -p codex-core token_budget`
  - `just test -p codex-core
  code_mode_get_context_remaining_returns_structured_result`
  - `just test -p core_test_support redacted_text_mode_normalizes_uuids`

  pakrym-oai · 2026-06-11 15:10:29 -07:00
  7516eb5c70
• core: Consolidate Responses API Codex metadata (#27122)

  ## What
  Introduce a `CodexResponsesMetadata` struct that defines all the core
  metadata we send to Responses API. Example fields are `thread_id`,
  `turn_id`, `window_id`, etc.
  
  Going forward, `client_metadata["x-codex-turn-metadata"]` will be the
  canonical way Codex sends metadata to Responses API across both HTTP and
  websocket transports.
  
  For now, we continue to emit the existing top-level HTTP headers and
  top-level `client_metadata` fields from the same
  `CodexResponsesMetadata` struct for compatibility reasons.
  
  Also, app-server clients who specify additional
  `responsesapi_client_metadata` via `turn/start` and `turn/steer` will
  have those fields merged into
  `client_metadata["x-codex-turn-metadata"]`, but cannot override the
  reserved fields that core uses (i.e. the fields in
  `CodexResponsesMetadata`).
  
  ## Why
  
  Responses API request instrumentation is the source of truth for
  downstream Codex analytics that join requests by Codex IDs such as
  session, thread, turn, and context window. Before this change, those
  values were assembled through several request-specific paths: HTTP
  request bodies, websocket handshake headers, websocket `response.create`
  payloads, compaction requests, and the rich `x-codex-turn-metadata`
  envelope all had their own wiring.
  
  That made metadata propagation easy to drift across API-key/direct
  Responses API requests, ChatGPT-auth/proxied requests, websocket
  requests, and compaction requests. It also made additions like
  `window_id` error-prone because a field could be added to one transport
  projection but missed in another.
  
  ## What changed
  
  - Added `CodexResponsesMetadata` as the core-owned snapshot for Codex
  metadata sent to ResponsesAPI.
  - Render `client_metadata["x-codex-turn-metadata"]`, flat
  `client_metadata` projections, and direct compatibility headers from
  that same snapshot.
  - Include the known Codex-owned fields in the turn metadata blob,
  including installation/session/thread/turn/window IDs, request kind,
  lineage, sandbox/workspace metadata, timing, and compaction details.
  - Treat app-server `responsesapi_client_metadata` as enrichment for the
  Codex turn metadata blob while preventing those extras from overriding
  Codex-owned fields.
  - Use the same metadata path for normal turns, websocket prewarm, local
  compaction, remote v1 compaction, and remote v2 compaction.
  - Keep websocket connection-only preconnect metadata separate so
  handshakes carry compatibility identity headers without inventing a fake
  turn metadata blob.
  
  ## Verification
  
  - `cargo check -p codex-core`
  - `just fix -p codex-core`

  Owen Lin · 2026-06-11 13:42:09 -07:00
  14df0e8833
• Resolve MCP server registrations through a catalog (#27634)

  ## Why
  
  MCP servers currently come from user config, local plugins,
  compatibility Apps synthesis, and host extensions. Those sources were
  composed by mutating a shared map, leaving registration identity,
  precedence, removal, and provenance implicit in assembly order.
  
  Before adding executor-owned MCPs, Codex needs one durable resolution
  boundary above `McpConnectionManager`. This PR introduces that boundary
  while preserving current server configuration, policy, and runtime
  behavior. Executor-scoped registrations and explicit policy layers
  remain follow-ups.
  
  ## What changed
  
  - Add typed `McpServerRegistration` inputs and an immutable
  `ResolvedMcpCatalog` in `codex-mcp`.
  - Retain each registration's complete `McpServerConfig`, including its
  environment binding, while recording its source and provenance.
  - Preserve the existing structural precedence between plugin, config,
  compatibility, and ordered extension sources.
  - Resolve equal-precedence actions by contribution order; provenance IDs
  are used only for diagnostics and cannot affect the winner.
  - Preserve extension removals and the existing name-scoped `enabled =
  false` veto.
  - Report same-tier conflicts with every contender and the final catalog
  outcome, including whether the winning action registers or removes the
  server.
  - Require MCP contributors to provide a stable diagnostic identity.
  - Derive materialized server maps and plugin ownership from the resolved
  catalog.
  
  `McpConnectionManager`, transport startup, tool calls, and resource
  routing continue to consume the same effective `McpServerConfig` values.
  
  ## Scope
  
  This PR does not add new MCP capabilities or change user-visible
  behavior. It does not add executor plugin discovery, thread-scoped
  registrations, dynamic refresh generations, or new user/managed policy
  semantics.
  
  ## Verification
  
  - Added focused catalog coverage for source precedence, complete
  configuration preservation, disabled vetoes, plugin ownership,
  contribution-order tie breaking, removal outcomes, and conflict
  diagnostics.
  - Extended hosted Apps coverage for ordered extension removal and
  Apps-disabled hosts with and without the hosted extension installed.
  - `cargo check -p codex-mcp --tests -p codex-extension-api -p
  codex-core`

  jif · 2026-06-11 21:54:52 +02:00
  4a5a676499
• [codex] Load user instructions through an injected provider (#27101)

  ## Why
  
  We want to remove implicit use of `$CODEX_HOME` from `codex-core` and
  make embedders responsible for supplying user-level instructions. This
  also ensures user instructions load when no primary environment is
  selected.
  
  ## What changed
  
  Stacked on #27415, which makes `codex exec` surface thread-scoped
  runtime warnings.
  
  - Added `UserInstructionsProvider` to `codex-extension-api`, with
  absolute source attribution and recoverable loading warnings.
  - Added `codex-home` with the filesystem-backed provider for
  `AGENTS.override.md` and `AGENTS.md`, preserving precedence, fallback,
  trimming, lossy UTF-8 handling, and the existing uncapped global
  instruction size.
  - Removed global instruction loading from `Config` and require
  `ThreadManager` callers to inject a provider.
  - Load provider instructions once for each fresh root runtime, including
  runtimes without a primary environment. Running sessions retain their
  snapshot, while child agents inherit the parent snapshot without
  invoking the provider.
  - Keep provider instructions separate while loading project `AGENTS.md`,
  then assemble the model-visible instructions with the existing ordering,
  source attribution, warning, and turn-context behavior.
  - Wired the Codex home provider through the CLI, app server, MCP server,
  core facade, and thread-manager sample.
  
  ## Validation
  
  - `just test -p codex-home -p codex-extension-api`
  - `just test -p codex-core agents_md`
  - `just test -p codex-core guardian`
  - `just test -p codex-app-server
  thread_start_without_selected_environment_includes_only_global_instruction_source`
  - `just test -p codex-exec warning`
  - `just bazel-lock-check`

  Adam Perry @ OpenAI · 2026-06-11 19:28:47 +00:00
  236b50125d
• skills: make backend plugin skills invocable without an executor (#27387)

  ## Why
  
  #27198 made the extension-owned `codex_apps` MCP connection the hosted
  plugin runtime, but its `mcp/skill` resources still bypassed the skills
  extension. App-server could list and read those resources through
  generic MCP APIs, but a thread with no selected environment did not
  expose them in the model's skills catalog or load their `SKILL.md`
  through `$skill`.
  
  Hosted skills should stay remote while using the same typed catalog,
  source authority, deduplication, bounded contextual catalog, and
  selected-skill prompt injection as host and executor skills. They should
  not be downloaded or exposed as ambient filesystem paths.
  
  ## What changed
  
  - Add a session-scoped `McpResourceClient` over the replaceable MCP
  connection manager so resource list/read calls follow startup and
  refresh replacements.
  - Add a `BackendSkillProvider` that pages `codex_apps` resources,
  accepts bounded and validated `mcp/skill` entries, and reads a selected
  skill's `SKILL.md` through the same MCP connection.
  - Register the remote provider in app-server and include it in the
  skills catalog even when a thread has no selected capability roots or
  executor.
  - Contribute hosted skill metadata through the bounded
  `AvailableSkillsInstructions` developer-context path, exclude remote
  entries from per-turn catalog injection, and classify `<skills>`
  messages as contextual developer content so rollback can trim and
  rebuild them correctly.
  
  ## Testing
  
  - Extend the app-server MCP resource integration test with
  `environments: []` to exercise two-page discovery, filter a
  non-`mcp/skill` resource, verify the escaped developer catalog entry and
  user-role `<skill>` fragment containing the fetched `SKILL.md`, and
  preserve generic MCP resource reads.
  - Add core event-mapping coverage that classifies `<skills>` developer
  messages as contextual history.

  jif · 2026-06-11 11:28:16 +02:00
  a287c5dffd
• [codex] Compact when comp_hash changes (#27520)

  ## Summary
  - snapshot `comp_hash` into `TurnContext` when the turn is created and
  use that snapshot as the downstream source of truth
  - persist the turn hash in rollout context and recover it into
  previous-turn settings during resume and fork replay
  - compact existing history with the previous model only when both
  adjacent turns provide hashes and the values differ
  - record `comp_hash_changed` as the compaction reason
  - cover ordinary transitions, resume, and missing-hash compatibility
  with end-to-end tests
  
  ## Why
  History produced under one compaction-compatible model configuration may
  not be safe to carry directly into another. Compacting at the turn
  boundary converts that history before context updates and the new user
  message are added. Persisting the turn snapshot in `TurnContextItem`
  makes the same protection work after resuming a rollout.
  
  A missing hash is not treated as evidence of incompatibility. `None →
  Some`, `Some → None`, and `None → None` do not trigger compaction; only
  `Some(previous) → Some(current)` with unequal values does.
  
  ## Stack
  - depends on #27532
  - #27532 is based directly on `main`
  
  ## Testing
  - `just test -p codex-core pre_sampling_compact_` — 6 passed
  - `just test -p codex-core
  turn_context_item_uses_turn_context_comp_hash_snapshot` — passed
  - `just fix -p codex-core -p codex-protocol -p codex-analytics -p
  codex-models-manager`

  Ahmed Ibrahim · 2026-06-11 04:11:26 +00:00
  ba4925b3c2
• [codex] Add new context window tool (#27488)

  ## Why
  
  The token budget feature tells the model how much room remains in the
  current context window. When the model decides the current window is no
  longer useful, it needs a way to ask Codex to start over with a fresh
  context window without spending tokens on a compaction summary.
  
  This PR adds that model-requestable escape hatch on top of #27438.
  
  ## What changed
  
  - Added a direct-model-only `new_context` tool behind
  `Feature::TokenBudget`.
  - Stores the tool request on `AutoCompactWindow` and consumes it after
  sampling so the next follow-up request in the same turn starts in the
  new window.
  - Starts the new window as a no-summary compaction checkpoint that
  contains only fresh initial context, not preserved conversation history.
  - Keeps the new window aligned with token-budget startup context,
  including the `Current context window Z` message.
  - Added integration coverage and a snapshot showing the same-turn
  `new_context` flow into a fresh full-context follow-up request.
  
  ## Validation
  
  - `just test -p codex-core token_budget`

  pakrym-oai · 2026-06-11 03:39:07 +00:00
  87ab01834a
• [codex] Add token budget context feature (#27438)

  ## Why
  
  The model should be able to see bounded context-window budget metadata
  when the `token_budget` feature is enabled. The full-window message is
  only injected with full context, while normal turns get a smaller
  follow-up only when reported usage first crosses a budget threshold.
  
  ## What changed
  
  - Added the `TokenBudget` feature flag.
  - Added `<token_budget>` developer fragments for full context-window
  metadata and current-window remaining tokens.
  - Inserted the threshold message during normal turn handling by
  comparing token usage before and after sampling, avoiding persistent
  threshold bookkeeping.
  - Added core integration coverage for full-context-only metadata and
  25/50/75 percent threshold messages.
  
  ## Verification
  
  - `just test -p codex-core token_budget`
  - `git diff --check`

  pakrym-oai · 2026-06-10 20:07:06 -07:00
  658af936fd
• core: resize all history images behind a feature flag (#27247)

  ## Summary
  
  Adds complete client-side image preparation behind the default-off
  `resize_all_images` feature flag.
  
  When enabled, local image producers defer decoding and resizing. Images
  are prepared centrally before insertion into conversation history,
  covering user input, `view_image`, and structured tool-output images.
  
  ## Behavior
  
  - Processes base64 `data:` images in messages and function/custom tool
  outputs.
  - Leaves non-data URLs, including HTTP(S) URLs, unchanged.
  - Applies image-detail budgets:
    - `high` and omitted: 2048px maximum dimension and 2.5K 32px patches.
    - `original`: 6000px maximum dimension and 10K 32px patches.
    - `auto`: uses the same 2048px / 2.5K-patch budget as high.
    - `low`: unsupported and replaced with an actionable placeholder.
  - Preserves original image bytes when no resize or format conversion is
  needed.
  - Enforces the shared 1 GiB encoded and decoded data-URL sanity limits.
  - Replaces only an image that fails preparation, preserving sibling
  content and tool-output metadata.
  - Uses bounded placeholders distinguishing generic processing failures,
  oversized images, and unsupported `low` detail.
  - Prepares resumed and forked history before installing it as live
  history without modifying persisted rollouts.
  
  ## Flag-Off Behavior
  
  When `resize_all_images` is disabled:
  
  - Existing local user-input and `view_image` processing remains
  unchanged.
  - Existing decoding and error behavior remains unchanged.
  - Arbitrary tool-output images are not processed.
  - HTTP(S) image URLs continue to be forwarded unchanged.
  
  
  #### [git stack](https://github.com/magus/git-stack-cli)
  - ✅ `1` https://github.com/openai/codex/pull/27245
  - 👉 `2` https://github.com/openai/codex/pull/27247
  - ⏳ `3` https://github.com/openai/codex/pull/27246
  - ⏳ `4` https://github.com/openai/codex/pull/27266

  Curtis 'Fjord' Hawthorne · 2026-06-10 19:21:24 -07:00
  a6f435ea94
• Forward standalone assistant output to realtime (#27319)

  ## Why
  
  When a realtime session is open without an active frontend-model
  handoff, completed Codex assistant messages are currently dropped. That
  prevents the frontend model from hearing orchestrator preambles and
  final responses produced by typed turns or other non-handoff work, which
  makes the two models present as disconnected personas.
  
  Active handoffs already forward each completed assistant message,
  including preambles. This change leaves those V1 and V2 paths intact and
  fills only the no-active-handoff gap.
  
  ## What changed
  
  - Send standalone V1 assistant messages through
  `conversation.handoff.append` with a stable synthetic handoff ID
  - Send standalone V2 assistant messages as normal `[BACKEND]`
  `conversation.item.create` message items, then enqueue `response.create`
  so the frontend model responds
  - Preserve the existing active V1 and V2 transport and completion
  behavior
  - Continue excluding user messages from realtime mirroring
  - Skip empty output and cap each complete context injection, including
  its V2 prefix, at 1,000 tokens
  - Add end-to-end coverage for both wire formats, V2 response creation,
  preambles, final responses, and truncation
  
  ## Test plan
  
  - CI

  guinness-oai · 2026-06-10 21:32:29 +00:00
  22dd6ebc7d
• [codex] Store compact window id in rollout (#27264)

  ## Why
  
  Compaction window identity is part of session history, not model-client
  transport state. Persisting it with the compacted rollout item lets
  resumed threads continue from the reconstructed window without keeping
  mutable window state on `ModelClient`.
  
  ## What changed
  
  - Added `window_id` to `CompactedItem` and stamp it when
  `replace_compacted_history` installs compacted history.
  - Moved auto-compact window id ownership into `AutoCompactWindow` /
  `SessionState`; `ModelClient` now receives the request window id from
  callers instead of storing it.
  - Returned `window_id` from rollout reconstruction for resume.
  Reconstruction uses the newest surviving compacted item's stored
  `window_id` when present, and falls back to the legacy compacted-item
  count when it is absent.
  - Kept fork startup at the fresh default window id and updated direct
  model-client tests to pass explicit test window ids.
  
  ## Validation
  
  - `cargo check -p codex-core --tests`

  pakrym-oai · 2026-06-10 08:47:16 -07:00
  30ddb3325e
• Use latest-wins MCP manager replacement (#27259)

  ## Summary
  
  We originally addressed startup prewarming holding the read side of
  `RwLock<McpConnectionManager>` by snapshotting tool-list state. Review
  feedback identified the broader ownership problem: the outer
  synchronization should only publish or retrieve the current manager,
  while MCP operations rely on the manager's internal synchronization. A
  follow-up preserved operation retirement with a separate gate, but
  further review questioned whether that synchronization was actually
  required and whether we could support latest-wins replacement instead.
  
  This PR now stores the current MCP manager in `ArcSwap`. Each operation
  uses `load_full()` to obtain an owned `Arc<McpConnectionManager>`, then
  performs MCP I/O without retaining the publication mechanism. Refresh
  cancels obsolete startup work, constructs a replacement, and atomically
  publishes it. New operations see the latest manager, while operations
  that already loaded the previous manager retain a valid handle. Refresh
  happens at a turn boundary, so there should be no active user tool calls
  to drain.
  
  Git history supports dropping the outer `RwLock`. It was introduced in
  `03ffe4d595` on November 17, 2025 for non-blocking MCP startup: the
  session published an empty manager, startup initialized that same object
  while holding the write lock, and readers waited for initialization.
  `7cd2e84026` on February 19, 2026 removed that two-phase initialization
  in favor of constructing a fresh manager and swapping it in, explicitly
  noting that `Option` or `OnceCell` could replace the placeholder design.
  Hot reload later reused the existing lock to publish a replacement, but
  I found no indication that the lock was introduced to guarantee
  in-flight tool calls finish before refresh or shutdown.
  
  Terminal shutdown remains separate from refresh: it aborts startup
  prewarming and active tasks before shutting down the current manager, so
  tool calls may be interrupted and no model WebSocket work continues
  after shutdown. Focused regression coverage exercises pending tool-list
  cancellation, deferred refresh, and startup-prewarm shutdown.

  Charlie Marsh · 2026-06-10 08:33:21 -07:00
  41b4fabbb4
• Remove async-trait from extension contributors (#27383)

  ## Why
  
  Extension contributors are registered behind `dyn Trait` objects, so
  native `async fn`/RPITIT methods would make these traits
  non-object-safe. Spell out the boxed, `Send` future contract directly so
  `extension-api` no longer needs `async-trait` while retaining the
  existing runtime model.
  
  ## What changed
  
  - add a shared `ExtensionFuture` alias and use it for asynchronous
  contributor methods
  - migrate production and test implementations to return `Box::pin(async
  move { ... })`
  - remove `async-trait` dependencies where they are no longer used,
  keeping it dev-only where unrelated test executors still require it
  
  ## Behavior
  
  No behavior change is intended. Contributor futures remain boxed,
  `Send`, dynamically dispatched, and lazily executed; cancellation and
  callback ordering stay unchanged.
  
  ## Testing
  
  - `just test -p codex-extension-api` (11 passed)
  - affected extension crates (64 passed)
  - targeted `codex-core` contributor tests (14 passed)
  - `just fmt`
  - `just bazel-lock-update`
  - `just bazel-lock-check`
  
  A broad local `codex-core` run compiled successfully but encountered
  unrelated sandbox and missing test-binary fixture failures; CI will run
  the full checks.

  jif · 2026-06-10 14:31:09 +02:00
  d2f6d23c6c
• Use plugin-service MCP as the hosted plugin runtime (#27198)

  ## Stack
  
  - Base: #27191
  - This PR is the third vertical and should be reviewed against
  `jif/external-plugins-2`, not `main`.
  
  ## Why
  
  #27191 moves the host-owned Apps MCP registration behind an extension
  contributor, but deliberately preserves the existing endpoint-selection
  feature while that contribution contract lands. App-server can therefore
  resolve the server through extensions, yet the hosted plugin endpoint is
  still selected through temporary `apps_mcp_path_override` plumbing.
  
  That is not the long-term plugin model. A plugin can bundle skills,
  connectors, MCP servers, and hooks, and those components do not all need
  the same source or execution environment. In particular, an
  authenticated HTTP MCP server can expose plugin capabilities directly
  from a backend without an executor or an orchestrator filesystem.
  
  This PR completes that hosted vertical. App-server's MCP extension now
  owns the aggregate hosted plugin runtime at `/ps/mcp`. Connector actions
  continue to arrive as MCP tools, while backend-provided skills arrive as
  MCP resources and use Codex's existing resource list/read paths. No
  second backend client, skill filesystem, or generic plugin activation
  framework is introduced.
  
  The backend route remains the hosted implementation. This change
  replaces Codex's temporary endpoint-selection mechanism, not the service
  behind the endpoint.
  
  ## What changed
  
  ### Hosted plugin runtime
  
  The MCP extension now contributes `codex_apps` as the hosted plugin
  runtime rather than as a configurable Apps endpoint:
  
  - `https://chatgpt.com` resolves to
  `https://chatgpt.com/backend-api/ps/mcp`;
  - a bare custom ChatGPT base resolves to `/api/codex/ps/mcp`;
  - the existing product-SKU header and ChatGPT authentication behavior
  are preserved;
  - executor availability is never consulted for this streamable HTTP
  transport.
  
  The same MCP connection carries both component shapes supported by the
  hosted endpoint:
  
  - connector actions are discovered and invoked as MCP tools;
  - hosted skills are enumerated and read as MCP resources through the
  existing `list_mcp_resources` and `read_mcp_resource` paths.
  
  This keeps component access in the subsystem that already owns the
  protocol instead of downloading backend skills into an orchestrator
  filesystem or inventing a parallel hosted-skill client.
  
  ### Explicit runtime ordering
  
  `McpManager` now resolves the reserved `codex_apps` entry in three
  ordered phases:
  
  1. install the legacy Apps fallback for compatibility;
  2. apply ordered extension `Set` or `Remove` overlays;
  3. apply the final ChatGPT-auth gate without synthesizing the server
  again.
  
  This ordering is important:
  
  - an ordinary configured or plugin MCP server cannot claim the
  auth-bearing `codex_apps` name;
  - an extension-contributed hosted runtime wins over the fallback;
  - an extension `Remove` remains authoritative;
  - a host without the MCP extension retains the legacy Apps endpoint and
  current local-only behavior.
  
  The temporary `legacy_apps_mcp_loader_enabled` coordination flag is no
  longer needed.
  
  ### Remove the path override
  
  The `apps_mcp_path_override` feature and its runtime plumbing are
  removed, including:
  
  - the feature registry entry and structured feature config;
  - `Config` and `McpConfig` fields;
  - config schema output;
  - config-lock materialization;
  - URL override handling in `codex-mcp`.
  
  Existing boolean and structured forms still deserialize as ignored
  compatibility input. They are omitted from new serialized config, and
  config-lock comparison normalizes the removed input so older locks
  remain replayable.
  
  ### App-server coverage
  
  App-server MCP fixtures now serve the hosted route at
  `/api/codex/ps/mcp`. Existing resource-read and tool/elicitation flows
  therefore exercise the extension-owned endpoint rather than succeeding
  through the legacy fallback.
  
  The stack also adds the missing `codex_chatgpt::connectors` re-export
  for the manager-backed connector helper introduced in #27191.
  
  ## Compatibility
  
  - App-server installs the extension and uses `/ps/mcp` for the hosted
  runtime.
  - CLI and other hosts that do not install the extension retain the
  legacy Apps endpoint.
  - Apps disabled or non-ChatGPT authentication removes `codex_apps` from
  the effective runtime view.
  - Existing local plugins, local skills, executor-selected skills,
  configured MCP servers, and MCP OAuth behavior are otherwise unchanged.
  - Backend plugin enablement remains account/workspace state owned by the
  hosted endpoint; this PR does not add thread-local backend plugin
  selection.
  
  ## Architectural fit
  
  The stack now proves two independent runtime shapes:
  
  1. #27184 resolves filesystem-backed skills through the executor that
  owns a selected root.
  2. #27191 and this PR resolve a backend-hosted HTTP MCP through an
  extension with no executor.
  
  Together they preserve the intended separation:
  
  - selection identifies a plugin/root when explicit selection is needed;
  - each component's owning extension resolves its concrete access
  mechanism;
  - execution stays with the runtime required by that component;
  - existing skills, MCP, connector, and hook subsystems remain the
  downstream consumers.
  
  ## Planned follow-ups
  
  1. **Executor stdio MCP:** selecting an executor plugin registers a
  manifest-declared stdio MCP server and executes it in the environment
  that owns the plugin.
  2. **Optional backend selection:** only if CCA needs thread-local
  selection distinct from backend account/workspace enablement, add a
  concrete backend-owned capability location and surface those selected
  skills through the skills catalog.
  3. **Connector metadata and hooks:** activate those plugin components
  through their existing owning subsystems, with executor hooks remaining
  environment-bound.
  4. **Propagation and persistence:** define explicit resume, fork,
  subagent, refresh, and environment-removal semantics once selected roots
  have multiple real consumers.
  5. **Local convergence:** migrate legacy local skill, MCP, connector,
  and hook paths behind their owning extensions one vertical at a time,
  then remove duplicate core managers and compatibility plumbing after
  parity.
  
  ## Verification
  
  Coverage in this change exercises:
  
  - extension-owned `/backend-api/ps/mcp` registration without an
  executor;
  - preservation of the legacy endpoint in hosts without the extension;
  - extension `Set` and `Remove` precedence over the legacy fallback;
  - ChatGPT-auth gating for the reserved server;
  - hosted MCP resource reads with and without an active thread;
  - connector tool invocation and MCP elicitation through the hosted
  route;
  - ignored boolean and structured forms of the removed path override;
  - config-lock replay compatibility for the removed feature.
  
  `cargo check -p codex-features -p codex-mcp-extension -p
  codex-app-server` passes. Tests and Clippy were not run locally under
  the current development instruction; CI provides the full validation
  pass.

  jif · 2026-06-10 12:54:21 +02:00
  9cd11e9e62
• [codex] Make MCP connection startup fallible (#27261)

  ## Why
  
  Required MCP server startup was enforced in `Session::new` after
  `McpConnectionManager` had already created the clients. That split let
  other manager construction paths bypass the same requirement and exposed
  manager internals solely so the session could validate them. Keeping
  required-server readiness in the constructor gives every caller one
  consistent startup contract.
  
  ## What changed
  
  - make `McpConnectionManager::new` return `anyhow::Result<Self>` and
  fail when an enabled, required server cannot initialize
  - pass the startup cancellation token into the constructor so
  required-server waits remain cancellable
  - propagate constructor failures through resource reads, connector
  discovery, and MCP status collection
  - preserve the active manager and cancellation token when a refreshed
  replacement fails
  - keep required-startup failure collection private and cover the
  constructor error contract directly
  
  ## Validation
  
  - updated the focused connection-manager test to assert the complete
  required-server startup error
  - local tests not run; relying on CI

  Ahmed Ibrahim · 2026-06-10 00:17:58 -07:00
  a7b6baecc6
• Add spans to run_turn (#27107)

  ## Why
  Codex app-server latency traces do not granularly cover turn
  orchestration, sampling-request preparation, and tool-loading work.
  These spans help separate local coordination/setup costs from model
  streaming and tool execution.
  
  ## What changed
  - Add `run_turn.*` spans around sampling-request input preparation and
  post-sampling state collection
  - Add function-level trace spans around turn setup, hook execution,
  compaction, prompt construction, and MCP tool exposure
  - Add `built_tools.*` spans around plugin loading and discoverable-tool
  loading
  
  ## Verification
  Trigger Codex rollout and observe new spans are included

  mchen-oai · 2026-06-10 04:41:06 +00:00
  00a25e1e0c
• Stop mirroring Codex user input into realtime (#27116)

  ## Why
  
  The realtime frontend model and the backing Codex thread should present
  one coherent assistant. Raw typed messages, steers, and worker reports
  belong to the orchestrator; the frontend model should receive the
  orchestrator's user-facing result rather than a second copy of those
  inputs.
  
  Today normal `turn/start` input is automatically inserted into the
  realtime conversation, while `turn/steer` is not. Besides creating
  inconsistent context, this can make the frontend model react
  independently before Codex has produced the response it should speak.
  
  ## What changed
  
  - Remove automatic accepted-user-input mirroring into realtime
  - Remove the mirror-only echo-suppression flag and dead V2 prefix helper
  - Preserve explicit app-to-realtime text injection and FEM-to-Codex
  delegation
  - Replace the positive mirror tests and obsolete snapshots with a
  negative routing regression test
  
  ## Test plan
  
  - `cargo test -p codex-core
  conversation_user_text_turn_is_not_sent_to_realtime`
  - `cargo test -p codex-core
  conversation_startup_context_is_truncated_and_sent_once_per_start`
  - `cargo test -p codex-core inbound_handoff_request_starts_turn`

  guinness-oai · 2026-06-09 15:20:01 -07:00
  cc8325f181