codex_codes/
protocol.rs

1//! App-server protocol types for the Codex CLI.
2//!
3//! Every wire type is generated from the upstream JSON Schema bundle by
4//! `scripts/codegen_protocol.py` and lives in [`crate::protocol_generated::types`].
5//! This module re-exports them and adds the JSON-RPC method-name constants
6//! the dispatch layer matches against.
7//!
8//! # Parsing notifications
9//!
10//! Prefer the typed dispatch in [`crate::messages`] over manual `method` checks:
11//!
12//! ```
13//! use codex_codes::{Notification, ServerMessage};
14//!
15//! fn handle(msg: ServerMessage) {
16//!     if let ServerMessage::Notification(Notification::TurnCompleted(c)) = msg {
17//!         println!("Turn on thread {} completed", c.thread_id);
18//!     }
19//! }
20//! ```
21
22pub use crate::protocol_generated::types::*;
23
24/// JSON-RPC method names used by the app-server protocol.
25///
26/// Use these constants when matching on [`crate::ServerMessage::Notification`] or
27/// [`crate::ServerMessage::Request`] method fields to avoid typos.
28pub mod methods {
29    // Client → server requests
30    pub const INITIALIZE: &str = "initialize";
31    pub const INITIALIZED: &str = "initialized";
32    pub const THREAD_START: &str = "thread/start";
33    pub const THREAD_ARCHIVE: &str = "thread/archive";
34    pub const TURN_START: &str = "turn/start";
35    pub const TURN_INTERRUPT: &str = "turn/interrupt";
36    pub const TURN_STEER: &str = "turn/steer";
37    pub const THREAD_RESUME: &str = "thread/resume";
38    pub const THREAD_FORK: &str = "thread/fork";
39    pub const THREAD_UNSUBSCRIBE: &str = "thread/unsubscribe";
40    pub const THREAD_NAME_SET: &str = "thread/name/set";
41    pub const THREAD_METADATA_UPDATE: &str = "thread/metadata/update";
42    pub const THREAD_UNARCHIVE: &str = "thread/unarchive";
43    pub const THREAD_COMPACT_START: &str = "thread/compact/start";
44    pub const THREAD_SHELLCOMMAND: &str = "thread/shellCommand";
45    pub const THREAD_APPROVEGUARDIANDENIEDACTION: &str = "thread/approveGuardianDeniedAction";
46    pub const THREAD_ROLLBACK: &str = "thread/rollback";
47    pub const THREAD_LIST: &str = "thread/list";
48    pub const THREAD_LOADED_LIST: &str = "thread/loaded/list";
49    pub const THREAD_READ: &str = "thread/read";
50    pub const THREAD_INJECT_ITEMS: &str = "thread/inject_items";
51    pub const SKILLS_LIST: &str = "skills/list";
52    pub const HOOKS_LIST: &str = "hooks/list";
53    pub const MARKETPLACE_ADD: &str = "marketplace/add";
54    pub const MARKETPLACE_REMOVE: &str = "marketplace/remove";
55    pub const MARKETPLACE_UPGRADE: &str = "marketplace/upgrade";
56    pub const PLUGIN_LIST: &str = "plugin/list";
57    pub const PLUGIN_READ: &str = "plugin/read";
58    pub const PLUGIN_SKILL_READ: &str = "plugin/skill/read";
59    pub const PLUGIN_SHARE_SAVE: &str = "plugin/share/save";
60    pub const PLUGIN_SHARE_UPDATETARGETS: &str = "plugin/share/updateTargets";
61    pub const PLUGIN_SHARE_LIST: &str = "plugin/share/list";
62    pub const PLUGIN_SHARE_CHECKOUT: &str = "plugin/share/checkout";
63    pub const PLUGIN_SHARE_DELETE: &str = "plugin/share/delete";
64    pub const APP_LIST: &str = "app/list";
65    pub const FS_READFILE: &str = "fs/readFile";
66    pub const FS_WRITEFILE: &str = "fs/writeFile";
67    pub const FS_CREATEDIRECTORY: &str = "fs/createDirectory";
68    pub const FS_GETMETADATA: &str = "fs/getMetadata";
69    pub const FS_READDIRECTORY: &str = "fs/readDirectory";
70    pub const FS_REMOVE: &str = "fs/remove";
71    pub const FS_COPY: &str = "fs/copy";
72    pub const FS_WATCH: &str = "fs/watch";
73    pub const FS_UNWATCH: &str = "fs/unwatch";
74    pub const SKILLS_CONFIG_WRITE: &str = "skills/config/write";
75    pub const PLUGIN_INSTALL: &str = "plugin/install";
76    pub const PLUGIN_UNINSTALL: &str = "plugin/uninstall";
77    pub const REVIEW_START: &str = "review/start";
78    pub const MODEL_LIST: &str = "model/list";
79    pub const MODELPROVIDER_CAPABILITIES_READ: &str = "modelProvider/capabilities/read";
80    pub const EXPERIMENTALFEATURE_LIST: &str = "experimentalFeature/list";
81    pub const EXPERIMENTALFEATURE_ENABLEMENT_SET: &str = "experimentalFeature/enablement/set";
82    pub const MCPSERVER_OAUTH_LOGIN: &str = "mcpServer/oauth/login";
83    pub const CONFIG_MCPSERVER_RELOAD: &str = "config/mcpServer/reload";
84    pub const MCPSERVERSTATUS_LIST: &str = "mcpServerStatus/list";
85    pub const MCPSERVER_RESOURCE_READ: &str = "mcpServer/resource/read";
86    pub const MCPSERVER_TOOL_CALL: &str = "mcpServer/tool/call";
87    pub const WINDOWSSANDBOX_SETUPSTART: &str = "windowsSandbox/setupStart";
88    pub const WINDOWSSANDBOX_READINESS: &str = "windowsSandbox/readiness";
89    pub const ACCOUNT_LOGIN_START: &str = "account/login/start";
90    pub const ACCOUNT_LOGIN_CANCEL: &str = "account/login/cancel";
91    pub const ACCOUNT_LOGOUT: &str = "account/logout";
92    pub const ACCOUNT_RATELIMITS_READ: &str = "account/rateLimits/read";
93    pub const ACCOUNT_SENDADDCREDITSNUDGEEMAIL: &str = "account/sendAddCreditsNudgeEmail";
94    pub const FEEDBACK_UPLOAD: &str = "feedback/upload";
95    pub const COMMAND_EXEC: &str = "command/exec";
96    pub const COMMAND_EXEC_WRITE: &str = "command/exec/write";
97    pub const COMMAND_EXEC_TERMINATE: &str = "command/exec/terminate";
98    pub const COMMAND_EXEC_RESIZE: &str = "command/exec/resize";
99    pub const CONFIG_READ: &str = "config/read";
100    pub const EXTERNALAGENTCONFIG_DETECT: &str = "externalAgentConfig/detect";
101    pub const EXTERNALAGENTCONFIG_IMPORT: &str = "externalAgentConfig/import";
102    pub const CONFIG_VALUE_WRITE: &str = "config/value/write";
103    pub const CONFIG_BATCHWRITE: &str = "config/batchWrite";
104    pub const CONFIGREQUIREMENTS_READ: &str = "configRequirements/read";
105    pub const ACCOUNT_READ: &str = "account/read";
106    pub const FUZZYFILESEARCH: &str = "fuzzyFileSearch";
107
108    // Server → client notifications
109    pub const THREAD_STARTED: &str = "thread/started";
110    pub const THREAD_STATUS_CHANGED: &str = "thread/status/changed";
111    pub const THREAD_TOKEN_USAGE_UPDATED: &str = "thread/tokenUsage/updated";
112    pub const TURN_STARTED: &str = "turn/started";
113    pub const TURN_COMPLETED: &str = "turn/completed";
114    pub const ITEM_STARTED: &str = "item/started";
115    pub const ITEM_COMPLETED: &str = "item/completed";
116    pub const AGENT_MESSAGE_DELTA: &str = "item/agentMessage/delta";
117    pub const CMD_OUTPUT_DELTA: &str = "item/commandExecution/outputDelta";
118    pub const FILE_CHANGE_OUTPUT_DELTA: &str = "item/fileChange/outputDelta";
119    pub const REASONING_DELTA: &str = "item/reasoning/summaryTextDelta";
120    pub const ERROR: &str = "error";
121    pub const ACCOUNT_RATE_LIMITS_UPDATED: &str = "account/rateLimits/updated";
122    pub const MCP_SERVER_STARTUP_STATUS_UPDATED: &str = "mcpServer/startupStatus/updated";
123    pub const MCP_SERVER_OAUTH_LOGIN_COMPLETED: &str = "mcpServer/oauthLogin/completed";
124    pub const REMOTE_CONTROL_STATUS_CHANGED: &str = "remoteControl/status/changed";
125    pub const FILE_CHANGE_PATCH_UPDATED: &str = "item/fileChange/patchUpdated";
126    pub const PLAN_DELTA: &str = "item/plan/delta";
127    pub const TURN_PLAN_UPDATED: &str = "turn/plan/updated";
128    pub const TURN_DIFF_UPDATED: &str = "turn/diff/updated";
129    pub const REASONING_SUMMARY_PART_ADDED: &str = "item/reasoning/summaryPartAdded";
130    pub const REASONING_TEXT_DELTA: &str = "item/reasoning/textDelta";
131    pub const ACCOUNT_LOGIN_COMPLETED: &str = "account/login/completed";
132    pub const DEPRECATION_NOTICE: &str = "deprecationNotice";
133    pub const GUARDIAN_WARNING: &str = "guardianWarning";
134    pub const WARNING: &str = "warning";
135    pub const THREAD_ARCHIVED: &str = "thread/archived";
136    pub const THREAD_CLOSED: &str = "thread/closed";
137    pub const THREAD_UNARCHIVED: &str = "thread/unarchived";
138    pub const THREAD_GOAL_CLEARED: &str = "thread/goal/cleared";
139    pub const THREAD_NAME_UPDATED: &str = "thread/name/updated";
140    pub const SKILLS_CHANGED: &str = "skills/changed";
141    pub const FS_CHANGED: &str = "fs/changed";
142    pub const CONFIG_WARNING: &str = "configWarning";
143    pub const ACCOUNT_UPDATED: &str = "account/updated";
144    pub const APP_LIST_UPDATED: &str = "app/list/updated";
145    pub const COMMAND_EXEC_OUTPUT_DELTA: &str = "command/exec/outputDelta";
146    pub const EXTERNAL_AGENT_CONFIG_IMPORT_COMPLETED: &str = "externalAgentConfig/import/completed";
147    pub const FUZZY_FILE_SEARCH_SESSION_COMPLETED: &str = "fuzzyFileSearch/sessionCompleted";
148    pub const FUZZY_FILE_SEARCH_SESSION_UPDATED: &str = "fuzzyFileSearch/sessionUpdated";
149    pub const HOOK_COMPLETED: &str = "hook/completed";
150    pub const HOOK_STARTED: &str = "hook/started";
151    pub const ITEM_AUTO_APPROVAL_REVIEW_COMPLETED: &str = "item/autoApprovalReview/completed";
152    pub const ITEM_AUTO_APPROVAL_REVIEW_STARTED: &str = "item/autoApprovalReview/started";
153    pub const ITEM_COMMAND_EXEC_TERMINAL_INTERACTION: &str =
154        "item/commandExecution/terminalInteraction";
155    pub const ITEM_MCP_TOOL_CALL_PROGRESS: &str = "item/mcpToolCall/progress";
156    pub const MODEL_REROUTED: &str = "model/rerouted";
157    pub const MODEL_VERIFICATION: &str = "model/verification";
158    pub const PROCESS_EXITED: &str = "process/exited";
159    pub const PROCESS_OUTPUT_DELTA: &str = "process/outputDelta";
160    pub const SERVER_REQUEST_RESOLVED: &str = "serverRequest/resolved";
161    pub const THREAD_COMPACTED: &str = "thread/compacted";
162    pub const THREAD_GOAL_UPDATED: &str = "thread/goal/updated";
163    pub const THREAD_REALTIME_CLOSED: &str = "thread/realtime/closed";
164    pub const THREAD_REALTIME_ERROR: &str = "thread/realtime/error";
165    pub const THREAD_REALTIME_ITEM_ADDED: &str = "thread/realtime/itemAdded";
166    pub const THREAD_REALTIME_OUTPUT_AUDIO_DELTA: &str = "thread/realtime/outputAudio/delta";
167    pub const THREAD_REALTIME_SDP: &str = "thread/realtime/sdp";
168    pub const THREAD_REALTIME_STARTED: &str = "thread/realtime/started";
169    pub const THREAD_REALTIME_TRANSCRIPT_DELTA: &str = "thread/realtime/transcript/delta";
170    pub const THREAD_REALTIME_TRANSCRIPT_DONE: &str = "thread/realtime/transcript/done";
171    pub const WINDOWS_WORLD_WRITABLE_WARNING: &str = "windows/worldWritableWarning";
172    pub const WINDOWS_SANDBOX_SETUP_COMPLETED: &str = "windowsSandbox/setupCompleted";
173
174    // Server → client requests (approval flow, v2 envelope)
175    pub const CMD_EXEC_APPROVAL: &str = "item/commandExecution/requestApproval";
176    pub const FILE_CHANGE_APPROVAL: &str = "item/fileChange/requestApproval";
177    pub const TOOL_REQUEST_USER_INPUT: &str = "item/tool/requestUserInput";
178    pub const MCP_SERVER_ELICITATION_REQUEST: &str = "mcpServer/elicitation/request";
179    pub const PERMISSIONS_REQUEST_APPROVAL: &str = "item/permissions/requestApproval";
180    pub const ITEM_TOOL_CALL: &str = "item/tool/call";
181    pub const CHATGPT_AUTH_TOKENS_REFRESH: &str = "account/chatgptAuthTokens/refresh";
182    pub const ATTESTATION_GENERATE: &str = "attestation/generate";
183    pub const APPLY_PATCH_APPROVAL: &str = "applyPatchApproval";
184    pub const EXEC_COMMAND_APPROVAL: &str = "execCommandApproval";
185}
codex_codes/protocol.rs

codex_codes/
protocol.rs
