## 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.
- shows names of threads in the ResumePicker used by `/resume` and
`codex resume` if set, default to preview (previous behaviour) if none
- adds a `find_thread_names_by_ids` that maps names to IDs in
`codex-rs/core/src/rollout/session_index.rs`. It reads sequentially in
normal (instead of reverse order in `codex resume <name>`) the index
mapping file. This function is called from a list of session (default
page is 25, pages loaded depends of height of terminal), for which most
of them will always have at least one session unnamed and require the
whole file to be read therefore. Could be better and sqlite integration
will make this better
- those reads won't be needed when leveraging sqlite
Opened questions:
- We could rename the TUI "Conversation" column to "Name" or "Thread"
that would feel more accurate. Could be a fast-follow if we implement
auto-naming as it'll always be a name instead?
Similar to what @sayan-oai did in openai/codex#8956 for
`config.schema.json`, this PR updates the repo so that it includes the
output of `codex app-server generate-json-schema` and `codex app-server
generate-ts` and adds a test to verify it is in sync with the current
code.
Motivation:
- This makes any schema changes introduced by a PR transparent during
code review.
- In particular, this should help us catch PRs that would introduce a
non-backwards-compatible change to the app schema (eventually, this
should also be enforced by tooling).
- Once https://github.com/openai/codex/pull/10231 is in to formalize the
notion of "experimental" fields, we can work on ensuring the
non-experimental bits are backwards-compatible.
`codex-rs/app-server-protocol/tests/schema_fixtures.rs` was added as the
test and `just write-app-server-schema` can be use to generate the
vendored schema files.
Incidentally, when I run:
```
rg _ codex-rs/app-server-protocol/schema/typescript/v2
```
I see a number of `snake_case` names that should be `camelCase`.
Motivation:
- `codex-app-server-protocol` schema fixtures are not insta snapshots.
- Filtering `*.snap.new` is confusing and risks hiding real files.
What changed:
- Remove the `.snap.new` filename special case in `read_schema_fixture_tree`.
Refs: macOS Bazel schema fixture mismatch investigation
Motivation:
- `codex-app-server-protocol` schema fixtures are not insta snapshots.
- Filtering `*.snap.new` is confusing and risks hiding real files.
What changed:
- Remove the `.snap.new` filename special case in `read_schema_fixture_tree`.
Refs: macOS Bazel schema fixture mismatch investigation
Motivation:
- `codex-app-server-protocol` schema fixtures are not insta snapshots.
- Filtering `*.snap.new` is confusing and risks hiding real files.
What changed:
- Remove the `.snap.new` filename special case in `read_schema_fixture_tree`.
Refs: macOS Bazel schema fixture mismatch investigation
Motivation:
- App-server JSON schema output is already stable; sorting object keys is unnecessary.
- Alphabetical key canonicalization is potentially harmful because it obscures intentional ordering (e.g. struct field order) and makes diffs noisier.
What changed:
- Remove JSON key-sorting from schema emission.
- Regenerate vendored JSON schema fixtures.
Refs: openai/codex#8956 (fixture sync test pattern)
Motivation:
- `cargo clippy --tests` is run in CI with `-D clippy::expect-used`; the new schema fixture test used `expect()`.
What changed:
- Convert test helpers to return `anyhow::Result` and add context instead of using `expect()`.
Refs: 3b069fda39 (schema fixture vendoring commit)
Motivation:
- Keep `codex app-server` protocol artifacts (TypeScript + JSON Schema) checked in for consumers (e.g. IDE integrations) and make changes reviewable.
- Prevent drift between generated output (`codex app-server generate-ts` / `codex app-server generate-json-schema`) and what is vendored in the repo.
What changed:
- Vendor generated artifacts under `codex-rs/app-server-protocol/schema/typescript/` and `codex-rs/app-server-protocol/schema/json/`.
- Add `just write-app-server-schema` to fully regenerate fixtures (including deleting stale files).
- Add a fixture sync test for `codex-app-server-protocol` to assert the vendored trees match freshly generated output.
- Canonicalize JSON schema output (sorted object keys) for deterministic diffs.
- Wire Bazel test data so remote tests can read the vendored fixtures.
Refs: openai/codex#8956 (config.schema.json vendoring + sync test pattern)
## Summary
We ideally shouldn't make it to this point in the first place, but if we
do try to append a rule that already exists, we shouldn't append the
same rule twice.
## Testing
- [x] Added unit test for this case
Michael Bolin