Skip to content

Conversation

@bolinfest
Copy link
Collaborator

@bolinfest bolinfest commented Jan 30, 2026

The idea behind this PR is to formalize unstable/experimental fields in app server. It adds a default feature named codex-experimental-api to the codex-app-server-protocol crate.

By declaring #[cfg(feature = "codex-experimental-api")] on a struct or field, that declares it "experimental." Example:

#[cfg(feature = "codex-experimental-api")]
/// EXPERIMENTAL - list collaboration mode presets.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema, TS)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct CollaborationModeListParams {}

#[cfg(feature = "codex-experimental-api")]
/// EXPERIMENTAL - collaboration mode presets response.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct CollaborationModeListResponse {
    pub data: Vec<CollaborationModeMask>,
}

Now codex app-server has some new options:

codex app-server generate-ts --experimental
codex app-server generate-json-schema --experimental

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:

  • When building the CLI, the codex-experimental-api feature is enabled.
  • To build the stable version, codex-experimental-api must be disabled, so we only do this for the codex-app-server-protocol-stable-export crate, which contains only a main.rs that is used to codegen the stable version.
  • Both the codex-app-server-json-schema and codex-app-server-ts-types crates uses the codex-app-server-protocol-stable-export binary to verify that the vendored stable/ folders match the current source code.
  • just write-app-server-protocol-stable to regenerate the vendored stable/ folders also uses codex-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 build codex-app-server-protocol with one permutation of features when building the CLI, though we have to build one other permutation when running tests.)

@bolinfest
Copy link
Collaborator Author

Abandoning in favor of #10231.

@bolinfest bolinfest closed this Jan 30, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant