@av-pi-studio/server 0.0.1

package/dist/terminal/pty-backend.js

@@ -0,0 +1,119 @@
+import { spawn } from "node:child_process";
+import nodePty from "node-pty";
+import treeKill from "tree-kill";
+import which from "which";
+const encoder = new TextEncoder();
+/**
+ * Resolve a shell/binary name to an absolute path via `$PATH` (cross-platform, honors Windows
+ * PATHEXT). Returns the input unchanged when it already looks like a path or cannot be resolved
+ * (the spawn will then surface a clear ENOENT).
+ */
+export function resolveExecutable(bin, env = process.env) {
+    if (bin.includes("/") || bin.includes("\\"))
+        return bin;
+    const resolved = which.sync(bin, { nothrow: true, path: env.PATH ?? env.Path });
+    return resolved ?? bin;
+}
+/** Best-effort termination of a whole process tree (kills orphaned grandchildren too). */
+function killTree(pid, signal = "SIGTERM") {
+    if (pid === undefined)
+        return;
+    treeKill(pid, signal, () => {
+        // Best-effort: ignore errors (process may already be gone).
+    });
+}
+/** Production backend: a real PTY via `node-pty`. */
+export class NodePtyBackend {
+    spawn(opts) {
+        const shell = resolveExecutable(opts.shell, opts.env ?? process.env);
+        const proc = nodePty.spawn(shell, opts.args ?? [], {
+            name: "xterm-256color",
+            cols: opts.cols,
+            rows: opts.rows,
+            cwd: opts.cwd,
+            env: { ...process.env, ...opts.env },
+        });
+        return {
+            write: (data) => proc.write(Buffer.from(data).toString("utf8")),
+            resize: (cols, rows) => {
+                try {
+                    proc.resize(cols, rows);
+                }
+                catch {
+                    // PTY may have exited between the size change and this call; ignore.
+                }
+            },
+            kill: () => {
+                killTree(proc.pid);
+                try {
+                    proc.kill();
+                }
+                catch {
+                    // Already exited.
+                }
+            },
+            onData: (cb) => {
+                proc.onData((s) => cb(encoder.encode(s)));
+            },
+            onExit: (cb) => {
+                proc.onExit(({ exitCode }) => cb(exitCode));
+            },
+        };
+    }
+}
+/** Fallback backend: a piped child process. Not a real TTY, but streams stdout/stderr ⇄ stdin. */
+export class ChildProcessPtyBackend {
+    spawn(opts) {
+        const child = spawn(resolveExecutable(opts.shell, opts.env ?? process.env), opts.args ?? [], {
+            cwd: opts.cwd,
+            env: { ...process.env, ...opts.env },
+            windowsHide: true,
+        });
+        const dataCbs = [];
+        const exitCbs = [];
+        const emit = (chunk) => {
+            const bytes = new Uint8Array(chunk);
+            for (const cb of dataCbs)
+                cb(bytes);
+        };
+        child.stdout?.on("data", emit);
+        child.stderr?.on("data", emit);
+        child.on("exit", (code) => {
+            for (const cb of exitCbs)
+                cb(code);
+        });
+        return {
+            write: (data) => {
+                child.stdin?.write(Buffer.from(data));
+            },
+            resize: () => {
+                // No-op for piped child processes (no TTY); the node-pty backend calls `pty.resize`.
+            },
+            kill: () => {
+                killTree(child.pid);
+                child.kill();
+            },
+            onData: (cb) => {
+                dataCbs.push(cb);
+            },
+            onExit: (cb) => {
+                exitCbs.push(cb);
+            },
+        };
+    }
+}
+/**
+ * Default backend factory: prefer the real PTY (`node-pty`); if the native module cannot be loaded
+ * on this platform, fall back to the piped child-process backend.
+ */
+export function createDefaultPtyBackend() {
+    try {
+        // Touch the native binding so an unsupported platform fails here, not on first spawn.
+        void nodePty.spawn;
+        return new NodePtyBackend();
+    }
+    catch {
+        return new ChildProcessPtyBackend();
+    }
+}
+//# sourceMappingURL=pty-backend.js.map

