From 1751116ec62aebf9c242ad7ed00515386629f56e Mon Sep 17 00:00:00 2001 From: Owen Lin Date: Fri, 6 Feb 2026 12:48:04 -0800 Subject: [PATCH] chore(app-server): add experimental annotation to relevant fields (#10928) These fields had always been documented as experimental/unstable with docstrings, but now let's actually use the `experimental` annotation to be more explicit. - thread/start.experimentalRawEvents - thread/resume.history - thread/resume.path - thread/fork.path - turn/start.collaborationMode - account/login/start.chatgptAuthTokens --- .../schema/json/ClientRequest.json | 40 ------------------- .../codex_app_server_protocol.schemas.json | 40 ------------------- .../schema/json/v2/ThreadForkParams.json | 7 ---- .../schema/json/v2/ThreadResumeParams.json | 17 -------- .../schema/json/v2/ThreadStartParams.json | 5 --- .../schema/json/v2/TurnStartParams.json | 11 ----- .../schema/typescript/v2/ThreadForkParams.ts | 8 ++-- .../typescript/v2/ThreadResumeParams.ts | 11 ++--- .../schema/typescript/v2/ThreadStartParams.ts | 4 +- .../schema/typescript/v2/TurnStartParams.ts | 31 +++++--------- .../src/protocol/common.rs | 4 ++ .../app-server-protocol/src/protocol/v2.rs | 26 ++++++++---- 12 files changed, 41 insertions(+), 163 deletions(-) diff --git a/codex-rs/app-server-protocol/schema/json/ClientRequest.json b/codex-rs/app-server-protocol/schema/json/ClientRequest.json index 0ccf45302..7ffaadbfc 100644 --- a/codex-rs/app-server-protocol/schema/json/ClientRequest.json +++ b/codex-rs/app-server-protocol/schema/json/ClientRequest.json @@ -2323,13 +2323,6 @@ "null" ] }, - "path": { - "description": "[UNSTABLE] Specify the rollout path to fork from. If specified, the thread_id param will be ignored.", - "type": [ - "string", - "null" - ] - }, "sandbox": { "anyOf": [ { @@ -2486,16 +2479,6 @@ "null" ] }, - "history": { - "description": "[UNSTABLE] FOR CODEX CLOUD - DO NOT USE. If specified, the thread will be resumed with the provided history instead of loaded from disk.", - "items": { - "$ref": "#/definitions/ResponseItem" - }, - "type": [ - "array", - "null" - ] - }, "model": { "description": "Configuration overrides for the resumed thread, if any.", "type": [ @@ -2509,13 +2492,6 @@ "null" ] }, - "path": { - "description": "[UNSTABLE] Specify the rollout path to resume from. If specified, the thread_id param will be ignored.", - "type": [ - "string", - "null" - ] - }, "personality": { "anyOf": [ { @@ -2643,11 +2619,6 @@ "null" ] }, - "experimentalRawEvents": { - "default": false, - "description": "If true, opt into emitting raw response items on the event stream.\n\nThis is for internal use only (e.g. Codex Cloud). (TODO): Figure out a better way to categorize internal / experimental events & protocols.", - "type": "boolean" - }, "model": { "type": [ "string", @@ -2722,17 +2693,6 @@ ], "description": "Override the approval policy for this turn and subsequent turns." }, - "collaborationMode": { - "anyOf": [ - { - "$ref": "#/definitions/CollaborationMode" - }, - { - "type": "null" - } - ], - "description": "EXPERIMENTAL - set a pre-set collaboration mode. Takes precedence over model, reasoning_effort, and developer instructions if set." - }, "cwd": { "description": "Override the working directory for this turn and subsequent turns.", "type": [ diff --git a/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json b/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json index c72db7dae..969d914b1 100644 --- a/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json +++ b/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json @@ -14230,13 +14230,6 @@ "null" ] }, - "path": { - "description": "[UNSTABLE] Specify the rollout path to fork from. If specified, the thread_id param will be ignored.", - "type": [ - "string", - "null" - ] - }, "sandbox": { "anyOf": [ { @@ -14995,16 +14988,6 @@ "null" ] }, - "history": { - "description": "[UNSTABLE] FOR CODEX CLOUD - DO NOT USE. If specified, the thread will be resumed with the provided history instead of loaded from disk.", - "items": { - "$ref": "#/definitions/v2/ResponseItem" - }, - "type": [ - "array", - "null" - ] - }, "model": { "description": "Configuration overrides for the resumed thread, if any.", "type": [ @@ -15018,13 +15001,6 @@ "null" ] }, - "path": { - "description": "[UNSTABLE] Specify the rollout path to resume from. If specified, the thread_id param will be ignored.", - "type": [ - "string", - "null" - ] - }, "personality": { "anyOf": [ { @@ -15224,11 +15200,6 @@ "null" ] }, - "experimentalRawEvents": { - "default": false, - "description": "If true, opt into emitting raw response items on the event stream.\n\nThis is for internal use only (e.g. Codex Cloud). (TODO): Figure out a better way to categorize internal / experimental events & protocols.", - "type": "boolean" - }, "model": { "type": [ "string", @@ -15665,17 +15636,6 @@ ], "description": "Override the approval policy for this turn and subsequent turns." }, - "collaborationMode": { - "anyOf": [ - { - "$ref": "#/definitions/v2/CollaborationMode" - }, - { - "type": "null" - } - ], - "description": "EXPERIMENTAL - set a pre-set collaboration mode. Takes precedence over model, reasoning_effort, and developer instructions if set." - }, "cwd": { "description": "Override the working directory for this turn and subsequent turns.", "type": [ diff --git a/codex-rs/app-server-protocol/schema/json/v2/ThreadForkParams.json b/codex-rs/app-server-protocol/schema/json/v2/ThreadForkParams.json index 1de59e2a0..5638468a4 100644 --- a/codex-rs/app-server-protocol/schema/json/v2/ThreadForkParams.json +++ b/codex-rs/app-server-protocol/schema/json/v2/ThreadForkParams.json @@ -69,13 +69,6 @@ "null" ] }, - "path": { - "description": "[UNSTABLE] Specify the rollout path to fork from. If specified, the thread_id param will be ignored.", - "type": [ - "string", - "null" - ] - }, "sandbox": { "anyOf": [ { diff --git a/codex-rs/app-server-protocol/schema/json/v2/ThreadResumeParams.json b/codex-rs/app-server-protocol/schema/json/v2/ThreadResumeParams.json index ed1d5274e..58e20e58e 100644 --- a/codex-rs/app-server-protocol/schema/json/v2/ThreadResumeParams.json +++ b/codex-rs/app-server-protocol/schema/json/v2/ThreadResumeParams.json @@ -832,16 +832,6 @@ "null" ] }, - "history": { - "description": "[UNSTABLE] FOR CODEX CLOUD - DO NOT USE. If specified, the thread will be resumed with the provided history instead of loaded from disk.", - "items": { - "$ref": "#/definitions/ResponseItem" - }, - "type": [ - "array", - "null" - ] - }, "model": { "description": "Configuration overrides for the resumed thread, if any.", "type": [ @@ -855,13 +845,6 @@ "null" ] }, - "path": { - "description": "[UNSTABLE] Specify the rollout path to resume from. If specified, the thread_id param will be ignored.", - "type": [ - "string", - "null" - ] - }, "personality": { "anyOf": [ { diff --git a/codex-rs/app-server-protocol/schema/json/v2/ThreadStartParams.json b/codex-rs/app-server-protocol/schema/json/v2/ThreadStartParams.json index f2b0052e6..1574c0710 100644 --- a/codex-rs/app-server-protocol/schema/json/v2/ThreadStartParams.json +++ b/codex-rs/app-server-protocol/schema/json/v2/ThreadStartParams.json @@ -86,11 +86,6 @@ "null" ] }, - "experimentalRawEvents": { - "default": false, - "description": "If true, opt into emitting raw response items on the event stream.\n\nThis is for internal use only (e.g. Codex Cloud). (TODO): Figure out a better way to categorize internal / experimental events & protocols.", - "type": "boolean" - }, "model": { "type": [ "string", diff --git a/codex-rs/app-server-protocol/schema/json/v2/TurnStartParams.json b/codex-rs/app-server-protocol/schema/json/v2/TurnStartParams.json index be351a48e..d1b245614 100644 --- a/codex-rs/app-server-protocol/schema/json/v2/TurnStartParams.json +++ b/codex-rs/app-server-protocol/schema/json/v2/TurnStartParams.json @@ -383,17 +383,6 @@ ], "description": "Override the approval policy for this turn and subsequent turns." }, - "collaborationMode": { - "anyOf": [ - { - "$ref": "#/definitions/CollaborationMode" - }, - { - "type": "null" - } - ], - "description": "EXPERIMENTAL - set a pre-set collaboration mode. Takes precedence over model, reasoning_effort, and developer instructions if set." - }, "cwd": { "description": "Override the working directory for this turn and subsequent turns.", "type": [ diff --git a/codex-rs/app-server-protocol/schema/typescript/v2/ThreadForkParams.ts b/codex-rs/app-server-protocol/schema/typescript/v2/ThreadForkParams.ts index eae506c2b..44c81a24e 100644 --- a/codex-rs/app-server-protocol/schema/typescript/v2/ThreadForkParams.ts +++ b/codex-rs/app-server-protocol/schema/typescript/v2/ThreadForkParams.ts @@ -14,13 +14,11 @@ import type { SandboxMode } from "./SandboxMode"; * * Prefer using thread_id whenever possible. */ -export type ThreadForkParams = { threadId: string, -/** +export type ThreadForkParams = {threadId: string, /** * [UNSTABLE] Specify the rollout path to fork from. * If specified, the thread_id param will be ignored. */ -path?: string | null, -/** +path?: string | null, /** * Configuration overrides for the forked thread, if any. */ -model?: string | null, modelProvider?: string | null, cwd?: string | null, approvalPolicy?: AskForApproval | null, sandbox?: SandboxMode | null, config?: { [key in string]?: JsonValue } | null, baseInstructions?: string | null, developerInstructions?: string | null, }; +model?: string | null, modelProvider?: string | null, cwd?: string | null, approvalPolicy?: AskForApproval | null, sandbox?: SandboxMode | null, config?: { [key in string]?: JsonValue } | null, baseInstructions?: string | null, developerInstructions?: string | null}; diff --git a/codex-rs/app-server-protocol/schema/typescript/v2/ThreadResumeParams.ts b/codex-rs/app-server-protocol/schema/typescript/v2/ThreadResumeParams.ts index 64d1f77d8..c868b8f95 100644 --- a/codex-rs/app-server-protocol/schema/typescript/v2/ThreadResumeParams.ts +++ b/codex-rs/app-server-protocol/schema/typescript/v2/ThreadResumeParams.ts @@ -18,19 +18,16 @@ import type { SandboxMode } from "./SandboxMode"; * * Prefer using thread_id whenever possible. */ -export type ThreadResumeParams = { threadId: string, -/** +export type ThreadResumeParams = {threadId: string, /** * [UNSTABLE] FOR CODEX CLOUD - DO NOT USE. * If specified, the thread will be resumed with the provided history * instead of loaded from disk. */ -history?: Array | null, -/** +history?: Array | null, /** * [UNSTABLE] Specify the rollout path to resume from. * If specified, the thread_id param will be ignored. */ -path?: string | null, -/** +path?: string | null, /** * Configuration overrides for the resumed thread, if any. */ -model?: string | null, modelProvider?: string | null, cwd?: string | null, approvalPolicy?: AskForApproval | null, sandbox?: SandboxMode | null, config?: { [key in string]?: JsonValue } | null, baseInstructions?: string | null, developerInstructions?: string | null, personality?: Personality | null, }; +model?: string | null, modelProvider?: string | null, cwd?: string | null, approvalPolicy?: AskForApproval | null, sandbox?: SandboxMode | null, config?: { [key in string]?: JsonValue } | null, baseInstructions?: string | null, developerInstructions?: string | null, personality?: Personality | null}; diff --git a/codex-rs/app-server-protocol/schema/typescript/v2/ThreadStartParams.ts b/codex-rs/app-server-protocol/schema/typescript/v2/ThreadStartParams.ts index b0f1d1e2e..84ad633d5 100644 --- a/codex-rs/app-server-protocol/schema/typescript/v2/ThreadStartParams.ts +++ b/codex-rs/app-server-protocol/schema/typescript/v2/ThreadStartParams.ts @@ -7,9 +7,7 @@ import type { AskForApproval } from "./AskForApproval"; import type { SandboxMode } from "./SandboxMode"; export type ThreadStartParams = {model?: string | null, modelProvider?: string | null, cwd?: string | null, approvalPolicy?: AskForApproval | null, sandbox?: SandboxMode | null, config?: { [key in string]?: JsonValue } | null, baseInstructions?: string | null, developerInstructions?: string | null, personality?: Personality | null, ephemeral?: boolean | null, /** - * If true, opt into emitting raw response items on the event stream. - * + * If true, opt into emitting raw Responses API items on the event stream. * This is for internal use only (e.g. Codex Cloud). - * (TODO): Figure out a better way to categorize internal / experimental events & protocols. */ experimentalRawEvents: boolean}; diff --git a/codex-rs/app-server-protocol/schema/typescript/v2/TurnStartParams.ts b/codex-rs/app-server-protocol/schema/typescript/v2/TurnStartParams.ts index 8cf1aaf20..ec3904864 100644 --- a/codex-rs/app-server-protocol/schema/typescript/v2/TurnStartParams.ts +++ b/codex-rs/app-server-protocol/schema/typescript/v2/TurnStartParams.ts @@ -10,41 +10,32 @@ import type { AskForApproval } from "./AskForApproval"; import type { SandboxPolicy } from "./SandboxPolicy"; import type { UserInput } from "./UserInput"; -export type TurnStartParams = { threadId: string, input: Array, -/** +export type TurnStartParams = {threadId: string, input: Array, /** * Override the working directory for this turn and subsequent turns. */ -cwd?: string | null, -/** +cwd?: string | null, /** * Override the approval policy for this turn and subsequent turns. */ -approvalPolicy?: AskForApproval | null, -/** +approvalPolicy?: AskForApproval | null, /** * Override the sandbox policy for this turn and subsequent turns. */ -sandboxPolicy?: SandboxPolicy | null, -/** +sandboxPolicy?: SandboxPolicy | null, /** * Override the model for this turn and subsequent turns. */ -model?: string | null, -/** +model?: string | null, /** * Override the reasoning effort for this turn and subsequent turns. */ -effort?: ReasoningEffort | null, -/** +effort?: ReasoningEffort | null, /** * Override the reasoning summary for this turn and subsequent turns. */ -summary?: ReasoningSummary | null, -/** +summary?: ReasoningSummary | null, /** * Override the personality for this turn and subsequent turns. */ -personality?: Personality | null, -/** +personality?: Personality | null, /** * Optional JSON Schema used to constrain the final assistant message for this turn. */ -outputSchema?: JsonValue | null, -/** - * EXPERIMENTAL - set a pre-set collaboration mode. +outputSchema?: JsonValue | null, /** + * EXPERIMENTAL - Set a pre-set collaboration mode. * Takes precedence over model, reasoning_effort, and developer instructions if set. */ -collaborationMode?: CollaborationMode | null, }; +collaborationMode?: CollaborationMode | null}; diff --git a/codex-rs/app-server-protocol/src/protocol/common.rs b/codex-rs/app-server-protocol/src/protocol/common.rs index 46de0e581..9e0a5f8d7 100644 --- a/codex-rs/app-server-protocol/src/protocol/common.rs +++ b/codex-rs/app-server-protocol/src/protocol/common.rs @@ -190,10 +190,12 @@ client_request_definitions! { }, ThreadResume => "thread/resume" { params: v2::ThreadResumeParams, + inspect_params: true, response: v2::ThreadResumeResponse, }, ThreadFork => "thread/fork" { params: v2::ThreadForkParams, + inspect_params: true, response: v2::ThreadForkResponse, }, ThreadArchive => "thread/archive" { @@ -250,6 +252,7 @@ client_request_definitions! { }, TurnStart => "turn/start" { params: v2::TurnStartParams, + inspect_params: true, response: v2::TurnStartResponse, }, TurnSteer => "turn/steer" { @@ -303,6 +306,7 @@ client_request_definitions! { LoginAccount => "account/login/start" { params: v2::LoginAccountParams, + inspect_params: true, response: v2::LoginAccountResponse, }, diff --git a/codex-rs/app-server-protocol/src/protocol/v2.rs b/codex-rs/app-server-protocol/src/protocol/v2.rs index 756543328..630e03957 100644 --- a/codex-rs/app-server-protocol/src/protocol/v2.rs +++ b/codex-rs/app-server-protocol/src/protocol/v2.rs @@ -867,7 +867,7 @@ pub enum Account { Chatgpt { email: String, plan_type: PlanType }, } -#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)] +#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS, ExperimentalApi)] #[serde(tag = "type")] #[ts(tag = "type")] #[ts(export_to = "v2/")] @@ -884,6 +884,7 @@ pub enum LoginAccountParams { Chatgpt, /// [UNSTABLE] FOR OPENAI INTERNAL USE ONLY - DO NOT USE. /// The access token must contain the same scopes that Codex-managed ChatGPT auth tokens have. + #[experimental("account/login/start.chatgptAuthTokens")] #[serde(rename = "chatgptAuthTokens")] #[ts(rename = "chatgptAuthTokens")] ChatgptAuthTokens { @@ -1314,10 +1315,9 @@ pub struct ThreadStartParams { #[experimental("thread/start.mockExperimentalField")] #[ts(optional = nullable)] pub mock_experimental_field: Option, - /// If true, opt into emitting raw response items on the event stream. - /// + /// If true, opt into emitting raw Responses API items on the event stream. /// This is for internal use only (e.g. Codex Cloud). - /// (TODO): Figure out a better way to categorize internal / experimental events & protocols. + #[experimental("thread/start.experimentalRawEvents")] #[serde(default)] pub experimental_raw_events: bool, } @@ -1352,7 +1352,9 @@ pub struct ThreadStartResponse { pub reasoning_effort: Option, } -#[derive(Serialize, Deserialize, Debug, Default, Clone, PartialEq, JsonSchema, TS)] +#[derive( + Serialize, Deserialize, Debug, Default, Clone, PartialEq, JsonSchema, TS, ExperimentalApi, +)] #[serde(rename_all = "camelCase")] #[ts(export_to = "v2/")] /// There are three ways to resume a thread: @@ -1370,11 +1372,13 @@ pub struct ThreadResumeParams { /// [UNSTABLE] FOR CODEX CLOUD - DO NOT USE. /// If specified, the thread will be resumed with the provided history /// instead of loaded from disk. + #[experimental("thread/resume.history")] #[ts(optional = nullable)] pub history: Option>, /// [UNSTABLE] Specify the rollout path to resume from. /// If specified, the thread_id param will be ignored. + #[experimental("thread/resume.path")] #[ts(optional = nullable)] pub path: Option, @@ -1412,7 +1416,9 @@ pub struct ThreadResumeResponse { pub reasoning_effort: Option, } -#[derive(Serialize, Deserialize, Debug, Default, Clone, PartialEq, JsonSchema, TS)] +#[derive( + Serialize, Deserialize, Debug, Default, Clone, PartialEq, JsonSchema, TS, ExperimentalApi, +)] #[serde(rename_all = "camelCase")] #[ts(export_to = "v2/")] /// There are two ways to fork a thread: @@ -1427,6 +1433,7 @@ pub struct ThreadForkParams { /// [UNSTABLE] Specify the rollout path to fork from. /// If specified, the thread_id param will be ignored. + #[experimental("thread/fork.path")] #[ts(optional = nullable)] pub path: Option, @@ -2027,7 +2034,9 @@ pub enum TurnStatus { } // Turn APIs -#[derive(Serialize, Deserialize, Debug, Default, Clone, PartialEq, JsonSchema, TS)] +#[derive( + Serialize, Deserialize, Debug, Default, Clone, PartialEq, JsonSchema, TS, ExperimentalApi, +)] #[serde(rename_all = "camelCase")] #[ts(export_to = "v2/")] pub struct TurnStartParams { @@ -2058,8 +2067,9 @@ pub struct TurnStartParams { #[ts(optional = nullable)] pub output_schema: Option, - /// EXPERIMENTAL - set a pre-set collaboration mode. + /// EXPERIMENTAL - Set a pre-set collaboration mode. /// Takes precedence over model, reasoning_effort, and developer instructions if set. + #[experimental("turn/start.collaborationMode")] #[ts(optional = nullable)] pub collaboration_mode: Option, }