Crate codexwire_protocol

Expand description

Generated wire types for the OpenAI Codex app-server.

This crate needs only serde and serde_json. Use it to parse or construct protocol messages without spawning a process or depending on Tokio.

§codexwire-protocol

Generated serde types for Codex 0.167.0’s app-server JSON-RPC protocol. This crate depends on serde and serde_json, with no Tokio, I/O, or child process support. For a client, use codexwire.

Initial crates.io publication is pending. Install from Git for now:

cargo add codexwire-protocol --git https://github.com/talaagent/codexwire
cargo add serde_json

§Construct a typed request

use codexwire_protocol::{ClientInfo, InitializeParams, Request};

let params = InitializeParams {
    capabilities: None,
    client_info: ClientInfo {
        name: "example".into(), title: None, version: "0.1.0".into(),
    },
};
assert_eq!(InitializeParams::METHOD, "initialize");
let json = serde_json::to_value(&params)?;
assert_eq!(json["clientInfo"]["name"], "example");

Request ties params to a method and response type. Notification and ServerRequest identify the server messages supported by the client. These are message bodies; a JSON-RPC transport adds IDs, method names, and envelopes.

§Read unfamiliar variants

use codexwire_protocol::ThreadItem;
use serde_json::json;

let raw = json!({"type": "futureItem", "id": "example", "newField": true});
let item: ThreadItem = serde_json::from_value(raw.clone())?;
assert!(matches!(&item, ThreadItem::Unknown(_)));
assert_eq!(serde_json::to_value(item)?, raw);

A known tag whose body fails to decode also lands in the raw fallback. Not every schema method is generated, and some complex bodies deliberately remain serde_json::Value. The input schema is committed with a version pin; regenerate with scripts/gen-codex-protocol from the repository root. Packaged consumers need neither the schema, Python, nor a Codex binary to build this crate.

CODEX_VERSION records the upstream CLI pin. Package versions follow the public Rust API’s compatibility, independently of the Codex CLI version.

See CONTRIBUTING.md for schema updates and release instructions. Licensed under Apache-2.0, with upstream attribution in NOTICE.

Structs§

AccountRateLimitsUpdatedNotification: Sparse rolling rate-limit update.
AddPatchChangeKind
AgentMessageDeltaNotification
AgentMessageThreadItem
AskForApprovalGranular
AudioUserInput
ClientInfo
CodexErrorInfoActiveTurnNotSteerable
CodexErrorInfoHttpConnectionFailed
CodexErrorInfoResponseStreamConnectionFailed
CodexErrorInfoResponseStreamDisconnected
CodexErrorInfoResponseTooManyFailedAttempts
CollabAgentToolCallThreadItem
CollaborationMode: Collaboration mode for a Codex session.
CommandExecutionApprovalDecisionAcceptWithExecpolicyAmendment
CommandExecutionApprovalDecisionApplyNetworkPolicyAmendment
CommandExecutionRequestApprovalParams
CommandExecutionRequestApprovalResponse
CommandExecutionThreadItem
ContextCompactionThreadItem
CreditsSnapshot
DeletePatchChangeKind
DynamicToolCallThreadItem
EnteredReviewModeThreadItem
ErrorNotification
ExitedReviewModeThreadItem
FileChangeRequestApprovalParams
FileChangeRequestApprovalResponse
FileChangeThreadItem
FileUpdateChange
FunctionCallOutputThreadItem
HookPromptThreadItem
ImageGenerationInputImage: A local image file successfully read for this exact image-generation request.
ImageGenerationThreadItem
ImageUserInput
ImageViewThreadItem
InitializeCapabilities: Client-declared capabilities negotiated during initialize.
InitializeParams
InitializeResponse
ItemCompletedNotification
ItemStartedNotification
LocalAudioUserInput
LocalImageUserInput
McpAppUi: UI resource and display preference for model invocations, captured from the tool descriptor.
McpServerElicitationRequestResponse
McpToolCallAppContext
McpToolCallError
McpToolCallThreadItem
MentionUserInput
MisalignmentErrorDetails
MisalignmentSteer
NetworkApprovalContext
PlanThreadItem
RateLimitSnapshot
RateLimitWindow
ReasoningThreadItem
Settings: Settings for a collaboration mode.
SkillUserInput
SleepThreadItem
SpendControlLimitSnapshot
SubAgentActivityThreadItem
SubAgentSourceThreadSpawn
TextUserInput
Thread
ThreadResumeParams: There are three ways to resume a thread: 1. By thread_id: load the thread from disk by thread_id and resume it. 2. By history: instantiate the thread from memory and resume it. 3. By path: load the thread from disk by path and resume it.
ThreadResumeResponse
ThreadSection: An independently persisted, user-visible thread section.
ThreadSectionAppearance: Extensible visual presentation for a custom thread section.
ThreadStartParams
ThreadStartResponse
ThreadStartedNotification
ThreadTokenUsage
ThreadTokenUsageUpdatedNotification
TokenUsageBreakdown
Turn
TurnCompletedNotification
TurnError
TurnInterruptParams
TurnStartParams
TurnStartResponse
TurnStartedNotification
TurnToolOutput
UpdatePatchChangeKind
UsageLimitExceededImageGenerationFailure
UserMessageThreadItem
WebSearchThreadItem