package/dist/terminal/pty-backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pty-backend.js","sourceRoot":"","sources":["../../src/terminal/pty-backend.ts"],"names":[],"mappings":"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"}

package/dist/terminal/screen-buffer.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Server-side terminal screen model backed by `@xterm/headless` (features/terminals.md § capture).
+ *
+ * The binary Snapshot frame sent to subscribing clients is the raw byte ring (each client's own
+ * xterm replays it faithfully). But CLI/MCP `capture()` needs the *visible grid as text* — replaying
+ * raw bytes through `strip-ansi` is wrong for anything that moves the cursor, clears the screen, or
+ * redraws (progress bars, full-screen apps). Feeding the byte stream through a headless terminal and
+ * reading the grid yields the true on-screen text.
+ */
+export declare class ScreenBuffer {
+    private readonly term;
+    constructor(cols: number, rows: number, scrollback?: number);
+    write(data: Uint8Array): void;
+    resize(cols: number, rows: number): void;
+    /** Resolve once the parser has drained all pending writes (used by tests / before capture). */
+    flush(): Promise<void>;
+    /** The visible viewport as plain text, with trailing blank lines trimmed. */
+    snapshotText(): string;
+    dispose(): void;
+}
+//# sourceMappingURL=screen-buffer.d.ts.map

package/dist/terminal/screen-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"screen-buffer.d.ts","sourceRoot":"","sources":["../../src/terminal/screen-buffer.ts"],"names":[],"mappings":"AAWA;;;;;;;;GAQG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAmB;gBAE5B,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,SAAO;IAIzD,KAAK,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAI7B,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAQxC,+FAA+F;IAC/F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,6EAA6E;IAC7E,YAAY,IAAI,MAAM;IAatB,OAAO,IAAI,IAAI;CAGhB"}

package/dist/terminal/screen-buffer.js

@@ -0,0 +1,55 @@
+import { createRequire } from "node:module";
+import stripAnsi from "strip-ansi";
+// `@xterm/headless` ships a UMD bundle whose `module.exports` Node's ESM loader cannot statically
+// read, so a named `import { Terminal }` resolves at type-check time but throws at runtime. Load it
+// through `createRequire` (CJS) to get the real `Terminal` constructor.
+const require = createRequire(import.meta.url);
+const { Terminal } = require("@xterm/headless");
+/**
+ * Server-side terminal screen model backed by `@xterm/headless` (features/terminals.md § capture).
+ *
+ * The binary Snapshot frame sent to subscribing clients is the raw byte ring (each client's own
+ * xterm replays it faithfully). But CLI/MCP `capture()` needs the *visible grid as text* — replaying
+ * raw bytes through `strip-ansi` is wrong for anything that moves the cursor, clears the screen, or
+ * redraws (progress bars, full-screen apps). Feeding the byte stream through a headless terminal and
+ * reading the grid yields the true on-screen text.
+ */
+export class ScreenBuffer {
+    term;
+    constructor(cols, rows, scrollback = 1000) {
+        this.term = new Terminal({ cols, rows, scrollback, allowProposedApi: true });
+    }
+    write(data) {
+        this.term.write(Buffer.from(data));
+    }
+    resize(cols, rows) {
+        try {
+            this.term.resize(cols, rows);
+        }
+        catch {
+            // Ignore invalid dimensions (e.g. 0); the live PTY resize already guards this.
+        }
+    }
+    /** Resolve once the parser has drained all pending writes (used by tests / before capture). */
+    flush() {
+        return new Promise((resolve) => this.term.write("", () => resolve()));
+    }
+    /** The visible viewport as plain text, with trailing blank lines trimmed. */
+    snapshotText() {
+        const buf = this.term.buffer.active;
+        const top = buf.baseY;
+        const lines = [];
+        for (let y = top; y < top + this.term.rows; y++) {
+            const line = buf.getLine(y);
+            lines.push(line ? line.translateToString(true) : "");
+        }
+        while (lines.length > 0 && lines[lines.length - 1].trim() === "")
+            lines.pop();
+        // translateToString already yields plain text; strip-ansi defends against any passthrough.
+        return stripAnsi(lines.join("\n"));
+    }
+    dispose() {
+        this.term.dispose();
+    }
+}
+//# sourceMappingURL=screen-buffer.js.map

package/dist/terminal/screen-buffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"screen-buffer.js","sourceRoot":"","sources":["../../src/terminal/screen-buffer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,SAAS,MAAM,YAAY,CAAC;AAEnC,kGAAkG;AAClG,oGAAoG;AACpG,wEAAwE;AACxE,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,iBAAiB,CAAqC,CAAC;AAGpF;;;;;;;;GAQG;AACH,MAAM,OAAO,YAAY;IACN,IAAI,CAAmB;IAExC,YAAY,IAAY,EAAE,IAAY,EAAE,UAAU,GAAG,IAAI;QACvD,IAAI,CAAC,IAAI,GAAG,IAAI,QAAQ,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,gBAAgB,EAAE,IAAI,EAAE,CAAC,CAAC;IAC/E,CAAC;IAED,KAAK,CAAC,IAAgB;QACpB,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACrC,CAAC;IAED,MAAM,CAAC,IAAY,EAAE,IAAY;QAC/B,IAAI,CAAC;YACH,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,+EAA+E;QACjF,CAAC;IACH,CAAC;IAED,+FAA+F;IAC/F,KAAK;QACH,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IACxE,CAAC;IAED,6EAA6E;IAC7E,YAAY;QACV,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;QACpC,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC;QACtB,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,KAAK,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC,GAAG,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;YAChD,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;YAC5B,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACvD,CAAC;QACD,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC,IAAI,EAAE,KAAK,EAAE;YAAE,KAAK,CAAC,GAAG,EAAE,CAAC;QAC/E,2FAA2F;QAC3F,OAAO,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACrC,CAAC;IAED,OAAO;QACL,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;IACtB,CAAC;CACF"}

package/dist/terminal/terminal-manager.d.ts

@@ -0,0 +1,79 @@
+import { type PtyBackend } from "./pty-backend.js";
+/**
+ * Workspace-scoped PTY terminal manager (features/terminals.md § Behavior, § PTY size ownership,
+ * § Output coalescing). PTYs are multiplexed over the binary terminal stream protocol by `slot`.
+ *
+ * Size ownership is **last-interacting-client-wins** and is a client concern: the manager only
+ * resizes the PTY when a client explicitly sends a Resize (genuine viewport change / focus). It
+ * NEVER resizes on subscribe/attach, and never broadcasts resize ownership — a resized PTY simply
+ * redraws via normal Output, which every attached client renders in its own viewport.
+ */
+/** A subscriber sink receives fully-encoded binary terminal frames. */
+export type TerminalFrameSink = (frame: Uint8Array) => void;
+export interface TerminalRuntimeEntry {
+    slot: number;
+    workspaceId: string;
+    name: string;
+    cwd?: string;
+    shell: string;
+    cols: number;
+    rows: number;
+    /** `true` once the PTY has exited. */
+    closed: boolean;
+    /** Marks a service-script-backed terminal (handed to the service proxy elsewhere). */
+    service?: boolean;
+}
+export interface CreateTerminalOptions {
+    workspaceId: string;
+    cwd?: string;
+    shell?: string;
+    args?: string[];
+    name?: string;
+    cols?: number;
+    rows?: number;
+    env?: Record<string, string>;
+    service?: boolean;
+}
+export interface TerminalManagerOptions {
+    backend?: PtyBackend;
+    /** Output coalescing window in ms (batch before broadcast). Default 4ms. */
+    coalesceMs?: number;
+    /** Max bytes retained as the transient "screen" snapshot. Default 64KiB. */
+    snapshotBytes?: number;
+    defaultShell?: string;
+}
+export declare class TerminalManager {
+    private readonly backend;
+    private readonly coalesceMs;
+    private readonly snapshotBytes;
+    private readonly defaultShell;
+    private readonly terminals;
+    private nextSlot;
+    constructor(options?: TerminalManagerOptions);
+    /** All live terminal runtime entries. */
+    list(): TerminalRuntimeEntry[];
+    get(slot: number): TerminalRuntimeEntry | undefined;
+    /** Spawn a PTY in the backend, assign a slot, and track the runtime entry. */
+    createTerminal(options: CreateTerminalOptions): TerminalRuntimeEntry;
+    /**
+     * Subscribe to a slot: emit a Snapshot frame (current screen) immediately, then live Output frames.
+     * Does NOT resize the PTY (passive attach must not claim size). Returns an unsubscribe fn.
+     */
+    subscribe(slot: number, sink: TerminalFrameSink): () => void;
+    rename(slot: number, name: string): boolean;
+    /** Forward input bytes to the PTY. */
+    input(slot: number, bytes: Uint8Array): boolean;
+    /**
+     * Explicit, client-initiated resize (genuine viewport change / focus). The only path that claims
+     * PTY size. Never called from subscribe/attach.
+     */
+    resize(slot: number, cols: number, rows: number): boolean;
+    /** One-shot current screen text (for CLI/MCP capture). Does not subscribe. Screen-accurate. */
+    capture(slot: number): string | null;
+    /** Terminate the PTY and notify subscribers. */
+    kill(slot: number): boolean;
+    private onOutput;
+    private flush;
+    private onExit;
+}
+//# sourceMappingURL=terminal-manager.d.ts.map

