Struct PtyShell 

pub struct PtyShell {
    pub last_command: String,
    pub output_buffer: String,
    pub command_running: bool,
    pub last_exit_code: Option<i32>,
    pub output_truncated: bool,
    pub last_returned_hash: Option<u64>,
    pub attach_hint: Option<String>,
    /* private fields */
}

Real PTY-based interactive shell

Uses portable-pty for true pseudo-terminal functionality, enabling proper handling of interactive programs like sudo, vim, etc.

Fields

last_command: String

Last command executed

output_buffer: String

Accumulated output buffer

command_running: bool

Whether a command is currently running

last_exit_code: Option<i32>

Exit code of the last completed foreground command, parsed from the prompt marker (──➤<nonce>:<code>). None until a command finishes, and reset to None while one is running.

output_truncated: bool

Flag for output truncation

last_returned_hash: Option<u64>

Hash of the last rendered output we shipped to the caller. Used by the delta path in status_check to elide repeats when the screen is idle.

attach_hint: Option<String>

Optional command a human can run to attach to the same terminal session.

Implementations

impl PtyShell

pub fn new(initial_dir: &Path, restricted_mode: bool) -> Result<Self>

Create a new PTY shell session

Arguments

• initial_dir - Starting directory for the shell
• restricted_mode - Whether to use bash restricted mode (-r)

Returns

A new PtyShell instance with an active bash session

pub fn clear_to_run(&mut self, max_wait_secs: f32) -> Result<bool>

Drain any pending output and, if a previous command still seems to be running, send a Ctrl-C to flush it. Mirrors wcgw’s clear_to_run so a new command never inherits stale prompt fragments or a half-typed line.

Returns true if the shell looks idle (prompt seen), false if it still wouldn’t yield after the Ctrl-C — caller may want to reset.

pub fn send_command(&mut self, command: &str) -> Result<()>

Send a command to the shell and start reading output

pub fn collect_scrollback(&self, lines: usize) -> String

Return up to lines recent lines from the scrollback ring, oldest first. When older lines were evicted or a long unterminated line was clipped, a [winx: …] notice is prepended so the caller knows the scrollback is incomplete rather than silently receiving less than asked.

pub fn fingerprint(text: &str) -> u64

Hash arbitrary rendered output into a u64 dedup key.

pub fn read_output(&mut self, timeout_secs: f32) -> Result<(String, bool)>

Read output from the PTY with timeout

Returns (output, is_complete) tuple where is_complete indicates whether the command has finished (prompt detected)

pub fn poll_output_nonblocking(&mut self) -> bool

Non-blocking drain of whatever the reader thread has already queued.

Unlike read_output, this never sleeps: it consumes every chunk currently available, updates prompt/completion state, and returns immediately. prune_finished_shells uses it so the global background-shell lock is never held across a blocking 100ms read_output. Returns true if the command has completed (prompt seen or PTY closed).

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

Send Ctrl+C (interrupt) to the PTY

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

Send Ctrl+D (EOF) to the PTY

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

Send Ctrl+Z (suspend) to the PTY

pub fn send_text(&mut self, text: &str) -> Result<()>

Send text directly to the PTY (for interactive input)

pub fn send_bytes(&mut self, bytes: &[u8]) -> Result<()>

Send raw bytes directly to the PTY.

pub fn send_special_key(&mut self, key: &str) -> Result<()>

Send a special key sequence

pub fn live_snapshot(&self, max_lines: usize) -> Vec<String>

Snapshot the live terminal screen — a stable, consolidated view of what a human would currently see, with cursor moves/redraws applied and ANSI stripped. max_lines of 0 returns the full screen buffer. This is the foundation for piloting interactive TUIs (the claude CLI, vim, …).

pub fn live_in_alt_screen(&self) -> bool

Whether the live terminal is currently on the alternate screen buffer (a full-screen app like vim/htop/less is running).

pub fn live_cursor_position(&self) -> (u16, u16)

Cursor position (row, col) on the live screen (0-based), so a piloting agent knows where focus is in a menu/form. (0, 0) if the lock is poisoned.

pub fn live_snapshot_diff( &self, max_lines: usize, threshold: usize, ) -> ScreenUpdate

Diff the live screen against what the client last saw, returning only the changed lines when the change is small (huge token savings over many polls). Updates the baseline as a side effect. See ScreenUpdate.

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

Resize the terminal

pub fn get_size(&self) -> (u16, u16)

Get current terminal size

pub fn is_alive(&mut self) -> bool

Check if the shell is still alive

Trait Implementations

impl Debug for PtyShell

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for PtyShell

fn drop(&mut self)

Kill and reap the shell child so it doesn’t leak.

std::process::Child::drop neither kills nor waits, so without this every dropped shell (reset_shell, background-shell prune/remove) would leak a live bash process — soon a zombie — plus the reader thread blocked in read(). Killing the child closes the PTY slave, which makes the reader’s read() return EOF so the thread terminates on its own. Best-effort.

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.