terminal-pilot 0.0.2 → 0.0.4

package/README.md

@@ -1,38 +1,23 @@
-# @poe-code/terminal-pilot
+# terminal-pilot
 
-`terminal-pilot` is a Playwright-like SDK and MCP server for automating interactive CLI apps through a real pseudoterminal (PTY).
+`terminal-pilot` is a Playwright-like SDK for automating interactive CLI apps through a real pseudoterminal (PTY).
 
 Use it when plain stdio is not enough: menus, prompts, arrow-key navigation, confirmations, and terminal redraws such as `poe-code configure`.
 
 For design rationale and scope, see `docs/plans/terminal-pilot.md`.
 
+For the MCP server, see [terminal-pilot-mcp](../terminal-pilot-mcp).
+
 ## What it includes
 
 - **SDK:** `TerminalPilot` → `TerminalSession` → `TerminalScreen`
-- **MCP server:** 10 tools for AI-driven CLI automation
 - **Real PTY execution:** works with interactive CLIs that expect a terminal
 - **Headless by default:** optional `observe: true` mirrors PTY output for debugging
 
 ## Entry points
 
 ```ts
-import { TerminalPilot } from "@poe-code/terminal-pilot";
-```
-
-```ts
-import { createTerminalPilotMcpServer, main } from "@poe-code/terminal-pilot/mcp";
-```
-
-CLI bin:
-
-```sh
-terminal-pilot-mcp
-```
-
-Development entry point in this repo:
-
-```sh
-npx tsx packages/terminal-pilot/src/mcp-server.ts
+import { TerminalPilot } from "terminal-pilot";
 ```
 
 ## SDK API
@@ -42,7 +27,7 @@ npx tsx packages/terminal-pilot/src/mcp-server.ts
 Creates and tracks active terminal sessions.
 
 ```ts
-import { TerminalPilot } from "@poe-code/terminal-pilot";
+import { TerminalPilot } from "terminal-pilot";
 
 const pilot = await TerminalPilot.launch();
 
@@ -76,8 +61,9 @@ type NewSessionOptions = {
 class TerminalPilot {
   static launch(): Promise<TerminalPilot>;
   newSession(options: NewSessionOptions): Promise<TerminalSession>;
-  getSession(id: string): TerminalSession; // throws if missing
-  sessions(): TerminalSession[]; // active sessions only
+  getSession(id: string): TerminalSession; // throws if not in map; works for exited sessions until deleteSession
+  deleteSession(id: string): void; // explicit removal from session map
+  sessions(): TerminalSession[]; // running sessions only (exitCode === null)
   close(): Promise<void>;
 }
 ```
