@co0ontty/wand 4.46.0 → 4.47.0

package/dist/structured-exec-host.js

@@ -0,0 +1,117 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+/**
+ * Ownership seam for structured CLI runs, mirroring TerminalHost for PTYs.
+ * Persistent adapters (terminald) outlive web restarts; the in-process adapter
+ * deliberately keeps the legacy "die with the server" lifecycle.
+ */
+/** Per-stream replay log cap inside the daemon. Reducers need full history. */
+export const STRUCTURED_RUN_LOG_MAX_CHARS = 8 * 1024 * 1024;
+/** Resolve a stable daemon-side key for a session's active structured run. */
+export function structuredRunId(sessionId) {
+    return `structured:${sessionId}`;
+}
+class InProcessStructuredExecProcess {
+    runId;
+    child;
+    incarnationId = randomUUID();
+    stdoutSeq = 0;
+    stderrSeq = 0;
+    constructor(runId, child) {
+        this.runId = runId;
+        this.child = child;
+    }
+    get pid() {
+        return this.child.pid ?? -1;
+    }
+    interrupt(signal) {
+        try {
+            this.child.kill((signal ?? "SIGTERM"));
+        }
+        catch { /* best-effort */ }
+    }
+    onStream(listener) {
+        const stdoutHandler = (chunk) => listener({ stream: "stdout", data: chunk.toString(), seq: ++this.stdoutSeq });
+        const stderrHandler = (chunk) => listener({ stream: "stderr", data: chunk.toString(), seq: ++this.stderrSeq });
+        this.child.stdout?.on("data", stdoutHandler);
+        this.child.stderr?.on("data", stderrHandler);
+        return {
+            dispose: () => {
+                this.child.stdout?.off("data", stdoutHandler);
+                this.child.stderr?.off("data", stderrHandler);
+            },
+        };
+    }
+    onExit(listener) {
+        let settled = false;
+        const closeHandler = (code, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            listener({ exitCode: code, signal: signal === null || signal === undefined ? null : osSignalNumber(signal) });
+        };
+        const errorHandler = () => {
+            if (settled)
+                return;
+            settled = true;
+            listener({ exitCode: null, signal: null });
+        };
+        this.child.on("close", closeHandler);
+        this.child.on("error", errorHandler);
+        return {
+            dispose: () => {
+                this.child.off("close", closeHandler);
+                this.child.off("error", errorHandler);
+            },
+        };
+    }
+}
+/** Legacy/local adapter and deterministic test adapter for the structured seam. */
+export class InProcessStructuredExecHost {
+    persistent = false;
+    processes = new Map();
+    async spawnStructured(request) {
+        const existing = this.processes.get(request.runId);
+        if (existing && existing.pid > 0)
+            return existing;
+        const wantsStdin = typeof request.stdinData === "string";
+        const child = spawn(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 wrapped = new InProcessStructuredExecProcess(request.runId, child);
+        this.processes.set(request.runId, wrapped);
+        wrapped.onExit(() => {
+            // Keep exited records until forgetRun so attachRun can still answer.
+        });
+        return wrapped;
+    }
+    async attachRun() {
+        return null;
+    }
+    async adoptRun() {
+        return null;
+    }
+    async listRuns() {
+        return [];
+    }
+    forgetRun(runId) {
+        const wrapped = this.processes.get(runId);
+        this.processes.delete(runId);
+        if (wrapped)
+            wrapped.interrupt();
+    }
+}
+/** Map a NodeJS.Signals name to the numeric value used by waitpid-style APIs. */
+export function osSignalNumber(signal) {
+    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[signal] ?? 0;
+}

package/dist/structured-exec-pump.d.ts

@@ -0,0 +1,37 @@
+import { spawn } from "node:child_process";
+import type { StructuredExecHost } from "./structured-exec-host.js";
+import type { StructuredRunnerExecution, StructuredRunnerObserver, StructuredRunnerResult, StructuredRunnerTurnState } from "./structured-runner.js";
+/**
+ * Shared pump for CLI-backed structured runners. One implementation drives both
+ * ownership modes: a local ChildProcess (legacy lifecycle, test injection) and
+ * a daemon-backed StructuredExecProcess whose streams survive web restarts.
+ * Per-provider differences stay in the adapter via processLine/finalize hooks.
+ */
+export interface StructuredCliPumpContext<S extends StructuredRunnerTurnState> {
+    state: S;
+    stderr: string;
+    observer: StructuredRunnerObserver;
+    /** Ask the underlying CLI to stop early (e.g. Claude ask-user-question). */
+    requestStop(): void;
+}
+export interface StructuredCliPumpOptions<S extends StructuredRunnerTurnState> {
+    sessionId: string;
+    file: string;
+    args: string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    /** Written to stdin once then closed; omit for stdio-ignore CLIs. */
+    stdinData?: string;
+    observer: StructuredRunnerObserver;
+    /** When set and persistent, the run is owned by terminald instead of us. */
+    execHost?: StructuredExecHost;
+    /** Local/test spawn injection; ignored when the execHost takes over. */
+    spawnProcess?: typeof spawn;
+    /** Fresh per-run state (or reducer-owned state) for the pump context. */
+    createState(): S;
+    processLine(line: string, ctx: StructuredCliPumpContext<S>): void;
+    /** Raw stdout text hook (e.g. Claude stdoutTail bookkeeping). */
+    onStdoutText?(text: string): void;
+    finalize(ctx: StructuredCliPumpContext<S>, exitCode: number | null, signal: NodeJS.Signals | null, spawnError?: NodeJS.ErrnoException): StructuredRunnerResult;
+}
+export declare function startStructuredCli<S extends StructuredRunnerTurnState>(options: StructuredCliPumpOptions<S>): StructuredRunnerExecution;

package/dist/structured-exec-pump.js

@@ -0,0 +1,127 @@
+import { spawn } from "node:child_process";
+export function startStructuredCli(options) {
+    const spawnedAt = new Date().toISOString();
+    const observer = options.observer;
+    const ctx = {
+        state: options.createState(),
+        stderr: "",
+        observer,
+        requestStop: () => source?.interrupt(),
+    };
+    let source = null;
+    let sourceReady;
+    let lineBuffer = "";
+    let settled = false;
+    let resolveCompletion;
+    const completion = new Promise((resolve) => {
+        resolveCompletion = resolve;
+    });
+    const finish = (exitCode, signal, spawnError) => {
+        if (settled)
+            return;
+        settled = true;
+        if (lineBuffer.trim())
+            options.processLine(lineBuffer, ctx);
+        lineBuffer = "";
+        resolveCompletion(options.finalize(ctx, exitCode, signal, spawnError));
+    };
+    const handleStdoutText = (text) => {
+        if (!observer.isActive())
+            return;
+        observer.onStdout?.(text);
+        options.onStdoutText?.(text);
+        lineBuffer += text;
+        const lines = lineBuffer.split("\n");
+        lineBuffer = lines.pop() ?? "";
+        for (const line of lines)
+            options.processLine(line, ctx);
+    };
+    const handleStderrText = (text) => {
+        if (!observer.isActive())
+            return;
+        observer.onStderr?.(text);
+        ctx.stderr += text;
+    };
+    const useRemoteHost = options.execHost?.persistent === true;
+    if (useRemoteHost) {
+        const host = options.execHost;
+        const request = {
+            runId: `structured:${options.sessionId}`,
+            file: options.file,
+            args: options.args,
+            cwd: options.cwd,
+            env: options.env,
+            ...(options.stdinData !== undefined ? { stdinData: options.stdinData } : {}),
+        };
+        let pendingInterrupt = null;
+        sourceReady = host.spawnStructured(request).then((handle) => {
+            source = { pid: handle.pid, interrupt: () => handle.interrupt() };
+            if (pendingInterrupt !== null)
+                handle.interrupt(pendingInterrupt);
+            wireRemoteHandle(handle, handleStdoutText, handleStderrText, finish);
+        }, () => {
+            // Daemon vanished between health check and spawn; surface as spawn error.
+            finish(null, null, Object.assign(new Error(`terminal daemon unavailable for ${options.file}`), { code: "EDAEMON" }));
+        });
+        source = {
+            pid: null,
+            interrupt: (signal) => {
+                pendingInterrupt = signal ?? "SIGTERM";
+                void sourceReady.then(() => source?.interrupt());
+            },
+        };
+    }
+    else {
+        const spawnProcess = options.spawnProcess ?? spawn;
+        const wantsStdin = typeof options.stdinData === "string";
+        const child = spawnProcess(options.file, options.args, {
+            cwd: options.cwd,
+            env: options.env,
+            stdio: wantsStdin ? ["pipe", "pipe", "pipe"] : ["ignore", "pipe", "pipe"],
+        });
+        if (wantsStdin)
+            child.stdin?.end(options.stdinData);
+        source = { pid: child.pid ?? null, interrupt: () => child.kill("SIGTERM") };
+        child.stdout?.on("data", (chunk) => handleStdoutText(chunk.toString()));
+        child.stderr?.on("data", (chunk) => handleStderrText(chunk.toString()));
+        child.on("error", (error) => finish(null, null, error));
+        child.on("close", (exitCode, signalName) => finish(exitCode, signalName === null || signalName === undefined ? null : signalName));
+        sourceReady = Promise.resolve();
+    }
+    return {
+        args: options.args,
+        spawnedAt,
+        get pid() {
+            return source?.pid ?? null;
+        },
+        completion,
+        interrupt: () => {
+            try {
+                source?.interrupt();
+            }
+            catch { /* best-effort external interruption */ }
+        },
+    };
+}
+function wireRemoteHandle(handle, onStdout, onStderr, finish) {
+    handle.onStream((event) => {
+        if (event.stream === "stdout")
+            onStdout(event.data);
+        else
+            onStderr(event.data);
+    });
+    handle.onExit((event) => {
+        finish(event.exitCode, numericToSignalName(event.signal));
+    });
+}
+function numericToSignalName(signal) {
+    if (signal === null || signal === 0)
+        return null;
+    const names = {
+        1: "SIGHUP", 2: "SIGINT", 3: "SIGQUIT", 4: "SIGILL", 5: "SIGTRAP", 6: "SIGABRT",
+        7: "SIGBUS", 8: "SIGFPE", 9: "SIGKILL", 10: "SIGUSR1", 11: "SIGSEGV", 12: "SIGUSR2",
+        13: "SIGPIPE", 14: "SIGALRM", 15: "SIGTERM", 17: "SIGCHLD", 18: "SIGCONT",
+        19: "SIGSTOP", 20: "SIGTSTP",
+    };
+    return names[signal] ?? "SIGTERM";
+}

package/dist/structured-grok-adapter.d.ts

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import type { StructuredExecHost } from "./structured-exec-host.js";
 import type { StructuredRunnerAdapter, StructuredRunnerContext, StructuredRunnerExecution, StructuredRunnerObserver, StructuredRunnerTurnState } from "./structured-runner.js";
 import type { SessionSnapshot } from "./types.js";
 export type GrokTurnState = StructuredRunnerTurnState;
@@ -7,6 +8,7 @@ export declare function buildGrokArgs(session: SessionSnapshot, prompt: string):
 export declare function applyGrokEvent(state: GrokTurnState, event: Record<string, unknown>): string | null;
 export declare class GrokRunner implements StructuredRunnerAdapter {
     private readonly spawnProcess;
-    constructor(spawnProcess?: typeof spawn);
+    private readonly execHost?;
+    constructor(spawnProcess?: typeof spawn, execHost?: StructuredExecHost | undefined);
     start(context: StructuredRunnerContext, observer: StructuredRunnerObserver): StructuredRunnerExecution;
 }

package/dist/structured-grok-adapter.js

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { startStructuredCli } from "./structured-exec-pump.js";
 import { thinkingEffortToGrokEffort } from "./structured-provider-common.js";
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
@@ -70,87 +71,47 @@ export function applyGrokEvent(state, event) {
 }
 export class GrokRunner {
     spawnProcess;
-    constructor(spawnProcess = spawn) {
+    execHost;
+    constructor(spawnProcess = spawn, execHost) {
         this.spawnProcess = spawnProcess;
+        this.execHost = execHost;
     }
     start(context, observer) {
         const args = buildGrokArgs(context.session, context.prompt);
-        const spawnedAt = new Date().toISOString();
-        const child = this.spawnProcess("grok", args, {
-            cwd: context.session.cwd,
-            env: context.env,
-            stdio: ["ignore", "pipe", "pipe"],
-        });
         const state = {
             blocks: [],
             result: "",
             sessionId: context.session.claudeSessionId,
             model: context.session.selectedModel ?? context.session.structuredState?.model,
         };
-        let lineBuffer = "";
-        let stderr = "";
         let primaryError = null;
-        let settled = false;
-        const finish = (exitCode, signal, spawnError) => ({
-            state, exitCode, signal, stderr, primaryError, ...(spawnError ? { spawnError } : {}),
-        });
-        const processLine = (line) => {
-            if (!observer.isActive())
-                return;
-            const trimmed = line.trim();
-            if (!trimmed)
-                return;
-            try {
-                const event = JSON.parse(trimmed);
-                observer.onEvent?.(event);
-                primaryError = applyGrokEvent(state, event) ?? primaryError;
-                observer.onUpdate(state);
-            }
-            catch { /* Grok diagnostics belong on stderr; ignore non-JSON stdout defensively. */ }
-        };
-        const completion = new Promise((resolve) => {
-            child.stdout?.on("data", (chunk) => {
-                if (!observer.isActive())
-                    return;
-                const text = chunk.toString();
-                observer.onStdout?.(text);
-                lineBuffer += text;
-                const lines = lineBuffer.split("\n");
-                lineBuffer = lines.pop() ?? "";
-                for (const line of lines)
-                    processLine(line);
-            });
-            child.stderr?.on("data", (chunk) => {
+        return startStructuredCli({
+            sessionId: context.session.id,
+            file: "grok",
+            args,
+            cwd: context.session.cwd,
+            env: context.env,
+            observer,
+            execHost: this.execHost,
+            spawnProcess: this.spawnProcess,
+            createState: () => state,
+            processLine: (line) => {
                 if (!observer.isActive())
                     return;
-                const text = chunk.toString();
-                observer.onStderr?.(text);
-                stderr += text;
-            });
-            child.on("error", (error) => {
-                if (settled)
+                const trimmed = line.trim();
+                if (!trimmed)
                     return;
-                settled = true;
-                resolve(finish(null, null, error));
-            });
-            child.on("close", (exitCode, signal) => {
-                if (settled)
-                    return;
-                settled = true;
-                if (lineBuffer.trim())
-                    processLine(lineBuffer);
-                resolve(finish(exitCode, signal));
-            });
+                try {
+                    const event = JSON.parse(trimmed);
+                    observer.onEvent?.(event);
+                    primaryError = applyGrokEvent(state, event) ?? primaryError;
+                    observer.onUpdate(state);
+                }
+                catch { /* Grok diagnostics belong on stderr; ignore non-JSON stdout defensively. */ }
+            },
+            finalize: (ctx, exitCode, signal, spawnError) => ({
+                state, exitCode, signal, stderr: ctx.stderr, primaryError, ...(spawnError ? { spawnError } : {}),
+            }),
         });
-        return {
-            args,
-            spawnedAt,
-            pid: child.pid ?? null,
-            completion,
-            interrupt: () => { try {
-                child.kill("SIGTERM");
-            }
-            catch { /* best effort */ } },
-        };
     }
 }

package/dist/structured-opencode-adapter.d.ts

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import type { StructuredExecHost } from "./structured-exec-host.js";
 import type { StructuredRunnerAdapter, StructuredRunnerContext, StructuredRunnerExecution, StructuredRunnerObserver, StructuredRunnerTurnState } from "./structured-runner.js";
 import type { SessionSnapshot } from "./types.js";
 export type OpenCodeTurnState = StructuredRunnerTurnState;
@@ -8,6 +9,7 @@ export declare function applyOpenCodeEvent(turnState: OpenCodeTurnState, event:
 /** Production adapter for the external `opencode run --format json` process. */
 export declare class OpenCodeRunner implements StructuredRunnerAdapter {
     private readonly spawnProcess;
-    constructor(spawnProcess?: typeof spawn);
+    private readonly execHost?;
+    constructor(spawnProcess?: typeof spawn, execHost?: StructuredExecHost | undefined);
     start(context: StructuredRunnerContext, observer: StructuredRunnerObserver): StructuredRunnerExecution;
 }

package/dist/structured-opencode-adapter.js

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { spawn } from "node:child_process";
+import { startStructuredCli } from "./structured-exec-pump.js";
 import { thinkingEffortToOpenCodeVariant } from "./structured-provider-common.js";
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
@@ -117,18 +118,13 @@ export function applyOpenCodeEvent(turnState, event, createId = randomUUID) {
 /** Production adapter for the external `opencode run --format json` process. */
 export class OpenCodeRunner {
     spawnProcess;
-    constructor(spawnProcess = spawn) {
+    execHost;
+    constructor(spawnProcess = spawn, execHost) {
         this.spawnProcess = spawnProcess;
+        this.execHost = execHost;
     }
     start(context, observer) {
         const args = buildOpenCodeArgs(context.session);
-        const spawnedAt = new Date().toISOString();
-        const child = this.spawnProcess("opencode", args, {
-            cwd: context.session.cwd,
-            env: context.env,
-            stdio: ["pipe", "pipe", "pipe"],
-        });
-        child.stdin?.end(context.prompt);
         const state = {
             blocks: [],
             result: "",
@@ -136,83 +132,45 @@ export class OpenCodeRunner {
             model: context.session.selectedModel ?? context.session.structuredState?.model,
             usage: undefined,
         };
-        let lineBuffer = "";
-        let stderr = "";
         let primaryError = null;
-        let settled = false;
-        const result = (exitCode, signal, spawnError) => ({
-            state,
-            exitCode,
-            signal,
-            stderr,
-            primaryError,
-            ...(spawnError ? { spawnError } : {}),
-        });
-        const processLine = (line) => {
-            if (!observer.isActive())
-                return;
-            const trimmed = line.trim();
-            if (!trimmed)
-                return;
-            let event;
-            try {
-                event = JSON.parse(trimmed);
-            }
-            catch {
-                return;
-            }
-            observer.onEvent?.(event);
-            const error = applyOpenCodeEvent(state, event);
-            if (error)
-                primaryError = error;
-            observer.onUpdate(state);
-        };
-        const completion = new Promise((resolve) => {
-            child.stdout?.on("data", (chunk) => {
-                if (!observer.isActive())
-                    return;
-                const text = chunk.toString();
-                observer.onStdout?.(text);
-                lineBuffer += text;
-                const lines = lineBuffer.split("\n");
-                lineBuffer = lines.pop() ?? "";
-                for (const line of lines)
-                    processLine(line);
-            });
-            child.stderr?.on("data", (chunk) => {
+        return startStructuredCli({
+            sessionId: context.session.id,
+            file: "opencode",
+            args,
+            cwd: context.session.cwd,
+            env: context.env,
+            stdinData: context.prompt,
+            observer,
+            execHost: this.execHost,
+            spawnProcess: this.spawnProcess,
+            createState: () => state,
+            processLine: (line) => {
                 if (!observer.isActive())
                     return;
-                const text = chunk.toString();
-                observer.onStderr?.(text);
-                stderr += text;
-            });
-            child.on("error", (error) => {
-                if (settled)
-                    return;
-                settled = true;
-                resolve(result(null, null, error));
-            });
-            child.on("close", (exitCode, signal) => {
-                if (settled)
+                const trimmed = line.trim();
+                if (!trimmed)
                     return;
-                settled = true;
-                if (lineBuffer.trim())
-                    processLine(lineBuffer);
-                lineBuffer = "";
-                resolve(result(exitCode, signal));
-            });
-        });
-        return {
-            args,
-            spawnedAt,
-            pid: child.pid ?? null,
-            completion,
-            interrupt: () => {
+                let event;
                 try {
-                    child.kill("SIGTERM");
+                    event = JSON.parse(trimmed);
                 }
-                catch { /* best-effort external interruption */ }
+                catch {
+                    return;
+                }
+                observer.onEvent?.(event);
+                const error = applyOpenCodeEvent(state, event);
+                if (error)
+                    primaryError = error;
+                observer.onUpdate(state);
             },
-        };
+            finalize: (ctx, exitCode, signal, spawnError) => ({
+                state,
+                exitCode,
+                signal,
+                stderr: ctx.stderr,
+                primaryError,
+                ...(spawnError ? { spawnError } : {}),
+            }),
+        });
     }
 }

package/dist/structured-pi-adapter.d.ts

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import type { StructuredExecHost } from "./structured-exec-host.js";
 import type { StructuredRunnerAdapter, StructuredRunnerContext, StructuredRunnerExecution, StructuredRunnerObserver, StructuredRunnerTurnState } from "./structured-runner.js";
 import type { SessionSnapshot } from "./types.js";
 export declare function buildPiArgs(session: SessionSnapshot, prompt: string): string[];
@@ -6,6 +7,7 @@ export declare function piToolName(name: string): string;
 export declare function applyPiEvent(state: StructuredRunnerTurnState, event: Record<string, unknown>): string | null;
 export declare class PiRunner implements StructuredRunnerAdapter {
     private readonly spawnProcess;
-    constructor(spawnProcess?: typeof spawn);
+    private readonly execHost?;
+    constructor(spawnProcess?: typeof spawn, execHost?: StructuredExecHost | undefined);
     start(context: StructuredRunnerContext, observer: StructuredRunnerObserver): StructuredRunnerExecution;
 }