Struct SyncClient 

pub struct SyncClient { /* private fields */ }

Synchronous 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 SyncClient

pub 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 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 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 SyncClient::initialize before any other requests.

pub 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 SyncClient::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 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 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 SyncClient::events or SyncClient::next_message to consume notifications until turn/completed.

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

Interrupt an active turn.

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

Archive a thread.

pub 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 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 fn respond_error( &mut self, id: RequestId, code: i64, message: &str, ) -> Result<()>

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

pub 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 a SyncClient::request call), then reads from the wire.

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

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

Return an iterator over ServerMessages.

The iterator yields Result<ServerMessage> and terminates when the connection closes (EOF). This is the idiomatic way to consume a turn’s notifications in synchronous code.

pub fn shutdown(&mut self) -> Result<()>

Shut down the child process.

Kills the process if it’s still running. Called automatically on Drop.

Trait Implementations

impl Drop for SyncClient

fn drop(&mut self)

Executes the destructor for this type.