12 Commits

• feat: add extension turn-input contributors (#25959)

  ## Disclaimer
  Do not use for now
  
  ## Why
  
  Extensions can already contribute prompt fragments and request same-turn
  item injection, but there was no host-owned hook for contributing
  structured `ResponseItem`s while Codex is assembling a new turn's
  initial model input. This change adds that seam so extensions can attach
  turn-local input that depends on the submitted user input and resolved
  turn environments without routing through prompt text or late injection.
  
  ## What changed
  
  - add `TurnInputContributor` to `codex_extension_api` and export the new
  `TurnInputContext` / `TurnInputEnvironment` types it receives
  - teach `ExtensionRegistry` to register and expose turn-input
  contributors alongside the existing extension hooks
  - call registered turn-input contributors from
  `core/src/session/turn.rs` while building the initial injected input for
  a turn, then append their returned `ResponseItem`s after the skill and
  plugin injections

  jif · 2026-06-03 01:33:31 +02:00
  271d5cecf2
• feat: async approval contrib (#23690)
  jif-oai · 2026-05-20 15:13:54 +02:00
  f64fce61b3
• Add tool lifecycle extension contributor (#23309)

  ## Why
  
  Extensions that need to track runtime progress currently have no typed
  host signal for tool execution. The goal extension in particular needs
  to observe tool attempts without inspecting tool payloads, owning tool
  implementations, or staying coupled to core-only runtime plumbing.
  
  This adds a narrow lifecycle contributor API for host-owned tool
  execution: extensions can observe when an accepted tool call starts and
  how it finishes, while policy hooks and tool handlers continue to own
  payload rewriting, blocking, and execution.
  
  Relevant code:
  
  -
  [`ToolLifecycleContributor`](https://github.com/openai/codex/blob/3ad2850ffc7d8a1da19c65a92425637a59098f1b/codex-rs/ext/extension-api/src/contributors.rs#L119)
  defines the extension-facing observer contract.
  -
  [`tool_lifecycle.rs`](https://github.com/openai/codex/blob/3ad2850ffc7d8a1da19c65a92425637a59098f1b/codex-rs/ext/extension-api/src/contributors/tool_lifecycle.rs)
  defines the typed start/finish inputs, source, and outcome enums.
  - [`notify_tool_start` /
  `notify_tool_finish`](https://github.com/openai/codex/blob/3ad2850ffc7d8a1da19c65a92425637a59098f1b/codex-rs/core/src/tools/lifecycle.rs)
  bridges core tool dispatch into the extension registry.
  
  ## What Changed
  
  - Added `ToolLifecycleContributor` to `codex-extension-api`, including:
    - `ToolStartInput`
    - `ToolFinishInput`
    - `ToolCallSource`
    - `ToolCallOutcome`
  - Added registration and lookup support on `ExtensionRegistryBuilder` /
  `ExtensionRegistry`.
  - Wired core tool dispatch to notify lifecycle contributors for:
    - accepted tool starts
    - completed tool calls, including the tool output success marker
    - pre-tool-use blocks
    - failures before or after the handler runs
    - cancellation/abort in the parallel tool path
  - Registered the goal extension as a lifecycle contributor and added the
  outcome filter it will use for goal progress accounting.
  
  ## Test Coverage
  
  - Added `dispatch_notifies_tool_lifecycle_contributors` to cover
  lifecycle notification ordering and outcomes for successful and
  handler-failed tool calls.

  jif-oai · 2026-05-18 21:55:57 +02:00
  c69cde3547
• feat: add extension event sink capability (#23293)

  ## Why
  
  Extensions can already expose typed contributions and receive host
  capabilities such as `AgentSpawner`, but they do not have a typed way to
  send protocol events back through the host. Extensions that need to
  surface progress or status should not have to own persistence, ordering,
  transport fanout, or logging decisions themselves.
  
  ## What
  
  - Add `ExtensionEventSink`, a host-provided fire-and-forget sink for
  `codex_protocol::protocol::Event`.
  - Add `NoopExtensionEventSink` so hosts that do not expose extension
  event emission keep the existing empty-registry behavior.
  - Store the sink on `ExtensionRegistryBuilder` / `ExtensionRegistry`,
  with `with_event_sink(...)` and `event_sink()` accessors, and re-export
  the new capability from `codex-extension-api`.
  
  ## Testing
  
  - Not run locally; PR metadata/body update only.

  jif-oai · 2026-05-18 14:08:56 +02:00
  6a8173588c
• Make extension lifecycle hooks async (#23291)

  ## Why
  
  Extension lifecycle hooks sit on the host/extension boundary, but the
  current trait surface only allows synchronous callbacks. That forces
  extensions that need to seed, rehydrate, observe, or flush
  extension-owned state during thread and turn transitions to either block
  inside the callback or move async work into separate host plumbing.
  
  This PR makes those lifecycle callbacks awaitable so extension
  implementations can perform async work directly at the lifecycle point
  where the host already has the relevant session, thread, or turn stores
  available.
  
  ## What changed
  
  - Makes `ThreadLifecycleContributor` and `TurnLifecycleContributor`
  async in `codex-extension-api`.
  - Awaits thread start/resume/stop and turn start/stop/abort lifecycle
  callbacks from `codex-core`.
  - Updates the guardian and memories extensions to implement the async
  lifecycle trait surface.
  - Updates the existing lifecycle tests to use async contributor
  implementations.
  - Adds `async-trait` to the crates that now expose or implement these
  async object-safe lifecycle traits.
  
  ## Testing
  
  - Existing `codex-core` lifecycle tests were updated to cover async
  implementations for thread stop and turn abort ordering.

  jif-oai · 2026-05-18 13:53:58 +02:00
  9531e932ef
• feat: add config-change extension contributor (#22488)

  ## Why
  
  Extensions can observe thread and turn lifecycle events today, but there
  was no single host-owned hook for changes to the effective thread
  configuration. That makes features that need to react to model,
  permission, or tool-suggest updates either depend on individual mutation
  paths or risk going stale after runtime config refreshes.
  
  This adds a typed config-change contributor so extension-owned state can
  stay synchronized with the effective thread config while the host
  remains responsible for deciding when config changed.
  
  ## What Changed
  
  - Added `ConfigContributor<C>` to `codex_extension_api`, with
  before/after immutable snapshots of the effective config plus
  session/thread extension stores.
  - Added registry builder/accessor support through `config_contributor`
  and `config_contributors`.
  - Emits config-change callbacks after committed updates from session
  settings, per-turn setting updates, and `refresh_runtime_config`.
  - Builds effective config snapshots only when config contributors are
  registered, and suppresses no-op callbacks when the before/after
  snapshots are equal.
  - Added a core session regression test that verifies contributors
  observe both model changes and user-layer runtime config changes,
  including access to session and thread extension stores.
  
  ## Validation
  
  Added `config_change_contributor_observes_effective_config_changes` in
  `codex-rs/core/src/session/tests.rs` to cover the new contributor path.

  jif-oai · 2026-05-13 17:13:34 +02:00
  34bb85519f
• feat: add token usage contributor hook (#22485)

  ## Why
  
  Extensions need a stable place to observe token accounting after Codex
  folds model-provider usage into the session's cached `TokenUsageInfo`.
  Without a contributor hook, extension-owned features that need last-turn
  or cumulative token usage have to duplicate session plumbing or infer
  state from client-facing `TokenCount` notifications.
  
  ## What changed
  
  - Added `TokenUsageContributor` to `codex-extension-api`, passing
  session/thread `ExtensionData`, `ThreadId`, turn id, and the current
  `TokenUsageInfo`.
  - Added registry builder/storage support for token-usage contributors.
  - Invoked registered contributors from
  `Session::record_token_usage_info` after the session token cache is
  updated and before the client `TokenCount` notification is emitted.
  
  ## Testing
  
  - Added `record_token_usage_info_notifies_extension_contributors`,
  covering cumulative token usage updates and access to both extension
  stores.

  jif-oai · 2026-05-13 14:32:23 +02:00
  083c1962f9
• feat: add turn lifecycle contributors (#22480)

  ## Why
  
  Extensions can already contribute prompt, tool, turn-item, and
  thread-lifecycle behavior, but there was no explicit host-owned hook for
  per-turn setup and cleanup. That makes extension-private turn state
  awkward: an extension either has to stash it outside the turn lifecycle
  or depend on core runtime objects.
  
  This adds a small turn lifecycle boundary. Extensions receive stable
  identifiers plus the existing session, thread, and turn `ExtensionData`
  stores, while core keeps owning task scheduling, cancellation, and turn
  teardown.
  
  ## What Changed
  
  - Added `TurnLifecycleContributor` with `on_turn_start`, `on_turn_stop`,
  and `on_turn_abort` callbacks in `codex-rs/ext/extension-api`.
  - Added typed `TurnStartInput`, `TurnStopInput`, and `TurnAbortInput`
  payloads that expose `thread_id`, `turn_id`, `session_store`,
  `thread_store`, and `turn_store`.
  - Registered and re-exported turn lifecycle contributors through
  `ExtensionRegistry` and `ExtensionRegistryBuilder`.
  - Wired `Session` to emit turn start, stop, and abort callbacks from the
  existing turn/task lifecycle paths.
  - Carried the turn-scoped `ExtensionData` through `RunningTask` and
  `RemovedTask` so stop/abort callbacks receive the same turn store
  created at turn start.
  
  ## Verification
  
  - Not run locally.

  jif-oai · 2026-05-13 13:47:27 +02:00
  27e67a8c2a
• feat: add thread lifecycle contributor hooks (#22476)

  ## Why
  
  Extensions that need thread-scoped state currently only get a start-time
  callback. That is enough for seeding stores, but it leaves the host
  without a shared extension seam for later thread rehydrate and flush
  work as thread ownership evolves. This PR turns that start-only seam
  into a host-owned thread lifecycle contributor contract so
  extension-private state can stay behind the extension API instead of
  leaking extra orchestration through core.
  
  ## What changed
  
  - Replaced `ThreadStartContributor` with `ThreadLifecycleContributor`
  and added typed lifecycle inputs for thread start, resume, and stop. The
  contract lives in
  [`contributors/thread_lifecycle.rs`](https://github.com/openai/codex/blob/d0e9211f70e58d6b07ef07e84f359d1b9aa25955/codex-rs/ext/extension-api/src/contributors/thread_lifecycle.rs#L1-L64).
  - Kept the existing start-time behavior intact by routing session
  construction through `on_thread_start`.
  - Invoked `on_thread_stop` during session shutdown before thread-scoped
  extension state is dropped, while isolating contributor failures behind
  warning logs.
  - Migrated `git-attribution` and `guardian` onto the lifecycle
  registration path.
  - Renamed the extension registry plumbing from start-specific
  contributors to lifecycle-specific contributors.
  
  ## Notes
  
  `on_thread_resume` is introduced at the API boundary here so extensions
  can target the final lifecycle shape; host resume dispatch can be wired
  where that runtime path is finalized.

  jif-oai · 2026-05-13 13:11:30 +02:00
  5ab7e6b4c6
• extension-api: add approval review contributor flow (#22344)

  ## Why
  
  `codex-extension-api` needs an approval hook that lets an installed
  extension own a rendered approval-review prompt and produce the final
  `ReviewDecision`. The prior interceptor stub only exposed a yes/no claim
  and did not model the review result itself, which left the host with the
  missing half of the control flow.
  
  ## What changed
  
  - Replaces `ApprovalInterceptorContributor` with
  [`ApprovalReviewContributor`](https://github.com/openai/codex/blob/c49d17531e15057a373a9b17f410cafb6299d0c1/codex-rs/ext/extension-api/src/contributors.rs#L43-L55),
  which may claim a rendered prompt and return an async `ReviewDecision`.
  - Re-exports the new contributor and future types from `extension-api`.
  - Adds registry support through `approval_review_contributor(...)` plus
  [`ExtensionRegistry::approval_review(...)`](https://github.com/openai/codex/blob/c49d17531e15057a373a9b17f410cafb6299d0c1/codex-rs/ext/extension-api/src/registry.rs#L90-L101),
  which returns the first installed contributor that claims the prompt.

  jif-oai · 2026-05-13 10:39:12 +02:00
  155c04ad40
• feat: drop CodexExtension (#22140)

  Drop `CodexExtension` as not needed for now

  jif-oai · 2026-05-11 14:19:51 +02:00
  ebd3d53451
• extension: add initial typed extension API (#21736)

  ## Why
  
  `codex-core` still owns a growing amount of product-specific behavior.
  This PR starts the extraction path by introducing a small, typed
  first-party extension seam: features can install the contribution
  families they actually own, while the host keeps lifecycle and state
  ownership instead of pushing a broad service locator into the API.
  
  See the `examples/` for illustration
  
  ## Known limitations
  * Tool contract definition will be shared with core
  * Fragments must be extracted
  * Missing some contributors

  jif-oai · 2026-05-11 11:06:24 +02:00
  d2c3ebac1f