core/core-agent-ide
8
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
core-agent-ide/codex-rs/app-server-protocol/schema/json/v2
History
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
..
AccountLoginCompletedNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
AccountRateLimitsUpdatedNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
AccountUpdatedNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
AgentMessageDeltaNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
AppsListParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
AppsListResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
CancelLoginAccountParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
CancelLoginAccountResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
CommandExecParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
CommandExecResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
CommandExecutionOutputDeltaNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ConfigBatchWriteParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ConfigReadParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ConfigReadResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ConfigRequirementsReadResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ConfigValueWriteParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ConfigWarningNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ConfigWriteResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ContextCompactedNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
DeprecationNoticeNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ErrorNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
FeedbackUploadParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
FeedbackUploadResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
FileChangeOutputDeltaNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
GetAccountParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
GetAccountRateLimitsResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
GetAccountResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ItemCompletedNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ItemStartedNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ListMcpServerStatusParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ListMcpServerStatusResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
LoginAccountParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
LoginAccountResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
LogoutAccountResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
McpServerOauthLoginCompletedNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
McpServerOauthLoginParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
McpServerOauthLoginResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
McpServerRefreshResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
McpToolCallProgressNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ModelListParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ModelListResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
PlanDeltaNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
RawResponseItemCompletedNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ReasoningSummaryPartAddedNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ReasoningSummaryTextDeltaNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ReasoningTextDeltaNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ReviewStartParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ReviewStartResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
SkillsConfigWriteParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
SkillsConfigWriteResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
SkillsListParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
SkillsListResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
TerminalInteractionNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ThreadArchiveParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ThreadArchiveResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ThreadForkParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ThreadForkResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ThreadListParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ThreadListResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ThreadLoadedListParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ThreadLoadedListResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ThreadNameUpdatedNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ThreadReadParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ThreadReadResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ThreadResumeParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ThreadResumeResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ThreadRollbackParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ThreadRollbackResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ThreadSetNameParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ThreadSetNameResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ThreadStartedNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ThreadStartParams.json feat: experimental flags (#10231) 2026-02-02 11:06:50 +00:00
ThreadStartResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ThreadTokenUsageUpdatedNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ThreadUnarchiveParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ThreadUnarchiveResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
TurnCompletedNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
TurnDiffUpdatedNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
TurnInterruptParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
TurnInterruptResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
TurnPlanUpdatedNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
TurnStartedNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
TurnStartParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
TurnStartResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
WindowsWorldWritableWarningNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00