@co0ontty/wand 4.72.1 → 4.72.2-beta.g52f54af

package/dist/render-host.d.ts

@@ -0,0 +1,59 @@
+import { type RenderDaemonClient } from "./render-daemon-client.js";
+import { TerminalDaemonClient } from "./terminal-daemon-client.js";
+import { type TerminalAttachResult, type TerminalHost, type TerminalSpawnRequest } from "./terminal-host.js";
+import type { RenderEngine } from "./types.js";
+export interface RenderHostOptions {
+    /** 配置里显式指定的引擎；环境变量 WAND_RENDER_ENGINE 优先。 */
+    engine?: RenderEngine;
+    /** 配置里显式指定的二进制路径。 */
+    binaryPath?: string;
+}
+export interface UpgradeAwareTerminalHost {
+    host: TerminalHost;
+    renderHost: TerminalHost | null;
+    legacyHost: TerminalDaemonClient | null;
+}
+export interface RoutedTerminalHosts {
+    legacy: TerminalHost | null;
+    render: TerminalHost;
+}
+/**
+ * 升级期无损路由：旧会话留在 legacy terminald，新会话一律进 Render。
+ *
+ * 所有权判断只能靠 legacy 自己的 inventory —— Server 无法从 DB 倒推
+ * 「这个 PTY 现在归谁」，因为升级前建的会话进程就在旧 daemon 里。
+ */
+export declare class CompositeTerminalHost implements TerminalHost {
+    readonly persistent = true;
+    private readonly legacy;
+    private readonly render;
+    constructor(hosts: RoutedTerminalHosts);
+    attach(sessionId: string, afterSeq?: number): TerminalAttachResult | null;
+    createOrAttach(request: TerminalSpawnRequest, afterSeq?: number): Promise<TerminalAttachResult>;
+    forget(sessionId: string): void;
+    /**
+     * 两侧都只是解绑：legacy daemon 可能还持有升级前的旧 PTY，Render 更是必须
+     * 跨 Server 重启继续活着。**这里绝不能 kill 任何东西。**
+     */
+    disconnect(): void;
+    /**
+     * legacy 查询失败（socket 抖动）时按「不属于它」处理：宁可让 Render 侧查一遍，
+     * 也不能在会话恢复路径上抛异常 —— 那会让服务器重启后旧会话全部恢复失败。
+     */
+    private attachFromLegacy;
+    private legacyOwns;
+}
+/** 环境变量优先于 config；非法值忽略并告警。 */
+export declare function resolveRenderEngine(envValue: string | undefined, configEngine: RenderEngine | undefined): RenderEngine;
+export declare function createUpgradeAwareTerminalHost(configPath: string, options?: RenderHostOptions): Promise<UpgradeAwareTerminalHost>;
+/**
+ * adopt 已存在的 Render，不存在则 spawn 后等待就绪。
+ *
+ * 协议（docs/render-protocol.md §6）：pid 活着但 socket 不可用 → 等待就绪，
+ * 不另起第二个 daemon；协议版本不符 → 明确抛错，**不做降级运行**。
+ */
+export declare function createRenderTerminalHost(configPath: string, options?: {
+    binaryPath?: string;
+}): Promise<RenderDaemonClient>;
+/** detached spawn（stdio 忽略、unref），并等 socket + token 就绪。 */
+export declare function spawnDetachedRender(configPath: string, binaryPath: string): Promise<RenderDaemonClient>;

package/dist/render-host.js

