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 new(child: Child) -> Result<Self>

Create a client from an existing child process.

The child’s stdin, stdout, and stderr must all be piped. This does not perform the app-server initialize handshake or a Codex version check. Use AppServerBuilder::build_command_sync to retain the SDK’s command-line and stdio configuration while customizing how the process is spawned.

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 the binary path, working directory, environment, or CLI arguments.

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 thread_resume( &mut self, params: &ThreadResumeParams, ) -> Result<ThreadResumeResponse>

Resume a previously persisted thread by id.

Replays the thread’s history so turns can continue where they left off.

pub fn thread_fork( &mut self, params: &ThreadForkParams, ) -> Result<ThreadForkResponse>

Fork an existing thread into a new independent thread.

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 thread_delete( &mut self, params: &ThreadDeleteParams, ) -> Result<ThreadDeleteResponse>

Delete 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.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.