Struct PtySession 

pub struct PtySession { /* private fields */ }

Async PTY session. Spawns a CLI tool in a real PTY and broadcasts AgentEvent to all subscribers via a tokio broadcast channel.

The reader loop runs on a blocking thread (via spawn_blocking) because PTY I/O is inherently blocking. The loop bridges to async consumers via the broadcast channel.

Broadcast semantics

tokio::sync::broadcast drops events for lagged receivers — if a subscriber falls behind, it will skip events. This is acceptable for streaming agent output (e.g., TUI rendering can re-render from the PTY screen buffer). If you need guaranteed delivery, wrap the receiver in a buffering layer.

Implementations

impl PtySession

pub async fn spawn(config: SessionConfig) -> Result<Self, AgentError>

Spawn a CLI tool in a PTY and start broadcasting events.

Uses a 24x80 terminal size (compact). To control size, use spawn_with_size.

pub async fn spawn_with_size( config: SessionConfig, rows: u16, cols: u16, ) -> Result<Self, AgentError>

Spawn a CLI tool in a PTY with a specific terminal size.

pub fn subscribe(&self) -> Receiver<AgentEvent>

Subscribe to receive all future AgentEvent values from this session.

Note: events that occurred before subscribing will not be received.

pub fn write_handle(&self) -> PtyWriteHandle

Get the write handle for sending input to the PTY.

pub async fn write(&self, data: &str) -> Result<(), AgentError>

Send raw bytes to the PTY.

pub async fn send_prompt(&self, prompt: &str) -> Result<(), AgentError>

Send a prompt char-by-char (required for Ink-based TUI tools like Claude Code).

Sends each character with a small delay to avoid overwhelming the TUI’s raw-mode input processing. Ends with a carriage return.

pub async fn resize(&self, rows: u16, cols: u16) -> Result<(), AgentError>

Resize the PTY.

pub fn session_id(&self) -> &str

Session ID assigned at spawn time.

pub async fn kill(&self) -> Result<(), AgentError>

Abort the reader task and kill the child process.