Skip to content

feat: experimental flags#10231

Merged
jif-oai merged 12 commits intomainfrom
jif/experimental
Feb 2, 2026
Merged

feat: experimental flags#10231
jif-oai merged 12 commits intomainfrom
jif/experimental

Conversation

@jif-oai
Copy link
Collaborator

@jif-oai jif-oai commented Jan 30, 2026

## 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
Copy link
Collaborator Author

jif-oai commented Jan 31, 2026

@codex review

Copy link
Contributor

@chatgpt-codex-connector chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2281b13a7f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@jif-oai
Copy link
Collaborator Author

jif-oai commented Jan 31, 2026

@codex review

@jif-oai jif-oai marked this pull request as ready for review January 31, 2026 17:16
Copy link
Contributor

@chatgpt-codex-connector chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c5d570761d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Copy link
Collaborator

@bolinfest bolinfest left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice: I'm excited to get this in!

bolinfest added a commit that referenced this pull request Feb 2, 2026
Similar to what @sayan-oai did in #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 #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`.
@bolinfest
Copy link
Collaborator

@jif-oai now that #10371 is in, you must rebase on it and run just write-app-server-schema as part of your PR. If your stuff is working correctly, then only experimental APIs should be removed as part of the changes to codex-rs/app-server-protocol/schema.

@jif-oai
Copy link
Collaborator Author

jif-oai commented Feb 2, 2026

@codex review

@chatgpt-codex-connector
Copy link
Contributor

Codex Review: Didn't find any major issues. More of your lovely PRs please.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@jif-oai jif-oai merged commit 3cc9122 into main Feb 2, 2026
37 of 38 checks passed
@jif-oai jif-oai deleted the jif/experimental branch February 2, 2026 11:06
@github-actions github-actions bot locked and limited conversation to collaborators Feb 2, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants