Struct CodexSession 

pub struct CodexSession { /* private fields */ }

High-level app-server session that owns a client plus event stream.

CodexSession performs the initialize / initialized handshake before it is returned, then offers convenience methods for common thread and text-turn workflows while keeping the full low-level CodexAppServerClient exposed.

Implementations

impl CodexSession

pub async fn spawn(options: SessionOptions) -> Result<Self>

Spawns codex app-server, performs the handshake, and returns a session.

pub async fn connect_streams<R, W>( reader: R, writer: W, options: SessionOptions, ) -> Result<Self>

where R: AsyncBufRead + Unpin + Send + 'static, W: AsyncWrite + Unpin + Send + 'static,

Connects over caller-provided async streams and performs the handshake.

This is primarily useful for tests and custom transports.

pub async fn connect_unix( path: impl AsRef<Path>, options: SessionOptions, ) -> Result<Self>

Connects to an app-server Unix socket and performs the handshake.

pub fn client(&self) -> &CodexAppServerClient

pub fn initialize_response(&self) -> &InitializeResponse

Returns the initialize response captured during session setup.

pub async fn next_event(&mut self) -> Option<Event>

Receives the next raw event without applying an approval policy.

Most integrations should prefer Self::next_notification, Self::collect_until_complete, or the higher-level text helpers so server requests are answered promptly.

pub async fn next_notification<H>( &mut self, handler: &H, ) -> Option<ServerNotification>

where H: ApprovalHandler,

Receives the next server notification, replying to server requests with the supplied ApprovalHandler while waiting.

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

Starts a thread with fully-typed generated params.

pub async fn start_thread_with_model( &self, model: impl Into<String>, ) -> Result<ThreadStartResponse>

Starts a thread using only a model override.

This is a convenience wrapper around start_thread(ThreadStartParams::new().model(model)).

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

Sends a turn with fully-typed generated params.

pub async fn send_text_turn( &self, thread_id: impl Into<String>, text: impl Into<String>, ) -> Result<TurnStartResponse>

Sends one text input item to an existing thread.

This is a convenience wrapper around send_turn(TurnStartParams::text(thread_id, text)).

pub async fn run_text_turn( &mut self, text: impl Into<String>, ) -> Result<TextTurnResult>

Runs a one-shot text turn using a new default thread.

Server requests are answered with DenyAllApprovalHandler. Use Self::run_text_turn_with_model_and_handler when the turn needs a specific model or a real approval/tool policy.

pub async fn run_text_turn_with_model_and_handler<H>( &mut self, model: impl Into<String>, text: impl Into<String>, handler: &H, ) -> Result<TextTurnResult>

where H: ApprovalHandler,

Runs a one-shot text turn with an explicit model and approval handler.

The helper starts a new thread, sends the text turn, drains notifications until that turn completes, and returns the collected assistant text/diff/errors.

pub async fn run_text_turn_with_params_and_handler<H>( &mut self, thread_params: ThreadStartParams, text: impl Into<String>, handler: &H, ) -> Result<TextTurnResult>

where H: ApprovalHandler,

Runs a one-shot text turn with explicit thread/start params and an approval handler.

This is the lowest-level text-turn convenience helper: callers can set the full typed ThreadStartParams instead of only the model, while still reusing the shared thread start, turn start, server-request handling, and event collection flow.

pub async fn wait_for_turn_completed<H>( &mut self, thread_id: impl Into<String>, turn_id: impl Into<String>, handler: &H, ) -> Result<EventCollector>

where H: ApprovalHandler,

Drains notifications until a specific turn reaches a terminal status.

Any server request encountered while waiting is answered through handler. The returned EventCollector contains assistant text, latest diff, completion state, and turn errors observed for the named thread/turn pair.

pub async fn collect_agent_message<H>( &mut self, thread_id: impl Into<String>, turn_id: impl Into<String>, handler: &H, ) -> Result<String>

where H: ApprovalHandler,

Drains notifications for a turn and returns only the assistant text.

pub async fn collect_until_complete<H>( &mut self, collector: &mut EventCollector, handler: &H, ) -> Result<()>

where H: ApprovalHandler,

Drains notifications into an existing collector until it is complete.