@co0ontty/wand 4.46.0 → 4.47.0

package/dist/terminal-daemon-client.js

@@ -4,6 +4,7 @@ import { spawn } from "node:child_process";
 import process from "node:process";
 import { TERMINAL_DAEMON_PROTOCOL_VERSION, terminalDaemonPaths, } from "./terminal-daemon-protocol.js";
 import { appendTerminalChunkWindow, InProcessTerminalHost, } from "./terminal-host.js";
+import { STRUCTURED_RUN_LOG_MAX_CHARS, } from "./structured-exec-host.js";
 import { appendWindow, PTY_OUTPUT_MAX_SIZE } from "./pty-text-utils.js";
 const TERMINAL_DAEMON_RECONNECT_INITIAL_MS = 500;
 const TERMINAL_DAEMON_RECONNECT_MAX_MS = 10_000;
@@ -97,6 +98,125 @@ class RemoteTerminalProcess {
             listener(event);
     }
 }
+/** Client-side handle for a daemon-owned structured CLI run. */
+class RemoteStructuredProcess {
+    runId;
+    incarnationId;
+    pid;
+    client;
+    streamListeners = new Set();
+    exitListeners = new Set();
+    paused = false;
+    pausedEvents = [];
+    undeliveredEvents = [];
+    pendingExit = null;
+    lastStdoutSeq = 0;
+    lastStderrSeq = 0;
+    constructor(runId, incarnationId, pid, client) {
+        this.runId = runId;
+        this.incarnationId = incarnationId;
+        this.pid = pid;
+        this.client = client;
+    }
+    interrupt(signal) {
+        void this.client.request("structuredKill", { runId: this.runId, signal }).catch((error) => this.client.reportOperationError(this.runId, error));
+    }
+    onStream(listener) {
+        this.streamListeners.add(listener);
+        if (this.undeliveredEvents.length > 0) {
+            const pending = this.undeliveredEvents;
+            this.undeliveredEvents = [];
+            queueMicrotask(() => {
+                if (!this.streamListeners.has(listener))
+                    return;
+                for (const event of pending)
+                    listener(event);
+            });
+        }
+        return { dispose: () => this.streamListeners.delete(listener) };
+    }
+    onExit(listener) {
+        this.exitListeners.add(listener);
+        const pending = this.pendingExit;
+        if (pending) {
+            queueMicrotask(() => {
+                if (this.exitListeners.has(listener))
+                    listener(pending);
+            });
+        }
+        return { dispose: () => this.exitListeners.delete(listener) };
+    }
+    acceptStream(event) {
+        this.deliveredChars[event.stream] += event.data.length;
+        if (event.stream === "stdout")
+            this.lastStdoutSeq = Math.max(this.lastStdoutSeq, event.seq);
+        else
+            this.lastStderrSeq = Math.max(this.lastStderrSeq, event.seq);
+        if (this.paused) {
+            this.pausedEvents.push(event);
+            return;
+        }
+        if (this.streamListeners.size === 0) {
+            this.undeliveredEvents.push(event);
+            if (this.undeliveredEvents.length > 4096)
+                this.undeliveredEvents.shift();
+            return;
+        }
+        this.emitStream(event);
+    }
+    acceptExit(event) {
+        this.pendingExit = event;
+        for (const listener of Array.from(this.exitListeners))
+            listener(event);
+    }
+    /** Gap-free catch-up from the daemon's full replay logs after a reconnect. */
+    replayFromLogs(state) {
+        const stdoutDelta = alignedDelta(state.stdoutLog, state.stdoutTruncated, this.deliveredChars.stdout);
+        if (stdoutDelta === null) {
+            process.stderr.write(`[wand] structured run ${this.runId} stdout log no longer aligns with delivered output; skipping catch-up\n`);
+        }
+        else if (stdoutDelta) {
+            this.acceptStream({ stream: "stdout", data: stdoutDelta, seq: ++this.syntheticSeq });
+        }
+        const stderrDelta = alignedDelta(state.stderrLog, state.stderrTruncated, this.deliveredChars.stderr);
+        if (stderrDelta === null) {
+            process.stderr.write(`[wand] structured run ${this.runId} stderr log no longer aligns with delivered output; skipping catch-up\n`);
+        }
+        else if (stderrDelta) {
+            this.acceptStream({ stream: "stderr", data: stderrDelta, seq: ++this.syntheticSeq });
+        }
+    }
+    pause() {
+        this.paused = true;
+    }
+    resume() {
+        if (!this.paused)
+            return;
+        this.paused = false;
+        const pending = this.pausedEvents;
+        this.pausedEvents = [];
+        for (const event of pending)
+            this.emitStream(event);
+    }
+    emitStream(event) {
+        for (const listener of Array.from(this.streamListeners))
+            listener(event);
+    }
+    deliveredChars = { stdout: 0, stderr: 0 };
+    syntheticSeq = 1_000_000_000_000;
+}
+/**
+ * Deliver the suffix of the daemon's replay log beyond what this handle has
+ * already seen. Returns null when alignment is impossible (head-truncated log
+ * or watermark beyond the log), in which case callers skip catch-up.
+ */
+function alignedDelta(log, truncated, deliveredChars) {
+    if (truncated)
+        return null;
+    if (log.length < deliveredChars)
+        return null;
+    return log.slice(deliveredChars);
+}
 export class TerminalDaemonClient {
     socketPath;
     token;
@@ -108,6 +228,9 @@ export class TerminalDaemonClient {
     inventory = new Map();
     handles = new Map();
     pendingEvents = new Map();
+    structuredInventory = new Map();
+    structuredHandles = new Map();
+    pendingStructuredEvents = new Map();
     disposed = false;
     reconnectTimer = null;
     reconnectDelayMs = TERMINAL_DAEMON_RECONNECT_INITIAL_MS;
@@ -151,6 +274,7 @@ export class TerminalDaemonClient {
                 this.reconcileAfterReconnect(previous);
                 process.stderr.write("[wand] Reconnected to terminal daemon; reconciled PTY inventory.\n");
             }
+            await this.refreshStructuredAfterReconnect();
         }
         catch (error) {
             if (!this.disposed) {
@@ -183,6 +307,91 @@ export class TerminalDaemonClient {
         this.pendingEvents.delete(sessionId);
         void this.request("forget", { sessionId }).catch((error) => this.reportOperationError(sessionId, error));
     }
+    // ---------------------------------------------------------------------------
+    // StructuredExecHost: daemon-owned CLI runs that survive web restarts.
+    // ---------------------------------------------------------------------------
+    async spawnStructured(request) {
+        const existingHandle = this.structuredHandles.get(request.runId);
+        const existing = this.structuredInventory.get(request.runId);
+        if (existingHandle && existing?.status === "running" && existing.incarnationId === existingHandle.incarnationId) {
+            return existingHandle;
+        }
+        this.structuredHandles.delete(request.runId);
+        const state = await this.request("structuredSpawn", { ...request });
+        return this.handleFromState(state, existingHandle ?? null);
+    }
+    async attachRun(runId) {
+        const payload = await this.request("structuredAttach", { runId });
+        if (!payload.state)
+            return null;
+        this.structuredInventory.set(runId, payload.state);
+        return payload.state;
+    }
+    async adoptRun(runId) {
+        const state = await this.attachRun(runId);
+        if (!state || state.status !== "running")
+            return null;
+        const existing = this.structuredHandles.get(runId);
+        if (existing && existing.incarnationId === state.incarnationId)
+            return existing;
+        return this.handleFromState(state, existing ?? null);
+    }
+    async listRuns() {
+        const result = await this.request("structuredList");
+        // Defensive against protocol skew with older daemons that answer unknown
+        // methods with a generic { ok: true }.
+        return Array.isArray(result) ? result : [];
+    }
+    forgetRun(runId) {
+        this.structuredInventory.delete(runId);
+        this.structuredHandles.delete(runId);
+        this.pendingStructuredEvents.delete(runId);
+        void this.request("structuredForget", { runId }).catch((error) => this.reportOperationError(runId, error));
+    }
+    /** Refresh the structured inventory and catch live handles up after a reconnect. */
+    async refreshStructuredAfterReconnect() {
+        const previous = new Map(this.structuredInventory);
+        let runs;
+        try {
+            runs = await this.listRuns();
+        }
+        catch {
+            return; // socket died again mid-refresh; next reconnect retries
+        }
+        this.structuredInventory.clear();
+        for (const run of runs)
+            this.structuredInventory.set(run.runId, run);
+        for (const [runId, oldState] of previous) {
+            const current = this.structuredInventory.get(runId);
+            const handle = this.structuredHandles.get(runId);
+            if (!handle || handle.incarnationId !== oldState.incarnationId)
+                continue;
+            if (current && current.status === "running") {
+                handle.replayFromLogs(current);
+                continue;
+            }
+            // Run exited while we were disconnected.
+            this.structuredHandles.delete(runId);
+            handle.acceptExit({ exitCode: current?.exitCode ?? -1, signal: current?.signal ?? null });
+        }
+    }
+    handleFromState(state, reuse) {
+        this.structuredInventory.set(state.runId, state);
+        if (state.status !== "running") {
+            this.structuredHandles.delete(state.runId);
+            return reuse ?? new RemoteStructuredProcess(state.runId, state.incarnationId, state.pid, this);
+        }
+        let process = this.structuredHandles.get(state.runId) ?? null;
+        if (!process || process.incarnationId !== state.incarnationId) {
+            process = new RemoteStructuredProcess(state.runId, state.incarnationId, state.pid, this);
+            this.structuredHandles.set(state.runId, process);
+            const pending = this.pendingStructuredEvents.get(state.runId) ?? [];
+            this.pendingStructuredEvents.delete(state.runId);
+            for (const event of pending)
+                this.routeStructuredEvent(event);
+        }
+        return process;
+    }
     disconnect() {
         this.disposed = true;
         if (this.reconnectTimer) {
@@ -196,6 +405,8 @@ export class TerminalDaemonClient {
         this.rejectPending(new Error("Terminal daemon client disposed"));
         this.handles.clear();
         this.pendingEvents.clear();
+        this.structuredHandles.clear();
+        this.pendingStructuredEvents.clear();
     }
     /**
      * Socket teardown path. Without a reconnect, a daemon restart would leave
@@ -355,6 +566,10 @@ export class TerminalDaemonClient {
         }
     }
     routeEvent(event) {
+        if (event.event === "sdata" || event.event === "sexit") {
+            this.routeStructuredEvent(event);
+            return;
+        }
         const state = this.inventory.get(event.sessionId);
         if (state && state.incarnationId === event.incarnationId) {
             if (event.event === "data" && typeof event.data === "string" && typeof event.seq === "number") {
@@ -382,6 +597,52 @@ export class TerminalDaemonClient {
             this.handles.delete(event.sessionId);
         }
     }
+    /** Structured run events update the inventory and feed live handles. */
+    routeStructuredEvent(event) {
+        const state = this.structuredInventory.get(event.sessionId);
+        if (state && state.incarnationId === event.incarnationId) {
+            if (event.event === "sdata" && typeof event.data === "string" && typeof event.seq === "number") {
+                const stream = event.stream === "stderr" ? "stderr" : "stdout";
+                if (stream === "stdout")
+                    state.stdoutSeq = Math.max(state.stdoutSeq, event.seq);
+                else
+                    state.stderrSeq = Math.max(state.stderrSeq, event.seq);
+                if (stream === "stdout") {
+                    state.stdoutLog += event.data;
+                    if (state.stdoutLog.length > STRUCTURED_RUN_LOG_MAX_CHARS) {
+                        state.stdoutLog = state.stdoutLog.slice(-STRUCTURED_RUN_LOG_MAX_CHARS);
+                        state.stdoutTruncated = true;
+                    }
+                }
+                else {
+                    state.stderrLog += event.data;
+                    if (state.stderrLog.length > STRUCTURED_RUN_LOG_MAX_CHARS) {
+                        state.stderrLog = state.stderrLog.slice(-STRUCTURED_RUN_LOG_MAX_CHARS);
+                        state.stderrTruncated = true;
+                    }
+                }
+            }
+            else if (event.event === "sexit") {
+                state.status = "exited";
+                state.exitCode = event.exitCode ?? null;
+                state.signal = event.signal ?? null;
+            }
+        }
+        const handle = this.structuredHandles.get(event.sessionId);
+        if (!handle || handle.incarnationId !== event.incarnationId) {
+            const pending = this.pendingStructuredEvents.get(event.sessionId) ?? [];
+            pending.push(event);
+            this.pendingStructuredEvents.set(event.sessionId, pending.slice(-2048));
+            return;
+        }
+        if (event.event === "sdata" && typeof event.data === "string" && typeof event.seq === "number") {
+            handle.acceptStream({ stream: event.stream === "stderr" ? "stderr" : "stdout", data: event.data, seq: event.seq });
+        }
+        else if (event.event === "sexit") {
+            handle.acceptExit({ exitCode: event.exitCode ?? null, signal: event.signal ?? null });
+            this.structuredHandles.delete(event.sessionId);
+        }
+    }
     rejectPending(error) {
         for (const pending of this.pending.values()) {
             clearTimeout(pending.timer);

package/dist/terminal-daemon-protocol.d.ts

@@ -1,5 +1,6 @@
+import type { StructuredRunState, StructuredSpawnRequest } from "./structured-exec-host.js";
 import type { TerminalSessionState, TerminalSpawnRequest } from "./terminal-host.js";
-export declare const TERMINAL_DAEMON_PROTOCOL_VERSION = 1;
+export declare const TERMINAL_DAEMON_PROTOCOL_VERSION = 2;
 export interface TerminalDaemonPaths {
     socketPath: string;
     tokenPath: string;
@@ -10,7 +11,7 @@ export type TerminalDaemonRequest = {
     id: number;
     token: string;
     protocolVersion: number;
-    method: "hello" | "list" | "createOrAttach" | "write" | "resize" | "kill" | "forget";
+    method: "hello" | "list" | "createOrAttach" | "write" | "resize" | "kill" | "forget" | "structuredSpawn" | "structuredAttach" | "structuredList" | "structuredKill" | "structuredForget";
     params?: Record<string, unknown>;
 };
 export type TerminalDaemonResponse = {
@@ -26,14 +27,20 @@ export type TerminalDaemonResponse = {
 };
 export type TerminalDaemonEvent = {
     kind: "event";
-    event: "data" | "exit";
+    event: "data" | "exit" | "sdata" | "sexit";
     sessionId: string;
     incarnationId: string;
     data?: string;
     seq?: number;
     exitCode?: number;
     signal?: number;
+    stream?: "stdout" | "stderr";
 };
+export interface TerminalDaemonStructuredAttachPayload {
+    state: StructuredRunState | null;
+}
+export interface TerminalDaemonStructuredSpawnParams extends StructuredSpawnRequest {
+}
 export interface TerminalDaemonCreateParams extends TerminalSpawnRequest {
     afterSeq?: number;
 }

package/dist/terminal-daemon-protocol.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import os from "node:os";
 import path from "node:path";
-export const TERMINAL_DAEMON_PROTOCOL_VERSION = 1;
+export const TERMINAL_DAEMON_PROTOCOL_VERSION = 2;
 export function terminalDaemonPaths(configPath) {
     const resolved = path.resolve(configPath);
     const suffix = createHash("sha256").update(resolved).digest("hex").slice(0, 12);

package/dist/terminal-daemon-server.js

@@ -1,14 +1,17 @@
 import { randomBytes, randomUUID } from "node:crypto";
+import { spawn as nodeSpawn } from "node:child_process";
 import { chmodSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import net from "node:net";
 import path from "node:path";
 import pty from "node-pty";
 import { ensureNodePtyHelperExecutable } from "./ensure-node-pty-helper.js";
+import { STRUCTURED_RUN_LOG_MAX_CHARS, } from "./structured-exec-host.js";
 import { TERMINAL_DAEMON_PROTOCOL_VERSION, terminalDaemonPaths, } from "./terminal-daemon-protocol.js";
 import { appendTerminalChunkWindow, } from "./terminal-host.js";
 import { PtyTerminalState } from "./pty-terminal-state.js";
 import { PtyCliExitMarker } from "./pty-shell-launch.js";
 import { appendWindow, PTY_OUTPUT_MAX_SIZE } from "./pty-text-utils.js";
+const MAX_STRUCTURED_RUNS = 256;
 const MAX_REQUEST_BUFFER = 4 * 1024 * 1024;
 export async function runTerminalDaemon(configPath) {
     const paths = terminalDaemonPaths(configPath);
@@ -34,6 +37,7 @@ export async function runTerminalDaemon(configPath) {
     const token = randomBytes(32).toString("hex");
     const sessions = new Map();
     const clients = new Set();
+    const structuredRuns = new Map();
     const send = (socket, message) => {
         if (!socket.destroyed && socket.writable)
             socket.write(`${JSON.stringify(message)}\n`);
@@ -137,6 +141,142 @@ export async function runTerminalDaemon(configPath) {
         }
         session.terminalState.dispose();
     };
+    // ---------------------------------------------------------------------------
+    // Structured CLI runs: plain child_process ownership with full replay logs.
+    // ---------------------------------------------------------------------------
+    const appendRunLog = (run, stream, data) => {
+        const seq = stream === "stdout" ? ++run.stdoutSeq : ++run.stderrSeq;
+        if (stream === "stdout") {
+            run.stdoutLog += data;
+            if (run.stdoutLog.length > STRUCTURED_RUN_LOG_MAX_CHARS) {
+                run.stdoutLog = run.stdoutLog.slice(-STRUCTURED_RUN_LOG_MAX_CHARS);
+                run.stdoutTruncated = true;
+            }
+        }
+        else {
+            run.stderrLog += data;
+            if (run.stderrLog.length > STRUCTURED_RUN_LOG_MAX_CHARS) {
+                run.stderrLog = run.stderrLog.slice(-STRUCTURED_RUN_LOG_MAX_CHARS);
+                run.stderrTruncated = true;
+            }
+        }
+        return seq;
+    };
+    const serializeStructuredRun = (run) => ({
+        runId: run.request.runId,
+        incarnationId: run.incarnationId,
+        pid: run.pid,
+        status: run.status,
+        exitCode: run.exitCode,
+        signal: run.signal,
+        stdoutSeq: run.stdoutSeq,
+        stderrSeq: run.stderrSeq,
+        stdoutLog: run.stdoutLog,
+        stderrLog: run.stderrLog,
+        stdoutTruncated: run.stdoutTruncated,
+        stderrTruncated: run.stderrTruncated,
+    });
+    /** Evict oldest exited records once the map outgrows its bound. */
+    const evictStaleStructuredRuns = () => {
+        if (structuredRuns.size <= MAX_STRUCTURED_RUNS)
+            return;
+        for (const [runId, run] of structuredRuns) {
+            if (structuredRuns.size <= MAX_STRUCTURED_RUNS)
+                break;
+            if (run.status === "exited")
+                structuredRuns.delete(runId);
+        }
+    };
+    const structuredSpawn = (request) => {
+        const existing = structuredRuns.get(request.runId);
+        if (existing && existing.status === "running")
+            return serializeStructuredRun(existing);
+        const wantsStdin = typeof request.stdinData === "string";
+        const child = nodeSpawn(request.file, request.args, {
+            cwd: request.cwd,
+            env: request.env,
+            stdio: wantsStdin ? ["pipe", "pipe", "pipe"] : ["ignore", "pipe", "pipe"],
+        });
+        if (wantsStdin)
+            child.stdin?.end(request.stdinData);
+        const run = {
+            request,
+            incarnationId: randomUUID(),
+            child,
+            pid: child.pid ?? -1,
+            status: "running",
+            exitCode: null,
+            signal: null,
+            stdoutSeq: 0,
+            stderrSeq: 0,
+            stdoutLog: "",
+            stderrLog: "",
+            stdoutTruncated: false,
+            stderrTruncated: false,
+        };
+        structuredRuns.set(request.runId, run);
+        evictStaleStructuredRuns();
+        child.stdout?.on("data", (chunk) => {
+            const text = chunk.toString();
+            const seq = appendRunLog(run, "stdout", text);
+            broadcast({
+                kind: "event",
+                event: "sdata",
+                sessionId: run.request.runId,
+                incarnationId: run.incarnationId,
+                stream: "stdout",
+                data: text,
+                seq,
+            });
+        });
+        child.stderr?.on("data", (chunk) => {
+            const text = chunk.toString();
+            const seq = appendRunLog(run, "stderr", text);
+            broadcast({
+                kind: "event",
+                event: "sdata",
+                sessionId: run.request.runId,
+                incarnationId: run.incarnationId,
+                stream: "stderr",
+                data: text,
+                seq,
+            });
+        });
+        child.on("error", () => {
+            // Spawn failures surface via close with no exit code; keep the record so
+            // attach still reports a terminal state to late adopters.
+        });
+        child.on("close", (code, signalName) => {
+            if (structuredRuns.get(run.request.runId) !== run || run.child !== child)
+                return;
+            run.child = null;
+            run.status = "exited";
+            run.exitCode = code;
+            run.signal = signalName === null || signalName === undefined ? null : Number(signalName) || signalNumberFromName(signalName);
+            broadcast({
+                kind: "event",
+                event: "sexit",
+                sessionId: run.request.runId,
+                incarnationId: run.incarnationId,
+                exitCode: run.exitCode ?? undefined,
+                signal: run.signal ?? undefined,
+            });
+        });
+        return serializeStructuredRun(run);
+    };
+    const structuredForget = (runId) => {
+        const run = structuredRuns.get(runId);
+        if (!run)
+            return;
+        structuredRuns.delete(runId);
+        if (run.child) {
+            try {
+                run.child.kill("SIGTERM");
+            }
+            catch { /* best-effort explicit deletion */ }
+            run.child = null;
+        }
+    };
     const handleRequest = (client, request) => {
         if (request.token !== token) {
             send(client.socket, { kind: "response", id: request.id, ok: false, error: "Unauthorized" });
@@ -200,6 +340,33 @@ export async function runTerminalDaemon(configPath) {
                     forget(String(params.sessionId ?? ""));
                     result = { ok: true };
                     break;
+                case "structuredSpawn":
+                    result = structuredSpawn(params);
+                    break;
+                case "structuredAttach": {
+                    const run = structuredRuns.get(String(params.runId ?? ""));
+                    result = { state: run ? serializeStructuredRun(run) : null };
+                    break;
+                }
+                case "structuredList":
+                    result = Array.from(structuredRuns.values(), serializeStructuredRun);
+                    break;
+                case "structuredKill": {
+                    const run = structuredRuns.get(String(params.runId ?? ""));
+                    const signal = typeof params.signal === "string" ? params.signal : "SIGTERM";
+                    if (run?.child) {
+                        try {
+                            run.child.kill(signal);
+                        }
+                        catch { /* best-effort interruption */ }
+                    }
+                    result = { ok: true };
+                    break;
+                }
+                case "structuredForget":
+                    structuredForget(String(params.runId ?? ""));
+                    result = { ok: true };
+                    break;
             }
             send(client.socket, { kind: "response", id: request.id, ok: true, result });
         }
@@ -259,6 +426,8 @@ export async function runTerminalDaemon(configPath) {
     const shutdown = () => {
         for (const sessionId of Array.from(sessions.keys()))
             forget(sessionId);
+        for (const runId of Array.from(structuredRuns.keys()))
+            structuredForget(runId);
         for (const client of clients)
             client.socket.destroy();
         server.close(() => process.exit(0));
@@ -295,6 +464,15 @@ function isProcessAlive(pid) {
         return false;
     }
 }
+function signalNumberFromName(signalName) {
+    const table = {
+        SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGILL: 4, SIGTRAP: 5, SIGABRT: 6,
+        SIGBUS: 7, SIGFPE: 8, SIGKILL: 9, SIGUSR1: 10, SIGSEGV: 11, SIGUSR2: 12,
+        SIGPIPE: 13, SIGALRM: 14, SIGTERM: 15, SIGCHLD: 17, SIGCONT: 18,
+        SIGSTOP: 19, SIGTSTP: 20,
+    };
+    return table[signalName] ?? 0;
+}
 function waitForProcessExit(pid) {
     return new Promise((resolve) => {
         const timer = setInterval(() => {