feat: annotate experimental fields in app server protocol #10221
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The idea behind this PR is to formalize unstable/experimental fields in app server. It adds a default feature named
codex-experimental-apito thecodex-app-server-protocolcrate.By declaring
#[cfg(feature = "codex-experimental-api")]on a struct or field, that declares it "experimental." Example:Now
codex app-serverhas some new options:Without
--experimental, the output will not include anything tagged with#[cfg(feature = "codex-experimental-api")]. This is what we should tell our external partners to use, or anyone who doesn't bundle Codex CLI with their product to ensure there is no API drift.Because this uses a crate feature, we have to build carefully where:
codex-experimental-apifeature is enabled.codex-experimental-apimust be disabled, so we only do this for thecodex-app-server-protocol-stable-exportcrate, which contains only amain.rsthat is used to codegen the stable version.codex-app-server-json-schemaandcodex-app-server-ts-typescrates uses thecodex-app-server-protocol-stable-exportbinary to verify that the vendoredstable/folders match the current source code.just write-app-server-protocol-stableto regenerate the vendoredstable/folders also usescodex-app-server-protocol-stable-export.The downside of the current approach is that it currently uses
include_dir!()with the uncompressed version of the stable API. This adds a few megabytes, but we should be able to use compression to improve things. (We do this so that we only buildcodex-app-server-protocolwith one permutation offeatureswhen building the CLI, though we have to build one other permutation when running tests.)