terminal-pilot 0.0.1

package/dist/mcp-tools.js

@@ -0,0 +1,169 @@
+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 output = input.timeout === undefined
+                ? await session.waitFor(pattern)
+                : await session.waitFor(pattern, { timeout: input.timeout });
+            return { matched: true, output };
+        }
+    };
+}
+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
+                }))
+            };
+        }
+    };
+}

package/dist/terminal-pilot.d.ts

@@ -0,0 +1,18 @@
+import { TerminalSession } from "./terminal-session.js";
+export interface NewSessionOptions {
+    command: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    cols?: number;
+    rows?: number;
+    observe?: boolean;
+}
+export declare class TerminalPilot {
+    private readonly sessionMap;
+    static launch(): Promise<TerminalPilot>;
+    newSession(opts: NewSessionOptions): Promise<TerminalSession>;
+    getSession(id: string): TerminalSession;
+    sessions(): TerminalSession[];
+    close(): Promise<void>;
+}

package/dist/terminal-pilot.js

@@ -0,0 +1,46 @@
+import { randomUUID } from "node:crypto";
+import { TerminalSession } from "./terminal-session.js";
+const DEFAULT_COLS = 120;
+const DEFAULT_ROWS = 40;
+export class TerminalPilot {
+    sessionMap = new Map();
+    static async launch() {
+        return new TerminalPilot();
+    }
+    async newSession(opts) {
+        const session = new TerminalSession({
+            id: randomUUID(),
+            command: opts.command,
+            args: opts.args,
+            cwd: opts.cwd,
+            env: opts.env,
+            cols: opts.cols ?? DEFAULT_COLS,
+            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;
+    }
+    getSession(id) {
+        const session = this.sessionMap.get(id);
+        if (session === undefined) {
+            throw new Error(`Session not found: ${id}`);
+        }
+        return session;
+    }
+    sessions() {
+        return [...this.sessionMap.values()];
+    }
+    async close() {
+        const sessions = [...this.sessionMap.values()];
+        try {
+            await Promise.all(sessions.map((session) => session.close()));
+        }
+        finally {
+            this.sessionMap.clear();
+        }
+    }
+}

package/dist/terminal-screen.d.ts

@@ -0,0 +1,27 @@
+export declare class TerminalScreen {
+    readonly lines: readonly string[];
+    readonly rawLines: readonly string[];
+    readonly cursor: {
+        row: number;
+        col: number;
+    };
+    readonly size: {
+        rows: number;
+        cols: number;
+    };
+    constructor({ lines, rawLines, cursor, size }: {
+        lines: string[];
+        rawLines: string[];
+        cursor: {
+            row: number;
+            col: number;
+        };
+        size: {
+            rows: number;
+            cols: number;
+        };
+    });
+    get text(): string;
+    contains(substring: string): boolean;
+    line(index: number): string;
+}

package/dist/terminal-screen.js

@@ -0,0 +1,28 @@
+import { stripAnsi } from "./ansi.js";
+export class TerminalScreen {
+    lines;
+    rawLines;
+    cursor;
+    size;
+    constructor({ lines, rawLines, cursor, size }) {
+        this.lines = Object.freeze(lines.map((line) => stripAnsi(line)));
+        this.rawLines = Object.freeze([...rawLines]);
+        this.cursor = Object.freeze({ ...cursor });
+        this.size = Object.freeze({ ...size });
+        Object.freeze(this);
+    }
+    get text() {
+        return this.lines.join("\n");
+    }
+    contains(substring) {
+        return this.text.includes(substring);
+    }
+    line(index) {
+        const normalizedIndex = index < 0 ? this.lines.length + index : index;
+        const line = this.lines[normalizedIndex];
+        if (line === undefined) {
+            throw new RangeError(`Line index out of bounds: ${index}`);
+        }
+        return line;
+    }
+}

package/dist/terminal-session.d.ts

@@ -0,0 +1,48 @@
+import { type TerminalKey } from "./keys.js";
+import { TerminalScreen } from "./terminal-screen.js";
+type TerminalSessionOptions = {
+    id: string;
+    command: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    cols?: number;
+    rows?: number;
+    observe?: boolean;
+};
+export type WaitForOptions = {
+    timeout?: number;
+};
+export type HistoryOptions = {
+    last?: number;
+};
+export declare class TerminalSession {
+    readonly id: string;
+    readonly command: string;
+    readonly pid: number;
+    exitCode: number | null;
+    private readonly pty;
+    private readonly terminal;
+    private readonly emitter;
+    private readonly exitPromise;
+    private rawBuffer;
+    private lastDataAt;
+    private currentCols;
+    private currentRows;
+    private closeRequested;
+    private signalRequested;
+    constructor({ id, command, args, cwd, env, cols, rows, observe }: TerminalSessionOptions);
+    type(text: string): Promise<void>;
+    fill(text: string): Promise<void>;
+    press(key: TerminalKey): Promise<void>;
+    send(raw: string): Promise<void>;
+    signal(sig: string): Promise<void>;
+    waitFor(pattern: string | RegExp, opts?: WaitForOptions): Promise<string>;
+    waitForQuiet(ms: number): Promise<void>;
+    screen(): Promise<TerminalScreen>;
+    history(opts?: HistoryOptions): Promise<string[]>;
+    resize(cols: number, rows: number): Promise<void>;
+    close(): Promise<number>;
+    on(event: "exit", cb: (code: number) => void): void;
+}
+export {};

package/dist/terminal-session.js

@@ -0,0 +1,320 @@
+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 { 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;
+const WAIT_FOR_POLL_MS = 100;
+const TYPE_DELAY_MS = 15;
+const CLOSE_AFTER_SIGNAL_GRACE_MS = 250;
+export class TerminalSession {
+    id;
+    command;
+    pid;
+    exitCode = null;
+    pty;
+    terminal;
+    emitter = new EventEmitter();
+    exitPromise;
+    rawBuffer = "";
+    lastDataAt = Date.now();
+    currentCols;
+    currentRows;
+    closeRequested = false;
+    signalRequested = false;
+    constructor({ id, command, args = [], cwd = process.cwd(), env = process.env, cols = DEFAULT_COLS, rows = DEFAULT_ROWS, observe = false }) {
+        this.id = id;
+        this.command = command;
+        this.currentCols = cols;
+        this.currentRows = rows;
+        this.terminal = new HeadlessTerminal(cols, rows);
+        this.pty = createPtyProcess({ command, args, cwd, env, cols, rows });
+        this.pid = this.pty.pid;
+        const dataSubscription = this.pty.onData((chunk) => {
+            this.rawBuffer += chunk;
+            this.lastDataAt = Date.now();
+            this.terminal.write(chunk);
+            if (observe) {
+                process.stderr.write(chunk);
+            }
+        });
+        let exitSubscription;
+        this.exitPromise = new Promise((resolve) => {
+            exitSubscription = this.pty.onExit(({ exitCode }) => {
+                if (this.exitCode !== null) {
+                    resolve(this.exitCode);
+                    return;
+                }
+                this.exitCode = exitCode;
+                dataSubscription.dispose();
+                exitSubscription?.dispose();
+                this.emitter.emit("exit", exitCode);
+                resolve(exitCode);
+            });
+        });
+    }
+    async type(text) {
+        for (const character of text) {
+            await this.send(character);
+            await sleep(TYPE_DELAY_MS);
+        }
+    }
+    async fill(text) {
+        await this.send(text);
+    }
+    async press(key) {
+        await this.send(keyToSequence(key));
+    }
+    async send(raw) {
+        if (this.exitCode !== null) {
+            return;
+        }
+        this.pty.write(raw);
+    }
+    async signal(sig) {
+        if (this.exitCode !== null) {
+            return;
+        }
+        this.signalRequested = true;
+        this.pty.kill(sig);
+    }
+    async waitFor(pattern, opts) {
+        const timeout = opts?.timeout ?? DEFAULT_TIMEOUT_MS;
+        const startedAt = Date.now();
+        while (Date.now() - startedAt <= timeout) {
+            const matched = matchPattern(this.rawBuffer, pattern);
+            if (matched !== null) {
+                return matched;
+            }
+            await sleep(WAIT_FOR_POLL_MS);
+        }
+        throw new Error(`Timed out waiting for pattern after ${timeout}ms: ${String(pattern)}`);
+    }
+    async waitForQuiet(ms) {
+        while (true) {
+            const remaining = ms - (Date.now() - this.lastDataAt);
+            if (remaining <= 0) {
+                return;
+            }
+            await sleep(remaining);
+        }
+    }
+    async screen() {
+        const rawLines = [];
+        for (let row = 0; row < this.currentRows; row += 1) {
+            const cells = this.terminal.displayBuffer.data[row] ?? [];
+            let rawLine = "";
+            for (const cell of cells) {
+                rawLine += cell?.[1] ?? " ";
+            }
+            rawLines.push(trimTrailingSpaces(rawLine));
+        }
+        return new TerminalScreen({
+            lines: rawLines,
+            rawLines,
+            cursor: {
+                row: this.terminal.displayBuffer.cursorY,
+                col: this.terminal.displayBuffer.cursorX
+            },
+            size: {
+                rows: this.currentRows,
+                cols: this.currentCols
+            }
+        });
+    }
+    async history(opts) {
+        const normalized = normalizeHistoryBuffer(stripAnsi(this.rawBuffer));
+        const lines = splitHistoryLines(normalized);
+        if (opts?.last === undefined) {
+            return lines;
+        }
+        const start = Math.max(0, lines.length - opts.last);
+        return lines.slice(start);
+    }
+    async resize(cols, rows) {
+        this.currentCols = cols;
+        this.currentRows = rows;
+        this.pty.resize(cols, rows);
+        this.terminal.resize(cols, rows);
+    }
+    async close() {
+        if (this.exitCode !== null) {
+            return this.exitCode;
+        }
+        if (!this.closeRequested) {
+            this.closeRequested = true;
+            if (this.signalRequested) {
+                const exitCode = await waitForExit(this.exitPromise, CLOSE_AFTER_SIGNAL_GRACE_MS);
+                if (exitCode !== null) {
+                    return exitCode;
+                }
+            }
+            if (this.exitCode === null) {
+                this.pty.kill("SIGTERM");
+            }
+        }
+        return this.exitPromise;
+    }
+    on(event, cb) {
+        this.emitter.on(event, cb);
+    }
+}
+function createPtyProcess({ command, args, cwd, env, cols, rows }) {
+    try {
+        return nodePty.spawn(command, args, {
+            cwd,
+            env,
+            cols,
+            rows,
+            encoding: "utf8"
+        });
+    }
+    catch {
+        return createChildProcessFallback({ command, args, cwd, env });
+    }
+}
+function createChildProcessFallback({ command, args, cwd, env }) {
+    const child = spawnChildProcess(command, args, {
+        cwd,
+        env,
+        stdio: ["pipe", "pipe", "pipe"]
+    });
+    return new ChildProcessFallback(child);
+}
+class ChildProcessFallback {
+    pid;
+    child;
+    dataEmitter = new EventEmitter();
+    exitEmitter = new EventEmitter();
+    constructor(child) {
+        this.child = child;
+        this.pid = child.pid ?? -1;
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", this.handleData);
+        child.stderr.on("data", this.handleData);
+        child.on("exit", (exitCode, signal) => {
+            this.exitEmitter.emit("exit", {
+                exitCode: exitCode ?? signalToExitCode(signal),
+                signal: undefined
+            });
+        });
+    }
+    write(data) {
+        this.child.stdin.write(data);
+    }
+    resize() {
+        // No-op in fallback mode.
+    }
+    kill(signal) {
+        this.child.kill(signal);
+    }
+    onData(listener) {
+        this.dataEmitter.on("data", listener);
+        return {
+            dispose: () => {
+                this.dataEmitter.off("data", listener);
+            }
+        };
+    }
+    onExit(listener) {
+        this.exitEmitter.on("exit", listener);
+        return {
+            dispose: () => {
+                this.exitEmitter.off("exit", listener);
+            }
+        };
+    }
+    handleData = (chunk) => {
+        this.dataEmitter.emit("data", String(chunk));
+    };
+}
+function signalToExitCode(signal) {
+    if (signal === null) {
+        return 0;
+    }
+    const signalNumbers = {
+        SIGTERM: 15,
+        SIGINT: 2,
+        SIGHUP: 1,
+        SIGKILL: 9
+    };
+    const signalNumber = signalNumbers[signal];
+    if (signalNumber === undefined) {
+        return 1;
+    }
+    return 128 + signalNumber;
+}
+function matchPattern(buffer, pattern) {
+    if (typeof pattern === "string") {
+        return buffer.includes(pattern) ? pattern : null;
+    }
+    const flags = removeCharacter(pattern.flags, "g");
+    const localPattern = new RegExp(pattern.source, flags);
+    const match = localPattern.exec(buffer);
+    return match?.[0] ?? null;
+}
+function removeCharacter(input, charToRemove) {
+    let output = "";
+    for (const character of input) {
+        if (character !== charToRemove) {
+            output += character;
+        }
+    }
+    return output;
+}
+function splitHistoryLines(input) {
+    const lines = input.split("\n");
+    if (lines.length > 0 && lines[lines.length - 1] === "") {
+        lines.pop();
+    }
+    return lines;
+}
+function normalizeHistoryBuffer(input) {
+    let output = "";
+    for (const character of input) {
+        if (character === "\r" || character === "\b") {
+            continue;
+        }
+        output += character;
+    }
+    return output;
+}
+function trimTrailingSpaces(input) {
+    let end = input.length;
+    while (end > 0 && input[end - 1] === " ") {
+        end -= 1;
+    }
+    return input.slice(0, end);
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+async function waitForExit(exitPromise, timeout) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            resolve(null);
+        }, timeout);
+        void exitPromise.then((code) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            resolve(code);
+        });
+    });
+}

package/dist/testing/menu-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env tsx
+export {};