Struct AsyncClient 

pub struct AsyncClient { /* private fields */ }

Asynchronous multi-turn client for the Codex app-server.

Communicates with a long-lived codex app-server process via newline-delimited JSON-RPC over stdio. Manages request/response correlation and buffers incoming notifications that arrive while waiting for RPC responses.

The client automatically kills the app-server process when dropped.

Implementations

impl AsyncClient

pub async fn start() -> Result<Self>

Start an app-server with default settings.

Spawns codex app-server --listen stdio://, performs the required initialize handshake, and returns a connected client ready for thread_start().

Errors

Returns an error if the codex CLI is not installed, the version is incompatible, the process fails to start, or the initialization handshake fails.

pub async fn start_with(builder: AppServerBuilder) -> Result<Self>

Start an app-server with a custom AppServerBuilder.

Performs the required initialize handshake before returning. Use this to configure a custom binary path or working directory.

Errors

Returns an error if the process fails to start, stdio pipes cannot be established, or the initialization handshake fails.

pub async fn spawn(builder: AppServerBuilder) -> Result<Self>

Spawn an app-server without performing the initialize handshake.

Use this if you need to send a custom InitializeParams (e.g., with specific capabilities). You must call AsyncClient::initialize before any other requests.

pub async fn request<P: Serialize, R: DeserializeOwned>( &mut self, method: &str, params: &P, ) -> Result<R>

Send a JSON-RPC request and wait for the matching response.

Any notifications or server requests that arrive before the response are buffered and can be retrieved via AsyncClient::next_message.

Errors

• Error::JsonRpc if the server returns a JSON-RPC error
• Error::ServerClosed if the connection drops before a response arrives
• Error::Json if response deserialization fails

pub async fn thread_start( &mut self, params: &ThreadStartParams, ) -> Result<ThreadStartResponse>

Start a new thread (conversation session).

A thread must be created before any turns can be started. The returned ThreadStartResponse contains the thread_id needed for subsequent calls.

pub async fn turn_start( &mut self, params: &TurnStartParams, ) -> Result<TurnStartResponse>

Start a new turn within a thread.

Sends user input to the agent. After calling this, use AsyncClient::next_message to stream notifications until turn/completed arrives.

pub async fn turn_interrupt( &mut self, params: &TurnInterruptParams, ) -> Result<TurnInterruptResponse>

Interrupt an active turn.

pub async fn thread_archive( &mut self, params: &ThreadArchiveParams, ) -> Result<ThreadArchiveResponse>

Archive a thread.

pub async fn initialize( &mut self, params: &InitializeParams, ) -> Result<InitializeResponse>

Perform the initialize handshake with the app-server.

Sends initialize with the given params and then sends the initialized notification. This must be the first request after spawning the process.

pub async fn respond<R: Serialize>( &mut self, id: RequestId, result: &R, ) -> Result<()>

Respond to a server-to-client request (e.g., approval flow).

When the server sends a ServerMessage::Request, it expects a response. Use this method with the request’s id and a result payload. For command approval, pass a CommandExecutionApprovalResponse. For file change approval, pass a FileChangeApprovalResponse.

pub async fn respond_error( &mut self, id: RequestId, code: i64, message: &str, ) -> Result<()>

Respond to a server-to-client request with an error.

pub async fn next_message(&mut self) -> Result<Option<ServerMessage>>

Read the next incoming server message (notification or server request).

Returns buffered messages first (from notifications that arrived during an AsyncClient::request call), then reads from the wire.

Returns Ok(None) when the app-server closes the connection (EOF).

Typical notification methods

Method	Meaning
turn/started	Agent began processing
item/agentMessage/delta	Streaming text chunk
item/commandExecution/outputDelta	Command output chunk
item/started / item/completed	Item lifecycle
turn/completed	Agent finished the turn
error	Server-side error

pub fn events(&mut self) -> EventStream<'_>

Return an async event stream over ServerMessages.

Wraps AsyncClient::next_message in a stream-like API. Call EventStream::next in a loop, or EventStream::collect to gather all messages until EOF.

pub fn take_stderr(&mut self) -> Option<BufReader<ChildStderr>>

Take the stderr reader (can only be called once).

Useful for logging or diagnostics. Returns None on subsequent calls.

pub fn pid(&self) -> Option<u32>

Get the process ID.

pub fn is_alive(&mut self) -> bool

Check if the child process is still running.

pub async fn shutdown(self) -> Result<()>

Shut down the app-server process.

Consumes the client. If you don’t call this explicitly, the Drop implementation will kill the process automatically.

Trait Implementations

impl Drop for AsyncClient

fn drop(&mut self)

Executes the destructor for this type.