@@ -0,0 +1,270 @@
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import net from "node:net";
+import process from "node:process";
+import { getErrorMessage } from "./error-utils.js";
+import { isExecutableFile, readRenderBinaryVersion, resolveRenderBinaryPath } from "./render-binary.js";
+import { connectExistingRenderClient } from "./render-daemon-client.js";
+import { renderPaths } from "./render-protocol.js";
+import { connectExistingTerminalHost, createTerminalHost, TerminalDaemonClient } from "./terminal-daemon-client.js";
+import { InProcessTerminalHost, } from "./terminal-host.js";
+/** Render 的 socket/token 就绪等待窗口，与 legacy daemon 保持一致。 */
+const RENDER_READY_TIMEOUT_MS = 5_000;
+/**
+ * 升级期无损路由：旧会话留在 legacy terminald，新会话一律进 Render。
+ *
+ * 所有权判断只能靠 legacy 自己的 inventory —— Server 无法从 DB 倒推
+ * 「这个 PTY 现在归谁」，因为升级前建的会话进程就在旧 daemon 里。
+ */
+export class CompositeTerminalHost {
+    persistent = true;
+    legacy;
+    render;
+    constructor(hosts) {
+        this.legacy = hosts.legacy;
+        this.render = hosts.render;
+    }
+    attach(sessionId, afterSeq = 0) {
+        // legacy 命中就直接用；返回 null 说明这条会话不属于它（新会话在 Render）。
+        const fromLegacy = this.attachFromLegacy(sessionId, afterSeq);
+        if (fromLegacy)
+            return fromLegacy;
+        return this.render.attach(sessionId, afterSeq);
+    }
+    async createOrAttach(request, afterSeq = 0) {
+        if (this.legacyOwns(request.sessionId)) {
+            return this.legacy.createOrAttach(request, afterSeq);
+        }
+        return this.render.createOrAttach(request, afterSeq);
+    }
+    forget(sessionId) {
+        this.legacy?.forget(sessionId);
+        this.render.forget(sessionId);
+    }
+    /**
+     * 两侧都只是解绑：legacy daemon 可能还持有升级前的旧 PTY，Render 更是必须
+     * 跨 Server 重启继续活着。**这里绝不能 kill 任何东西。**
+     */
+    disconnect() {
+        this.legacy?.disconnect();
+        this.render.disconnect();
+    }
+    /**
+     * legacy 查询失败（socket 抖动）时按「不属于它」处理：宁可让 Render 侧查一遍，
+     * 也不能在会话恢复路径上抛异常 —— 那会让服务器重启后旧会话全部恢复失败。
+     */
+    attachFromLegacy(sessionId, afterSeq) {
+        if (!this.legacy)
+            return null;
+        try {
+            return this.legacy.attach(sessionId, afterSeq) ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    legacyOwns(sessionId) {
+        if (!this.legacy)
+            return false;
+        try {
+            return this.legacy.attach(sessionId) !== null;
+        }
+        catch {
+            // 查询失败按「不属于 legacy」处理：宁可让 Render 建新会话，也不要把请求丢进坏掉的 daemon。
+            return false;
+        }
+    }
+}
+/** 环境变量优先于 config；非法值忽略并告警。 */
+export function resolveRenderEngine(envValue, configEngine) {
+    const raw = (envValue ?? "").trim().toLowerCase();
+    if (raw) {
+        if (raw === "rust" || raw === "legacy" || raw === "auto")
+            return raw;
+        process.stderr.write(`[wand] WAND_RENDER_ENGINE=${envValue} is invalid (expected rust|legacy|auto); ignoring it.\n`);
+    }
+    return configEngine === "rust" || configEngine === "legacy" ? configEngine : "auto";
+}
+export async function createUpgradeAwareTerminalHost(configPath, options = {}) {
+    if (process.env.WAND_TEST_MODE === "1" || process.env.NODE_TEST_CONTEXT) {
+        // 与 legacy 缝隙一致：测试进程不拉起任何常驻 daemon。
+        return { host: new InProcessTerminalHost(), renderHost: null, legacyHost: null };
+    }
+    const engine = resolveRenderEngine(process.env.WAND_RENDER_ENGINE, options.engine);
+    // engine=legacy 等价于当前行为：adopt 已有 terminald，不存在才 spawn。
+    if (engine === "legacy") {
+        const legacy = await createTerminalHost(configPath);
+        return { host: legacy, renderHost: null, legacyHost: asTerminalDaemonClient(legacy) };
+    }
+    // 只 adopt，绝不 spawn/杀：它可能正持有升级前的会话 PTY。
+    const legacy = await connectExistingTerminalHost(configPath);
+    const configuredBinary = options.binaryPath?.trim();
+    const binaryPath = configuredBinary || resolveRenderBinaryPath(configPath);
+    if (!binaryPath) {
+        if (engine === "rust") {
+            throw new Error("render.engine=rust but no wand-render binary was found (checked WAND_RENDER_BIN, render/target/{release,debug}, " +
+                "<configDir>/bin, dist/native/<platform>-<arch>, PATH). " +
+                "Build it with `npm run build:render-native` (cargo build --release in render/), " +
+                "or set render.engine=auto/legacy to fall back.");
+        }
+        process.stderr.write("[wand] WARNING: render.engine=auto but no wand-render binary was found; PTYs stay on the legacy terminald. " +
+            "Build it with `npm run build:render-native`, stage a published build with `npm run build:render-bin`, or set WAND_RENDER_BIN.\n");
+        const fallback = legacy ?? await createTerminalHost(configPath);
+        return { host: fallback, renderHost: null, legacyHost: asTerminalDaemonClient(fallback) };
+    }
+    if (configuredBinary && !isExecutableFile(configuredBinary)) {
+        // 显式配置指向不可执行文件属于配置错误，静默回退 legacy 会让人以为 Rust 引擎在跑。
+        throw new Error(`render.binaryPath points at ${configuredBinary}, which is not an executable file.`);
+    }
+    try {
+        const render = await createRenderTerminalHost(configPath, { binaryPath });
+        const version = await readRenderBinaryVersion(binaryPath);
+        process.stderr.write(`[wand] Render engine active (${version ? `wand-render ${version}` : "version unknown"}, ${binaryPath})` +
+            `${legacy ? "; legacy terminald still serving pre-upgrade sessions" : ""}.\n`);
+        const host = legacy ? new CompositeTerminalHost({ legacy, render }) : render;
+        return { host, renderHost: render, legacyHost: legacy };
+    }
+    catch (error) {
+        if (engine === "rust")
+            throw error;
+        // auto 模式下把失败讲清楚再回退：这种情况用户最需要知道 Rust 引擎没生效。
+        process.stderr.write(`[wand] WARNING: render.engine=auto could not bring up Render (${getErrorMessage(error)}); falling back to the legacy terminald.\n`);
+        const fallback = legacy ?? await createTerminalHost(configPath);
+        return { host: fallback, renderHost: null, legacyHost: asTerminalDaemonClient(fallback) };
+    }
+}
+/**
+ * adopt 已存在的 Render，不存在则 spawn 后等待就绪。
+ *
+ * 协议（docs/render-protocol.md §6）：pid 活着但 socket 不可用 → 等待就绪，
+ * 不另起第二个 daemon；协议版本不符 → 明确抛错，**不做降级运行**。
+ */
+export async function createRenderTerminalHost(configPath, options = {}) {
+    const paths = renderPaths(configPath);
+    const endpointExists = process.platform !== "win32" && existsSync(paths.socketPath);
+    if (endpointExists) {
+        const adopted = await connectExistingRenderClient(configPath);
+        if (adopted)
+            return adopted;
+        if (await isSocketListening(paths.socketPath)) {
+            // 有人监听却拒绝 adopt（协议版本不符 / token 不符）：这是错误配置，必须报出来而不是绕开。
+            const starting = await waitForRender(configPath, RENDER_READY_TIMEOUT_MS);
+            if (starting)
+                return starting;
+            throw new Error(`A Render daemon is listening on ${paths.socketPath} but rejected adoption. Refusing to spawn a competing Render; ` +
+                "check the protocol version/token of the running binary, or stop it first.");
+        }
+        // 没人在监听，且没有活着的 pid = 上一次 renderd 崩溃留下的孤儿 socket 文件。
+        // 清掉它再 spawn，否则会永久卡在「等一个永远不会就绪的 socket」。
+        if (readLiveRenderPid(paths.pidPath) === null) {
+            try {
+                unlinkSync(paths.socketPath);
+            }
+            catch { /* 已被别处清掉即可 */ }
+        }
+    }
+    // 进程活着但 socket 还没就绪（启动竞态 / 正在 drain）：等它就绪，
+    // 绝不另起第二个 daemon（协议 §6 single instance）。
+    const livePid = readLiveRenderPid(paths.pidPath);
+    if (livePid !== null) {
+        const starting = await waitForRender(configPath, RENDER_READY_TIMEOUT_MS);
+        if (starting)
+            return starting;
+        throw new Error(`Render process ${livePid} is alive but its socket ${paths.socketPath} is unavailable; refusing to spawn a second daemon.`);
+    }
+    const binaryPath = options.binaryPath ?? resolveRenderBinaryPath(configPath);
+    if (!binaryPath)
+        throw new Error("wand-render binary is required to start Render");
+    return spawnDetachedRender(configPath, binaryPath);
+}
+/** detached spawn（stdio 忽略、unref），并等 socket + token 就绪。 */
+export async function spawnDetachedRender(configPath, binaryPath) {
+    const paths = renderPaths(configPath);
+    // `-c <configPath>` 是按 config 隔离的既定约定（docs/render-protocol.md §6）：
+    // socket / token / pid / meta 全部由它派生。
+    const child = spawn(binaryPath, ["-c", configPath], {
+        detached: true,
+        stdio: "ignore",
+        cwd: process.cwd(),
+        env: process.env,
+    });
+    child.on("error", (error) => {
+        process.stderr.write(`[wand] Failed to spawn wand-render: ${getErrorMessage(error)}\n`);
+    });
+    child.unref();
+    const client = await waitForRender(configPath, RENDER_READY_TIMEOUT_MS);
+    if (!client) {
+        // 自己生的进程自己收：就位超时（选错了二进制、二进制是 stub、或者它卡在启动）
+        // 时如果不回收，就会留下一个永久孤儿 daemon —— 它占着 socket 名字、下次启动会被
+        // 当成「活着但不接受领养」而直接阻塞启动。收尾是 best-effort，失败不影响报错。
+        reapUnreadyRender(child.pid);
+        throw new Error(`Spawned ${binaryPath} but its socket/token (${paths.socketPath}) did not become ready within ${RENDER_READY_TIMEOUT_MS}ms.`);
+    }
+    return client;
+}
+async function waitForRender(configPath, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const client = await connectExistingRenderClient(configPath);
+        if (client)
+            return client;
+        await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    return null;
+}
+/**
+ * 回收一个「已 spawn 但始终没就绪」的 Render 进程。
+ *
+ * 不回收会留下孤儿 daemon：它占着按 config 派生的 socket 名字，下次启动会被判成
+ * 「进程活着但 socket 不可达」，于是启动直接失败而不是重建 —— 一个失败的启动不该
+ * 破坏后续所有启动。先 SIGTERM 给它清理 socket/token 的机会，短暂等待后 SIGKILL。
+ */
+function reapUnreadyRender(pid) {
+    if (typeof pid !== "number" || pid <= 0)
+        return;
+    const signal = (name) => {
+        try {
+            process.kill(pid, name);
+        }
+        catch { /* 已经退出 */ }
+    };
+    signal("SIGTERM");
+    const timer = setTimeout(() => signal("SIGKILL"), 500);
+    timer.unref?.();
+}
+/** 对端是否真的在监听：区分「活着但拒绝 adopt」与「上一轮崩溃留下的孤儿 socket 文件」。 */ function isSocketListening(socketPath) {
+    return new Promise((resolve) => {
+        const socket = net.createConnection(socketPath);
+        const finish = (alive) => {
+            socket.removeAllListeners();
+            socket.destroy();
+            resolve(alive);
+        };
+        socket.once("connect", () => finish(true));
+        socket.once("error", () => finish(false));
+        const timer = setTimeout(() => finish(false), 300);
+        timer.unref?.();
+    });
+}
+function readLiveRenderPid(pidPath) {
+    let pid;
+    try {
+        pid = Number(readFileSync(pidPath, "utf8").trim());
+    }
+    catch {
+        return null;
+    }
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return null;
+    try {
+        process.kill(pid, 0);
+        return pid;
+    }
+    catch {
+        return null;
+    }
+}
+/** structuredExecHost 只认 daemon 客户端；测试注入的 in-process host 不算。 */
+function asTerminalDaemonClient(host) {
+    return host instanceof TerminalDaemonClient ? host : null;
+}

package/dist/render-protocol.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Render 协议 v1 的 TS 镜像。Rust 单一真源在
+ * `render/crates/wand-render-protocol/src/lib.rs`，契约文档在
+ * `render/docs/render-protocol.md`（本仓库 `docs/render-protocol.md` 只是指针）。
+ *
+ * 两侧常量与字段名必须逐一对齐；任一侧改动都要同时提升版本号并更新文档。
+ */
+export declare const RENDER_PROTOCOL_VERSION = 1;
+/** 单帧上限：`u32` 大端长度前缀 + UTF-8 JSON。 */
+export declare const MAX_FRAME_BYTES: number;
+/** 与 `PTY_OUTPUT_MAX_SIZE` 对齐（chunk 窗口 / output 有界）。 */
+export declare const RENDER_PTY_OUTPUT_MAX_CHARS = 200000;
+export type RenderErrorCode = "unauthorized" | "badRequest" | "notFound" | "conflict" | "unsupportedMethod" | "protocolMismatch" | "internal";
+export interface RenderRequest {
+    id: number;
+    token: string;
+    protocolVersion: number;
+    method: RenderMethod;
+    params?: Record<string, unknown>;
+}
+export type RenderMethod = "hello" | "ping" | "list" | "attach" | "createOrAttach" | "write" | "resize" | "kill" | "forget" | "stats" | "shutdown";
+export interface RenderResponse {
+    id: number;
+    ok: boolean;
+    result?: unknown;
+    error?: {
+        code: RenderErrorCode;
+        message: string;
+    };
+}
+export type RenderEvent = {
+    event: "data";
+    sessionId: string;
+    incarnationId: string;
+    data: string;
+    seq: number;
+} | {
+    event: "exit";
+    sessionId: string;
+    incarnationId: string;
+    exitCode: number | null;
+    signal: number | null;
+} | {
+    event: "reconcile";
+    sessionIds: string[];
+};
+export interface RenderHelloResult {
+    version: string;
+    protocolVersion: number;
+    pid: number;
+    startedAt: string;
+    sessions: number;
+}
+export interface RenderSessionState {
+    sessionId: string;
+    incarnationId: string;
+    pid: number;
+    status: "running" | "exited";
+    exitCode: number | null;
+    cols: number;
+    rows: number;
+    seq: number;
+    output: string;
+    chunks: {
+        data: string;
+        seq: number;
+    }[];
+    terminalSnapshot: {
+        version: number;
+        data: string;
+        cols: number;
+        rows: number;
+        pending: ({
+            type: "data";
+            data: string;
+        } | {
+            type: "resize";
+            cols: number;
+            rows: number;
+        })[];
+    } | null;
+    launchMarkerToken: string | null;
+}
+export interface RenderCreateOrAttachParams {
+    sessionId: string;
+    file: string;
+    args: string[];
+    cwd: string;
+    env: Record<string, string>;
+    name: string;
+    cols: number;
+    rows: number;
+    launchMarkerToken?: string;
+    afterSeq?: number;
+}
+export interface RenderStatsResult {
+    uptimeMs: number;
+    sessions: number;
+    liveBytes: number;
+    rssBytes: number;
+}
+export interface RenderPaths {
+    socketPath: string;
+    tokenPath: string;
+    pidPath: string;
+    metaPath: string;
+}
+/**
+ * Render 的按 config 隔离寻址。
+ *
+ * 与 legacy `terminald`（`wand-terminald-<uid>-<suffix>.sock` /
+ * `.terminald-<suffix>.token`）**刻意使用不同文件名**：升级期两套并存，
+ * 但永不互相领养。
+ */
+export declare function renderPaths(configPath: string): RenderPaths;
+/** 编码一帧：`u32` 大端长度 + UTF-8 JSON。 */
+export declare function encodeRenderFrame(value: unknown): Buffer;
+/**
+ * 从累积缓冲区解出所有完整帧。
+ *
+ * 返回剩余（不完整）字节。长度越界时抛错，调用方应关闭连接。
+ */
+export declare function decodeRenderFrames<T>(buffer: Buffer): {
+    frames: T[];
+    rest: Buffer;
+};
+/** 是否为 protocol v1 事件帧（无 `id`，带 `event`）。 */
+export declare function isRenderEvent(value: unknown): value is RenderEvent;

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/server-session-routes.js

@@ -17,6 +17,7 @@ import { sendRouteError } from "./server-request.js";
 import { registerStructuredResumeRoutes } from "./server-resume-routes.js";
 import { addHiddenSessionIds, removeHiddenSessionIds } from "./session-registry.js";
 import { enrichStructuredMessages, WAND_PROTOCOL_VERSION } from "./structured-client-protocol.js";
+import { asRecord, isStructuredImagePart } from "./structured-content.js";
 import { syncWorkspaceTaskToBoard } from "./wand-task-sync.js";
 import { buildDirectoryTree, normalizeSessionDirectory, } from "./session-directory-tree.js";
 import { projectCwdForSession, renameWorkspaceDirectory, resolveWorkspaceIdForNewSession, } from "./workspace-binding.js";
@@ -351,7 +352,7 @@ function isMergeActionAllowed(snapshot) {
 }
 export function registerSessionRoutes(app, processes, structured, storage, defaultMode, config, sessions, onSessionCreated) {
     const sessionResponseDTO = (snapshot) => {
-        const windowed = windowMessagesForTransport(enrichStructuredMessages(snapshot.messages ?? []), config.cardDefaults ?? {});
+        const windowed = windowMessagesForTransport(enrichStructuredMessages(snapshot.messages ?? [], snapshot.id), config.cardDefaults ?? {});
         return toSessionDetailDTO(snapshot, {
             messages: windowed.messages,
             messageOffset: windowed.messageOffset,
@@ -688,6 +689,41 @@ export function registerSessionRoutes(app, processes, structured, storage, defau
         }
         res.status(404).json({ error: "未找到该工具结果。" });
     });
+    // ── Inline tool image endpoint ──
+    // tool_result 里内联的 base64 图片在传输层被改写为这个 URL（避免把整张图的 base64
+    // 塞进每次快照 / WS 帧）。各端用同一套带鉴权的取图通道按需加载。
+    app.get("/api/sessions/:id/tool-images/:toolUseId/:index", (req, res) => {
+        const snapshot = sessions.get(req.params.id);
+        if (!snapshot) {
+            res.status(404).json({ error: "未找到该会话。" });
+            return;
+        }
+        const toolUseId = req.params.toolUseId;
+        const index = Number.parseInt(req.params.index, 10);
+        if (!Number.isFinite(index) || index < 0) {
+            res.status(400).json({ error: "无效的图片序号。" });
+            return;
+        }
+        for (const turn of snapshot.messages ?? []) {
+            for (const block of turn.content) {
+                if (block.type !== "tool_result" || block.tool_use_id !== toolUseId || !Array.isArray(block.content))
+                    continue;
+                const part = block.content.filter(isStructuredImagePart)[index];
+                const source = asRecord(part?.source);
+                const data = typeof source?.data === "string" ? source.data : undefined;
+                if (source?.type !== "base64" || !data) {
+                    res.status(404).json({ error: "未找到该图片。" });
+                    return;
+                }
+                res.setHeader("Content-Type", typeof source.media_type === "string" ? source.media_type : "image/png");
+                res.setHeader("Cache-Control", "private, max-age=3600");
+                res.setHeader("X-Content-Type-Options", "nosniff");
+                res.send(Buffer.from(data, "base64"));
+                return;
+            }
+        }
+        res.status(404).json({ error: "未找到该工具结果。" });
+    });
     app.post("/api/sessions/:id/worktree/merge/check", asyncRoute(async (req, res) => {
         try {
             const current = requireWorktreeSession(sessions.getLatest(req.params.id));
@@ -1016,7 +1052,7 @@ export function registerSessionRoutes(app, processes, structured, storage, defau
             const rawBudget = req.query.blockBudget;
             if (typeof rawBudget === "string" && /^\d+$/.test(rawBudget) && Number(rawBudget) > 0) {
                 const blockBudget = parseBoundedInteger(rawBudget, 1, 1, 2_000);
-                const windowed = blockWindowMessagesForTransport(enrichStructuredMessages(snapshot.messages ?? []), config.cardDefaults ?? {}, blockBudget);
+                const windowed = blockWindowMessagesForTransport(enrichStructuredMessages(snapshot.messages ?? [], snapshot.id), config.cardDefaults ?? {}, blockBudget);
                 res.json(toSessionDetailDTO(snapshot, {
                     output: transcriptOutput,
                     messages: windowed.messages,
@@ -1028,7 +1064,7 @@ export function registerSessionRoutes(app, processes, structured, storage, defau
                 return;
             }
             // 与 WS init 对齐：只回最近一窗 turn + offset/total，更早的走 /messages 翻页。
-            const windowed = windowMessagesForTransport(enrichStructuredMessages(snapshot.messages ?? []), config.cardDefaults ?? {});
+            const windowed = windowMessagesForTransport(enrichStructuredMessages(snapshot.messages ?? [], snapshot.id), config.cardDefaults ?? {});
             res.json(toSessionDetailDTO(snapshot, {
                 output: transcriptOutput,
                 messages: windowed.messages,
@@ -1048,7 +1084,7 @@ export function registerSessionRoutes(app, processes, structured, storage, defau
             res.status(404).json({ error: "未找到该会话，可能已被删除。" });
             return;
         }
-        const all = enrichStructuredMessages(snapshot.messages ?? []);
+        const all = enrichStructuredMessages(snapshot.messages ?? [], snapshot.id);
         const total = all.length;
         // 块级翻页（iOS）：?turn=<i>&blockOffset=<当前 leading 偏移>&blockLimit=<N>
         // 取该 turn 的 [start, blockOffset) 段（start = max(0, blockOffset - blockLimit)）。
@@ -1069,7 +1105,7 @@ export function registerSessionRoutes(app, processes, structured, storage, defau
             const blocks = enrichStructuredMessages([{
                     ...turn,
                     content: sliceTurnBlocksForTransport(turn, blockStart, blockEnd, config.cardDefaults ?? {}),
-                }])[0].content;
+                }], snapshot.id)[0].content;
             res.json({ wandProtocolVersion: WAND_PROTOCOL_VERSION, turnIndex, blocks, blockOffset: blockStart, blockTotal });
             return;
         }
@@ -1078,7 +1114,7 @@ export function registerSessionRoutes(app, processes, structured, storage, defau
         const limit = Math.min(Math.max(Number.isFinite(rawLimit) ? rawLimit : 40, 1), 200);
         const offset = Math.min(Math.max(Number.isFinite(rawOffset) ? rawOffset : 0, 0), total);
         const end = Math.min(offset + limit, total);
-        const slice = enrichStructuredMessages(truncateMessagesForTransport(all.slice(offset, end), config.cardDefaults ?? {}));
+        const slice = enrichStructuredMessages(truncateMessagesForTransport(all.slice(offset, end), config.cardDefaults ?? {}), snapshot.id);
         res.json({ wandProtocolVersion: WAND_PROTOCOL_VERSION, messages: slice, offset, total });
     });
     app.post("/api/sessions/:id/resume", asyncRoute(async (req, res) => {