dsh-tabbit 0.2.3 → 0.3.2

package/lib/runtime/client.js

@@ -0,0 +1,454 @@
+/*
+ * ============================================================================
+ * 文件职责：Runtime Service 的高层客户端 `TabbitClient`
+ * ============================================================================
+ *
+ * runtime/ 目录的"总装层"：把 cli.ts（子进程调用）、codec.ts（base64 信封）、
+ * errors.ts（错误分类）、instances.ts（实例注册表）组合成一个好用的类。
+ * 负责：实例选择、请求排队/并发控制、结果解码、超大结果的分块读回、
+ * 以及两类故障（任务隔离 quarantine、任务重置 task-reset）的自动恢复。
+ *
+ * ⚠️ 本文件（乃至整个 runtime/ 目录）完全不依赖任何 dsh 包——可以脱离 dsh
+ * 单独使用（`node` 里直接 import lib/runtime/client.js 做脚本调试）。
+ * 与 dsh 的对接全部发生在上层（core/tool-browser/web-fetch/mentions）。
+ *
+ * ─── 必备背景：Runtime Service 的「任务」（task）模型 ───────────────────
+ *
+ * Tabbit 的 Runtime Service 以「任务」为隔离单位：
+ *  - 每个任务有一个名字（task name）。这个名字【同时也是浏览器里那个
+ *    标签组（tab group）唯一可见的标题】——服务没有独立的"标题"字段，
+ *    改标题只能改任务命名本身；
+ *  - 一个任务 = 一个独立的浏览器上下文视角：自己开的标签页、自己的
+ *    globalThis（跨调用持久，可以存变量）、自己的 artifacts 目录；
+ *  - 任务【只能看到自己打开的或被显式 claim（认领）的标签页】，无法枚举
+ *    用户的其它标签页——这是浏览器侧的安全边界；
+ *  - 整机最多 8 个并发任务；单次求值最长 120 秒；
+ *  - 本客户端用到的 CLI 动词：`nodejs`（求值，创建时可带 --claim-tab）、
+ *    `finish`（结束任务，keep 语义两代有别，见 finishTask 注释）、
+ *    `receipt`（查回执）、`checkpoint`（检查点）、`resource`（分块读资源）、
+ *    `tasks`（列任务）、`claim`（对已存在的任务追加认领标签页，见
+ *    claimTabs()——真机 `--help` 确认过是独立顶层子命令，不是只存在于
+ *    persistent 帧协议里）。新代 CLI（1.11.16+）另有 tabs/resume/
+ *    screenshot/inspect/paste 和 persistent 持久模式（JSON 帧协议）——
+ *    本客户端尚未使用，见浏览器共享 skill（~/.agents/skills/tabbit）与
+ *    TabbitDance 源码。
+ *
+ * ─── 一次 evaluate 的完整旅程 ─────────────────────────────────────────
+ *
+ *  evaluate()
+ *    └─ withTaskLock()        同名任务串行化（服务端 worker 本来就一次只做一件事）
+ *        └─ 重试循环（最多 3 轮）
+ *            └─ evaluateOnce()
+ *                ├─ buildEvaluationSource()  给代码穿上 base64 信封（codec.ts）
+ *                ├─ invoke('nodejs', ...)    起 CLI 子进程提交（cli.ts；全局限流 4 并发）
+ *                ├─ waitForTerminalReceipt() 回执没到终态就轮询 receipt
+ *                └─ decodeReceiptResult()    内联结果直接解信封；溢出结果先
+ *                                            resource 分块读回再解信封
+ */
+import { randomUUID } from 'node:crypto';
+import { runCli } from './cli.js';
+import { buildEvaluationSource, decodeEnvelope } from './codec.js';
+import { CLI_ERROR_CODES, TabbitCliError, isUnknownTaskError } from './errors.js';
+import { defaultLauncherPath, listInstances, resolveInstanceId } from './instances.js';
+/* 求值超时的天花板：服务端硬上限 120 秒，请求再大也压到这里。 */
+const EVAL_TIMEOUT_CEILING_MS = 120_000;
+/* CLI 子进程的墙钟超时。CLI 自己会等结果最长 125 秒，浏览器冷启动还要 ~20 秒，
+ *  所以子进程超时必须比求值超时富余一大截，否则会在正常等待时误杀。 */
+const SUBPROCESS_TIMEOUT_MS = 145_000;
+/* 控制类命令（finish/receipt/resource/tasks）的超时——也要容纳浏览器自动拉起的 ~20 秒。 */
+const CONTROL_TIMEOUT_MS = 40_000;
+/* 溢出资源默认最多读回 4 MB。 */
+const DEFAULT_MAX_RESULT_BYTES = 4_000_000;
+/* 同一客户端同时在跑的 CLI 子进程上限（对整台机器的 Runtime Service 友好些）。 */
+const MAX_CONCURRENT_CALLS = 4;
+export class TabbitClient {
+    options;
+    /* 每个任务名一条 Promise 链，实现按任务串行（见 withTaskLock）。 */
+    taskQueues = new Map();
+    /* 当前在飞的 CLI 子进程数（配合 MAX_CONCURRENT_CALLS 限流）。 */
+    inFlight = 0;
+    /* 排队等空位的唤醒回调（先来先走）。 */
+    waiters = [];
+    constructor(options = {}) {
+        this.options = options;
+    }
+    listInstances() {
+        return listInstances();
+    }
+    launcher() {
+        return this.options.launcherPath ?? defaultLauncherPath();
+    }
+    /* 每次调用时实时解析实例（配置的 id 校验一遍；没配就自动选）。可能抛引导错误。 */
+    instance() {
+        const instances = listInstances();
+        // Windows：实例注册表目录在 Windows 上的位置未经真机确认（本地解析很可能
+        // 读到空列表），此时不要在客户端这层拦死——把选择（连同可能配置的 id）
+        // 原样委托给原生 tabbit-cli.exe，它自有实例选择与可解码的报错
+        // （exit 69 → cli.ts 归类为 instance-selection）。
+        if (process.platform === 'win32' && instances.length === 0)
+            return this.options.instanceId;
+        return resolveInstanceId(this.options.instanceId, instances);
+    }
+    /*
+     * 当前实际会解析到的实例 id（不抛错版本；解析不出就 undefined）。
+     * 用途：上层（core 的任务登记）在每次求值成功后记下"这个任务真正跑在了
+     * 哪个实例上"，会话结束清理时对症下药——因为"当前解析结果"是会漂移的
+     * （用户换个 Tabbit 窗口看 dsh，观看实例就变了）。
+     */
+    resolvedInstanceId() {
+        try {
+            return this.instance();
+        }
+        catch {
+            return undefined;
+        }
+    }
+    log(message) {
+        this.options.logger?.(message);
+    }
+    /*
+     * 并发限流的"占坑"：满员就把自己的唤醒函数排进 waiters 等着。
+     * 返回一个"释放函数"，用 released 标志保证幂等（重复调用只生效一次）；
+     * 释放时顺手唤醒队首的等待者。这是不依赖任何库的手写信号量（semaphore）。
+     */
+    async acquireSlot() {
+        if (this.inFlight >= MAX_CONCURRENT_CALLS) {
+            await new Promise((resolve) => this.waiters.push(resolve));
+        }
+        this.inFlight += 1;
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            this.inFlight -= 1;
+            this.waiters.shift()?.();
+        };
+    }
+    /*
+     * 按任务串行化：同一个任务名下的求值排成一条 Promise 链，前一个完成
+     * （无论成败——所以 then 的两个参数都是 fn）才轮到下一个。
+     * 为什么：服务端的任务 worker 本来就一次只处理一个请求，客户端排好队
+     * 能避免请求在服务端队列里堆积、超时语义也更清晰。
+     * 不同任务之间互不阻塞（只受全局 4 并发限流约束）。
+     */
+    async withTaskLock(task, fn) {
+        const previous = this.taskQueues.get(task) ?? Promise.resolve();
+        const run = previous.then(fn, fn);
+        // 存进 map 的是"吞掉结果和错误"的版本，防止链上残留 rejected Promise
+        // 触发 unhandled rejection 警告。
+        this.taskQueues.set(task, run.then(() => undefined, () => undefined));
+        return await run;
+    }
+    /* 所有 CLI 调用的统一入口：先占并发坑，再执行，finally 保证释放。 */
+    async invoke(argv, stdin, timeoutMs, signal) {
+        const release = await this.acquireSlot();
+        try {
+            return await runCli(argv, stdin, {
+                launcherPath: this.launcher(),
+                instanceId: this.instance(),
+                timeoutMs,
+                ...(signal ? { signal } : {}),
+            });
+        }
+        finally {
+            release();
+        }
+    }
+    /*
+     * 求值主入口：带自动恢复的重试循环（最多 3 次尝试，attempt 0/1/2）。
+     * 三种可自动恢复的失败，各自的处理：
+     *
+     *  - quarantined（任务被隔离）：一次带副作用的求值被中断后，服务端把任务
+     *    锁起来拒绝新请求，要求先 checkpoint 确认状态。我们自动补一次
+     *    checkpoint 然后重试，并在 notes 里向模型说明（它可能需要核实上次
+     *    操作到底成没成功）。
+     *
+     *  - task-reset（任务重置）：worker 丢了/浏览器重启了，任务里的页面和
+     *    globalThis 全没了。直接重试会在【全新的空任务】里执行——所以必须
+     *    把 taskWasReset 标记出来告诉模型"你之前存的状态没了"，否则它会
+     *    对着空任务困惑。
+     *
+     *  - browser-unavailable（浏览器暂不可达）：可能正在启动，等 3 秒重试
+     *    一次（只在第一次尝试时这么做，避免反复空等）。
+     *
+     * 其余错误不重试，原样抛出（由上层决定措辞）。
+     */
+    async evaluate(request) {
+        return await this.withTaskLock(request.task, async () => {
+            const notes = [];
+            let taskWasReset = false;
+            for (let attempt = 0;; attempt += 1) {
+                try {
+                    return await this.evaluateOnce(request, notes, taskWasReset);
+                }
+                catch (error) {
+                    if (!(error instanceof TabbitCliError) || attempt >= 2)
+                        throw error;
+                    if (error.kind === 'quarantined') {
+                        this.log(`task ${request.task} quarantined; running checkpoint`);
+                        await this.checkpoint(request.task).catch(() => undefined);
+                        notes.push('Task was quarantined after an interrupted run; a checkpoint was taken and the call was retried.');
+                        continue;
+                    }
+                    if (error.kind === 'task-reset') {
+                        taskWasReset = true;
+                        notes.push('The browser task was reset (worker lost or browser restarted). Pages and globalThis state from earlier calls are gone; the call was retried in a fresh task.');
+                        continue;
+                    }
+                    if (error.kind === 'browser-unavailable' && attempt === 0) {
+                        notes.push('Tabbit Browser runtime was unavailable; retried once after 3s.');
+                        await new Promise((resolve) => setTimeout(resolve, 3000));
+                        continue;
+                    }
+                    throw error;
+                }
+            }
+        });
+    }
+    /*
+     * 单次求值（不含重试）。流程：
+     *  1. 生成唯一 requestId（幂等追踪用）并拼 `nodejs` 命令的参数；
+     *  2. 用信封包装代码，经 invoke 提交（代码走 stdin）；
+     *  3. 校验 claim_tabs 语义：claim 只在任务【创建】时生效——若服务端说
+     *     reused（任务早已存在），claim 实际被无视了，与其静默让调用者误以为
+     *     认领成功，不如报错让它换个新任务名；
+     *  4. 回执可能还没到终态（queued/running），轮询等它；
+     *  5. 按回执状态返回成功（解码结果）或失败（提取错误信息）。
+     */
+    async evaluateOnce(request, notes, taskWasReset) {
+        const requestId = `dsh-${randomUUID()}`;
+        const argv = ['nodejs', '--task', request.task, '--request-id', requestId];
+        if (request.readOnly)
+            argv.push('--read-only');
+        if (request.foreground)
+            argv.push('--foreground');
+        // 超时钳位到 [1000, 120000] 区间（服务端上限 120 秒）。
+        const timeoutMs = Math.min(Math.max(request.timeoutMs ?? EVAL_TIMEOUT_CEILING_MS, 1000), EVAL_TIMEOUT_CEILING_MS);
+        argv.push('--timeout-ms', String(timeoutMs));
+        for (const tab of request.claimTabs ?? [])
+            argv.push('--claim-tab', String(tab));
+        const source = buildEvaluationSource(request.code);
+        const response = (await this.invoke(argv, source, SUBPROCESS_TIMEOUT_MS, request.signal));
+        const task = response.task;
+        if ((request.claimTabs?.length ?? 0) > 0 && task.reused) {
+            throw new TabbitCliError({
+                kind: 'tab-claim',
+                code: 'CLAIM_REQUIRES_NEW_TASK',
+                message: `Task "${request.task}" already exists, and tab claims are only honored when a task is created. Use a new task name to claim tabs.`,
+            });
+        }
+        // 兼容两代 `nodejs` 输出（真机对照实测）：
+        //  - 旧版（≤ Tabbit 1.10 / Cr150）：{ task, receipt }——receipt 里带
+        //    requestId/status/result（result 有 type 判别）；
+        //  - 新版（Tabbit 1.11+/Cr151）：顶层就是一张【扁平终态回执】
+        //    { status, result, task, transition }——result 无 type 字段（inline
+        //    有 value、溢出有 resourceId+byteLength），失败时错误在 result.error。
+        // 注意 `receipt` 子命令两代都返回旧版包裹形（回执存储没变），所以只需
+        // 在这里归一化，轮询路径照旧。
+        let receipt = response.receipt !== undefined ? response.receipt : normalizeFlatReceipt(response, requestId);
+        receipt = await this.waitForTerminalReceipt(request.task, receipt);
+        if (receipt.status === 'succeeded') {
+            const result = await this.decodeReceiptResult(request.task, receipt, request.maxResultBytes ?? DEFAULT_MAX_RESULT_BYTES, notes);
+            return { status: 'succeeded', result, task, taskWasReset, notes };
+        }
+        const errorMessage = extractReceiptError(receipt);
+        return { status: 'failed', errorMessage, task, taskWasReset, notes };
+    }
+    /*
+     * 回执轮询：正常情况下 `nodejs` 命令会阻塞到求值结束才返回终态回执，但
+     * 边缘情况（CLI 等待窗口耗尽等）下可能拿到 queued/running。此时每 2 秒
+     * 用 `receipt` 命令查一次，最多 20 次（40 秒）；到头了就把非终态回执
+     * 原样返回，让上层把它当失败处理。
+     */
+    async waitForTerminalReceipt(task, receipt) {
+        let current = receipt;
+        for (let poll = 0; poll < 20 && (current.status === 'queued' || current.status === 'running'); poll += 1) {
+            await new Promise((resolve) => setTimeout(resolve, 2000));
+            current = (await this.invoke(['receipt', '--task', task, '--request', current.requestId], '', CONTROL_TIMEOUT_MS));
+        }
+        return current;
+    }
+    /*
+     * 从成功回执里取出并解码返回值：
+     *  - 无 result 字段：视为 null；
+     *  - inline：值就在回执里，直接解信封；
+     *  - resource（结果 >8KiB 溢出成了资源文件）：分块读回文本——
+     *      · 读完整了：先 JSON.parse（资源里存的是"包含信封字符串的 JSON"，
+     *        即形如 `"b64:xxxx"` 的带引号文本）再解信封；parse 不动就把文本
+     *        当 rawText 交上去；
+     *      · 被字节上限截停：文本只是前缀（形如 `"b64:AAAA...` 掐头去尾都
+     *        不完整），剥掉开头引号后按"不完整"模式解信封（codec 的宽松
+     *        解码能救回前缀部分），并在 notes 里提醒模型返回值太大了。
+     */
+    async decodeReceiptResult(task, receipt, maxResultBytes, notes) {
+        const result = receipt.result;
+        if (!result)
+            return { value: null, truncated: false };
+        if (result.type === 'inline')
+            return decodeEnvelope(result.value);
+        const { text, complete } = await this.readResourceText(task, result.resourceId, maxResultBytes);
+        if (!complete) {
+            notes.push(`Result was ${result.byteLength} bytes; only the first ${maxResultBytes} bytes were read back. Return smaller values (or write files via artifactPath) for complete results.`);
+        }
+        if (complete) {
+            try {
+                return decodeEnvelope(JSON.parse(text));
+            }
+            catch {
+                return { rawText: text, truncated: true };
+            }
+        }
+        // 不完整的资源：JSON 文本是形如 `"b64:AAAA...` 的前缀，剥掉引号解信封。
+        const stripped = text.startsWith('"') ? text.slice(1) : text;
+        return decodeEnvelope(stripped, false);
+    }
+    /*
+     * 用 `resource` 命令分块读回一个溢出资源。
+     * 协议：每次带 --offset 请求，返回 {data: 本块文本, nextOffset, eof}；
+     * eof=true 表示读完。达到 maxBytes 上限就带着 complete:false 提前收手。
+     * 中间那个防御分支：万一服务端返回畸形块（没有 nextOffset 或空 data），
+     * 宁可当"没读完"返回也绝不无限自旋。
+     */
+    async readResourceText(task, resourceId, maxBytes) {
+        let offset = 0;
+        let text = '';
+        for (;;) {
+            const chunk = (await this.invoke(['resource', '--task', task, '--resource', resourceId, '--offset', String(offset)], '', CONTROL_TIMEOUT_MS));
+            text += chunk.data;
+            if (chunk.eof)
+                return { text, complete: true };
+            if (typeof chunk.nextOffset !== 'number' || chunk.data.length === 0) {
+                // 防御：畸形块回复，绝不自旋。
+                return { text, complete: false };
+            }
+            offset = chunk.nextOffset;
+            if (offset >= maxBytes)
+                return { text, complete: false };
+        }
+    }
+    /*
+     * 结束一个任务（`finish` 命令）。
+     *
+     * ── keep 语义的两代差异与本实现的策略（2026-08-28 按新语义适配）──────
+     * 新代 Runtime（本机稳定/Dev 的 1.11.16+ CLI 源码实证）：
+     *   `finish` 缺省【保留】标签页与可恢复组（keep:true），`--discard` 才
+     *   关闭；`--keep --discard` 同传报错。
+     * 旧代（≤1.11.13）：缺省关闭，`--keep` 保留；解析器风格是"扫描已知
+     *   flag、忽略未知"（新旧同款代码风格），未知的 `--discard` 会被忽略。
+     * 因此【恒显式】即可两代通吃、无需探测版本：
+     *   keep=true  → `--keep`   （新代：保留✓；旧代：保留✓）
+     *   keep=false → `--discard`（新代：关闭✓；旧代：忽略未知 flag → 裸
+     *                             finish → 旧默认关闭✓）
+     *
+     * 三类错误吞掉不抛（视为"清理已达成"），但每次吞掉都【记一行日志】——
+     * 吞错本身是对的，可完全无痕就没法排障（真机复现过：finish 打到漂移后的
+     * 错误实例，命中 Unknown task name 被吞，调用方误以为成功，真正持有任务
+     * 的实例上标签组一直挂着）：
+     *  - Unknown task name：任务在【本实例】上不存在——可能确实早没了，也可能
+     *    它活在另一个实例上（实例漂移场景），所以日志里特意带上实例 id 供对账；
+     *  - browser-unavailable：浏览器都没在跑，任务自然也没了（不能为了 finish
+     *    把浏览器拉起来）；
+     *  - task-reset：服务重启过，旧任务已作废。
+     * 其余错误照常抛出（调用方大多也会 catch 住做尽力而为清理）。
+     */
+    async finishTask(task, options = {}) {
+        const argv = ['finish', '--task', task, options.keep ? '--keep' : '--discard'];
+        try {
+            await this.invoke(argv, '', CONTROL_TIMEOUT_MS);
+        }
+        catch (error) {
+            const instance = this.resolvedInstanceId() ?? 'unresolved';
+            if (isUnknownTaskError(error)) {
+                this.log(`finish --task "${task}" ignored: unknown task on instance ${instance} (already gone there; if its tab group is still visible, the task may live on a DIFFERENT instance)`);
+                return;
+            }
+            if (error instanceof TabbitCliError && (error.kind === 'browser-unavailable' || error.kind === 'task-reset')) {
+                this.log(`finish --task "${task}" skipped on instance ${instance}: ${error.kind} (${error.message})`);
+                return;
+            }
+            throw error;
+        }
+    }
+    /* 打检查点（`checkpoint` 命令）——解除任务隔离状态的钥匙（见 evaluate 的恢复逻辑）。 */
+    async checkpoint(task) {
+        return await this.invoke(['checkpoint', '--task', task], '', CONTROL_TIMEOUT_MS);
+    }
+    /*
+     * 把一个或多个可用（available）标签页追加认领进一个【已经存在】的任务
+     * （`claim` 命令）。与 evaluate() 的 claimTabs 只在任务创建那一刻生效不同，
+     * 这是独立的一次性 CLI 子命令——真机 `tabbit-cli --help` 的 usage 行确认过
+     * 它是顶层动词（`claim --task <name> --tab <id>...`），不是只存在于 persistent
+     * 帧协议里；真机验证过对一个此前已创建好的任务追加 claim 可行。
+     * 批量原子：文档明确"duplicate, stale, busy, unsupported, or cross-window
+     * inputs do not partially claim"——要么全部认领成功，要么整批失败并抛错，
+     * 调用方不需要处理"部分成功"的中间态。
+     */
+    async claimTabs(task, tabIds) {
+        const argv = ['claim', '--task', task];
+        for (const tab of tabIds)
+            argv.push('--tab', String(tab));
+        const response = (await this.invoke(argv, '', CONTROL_TIMEOUT_MS));
+        return {
+            ...(typeof response.groupId === 'string' ? { groupId: response.groupId } : {}),
+            ...(typeof response.ownedPageCount === 'number' ? { ownedPageCount: response.ownedPageCount } : {}),
+        };
+    }
+    /* 列出当前实例上的所有任务（`tasks` 命令）。返回值形状异常时兜底为空数组。 */
+    async listTasks() {
+        const value = await this.invoke(['tasks'], '', CONTROL_TIMEOUT_MS);
+        return Array.isArray(value) ? value : [];
+    }
+}
+/*
+ * 把新版（Cr151 世代）`nodejs` 命令的扁平终态输出归一成旧版 Receipt 形状
+ * （形状差异与实测样本见 evaluateOnce 里的注释）。要点：
+ *  - result 无 type 判别：有 resourceId 视为溢出资源，否则带 value 键视为
+ *    inline（值本身可以是 undefined/null，所以用 'value' in result 判断）；
+ *  - 失败时错误在 result.error（字符串）；requestId 可能在顶层或 result 里，
+ *    都没有就用我们自己生成的那个（轮询/日志用，语义不受影响）。
+ */
+function normalizeFlatReceipt(raw, fallbackRequestId) {
+    const result = raw.result;
+    const normalizedResult = result === undefined
+        ? undefined
+        : result.resourceId !== undefined
+            ? { type: 'resource', resourceId: String(result.resourceId), byteLength: Number(result.byteLength ?? 0) }
+            : 'value' in result
+                ? { type: 'inline', value: result.value }
+                : undefined;
+    const requestId = typeof raw.requestId === 'string' ? raw.requestId : typeof result?.requestId === 'string' ? result.requestId : fallbackRequestId;
+    const error = raw.error ?? result?.error;
+    return {
+        requestId,
+        status: raw.status,
+        ...(normalizedResult !== undefined ? { result: normalizedResult } : {}),
+        ...(error !== undefined ? { error } : {}),
+    };
+}
+/*
+ * 从失败回执里尽力抠出一条人话错误信息：
+ * error 字段可能是字符串、带 message 的对象、或任意奇形怪状——逐层降级；
+ * interrupted 状态（求值没跑完服务就重启了）给专门文案。
+ */
+function extractReceiptError(receipt) {
+    const error = receipt.error;
+    if (typeof error === 'string')
+        return error;
+    if (error && typeof error === 'object') {
+        const message = error.message;
+        if (typeof message === 'string')
+            return message;
+        try {
+            return JSON.stringify(error);
+        }
+        catch {
+            /* 序列化不了就落到最后的兜底文案 */
+        }
+    }
+    if (receipt.status === 'interrupted')
+        return 'Evaluation was interrupted (runtime restarted before it settled).';
+    return `Evaluation ${receipt.status} without an error message.`;
+}
+// 把底层的错误类型和实例类型一并转出去，上层只需要 import 本文件。
+export { CLI_ERROR_CODES, TabbitCliError };