@@ -137,12 +123,13 @@ class TerminalSession {
   readonly pid: number;
   exitCode: number | null;
 
-  type(text: string): Promise<void>; // character-by-character
-  fill(text: string): Promise<void>; // bulk write
+  type(text: string): Promise<void>; // character-by-character with delay
+  fill(text: string): Promise<void>; // bulk write (\n → \r)
   press(key: TerminalKey): Promise<void>;
   send(raw: string): Promise<void>; // raw bytes / escape sequences
   signal(signal: string): Promise<void>;
   waitFor(pattern: string | RegExp, options?: WaitForOptions): Promise<string>;
+  waitForExit(options?: { timeout?: number }): Promise<number>; // throws on timeout
   waitForQuiet(ms: number): Promise<void>;
   screen(): Promise<TerminalScreen>;
   history(options?: HistoryOptions): Promise<string[]>;
@@ -188,125 +175,11 @@ class TerminalScreen {
 }
 ```
 
-## MCP server
-
-The MCP server holds one in-memory `TerminalPilot` instance and exposes terminal automation over stdio.
-
-### Run it
-
-Development:
-
-```sh
-npx tsx packages/terminal-pilot/src/mcp-server.ts
-```
-
-Built / installed package:
-
-```sh
-terminal-pilot-mcp
-```
-
-Programmatic:
-
-```ts
-import { main } from "@poe-code/terminal-pilot/mcp";
-
-await main();
-```
-
-### Connect to an MCP client
-
-Install the package globally from a local build:
-
-```sh
-cd packages/terminal-pilot
-npm pack --pack-destination /tmp && npm install -g /tmp/poe-code-terminal-pilot-*.tgz && rm /tmp/poe-code-terminal-pilot-*.tgz
-```
-
-This makes the `terminal-pilot-mcp` bin available globally.
-
-**Claude Code** (`~/.claude.json` or project `.mcp.json`):
-
-```json
-{
-  "mcpServers": {
-    "terminal-pilot": {
-      "command": "terminal-pilot-mcp"
-    }
-  }
-}
-```
-
-**Claude Desktop** (`claude_desktop_config.json`):
-
-```json
-{
-  "mcpServers": {
-    "terminal-pilot": {
-      "command": "terminal-pilot-mcp"
-    }
-  }
-}
-```
-
-**Cursor** (`.cursor/mcp.json`):
-
-```json
-{
-  "mcpServers": {
-    "terminal-pilot": {
-      "command": "terminal-pilot-mcp"
-    }
-  }
-}
-```
-
-### Tools
-
-`void` means the tool returns no payload.
-
-| Tool | Input | Output |
-| --- | --- | --- |
-| `terminal_create_session` | `{ command: string, args?: string[], cwd?: string, cols?: number, rows?: number, observe?: boolean }` | `{ sessionId: string, pid: number }` |
-| `terminal_type` | `{ sessionId: string, text: string }` | `void` |
-| `terminal_press_key` | `{ sessionId: string, key: TerminalKey }` | `void` |
-| `terminal_send_signal` | `{ sessionId: string, signal: string }` | `void` |
-| `terminal_wait_for` | `{ sessionId: string, pattern: string, timeout?: number }` | `{ matched: true, output: string }` |
-| `terminal_read_screen` | `{ sessionId: string }` | `{ lines: string[], cursor: { row: number, col: number }, size: { rows: number, cols: number } }` |
-| `terminal_read_history` | `{ sessionId: string, last?: number }` | `{ lines: string[] }` |
-| `terminal_resize` | `{ sessionId: string, cols: number, rows: number }` | `void` |
-| `terminal_close_session` | `{ sessionId: string }` | `{ exitCode: number }` |
-| `terminal_list_sessions` | `{}` | `{ sessions: Array<{ id: string, command: string, pid: number }> }` |
-
-Practical notes:
-
-- `terminal_wait_for.pattern` is compiled as a JavaScript `RegExp` on the server.
-- `terminal_type` maps to `session.fill(...)` for bulk text entry.
-- `terminal_read_screen` returns the **current visible screen**, not scrollback.
-- `terminal_read_history` returns ANSI-stripped output since session start.
-- `terminal_list_sessions` returns **active** sessions only.
-- `observe: true` mirrors PTY output to `stderr`, which is useful when debugging MCP-driven runs.
-
-Minimal MCP flow:
-
-```json
-{"tool":"terminal_create_session","arguments":{"command":"poe-code","args":["configure"]}}
-{"tool":"terminal_wait_for","arguments":{"sessionId":"<id>","pattern":"Pick an agent to configure:"}}
-{"tool":"terminal_press_key","arguments":{"sessionId":"<id>","key":"Enter"}}
-{"tool":"terminal_read_screen","arguments":{"sessionId":"<id>"}}
-{"tool":"terminal_close_session","arguments":{"sessionId":"<id>"}}
-```
-
 ## Environment variables
 
 There are **no terminal-pilot-specific environment variables**.
 
-Runtime environment is controlled per session:
-
-- SDK: `newSession({ env })`
-- MCP server: spawned commands inherit the MCP server process environment unless you override it in your command wrapper
-
-There are also **no package-level config files or config options** beyond the per-session options above.
+Runtime environment is controlled per session via `newSession({ env })`. There are no package-level config files or config options beyond the per-session options.
 
 ## Testing
 
@@ -340,7 +213,7 @@ Example fixture-based test:
 
 ```ts
 import path from "node:path";
-import { TerminalPilot } from "@poe-code/terminal-pilot";
+import { TerminalPilot } from "terminal-pilot";
 
 const pilot = await TerminalPilot.launch();
 const tsxPath = path.join(process.cwd(), "node_modules", ".bin", "tsx");
@@ -371,7 +244,7 @@ Use a temporary home directory so you do not touch your real config while testin
 import { mkdtempSync, rmSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { TerminalPilot } from "@poe-code/terminal-pilot";
+import { TerminalPilot } from "terminal-pilot";
 
 const tmpHome = mkdtempSync(path.join(os.tmpdir(), "poe-configure-test-"));
 const pilot = await TerminalPilot.launch();

package/dist/terminal-buffer.d.ts

@@ -0,0 +1,38 @@
+type Cell = [number, string] | null;
+type Row = Cell[];
+export declare class TerminalBuffer {
+    private _cols;
+    private _rows;
+    private _screen;
+    private _cursorX;
+    private _cursorY;
+    private _savedCursor;
+    private _scrollTop;
+    private _scrollBottom;
+    private _state;
+    private _csiParams;
+    private _csiPrivate;
+    readonly displayBuffer: {
+        readonly cursorX: number;
+        readonly cursorY: number;
+        readonly data: Array<Row | undefined>;
+    };
+    constructor(cols: number, rows: number);
+    write(data: string): void;
+    resize(cols: number, rows: number): void;
+    private _makeScreen;
+    private _makeRow;
+    private _clamp;
+    private _setChar;
+    private _eraseLine;
+    private _scrollUp;
+    private _scrollDown;
+    private _newline;
+    private _parseCsiParams;
+    private _execCsi;
+    private _feed;
+    private _feedNormal;
+    private _feedEscape;
+    private _feedCsi;
+}
+export {};

package/dist/terminal-buffer.js

@@ -0,0 +1,445 @@
+export class TerminalBuffer {
+    _cols;
+    _rows;
+    _screen;
+    _cursorX = 0;
+    _cursorY = 0;
+    _savedCursor = { x: 0, y: 0 };
+    _scrollTop = 0;
+    _scrollBottom;
+    _state = 0 /* State.Normal */;
+    _csiParams = "";
+    _csiPrivate = "";
+    displayBuffer;
+    constructor(cols, rows) {
+        this._cols = cols;
+        this._rows = rows;
+        this._scrollBottom = rows - 1;
+        this._screen = this._makeScreen(cols, rows);
+        this.displayBuffer = Object.defineProperties({}, {
+            cursorX: { get: () => this._cursorX, enumerable: true },
+            cursorY: { get: () => this._cursorY, enumerable: true },
+            data: { get: () => this._screen, enumerable: true },
+        });
+    }
+    write(data) {
+        for (const ch of data) {
+            this._feed(ch);
+        }
+    }
+    resize(cols, rows) {
+        // Adjust row count
+        while (this._screen.length < rows) {
+            this._screen.push(this._makeRow(cols));
+        }
+        this._screen.length = rows;
+        // Adjust col count for each row
+        for (let y = 0; y < rows; y++) {
+            const row = this._screen[y] ?? this._makeRow(cols);
+            while (row.length < cols)
+                row.push(null);
+            row.length = cols;
+            this._screen[y] = row;
+        }
+        this._cols = cols;
+        this._rows = rows;
+        this._scrollTop = 0;
+        this._scrollBottom = rows - 1;
+        this._cursorX = this._clamp(this._cursorX, 0, cols - 1);
+        this._cursorY = this._clamp(this._cursorY, 0, rows - 1);
+    }
+    _makeScreen(cols, rows) {
+        return Array.from({ length: rows }, () => this._makeRow(cols));
+    }
+    _makeRow(cols) {
+        return Array(cols).fill(null);
+    }
+    _clamp(value, min, max) {
+        return Math.max(min, Math.min(max, value));
+    }
+    _setChar(y, x, ch) {
+        const row = this._screen[y];
+        if (row && x >= 0 && x < this._cols) {
+            row[x] = [ch.charCodeAt(0), ch];
+        }
+    }
+    _eraseLine(y, fromX, toX) {
+        const row = this._screen[y];
+        if (!row)
+            return;
+        for (let x = fromX; x <= toX && x < this._cols; x++) {
+            row[x] = null;
+        }
+    }
+    _scrollUp(count) {
+        for (let i = 0; i < count; i++) {
+            this._screen.splice(this._scrollTop, 1);
+            this._screen.splice(this._scrollBottom, 0, this._makeRow(this._cols));
+        }
+    }
+    _scrollDown(count) {
+        for (let i = 0; i < count; i++) {
+            this._screen.splice(this._scrollBottom, 1);
+            this._screen.splice(this._scrollTop, 0, this._makeRow(this._cols));
+        }
+    }
+    _newline() {
+        if (this._cursorY === this._scrollBottom) {
+            this._scrollUp(1);
+        }
+        else {
+            this._cursorY = Math.min(this._cursorY + 1, this._rows - 1);
+        }
+    }
+    _parseCsiParams() {
+        if (!this._csiParams)
+            return [];
+        return this._csiParams.split(";").map((s) => (s === "" ? 0 : parseInt(s, 10)));
+    }
+    _execCsi(final) {
+        const params = this._parseCsiParams();
+        const p0 = params[0] ?? 0;
+        const p1 = params[1] ?? 0;
+        if (this._csiPrivate === "?") {
+            if (final === "h" || final === "l") {
+                // Only handle alt screen (1049) — ignore everything else
+                if (params.includes(1049)) {
+                    if (final === "h") {
+                        this._screen = this._makeScreen(this._cols, this._rows);
+                        this._cursorX = 0;
+                        this._cursorY = 0;
+                    }
+                    else {
+                        this._screen = this._makeScreen(this._cols, this._rows);
+                        this._cursorX = 0;
+                        this._cursorY = 0;
+                    }
+                }
+            }
+            return;
+        }
+        switch (final) {
+            case "A": // cursor up
+                this._cursorY = this._clamp(this._cursorY - Math.max(1, p0), 0, this._rows - 1);
+                break;
+            case "B": // cursor down
+                this._cursorY = this._clamp(this._cursorY + Math.max(1, p0), 0, this._rows - 1);
+                break;
+            case "C": // cursor forward
+            case "a":
+                this._cursorX = this._clamp(this._cursorX + Math.max(1, p0), 0, this._cols - 1);
+                break;
+            case "D": // cursor backward
+                this._cursorX = this._clamp(this._cursorX - Math.max(1, p0), 0, this._cols - 1);
+                break;
+            case "E": // cursor next line
+                this._cursorY = this._clamp(this._cursorY + Math.max(1, p0), 0, this._rows - 1);
+                this._cursorX = 0;
+                break;
+            case "F": // cursor preceding line
+                this._cursorY = this._clamp(this._cursorY - Math.max(1, p0), 0, this._rows - 1);
+                this._cursorX = 0;
+                break;
+            case "G": // cursor horizontal absolute
+            case "`":
+                this._cursorX = this._clamp(Math.max(1, p0) - 1, 0, this._cols - 1);
+                break;
+            case "H": // cursor position
+            case "f":
+                this._cursorY = this._clamp(Math.max(1, p0) - 1, 0, this._rows - 1);
+                this._cursorX = this._clamp(Math.max(1, p1) - 1, 0, this._cols - 1);
+                break;
+            case "I": // cursor forward tabulation
+                for (let i = 0; i < Math.max(1, p0); i++) {
+                    this._cursorX = Math.min(this._cols - 1, (Math.floor(this._cursorX / 8) + 1) * 8);
+                }
+                break;
+            case "J": // erase in display
+                if (p0 === 0) {
+                    this._eraseLine(this._cursorY, this._cursorX, this._cols - 1);
+                    for (let y = this._cursorY + 1; y < this._rows; y++)
+                        this._eraseLine(y, 0, this._cols - 1);
+                }
+                else if (p0 === 1) {
+                    for (let y = 0; y < this._cursorY; y++)
+                        this._eraseLine(y, 0, this._cols - 1);
+                    this._eraseLine(this._cursorY, 0, this._cursorX);
+                }
+                else if (p0 === 2 || p0 === 3) {
+                    for (let y = 0; y < this._rows; y++)
+                        this._eraseLine(y, 0, this._cols - 1);
+                }
+                break;
+            case "K": // erase in line
+                if (p0 === 0)
+                    this._eraseLine(this._cursorY, this._cursorX, this._cols - 1);
+                else if (p0 === 1)
+                    this._eraseLine(this._cursorY, 0, this._cursorX);
+                else if (p0 === 2)
+                    this._eraseLine(this._cursorY, 0, this._cols - 1);
+                break;
+            case "X": // erase characters (ECH)
+                this._eraseLine(this._cursorY, this._cursorX, this._cursorX + Math.max(1, p0) - 1);
+                break;
+            case "L": { // insert lines
+                const n = Math.max(1, p0);
+                for (let i = 0; i < n; i++) {
+                    this._screen.splice(this._scrollBottom, 1);
+                    this._screen.splice(this._cursorY, 0, this._makeRow(this._cols));
+                }
+                break;
+            }
+            case "M": { // delete lines
+                const n = Math.max(1, p0);
+                for (let i = 0; i < n; i++) {
+                    this._screen.splice(this._cursorY, 1);
+                    this._screen.splice(this._scrollBottom, 0, this._makeRow(this._cols));
+                }
+                break;
+            }
+            case "P": { // delete characters
+                const row = this._screen[this._cursorY];
+                if (row) {
+                    const n = Math.max(1, p0);
+                    row.splice(this._cursorX, n);
+                    while (row.length < this._cols)
+                        row.push(null);
+                }
+                break;
+            }
+            case "@": { // insert blank characters
+                const row = this._screen[this._cursorY];
+                if (row) {
+                    const n = Math.max(1, p0);
+                    for (let i = 0; i < n; i++)
+                        row.splice(this._cursorX, 0, null);
+                    row.splice(this._cols);
+                }
+                break;
+            }
+            case "S": // scroll up
+                this._scrollUp(Math.max(1, p0));
+                break;
+            case "T": // scroll down
+                if (params.length <= 1)
+                    this._scrollDown(Math.max(1, p0));
+                break;
+            case "Z": { // cursor backward tabulation
+                const n = Math.max(1, p0);
+                for (let i = 0; i < n; i++) {
+                    this._cursorX = Math.max(0, (Math.ceil(this._cursorX / 8) - 1) * 8);
+                }
+                break;
+            }
+            case "d": // line position absolute
+                this._cursorY = this._clamp(Math.max(1, p0) - 1, 0, this._rows - 1);
+                break;
+            case "e": // vertical position relative
+                this._cursorY = this._clamp(this._cursorY + Math.max(1, p0), 0, this._rows - 1);
+                break;
+            case "r": { // set scrolling region
+                const top = this._clamp(Math.max(1, p0) - 1, 0, this._rows - 1);
+                const bottom = this._clamp((p1 === 0 ? this._rows : p1) - 1, 0, this._rows - 1);
+                if (top < bottom) {
+                    this._scrollTop = top;
+                    this._scrollBottom = bottom;
+                }
+                this._cursorX = 0;
+                this._cursorY = 0;
+                break;
+            }
+            case "s": // save cursor
+                this._savedCursor = { x: this._cursorX, y: this._cursorY };
+                break;
+            case "u": // restore cursor
+                this._cursorX = this._clamp(this._savedCursor.x, 0, this._cols - 1);
+                this._cursorY = this._clamp(this._savedCursor.y, 0, this._rows - 1);
+                break;
+            case "m": // SGR — ignore (we don't track attributes)
+                break;
+            default:
+                break;
+        }
+    }
+    _feed(ch) {
+        const code = ch.charCodeAt(0);
+        switch (this._state) {
+            case 0 /* State.Normal */:
+                this._feedNormal(ch, code);
+                break;
+            case 1 /* State.Escape */:
+                this._feedEscape(ch, code);
+                break;
+            case 2 /* State.Csi */:
+                this._feedCsi(ch, code);
+                break;
+            case 3 /* State.Osc */:
+                // consume until BEL or ESC (ESC \ = ST)
+                if (code === 0x07 || code === 0x9c) {
+                    this._state = 0 /* State.Normal */;
+                }
+                else if (code === 0x1b) {
+                    // next char should be `\` — just return to normal, it will be consumed
+                    this._state = 0 /* State.Normal */;
+                }
+                break;
+            case 4 /* State.Str */:
+                // consume until ST (0x9c) or BEL
+                if (code === 0x9c || code === 0x07) {
+                    this._state = 0 /* State.Normal */;
+                }
+                else if (code === 0x1b) {
+                    this._state = 0 /* State.Normal */;
+                }
+                break;
+            case 5 /* State.EscCharset */:
+                // consume one character for charset designation
+                this._state = 0 /* State.Normal */;
+                break;
+            case 6 /* State.EscHash */:
+                // consume one character for line attributes
+                this._state = 0 /* State.Normal */;
+                break;
+        }
+    }
+    _feedNormal(ch, code) {
+        if (code === 0x1b) {
+            this._state = 1 /* State.Escape */;
+        }
+        else if (code === 0x9b) {
+            // C1 CSI
+            this._csiParams = "";
+            this._csiPrivate = "";
+            this._state = 2 /* State.Csi */;
+        }
+        else if (code === 0x9d) {
+            // C1 OSC
+            this._state = 3 /* State.Osc */;
+        }
+        else if (code === 0x90 || code === 0x98 || code === 0x9e || code === 0x9f) {
+            // DCS, SOS, PM, APC
+            this._state = 4 /* State.Str */;
+        }
+        else if (code === 0x07 || code === 0x05 || code === 0x06) {
+            // BEL, ENQ, ACK — ignore
+        }
+        else if (code === 0x08) {
+            // BS
+            if (this._cursorX > 0)
+                this._cursorX--;
+        }
+        else if (code === 0x7f) {
+            // DEL
+            if (this._cursorX > 0) {
+                this._cursorX--;
+                this._setChar(this._cursorY, this._cursorX, " ");
+            }
+        }
+        else if (code === 0x09) {
+            // HT
+            this._cursorX = Math.min(this._cols - 1, (Math.floor(this._cursorX / 8) + 1) * 8);
+        }
+        else if (code === 0x0a || code === 0x0b || code === 0x0c) {
+            // LF, VT, FF
+            this._newline();
+        }
+        else if (code === 0x0d) {
+            // CR
+            this._cursorX = 0;
+        }
+        else if (code === 0x0e || code === 0x0f) {
+            // SO, SI — charset switch, ignore
+        }
+        else if (code >= 0x20 && code !== 0x7f) {
+            // Printable character (including multi-byte Unicode via code points)
+            this._setChar(this._cursorY, this._cursorX, ch);
+            this._cursorX++;
+            if (this._cursorX >= this._cols) {
+                // Auto-wrap
+                this._cursorX = 0;
+                this._newline();
+            }
+        }
+    }
+    _feedEscape(ch, code) {
+        this._state = 0 /* State.Normal */;
+        if (code === 0x5b) {
+            // ESC [ = CSI
+            this._csiParams = "";
+            this._csiPrivate = "";
+            this._state = 2 /* State.Csi */;
+        }
+        else if (code === 0x5d) {
+            // ESC ] = OSC
+            this._state = 3 /* State.Osc */;
+        }
+        else if (code === 0x50 || code === 0x58 || code === 0x5e || code === 0x5f) {
+            // DCS, SOS, PM, APC
+            this._state = 4 /* State.Str */;
+        }
+        else if (code === 0x28 || code === 0x29 || code === 0x2a || code === 0x2b || code === 0x2d || code === 0x2e) {
+            // ESC ( ) * + - . = charset designation (consume next char)
+            this._state = 5 /* State.EscCharset */;
+        }
+        else if (code === 0x23) {
+            // ESC # = line attributes (consume next char)
+            this._state = 6 /* State.EscHash */;
+        }
+        else if (code === 0x37) {
+            // ESC 7 = save cursor
+            this._savedCursor = { x: this._cursorX, y: this._cursorY };
+        }
+        else if (code === 0x38) {
+            // ESC 8 = restore cursor
+            this._cursorX = this._clamp(this._savedCursor.x, 0, this._cols - 1);
+            this._cursorY = this._clamp(this._savedCursor.y, 0, this._rows - 1);
+        }
+        else if (code === 0x44) {
+            // ESC D = index (LF)
+            this._newline();
+        }
+        else if (code === 0x45) {
+            // ESC E = next line
+            this._cursorX = 0;
+            this._newline();
+        }
+        else if (code === 0x4d) {
+            // ESC M = reverse index
+            if (this._cursorY === this._scrollTop) {
+                this._scrollDown(1);
+            }
+            else {
+                this._cursorY = Math.max(0, this._cursorY - 1);
+            }
+        }
+        else if (code === 0x48) {
+            // ESC H = tab set (ignore)
+        }
+        else if (code === 0x63) {
+            // ESC c = full reset
+            this._screen = this._makeScreen(this._cols, this._rows);
+            this._cursorX = 0;
+            this._cursorY = 0;
+            this._savedCursor = { x: 0, y: 0 };
+            this._scrollTop = 0;
+            this._scrollBottom = this._rows - 1;
+        }
+        // All other ESC sequences: two-char, already consumed — ignore
+    }
+    _feedCsi(ch, code) {
+        if (code >= 0x40 && code <= 0x7e) {
+            // Final byte
+            this._execCsi(ch);
+            this._state = 0 /* State.Normal */;
+        }
+        else if (code === 0x3f || code === 0x21 || code === 0x3e || code === 0x20) {
+            // Private/intermediate marker (?, !, >, space)
+            this._csiPrivate = ch;
+        }
+        else if ((code >= 0x30 && code <= 0x39) || code === 0x3b) {
+            // Digit or semicolon — parameter byte
+            this._csiParams += ch;
+        }
+        // Other bytes ignored
+    }
+}

package/dist/terminal-pilot.d.ts

@@ -13,6 +13,7 @@ export declare class TerminalPilot {
     static launch(): Promise<TerminalPilot>;
     newSession(opts: NewSessionOptions): Promise<TerminalSession>;
     getSession(id: string): TerminalSession;
+    deleteSession(id: string): void;
     sessions(): TerminalSession[];
     close(): Promise<void>;
 }

package/dist/terminal-pilot.js

@@ -18,9 +18,6 @@ export class TerminalPilot {
             rows: opts.rows ?? DEFAULT_ROWS,
             observe: opts.observe ?? false
         });
-        session.on("exit", () => {
-            this.sessionMap.delete(session.id);
-        });
         this.sessionMap.set(session.id, session);
         return session;
     }
