33 Commits

• chore: clean up argument-comment lint and roll out all-target CI on macOS (#16054)

  ## Why
  
  `argument-comment-lint` was green in CI even though the repo still had
  many uncommented literal arguments. The main gap was target coverage:
  the repo wrapper did not force Cargo to inspect test-only call sites, so
  examples like the `latest_session_lookup_params(true, ...)` tests in
  `codex-rs/tui_app_server/src/lib.rs` never entered the blocking CI path.
  
  This change cleans up the existing backlog, makes the default repo lint
  path cover all Cargo targets, and starts rolling that stricter CI
  enforcement out on the platform where it is currently validated.
  
  ## What changed
  
  - mechanically fixed existing `argument-comment-lint` violations across
  the `codex-rs` workspace, including tests, examples, and benches
  - updated `tools/argument-comment-lint/run-prebuilt-linter.sh` and
  `tools/argument-comment-lint/run.sh` so non-`--fix` runs default to
  `--all-targets` unless the caller explicitly narrows the target set
  - fixed both wrappers so forwarded cargo arguments after `--` are
  preserved with a single separator
  - documented the new default behavior in
  `tools/argument-comment-lint/README.md`
  - updated `rust-ci` so the macOS lint lane keeps the plain wrapper
  invocation and therefore enforces `--all-targets`, while Linux and
  Windows temporarily pass `-- --lib --bins`
  
  That temporary CI split keeps the stricter all-targets check where it is
  already cleaned up, while leaving room to finish the remaining Linux-
  and Windows-specific target-gated cleanup before enabling
  `--all-targets` on those runners. The Linux and Windows failures on the
  intermediate revision were caused by the wrapper forwarding bug, not by
  additional lint findings in those lanes.
  
  ## Validation
  
  - `bash -n tools/argument-comment-lint/run.sh`
  - `bash -n tools/argument-comment-lint/run-prebuilt-linter.sh`
  - shell-level wrapper forwarding check for `-- --lib --bins`
  - shell-level wrapper forwarding check for `-- --tests`
  - `just argument-comment-lint`
  - `cargo test` in `tools/argument-comment-lint`
  - `cargo test -p codex-terminal-detection`
  
  ## Follow-up
  
  - Clean up remaining Linux-only target-gated callsites, then switch the
  Linux lint lane back to the plain wrapper invocation.
  - Clean up remaining Windows-only target-gated callsites, then switch
  the Windows lint lane back to the plain wrapper invocation.

  Michael Bolin · 2026-03-27 19:00:44 -07:00
  61dfe0b86c
• chore: remove skill metadata from command approval payloads (#15906)

  ## Why
  
  This is effectively a follow-up to
  [#15812](https://github.com/openai/codex/pull/15812). That change
  removed the special skill-script exec path, but `skill_metadata` was
  still being threaded through command-approval payloads even though the
  approval flow no longer uses it to render prompts or resolve decisions.
  
  Keeping it around added extra protocol, schema, and client surface area
  without changing behavior.
  
  Removing it keeps the command-approval contract smaller and avoids
  carrying a dead field through app-server, TUI, and MCP boundaries.
  
  ## What changed
  
  - removed `ExecApprovalRequestSkillMetadata` and the corresponding
  `skillMetadata` field from core approval events and the v2 app-server
  protocol
  - removed the generated JSON and TypeScript schema output for that field
  - updated app-server, MCP server, TUI, and TUI app-server approval
  plumbing to stop forwarding the field
  - cleaned up tests that previously constructed or asserted
  `skillMetadata`
  
  ## Testing
  
  - `cargo test -p codex-app-server-protocol`
  - `cargo test -p codex-protocol`
  - `cargo test -p codex-app-server-test-client`
  - `cargo test -p codex-mcp-server`
  - `just argument-comment-lint`

  Michael Bolin · 2026-03-26 15:32:03 -07:00
  5906c6a658
• generate an internal json schema for RolloutLine (#14434)

  ### Why
  i'm working on something that parses and analyzes codex rollout logs,
  and i'd like to have a schema for generating a parser/validator.
  
  `codex app-server generate-internal-json-schema` writes an
  `RolloutLine.json` file
  
  while doing this, i noticed we have a writer <> reader mismatch issue on
  `FunctionCallOutputPayload` and reasoning item ID -- added some schemars
  annotations to fix those
  
  ### Test
  
  ```
  $ just codex app-server generate-internal-json-schema --out ./foo
  ```
  
  generates an `RolloutLine.json` file, which i validated against jsonl
  files on disk
  
  `just codex app-server --help` doesn't expose the
  `generate-internal-json-schema` option by default, but you can do `just
  codex app-server generate-internal-json-schema --help` if you know the
  command
  
  everything else still works
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  Keyan Zhang · 2026-03-17 11:19:42 -07:00
  904dbd414f
• Apply argument comment lint across codex-rs (#14652)

  ## Why
  
  Once the repo-local lint exists, `codex-rs` needs to follow the
  checked-in convention and CI needs to keep it from drifting. This commit
  applies the fallback `/*param*/` style consistently across existing
  positional literal call sites without changing those APIs.
  
  The longer-term preference is still to avoid APIs that require comments
  by choosing clearer parameter types and call shapes. This PR is
  intentionally the mechanical follow-through for the places where the
  existing signatures stay in place.
  
  After rebasing onto newer `main`, the rollout also had to cover newly
  introduced `tui_app_server` call sites. That made it clear the first cut
  of the CI job was too expensive for the common path: it was spending
  almost as much time installing `cargo-dylint` and re-testing the lint
  crate as a representative test job spends running product tests. The CI
  update keeps the full workspace enforcement but trims that extra
  overhead from ordinary `codex-rs` PRs.
  
  ## What changed
  
  - keep a dedicated `argument_comment_lint` job in `rust-ci`
  - mechanically annotate remaining opaque positional literals across
  `codex-rs` with exact `/*param*/` comments, including the rebased
  `tui_app_server` call sites that now fall under the lint
  - keep the checked-in style aligned with the lint policy by using
  `/*param*/` and leaving string and char literals uncommented
  - cache `cargo-dylint`, `dylint-link`, and the relevant Cargo
  registry/git metadata in the lint job
  - split changed-path detection so the lint crate's own `cargo test` step
  runs only when `tools/argument-comment-lint/*` or `rust-ci.yml` changes
  - continue to run the repo wrapper over the `codex-rs` workspace, so
  product-code enforcement is unchanged
  
  Most of the code changes in this commit are intentionally mechanical
  comment rewrites or insertions driven by the lint itself.
  
  ## Verification
  
  - `./tools/argument-comment-lint/run.sh --workspace`
  - `cargo test -p codex-tui-app-server -p codex-tui`
  - parsed `.github/workflows/rust-ci.yml` locally with PyYAML
  
  ---
  
  * -> #14652
  * #14651

  Michael Bolin · 2026-03-16 16:48:15 -07:00
  b77fe8fefe
• chore(app-server): stop exporting EventMsg schemas (#14478)

  Follow up to https://github.com/openai/codex/pull/14392, stop exporting
  EventMsg types to TypeScript and JSON schema since we no longer emit
  them.

  Owen Lin · 2026-03-12 12:16:05 -07:00
  4724a2e9e7
• Stabilize protocol schema fixture generation (#13886)

  ## What changed
  - TypeScript schema fixture generation now goes through in-memory tree
  helpers rather than a heavier on-disk generation path.
  - The comparison logic normalizes generated banner and path differences
  that are not semantically relevant to the exported schema.
  - TypeScript and JSON fixture coverage are split into separate tests,
  and the expensive schema-export tests are serialized in `nextest`.
  
  ## Why this fixes the flake
  - The original fixture coverage mixed several heavy codegen paths into
  one monolithic test and then compared generated output that included
  incidental banner/path differences.
  - On Windows CI, that combination created both runtime pressure and
  output variance unrelated to the schema shapes we actually care about.
  - Splitting the coverage isolates failures by format, in-memory
  generation reduces filesystem churn, normalization strips generator
  noise, and serializing the heavy tests removes parallel resource
  contention.
  
  ## Scope
  - Production helper change plus test changes.

  Ahmed Ibrahim · 2026-03-09 13:51:50 -07:00
  831ee51c86
• app-server: include experimental skill metadata in exec approval requests (#13929)

  ## Summary
  
  This change surfaces skill metadata on command approval requests so
  app-server clients can tell when an approval came from a skill script
  and identify the originating `SKILL.md`.
  
  - add `skill_metadata` to exec approval events in the shared protocol
  - thread skill metadata through core shell escalation and delegated
  approval handling for skill-triggered approvals
  - expose the field in app-server v2 as experimental `skillMetadata`
  - regenerate the JSON/TypeScript schemas and cover the new field in
  protocol, transport, core, and TUI tests
  
  ## Why
  
  Skill-triggered approvals already carry skill context inside core, but
  app-server clients could not see which skill caused the prompt. Sending
  the skill metadata with the approval request makes it possible for
  clients to present better approval UX and connect the prompt back to the
  relevant skill definition.
  
  
  ## example event in app-server-v2
  verified that we see this event when experimental api is on:
  ```
  < {
  <   "id": 11,
  <   "method": "item/commandExecution/requestApproval",
  <   "params": {
  <     "additionalPermissions": {
  <       "fileSystem": null,
  <       "macos": {
  <         "accessibility": false,
  <         "automations": {
  <           "bundle_ids": [
  <             "com.apple.Notes"
  <           ]
  <         },
  <         "calendar": false,
  <         "preferences": "read_only"
  <       },
  <       "network": null
  <     },
  <     "approvalId": "25d600ee-5a3c-4746-8d17-e2e61fb4c563",
  <     "availableDecisions": [
  <       "accept",
  <       "acceptForSession",
  <       "cancel"
  <     ],
  <     "command": "/Applications/ChatGPT.app/Contents/Resources/CodexAppServer_CodexAppServerBundledSkills.bundle/Contents/Resources/skills/apple-notes/scripts/notes_info",
  <     "commandActions": [
  <       {
  <         "command": "/Applications/ChatGPT.app/Contents/Resources/CodexAppServer_CodexAppServerBundledSkills.bundle/Contents/Resources/skills/apple-notes/scripts/notes_info",
  <         "type": "unknown"
  <       }
  <     ],
  <     "cwd": "/Applications/ChatGPT.app/Contents/Resources/CodexAppServer_CodexAppServerBundledSkills.bundle/Contents/Resources/skills/apple-notes",
  <     "itemId": "call_jZp3xFpNg4D8iKAD49cvEvZy",
  <     "skillMetadata": {
  <       "pathToSkillsMd": "/Applications/ChatGPT.app/Contents/Resources/CodexAppServer_CodexAppServerBundledSkills.bundle/Contents/Resources/skills/apple-notes/SKILL.md"
  <     },
  <     "threadId": "019ccc10-b7d3-7ff2-84fe-3a75e7681e69",
  <     "turnId": "019ccc10-b848-76f1-81b3-4a1fa225493f"
  <   }
  < }`
  ```
  
  & verified that this is the event when experimental api is off:
  ```
  < {
  <   "id": 13,
  <   "method": "item/commandExecution/requestApproval",
  <   "params": {
  <     "approvalId": "5fbbf776-261b-4cf8-899b-c125b547f2c0",
  <     "availableDecisions": [
  <       "accept",
  <       "acceptForSession",
  <       "cancel"
  <     ],
  <     "command": "/Applications/ChatGPT.app/Contents/Resources/CodexAppServer_CodexAppServerBundledSkills.bundle/Contents/Resources/skills/apple-notes/scripts/notes_info",
  <     "commandActions": [
  <       {
  <         "command": "/Applications/ChatGPT.app/Contents/Resources/CodexAppServer_CodexAppServerBundledSkills.bundle/Contents/Resources/skills/apple-notes/scripts/notes_info",
  <         "type": "unknown"
  <       }
  <     ],
  <     "cwd": "/Users/celia/code/codex/codex-rs",
  <     "itemId": "call_OV2DHzTgYcbYtWaTTBWlocOt",
  <     "threadId": "019ccc16-2a2b-7be1-8500-e00d45b892d4",
  <     "turnId": "019ccc16-2a8e-7961-98ec-649600e7d06a"
  <   }
  < }
  ```

  Celia Chen · 2026-03-08 18:07:46 -07:00
  340f9c9ecb
• feat(app-server-protocol): address naming conflicts in json schema exporter (#13819)

  This fixes a schema export bug where two different `WebSearchAction`
  types were getting merged under the same name in the app-server v2 JSON
  schema bundle.
  
  The problem was that v2 thread items use the app-server API's
  `WebSearchAction` with camelCase variants like `openPage`, while
  `ThreadResumeParams.history` and
  `RawResponseItemCompletedNotification.item` pull in the upstream
  `ResponseItem` graph, which uses the Responses API snake_case shape like
  `open_page`. During bundle generation we were flattening nested
  definitions into the v2 namespace by plain name, so the later definition
  could silently overwrite the earlier one.
  
  That meant clients generating code from the bundled schema could end up
  with the wrong `WebSearchAction` definition for v2 thread history. In
  practice this shows up on web search items reconstructed from rollout
  files with persisted extended history.
  
  This change does two things:
  - Gives the upstream Responses API schema a distinct JSON schema name:
  `ResponsesApiWebSearchAction`
  - Makes namespace-level schema definition collisions fail loudly instead
  of silently overwriting

  Owen Lin · 2026-03-07 01:33:46 +00:00
  90469d0a23
• chore(app-server): restore EventMsg TS types (#13397)

  Realized EventMsg generated types were unintentionally removed as part
  of this PR: https://github.com/openai/codex/pull/13375
  
  Turns out our TypeScript export pipeline relied on transitively reaching
  `EventMsg`. We should still export `EventMsg` explicitly since we're
  still emitting `codex/event/*` events (for now, but getting dropped soon
  as well).

  Owen Lin · 2026-03-03 13:37:40 -08:00
  d7eb195b62
• chore(app-server): delete v1 RPC methods and notifications (#13375)

  ## Summary
  This removes the old app-server v1 methods and notifications we no
  longer need, while keeping the small set the main codex app client still
  depends on for now.
  
  The remaining legacy surface is:
  - `initialize`
  - `getConversationSummary`
  - `getAuthStatus`
  - `gitDiffToRemote`
  - `fuzzyFileSearch`
  - `fuzzyFileSearch/sessionStart`
  - `fuzzyFileSearch/sessionUpdate`
  - `fuzzyFileSearch/sessionStop`
  
  And the raw `codex/event/*` notifications emitted from core. These
  notifications will be removed in a followup PR.
  
  ## What changed
  - removed deprecated v1 request variants from the protocol and
  app-server dispatcher
  - removed deprecated typed notifications: `authStatusChange`,
  `loginChatGptComplete`, and `sessionConfigured`
  - updated the app-server test client to use v2 flows instead of deleted
  v1 flows
  - deleted legacy-only app-server test suites and added focused coverage
  for `getConversationSummary`
  - regenerated app-server schema fixtures and updated the MCP interface
  docs to match the remaining compatibility surface
  
  ## Testing
  - `just write-app-server-schema`
  - `cargo test -p codex-app-server-protocol`
  - `cargo test -p codex-app-server`

  Owen Lin · 2026-03-03 13:18:25 -08:00
  167158f93c
• app-server-protocol: export flat v2 schema bundle (#13324)

  ## Summary
  - add an `--experimental` flag to the export binary and thread the
  option through TypeScript and JSON schema generation
  - flatten the v2 schema bundle into a datamodel-code-generator-friendly
  `codex_app_server_protocol.v2.schemas.json` export
  - retarget shared helper refs to namespaced v2 definitions, add coverage
  for the new export behavior, and vendor the generated schema fixtures
  
  ## Validation
  - `cargo test -p codex-app-server-protocol` (71 unit tests and bin
  targets passed locally; the final schema fixture integration target was
  revalidated via fresh schema regeneration and a tree diff)
  - `./target/debug/write_schema_fixtures --schema-root <tmpdir>`
  - `diff -rq app-server-protocol/schema <tmpdir>`
  
  ## Tickets
  - None

  Anton Panasenko · 2026-03-03 10:25:51 -08:00
  8da7e4bdae
• feat: add experimental additionalPermissions to v2 command execution approval requests (#12737)

  This adds additionalPermissions to the app-server v2
  item/commandExecution/requestApproval payload as an experimental field.
  
  The field is now exposed on CommandExecutionRequestApprovalParams and is
  populated from the existing core approval event when a command requests
  additional sandbox permissions.
  
  This PR also contains changes to make server requests to support
  experiment API.
  
  A real app server test client test:
  
  sample payload with experimental flag off:
  ```
   {
  <   "id": 0,
  <   "method": "item/commandExecution/requestApproval",
  <   "params": {
  <     "command": "/bin/zsh -lc 'mkdir -p ~/some/test && touch ~/some/test/file'",
  <     "commandActions": [
  <       {
  <         "command": "mkdir -p '~/some/test'",
  <         "type": "unknown"
  <       },
  <       {
  <         "command": "touch '~/some/test/file'",
  <         "type": "unknown"
  <       }
  <     ],
  <     "cwd": "/Users/celia/code/codex/codex-rs",
  <     "itemId": "call_QLp0LWkQ1XkU6VW9T2vUZFWB",
  <     "proposedExecpolicyAmendment": [
  <       "mkdir",
  <       "-p",
  <       "~/some/test"
  <     ],
  <     "reason": "Do you want to allow creating ~/some/test/file outside the workspace?",
  <     "threadId": "019c9309-e209-7d82-a01b-dcf9556a354d",
  <     "turnId": "019c9309-e27a-7f33-834f-6011e795c2d6"
  <   }
  < }
  ```
  with experimental flag on: 
  ```
  < {
  <   "id": 0,
  <   "method": "item/commandExecution/requestApproval",
  <   "params": {
  <     "additionalPermissions": {
  <       "fileSystem": null,
  <       "macos": null,
  <       "network": true
  <     },
  <     "command": "/bin/zsh -lc 'install -D /dev/null ~/some/test/file'",
  <     "commandActions": [
  <       {
  <         "command": "install -D /dev/null '~/some/test/file'",
  <         "type": "unknown"
  <       }
  <     ],
  <     "cwd": "/Users/celia/code/codex/codex-rs",
  <     "itemId": "call_K3U4b3dRbj3eMCqslmncbGsq",
  <     "proposedExecpolicyAmendment": [
  <       "install",
  <       "-D"
  <     ],
  <     "reason": "Do you want to allow creating the file at ~/some/test/file outside the workspace sandbox?",
  <     "threadId": "019c9303-3a8e-76e1-81bf-d67ac446d892",
  <     "turnId": "019c9303-3af1-7143-88a1-73132f771234"
  <   }
  < }
  ```

  Celia Chen · 2026-02-25 05:16:35 +00:00
  1151972fb2
• ignore v1 in JSON schema codegen (#12408)

  ## Why
  
  The generated unnamespaced JSON envelope schemas (`ClientRequest` and
  `ServerNotification`) still contained both v1 and v2 variants, which
  pulled legacy v1/core types and v2 types into the same `definitions`
  graph. That caused `schemars` to produce numeric suffix names (for
  example `AskForApproval2`, `ByteRange2`, `MessagePhase2`).
  
  This PR moves JSON codegen toward v2-only output while preserving the
  unnamespaced envelope artifacts, and avoids reintroducing numeric-suffix
  tolerance by removing the v1/internal-only variants that caused the
  collisions in those envelope schemas.
  
  ## What Changed
  
  - In `codex-rs/app-server-protocol/src/export.rs`, JSON generation now
  excludes v1 schema artifacts (`v1/*`) while continuing to emit
  unnamespaced/root JSON schemas and the JSON bundle.
  - Added a narrow JSON v1 allowlist (`JSON_V1_ALLOWLIST`) so
  `InitializeParams` and `InitializeResponse` are still emitted.
  - Added JSON-only post-processing for the mixed envelope schemas before
  collision checks run:
  - `ClientRequest`: strips v1 request variants from the generated `oneOf`
  using the temporary `V1_CLIENT_REQUEST_METHODS` list
  - `ServerNotification`: strips v1 notifications plus the internal-only
  `rawResponseItem/completed` notification using the temporary
  `EXCLUDED_SERVER_NOTIFICATION_METHODS_FOR_JSON` list
  - Added a temporary local-definition pruning pass for those envelope
  schemas so now-unreferenced v1/core definitions are removed from
  `definitions` after method filtering.
  - Updated the variant-title naming heuristic for single-property literal
  object variants to use the literal value (when available), avoiding
  collisions like multiple `state`-only variants all deriving the same
  title.
  - Collision handling remains fail-fast (no numeric suffix fallback map
  in this PR path).
  
  ## Verification
  
  - `just write-app-server-schema`
  
  ---
  [//]: # (BEGIN SAPLING FOOTER)
  Stack created with [Sapling](https://sapling-scm.com). Best reviewed
  with [ReviewStack](https://reviewstack.dev/openai/codex/pull/12408).
  * __->__ #12408
  * #12406

  Michael Bolin · 2026-02-20 21:36:12 -08:00
  1779feb6a7
• fix: explicitly list name collisions in JSON schema generation (#12406)

  ## Why
  
  JSON schema codegen was silently resolving naming collisions by
  appending numeric suffixes (for example `...2`, `...3`). That makes the
  generated schema names unstable: removing an earlier colliding type can
  cause a later type to be renumbered, which is a breaking change for
  consumers that referenced the old generated name.
  
  This PR makes those collisions explicit and reviewable.
  
  Though note that once we remove `v1` from the codegen, we will no longer
  support naming collisions. Or rather, naming collisions will have to be
  handled explicitly rather than the numeric suffix approach.
  
  ## What Changed
  
  - In `codex-rs/app-server-protocol/src/export.rs`, replaced implicit
  numeric suffix collision handling for generated variant titles with
  explicit special-case maps.
  - Added a panic when a collision occurs without an entry in the map, so
  new collisions fail loudly instead of silently renaming generated schema
  types.
  - Added the currently required special cases so existing generated names
  remain stable.
  - Extended the same approach to numbered `definitions` / `$defs`
  collisions (for example `MessagePhase2`-style names) so those are also
  explicitly tracked.
  
  ## Verification
  
  - Ran targeted generator-path test:
  - `cargo test -p codex-app-server-protocol
  generate_json_filters_experimental_fields_and_methods -- --nocapture`
  
  
  ---
  [//]: # (BEGIN SAPLING FOOTER)
  Stack created with [Sapling](https://sapling-scm.com). Best reviewed
  with [ReviewStack](https://reviewstack.dev/openai/codex/pull/12406).
  * #12408
  * __->__ #12406

  Michael Bolin · 2026-02-20 17:51:53 -08:00
  53bcfaf42d
• feat: cleaner TUI for sub-agents (#12327)

  <img width="760" height="496" alt="Screenshot 2026-02-20 at 14 31 25"
  src="https://github.com/user-attachments/assets/1983b825-bb47-417e-9925-6f727af56765"
  />

  jif-oai · 2026-02-20 15:26:33 +00:00
  4d60c803ba
• feat: opt-out of events in the app-server (#11319)

  Add `optOutNotificationMethods` in the app-server to opt-out events
  based on exact method matching

  jif-oai · 2026-02-10 18:04:52 +00:00
  a364dd8b56
• Mark Config.apps as experimental, correct schema generation issue (#10938)

  This PR makes `Config.apps `experimental-only and fixes a TS schema
  post-processing bug that removed needed imports. The bug happened
  because import pruning only checked the inner type body after filtering,
  not the full alias, so `JsonValue` got dropped from `Config.ts`. We now
  prune against the full alias body and added a regression test for this
  scenario.

  canvrno-oai · 2026-02-06 16:30:41 -08:00
  1446bd2b23
• fix(app-server): fix TS annotations for optional fields on requests (#10412)

  This updates our generated TypeScript types to be more correct with how
  the server actually behaves, **specifically for JSON-RPC requests**.
  
  Before this PR, we'd generate `field: T | null`. After this PR, we will
  have `field?: T | null`. The latter matches how the server actually
  works, in that if an optional field is omitted, the server will treat it
  as null. This also makes it less annoying in theory for clients to
  upgrade to newer versions of Codex, since adding a new optional field to
  a JSON-RPC request should not require a client change.
  
  NOTE: This only applies to JSON-RPC requests. All other payloads (i.e.
  responses, notifications) will return `field: T | null` as usual.

  Owen Lin · 2026-02-03 11:51:37 -08:00
  efd96c46c7
• feat: experimental flags (#10231)

  ## Problem being solved
  - We need a single, reliable way to mark app-server API surface as
  experimental so that:
    1. the runtime can reject experimental usage unless the client opts in
  2. generated TS/JSON schemas can exclude experimental methods/fields for
  stable clients.
  
  Right now that’s easy to drift or miss when done ad-hoc.
  
  ## How to declare experimental methods and fields
  - **Experimental method**: add `#[experimental("method/name")]` to the
  `ClientRequest` variant in `client_request_definitions!`.
  - **Experimental field**: on the params struct, derive `ExperimentalApi`
  and annotate the field with `#[experimental("method/name.field")]` + set
  `inspect_params: true` for the method variant so
  `ClientRequest::experimental_reason()` inspects params for experimental
  fields.
  
  ## How the macro solves it
  - The new derive macro lives in
  `codex-rs/codex-experimental-api-macros/src/lib.rs` and is used via
  `#[derive(ExperimentalApi)]` plus `#[experimental("reason")]`
  attributes.
  - **Structs**:
  - Generates `ExperimentalApi::experimental_reason(&self)` that checks
  only annotated fields.
    - The “presence” check is type-aware:
      - `Option<T>`: `is_some_and(...)` recursively checks inner.
      - `Vec`/`HashMap`/`BTreeMap`: must be non-empty.
      - `bool`: must be `true`.
      - Other types: considered present (returns `true`).
  - Registers each experimental field in an `inventory` with `(type_name,
  serialized field name, reason)` and exposes `EXPERIMENTAL_FIELDS` for
  that type. Field names are converted from `snake_case` to `camelCase`
  for schema/TS filtering.
  - **Enums**:
  - Generates an exhaustive `match` returning `Some(reason)` for annotated
  variants and `None` otherwise (no wildcard arm).
  - **Wiring**:
  - Runtime gating uses `ExperimentalApi::experimental_reason()` in
  `codex-rs/app-server/src/message_processor.rs` to reject requests unless
  `InitializeParams.capabilities.experimental_api == true`.
  - Schema/TS export filters use the inventory list and
  `EXPERIMENTAL_CLIENT_METHODS` from `client_request_definitions!` to
  strip experimental methods/fields when `experimental_api` is false.

  jif-oai · 2026-02-02 11:06:50 +00:00
  3cc9122ee2
• Fix: Skip Option<()> schema generation to avoid invalid Windows filenames (#7479) (#7969)

  ## Problem
  
  When generating JSON schemas on Windows, the `codex app-server
  generate-json-schema` command fails with a filename error:
  ```text
  Error: Failed to write JSON schema for Option<()>
  Caused by:
      0: Failed to write .\Option<()>.json
      1: The filename, directory name, or volume label syntax is incorrect. (os error 123)
  ```
  This occurs because Windows doesn't allow certain characters in
  filenames, specifically the angle brackets **<>** used in the
  **Option<()>** type name.
  
  ## Root Cause
  
  The schema generation process attempts to create individual JSON files
  for each schema definition, including `Option<()>`. However, the
  characters `<` and `>` are invalid in Windows filenames, causing the
  file creation to fail.
  
  ## Solution
  
  The fix extends the existing `IGNORED_DEFINITIONS` constant (which was
  already being used in the **bundle generation**) to also skip
  `Option<()>` when generating individual JSON schema files. This
  maintains consistency with the existing behavior where `Option<()>` is
  excluded from the bundled schema.
  
  ---
  
  close #7479

  Robby He · 2025-12-15 09:57:12 -08:00
  017a4a06b2
• Improved runtime of generated_ts_has_no_optional_nullable_fields test (#6851)

  The `generated_ts_has_no_optional_nullable_fields` test was occasionally
  failing on slow CI nodes because of a timeout. This change reduces the
  work done by the test. It adds some "options" for the `generate_ts`
  function so it can skip work that's not needed for the test.

  Eric Traut · 2025-11-18 15:24:32 -08:00
  ab30453dee
• Prompt to turn on windows sandbox when auto mode selected. (#6618)

  - stop prompting users to install WSL 
  - prompt users to turn on Windows sandbox when auto mode requested.
  
  <img width="1660" height="195" alt="Screenshot 2025-11-17 110612"
  src="https://github.com/user-attachments/assets/c67fc239-a227-417e-94bb-599a8ed8f11e"
  />
  <img width="1684" height="168" alt="Screenshot 2025-11-17 110637"
  src="https://github.com/user-attachments/assets/d18c3370-830d-4971-8746-04757ae2f709"
  />
  <img width="1655" height="293" alt="Screenshot 2025-11-17 110719"
  src="https://github.com/user-attachments/assets/d21f6ce9-c23e-4842-baf6-8938b77c16db"
  />

  iceweasel-oai · 2025-11-18 11:38:18 -08:00
  4bada5a84d
• [app-server] small fixes for JSON schema export and one-of types (#6614)

  A partner is consuming our generated JSON schema bundle for app-server
  and identified a few issues:
  - not all polymorphic / one-of types have a type descriminator
  - `"$ref": "#/definitions/v2/SandboxPolicy"` is missing
  - "Option<>" is an invalid schema name, and also unnecessary
  
  This PR:
  - adds the type descriminator to the various types that are missing it
  except for `SessionSource` and `SubAgentSource` because they are
  serialized to disk (adding this would break backwards compat for
  resume), and they should not be necessary to consume for an integration
  with app-server.
  - removes the special handling in `export.rs` of various types like
  SandboxPolicy, which turned out to be unnecessary and incorrect
  - filters out `Option<>` which was auto-generated for request params
  that don't need a body
  
  For context, we currently pull in wayyy more types than we need through
  the `EventMsg` god object which we are **not** planning to expose in API
  v2 (this is how I suspect `SessionSource` and `SubAgentSource` are being
  pulled in). But until we have all the necessary v2 notifications in
  place that will allow us to remove `EventMsg`, we will keep exporting it
  for now.

  Owen Lin · 2025-11-13 16:25:17 -08:00
  db2aa57d73
• Re-add prettier log-level=warn to generate-ts (#6528)

  I added it in https://github.com/openai/codex/pull/6342 but it was
  removed in
  https://github.com/openai/codex/pull/5063/files#diff-e2aa6dad1e886b7765158a27aefd1be5de99baa71b44f6bc5ce3fe462b9ae5d3R135
  as a result of a bad diamond merge

  Gabriel Peal · 2025-11-11 21:30:01 -05:00
  424bfecd0b
• [app-server] feat: add command to generate json schema (#6406)

  Add a `codex generate-json-schema` command for generating a JSON schema
  bundle of app-server types, analogous to the existing `codex
  generate-ts` command for Typescript.

  Owen Lin · 2025-11-10 16:59:14 +00:00
  fbdedd9a06
• [app-server] feat: export.rs supports a v2 namespace, initial v2 notifications (#6212)

  **Typescript and JSON schema exports**
  While working on Thread/Turn/Items type definitions, I realize we will
  run into name conflicts between v1 and v2 APIs (e.g. `RateLimitWindow`
  which won't be reusable since v1 uses `RateLimitWindow` from `protocol/`
  which uses snake_case, but we want to expose camelCase everywhere, so
  we'll define a V2 version of that struct that serializes as camelCase).
  
  To set us up for a clean and isolated v2 API, generate types into a
  `v2/` namespace for both typescript and JSON schema.
  - TypeScript: v2 types emit under `out_dir/v2/*.ts`, and root index.ts
  now re-exports them via `export * as v2 from "./v2"`;.
  - JSON Schemas: v2 definitions bundle under `#/definitions/v2/*` rather
  than the root.
  
  The location for the original types (v1 and types pulled from
  `protocol/` and other core crates) haven't changed and are still at the
  root. This is for backwards compatibility: no breaking changes to
  existing usages of v1 APIs and types.
  
  **Notifications**
  While working on export.rs, I:
  - refactored server/client notifications with macros (like we already do
  for methods) so they also get exported (I noticed they weren't being
  exported at all).
  - removed the hardcoded list of types to export as JSON schema by
  leveraging the existing macros instead
  - and took a stab at API V2 notifications. These aren't wired up yet,
  and I expect to iterate on these this week.

  Owen Lin · 2025-11-05 01:02:39 +00:00
  edf4c3f627
• [App-server] v2 for account/updated and account/logout (#6175)

  V2 for `account/updated` and `account/logout` for app server. correspond
  to old `authStatusChange` and `LogoutChatGpt` respectively. Followup PRs
  will make other v2 endpoints call `account/updated` instead of
  `authStatusChange` too.

  Celia Chen · 2025-11-03 22:01:33 -08:00
  d3187dbc17
• [app-server] remove serde(skip_serializing_if = "Option::is_none") annotations (#5939)

  We had this annotation everywhere in app-server APIs which made it so
  that fields get serialized as `field?: T`, meaning if the field as
  `None` we would omit the field in the payload. Removing this annotation
  changes it so that we return `field: T | null` instead, which makes
  codex app-server's API more aligned with the convention of public OpenAI
  APIs like Responses.
  
  Separately, remove the `#[ts(optional_fields = nullable)]` annotations
  that were recently added which made all the TS types become `field?: T |
  null` which is not great since clients need to handle undefined and
  null.
  
  I think generally it'll be best to have optional types be either:
  - `field: T | null` (preferred, aligned with public OpenAI APIs)
  - `field?: T` where we have to, such as types generated from the MCP
  schema:
  https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2025-06-18/schema.ts
  (see changes to `mcp-types/`)
  
  I updated @etraut-openai's unit test to check that all generated TS
  types are one or the other, not both (so will error if we have a type
  that has `field?: T | null`). I don't think there's currently a good use
  case for that - but we can always revisit.

  Owen Lin · 2025-10-30 18:18:53 +00:00
  89c00611c2
• Add missing "nullable" macro to protocol structs that contain optional fields (#5901)

  This PR addresses a current hole in the TypeScript code generation for
  the API server protocol. Fields that are marked as "Optional<>" in the
  Rust code are serialized such that the value is omitted when it is
  deserialized — appearing as `undefined`, but the TS type indicates
  (incorrectly) that it is always defined but possibly `null`. This can
  lead to subtle errors that the TypeScript compiler doesn't catch. The
  fix is to include the `#[ts(optional_fields = nullable)]` macro for all
  protocol structs that contain one or more `Optional<>` fields.
  
  This PR also includes a new test that validates that all TS protocol
  code containing "| null" in its type is marked optional ("?") to catch
  cases where `#[ts(optional_fields = nullable)]` is omitted.

  Eric Traut · 2025-10-29 12:09:47 -07:00
  069a38a06c
• [app-server] Annotate more exported types with a title (#5879)

  Follow-up to https://github.com/openai/codex/pull/5063
  
  Refined the app-server export pipeline so JSON Schema variants and
  discriminator fields are annotated with descriptive, stable titles
  before writing the bundle. This eliminates anonymous enum names in the
  generated Pydantic models (goodbye Type7) while keeping downstream
  tooling simple. Added shared helpers to derive titles and literals, and
  reused them across the traversal logic for clarity. Running just fix -p
  codex-app-server-protocol, just fmt, and cargo test -p
  codex-app-server-protocol validates the change.

  Rasmus Rygaard · 2025-10-28 16:35:12 -07:00
  a1635eea25
• fix: revert "[app-server] fix account/read response annotation (#5642)" (#5796)

  Revert #5642 because this generates:
  
  ```
  // GENERATED CODE! DO NOT MODIFY BY HAND!
  
  // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
  
  export type GetAccountResponse = Account | null;
  ```
  
  But `Account` is unknown.
  
  The unique use of `#[ts(export)]` on `GetAccountResponse` is also
  suspicious as are the changes to
  `codex-rs/app-server-protocol/src/export.rs` since the existing system
  has worked fine for quite some time.
  
  Though a pure backout of #5642 puts things in a state where, as the PR
  noted, the following does not work:
  
  ```
  cargo run -p codex-app-server-protocol --bin export -- --out DIR
  ```
  
  So in addition to the backout, this PR adds:
  
  ```rust
  #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
  #[serde(rename_all = "camelCase")]
  pub struct GetAccountResponse {
      pub account: Account,
  }
  ```
  
  and changes `GetAccount.response` as follows:
  
  ```diff
  -        response: Option<Account>,
  +        response: GetAccountResponse,
  ```
  
  making it consistent with other types.
  
  With this change, I verified that both of the following work:
  
  ```
  just codex generate-ts --out /tmp/somewhere
  cargo run -p codex-app-server-protocol --bin export -- --out /tmp/somewhere-else
  ```
  
  The generated TypeScript is as follows:
  
  ```typescript
  // GetAccountResponse.ts
  import type { Account } from "./Account";
  
  export type GetAccountResponse = { account: Account, };
  ```
  
  and
  
  ```typescript
  // Account.ts
  import type { PlanType } from "./PlanType";
  
  export type Account = { "type": "ApiKey", api_key: string, } | { "type": "chatgpt", email: string | null, plan_type: PlanType, };
  ```
  
  Though while the inconsistency between `"type": "ApiKey"` and `"type":
  "chatgpt"` is quite concerning, I'm not sure if that format is ever
  written to disk in any case, but @owenlin0, I would recommend looking
  into that.
  
  Also, it appears that the types in `codex-rs/protocol/src/account.rs`
  are used exclusively by the `app-server-protocol` crate, so perhaps they
  should just be moved there?

  Michael Bolin · 2025-10-26 18:57:42 -07:00
  a55b0c4bcc
• [app-server] fix account/read response annotation (#5642)

  The API schema export is currently broken:
  ```
  > cargo run -p codex-app-server-protocol --bin export -- --out DIR
  Error: this type cannot be exported
  ```
  
  This PR fixes the error message so we get more info:
  ```
  > cargo run -p codex-app-server-protocol --bin export -- --out DIR
  Error: failed to export client responses: dependency core::option::Option<codex_protocol::account::Account> cannot be exported
  ```
  
  And fixes the root cause which is the `account/read` response.

  Owen Lin · 2025-10-24 11:17:46 -07:00
  190e7eb104
• Generate JSON schema for app-server protocol (#5063)

  Add annotations and an export script that let us generate app-server
  protocol types as typescript and JSONSchema.
  
  The script itself is a bit hacky because we need to manually label some
  of the types. Unfortunately it seems that enum variants don't get good
  names by default and end up with something like `EventMsg1`,
  `EventMsg2`, etc. I'm not an expert in this by any means, but since this
  is only run manually and we already need to enumerate the types required
  to describe the protocol, it didn't seem that much worse. An ideal
  solution here would be to have some kind of root that we could generate
  schemas for in one go, but I'm not sure if that's compatible with how we
  generate the protocol today.

  Rasmus Rygaard · 2025-10-20 11:45:11 -07:00
  846960ae3d