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 send_command(&mut self, command: &str) -> Result<()>

Send a command to the shell and start reading output

pub fn mark_command_started(&mut self)

Start the monotonic runtime clock for a newly submitted command.

pub fn completion_report_pending(&self) -> bool

Whether the most recent foreground command has finished without any response having reported its exit yet.

pub fn mark_completion_reported(&mut self)

Record that a response reported the current command as finished.

pub fn command_generation(&self) -> u64

pub fn incarnation(&self) -> u64

pub fn command_elapsed(&self) -> Option<Duration>

Elapsed runtime since the current command was submitted.

pub fn current_cwd(&self) -> &Path

Current working directory last reported by this shell’s prompt.

pub fn delivered_output(&self) -> String

Snapshot used as the left-hand side of incremental output rendering.

pub fn mark_output_delivered(&mut self, output: &str)

Mark the cumulative output snapshot as delivered after rendering it.

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 output_snapshot(&self) -> String

Snapshot of the accumulated output buffer — the same text read_output returns. Lets callers poll non-blocking (poll_output_nonblocking) and grab the buffer once at the end instead of cloning it on every slice.

pub fn set_scratch_root(&mut self, root: &Path)

Point output-offload scratch files at root (the workspace). Idempotent; callers set it per command so it always tracks the current workspace.

pub fn scratch_path(&self) -> Option<&Path>

The scratch file holding the current command’s dropped output head, if any was offloaded this command.

pub fn reset_scratch(&mut self)

Forget the current command’s scratch file so the next command starts a fresh one. Does not delete the file (pruned later by age).

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_osc_title(&self) -> String

The latest OSC 0/2 window title emitted by the foreground program ("" when none) — an out-of-band turn signal for the manifest recognizers (claude/codex render a spinner glyph in the title while generating).

pub fn live_osc_progress(&self) -> String

The latest OSC 9 payload after 9; ("" when none) — ConEmu-style progress reads 4;<state>;<percent>.

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 process_id(&self) -> Option<u32>

OS process id of the shell that owns this PTY.

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 and its whole process group so neither the shell nor anything it spawned leaks.

std::process::Child::drop neither kills nor waits, and even Child::kill signals only the shell itself: a background job it started (npm run dev &, a nohup’d server) would be reparented to init and live on. Because portable-pty runs the shell as a session/group leader, we can signal the whole group with a negative pid - SIGTERM first so well-behaved children can clean up, then Child::kill (SIGKILL on the leader, which closes the PTY slave so the reader thread’s read() returns EOF and the thread exits), then SIGKILL the group to sweep anything still alive, then reap. The pgid is captured while the leader is alive and reused: it stays valid until we wait(), even after the leader dies. All 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.