package/lib/runtime/codec.js

@@ -0,0 +1,126 @@
+/*
+ * ============================================================================
+ * 文件职责：求值结果的 base64「信封」编解码（codec = coder/decoder）
+ * ============================================================================
+ *
+ * 为什么需要这个文件？——为了绕开 Tabbit CLI 的一个真实 bug：
+ *
+ * 1. 我们提交给浏览器执行的代码，其返回值由 Runtime Service 写进一张「回执」
+ *    （receipt）。回执小于 8 KiB 时直接内联返回；【大于 8 KiB 时会被"溢出"
+ *    （spill）到一个资源文件】，之后要用 `resource` 子命令按固定
+ *    8192 字节一块地分块读回。
+ *
+ * 2. 问题在于：CLI 读回资源时是【逐块按 UTF-8 解码】的。而 UTF-8 里一个中文
+ *    字符占 3 字节——如果这 3 个字节恰好横跨两个 8192 字节块的边界，两边各自
+ *    解码时都会把这半个字符变成乱码（U+FFFD）。也就是说：只要返回值里有中文
+ *    （或任何非 ASCII 字符）且体积超过 8 KiB，读回的内容【必然损坏】。
+ *    这是实测踩到的坑，不是理论推演。
+ *
+ * 解决方案（本文件实现的"信封"协议）：
+ *    - 发送端（浏览器里）：把模型代码的返回值先 JSON.stringify，再整体转成
+ *      base64。base64 只含 ASCII 字符（每字符 1 字节），怎么切块都不会损坏。
+ *      最后拼上前缀 "b64:"（或截断时 "b64trunc:"）作为标记。
+ *    - 接收端（本文件 decodeEnvelope）：识别前缀、base64 解码、JSON.parse，
+ *      还原出原始值。
+ *
+ * 这层信封对模型完全透明：模型写的代码正常 return，工具正常拿到值。
+ */
+/* 完整结果的信封前缀。 */
+export const ENVELOPE_PREFIX = 'b64:';
+/* 浏览器侧就已截断（超过下面的字符上限）的信封前缀。 */
+export const ENVELOPE_TRUNCATED_PREFIX = 'b64trunc:';
+/*
+ * 返回值 JSON 文本的字符数上限（150 万字符），超过就在浏览器侧先截断。
+ * 目的：防止模型不小心 return 一个巨型对象，把分块读回的时间拖到不可接受。
+ */
+export const MAX_RESULT_JSON_CHARS = 1_500_000;
+/*
+ * 把模型写的「async 函数体」包装成实际提交给 Runtime Service 的完整源码。
+ *
+ * 背景知识：Runtime Service 的持久求值器（persistent evaluator）收到 stdin
+ * 里的代码后，会自己再套一层 `(async () => { <stdin内容> })()` 执行。所以
+ * 我们这里生成的字符串本身就是一个"函数体"——最外层的 `return` 就是最终
+ * 返回给服务端的值。
+ *
+ * 包装结构（生成的代码在【浏览器进程里】执行，不在本 Node 进程）：
+ *   1. __dshEncode：UTF-8 → base64 的编码函数。优先用 Node 的 Buffer
+ *      （Tabbit 的求值环境里有）；万一没有则退回浏览器经典的
+ *      btoa+encodeURIComponent 组合技。
+ *   2. 把模型代码再包一层嵌套的 async IIFE（立即执行函数）并 await——
+ *      这样模型代码里自己写的 `return` 只会结束这层 IIFE、把值交给
+ *      __dshValue，不会干扰我们外层的信封逻辑。
+ *   3. JSON.stringify 该值；undefined 归一成 null；序列化抛异常（比如值里
+ *      有循环引用）时改为返回 {__dshSerializationError: 错误信息}。
+ *   4. 超长先截断（打 b64trunc: 前缀），否则打 b64: 前缀，整体 base64 后
+ *      return——这就是走网线（其实是走 CLI stdout/资源文件）的最终形态。
+ *
+ * ⚠️ 注意：下面模板字符串里的内容是要原样发给浏览器执行的代码，
+ * 请勿在字符串内部添加任何注释或改动（会改变实际下发的代码）。
+ */
+export function buildEvaluationSource(body) {
+    return `const __dshEncode = (text) => {
+  if (typeof Buffer !== 'undefined') return Buffer.from(text, 'utf8').toString('base64');
+  return btoa(unescape(encodeURIComponent(text)));
+};
+const __dshValue = await (async () => {
+${body}
+})();
+let __dshJson;
+try {
+  __dshJson = JSON.stringify(__dshValue === undefined ? null : __dshValue);
+  if (typeof __dshJson !== 'string') __dshJson = 'null';
+} catch (error) {
+  __dshJson = JSON.stringify({ __dshSerializationError: String((error && error.message) || error) });
+}
+if (__dshJson.length > ${MAX_RESULT_JSON_CHARS}) {
+  return '${ENVELOPE_TRUNCATED_PREFIX}' + __dshEncode(__dshJson.slice(0, ${MAX_RESULT_JSON_CHARS}));
+}
+return '${ENVELOPE_PREFIX}' + __dshEncode(__dshJson);`;
+}
+/*
+ * 宽松的 base64 解码：
+ *  1. 先剔除所有非 base64 字符（分块读回时可能混入引号、换行等杂质）；
+ *  2. 把长度裁到 4 的整数倍（base64 每 4 字符编码 3 字节，尾部不完整的
+ *     "量子"直接丢弃）——这样即使数据被截断在任意位置也能解出前缀部分。
+ */
+function decodeBase64Lenient(body) {
+    const clean = body.replace(/[^A-Za-z0-9+/=]/gu, '');
+    const usable = clean.slice(0, clean.length - (clean.length % 4));
+    return Buffer.from(usable, 'base64').toString('utf8');
+}
+/*
+ * 解码一个从求值返回的"线上值"（wire value）。
+ *
+ * @param wireValue CLI 返回的原始值。可能是：带信封前缀的字符串（正常路径）、
+ *                  不带前缀的任意值（比如老版本/别的任务写的，直接原样透传）。
+ * @param complete  资源分块读回是否读到了 EOF。为 false 表示读取被字节上限
+ *                  截停了——此时 base64 可能断在任意位置，解出来的 JSON 文本
+ *                  只是个前缀，不再尝试 JSON.parse，直接作为 rawText 返回。
+ */
+export function decodeEnvelope(wireValue, complete = true) {
+    // 不是字符串就不可能带信封，原样返回（数字、布尔、对象等）。
+    if (typeof wireValue !== 'string') {
+        return { value: wireValue, truncated: false };
+    }
+    if (wireValue.startsWith(ENVELOPE_PREFIX)) {
+        const text = decodeBase64Lenient(wireValue.slice(ENVELOPE_PREFIX.length));
+        if (complete) {
+            try {
+                return { value: JSON.parse(text), truncated: false };
+            }
+            catch {
+                // 理论上完整信封必可解析；解析不了说明数据异常，把文本原样交上去。
+                return { rawText: text, truncated: true };
+            }
+        }
+        // 读回不完整：JSON 文本只是前缀，parse 注定失败，直接给 rawText。
+        return { rawText: text, truncated: true };
+    }
+    if (wireValue.startsWith(ENVELOPE_TRUNCATED_PREFIX)) {
+        // 浏览器侧就截断过了，永远只能拿到文本片段。
+        const text = decodeBase64Lenient(wireValue.slice(ENVELOPE_TRUNCATED_PREFIX.length));
+        return { rawText: text, truncated: true };
+    }
+    // 无信封前缀的普通字符串：原样返回。
+    return { value: wireValue, truncated: false };
+}