@co0ontty/wand 4.72.2-beta.gcc5d57e → 4.73.0

package/dist/render-structured-client.js

@@ -0,0 +1,513 @@
+import { lstatSync, readFileSync } from "node:fs";
+import net from "node:net";
+import { startDaemonHeartbeat, waitForDaemonSocket } from "./daemon-connection.js";
+import { getErrorMessage } from "./error-utils.js";
+import { STRUCTURED_RENDER_PROTOCOL_VERSION, decodeRenderFrames, encodeRenderFrame, structuredRenderPaths, } from "./render-structured-protocol.js";
+const REQUEST_TIMEOUT_MS = 10_000;
+const MAX_QUEUED_EVENTS = 2048;
+function checkSocket(path) {
+    const stat = lstatSync(path);
+    if (!stat.isSocket() || (typeof process.getuid === "function" && stat.uid !== process.getuid())
+        || (stat.mode & 0o777) !== 0o600) {
+        throw new Error("Structured Render socket is not a private socket owned by this user");
+    }
+}
+function toState(state, stdoutLog = "", stderrLog = "") {
+    return { ...state, stdoutLog, stderrLog };
+}
+class RemoteRun {
+    runId;
+    incarnationId;
+    pid;
+    client;
+    streamListeners = new Set();
+    exitListeners = new Set();
+    beforeListener = [];
+    pendingExit = null;
+    seq = { stdout: 0, stderr: 0 };
+    queued = [];
+    syncing = false;
+    overflow = false;
+    get exited() { return this.pendingExit !== null; }
+    constructor(runId, incarnationId, pid, client) {
+        this.runId = runId;
+        this.incarnationId = incarnationId;
+        this.pid = pid;
+        this.client = client;
+    }
+    interrupt(signal) {
+        void this.client.request("interrupt", { runId: this.runId, signal }).catch((error) => process.stderr.write(`[wand] structured Render interrupt failed: ${getErrorMessage(error)}\n`));
+    }
+    onStream(listener) {
+        this.streamListeners.add(listener);
+        const pending = this.beforeListener.splice(0);
+        if (pending.length > 0)
+            queueMicrotask(() => {
+                if (this.streamListeners.has(listener))
+                    for (const event of pending)
+                        listener(event);
+            });
+        return { dispose: () => this.streamListeners.delete(listener) };
+    }
+    onExit(listener) {
+        this.exitListeners.add(listener);
+        const event = this.pendingExit;
+        if (event)
+            queueMicrotask(() => { if (this.exitListeners.has(listener))
+                listener(event); });
+        return { dispose: () => this.exitListeners.delete(listener) };
+    }
+    acceptStream(event) {
+        const last = this.seq[event.stream];
+        if (event.seq <= last || this.pendingExit)
+            return;
+        if (event.seq !== last + 1)
+            throw new Error("non-contiguous structured Render stream");
+        this.seq[event.stream] = event.seq;
+        if (this.streamListeners.size === 0) {
+            this.beforeListener.push(event);
+            // Never silently lose bytes when a fast process finishes before its
+            // consumer installs listeners: fail rather than dropping the head.
+            if (this.beforeListener.length > MAX_QUEUED_EVENTS)
+                this.fail();
+            return;
+        }
+        for (const listener of this.streamListeners)
+            listener(event);
+    }
+    acceptExit(event) {
+        if (this.pendingExit)
+            return;
+        this.pendingExit = event;
+        for (const listener of this.exitListeners)
+            listener(event);
+    }
+    fail() {
+        this.client.dropHandle(this.runId, this);
+        // Explicit failure is preferable to a successful but incomplete turn.
+        this.acceptExit({ exitCode: 1, signal: null });
+    }
+}
+/** v2-only StructuredExecHost. It never accesses the PTY v1 or terminald sockets. */
+export class RenderStructuredClient {
+    configPath;
+    persistent = true;
+    socket = null;
+    buffer = Buffer.alloc(0);
+    token = "";
+    requestId = 0;
+    pending = new Map();
+    inventory = new Map();
+    observed = new Map();
+    handles = new Map();
+    orphanEvents = new Map();
+    orphanOverflow = new Set();
+    connecting = null;
+    reconnectTimer = null;
+    disposed = false;
+    connected = false;
+    fatalProtocol = null;
+    stopHeartbeat = null;
+    reconnectDelayMs = 500;
+    constructor(configPath) {
+        this.configPath = configPath;
+    }
+    connect() {
+        if (this.disposed)
+            return Promise.reject(new Error("Structured Render client disposed"));
+        if (this.fatalProtocol)
+            return Promise.reject(this.fatalProtocol);
+        if (this.connected && this.socket && !this.socket.destroyed)
+            return Promise.resolve();
+        if (this.connecting)
+            return this.connecting;
+        const connecting = this.open();
+        this.connecting = connecting;
+        void connecting.finally(() => { if (this.connecting === connecting)
+            this.connecting = null; })
+            .catch(() => this.scheduleReconnect());
+        return connecting;
+    }
+    async open() {
+        const paths = structuredRenderPaths(this.configPath);
+        checkSocket(paths.socketPath);
+        this.token = readFileSync(paths.tokenPath, "utf8").trim();
+        if (!this.token)
+            throw new Error("Structured Render token missing");
+        const socket = net.createConnection(paths.socketPath);
+        socket.setNoDelay(true);
+        this.socket = socket;
+        try {
+            await waitForDaemonSocket(socket);
+        }
+        catch (error) {
+            socket.destroy();
+            if (this.socket === socket)
+                this.socket = null;
+            throw error;
+        }
+        this.buffer = Buffer.alloc(0);
+        socket.on("data", (data) => {
+            if (this.socket === socket)
+                this.consume(data);
+        });
+        socket.on("close", () => this.onDisconnect(socket));
+        socket.on("error", (error) => this.onDisconnect(socket, error));
+        try {
+            const hello = await this.request("hello");
+            if (hello.protocolVersion !== STRUCTURED_RENDER_PROTOCOL_VERSION) {
+                this.fatalProtocol = new Error("Structured Render protocol mismatch; refusing degraded mode");
+                throw this.fatalProtocol;
+            }
+            const result = await this.request("list");
+            this.inventory.clear();
+            for (const state of result.runs)
+                this.inventory.set(state.runId, state);
+            for (const [runId, handle] of this.handles) {
+                const state = this.inventory.get(runId);
+                if (!state || state.incarnationId !== handle.incarnationId) {
+                    handle.fail();
+                    continue;
+                }
+                await this.catchUp(handle);
+            }
+            if (this.disposed || this.socket !== socket)
+                throw new Error("Structured Render disconnected during adoption");
+            this.connected = true;
+            this.reconnectDelayMs = 500;
+            this.stopHeartbeat?.();
+            this.stopHeartbeat = startDaemonHeartbeat(socket, () => this.request("ping"), { socketPath: paths.socketPath });
+        }
+        catch (error) {
+            if (/protocolMismatch/.test(getErrorMessage(error))) {
+                this.fatalProtocol = new Error("Structured Render v2 protocol mismatch; refusing degraded mode");
+            }
+            socket.destroy();
+            this.onDisconnect(socket);
+            throw this.fatalProtocol ?? error;
+        }
+    }
+    async request(method, params) {
+        const socket = this.socket;
+        if (!socket || socket.destroyed)
+            throw new Error("Structured Render unavailable");
+        const id = ++this.requestId;
+        const frame = encodeRenderFrame({ id, token: this.token,
+            protocolVersion: STRUCTURED_RENDER_PROTOCOL_VERSION, method, params });
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`Structured Render ${method} timed out`));
+            }, REQUEST_TIMEOUT_MS);
+            this.pending.set(id, { resolve, reject, timer });
+            socket.write(frame, (error) => {
+                if (error) {
+                    const pending = this.pending.get(id);
+                    if (pending) {
+                        clearTimeout(pending.timer);
+                        this.pending.delete(id);
+                        pending.reject(error);
+                    }
+                }
+            });
+        });
+    }
+    consume(data) {
+        try {
+            this.buffer = Buffer.concat([this.buffer, data]);
+            const decoded = decodeRenderFrames(this.buffer);
+            this.buffer = decoded.rest;
+            for (const frame of decoded.frames) {
+                if ("event" in frame) {
+                    this.acceptEvent(frame);
+                    continue;
+                }
+                const pending = this.pending.get(frame.id);
+                if (!pending)
+                    continue;
+                this.pending.delete(frame.id);
+                clearTimeout(pending.timer);
+                if (frame.ok)
+                    pending.resolve(frame.result);
+                else
+                    pending.reject(new Error(`Structured Render ${frame.error?.code ?? "error"}: ${frame.error?.message ?? "unknown"}`));
+            }
+        }
+        catch (error) {
+            this.socket?.destroy(error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+    acceptEvent(event) {
+        if (event.event === "reconcile")
+            return;
+        const runId = event.runId;
+        const handle = this.handles.get(runId);
+        if (handle && handle.incarnationId === event.incarnationId) {
+            if (handle.syncing || !this.connected) {
+                this.queue(handle.queued, event, runId);
+                if (handle.queued.length >= MAX_QUEUED_EVENTS)
+                    handle.overflow = true;
+            }
+            else if (event.event === "exit") {
+                void this.catchUp(handle).then(() => handle.acceptExit(event)).catch(() => handle.fail());
+            }
+            else if (event.seq !== handle.seq[event.stream] + 1) {
+                void this.catchUp(handle).catch(() => handle.fail());
+                this.queue(handle.queued, event, runId);
+            }
+            else {
+                handle.acceptStream(event);
+            }
+            return;
+        }
+        const pending = this.orphanEvents.get(runId) ?? [];
+        this.queue(pending, event, runId);
+        this.orphanEvents.set(runId, pending);
+    }
+    queue(queue, event, runId) {
+        if (queue.length >= MAX_QUEUED_EVENTS) {
+            queue.shift();
+            this.orphanOverflow.add(runId);
+        }
+        queue.push(event);
+    }
+    async catchUp(handle) {
+        if (handle.syncing)
+            return;
+        handle.syncing = true;
+        try {
+            for (let pages = 0; pages < 2048; pages++) {
+                const page = await this.request("attach", { runId: handle.runId,
+                    afterStdoutSeq: handle.seq.stdout, afterStderrSeq: handle.seq.stderr });
+                if (page.state.incarnationId !== handle.incarnationId)
+                    throw new Error("structured owner changed");
+                this.replayStream(handle, "stdout", page.stdout);
+                this.replayStream(handle, "stderr", page.stderr);
+                this.inventory.set(handle.runId, page.state);
+                if (page.stdout.complete && page.stderr.complete)
+                    break;
+                if (pages === 2047)
+                    throw new Error("structured replay page cap exceeded");
+            }
+            if (handle.overflow || this.orphanOverflow.has(handle.runId)) {
+                handle.overflow = false;
+                this.orphanOverflow.delete(handle.runId);
+                // A bounded event queue overflow is recoverable from the authoritative
+                // replay. Recheck the tail before draining any surviving events.
+                handle.queued.splice(0);
+                for (let pages = 0; pages < 2048; pages++) {
+                    const tail = await this.request("attach", { runId: handle.runId,
+                        afterStdoutSeq: handle.seq.stdout, afterStderrSeq: handle.seq.stderr });
+                    this.replayStream(handle, "stdout", tail.stdout);
+                    this.replayStream(handle, "stderr", tail.stderr);
+                    this.inventory.set(handle.runId, tail.state);
+                    if (tail.stdout.complete && tail.stderr.complete)
+                        break;
+                    if (pages === 2047)
+                        throw new Error("structured overflow replay page cap exceeded");
+                }
+            }
+            if (handle.overflow || this.orphanOverflow.has(handle.runId)) {
+                throw new Error("structured event queue overflowed again during replay");
+            }
+            const latest = this.inventory.get(handle.runId);
+            const queued = handle.queued.splice(0);
+            for (const event of queued) {
+                if (event.incarnationId !== handle.incarnationId)
+                    continue;
+                if (event.event === "stream") {
+                    if (event.seq <= handle.seq[event.stream])
+                        continue;
+                    if (event.seq !== handle.seq[event.stream] + 1)
+                        throw new Error("structured live event gap");
+                    handle.acceptStream(event);
+                }
+                else if (event.event === "exit")
+                    handle.acceptExit(event);
+            }
+            if (latest?.status === "exited") {
+                handle.acceptExit({ exitCode: latest.exitCode, signal: latest.signal });
+            }
+        }
+        catch (error) {
+            process.stderr.write(`[wand] structured Render replay failed for ${handle.runId}: ${getErrorMessage(error)}\n`);
+            handle.fail();
+            throw error;
+        }
+        finally {
+            handle.syncing = false;
+        }
+    }
+    replayStream(handle, stream, replay) {
+        if (replay.resetRequired && handle.seq[stream] !== 0) {
+            throw new Error("structured replay window lost a live stream segment");
+        }
+        // A new adoption with a truncated head is handled by the recovery manager;
+        // an active handle may not quietly skip that head.
+        if (replay.resetRequired && replay.chunks[0]?.seq !== 1) {
+            throw new Error("structured replay cannot rebuild an active turn from a truncated head");
+        }
+        for (const chunk of replay.chunks) {
+            if (chunk.seq > handle.seq[stream])
+                handle.acceptStream({ stream, ...chunk });
+        }
+    }
+    async collect(runId) {
+        const logs = { stdout: [], stderr: [] };
+        const cursor = { stdout: 0, stderr: 0 };
+        for (let pages = 0; pages < 2048; pages++) {
+            let page;
+            try {
+                page = await this.request("attach", { runId, afterStdoutSeq: cursor.stdout,
+                    afterStderrSeq: cursor.stderr });
+            }
+            catch (error) {
+                if (/notFound/.test(getErrorMessage(error)))
+                    return null;
+                throw error;
+            }
+            for (const stream of ["stdout", "stderr"]) {
+                const replay = page[stream];
+                if (replay.resetRequired && cursor[stream] !== 0)
+                    throw new Error("structured snapshot changed during replay");
+                if (replay.resetRequired && !page.state[`${stream}Truncated`]) {
+                    throw new Error("structured replay cursor gap without truncation");
+                }
+                for (const chunk of replay.chunks)
+                    logs[stream].push(chunk.data);
+                cursor[stream] = replay.nextSeq;
+            }
+            if (page.stdout.complete && page.stderr.complete) {
+                const state = toState(page.state, logs.stdout.join(""), logs.stderr.join(""));
+                this.inventory.set(runId, page.state);
+                this.observed.set(runId, { incarnationId: state.incarnationId,
+                    stdoutSeq: state.stdoutSeq, stderrSeq: state.stderrSeq });
+                return state;
+            }
+        }
+        throw new Error("structured snapshot exceeded replay page cap");
+    }
+    /** Events can overtake the spawn response. Feed the contiguous prefix before
+     * paging so a fast >8 MiB child does not falsely lose its already-received head. */
+    primeBuffered(handle) {
+        const buffered = this.orphanEvents.get(handle.runId) ?? [];
+        this.orphanEvents.delete(handle.runId);
+        for (const event of buffered) {
+            if (event.incarnationId !== handle.incarnationId)
+                continue;
+            if (event.event === "exit") {
+                handle.queued.push(event);
+                continue;
+            }
+            if (event.seq <= handle.seq[event.stream])
+                continue;
+            if (event.seq !== handle.seq[event.stream] + 1) {
+                handle.queued.push(event);
+                continue;
+            }
+            handle.acceptStream(event);
+        }
+    }
+    async spawnStructured(request) {
+        await this.connect();
+        const existing = this.handles.get(request.runId);
+        if (existing && !existing.exited)
+            return existing;
+        if (existing)
+            this.handles.delete(request.runId);
+        const env = Object.fromEntries(Object.entries(request.env).filter((entry) => typeof entry[1] === "string"));
+        const result = await this.request("spawn", { ...request, env });
+        const handle = new RemoteRun(request.runId, result.state.incarnationId, result.state.pid, this);
+        this.handles.set(request.runId, handle);
+        this.primeBuffered(handle);
+        try {
+            await this.catchUp(handle);
+            if (result.state.status === "exited")
+                handle.acceptExit({ exitCode: result.state.exitCode, signal: result.state.signal });
+            return handle;
+        }
+        catch (error) {
+            this.dropHandle(request.runId, handle);
+            throw error;
+        }
+    }
+    async attachRun(runId) {
+        await this.connect();
+        return this.collect(runId);
+    }
+    async adoptRun(runId) {
+        await this.connect();
+        const prior = this.observed.get(runId);
+        const known = this.inventory.get(runId);
+        if (!known || known.status !== "running")
+            return null;
+        const handle = new RemoteRun(runId, known.incarnationId, known.pid, this);
+        if (prior?.incarnationId === known.incarnationId) {
+            handle.seq.stdout = prior.stdoutSeq;
+            handle.seq.stderr = prior.stderrSeq;
+        }
+        this.handles.set(runId, handle);
+        this.primeBuffered(handle);
+        await this.catchUp(handle);
+        return handle;
+    }
+    async listRuns() {
+        await this.connect();
+        const result = await this.request("list");
+        for (const state of result.runs)
+            this.inventory.set(state.runId, state);
+        return result.runs.map((state) => toState(state));
+    }
+    forgetRun(runId) {
+        this.handles.delete(runId);
+        this.inventory.delete(runId);
+        this.observed.delete(runId);
+        this.orphanEvents.delete(runId);
+        this.orphanOverflow.delete(runId);
+        void this.request("forget", { runId }).catch(() => { });
+    }
+    dropHandle(runId, handle) {
+        if (this.handles.get(runId) === handle)
+            this.handles.delete(runId);
+    }
+    disconnect() {
+        this.disposed = true;
+        this.stopHeartbeat?.();
+        this.stopHeartbeat = null;
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        this.socket?.destroy();
+        this.socket = null;
+        this.rejectPending(new Error("Structured Render client disconnected"));
+        this.handles.clear();
+    }
+    onDisconnect(socket, error) {
+        if (this.socket !== socket)
+            return;
+        this.connected = false;
+        this.socket = null;
+        this.stopHeartbeat?.();
+        this.stopHeartbeat = null;
+        socket.destroy();
+        this.buffer = Buffer.alloc(0);
+        this.rejectPending(error ?? new Error("Structured Render disconnected"));
+        this.scheduleReconnect();
+    }
+    scheduleReconnect() {
+        if (this.disposed || this.fatalProtocol || this.reconnectTimer)
+            return;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            void this.connect().catch(() => { });
+        }, this.reconnectDelayMs);
+        this.reconnectDelayMs = Math.min(this.reconnectDelayMs * 2, 10_000);
+        this.reconnectTimer.unref?.();
+    }
+    rejectPending(error) {
+        for (const pending of this.pending.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.pending.clear();
+    }
+}

package/dist/render-structured-host.d.ts

@@ -0,0 +1,31 @@
+import { RenderStructuredClient } from "./render-structured-client.js";
+import type { StructuredExecHost, StructuredExecProcess, StructuredRunState, StructuredSpawnRequest } from "./structured-exec-host.js";
+type Owner = "legacy" | "rust";
+/** Resolve the separate v2 executable; do not confuse it with PTY v1 wand-render. */
+export declare function resolveStructuredRenderBinary(configPath: string): string | null;
+/**
+ * A stable runId can belong to exactly one persistent daemon. Configuration
+ * chooses only new runs; existing owners are always resolved by inventories.
+ */
+export declare class CompositeStructuredExecHost implements StructuredExecHost {
+    private readonly legacy;
+    private readonly rust;
+    private readonly newOwner;
+    readonly persistent = true;
+    private readonly owners;
+    private readonly starting;
+    constructor(legacy: StructuredExecHost | null, rust: StructuredExecHost | null, newOwner: Owner);
+    private getHost;
+    listRuns(): Promise<StructuredRunState[]>;
+    private ownerOf;
+    spawnStructured(request: StructuredSpawnRequest): Promise<StructuredExecProcess>;
+    attachRun(runId: string): Promise<StructuredRunState | null>;
+    adoptRun(runId: string): Promise<StructuredExecProcess | null>;
+    forgetRun(runId: string): void;
+}
+/** Default legacy. v2 is adopted even on rollback when it still owns runs. */
+export declare function createUpgradeAwareStructuredHost(configPath: string, legacy: StructuredExecHost | null, processHost?: "legacy" | "rust"): Promise<{
+    host: StructuredExecHost | undefined;
+    rustClient: RenderStructuredClient | null;
+}>;
+export {};