Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
/**
* Codex app-server JSON-RPC 协议 — TypeScript 类型层。
*
* 仅手写 maker-core 实际用到的子集 (Phase 1: initialize + thread/start + turn/start +
* turn/interrupt + 7 类核心 Notification)。Phase 2/3 再补 ServerRequest (approval) /
* ThreadResume / ThreadFork / ThreadRollback。
*
* 真值参考 (只读, 不要在这边猜):
* - E:\AIWork\codex\codex-rs\app-server-protocol\src\jsonrpc_lite.rs
* ↑ 注意: Codex 的 JSON-RPC **不**发 jsonrpc: "2.0" 字段
* - E:\AIWork\codex\codex-rs\app-server-protocol\src\protocol\v1.rs (Initialize)
* - E:\AIWork\codex\codex-rs\app-server-protocol\src\protocol\v2.rs (Thread/Turn/Item)
* - E:\AIWork\codex\codex-rs\app-server-protocol\src\protocol\common.rs:1406-1487 (Notification 方法名表)
*/
import type {
AccountCreditsSnapshot,
AccountRateLimitsResponse,
AccountRateLimitSnapshot,
AccountRateLimitWindow,
ConsumeAccountRateLimitResetCreditParams,
ConsumeAccountRateLimitResetCreditResponse,
} from '../../../types/account-rate-limits.js';
// ── JSON-RPC envelope (字段对齐 Rust JSONRPCRequest/Notification/Response/Error) ──
/** 自增 id 我们用 number; Rust 那边 RequestId 是 string|number untagged。 */
export type JsonRpcId = number | string;
export interface JsonRpcRequest {
id: JsonRpcId;
method: string;
params?: unknown;
}
export interface JsonRpcNotification {
method: string;
params?: unknown;
}
export interface JsonRpcSuccessResponse {
id: JsonRpcId;
result: unknown;
}
export interface JsonRpcErrorObject {
code: number;
message: string;
data?: unknown;
}
export interface JsonRpcErrorResponse {
id: JsonRpcId;
error: JsonRpcErrorObject;
}
/** 入站消息的三类区分 (无 jsonrpc 字段, 仅靠 id/method/result/error 判别)。 */
export type IncomingMessage =
| JsonRpcRequest
| JsonRpcNotification
| JsonRpcSuccessResponse
| JsonRpcErrorResponse;
// ── JSON-RPC 错误码 (Rust app-server 自定义) ──────────────────────────────────
export const JSONRPC_ERROR_CODE = {
PARSE_ERROR: -32700,
INVALID_REQUEST: -32600,
METHOD_NOT_FOUND: -32601,
INVALID_PARAMS: -32602,
INTERNAL_ERROR: -32603,
/** Codex 自定义 — 模型 overloaded。 */
OVERLOADED: -32001,
} as const;
// ── Initialize (v1.rs) ───────────────────────────────────────────────────────
export interface ClientInfo {
name: string;
title?: string;
version: string;
}
export interface InitializeCapabilities {
/**
* 必须 true 才能拿到 v2 thread/turn/item.* 的 experimental 字段
* (我们重度依赖, 默认开)。
*/
experimentalApi?: boolean;
/**
* 告诉 server: 这些 notification 别推 (省带宽 + 主线程压力)。
* Rust 默认会过滤一批 delta — 我们 Phase 1 也跟着过, 后续要消费 delta 再去掉对应项。
*/
optOutNotificationMethods?: string[];
}
export interface InitializeParams {
clientInfo: ClientInfo;
capabilities?: InitializeCapabilities;
}
export interface InitializeResponse {
userAgent: string;
/** server 端 $CODEX_HOME 绝对路径。 */
codexHome: string;
platformFamily?: string;
platformOs?: string;
/** 其余字段不消费, 用 unknown 兜底防 schema 漂移。 */
[k: string]: unknown;
}
// ── ModelList (v2.rs) ───────────────────────────────────────────────────────
/**
* `model/list` 返回的单个运行时模型。这里只维护 desktop 动态目录需要的字段子集;
* app-server 后续增加字段时由结构化类型自然忽略,避免把整份生成协议复制进 maker-core。
*/
export interface CodexModelListItem {
id: string;
/** 真正传给 turn/thread 的模型 slug;当前通常与 id 相同。 */
model: string;
displayName: string;
description: string;
hidden: boolean;
supportedReasoningEfforts: Array<{
reasoningEffort: ReasoningEffort;
description: string;
}>;
defaultReasoningEffort: ReasoningEffort;
additionalSpeedTiers: string[];
serviceTiers: Array<{ id: string; name: string; description: string }>;
isDefault: boolean;
[k: string]: unknown;
}
export interface CodexModelListParams {
cursor?: string | null;
limit?: number | null;
includeHidden?: boolean | null;
}
/** Minimal subset of `mcpServerStatus/list` used for post-start capability gates. */
export interface CodexMcpServerStatus {
name: string;
tools: Record<string, unknown>;
[k: string]: unknown;
}
export interface CodexMcpServerStatusListResponse {
data: CodexMcpServerStatus[];
nextCursor: string | null;
}
export interface CodexModelListResponse {
data: CodexModelListItem[];
nextCursor: string | null;
}
// ── ThreadStart / TurnStart / TurnInterrupt (v2.rs) ───────────────────────────
/**
* Codex 的 approval 策略 — v2.rs `#[serde(rename_all = "kebab-case")]`
* + UnlessTrusted 显式 rename 'untrusted'。**注意是 kebab-case 不是 camelCase**,
* 错了 server 直接 -32600 Invalid request。
*/
export type AskForApproval = 'untrusted' | 'on-request' | 'on-failure' | 'never';
/** Codex app-server approval reviewer. */
export type ApprovalsReviewer = 'user' | 'auto_review' | 'guardian_subagent';
/**
* sandbox 模式 — v2.rs `#[serde(rename_all = "kebab-case")]`。
* 同上, kebab-case 不是 camelCase。
*/
export type SandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access';
/**
* 推理 effort — codex_protocol::openai_models::ReasoningEffort
* `#[serde(rename_all = "lowercase")]` (注意是全小写不是 kebab/camel),
* `XHigh → "xhigh"` 而不是 "x-high"; 同理 `Max → "max"`、`Ultra → "ultra"`。
*
* max / ultra 是较新档 (GPT-5.6 Sol 等), server 按模型的 supported_reasoning_levels
* 决定是否接受; 不支持的模型仍只到 xhigh。这里放开为全集, 由目录 efforts + UI 门控
* 保证只对声明支持的模型透传 (不做全局硬塞)。
*
* 协议层只有 turn/start 接 `effort: Option<ReasoningEffort>` (v2.rs:5800);
* thread/start 不接 effort (走 server config 默认), 想让 first turn 用用户选的
* effort, 必须在 first turn/start 透传。
*/
export type ReasoningEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'ultra';
/**
* 推理 summary 偏好 — codex_protocol::config_types::ReasoningSummary
* `#[serde(rename_all = "lowercase")]`, 默认 'auto' (跟 OpenAI Responses API 默认一致)。
*
* 协议层在 turn/start (v2.rs:5801-5803) 接 summary 字段, 设置后会 override 用户
* ~/.codex/config.toml 的 model_reasoning_summary, 持续到后续 turn。我们启动 codex
* 时强制传 'auto' — 不依赖用户配置, 让 reasoning 流式输出和 claude code 一致。
*
* 'none' = OpenAI 不返 summary (UI 看不到 thinking 文本); 不要传这个。
*/
export type ReasoningSummary = 'auto' | 'concise' | 'detailed' | 'none';
/**
* Codex service tier — v2.rs ServiceTier.
* Most app-server builds use the semantic value "fast"; some builds echo the
* OpenAI Responses API value "priority" back in responses for the same mode.
* 'default' = 显式 standard 档:关 Fast 后 server 在 thread/settings/updated 通知里
* 实际回带的就是这个值 (实测 0.142.0, 切到不支持 fast 的模型时 serviceTier→'default')。
*/
export type ServiceTier = 'default' | 'fast' | 'priority' | 'flex' | 'ultrafast';
export interface ThreadStartParams {
/** 缺省走 server 端 config 的默认 model。 */
model?: string;
/**
* 覆盖本 thread 的 model provider(config `model_providers` 里的 key)。
* 缺省走 config 顶层 model_provider。用于支持远端压缩的 thread 选择内部 OpenAI
* transport identity;产品 Provider 不随之改变。provider 身份是 thread 级冻结。
*/
modelProvider?: string;
cwd?: string;
/** EXPERIMENTAL. Runtime-visible workspace roots; replaces the thread's current roots. */
runtimeWorkspaceRoots?: string[];
approvalPolicy?: AskForApproval;
/** Route interactive approvals to the user or Codex's built-in reviewer. */
approvalsReviewer?: ApprovalsReviewer;
/** Named permission profile from config (mutually exclusive with sandbox). */
permissions?: string;
sandbox?: SandboxMode;
/** Per-request config overrides, including named permission profile definitions. */
config?: Record<string, unknown>;
/** Fast mode override. Undefined = 不覆盖; null = 清空/standard; 'fast' = Fast mode. */
serviceTier?: ServiceTier | null;
/**
* 替换 codex 默认 base prompt (codex-rs/protocol/src/prompts/base_instructions/default.md)。
* 谨慎使用 — 会覆盖 codex 自带的 persona / AGENTS.md spec / tool 说明,
* 一般场景请改用 developerInstructions(append 而非 replace)。
*/
baseInstructions?: string;
/**
* 在 codex 默认 base 之后追加 developer message。等价于 Claude 的
* `systemPrompt.append`,host 产品级 prompt 走这里注入。
*/
developerInstructions?: string;
/**
* EXPERIMENTAL. Dynamic tools exposed to the model for this thread.
* Present in Codex app-server 0.135.0 `generate-ts --experimental` output
* for thread/start only; resume/fork do not currently accept this field.
*/
dynamicTools?: DynamicToolSpec[] | null;
/**
* Codex 协议是 per-thread 设这些, 不是 per-turn。后续 setModel/setEffort
* 在我们这边记 mutable, 下一个 turn 通过 turn/start 透传 (Codex app-server
* 当前 turn/start 也接 model 覆盖)。
*/
[k: string]: unknown;
}
export interface ThreadStartResponse {
thread: { id: string; [k: string]: unknown };
model: string;
modelProvider: string;
cwd: string;
runtimeWorkspaceRoots?: string[];
activePermissionProfile?: { id: string; extends?: string | null };
serviceTier?: ServiceTier | null;
[k: string]: unknown;
}
/**
* Codex UserInput — v2.rs:6006 `#[serde(tag = "type", rename_all = "camelCase")]`
*
* 关键字段名 (踩坑后定稿, 不是猜的):
* - Image.url 字段名是 `url`, 不是 `imageUrl` (即使 core 内部叫 image_url)
* - LocalImage.path: 本地文件用这个变体, 字段名 `path` (绝对路径裸字符串, 不带 file:// 前缀)
*
* 本地图像附件 → LocalImage; 远程 http(s):// → Image。Skill/Mention 用于
* Codex skill / app / plugin 这类工具注入; 普通文件附件没有协议级 file 变体,
* 需要作为文本路径引用发给模型, 让 Codex 自己用读文件能力打开。
*/
export type UserInput =
| { type: 'text'; text: string }
| { type: 'image'; url: string }
| { type: 'localImage'; path: string }
| { type: 'skill'; name: string; path: string }
| { type: 'mention'; name: string; path: string };
/**
* v2 config_types.rs CollaborationMode — EXPERIMENTAL (`turn/start.collaborationMode` /
* `thread/settings/update.collaborationMode`, initialize 已恒开 experimentalApi)。
*
* 序列化注意:
* - ModeKind 是 `#[serde(rename_all = "snake_case")]` → 'plan' | 'default'。
* - Settings 结构体**没有** rename_all → 字段保持 snake_case
* (model / reasoning_effort / developer_instructions), 不是 camelCase。
* - settings.developer_instructions 三态:
* null → server 端 normalize_collaboration_mode 填该模式的**内置指令**
* (plan 模式即官方 plan-mode developer 段, 作为独立 <collaboration_mode>
* fragment 注入, 不覆盖我们 thread/start 的 developerInstructions);
* '' → 不注入任何模式指令 (normalize 只在 null 时才填内置文案);
* 文本 → client 自定指令。
* - 设置后 collaborationMode 对模型/effort 有覆盖优先级, settings.model /
* reasoning_effort 必须带上当前 mutable 值, 否则会把用户的模型选择顶掉。
*/
export interface CollaborationModeParam {
mode: 'plan' | 'default';
settings: {
model: string;
reasoning_effort: ReasoningEffort | null;
developer_instructions: string | null;
};
}
export interface TurnStartParams {
threadId: string;
input: UserInput[];
/** EXPERIMENTAL. Replaces the runtime-visible roots before this turn starts. */
runtimeWorkspaceRoots?: string[];
/** 覆盖 thread 的默认 model (用于运行时切换 — Phase 3)。 */
model?: string;
/** 覆盖 reasoning effort (v2.rs:5800). thread/start 不接, 只在 turn/start 这里透传。 */
effort?: ReasoningEffort;
/**
* 覆盖 reasoning summary 策略 (v2.rs:5801-5803). 我们恒传 'auto', 让
* reasoning summary 文本一定出现 — 不依赖用户 ~/.codex/config.toml 里
* 写没写 model_reasoning_summary。设 'none' 会让 OpenAI 不返摘要文本。
*/
summary?: ReasoningSummary;
cwd?: string;
approvalPolicy?: AskForApproval;
/** Route interactive approvals to the user or Codex's built-in reviewer. */
approvalsReviewer?: ApprovalsReviewer;
/** Named permission profile from thread config (mutually exclusive with sandboxPolicy). */
permissions?: string;
/** Fast mode override. Undefined = 不覆盖; null = 清空/standard; 'fast' = Fast mode. */
serviceTier?: ServiceTier | null;
/**
* **关键**: turn/start 用的是 `sandboxPolicy: SandboxPolicy` (复杂 tag union),
* **不是** thread/start 那套简单 `sandbox: SandboxMode` (kebab-case enum)。
* 字段名 + 类型都不一样, 写错 server 直接忽略 → mid-session 切 mode 不生效。
* 见 v2.rs:5778 + 1886 (SandboxPolicy 定义)。
*/
sandboxPolicy?: SandboxPolicy;
/**
* EXPERIMENTAL 计划模式 (collaboration mode)。sticky 语义 — 对本 turn 及后续
* turn 生效, 退出计划模式后必须显式发 mode:'default' 复位。见 CollaborationModeParam。
*/
collaborationMode?: CollaborationModeParam;
[k: string]: unknown;
}
export interface TurnStartResponse {
turn: { id: string; [k: string]: unknown };
/** 当前 Codex schema 未返回;保留防御字段,若上游补齐可直接读取并校准本地状态。 */
serviceTier?: ServiceTier | null;
[k: string]: unknown;
}
export interface TurnSteerParams {
threadId: string;
input: UserInput[];
/**
* app-server 要求客户端带上当前 active turn id。这个字段是 stale-client 防线:
* renderer/main 可能还以为 turn 在跑,但 server 已经完成;没有 expectedTurnId
* 会把这种竞态伪装成成功插话,造成队列消息丢失或 UI 状态错乱。
*/
expectedTurnId: string;
[k: string]: unknown;
}
export interface TurnSteerResponse {
turnId: string;
[k: string]: unknown;
}
export interface TurnInterruptParams {
threadId: string;
turnId: string;
}
export type TurnInterruptResponse = Record<string, unknown>;
// ── ThreadResume / ThreadFork / ThreadRollback (Phase 3) ─────────────────────
export interface ThreadResumeParams {
threadId: string;
/** 可选覆盖, 缺省继承 thread 原有配置。 */
model?: string;
/** 同 ThreadStartParams.modelProvider —— resume 也接受 provider 覆盖(v2.rs ThreadResumeParams)。 */
modelProvider?: string;
cwd?: string;
/** EXPERIMENTAL. Runtime-visible workspace roots; replaces the resumed thread's roots. */
runtimeWorkspaceRoots?: string[];
approvalPolicy?: AskForApproval;
/** Route interactive approvals to the user or Codex's built-in reviewer. */
approvalsReviewer?: ApprovalsReviewer;
/** Named permission profile from config (mutually exclusive with sandbox). */
permissions?: string;
sandbox?: SandboxMode;
/** Per-request config overrides, including named permission profile definitions. */
config?: Record<string, unknown>;
/** Fast mode override. Undefined = 不覆盖; null = 清空/standard; 'fast' = Fast mode. */
serviceTier?: ServiceTier | null;
/**
* 在 codex 默认 base 之后追加 developer message。thread/resume 支持该字段,
* 用于重启后恢复 host 产品级 prompt。
*/
developerInstructions?: string;
/**
* 只恢复 thread 元数据与 live state,不把完整历史塞进单条 NDJSON response。
* 历史展示由 Cindy 自己的会话数据负责。
*/
excludeTurns?: boolean;
[k: string]: unknown;
}
export interface ThreadResumeResponse {
thread: { id: string; [k: string]: unknown };
model: string;
modelProvider: string;
cwd: string;
runtimeWorkspaceRoots?: string[];
activePermissionProfile?: { id: string; extends?: string | null };
approvalPolicy: AskForApproval;
sandbox: SandboxPolicy;
serviceTier?: ServiceTier | null;
[k: string]: unknown;
}
/**
* v2.rs SandboxPolicy (line 1886): `#[serde(tag = "type", rename_all = "camelCase")]`,
* 各结构变体内部字段也是 `#[serde(rename_all = "camelCase")]` + `#[serde(default)]`
* 所以可以全部省略, 走 server 默认值。
*
* - dangerFullAccess: 无 sandbox, 任何 write OK
* - readOnly: 只读, networkAccess 默认 false
* - workspaceWrite: workspace 内可写, networkAccess 默认 false
* - externalSandbox: 外部 sandbox 接管 (我们不用)
*/
export type SandboxPolicy =
| { type: 'dangerFullAccess' }
| { type: 'readOnly'; networkAccess?: boolean }
| {
type: 'workspaceWrite';
writableRoots?: string[];
networkAccess?: boolean;
excludeTmpdirEnvVar?: boolean;
excludeSlashTmp?: boolean;
}
| { type: 'externalSandbox'; networkAccess?: 'restricted' | 'enabled' };
export interface ThreadForkParams {
threadId: string;
/** Fork the source thread at this provider-native turn boundary. */
lastTurnId?: string;
/** 可选: 从特定 rollout path fork (绝大多数场景用 threadId)。 */
path?: string;
/** Legacy fork + rollback path only; lastTurnId precision path omits it. */
persistExtendedHistory?: boolean;
model?: string;
cwd?: string;
/** EXPERIMENTAL. Runtime-visible workspace roots for the forked thread. */
runtimeWorkspaceRoots?: string[];
approvalPolicy?: AskForApproval;
/** Route interactive approvals to the user or Codex's built-in reviewer. */
approvalsReviewer?: ApprovalsReviewer;
/** Named permission profile from config (mutually exclusive with sandbox). */
permissions?: string;
sandbox?: SandboxMode;
/** Per-request config overrides, including named permission profile definitions. */
config?: Record<string, unknown>;
/**
* 只返回 thread 元数据与 live fork state,不把完整历史塞进单条 NDJSON response。
* 与 thread/resume.excludeTurns 同族;超长历史 thread 的 fork 响应体与历史成
* 正比、无上界,曾实测单行 31MiB 超过 client maxLineBytes(16MiB)熔断整条连接。
*/
excludeTurns?: boolean;
[k: string]: unknown;
}
export interface ThreadForkResponse {
thread: { id: string; [k: string]: unknown };
model: string;
modelProvider: string;
[k: string]: unknown;
}
export interface ThreadRollbackParams {
threadId: string;
/** 从 thread 尾部回滚多少个完整 turn。 */
numTurns: number;
}
/** Codex 0.153.4: bounded turn metadata, including failed/interrupted turns. */
export interface ThreadTurnsListParams {
threadId: string;
cursor?: string;
limit: number;
sortDirection: 'desc';
itemsView: 'notLoaded';
}
export interface ThreadTurnsListResponse {
data: Array<{ id: string; status: string; startedAt?: number | null }>;
nextCursor: string | null;
}
export interface ThreadRollbackResponse {
thread: { id: string; [k: string]: unknown };
[k: string]: unknown;
}
/** Release the app-server's live state for a thread without archiving its history. */
export interface ThreadUnsubscribeParams {
threadId: string;
}
export type ThreadUnsubscribeStatus = 'notLoaded' | 'notSubscribed' | 'unsubscribed';
export interface ThreadUnsubscribeResponse {
status: ThreadUnsubscribeStatus;
}
// ── ThreadSettingsUpdate (v2.rs ThreadSettingsUpdateParams) ──────────────────
// 会话中途单独推 model / serviceTier / effort 等设置, server 写入后续 turn 的
// sticky context (不必等下一个 turn/start 携带)。需要 experimentalApi capability
// (host.ts 已恒开)。响应仅是 ack, 真正状态经 thread/settings/updated 通知回带。
// **只镜像我们会发的字段** — 上游 params 还有 approvalPolicy / approvalsReviewer /
// sandboxPolicy /
// personality / collaborationMode 等, 用到再加, 保持最小协议面。
export interface ThreadSettingsUpdateParams {
threadId: string;
/** 覆盖后续 turn 的 model。省略 = 不变。 */
model?: string;
/** Route subsequent interactive approvals to the user or built-in reviewer. */
approvalsReviewer?: ApprovalsReviewer;
/**
* Fast mode override (双 Option 语义): 省略字段 = 不变; `null` = 清空/standard;
* 'fast' = Fast mode。发送侧必须用 `...(v !== undefined ? { serviceTier: v } : {})`
* 才能区分"省略"与"显式 null", 否则 null 会被当成不变。
*/
serviceTier?: ServiceTier | null;
/** 覆盖后续 turn 的 reasoning effort。省略 = 不变。 */
effort?: ReasoningEffort;
}
/** thread/settings/update 仅返回 ack, 不消费。 */
export type ThreadSettingsUpdateResponse = Record<string, unknown>;
/**
* thread/settings/updated 通知回带的 server 权威设置快照 (v2.rs ThreadSettings)。
* 只列我们消费的字段, 其余用索引签名兜底防 schema 漂移。serviceTier 在 server 端
* 是裸 string (可能回 'priority'), 由 normalizeServiceTier 归一回 'fast'。
*/
export interface ThreadSettings {
serviceTier?: ServiceTier | null;
model?: string;
effort?: ReasoningEffort | null;
[k: string]: unknown;
}
export interface ThreadSettingsUpdatedNotification {
method: 'thread/settings/updated';
params: {
threadId: string;
threadSettings: ThreadSettings;
};
}
// ── SkillsList (v2.rs) ──────────────────────────────────────────────────────
export interface SkillsListParams {
cwds?: string[];
forceReload?: boolean;
perCwdExtraUserRoots?: Array<{ cwd: string; extraUserRoots: string[] }> | null;
}
export type SkillScope = 'user' | 'repo' | 'system' | 'admin';
export interface SkillInterface {
displayName?: string;
shortDescription?: string;
iconSmall?: string;
iconLarge?: string;
brandColor?: string;
defaultPrompt?: string;
}
export interface SkillDependencies {
tools: Array<{
type: string;
value: string;
description?: string;
transport?: string;
command?: string;
url?: string;
}>;
}
export interface SkillMetadata {
name: string;
description: string;
shortDescription?: string;
interface?: SkillInterface;
dependencies?: SkillDependencies;
path: string;
scope: SkillScope;
enabled: boolean;
}
export interface SkillErrorInfo {
path: string;
message: string;
}
export interface SkillsListEntry {
cwd: string;
skills: SkillMetadata[];
errors: SkillErrorInfo[];
}
export interface SkillsListResponse {
data: SkillsListEntry[];
}
// ── ServerRequest: Approval (Phase 2) ────────────────────────────────────────
//
// 入站 ServerRequest, 我们必须 setRequestHandler 接住并回 response, 否则 server 卡 turn。
// v2.rs 字段 (camelCase serde):
// - CommandExecution: { threadId, turnId, itemId, approvalId?, reason?, command?, cwd?, ... }
// - FileChange: { threadId, turnId, itemId, reason?, grantRoot? }
export interface CommandExecutionRequestApprovalParams {
threadId: string;
turnId: string;
itemId: string;
/** zsh-exec-bridge 子命令场景, 一个 itemId 可能有多个 callback, 用此 id 区分; 普通 shell 是 null。 */
approvalId?: string | null;
reason?: string | null;
command?: string | null;
cwd?: string | null;
availableDecisions?: unknown[] | null;
[k: string]: unknown;
}
export interface FileChangeRequestApprovalParams {
threadId: string;
turnId: string;
itemId: string;
reason?: string | null;
/** [UNSTABLE] server 要求允许向某根目录写入。 */
grantRoot?: string | null;
[k: string]: unknown;
}
/**
* v2.rs CommandExecutionApprovalDecision (camelCase serde):
* accept | acceptForSession | decline | cancel
* (acceptWithExecpolicyAmendment / applyNetworkPolicyAmendment 是结构变体, 我们不实现)
*
* v2.rs FileChangeApprovalDecision:
* accept | acceptForSession | decline | cancel
*
* Phase 2 我们只发 accept/decline/cancel; acceptForSession 留 Phase 5+ ("Allow for session" 按钮)。
*/
export type ApprovalDecision = 'accept' | 'acceptForSession' | 'decline' | 'cancel';
export interface CommandExecutionRequestApprovalResponse {
decision: ApprovalDecision;
}
export interface FileChangeRequestApprovalResponse {
decision: ApprovalDecision;
}
export type McpServerElicitationAction = 'accept' | 'decline' | 'cancel';
export type McpServerElicitationRequestParams = {
threadId: string;
turnId: string | null;
serverName: string;
} & (
| {
mode: 'form';
_meta: unknown | null;
message: string;
requestedSchema: unknown;
}
| {
mode: 'url';
_meta: unknown | null;
message: string;
url: string;
elicitationId: string;
}
);
export interface McpServerElicitationRequestResponse {
action: McpServerElicitationAction;
content: unknown | null;
_meta: unknown | null;
}
// ── ServerRequest: Permissions Approval (MCP 工具等权限请求) ─────────────────
//
// Codex v2 新增 — item/permissions/requestApproval。
// 与 command/fileChange 不同: response 不是 { decision } 而是 { permissions, scope }。
// permissions 为空对象 = 拒绝; 非空 = 批准 (scope 决定粒度)。
export interface PermissionsRequestApprovalParams {
threadId: string;
turnId: string;
itemId?: string | null;
reason?: string | null;
/** 请求的权限列表 — 原样透传给 UI,批准时原样回传给 server。 */
permissions: unknown;
[k: string]: unknown;
}
export type PermissionsApprovalScope = 'turn' | 'session';
export interface PermissionsRequestApprovalResponse {
permissions: Record<string, unknown> | unknown;
scope: PermissionsApprovalScope;
}
// ── ServerRequest: User input + dynamic tools (experimental, Codex 0.135.0) ──
//
// Generated schema source:
// codex app-server generate-ts --experimental
// - method: item/tool/requestUserInput
// - params: ToolRequestUserInputParams
// - response: ToolRequestUserInputResponse
// - notification: serverRequest/resolved
export interface ToolRequestUserInputOption {
label: string;
description: string;
}
export interface ToolRequestUserInputQuestion {
id: string;
header: string;
question: string;
isOther: boolean;
isSecret: boolean;
options: ToolRequestUserInputOption[] | null;
}
export interface ToolRequestUserInputParams {
threadId: string;
turnId: string;
itemId: string;
questions: ToolRequestUserInputQuestion[];
}
export interface ToolRequestUserInputAnswer {
answers: string[];
}
export interface ToolRequestUserInputResponse {
answers: Record<string, ToolRequestUserInputAnswer | undefined>;
}
export interface ServerRequestResolvedNotification {
method: 'serverRequest/resolved';
params: {
threadId: string;
requestId: JsonRpcId;
};
}
export interface DynamicToolSpec {
/** Current canonical app-server format for top-level dynamic tools. */
type: 'function';
name: string;
description: string;
inputSchema: unknown;
deferLoading?: boolean;
}
export type DynamicToolCallOutputContentItem =
| { type: 'inputText'; text: string }
| { type: 'inputImage'; imageUrl: string };
export interface DynamicToolCallParams {
threadId: string;
turnId: string;
callId: string;
namespace: string | null;
tool: string;
arguments: unknown;
}
export interface DynamicToolCallResponse {
contentItems: DynamicToolCallOutputContentItem[];
success: boolean;
}
// ── Notification 联合 (Phase 1: 7 类) ────────────────────────────────────────
//
// 方法名作 discriminator。**绝大多数** notification 的 params 都带顶层 threadId,
// 但 thread/started 是例外 — threadId 在嵌套的 params.thread.id 里。
// AppServerHost 路由要 special-case 它 (见 host.ts extractThreadId)。
/**
* v2.rs ThreadStartedNotification: pub thread: Thread (无顶层 thread_id)。
* Host 端从 params.thread.id 取 threadId。
*/
export interface ThreadStartedNotification {
method: 'thread/started';
params: {
thread: {
id: string;
parentThreadId?: string | null;
[k: string]: unknown;
};
[k: string]: unknown;
};
}
export interface TurnStartedNotification {
method: 'turn/started';
params: { threadId: string; turn: { id: string; [k: string]: unknown }; [k: string]: unknown };
}
export interface TurnDiffUpdatedNotification {
method: 'turn/diff/updated';
params: { threadId: string; turnId: string; diff: string; [k: string]: unknown };
}
/**
* v2.rs TurnCompletedNotification: { thread_id, turn: Turn }
* Turn 包含 status (TurnStatus enum: completed/interrupted/failed/inProgress)
* + 可选 error (TurnError)。**注意**: usage 不在 Turn 上, 走单独的
* thread/tokenUsage/updated notification (translator 那边把两个事件归到一个 turn 处理)。
*/
export type TurnStatus = 'completed' | 'interrupted' | 'failed' | 'inProgress';
/**
* v2.rs CodexErrorInfo — codex 把内部 `CodexErr` 变体翻成 camelCase 暴露出来的
* **结构化** 错误标识。schema 正本:
* `codex-rs/app-server-protocol/schema/json/v2/ErrorNotification.json`。
*
* 为什么要用它: 同一个语义错误的 `message` 是 codex 侧硬编码的**用户可见文案**
* (`CodexErr::ServerOverloaded` 的文案是 "Selected model is at capacity. Please
* try a different model.", 见 codex-rs/protocol/src/error.rs 那个变体上的
* `#[error(...)]`)。那是给人看的提示语、不是 API 契约, codex 改一次措辞、所有
* 靠文案匹配的判定就一起静默失效。本字段是 schema 承诺的稳定契约。
*
* 形态有两种: 纯枚举变体在 wire 上就是**字符串**; 只有携带 `httpStatusCode` /
* `turnKind` 的那几个是单键对象。取 tag 统一走 `codexErrorInfoTag()`。
*/
export type CodexErrorInfo =
| 'contextWindowExceeded'
| 'sessionBudgetExceeded'
| 'usageLimitExceeded'
/** 上游临时过载: HTTP 503 + `server_is_overloaded` / `slow_down`。 */
| 'serverOverloaded'
| 'cyberPolicy'
| 'internalServerError'
| 'unauthorized'
| 'badRequest'
| 'threadRollbackFailed'
| 'sandboxError'
| 'other'
| { httpConnectionFailed: { httpStatusCode?: number | null } }
| { responseStreamConnectionFailed: { httpStatusCode?: number | null } }
| { responseStreamDisconnected: { httpStatusCode?: number | null } }
| { responseTooManyFailedAttempts: { httpStatusCode?: number | null } }
| { activeTurnNotSteerable: { turnKind?: unknown } };
/**
* `CodexErrorInfo` 的判别 tag。字符串变体原样返回; 单键对象取那个唯一的键。
*
* 形状不认识时返回 `undefined` 而**不是**猜一个: 上游新增变体、或某天把单键对象
* 改成多键结构时, 宁可退回文案兜底, 也不要把它误判成某个已知 tag 去驱动重试。
*/
export function codexErrorInfoTag(info: CodexErrorInfo | null | undefined): string | undefined {
if (typeof info === 'string') return info;
if (info && typeof info === 'object' && !Array.isArray(info)) {
const keys = Object.keys(info);
return keys.length === 1 ? keys[0] : undefined;
}
return undefined;
}
export interface TurnError {
message: string;
/**
* 原类型写的 `{ [k: string]: unknown } | null` 接不住实际值 —— 纯枚举变体在
* wire 上是字符串。这个字段此前没被任何判定消费, 所以类型不准一直没暴露。
*/
codexErrorInfo?: CodexErrorInfo | null;
additionalDetails?: string | null;
}
export interface TurnCompletedNotification {
method: 'turn/completed';
params: {
threadId: string;
turn: {
id: string;
status: TurnStatus;
error?: TurnError | null;
startedAt?: number | null;
completedAt?: number | null;
durationMs?: number | null;
items?: unknown[];
[k: string]: unknown;
};
};
}
/**
* v2.rs ThreadTokenUsageUpdatedNotification: { thread_id, turn_id, token_usage: ThreadTokenUsage }
* - total: 整个 thread 累计 (我们用它当 cumulative snapshot)
* - last: 上次 turn 的增量 (我们用它给 usage tracker ingestApiCallUsage)
*/
export interface TokenUsageBreakdown {
totalTokens: number;
inputTokens: number;
cachedInputTokens: number;
/** Present in Codex 0.153.0; older app-server versions omit this subset. */
cacheWriteInputTokens?: number;
outputTokens: number;
reasoningOutputTokens: number;
}
export interface ThreadTokenUsageUpdatedNotification {
method: 'thread/tokenUsage/updated';
params: {
threadId: string;
turnId: string;
tokenUsage: {
total: TokenUsageBreakdown;
last: TokenUsageBreakdown;
modelContextWindow?: number | null;
};
};
}
/**
* item.* 的 type / 内部字段 translator 那边按 discriminator narrow,
* 这里只保证 envelope shape。
*/
export interface ItemStartedNotification {
method: 'item/started';
params: { threadId: string; turnId: string; item: ItemEnvelope; startedAtMs?: number };
}
export interface ItemUpdatedNotification {
method: 'item/updated';
params: { threadId: string; turnId: string; item: ItemEnvelope };
}
export interface ItemCompletedNotification {
method: 'item/completed';
params: { threadId: string; turnId: string; item: ItemEnvelope; completedAtMs?: number };
}
/**
* v2 AgentMessageDeltaNotification:
* { thread_id, turn_id, item_id, delta }
*
* 正文的专用增量流。item/updated 仍作为旧版 / 异常上游的全文快照兜底,
* item/completed 负责最终全文校准。
*/
export interface AgentMessageDeltaNotification {
method: 'item/agentMessage/delta';
params: { threadId: string; turnId: string; itemId: string; delta: string };
}
export type PlanEntryStatus = 'pending' | 'in_progress' | 'completed';
export interface PlanEntry {
step: string;
status: PlanEntryStatus;
}
/**
* turn/plan/updated — Codex native plan/todo updates produced by update_plan.
*
* App-server README documents params as { turnId, explanation?, plan }; newer
* protocol revisions also carry threadId so clients can route per thread.
*/
export interface TurnPlanUpdatedNotification {
method: 'turn/plan/updated';
params: {
threadId?: string;
turnId: string;
explanation?: string | null;
plan: PlanEntry[];
};
}
/**
* v2.rs ReasoningSummaryTextDeltaNotification (line 7234-7241):
* { thread_id, turn_id, item_id, delta, summary_index }
*
* 一次 turn 内 OpenAI reasoning summary 是分段的 (Vec<String>), 每个 part 通过
* SummaryPartAdded 开启, 后续 SummaryTextDelta 携带该 part 的文本增量。
* summaryIndex 标识当前 part 的下标 (0-based)。
*/
export interface ReasoningSummaryTextDeltaNotification {
method: 'item/reasoning/summaryTextDelta';
params: { threadId: string; turnId: string; itemId: string; delta: string; summaryIndex: number };
}
/**
* v2.rs ReasoningSummaryPartAddedNotification (line 7246-7252):
* { thread_id, turn_id, item_id, summary_index }
*
* summary 数组开新一段时发, 没有 delta 文本; 用来在多段 summary 之间插分隔 ('\n\n')。
*/
export interface ReasoningSummaryPartAddedNotification {
method: 'item/reasoning/summaryPartAdded';
params: { threadId: string; turnId: string; itemId: string; summaryIndex: number };
}
/**
* v2.rs ReasoningTextDeltaNotification (line 7257-7264):
* { thread_id, turn_id, item_id, delta, content_index }
*
* 原始内部 reasoning (raw_content) 的增量, OpenAI 通常不返 (只返 summary), 开源 /
* self-hosted 模型才填。我们一并接通 — 没的话 server 不会推, 不浪费。
*/
export interface ReasoningTextDeltaNotification {
method: 'item/reasoning/textDelta';
params: { threadId: string; turnId: string; itemId: string; delta: string; contentIndex: number };
}
/**
* v2.rs AccountRateLimitsUpdatedNotification (line 8120-8125):
* { rate_limits: RateLimitSnapshot }
*
* **账号级 notification, 没有 threadId / turnId** — codex_protocol::protocol::RateLimitSnapshot
* (protocol/src/protocol.rs:2129-2173). server 在每 turn 完后推, 反映 ChatGPT 账号当前
* 各滚动限额窗口的配额占用。窗口构成完全以服务端下发为准, 消费侧不得假设固定窗口
* (OpenAI 会调整策略:典型是 5h + weekly 双窗, 2026-07 曾一度取消 5h, 且可能随时恢复)。
*
* host 端走全局 fan-out 路径 (无 threadId 不能走 routeNotification 的 per-thread 分发),
* 所有 active subscriber 各收到一份 — 账号级数据天然跨 session 共享。
*/
export type RateLimitWindow = AccountRateLimitWindow;
export type CreditsSnapshot = AccountCreditsSnapshot;
export type RateLimitSnapshot = AccountRateLimitSnapshot;
export interface AccountRateLimitsUpdatedNotification {
method: 'account/rateLimits/updated';
params: { rateLimits: RateLimitSnapshot };
}
/**
* v2.rs ThreadStatus (line 4611) — 线程级粗粒度运行状态。
*
* #[serde(tag = "type", rename_all = "camelCase")]
* enum ThreadStatus { NotLoaded, Idle, SystemError, Active { active_flags: Vec<ThreadActiveFlag> } }
*
* Active 是"在跑"的总称, 具体跑啥(reasoning / agentMessage / 工具)不在这条事件里 —
* 那些走 item.* 流。这里只关心 active_flags 的两类"等用户"信号。
*/
export type ThreadActiveFlag = 'waitingOnApproval' | 'waitingOnUserInput';
export type ThreadStatus =
| { type: 'notLoaded' }
| { type: 'idle' }
| { type: 'systemError' }
| { type: 'active'; activeFlags: ThreadActiveFlag[] };
/**
* v2.rs ThreadStatusChangedNotification (line 6961) — 线程状态机广播。
*
* server 端 ThreadWatchManager 在 turn 起/落、approval 请求起/落、user_input 请求起/落、
* system_error、shutdown 时发。turn lifecycle 我们已从 turn/started+turn/completed 自己
* 拼了 'Done' / isRunning, 不重复消费; 唯一新增语义 = active_flags 里的两类等待标志。
*/
export interface ThreadStatusChangedNotification {
method: 'thread/status/changed';
params: { threadId: string; status: ThreadStatus };
}
/**
* v2.rs ErrorNotification:
* pub error: TurnError, pub will_retry: bool, pub thread_id: String, pub turn_id: String
* willRetry=true 时 server 会自动重试, 不应当中断 turn (translator 可降级为 warn)。
*/
export interface ErrorNotification {
method: 'error';
params: {
threadId: string;
turnId: string;
willRetry: boolean;
/** Host-synthesized transport failures are session lifecycle errors, not turn-scoped SDK errors. */
scope?: 'turn' | 'transport';
/**
* 形状同 `TurnError`, 但 `message` 保持 optional —— host 合成的 transport 失败
* 走同一个 shape 且不保证带文案, 收紧成 required 会破坏那些构造点。
*/
error: { message?: string; codexErrorInfo?: CodexErrorInfo | null; [k: string]: unknown };
[k: string]: unknown;
};
}
/** Codex 0.144.x automatic Guardian approval review lifecycle. */
export type GuardianApprovalReviewStatus =
| 'inProgress'
| 'approved'
| 'denied'
| 'timedOut'
| 'aborted';
export type GuardianRiskLevel = 'low' | 'medium' | 'high' | 'critical';
export type GuardianUserAuthorization = 'unknown' | 'low' | 'medium' | 'high';
export type GuardianCommandSource = 'shell' | 'unifiedExec';
export type GuardianNetworkProtocol = string;
/** The action shape emitted by item/autoApprovalReview/* notifications. */
export type GuardianApprovalReviewAction =
| { type: 'command'; source: GuardianCommandSource; command: string; cwd: string }
| { type: 'execve'; source: GuardianCommandSource; program: string; argv: string[]; cwd: string }
| { type: 'applyPatch'; cwd: string; files: string[] }
| { type: 'networkAccess'; target: string; host: string; protocol: GuardianNetworkProtocol; port: number }
| {
type: 'mcpToolCall';
server: string;
toolName: string;
connectorId: string | null;
connectorName: string | null;
toolTitle: string | null;
}
| { type: 'requestPermissions'; reason: string | null; permissions: Record<string, unknown> };
export interface GuardianApprovalReview {
status: GuardianApprovalReviewStatus;
riskLevel: GuardianRiskLevel | null;
userAuthorization: GuardianUserAuthorization | null;
rationale: string | null;
}
export interface ItemGuardianApprovalReviewStartedNotification {
threadId: string;
turnId: string;
startedAtMs: number;
reviewId: string;
targetItemId: string | null;
review: GuardianApprovalReview;
action: GuardianApprovalReviewAction;
}
export interface ItemGuardianApprovalReviewCompletedNotification {
threadId: string;
turnId: string;
startedAtMs: number;
completedAtMs: number;
reviewId: string;
targetItemId: string | null;
decisionSource: 'agent';
review: GuardianApprovalReview;
action: GuardianApprovalReviewAction;
}
export interface GuardianWarningNotification {
threadId: string;
message: string;
}
/** JSON-RPC envelopes for the Guardian notification params above. */
export interface ItemGuardianApprovalReviewStartedServerNotification {
method: 'item/autoApprovalReview/started';
params: ItemGuardianApprovalReviewStartedNotification;
}
export interface ItemGuardianApprovalReviewCompletedServerNotification {
method: 'item/autoApprovalReview/completed';
params: ItemGuardianApprovalReviewCompletedNotification;
}
export interface GuardianWarningServerNotification {
method: 'guardianWarning';
params: GuardianWarningNotification;
}
/** User-facing warning (v2 WarningNotification); threadId is set when it targets a thread. */
export interface WarningNotification {
method: 'warning';
params: { message: string; threadId?: string | null };
}
/**
* v2 ThreadItem 的 envelope — 至少有 id / type, 余字段按 type narrow。
* 完整 union 在 v2.rs ThreadItem (太大, 不在 Phase 1 全列)。translator 用
* type as discriminator + 字段守卫。
*/
export interface ItemEnvelope {
id: string;
type: string;
[k: string]: unknown;
}
export type ServerNotification =
| ThreadStartedNotification
| TurnStartedNotification
| TurnDiffUpdatedNotification
| TurnCompletedNotification
| ThreadTokenUsageUpdatedNotification
| ItemStartedNotification
| ItemUpdatedNotification
| ItemCompletedNotification
| AgentMessageDeltaNotification
| ReasoningSummaryTextDeltaNotification
| ReasoningSummaryPartAddedNotification
| ReasoningTextDeltaNotification
| AccountRateLimitsUpdatedNotification
| ThreadStatusChangedNotification
| ThreadSettingsUpdatedNotification
| ServerRequestResolvedNotification
| ItemGuardianApprovalReviewStartedServerNotification
| ItemGuardianApprovalReviewCompletedServerNotification
| GuardianWarningServerNotification
| WarningNotification
| ErrorNotification;
// ── 方法名常量 (避免 string typo) ────────────────────────────────────────────
export const Method = {
Initialize: 'initialize',
ModelList: 'model/list',
McpServerStatusList: 'mcpServerStatus/list',
SkillsList: 'skills/list',
ThreadStart: 'thread/start',
ThreadResume: 'thread/resume',
ThreadInjectItems: 'thread/inject_items',
ThreadFork: 'thread/fork',
ThreadRollback: 'thread/rollback',
ThreadTurnsList: 'thread/turns/list',
ThreadUnsubscribe: 'thread/unsubscribe',
ThreadSettingsUpdate: 'thread/settings/update',
TurnStart: 'turn/start',
TurnSteer: 'turn/steer',
TurnInterrupt: 'turn/interrupt',
AccountRateLimitsRead: 'account/rateLimits/read',
AccountRateLimitResetCreditConsume: 'account/rateLimitResetCredit/consume',
// Memory (实验性, experimentalApi 必须 true 才能用):
// app-server/README.md:202-203 + 155
ConfigRead: 'config/read',
/** EXPERIMENTAL. Register a remote exec-server as a named environment. */
EnvironmentAdd: 'environment/add',
/** EXPERIMENTAL. Read a named environment's status without starting or recovering it. */
EnvironmentStatus: 'environment/status',
ExperimentalFeatureList: 'experimentalFeature/list',
ExperimentalFeatureEnablementSet: 'experimentalFeature/enablement/set',
MemoryReset: 'memory/reset',
// ServerRequest (Phase 2 + permissions):
CommandExecutionRequestApproval: 'item/commandExecution/requestApproval',
FileChangeRequestApproval: 'item/fileChange/requestApproval',
McpServerElicitationRequest: 'mcpServer/elicitation/request',
PermissionsRequestApproval: 'item/permissions/requestApproval',
ToolRequestUserInput: 'item/tool/requestUserInput',
DynamicToolCall: 'item/tool/call',
ItemGuardianApprovalReviewStarted: 'item/autoApprovalReview/started',
ItemGuardianApprovalReviewCompleted: 'item/autoApprovalReview/completed',
GuardianWarning: 'guardianWarning',
} as const;
export type {
AccountRateLimitsResponse,
ConsumeAccountRateLimitResetCreditParams,
ConsumeAccountRateLimitResetCreditResponse,
};