@co0ontty/wand 4.72.2 → 4.75.0-beta.g1d477a2

package/dist/render-protocol.js

@@ -0,0 +1,99 @@
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/**
+ * Render 协议 v1 的 TS 镜像。Rust 单一真源在
+ * `render/crates/wand-render-protocol/src/lib.rs`，契约文档在
+ * `render/docs/render-protocol.md`（本仓库 `docs/render-protocol.md` 只是指针）。
+ *
+ * 两侧常量与字段名必须逐一对齐；任一侧改动都要同时提升版本号并更新文档。
+ */
+export const RENDER_PROTOCOL_VERSION = 1;
+/** 单帧上限：`u32` 大端长度前缀 + UTF-8 JSON。 */
+export const MAX_FRAME_BYTES = 64 * 1024 * 1024;
+/** 与 `PTY_OUTPUT_MAX_SIZE` 对齐（chunk 窗口 / output 有界）。 */
+export const RENDER_PTY_OUTPUT_MAX_CHARS = 200_000;
+/**
+ * config 路径的 canonical 形式：`realpathSync` 解析符号链接，失败（文件尚未创建）
+ * 才回退纯词法的 `path.resolve`。
+ *
+ * 两侧必须对同一 config 派生出**同一套**路径，而「同一份 config」在用户那里常常是
+ * 经过符号链接的路径（`~/.wand` → 别的卷、`/tmp` → `/private/tmp`、容器挂载点）。
+ * 一侧做 realpath、另一侧只做 resolve，就会算出两个 suffix：同一个 config 出现两个
+ * Render、两套 PTY 所有权 —— 这正是要靠寻址归一化防住的故障。
+ */
+function canonicalConfigPath(configPath) {
+    const resolved = path.resolve(configPath);
+    try {
+        return realpathSync(resolved);
+    }
+    catch {
+        return resolved;
+    }
+}
+/**
+ * Render 的按 config 隔离寻址。
+ *
+ * 与 legacy `terminald`（`wand-terminald-<uid>-<suffix>.sock` /
+ * `.terminald-<suffix>.token`）**刻意使用不同文件名**：升级期两套并存，
+ * 但永不互相领养。
+ */
+export function renderPaths(configPath) {
+    const resolved = canonicalConfigPath(configPath);
+    const suffix = createHash("sha256").update(resolved).digest("hex").slice(0, 12);
+    const dir = path.dirname(resolved);
+    const uid = (() => {
+        try {
+            return os.userInfo().uid;
+        }
+        catch {
+            return 0;
+        }
+    })();
+    return {
+        // macOS 的 Unix socket 路径上限约 100 字节，所以 socket 放 /tmp 保持短。
+        socketPath: path.join("/tmp", `wand-render-${uid}-${suffix}.sock`),
+        tokenPath: path.join(dir, `.render-${suffix}.token`),
+        pidPath: path.join(dir, `.render-${suffix}.pid`),
+        metaPath: path.join(dir, `.render-${suffix}.json`),
+    };
+}
+/** 编码一帧：`u32` 大端长度 + UTF-8 JSON。 */
+export function encodeRenderFrame(value) {
+    const body = Buffer.from(JSON.stringify(value), "utf8");
+    if (body.length > MAX_FRAME_BYTES) {
+        throw new Error(`Render frame of ${body.length} bytes exceeds the ${MAX_FRAME_BYTES} byte limit`);
+    }
+    const header = Buffer.allocUnsafe(4);
+    header.writeUInt32BE(body.length, 0);
+    return Buffer.concat([header, body]);
+}
+/**
+ * 从累积缓冲区解出所有完整帧。
+ *
+ * 返回剩余（不完整）字节。长度越界时抛错，调用方应关闭连接。
+ */
+export function decodeRenderFrames(buffer) {
+    const frames = [];
+    let offset = 0;
+    while (buffer.length - offset >= 4) {
+        const length = buffer.readUInt32BE(offset);
+        if (length > MAX_FRAME_BYTES) {
+            throw new Error(`Render frame length ${length} exceeds the ${MAX_FRAME_BYTES} byte limit`);
+        }
+        if (buffer.length - offset - 4 < length)
+            break;
+        const body = buffer.subarray(offset + 4, offset + 4 + length);
+        frames.push(JSON.parse(body.toString("utf8")));
+        offset += 4 + length;
+    }
+    return { frames, rest: offset === 0 ? buffer : buffer.subarray(offset) };
+}
+/** 是否为 protocol v1 事件帧（无 `id`，带 `event`）。 */
+export function isRenderEvent(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    return typeof record.event === "string" && record.id === undefined;
+}

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

@@ -0,0 +1,80 @@
+import { type StructuredRenderEvent, type StructuredRenderMethod } from "./render-structured-protocol.js";
+import type { StructuredExecHost, StructuredExecProcess, StructuredExitEvent, StructuredRunState, StructuredSpawnRequest, StructuredStreamEvent } from "./structured-exec-host.js";
+type RunEvent = Extract<StructuredRenderEvent, {
+    event: "stream" | "exit";
+}>;
+declare class RemoteRun implements StructuredExecProcess {
+    readonly runId: string;
+    readonly incarnationId: string;
+    readonly pid: number;
+    private readonly client;
+    private readonly streamListeners;
+    private readonly exitListeners;
+    private readonly beforeListener;
+    private pendingExit;
+    readonly seq: {
+        stdout: number;
+        stderr: number;
+    };
+    readonly queued: RunEvent[];
+    syncing: boolean;
+    overflow: boolean;
+    get exited(): boolean;
+    constructor(runId: string, incarnationId: string, pid: number, client: RenderStructuredClient);
+    interrupt(signal?: string): void;
+    onStream(listener: (event: StructuredStreamEvent) => void): {
+        dispose(): void;
+    };
+    onExit(listener: (event: StructuredExitEvent) => void): {
+        dispose(): void;
+    };
+    acceptStream(event: StructuredStreamEvent): void;
+    acceptExit(event: StructuredExitEvent): void;
+    fail(): void;
+}
+/** v2-only StructuredExecHost. It never accesses the PTY v1 or terminald sockets. */
+export declare class RenderStructuredClient implements StructuredExecHost {
+    private readonly configPath;
+    readonly persistent = true;
+    private socket;
+    private buffer;
+    private token;
+    private requestId;
+    private readonly pending;
+    private readonly inventory;
+    private readonly observed;
+    private readonly handles;
+    private readonly orphanEvents;
+    private readonly orphanOverflow;
+    private connecting;
+    private reconnectTimer;
+    private disposed;
+    private connected;
+    private fatalProtocol;
+    private stopHeartbeat;
+    private reconnectDelayMs;
+    constructor(configPath: string);
+    connect(): Promise<void>;
+    private open;
+    request(method: StructuredRenderMethod, params?: Record<string, unknown>): Promise<unknown>;
+    private consume;
+    private acceptEvent;
+    private queue;
+    private catchUp;
+    private replayStream;
+    private collect;
+    /** 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. */
+    private primeBuffered;
+    spawnStructured(request: StructuredSpawnRequest): Promise<StructuredExecProcess>;
+    attachRun(runId: string): Promise<StructuredRunState | null>;
+    adoptRun(runId: string): Promise<StructuredExecProcess | null>;
+    listRuns(): Promise<StructuredRunState[]>;
+    forgetRun(runId: string): void;
+    dropHandle(runId: string, handle: RemoteRun): void;
+    disconnect(): void;
+    private onDisconnect;
+    private scheduleReconnect;
+    private rejectPending;
+}
+export {};

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();
+    }
+}