Crate codex_app_server_client

Expand description

Standalone async Rust client for the Codex CLI’s app-server v2 JSON-RPC protocol.

codex app-server is the interface Codex uses to power rich clients (the VS Code extension, the Codex app). This crate spawns (or connects to) an app-server process, speaks its newline-delimited JSON-RPC 2.0 wire format, and exposes every v2 method as a typed async function.

This crate has zero dependencies on anything else in the workspace it lives in - only published crates.io dependencies - so it can be lifted into another project wholesale. See README.md for how its vendored protocol schema was derived and how to regenerate it.

§Quick start

use codex_app_server_client::{CodexSession, DenyAllApprovalHandler, SessionOptions};

let mut session = CodexSession::spawn(SessionOptions::new("my_integration", "0.1.0")).await?;
let result = session
    .run_text_turn_with_model_and_handler(
        "gpt-5",
        "Say hello in one sentence.",
        &DenyAllApprovalHandler::default(),
    )
    .await?;
println!("{}", result.agent_message());

Modules§

protocol: Generated types for the Codex app-server v2 JSON-RPC protocol.
rest

Structs§

AllowAllApprovalHandler: Approval handler that approves Codex approval requests.
AsyncFnApprovalHandler: Approval handler backed by an async closure.
CodexAppServerClient: Async client for the Codex app-server v2 JSON-RPC protocol.
CodexDaemon
CodexSession: High-level app-server session that owns a client plus event stream.
CompatibilityReport
DenyAllApprovalHandler: Approval handler that rejects every server request with a JSON-RPC error.
EventCollector
EventStream: Receives Events from one app-server connection.
FnApprovalHandler: Approval handler backed by a closure.
PendingServerRequest: A server->client request the app-server sent us (approvals, elicitation, etc.), paired with a one-shot reply channel. Obtain these from EventStream::recv as an Event::Request.
ReadOnlyApprovalHandler: Approval handler for read-only integrations.
SessionOptions: Options used when creating a high-level CodexSession.
SurfaceSummary
TextTurnResult: Result of a one-shot text turn.

Enums§

Error: Errors returned by crate::CodexAppServerClient.
Event: An event pushed from the app-server connection. Deliberately not #[non_exhaustive] (contrast Error, which explains its own opposite choice) - this models a closed, stable three-way split of “shape of thing the app-server can send,” not an open-ended taxonomy, so callers matching on it exhaustively (as this crate’s own code does everywhere) get a compile error if a variant is ever added, rather than silently ignoring the new case via a wildcard arm.
ServerRequestReply: A typed reply for a server-to-client app-server request.

Constants§

CLIENT_NOTIFICATION_METHOD_COUNT
CLIENT_REQUEST_METHOD_COUNT
CODEX_SCHEMA_VERSION
DEFAULT_CALL_TIMEOUT: Default timeout for CodexAppServerClient::call_request (and therefore every generated per-method wrapper). Override with CodexAppServerClient::with_call_timeout. This bounds one request/response round trip - it has nothing to do with how long a turn takes to finish generating, since that streams via crate::Event::Notification instead of blocking the request that started it.
DEFAULT_EVENTS_CHANNEL_CAPACITY: Default capacity of the internal channel from the reader task to EventStream, used by CodexAppServerClient::spawn, CodexAppServerClient::connect_streams, and CodexAppServerClient::connect_unix. Bounded (rather than unbounded) so a stalled or absent consumer grows memory by a fixed amount, not without bound, if events keep arriving faster than EventStream::recv is called - see that type’s doc comment for the drop policy once this fills up.
MAX_LINE_BYTES: Hard cap on a single NDJSON line’s size. Without this, a single huge or unterminated line from a buggy or malicious app-server peer would grow read_line’s buffer without bound. 64 MiB comfortably covers legitimate large payloads (e.g. fs/readFile results, big diffs) while still being a real, finite bound.
SERVER_NOTIFICATION_METHODS: All 68 server notification methods this crate can decode: [“account/login/completed”, “account/rateLimits/updated”, “account/updated”, “app/list/updated”, “command/exec/outputDelta”, “configWarning”, “deprecationNotice”, “error”, “externalAgentConfig/import/completed”, “externalAgentConfig/import/progress”, “fs/changed”, “fuzzyFileSearch/sessionCompleted”, “fuzzyFileSearch/sessionUpdated”, “guardianWarning”, “hook/completed”, “hook/started”, “item/agentMessage/delta”, “item/autoApprovalReview/completed”, “item/autoApprovalReview/started”, “item/commandExecution/outputDelta”, “item/commandExecution/terminalInteraction”, “item/completed”, “item/fileChange/outputDelta”, “item/fileChange/patchUpdated”, “item/mcpToolCall/progress”, “item/plan/delta”, “item/reasoning/summaryPartAdded”, “item/reasoning/summaryTextDelta”, “item/reasoning/textDelta”, “item/started”, “mcpServer/oauthLogin/completed”, “mcpServer/startupStatus/updated”, “model/rerouted”, “model/safetyBuffering/updated”, “model/verification”, “process/exited”, “process/outputDelta”, “remoteControl/status/changed”, “serverRequest/resolved”, “skills/changed”, “thread/archived”, “thread/closed”, “thread/compacted”, “thread/deleted”, “thread/goal/cleared”, “thread/goal/updated”, “thread/name/updated”, “thread/realtime/closed”, “thread/realtime/error”, “thread/realtime/itemAdded”, “thread/realtime/outputAudio/delta”, “thread/realtime/sdp”, “thread/realtime/started”, “thread/realtime/transcript/delta”, “thread/realtime/transcript/done”, “thread/settings/updated”, “thread/started”, “thread/status/changed”, “thread/tokenUsage/updated”, “thread/unarchived”, “turn/completed”, “turn/diff/updated”, “turn/moderationMetadata”, “turn/plan/updated”, “turn/started”, “warning”, “windows/worldWritableWarning”, “windowsSandbox/setupCompleted”]
SERVER_NOTIFICATION_METHOD_COUNT
SERVER_REQUEST_METHOD_COUNT

Traits§

ApprovalHandler: Policy hook for server-to-client app-server requests.

Type Aliases§

ApprovalFuture: Boxed future returned by ApprovalHandler.
Result