rad/codex

mirror of https://github.com/openai/codex.git synced 2026-03-05 21:45:28 +03:00

Files

jif-oai 3cc9122ee2 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.

2026-02-02 11:06:50 +00:00

src

feat: experimental flags (#10231 )

2026-02-02 11:06:50 +00:00

BUILD.bazel

…

Cargo.toml

…

README.md

…

repo_root.marker

…

README.md

codex-utils-cargo-bin runfiles strategy

We disable the directory-based runfiles strategy and rely on the manifest strategy across all platforms. This avoids Windows path length issues and keeps behavior consistent in local and remote builds on all platforms. Bazel sets RUNFILES_MANIFEST_FILE, and the codex-utils-cargo-bin helpers use the runfiles crate to resolve runfiles via that manifest.

Function behavior:

cargo_bin: reads CARGO_BIN_EXE_* environment variables (set by Cargo or Bazel) and resolves them via the runfiles manifest when RUNFILES_MANIFEST_FILE is present. When not under runfiles, it only accepts absolute paths from CARGO_BIN_EXE_* and returns an error otherwise.
find_resource!: used by tests to locate fixtures. It chooses the Bazel runfiles resolution path when RUNFILES_MANIFEST_FILE is set, otherwise it falls back to a CARGO_MANIFEST_DIR-relative path for Cargo runs.

Background: