@tea-agent/loop-agent 0.43.0-next.1 → 0.43.0-next.11

package/dist/worker/console/chat/terminal-routes.js

@@ -0,0 +1,216 @@
+/**
+ * Operator Chat — terminal management HTTP API (Console UI side).
+ *
+ * Endpoints (all under /api/operator/v1/chat):
+ *   GET  /terminals                          list terminal sessions (all owners)
+ *   POST /terminals                          spawn { shell, name?, cwd?, ownerSessionId? }
+ *   GET  /terminals/:id                      session info + buffered output
+ *   POST /terminals/:id/input                { data }  write to the PTY
+ *   POST /terminals/:id/resize               { cols, rows }
+ *   POST /terminals/:id/interrupt            send Ctrl+C
+ *   POST /terminals/:id/kill                 stop and await full exit
+ *   GET  /terminals/:id/stream               SSE: buffered replay + live chunks
+ *
+ * Mutating routes require the Console boot token (same gate as other chat
+ * mutations). The stream is read-only and uses the same origin checks as the
+ * chat event stream.
+ */
+import { TerminalSessionError, availableShellKinds, } from "./terminal-sessions.js";
+function sendJson(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, {
+        "content-type": "application/json; charset=utf-8",
+        "cache-control": "no-store",
+    });
+    res.end(payload);
+}
+function mapTerminalError(res, error) {
+    if (error instanceof TerminalSessionError) {
+        const status = error.code === "TERMINAL_NOT_FOUND"
+            ? 404
+            : error.code === "TERMINAL_EXITED" || error.code === "TERMINAL_SEND_ACTIVE"
+                ? 409
+                : 500;
+        sendJson(res, status, {
+            ok: false,
+            error: { code: error.code, message: error.message },
+        });
+        return;
+    }
+    sendJson(res, 500, {
+        ok: false,
+        error: {
+            code: "TERMINAL_INTERNAL",
+            message: error instanceof Error ? error.message : String(error),
+        },
+    });
+}
+async function readJsonBody(req, maxBytes = 512 * 1024) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of req) {
+        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        total += buf.length;
+        if (total > maxBytes)
+            throw new Error("request body too large");
+        chunks.push(buf);
+    }
+    if (chunks.length === 0)
+        return {};
+    const raw = Buffer.concat(chunks).toString("utf8");
+    if (!raw.trim())
+        return {};
+    return JSON.parse(raw);
+}
+/** Route dispatcher; returns true when the request was handled. */
+export async function handleTerminalRequest(req, res, deps, pathname) {
+    if (!pathname.startsWith("/api/operator/v1/chat/terminals"))
+        return false;
+    const method = (req.method ?? "GET").toUpperCase();
+    const rest = pathname.slice("/api/operator/v1/chat/terminals".length);
+    const parts = rest.split("/").filter(Boolean);
+    try {
+        // GET /terminals — list (+ available shell kinds for this platform)
+        if (method === "GET" && parts.length === 0) {
+            sendJson(res, 200, {
+                ok: true,
+                data: {
+                    terminals: deps.terminals.list(),
+                    availableShells: availableShellKinds().kinds,
+                },
+            });
+            return true;
+        }
+        // POST /terminals — spawn
+        if (method === "POST" && parts.length === 0) {
+            const gate = deps.gateMutation(req);
+            if (!gate.ok) {
+                sendJson(res, gate.status, { ok: false, error: { code: gate.code, message: gate.message } });
+                return true;
+            }
+            const body = await readJsonBody(req);
+            const kinds = availableShellKinds().kinds;
+            const shell = kinds.includes(body.shell)
+                ? body.shell
+                : undefined;
+            if (!shell) {
+                sendJson(res, 400, {
+                    ok: false,
+                    error: {
+                        code: "INVALID_INPUT",
+                        message: `shell must be one of: ${kinds.join(", ")} (available on this platform)`,
+                    },
+                });
+                return true;
+            }
+            const info = deps.terminals.spawn({
+                ownerSessionId: typeof body.ownerSessionId === "string" && body.ownerSessionId
+                    ? body.ownerSessionId
+                    : "console-ui",
+                name: typeof body.name === "string" && body.name ? body.name : `${shell}-ui`,
+                shell: shell,
+                cwd: typeof body.cwd === "string" && body.cwd
+                    ? body.cwd
+                    : (deps.defaultCwd ?? undefined),
+                cols: typeof body.cols === "number" ? body.cols : undefined,
+                rows: typeof body.rows === "number" ? body.rows : undefined,
+            });
+            sendJson(res, 201, { ok: true, data: info });
+            return true;
+        }
+        const sessionId = parts[0];
+        if (!sessionId)
+            return false;
+        const sub = parts[1] ?? "";
+        // GET /terminals/:id — info + buffered output
+        if (method === "GET" && parts.length === 1) {
+            const info = deps.terminals.get(sessionId);
+            const output = deps.terminals.readAll(sessionId);
+            sendJson(res, 200, { ok: true, data: { ...info, output } });
+            return true;
+        }
+        // GET /terminals/:id/stream — SSE
+        if (method === "GET" && sub === "stream") {
+            // Validate existence first (404 before opening the stream).
+            const info = deps.terminals.get(sessionId);
+            void info;
+            res.writeHead(200, {
+                "content-type": "text/event-stream; charset=utf-8",
+                "cache-control": "no-cache, no-store",
+                connection: "keep-alive",
+                "x-accel-buffering": "no",
+            });
+            const writeFrame = (event, data) => {
+                if (res.writableEnded)
+                    return;
+                res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+            };
+            const buffered = deps.terminals.readAll(sessionId);
+            writeFrame("snapshot", {
+                truncated: buffered.truncated,
+                totalOutputChars: buffered.totalOutputChars,
+                text: buffered.text,
+                info: deps.terminals.get(sessionId),
+            });
+            const unsubscribe = deps.terminals.subscribe(sessionId, (chunk) => {
+                writeFrame("data", { chunk });
+            });
+            const heartbeat = setInterval(() => {
+                if (!res.writableEnded)
+                    res.write(": heartbeat\n\n");
+            }, 15_000);
+            res.once("close", () => {
+                clearInterval(heartbeat);
+                unsubscribe();
+            });
+            return true;
+        }
+        // Everything else mutates → gate first.
+        const gate = deps.gateMutation(req);
+        if (!gate.ok) {
+            sendJson(res, gate.status, { ok: false, error: { code: gate.code, message: gate.message } });
+            return true;
+        }
+        if (method === "POST" && sub === "input" && parts.length === 2) {
+            const body = await readJsonBody(req);
+            if (typeof body.data !== "string") {
+                sendJson(res, 400, { ok: false, error: { code: "INVALID_INPUT", message: "data (string) is required" } });
+                return true;
+            }
+            deps.terminals.send(sessionId, body.data);
+            sendJson(res, 200, { ok: true });
+            return true;
+        }
+        if (method === "POST" && sub === "resize" && parts.length === 2) {
+            const body = await readJsonBody(req);
+            const cols = Number(body.cols);
+            const rows = Number(body.rows);
+            if (!Number.isInteger(cols) || !Number.isInteger(rows) || cols < 2 || rows < 2 || cols > 500 || rows > 200) {
+                sendJson(res, 400, { ok: false, error: { code: "INVALID_INPUT", message: "cols and rows (integers 2..500/200) are required" } });
+                return true;
+            }
+            deps.terminals.resize(sessionId, cols, rows);
+            sendJson(res, 200, { ok: true });
+            return true;
+        }
+        if (method === "POST" && sub === "interrupt" && parts.length === 2) {
+            deps.terminals.interrupt(sessionId);
+            sendJson(res, 200, { ok: true });
+            return true;
+        }
+        if (method === "POST" && sub === "kill" && parts.length === 2) {
+            await deps.terminals.kill(sessionId);
+            sendJson(res, 200, { ok: true });
+            return true;
+        }
+        sendJson(res, 404, { ok: false, error: { code: "NOT_FOUND", message: `unknown terminal route: ${method} ${pathname}` } });
+        return true;
+    }
+    catch (error) {
+        if (!res.headersSent)
+            mapTerminalError(res, error);
+        else
+            res.end();
+        return true;
+    }
+}

package/dist/worker/console/chat/terminal-sessions.js

@@ -0,0 +1,348 @@
+/**
+ * Operator Chat — persistent PTY terminal sessions (DSH-style terminal seam).
+ *
+ * Process-local registry of owner-scoped persistent terminal sessions:
+ *   - spawn: create a named PTY (shell) owned by a chat session
+ *   - send:  write bytes into the PTY (model tool or console UI input)
+ *   - read:  ring-buffered output history + live subscriber fan-out
+ *   - signal/kill: interrupt or fully stop the process tree, awaited
+ *   - dispose: stop everything owned by one chat session
+ *
+ * Design mirrors the DSH terminal seam contract (process-local, no sharing
+ * across agents, single active send, kill waits for full stop) but stays
+ * deliberately small: no backend abstraction (node-pty is the only backend),
+ * no cross-process persistence (sessions die with the Console process).
+ */
+import { spawn as ptySpawn } from "node-pty";
+import { existsSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { release as osRelease } from "node:os";
+/** Bounded ring buffer of raw output chunks (bytes preserved as utf8 text). */
+const MAX_BUFFER_CHARS = 200_000;
+export class TerminalSessionError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "TerminalSessionError";
+    }
+}
+const IS_WINDOWS = process.platform === "win32";
+function firstExisting(paths) {
+    return paths.find((p) => existsSync(p));
+}
+/** Windows PowerShell 5+ or pwsh 7; prefer pwsh 7 when installed. */
+function resolvePowershell() {
+    if (IS_WINDOWS) {
+        const pwsh7 = firstExisting([
+            "C:\\Program Files\\PowerShell\\7\\pwsh.exe",
+            "C:\\Program Files (x86)\\PowerShell\\7\\pwsh.exe",
+        ]);
+        if (pwsh7) {
+            return {
+                file: pwsh7,
+                args: [
+                    "-NoLogo",
+                    "-NoProfile",
+                    "-ExecutionPolicy",
+                    "Bypass",
+                    "-NoExit",
+                    "-Command",
+                    "$PSDefaultParameterValues['Out-File:Encoding']='utf8'; [Console]::OutputEncoding=[Text.Encoding]::UTF8",
+                ],
+            };
+        }
+        const ps5 = "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe";
+        if (existsSync(ps5)) {
+            return {
+                file: ps5,
+                args: [
+                    "-NoProfile",
+                    "-ExecutionPolicy",
+                    "Bypass",
+                    "-NoExit",
+                    "-Command",
+                    "$PSDefaultParameterValues['Out-File:Encoding']='utf8'; [Console]::OutputEncoding=[Text.Encoding]::UTF8",
+                ],
+            };
+        }
+        return undefined;
+    }
+    // macOS / Linux: only pwsh 7 if explicitly installed.
+    const pwsh = firstExisting([
+        "/usr/local/bin/pwsh",
+        "/opt/homebrew/bin/pwsh",
+        "/usr/bin/pwsh",
+    ]);
+    return pwsh
+        ? { file: pwsh, args: ["-NoLogo", "-NoProfile"] }
+        : undefined;
+}
+/** bash: Git Bash on Windows, /bin/bash (or Homebrew) on unix-likes. */
+function resolveBash() {
+    if (IS_WINDOWS) {
+        const file = firstExisting([
+            "C:\\Program Files\\Git\\bin\\bash.exe",
+            "C:\\Program Files (x86)\\Git\\bin\\bash.exe",
+            "C:\\Program Files\\Git\\usr\\bin\\bash.exe",
+        ]);
+        return file ? { file, args: ["-i", "-l"] } : undefined;
+    }
+    const file = firstExisting(["/bin/bash", "/usr/bin/bash", "/usr/local/bin/bash", "/opt/homebrew/bin/bash"]);
+    return file ? { file, args: ["-i"] } : undefined;
+}
+/** zsh: macOS default shell; on Linux only when installed. */
+function resolveZsh() {
+    if (IS_WINDOWS)
+        return undefined;
+    const file = firstExisting(["/bin/zsh", "/usr/bin/zsh", "/usr/local/bin/zsh", "/opt/homebrew/bin/zsh"]);
+    return file ? { file, args: ["-i"] } : undefined;
+}
+/** Windows `cmd.exe`. Always present on Windows; offered alongside
+ * PowerShell so users can use native Windows tooling (`dir`, `where`,
+ * `mklink`, `net user`, etc.) without leaving the terminal panel.
+ *  - `/Q` turns off command echo (otherwise cmd echoes every input line,
+ *    doubling every prompt in PTY output).
+ *  - `/D` disables AutoRun execution from the registry (avoid running the
+ *    user's HKCU\...\RunOnce / autorun scripts on every fresh shell).
+ *  - `/K "prompt $P$G"` keeps the shell alive across tool calls (cwd/env
+ *    survive) and uses the classic cmd prompt `C:\path>` instead of the
+ *    bare `>`, so the user can see the working directory at a glance —
+ *    matching the default `cmd.exe` window. */
+function resolveCmd() {
+    if (!IS_WINDOWS)
+        return undefined;
+    const file = firstExisting([
+        "C:\\Windows\\System32\\cmd.exe",
+        // Wine / uncommon layouts
+        "C:\\Windows\\Sysnative\\cmd.exe",
+    ]);
+    if (!file)
+        return undefined;
+    return {
+        file,
+        args: ["/Q", "/D", "/K", "prompt $P$G"],
+    };
+}
+/** Synthesize the cmd.exe startup banner that node-pty drops. cmd prints
+ * `Microsoft Windows [版本 10.0.26200]\n(c) Microsoft Corporation。保留所有权利。`
+ * via `WriteConsole` BEFORE ConPTY attaches to its stdio handles, so
+ * node-pty / ConPTY never sees those writes. We re-emit an equivalent
+ * banner using `os.release()` (kernel build, e.g. "10.0.26200") so the
+ * console terminal looks like a real cmd window. The leading \r\n avoids
+ * the banner colliding with whatever ANSI preamble ConPTY already sent.
+ *
+ * Only meaningful for the cmd shell — bash and PowerShell on Windows have
+ * their own startup output that we must NOT paper over with a Windows
+ * banner they don't print. */
+function makeCmdBanner(shell) {
+    if (!IS_WINDOWS)
+        return undefined;
+    if (shell !== "cmd")
+        return undefined;
+    const build = osRelease();
+    return `\r\nMicrosoft Windows [版本 ${build}]\r\n(c) Microsoft Corporation。保留所有权利。\r\n\r\n`;
+}
+let cachedCatalog;
+/** Platform shell catalog, computed once per process. Drives both the UI
+ * button set and the model tool's shell parameter enum. */
+export function availableShellKinds() {
+    if (cachedCatalog)
+        return cachedCatalog;
+    const resolved = new Map();
+    const pwsh = resolvePowershell();
+    if (pwsh)
+        resolved.set("powershell", pwsh);
+    const bash = resolveBash();
+    if (bash)
+        resolved.set("bash", bash);
+    const zsh = resolveZsh();
+    if (zsh)
+        resolved.set("zsh", zsh);
+    const cmd = resolveCmd();
+    if (cmd)
+        resolved.set("cmd", cmd);
+    cachedCatalog = { kinds: [...resolved.keys()], resolved };
+    return cachedCatalog;
+}
+export function resolveShellCommand(shell) {
+    const resolved = availableShellKinds().resolved.get(shell);
+    if (!resolved) {
+        throw new TerminalSessionError("TERMINAL_SPAWN_FAILED", `shell "${shell}" is not available on this platform (${process.platform})`);
+    }
+    return resolved;
+}
+export class TerminalSessionRegistry {
+    entries = new Map();
+    nextSeq = 0;
+    spawn(options) {
+        let file;
+        let args;
+        try {
+            ({ file, args } = resolveShellCommand(options.shell));
+        }
+        catch (error) {
+            throw new TerminalSessionError("TERMINAL_SPAWN_FAILED", `failed to spawn ${options.shell}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const sessionId = `term-${Date.now().toString(36)}-${randomBytes(4).toString("hex")}`;
+        let pty;
+        try {
+            pty = ptySpawn(file, args, {
+                name: "xterm-256color",
+                cwd: options.cwd,
+                cols: options.cols ?? 120,
+                rows: options.rows ?? 30,
+                env: process.env ?? {},
+                encoding: "utf8",
+            });
+        }
+        catch (error) {
+            throw new TerminalSessionError("TERMINAL_SPAWN_FAILED", `failed to spawn ${options.shell}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const entry = {
+            info: {
+                sessionId,
+                ownerSessionId: options.ownerSessionId,
+                name: options.name,
+                shell: options.shell,
+                createdAt: new Date().toISOString(),
+                totalOutputChars: 0,
+                exited: false,
+            },
+            pty,
+            buffer: [],
+            bufferChars: 0,
+            subscribers: new Set(),
+            disposing: undefined,
+            pendingBanner: makeCmdBanner(options.shell) ?? undefined,
+        };
+        this.entries.set(sessionId, entry);
+        pty.onData((chunk) => {
+            entry.info.totalOutputChars += chunk.length;
+            // Inject the synthesized cmd banner into the FIRST chunk the
+            // subscribers see, so SSE/streaming attaches still see it even
+            // though node-pty already missed cmd's real banner.
+            if (entry.pendingBanner !== undefined) {
+                chunk = entry.pendingBanner + chunk;
+                entry.pendingBanner = undefined;
+            }
+            entry.buffer.push(chunk);
+            entry.bufferChars += chunk.length;
+            while (entry.bufferChars > MAX_BUFFER_CHARS && entry.buffer.length > 1) {
+                const dropped = entry.buffer.shift();
+                entry.bufferChars -= dropped?.length ?? 0;
+            }
+            for (const notify of entry.subscribers) {
+                try {
+                    notify(chunk);
+                }
+                catch {
+                    // subscriber callbacks must never break the pty stream
+                }
+            }
+        });
+        pty.onExit(({ exitCode }) => {
+            entry.info.exited = true;
+            entry.info.exitCode = exitCode;
+            for (const notify of entry.subscribers) {
+                try {
+                    notify(`\r\n\u001b[90m[terminal exited: code ${exitCode}]\u001b[0m\r\n`);
+                }
+                catch {
+                    // ignore
+                }
+            }
+        });
+        return { ...entry.info };
+    }
+    list(ownerSessionId) {
+        const all = [...this.entries.values()].map((e) => ({ ...e.info }));
+        return ownerSessionId
+            ? all.filter((i) => i.ownerSessionId === ownerSessionId)
+            : all;
+    }
+    get(sessionId) {
+        const entry = this.entries.get(sessionId);
+        if (!entry)
+            throw new TerminalSessionError("TERMINAL_NOT_FOUND", sessionId);
+        return { ...entry.info };
+    }
+    mustGet(sessionId) {
+        const entry = this.entries.get(sessionId);
+        if (!entry)
+            throw new TerminalSessionError("TERMINAL_NOT_FOUND", sessionId);
+        return entry;
+    }
+    /** Full buffered output (post-trim prefix may be incomplete). */
+    readAll(sessionId) {
+        const entry = this.mustGet(sessionId);
+        let text = entry.buffer.join("");
+        // If the caller reads before any real PTY output has arrived, the
+        // banner injection in onData hasn't fired yet — fold it in here.
+        if (entry.pendingBanner !== undefined) {
+            text = entry.pendingBanner + text;
+            entry.pendingBanner = undefined;
+        }
+        return {
+            text,
+            truncated: entry.info.totalOutputChars > entry.bufferChars,
+            totalOutputChars: entry.info.totalOutputChars,
+        };
+    }
+    /** Subscribe to live output chunks; returns unsubscribe. */
+    subscribe(sessionId, onChunk) {
+        const entry = this.mustGet(sessionId);
+        entry.subscribers.add(onChunk);
+        return () => entry.subscribers.delete(onChunk);
+    }
+    send(sessionId, data) {
+        const entry = this.mustGet(sessionId);
+        if (entry.info.exited)
+            throw new TerminalSessionError("TERMINAL_EXITED", "terminal already exited");
+        entry.pty.write(data);
+    }
+    /** Resize the PTY (console UI attach). */
+    resize(sessionId, cols, rows) {
+        const entry = this.mustGet(sessionId);
+        if (entry.info.exited)
+            return;
+        entry.pty.resize(cols, rows);
+    }
+    /** Send an interrupt character (Ctrl+C) to the foreground process. */
+    interrupt(sessionId) {
+        const entry = this.mustGet(sessionId);
+        if (entry.info.exited)
+            return;
+        entry.pty.write("\x03");
+    }
+    /** Kill and wait for full stop, then remove the registry entry so closed
+     * terminals disappear from the list (explicit close = forget). Idempotent. */
+    async kill(sessionId) {
+        const entry = this.entries.get(sessionId);
+        if (!entry)
+            throw new TerminalSessionError("TERMINAL_NOT_FOUND", sessionId);
+        if (!entry.info.exited) {
+            entry.disposing ??= new Promise((resolve) => {
+                const timer = setTimeout(() => resolve(), 5_000);
+                entry.pty.onExit(() => {
+                    clearTimeout(timer);
+                    resolve();
+                });
+                try {
+                    entry.pty.kill();
+                }
+                catch {
+                    clearTimeout(timer);
+                    resolve();
+                }
+            });
+            await entry.disposing;
+        }
+        this.entries.delete(sessionId);
+    }
+    /** Kill every session owned by one chat session; awaited. */
+    async disposeOwner(ownerSessionId) {
+        const owned = this.list(ownerSessionId).map((i) => i.sessionId);
+        await Promise.all(owned.map((id) => this.kill(id).catch(() => undefined)));
+    }
+}