package/dist/terminal/terminal-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-manager.d.ts","sourceRoot":"","sources":["../../src/terminal/terminal-manager.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,UAAU,EAGhB,MAAM,kBAAkB,CAAC;AAG1B;;;;;;;;GAQG;AAEH,uEAAuE;AACvE,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;AAE5D,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,MAAM,EAAE,OAAO,CAAC;IAChB,sFAAsF;IACtF,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAeD,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAa;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsC;IAChE,OAAO,CAAC,QAAQ,CAAK;gBAET,OAAO,GAAE,sBAA2B;IAOhD,yCAAyC;IACzC,IAAI,IAAI,oBAAoB,EAAE;IAI9B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS;IAInD,8EAA8E;IAC9E,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,oBAAoB;IA4CpE;;;OAGG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,MAAM,IAAI;IAa5D,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO;IAO3C,sCAAsC;IACtC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO;IAO/C;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO;IAUzD,+FAA+F;IAC/F,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAMpC,gDAAgD;IAChD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAU3B,OAAO,CAAC,QAAQ;IAWhB,OAAO,CAAC,KAAK;IASb,OAAO,CAAC,MAAM;CAaf"}

package/dist/terminal/terminal-manager.js

@@ -0,0 +1,174 @@
+import { encodeTerminalFrame } from "@av-pi-studio/protocol";
+import { createDefaultPtyBackend, resolveExecutable, } from "./pty-backend.js";
+import { ScreenBuffer } from "./screen-buffer.js";
+export class TerminalManager {
+    backend;
+    coalesceMs;
+    snapshotBytes;
+    defaultShell;
+    terminals = new Map();
+    nextSlot = 1;
+    constructor(options = {}) {
+        this.backend = options.backend ?? createDefaultPtyBackend();
+        this.coalesceMs = options.coalesceMs ?? 4;
+        this.snapshotBytes = options.snapshotBytes ?? 64 * 1024;
+        this.defaultShell = resolveExecutable(options.defaultShell ?? process.env.SHELL ?? "/bin/sh");
+    }
+    /** All live terminal runtime entries. */
+    list() {
+        return [...this.terminals.values()].map((t) => t.entry);
+    }
+    get(slot) {
+        return this.terminals.get(slot)?.entry;
+    }
+    /** Spawn a PTY in the backend, assign a slot, and track the runtime entry. */
+    createTerminal(options) {
+        const slot = this.nextSlot++;
+        const cols = options.cols ?? 80;
+        const rows = options.rows ?? 24;
+        const shell = options.shell ?? this.defaultShell;
+        const pty = this.backend.spawn({
+            shell,
+            args: options.args,
+            cwd: options.cwd,
+            env: options.env,
+            cols,
+            rows,
+        });
+        const entry = {
+            slot,
+            workspaceId: options.workspaceId,
+            name: options.name ?? `terminal-${slot}`,
+            cwd: options.cwd,
+            shell,
+            cols,
+            rows,
+            closed: false,
+            service: options.service,
+        };
+        const managed = {
+            entry,
+            pty,
+            subscribers: new Set(),
+            screen: new Uint8Array(0),
+            screenModel: new ScreenBuffer(cols, rows),
+            pending: [],
+            flushTimer: null,
+        };
+        this.terminals.set(slot, managed);
+        pty.onData((data) => this.onOutput(managed, data));
+        pty.onExit(() => this.onExit(managed));
+        return entry;
+    }
+    /**
+     * Subscribe to a slot: emit a Snapshot frame (current screen) immediately, then live Output frames.
+     * Does NOT resize the PTY (passive attach must not claim size). Returns an unsubscribe fn.
+     */
+    subscribe(slot, sink) {
+        const managed = this.terminals.get(slot);
+        if (!managed)
+            throw new Error(`no terminal in slot ${slot}`);
+        // Snapshot first (rebuilds screen state), then live output.
+        sink(encodeTerminalFrame({ opcode: "Snapshot", slot, data: managed.screen.slice() }));
+        managed.subscribers.add(sink);
+        return () => {
+            managed.subscribers.delete(sink);
+        };
+    }
+    rename(slot, name) {
+        const managed = this.terminals.get(slot);
+        if (!managed)
+            return false;
+        managed.entry.name = name;
+        return true;
+    }
+    /** Forward input bytes to the PTY. */
+    input(slot, bytes) {
+        const managed = this.terminals.get(slot);
+        if (!managed || managed.entry.closed)
+            return false;
+        managed.pty.write(bytes);
+        return true;
+    }
+    /**
+     * Explicit, client-initiated resize (genuine viewport change / focus). The only path that claims
+     * PTY size. Never called from subscribe/attach.
+     */
+    resize(slot, cols, rows) {
+        const managed = this.terminals.get(slot);
+        if (!managed || managed.entry.closed)
+            return false;
+        managed.entry.cols = cols;
+        managed.entry.rows = rows;
+        managed.pty.resize(cols, rows);
+        managed.screenModel.resize(cols, rows);
+        return true;
+    }
+    /** One-shot current screen text (for CLI/MCP capture). Does not subscribe. Screen-accurate. */
+    capture(slot) {
+        const managed = this.terminals.get(slot);
+        if (!managed)
+            return null;
+        return managed.screenModel.snapshotText();
+    }
+    /** Terminate the PTY and notify subscribers. */
+    kill(slot) {
+        const managed = this.terminals.get(slot);
+        if (!managed)
+            return false;
+        managed.pty.kill();
+        this.onExit(managed);
+        return true;
+    }
+    // ─── Internals ───────────────────────────────────────────────────────────
+    onOutput(managed, data) {
+        // Append to the transient screen snapshot (bounded ring) for binary client replay.
+        managed.screen = appendBounded(managed.screen, data, this.snapshotBytes);
+        // Feed the headless grid for screen-accurate text capture.
+        managed.screenModel.write(data);
+        // Coalesce before broadcast.
+        managed.pending.push(data);
+        if (managed.flushTimer)
+            return;
+        managed.flushTimer = setTimeout(() => this.flush(managed), this.coalesceMs);
+    }
+    flush(managed) {
+        managed.flushTimer = null;
+        if (managed.pending.length === 0)
+            return;
+        const batch = concat(managed.pending);
+        managed.pending = [];
+        const frame = encodeTerminalFrame({ opcode: "Output", slot: managed.entry.slot, data: batch });
+        for (const sink of managed.subscribers)
+            sink(frame);
+    }
+    onExit(managed) {
+        if (managed.entry.closed)
+            return;
+        if (managed.flushTimer) {
+            clearTimeout(managed.flushTimer);
+            this.flush(managed);
+        }
+        managed.entry.closed = true;
+        managed.screenModel.dispose();
+        this.terminals.delete(managed.entry.slot);
+        // Notify subscribers the terminal closed (empty Output then drop). Clients treat an exited
+        // terminal as closed; no dedicated close opcode exists in the binary protocol.
+        managed.subscribers.clear();
+    }
+}
+function appendBounded(buffer, data, max) {
+    const combined = concat([buffer, data]);
+    return combined.length <= max ? combined : combined.slice(combined.length - max);
+}
+function concat(parts) {
+    const total = parts.reduce((n, p) => n + p.length, 0);
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.length;
+    }
+    return out;
+}
+//# sourceMappingURL=terminal-manager.js.map