@@ -31,8 +28,11 @@ export class TerminalPilot {
         }
         return session;
     }
+    deleteSession(id) {
+        this.sessionMap.delete(id);
+    }
     sessions() {
-        return [...this.sessionMap.values()];
+        return [...this.sessionMap.values()].filter((s) => s.exitCode === null);
     }
     async close() {
         const sessions = [...this.sessionMap.values()];

package/dist/terminal-session.d.ts

@@ -42,6 +42,9 @@ export declare class TerminalSession {
     screen(): Promise<TerminalScreen>;
     history(opts?: HistoryOptions): Promise<string[]>;
     resize(cols: number, rows: number): Promise<void>;
+    waitForExit(opts?: {
+        timeout?: number;
+    }): Promise<number>;
     close(): Promise<number>;
     on(event: "exit", cb: (code: number) => void): void;
 }

package/dist/terminal-session.js

@@ -1,12 +1,10 @@
 import { spawn as spawnChildProcess } from "node:child_process";
 import { EventEmitter } from "node:events";
-import { createRequire } from "node:module";
 import * as nodePty from "node-pty";
 import { stripAnsi } from "./ansi.js";
+import { TerminalBuffer } from "./terminal-buffer.js";
 import { keyToSequence } from "./keys.js";
 import { TerminalScreen } from "./terminal-screen.js";
-const require = createRequire(import.meta.url);
-const HeadlessTerminal = require("headless-terminal");
 const DEFAULT_COLS = 120;
 const DEFAULT_ROWS = 40;
 const DEFAULT_TIMEOUT_MS = 10_000;
@@ -33,7 +31,7 @@ export class TerminalSession {
         this.command = command;
         this.currentCols = cols;
         this.currentRows = rows;
-        this.terminal = new HeadlessTerminal(cols, rows);
+        this.terminal = new TerminalBuffer(cols, rows);
         this.pty = createPtyProcess({ command, args, cwd, env, cols, rows });
         this.pid = this.pty.pid;
         const dataSubscription = this.pty.onData((chunk) => {
@@ -145,17 +143,31 @@ export class TerminalSession {
         }
         this.terminal.resize(cols, rows);
     }
+    async waitForExit(opts) {
+        if (this.exitCode !== null) {
+            return this.exitCode;
+        }
+        if (opts?.timeout !== undefined) {
+            const result = await waitForExit(this.exitPromise, opts.timeout);
+            if (result === null) {
+                throw new Error(`Timed out waiting for process to exit after ${opts.timeout}ms`);
+            }
+            return result;
+        }
+        return this.exitPromise;
+    }
     async close() {
         if (this.exitCode !== null) {
             return this.exitCode;
         }
         if (!this.closeRequested) {
             this.closeRequested = true;
+            const gracefulExitCode = await waitForExit(this.exitPromise, CLOSE_AFTER_SIGNAL_GRACE_MS);
+            if (gracefulExitCode !== null) {
+                return gracefulExitCode;
+            }
             if (this.signalRequested) {
-                const exitCode = await waitForExit(this.exitPromise, CLOSE_AFTER_SIGNAL_GRACE_MS);
-                if (exitCode !== null) {
-                    return exitCode;
-                }
+                return this.exitPromise;
             }
             if (this.exitCode === null) {
                 this.pty.kill("SIGTERM");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "terminal-pilot",
-  "version": "0.0.2",
-  "description": "Headless terminal session manager with MCP server support",
+  "version": "0.0.4",
+  "description": "Playwright-like SDK for automating interactive CLI apps through a real PTY",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,19 +9,12 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
-    },
-    "./mcp": {
-      "types": "./dist/mcp-server.d.ts",
-      "import": "./dist/mcp-server.js"
     }
   },
-  "bin": {
-    "terminal-pilot-mcp": "dist/mcp-server.js"
-  },
   "scripts": {
     "build": "tsc",
     "prepublishOnly": "tsc",
-    "install-local-package": "TMPD=$(mktemp -d) && cd ../tiny-stdio-mcp-server && npm pack --pack-destination $TMPD && cd ../terminal-pilot && npm pack --pack-destination $TMPD && npm install -g $TMPD/poe-code-terminal-pilot-*.tgz $TMPD/tiny-stdio-mcp-server-*.tgz && rm -rf $TMPD"
+    "install-local-package": "TMPD=$(mktemp -d) && npm pack --pack-destination $TMPD && npm install -g $TMPD/terminal-pilot-*.tgz && rm -rf $TMPD"
   },
   "files": [
     "dist"
@@ -37,14 +30,11 @@
   "license": "MIT",
   "keywords": [
     "terminal",
-    "mcp",
     "pty",
     "headless"
   ],
   "dependencies": {
-    "headless-terminal": "^0.4.0",
-    "node-pty": "^1.1.0",
-    "tiny-stdio-mcp-server": "^0.1.0"
+    "node-pty": "^1.1.0"
   },
   "devDependencies": {}
 }

package/dist/mcp-server.d.ts

@@ -1,11 +0,0 @@
-#!/usr/bin/env node
-import { type Server } from "tiny-stdio-mcp-server";
-import { TerminalPilot } from "./terminal-pilot.js";
-type RuntimeProcess = Pick<typeof process, "on" | "off">;
-export declare function createTerminalPilotMcpServer(agent: TerminalPilot): Server;
-export declare function main({ launchAgent, createMcpServer, runtimeProcess }?: {
-    launchAgent?: typeof TerminalPilot.launch;
-    createMcpServer?: (agent: TerminalPilot) => Server;
-    runtimeProcess?: RuntimeProcess;
-}): Promise<void>;
-export {};

package/dist/mcp-server.js

@@ -1,40 +0,0 @@
-#!/usr/bin/env node
-import packageJson from "../package.json" with { type: "json" };
-import { createServer } from "tiny-stdio-mcp-server";
-import { terminalPilotMcpTools } from "./mcp-tools.js";
-import { TerminalPilot } from "./terminal-pilot.js";
-export function createTerminalPilotMcpServer(agent) {
-    const server = createServer({
-        name: "terminal-pilot",
-        version: packageJson.version
-    });
-    for (const tool of terminalPilotMcpTools(agent)) {
-        server.tool(tool.name, tool.description, tool.inputSchema, tool.handler);
-    }
-    return server;
-}
-export async function main({ launchAgent = TerminalPilot.launch, createMcpServer = createTerminalPilotMcpServer, runtimeProcess = process } = {}) {
-    const agent = await launchAgent();
-    let closed = false;
-    const closeAgent = async () => {
-        if (closed) {
-            return;
-        }
-        closed = true;
-        await agent.close();
-    };
-    const handleExit = () => {
-        void closeAgent();
-    };
-    runtimeProcess.on("exit", handleExit);
-    try {
-        await createMcpServer(agent).listen();
-    }
-    finally {
-        runtimeProcess.off("exit", handleExit);
-        await closeAgent();
-    }
-}
-if (import.meta.url === `file://${process.argv[1]}`) {
-    void main();
-}

package/dist/mcp-tools.d.ts

@@ -1,46 +0,0 @@
-import { type ToolDefinition } from "tiny-stdio-mcp-server";
-import type { TerminalKey } from "./keys.js";
-import type { TerminalPilot } from "./terminal-pilot.js";
-export type TerminalPilotMcpTool<T = Record<string, unknown>> = ToolDefinition<T>;
-export declare function terminalCreateSessionTool(agent: TerminalPilot): TerminalPilotMcpTool<{
-    command: string;
-    args?: string[];
-    cwd?: string;
-    cols?: number;
-    rows?: number;
-    observe?: boolean;
-}>;
-export declare function terminalTypeTool(agent: TerminalPilot): TerminalPilotMcpTool<{
-    sessionId: string;
-    text: string;
-}>;
-export declare function terminalPressKeyTool(agent: TerminalPilot): TerminalPilotMcpTool<{
-    sessionId: string;
-    key: TerminalKey;
-}>;
-export declare function terminalSendSignalTool(agent: TerminalPilot): TerminalPilotMcpTool<{
-    sessionId: string;
-    signal: string;
-}>;
-export declare function terminalWaitForTool(agent: TerminalPilot): TerminalPilotMcpTool<{
-    sessionId: string;
-    pattern: string;
-    timeout?: number;
-}>;
-export declare function terminalReadScreenTool(agent: TerminalPilot): TerminalPilotMcpTool<{
-    sessionId: string;
-}>;
-export declare function terminalReadHistoryTool(agent: TerminalPilot): TerminalPilotMcpTool<{
-    sessionId: string;
-    last?: number;
-}>;
-export declare function terminalResizeTool(agent: TerminalPilot): TerminalPilotMcpTool<{
-    sessionId: string;
-    cols: number;
-    rows: number;
-}>;
-export declare function terminalCloseSessionTool(agent: TerminalPilot): TerminalPilotMcpTool<{
-    sessionId: string;
-}>;
-export declare function terminalPilotMcpTools(agent: TerminalPilot): Array<TerminalPilotMcpTool<any>>;
-export declare function terminalListSessionsTool(agent: TerminalPilot): TerminalPilotMcpTool<Record<string, never>>;

package/dist/mcp-tools.js

@@ -1,169 +0,0 @@
-import { defineSchema } from "tiny-stdio-mcp-server";
-export function terminalCreateSessionTool(agent) {
-    return {
-        name: "terminal_create_session",
-        description: "Spawn an interactive CLI in a PTY",
-        inputSchema: defineSchema({
-            command: { type: "string", description: "Command to execute" },
-            args: { type: "array", description: "Command arguments", optional: true },
-            cwd: { type: "string", description: "Working directory", optional: true },
-            cols: { type: "number", description: "Terminal width in columns", optional: true },
-            rows: { type: "number", description: "Terminal height in rows", optional: true },
-            observe: { type: "boolean", description: "Mirror PTY output to stderr", optional: true }
-        }),
-        async handler(input) {
-            const session = await agent.newSession(input);
-            return { sessionId: session.id, pid: session.pid };
-        }
-    };
-}
-export function terminalTypeTool(agent) {
-    return {
-        name: "terminal_type",
-        description: "Write text to an active terminal session",
-        inputSchema: defineSchema({
-            sessionId: { type: "string", description: "Terminal session id" },
-            text: { type: "string", description: "Text to write to the session" }
-        }),
-        async handler(input) {
-            await agent.getSession(input.sessionId).fill(input.text);
-            return undefined;
-        }
-    };
-}
-export function terminalPressKeyTool(agent) {
-    return {
-        name: "terminal_press_key",
-        description: "Send a named key press to an active terminal session",
-        inputSchema: defineSchema({
-            sessionId: { type: "string", description: "Terminal session id" },
-            key: { type: "string", description: "Named key to press" }
-        }),
-        async handler(input) {
-            await agent.getSession(input.sessionId).press(input.key);
-            return undefined;
-        }
-    };
-}
-export function terminalSendSignalTool(agent) {
-    return {
-        name: "terminal_send_signal",
-        description: "Send a process signal to an active terminal session",
-        inputSchema: defineSchema({
-            sessionId: { type: "string", description: "Terminal session id" },
-            signal: { type: "string", description: "Signal to send to the session process" }
-        }),
-        async handler(input) {
-            await agent.getSession(input.sessionId).signal(input.signal);
-            return undefined;
-        }
-    };
-}
-export function terminalWaitForTool(agent) {
-    return {
-        name: "terminal_wait_for",
-        description: "Wait for terminal output to match a pattern",
-        inputSchema: defineSchema({
-            sessionId: { type: "string", description: "Terminal session id" },
-            pattern: { type: "string", description: "Regular expression pattern to wait for" },
-            timeout: { type: "number", description: "Maximum wait time in milliseconds", optional: true }
-        }),
-        async handler(input) {
-            const session = agent.getSession(input.sessionId);
-            const pattern = new RegExp(input.pattern);
-            const line = input.timeout === undefined
-                ? await session.waitFor(pattern)
-                : await session.waitFor(pattern, { timeout: input.timeout });
-            return { matched: true, line };
-        }
-    };
-}
-export function terminalReadScreenTool(agent) {
-    return {
-        name: "terminal_read_screen",
-        description: "Read the current visible terminal screen",
-        inputSchema: defineSchema({
-            sessionId: { type: "string", description: "Terminal session id" }
-        }),
-        async handler(input) {
-            const screen = await agent.getSession(input.sessionId).screen();
-            return {
-                lines: [...screen.lines],
-                cursor: { ...screen.cursor },
-                size: { ...screen.size }
-            };
-        }
-    };
-}
-export function terminalReadHistoryTool(agent) {
-    return {
-        name: "terminal_read_history",
-        description: "Read terminal output history",
-        inputSchema: defineSchema({
-            sessionId: { type: "string", description: "Terminal session id" },
-            last: { type: "number", description: "Return only the last N lines", optional: true }
-        }),
-        async handler(input) {
-            const lines = await agent.getSession(input.sessionId).history({ last: input.last });
-            return { lines };
-        }
-    };
-}
-export function terminalResizeTool(agent) {
-    return {
-        name: "terminal_resize",
-        description: "Resize an active terminal session",
-        inputSchema: defineSchema({
-            sessionId: { type: "string", description: "Terminal session id" },
-            cols: { type: "number", description: "Terminal width in columns" },
-            rows: { type: "number", description: "Terminal height in rows" }
-        }),
-        async handler(input) {
-            await agent.getSession(input.sessionId).resize(input.cols, input.rows);
-            return undefined;
-        }
-    };
-}
-export function terminalCloseSessionTool(agent) {
-    return {
-        name: "terminal_close_session",
-        description: "Close an active terminal session",
-        inputSchema: defineSchema({
-            sessionId: { type: "string", description: "Terminal session id" }
-        }),
-        async handler(input) {
-            const exitCode = await agent.getSession(input.sessionId).close();
-            return { exitCode };
-        }
-    };
-}
-export function terminalPilotMcpTools(agent) {
-    return [
-        terminalCreateSessionTool(agent),
-        terminalTypeTool(agent),
-        terminalPressKeyTool(agent),
-        terminalSendSignalTool(agent),
-        terminalWaitForTool(agent),
-        terminalReadScreenTool(agent),
-        terminalReadHistoryTool(agent),
-        terminalResizeTool(agent),
-        terminalCloseSessionTool(agent),
-        terminalListSessionsTool(agent)
-    ];
-}
-export function terminalListSessionsTool(agent) {
-    return {
-        name: "terminal_list_sessions",
-        description: "List active terminal sessions",
-        inputSchema: defineSchema({}),
-        async handler() {
-            return {
-                sessions: agent.sessions().map((session) => ({
-                    id: session.id,
-                    command: session.command,
-                    pid: session.pid
-                }))
-            };
-        }
-    };
-}