Enums§

AgentMessageDelivery
ApprovalsReviewer: Configures who approval requests are routed to for review. Examples include sandbox escapes, blocked network access, MCP approval prompts, and ARC escalations. Defaults to user. auto_review uses a carefully prompted subagent to gather relevant context and apply a risk-based decision framework before approving or denying the request. The legacy value guardian_subagent is accepted for compatibility.
AskForApproval
CodexErrorInfo: This translation layer make sure that we expose codex error code in camel case.
CollabAgentTool
CollabAgentToolCallStatus
CommandExecutionApprovalDecision
CommandExecutionApprovalKind: Distinguishes a command approval from input sent to an existing terminal.
CommandExecutionSource
CommandExecutionStatus
DynamicToolCallStatus
FileChangeApprovalDecision
ImageDetail
ImageGenerationFailure
McpAppDisplayMode
McpServerElicitationAction
McpToolCallStatus
MessagePhase: Classifies assistant text as commentary, a partial answer, or a terminal answer.
ModeKind: Initial collaboration mode to use when the TUI starts.
NetworkApprovalProtocol
NonSteerableTurnKind
PatchApplyStatus
PatchChangeKind
Personality: Deprecated: friendly and pragmatic no longer select a style.
PlanType
RateLimitReachedType
ReasoningSummary: A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model’s reasoning process. See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#reasoning-summaries
SandboxMode
SessionSource
SubAgentActivityKind
SubAgentSource
ThreadHistoryMode
ThreadItem: A thread item and its recorded lifecycle times. The payload stays flat on the wire.
ThreadStartSource
TurnItemsView
TurnStatus
UserInput

Constants§

CODEX_VERSION: The Codex version this schema came from (codex --version).

Traits§

Notification: A server notification: its method name.
Request: A client request: its method name and response type.
ServerRequest: A server-to-client request: its method name and response type.

Type Aliases§

AbsolutePathBuf: A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).
AgentPath
AsyncUserInputQuestion
CollabAgentState
CommandAction
DynamicToolCallOutputContentItem
FunctionCallOutputBody
GitInfo
HookPromptFragment
LegacyAppPathString
McpServerElicitationRequestParams
McpToolCallResult
MemoryCitation
NetworkPolicyAmendment
ReasoningEffort: A non-empty reasoning effort value advertised by the model.
SandboxPolicy
TextElement
ThreadId
ThreadSource
ThreadStatus
TurnInterruptResponse
WebSearchAction