package/dist/terminal/terminal-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-manager.js","sourceRoot":"","sources":["../../src/terminal/terminal-manager.ts"],"names":[],"mappings":"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"}

package/dist/terminal/terminal-rpc.d.ts

@@ -0,0 +1,20 @@
+import type { Session } from "../ws/session.js";
+import type { BinaryHandler, HandlerRegistry } from "../ws/router.js";
+import type { TerminalManager } from "./terminal-manager.js";
+/**
+ * Terminal control RPC surface + capture/restore semantics (features/terminals.md § Control RPCs,
+ * § Restore / snapshot). Per-slot binary streams are piped to the requesting session; restore modes
+ * are gated by `features["terminal-restore-modes"]`.
+ */
+export interface TerminalRpcDeps {
+    manager: TerminalManager;
+    broadcast: (sessions: Iterable<Session>, message: unknown) => void;
+    /** Whether the daemon advertises `features["terminal-restore-modes"]`. */
+    restoreModesEnabled: boolean;
+    /** Resolve a project root → `pi-studio.json` path (for StartWorkspaceScriptRequest). */
+    projectConfigPath: (cwd: string) => string;
+}
+export declare function registerTerminalHandlers(registry: HandlerRegistry, deps: TerminalRpcDeps, getActiveSessions: () => Iterable<Session>): void;
+/** Binary terminal-input frame handler for the frame dispatcher (Input/Resize opcodes). */
+export declare function makeTerminalBinaryHandler(manager: TerminalManager): BinaryHandler;
+//# sourceMappingURL=terminal-rpc.d.ts.map

