Module codex_protocol 

Lightweight JSON-RPC types for the Codex app-server stdio protocol.

Codex communicates over stdin/stdout using newline-delimited JSON messages. The protocol is JSON-RPC-like but does not include the "jsonrpc": "2.0" field.

Protocol flow:

1. Client sends initialize request → server responds with {userAgent}
2. Client sends initialized notification (no id)
3. Client sends thread/start → server responds with {thread: {id, ...}, model, ...}
4. Client sends turn/start with {threadId, input} → server responds + streams events
5. Events: turn/started, item/started, item/agentMessage/delta, item/completed, turn/completed

Structs

JsonRpcClientNotification

A client-to-server notification (no id, no response expected).

JsonRpcError

JSON-RPC error object.

JsonRpcNotification

A server-to-client notification (no id field).

JsonRpcRequest

A request (client -> server). Has an id for correlation.

JsonRpcResponse

A response (server -> client). Has an id matching the request.

Enums

JsonRpcMessage

A line from Codex stdout can be either a response (has id) or a notification (no id).

Constants

EVENT_AGENT_MESSAGE_DELTA

A streaming text delta from the agent.

EVENT_COMMAND_OUTPUT_DELTA

Command execution output delta.

EVENT_ERROR

Error notification.

EVENT_ITEM_COMPLETED

An output item has completed.

EVENT_ITEM_STARTED

An output item has started.

EVENT_THREAD_STARTED

Thread has been started/loaded.

EVENT_TURN_COMPLETED

A turn has completed.

EVENT_TURN_STARTED

A turn has started processing.

METHOD_INITIALIZE

Initialize handshake.

METHOD_INITIALIZED

Client notification sent after initialize response.

METHOD_THREAD_START

Start a new thread (conversation).

METHOD_TURN_INTERRUPT

Interrupt the current turn.

METHOD_TURN_START

Start a new turn within a thread.