Terminal Sessions

The terminal manager uses the portable-pty crate to spawn pseudo-terminal processes. Each PTY is configured with the user's default shell, working directory, and environment variables. The manager maintains a HashMap of active sessions keyed by session_id.

Each session maintains two output destinations: a local Channel for UI consumption and WebSocket connections for mobile clients. Output is broadcast to all connected receivers without blocking the PTY read loop.

Broadcast pattern: Output is cloned to each receiver; slow consumers are dropped to prevent backpressure from affecting the PTY read loop.

Each session maintains a 32MB circular buffer for output history. This allows clients to reconnect and receive recent output without querying the database. The buffer automatically evicts oldest content when full.

// Buffer configuration
const BUFFER_SIZE: usize = 32 * 1024 * 1024; // 32MB per session

struct SessionBuffer {
    data: VecDeque<u8>,
    write_offset: usize,
}

impl SessionBuffer {
    fn push(&mut self, bytes: &[u8]) {
        // Evict from front if buffer full
        while self.data.len() + bytes.len() > BUFFER_SIZE {
            self.data.pop_front();
        }
        self.data.extend(bytes);
        self.write_offset += bytes.len();
    }

    fn get_since(&self, offset: usize) -> &[u8] {
        // Return bytes from offset to current end
    }
}

Mobile clients receive terminal output using the PTC1 binary framing protocol. This compact format includes message type, session ID, and payload length to support multiplexed session streams over a single WebSocket connection.

// PTC1 Frame Structure
┌─────────────────────────────────────────────────────┐
│  Type   │     Session UUID      │  Payload Length   │
│ (1 byte)│     (16 bytes)        │   (4 bytes LE)    │
├─────────────────────────────────────────────────────┤
│                   Payload Data                      │
│                 (variable length)                   │
└─────────────────────────────────────────────────────┘

Message Types:
  0x01 = Terminal output
  0x02 = Resize notification
  0x03 = Input acknowledgment
  0x04 = State change event

The compact header (21 bytes) minimizes overhead for real-time streaming to bandwidth-constrained mobile clients.

Sessions transition through defined states that reflect the PTY process lifecycle and recovery status.

Session state and output logs are flushed to SQLite every 10 seconds. This provides durability without impacting PTY performance. On app restart, sessions in Running or Suspended state are restored from the database.

-- terminal_sessions table schema
CREATE TABLE terminal_sessions (
    session_id      TEXT PRIMARY KEY,
    created_at      TEXT NOT NULL,
    updated_at      TEXT NOT NULL,
    status          TEXT NOT NULL,  -- Initializing|Running|Suspended|Exited|...
    exit_code       INTEGER,
    working_dir     TEXT NOT NULL,
    env_vars        TEXT,           -- JSON object
    output_log      BLOB            -- Full session output for restoration
);

-- Restoration query on startup
SELECT * FROM terminal_sessions
WHERE status IN ('Running', 'Suspended');

Health checks combine PTY process status with database records to determine session liveness. This dual-source approach handles edge cases where the PTY dies without updating the database.

Sessions follow a predictable lifecycle from creation through termination or restoration. The UI component initiates sessions, the terminal manager handles PTY operations, and the persistence layer ensures durability.

The terminal monitors agent activity through a two-level inactivity detection system. When an agent stops producing output, the system progressively alerts you to check what has happened:

Attention indicators clear automatically when new output is received. This helps track when agents have finished tasks or need guidance without guessing why they stopped.

Before launching commands, the terminal checks for configured CLI tools and reports the default shell. This ensures users know which environment will run and whether required tools are available.