package/dist/terminal/terminal-rpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-rpc.d.ts","sourceRoot":"","sources":["../../src/terminal/terminal-rpc.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D;;;;GAIG;AAEH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,eAAe,CAAC;IACzB,SAAS,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IACnE,0EAA0E;IAC1E,mBAAmB,EAAE,OAAO,CAAC;IAC7B,wFAAwF;IACxF,iBAAiB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;CAC5C;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,eAAe,EACzB,IAAI,EAAE,eAAe,EACrB,iBAAiB,EAAE,MAAM,QAAQ,CAAC,OAAO,CAAC,GACzC,IAAI,CAsHN;AAED,2FAA2F;AAC3F,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,eAAe,GAAG,aAAa,CAOjF"}

package/dist/terminal/terminal-rpc.js

@@ -0,0 +1,122 @@
+import { tryDecodeTerminalFrame } from "@av-pi-studio/protocol";
+import { readProjectConfig } from "../config/project-config.js";
+export function registerTerminalHandlers(registry, deps, getActiveSessions) {
+    const { manager } = deps;
+    // Per (session, slot) stream unsubscribers.
+    const streamUnsubs = new Map();
+    const key = (session, slot) => `${session.id}:${slot}`;
+    registry.register("list_terminals_request", () => ({
+        type: "list_terminals_response",
+        terminals: manager.list(),
+    }));
+    registry.register("subscribe_terminals_request", () => ({
+        type: "subscribe_terminals_response",
+        terminals: manager.list(),
+    }));
+    registry.register("unsubscribe_terminals_request", () => ({
+        type: "unsubscribe_terminals_response",
+        ok: true,
+    }));
+    registry.register("create_terminal_request", (ctx) => {
+        const entry = manager.createTerminal({
+            workspaceId: String(ctx.message.workspaceId ?? ""),
+            cwd: ctx.message.cwd,
+            shell: ctx.message.shell,
+            name: ctx.message.name,
+            cols: ctx.message.cols,
+            rows: ctx.message.rows,
+        });
+        deps.broadcast(getActiveSessions(), { type: "terminals_update", terminals: manager.list() });
+        return { type: "create_terminal_response", terminal: entry };
+    });
+    registry.register("rename_terminal_request", (ctx) => {
+        const slot = Number(ctx.message.slot);
+        const ok = manager.rename(slot, String(ctx.message.name ?? ""));
+        if (ok)
+            deps.broadcast(getActiveSessions(), { type: "terminals_update", terminals: manager.list() });
+        return { type: "rename_terminal_response", slot, ok };
+    });
+    registry.register("subscribe_terminal_request", (ctx) => {
+        const slot = Number(ctx.message.slot);
+        const session = ctx.session;
+        // Restore mode is honored only when the daemon advertises the feature AND the client advertised
+        // the reflowable-snapshot capability. Otherwise fall back to the basic snapshot (ignore mode).
+        const requestedMode = ctx.message.restoreMode;
+        const clientReflowable = session.supports("terminal_reflowable_snapshot");
+        const restoreMode = deps.restoreModesEnabled && clientReflowable ? (requestedMode ?? "basic") : "basic";
+        streamUnsubs.get(key(session, slot))?.(); // replace existing subscription
+        try {
+            const unsub = manager.subscribe(slot, (frame) => session.sendBinary(frame));
+            streamUnsubs.set(key(session, slot), unsub);
+            return { type: "subscribe_terminal_response", slot, ok: true, restoreMode };
+        }
+        catch {
+            return { type: "subscribe_terminal_response", slot, ok: false, error: "no_such_terminal" };
+        }
+    });
+    registry.register("unsubscribe_terminal_request", (ctx) => {
+        const slot = Number(ctx.message.slot);
+        streamUnsubs.get(key(ctx.session, slot))?.();
+        streamUnsubs.delete(key(ctx.session, slot));
+        return { type: "unsubscribe_terminal_response", slot, ok: true };
+    });
+    // Text-RPC input (binary input frames are handled by the binary router below).
+    registry.register("terminal_input", (ctx) => {
+        const slot = Number(ctx.message.slot);
+        const data = typeof ctx.message.data === "string"
+            ? Buffer.from(ctx.message.data, "base64")
+            : Buffer.from([]);
+        manager.input(slot, new Uint8Array(data));
+        return undefined; // fire-and-forget
+    });
+    registry.register("kill_terminal_request", (ctx) => {
+        const slot = Number(ctx.message.slot);
+        const ok = manager.kill(slot);
+        deps.broadcast(getActiveSessions(), { type: "terminals_update", terminals: manager.list() });
+        return { type: "kill_terminal_response", slot, ok };
+    });
+    registry.register("capture_terminal_request", (ctx) => {
+        const slot = Number(ctx.message.slot);
+        const screen = manager.capture(slot);
+        return { type: "capture_terminal_response", slot, ok: screen !== null, screen: screen ?? "" };
+    });
+    registry.register("start_workspace_script_request", async (ctx) => {
+        const cwd = String(ctx.message.cwd ?? "");
+        const scriptName = String(ctx.message.script ?? ctx.message.name ?? "");
+        const { config } = await readProjectConfig(deps.projectConfigPath(cwd));
+        const script = config.scripts[scriptName];
+        if (!script) {
+            return { type: "start_workspace_script_response", ok: false, error: "script_not_found" };
+        }
+        const isService = script.type === "service";
+        const entry = manager.createTerminal({
+            workspaceId: String(ctx.message.workspaceId ?? ""),
+            cwd,
+            shell: "/bin/sh",
+            args: ["-c", script.command],
+            name: scriptName,
+            service: isService,
+        });
+        deps.broadcast(getActiveSessions(), { type: "terminals_update", terminals: manager.list() });
+        // Service scripts are handed to the service proxy (task-003) by the caller via `entry.service`.
+        return {
+            type: "start_workspace_script_response",
+            ok: true,
+            terminal: entry,
+            service: isService,
+        };
+    });
+}
+/** Binary terminal-input frame handler for the frame dispatcher (Input/Resize opcodes). */
+export function makeTerminalBinaryHandler(manager) {
+    return (_session, bytes) => {
+        const frame = tryDecodeTerminalFrame(bytes);
+        if (!frame)
+            return;
+        if (frame.opcode === "Input")
+            manager.input(frame.slot, frame.data);
+        else if (frame.opcode === "Resize")
+            manager.resize(frame.slot, frame.cols, frame.rows);
+    };
+}
+//# sourceMappingURL=terminal-rpc.js.map

package/dist/terminal/terminal-rpc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-rpc.js","sourceRoot":"","sources":["../../src/terminal/terminal-rpc.ts"],"names":[],"mappings":"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"}