dsh-tabbit 0.2.3 → 0.3.2

package/lib/permissions/index.js

@@ -0,0 +1,136 @@
+import { privateTargetReason } from '../runtime/net.js';
+/* 受本门管辖的两个工具。 */
+const GATED_TOOLS = new Set(['tabbit_browser', 'web_fetch']);
+/*
+ * 把"想发起一次询问"折算成当前模式下的正确结论：
+ *  - 会话审批策略覆盖为 `never`（= Full access 模式）→ 'bypass' 放行
+ *    （理由见文件头：ask 注定被自动拒，发出去只会造成误伤）；
+ *  - 审批服务根本没挂载（某些 headless 组合）→ 返回一个【解释了出路】的
+ *    拒绝：告诉用户去 settings 把 tabbit.<key> 设为 always。若不接手，
+ *    dsh 工具层的通用拒绝文案会把这条出路藏没；
+ *  - 其它情况 → 正常返回 ask，交给审批 UI 问用户。
+ */
+function resolveAsk(ctx, exec, askReason, settingsKey) {
+    // ctx.get('approval')：按名取服务的"软"方式——不在 inject 里声明硬依赖，
+    // 服务缺席时拿到 undefined 而不是崩溃。
+    const approval = ctx.get('approval');
+    if (approval !== undefined && exec.agent !== undefined) {
+        try {
+            // overrideOf(session)：读该会话的审批策略覆盖（dsh-user-approval API）。
+            // ⚠️ 这个 API 只能在"开着的 turn"内调用（本处理器正是在 turn 内跑的）。
+            if (approval.overrideOf(exec.agent.session) === 'never')
+                return 'bypass';
+        }
+        catch {
+            /* 会话形状不认识：当普通情况处理，照常询问 */
+        }
+    }
+    if (approval === undefined) {
+        return {
+            kind: 'deny',
+            reason: `This action needs user confirmation (settings tabbit.${settingsKey} = ask), but no approval channel is mounted in this composition. Set settings tabbit.${settingsKey} to "always" to allow it without prompts.`,
+        };
+    }
+    return { kind: 'ask', reason: askReason };
+}
+export const name = 'tabbit-permissions';
+export const inject = ['tools', 'tabbit'];
+export function apply(ctx) {
+    // "挂账本"：已发出的内网询问，callId → 该在调用成功后授信的 (会话, origin)。
+    // 只在 ask 路径上挂账——这保证授权永远不可能发给"决策当时是公网"的目标
+    // （防 DNS rebinding 继承授权，见文件头）。
+    const pendingIntranetGrants = new Map();
+    // ── 事前拦截：tools/pre-execute 瀑布 ──────────────────────────────────
+    ctx.on('tools/pre-execute', async function (exec, next) {
+        // 不归我们管的工具：立刻放行给下一个处理器。
+        if (!GATED_TOOLS.has(exec.name))
+            return next();
+        const settings = ctx.tabbit.currentSettings();
+        // 总闸 never：两个工具一律拒绝。
+        if (settings.pageAccess === 'never') {
+            return {
+                kind: 'deny',
+                reason: 'Tabbit Browser page access is disabled (settings tabbit.pageAccess = never).',
+            };
+        }
+        // ── 附加闸：web_fetch 的内网目标检查（在总闸之前查，因为它更具体）──
+        if (exec.name === 'web_fetch') {
+            const url = urlArgumentOf(exec.arguments);
+            if (url !== undefined) {
+                // 内网判定（net.ts）：返回原因字符串 = 是内网；undefined = 公网/未知。
+                const reason = await privateTargetReason(url);
+                if (reason !== undefined) {
+                    if (settings.intranetFetch === 'never') {
+                        return {
+                            kind: 'deny',
+                            reason: `web_fetch to a private/intranet target is disabled (${reason}; settings tabbit.intranetFetch = never).`,
+                        };
+                    }
+                    if (settings.intranetFetch === 'ask') {
+                        const agentId = exec.agent !== undefined ? String(exec.agent.id) : undefined;
+                        const origin = originOf(url);
+                        // 本会话对这个 origin 是否已授权过？
+                        const granted = agentId !== undefined && origin !== undefined && ctx.tabbit.hasIntranetGrant(agentId, origin);
+                        if (!granted) {
+                            const outcome = resolveAsk(ctx, exec, `web_fetch targets a PRIVATE/INTRANET address through your browser: ${reason}. First request to ${origin ?? 'this target'} in this session — allow it? (Set settings tabbit.intranetFetch to "always" to skip these prompts.)`, 'intranetFetch');
+                            if (outcome !== 'bypass') {
+                                // 真的发出了询问：按 callId 挂账，等 tools/result 里对账。
+                                if (outcome.kind === 'ask' && agentId !== undefined && origin !== undefined) {
+                                    pendingIntranetGrants.set(String(exec.callId), { agentId, origin });
+                                }
+                                return outcome;
+                            }
+                            // bypass（Full access）：内网闸放行，继续走下面的总闸检查。
+                        }
+                    }
+                    // intranetFetch === 'always'：不拦，继续。
+                }
+            }
+        }
+        // ── 总闸：pageAccess = ask 且本会话还没授权过 → 发起询问 ──────────
+        if (settings.pageAccess === 'ask' && exec.agent !== undefined && !ctx.tabbit.hasPageAccessGrant(String(exec.agent.id))) {
+            const outcome = resolveAsk(ctx, exec, 'First Tabbit Browser page access in this session: the agent will browse with your real browser profile, including logged-in sessions. Allow browser access for this session? (Set settings tabbit.pageAccess to "always" to skip this prompt.)', 'pageAccess');
+            if (outcome !== 'bypass')
+                return outcome;
+        }
+        // 所有门都过了：放行执行。
+        return next();
+    });
+    // ── 事后记账：tools/result ────────────────────────────────────────────
+    // 一次被门拦过的调用最终【成功】，说明用户点了允许（或策略放行）——把授权
+    // 记进会话记忆，让询问做到"页面访问每会话一次、内网每会话每 origin 一次"，
+    // 而不是每次调用都问。失败什么都不记（用户拒绝/执行出错，下次重试再问）。
+    ctx.on('tools/result', (exec, result) => {
+        // 先对内网挂账：找到本 callId 的账，成功才授信，成败都销账。
+        const pending = pendingIntranetGrants.get(String(exec.callId));
+        if (pending !== undefined) {
+            pendingIntranetGrants.delete(String(exec.callId));
+            if (!result.isError)
+                ctx.tabbit.grantIntranet(pending.agentId, pending.origin);
+        }
+        // 再记总闸授权：任何受管工具的成功调用都算"用户认可过页面访问"。
+        if (!GATED_TOOLS.has(exec.name))
+            return;
+        if (result.isError)
+            return;
+        if (exec.agent === undefined)
+            return;
+        ctx.tabbit.grantPageAccess(String(exec.agent.id));
+    });
+}
+/* 提取 URL 的 origin（协议+主机+端口）——内网授权的记忆粒度。 */
+function originOf(url) {
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+/* 从工具参数里安全地抠出 url 字段（参数是模型给的，形状不可信，逐层判断）。 */
+function urlArgumentOf(args) {
+    if (typeof args !== 'object' || args === null)
+        return undefined;
+    const url = args.url;
+    return typeof url === 'string' ? url : undefined;
+}

package/lib/runtime/cli.js

@@ -0,0 +1,229 @@
+/*
+ * ============================================================================
+ * 文件职责：Tabbit CLI launcher（tabbit-cli，旧名 tabbit-playwright）的底层子进程调用
+ * ============================================================================
+ *
+ * 这是插件与 Tabbit Browser 通信的两条物理通道之一（另一条是 endpoint.ts 的
+ * 直连 socket，仅覆盖无任务的清单/健康检查类读取）：每次请求都
+ * 启动一个 launcher 子进程，把参数放在命令行、代码放在 stdin，从 stdout/stderr
+ * 收结果。没有常驻连接、没有 socket——launcher 内部才去连浏览器。
+ *
+ * launcher 的输入输出契约（对真机 CLI 实测得出）：
+ *   - 成功：stdout 打印一个 JSON 值，退出码 0；
+ *   - 失败（应用层）：stderr 打印【一行 JSON】`{"ok":false,"error":{name,code,message}}`，
+ *     退出码 64/69/70；
+ *   - 失败（外壳层，实例选择问题）：stderr 打印【纯文本】，退出码 69；
+ *   - ⚠️ 每次调用 launcher 都会把 stdin 读到 EOF 才继续——所以哪怕命令不需要
+ *     stdin（如 `tasks`），也必须写完就关闭 stdin，否则子进程会永远挂着等输入；
+ *   - 任何命令都可能触发"浏览器自动拉起"：浏览器没在跑时，launcher 会先启动它
+ *     并重试约 20 秒——这就是为什么下层超时要留足余量（见 client.ts 的常量）。
+ *
+ * 本文件只做"进程调用 + 输出解码 + 超时/取消"，不理解任何业务语义；
+ * 业务层的重试、队列、信封解码都在 client.ts。
+ */
+import { spawn } from 'node:child_process';
+import { TabbitCliError, classifyAppError } from './errors.js';
+/* stdout/stderr 各自最多缓存 32 MiB，防御子进程疯狂输出把内存打爆。 */
+const STDIO_CAP_BYTES = 32 * 1024 * 1024;
+/*
+ * 带上限地累积输出块：超过上限后新数据直接丢弃（保留前面的部分即可，
+ * 排障时头部信息最有用）。total 用对象包一层是为了跨调用共享计数。
+ */
+function capConcat(chunks, next, total) {
+    if (total.bytes >= STDIO_CAP_BYTES)
+        return;
+    const room = STDIO_CAP_BYTES - total.bytes;
+    chunks.push(next.byteLength > room ? next.subarray(0, room) : next);
+    total.bytes += Math.min(next.byteLength, room);
+}
+/*
+ * 执行一次 launcher 调用。
+ *
+ * @param argv  命令行参数（不含程序名本身），如 ['nodejs', '--task', 'xxx']。
+ * @param stdin 要写进子进程 stdin 的内容（求值代码；无内容的命令传空串）。
+ * @returns     stdout 解析出的 JSON 值（stdout 为空则是 undefined）。
+ * @throws      TabbitCliError——所有失败路径都归一为这一种错误类型。
+ *
+ * 实现要点（Node 子进程管理的标准套路，逐段解释）：
+ *   - spawn() 启动子进程，stdio 三路都接管为管道（pipe）；
+ *   - settled 布尔量保证 resolve/reject 只发生一次（多个事件可能竞争触发）；
+ *   - 超时/取消都是先发 SIGTERM（温和终止），2 秒后没死再补 SIGKILL（强杀）；
+ *   - timer.unref() 让这个定时器不阻止 Node 进程退出；
+ *   - 'close' 事件（而非 'exit'）在【stdio 流全部关闭后】触发，此时输出已收齐，
+ *     是做最终判定的正确时机。
+ */
+export async function runCli(argv, stdin, options) {
+    // 复制当前环境变量，按需叠加实例选择变量——launcher 靠它路由到具体实例。
+    const env = { ...process.env };
+    if (options.instanceId)
+        env.TABBIT_PLAYWRIGHT_INSTANCE = options.instanceId;
+    return await new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = spawn(options.launcherPath, argv, { env, stdio: ['pipe', 'pipe', 'pipe'] });
+        }
+        catch (error) {
+            // spawn 同步抛错的少见路径（参数非法等）；常见的 ENOENT 走 'error' 事件。
+            reject(spawnFailure(options.launcherPath, error));
+            return;
+        }
+        const stdout = [];
+        const stderr = [];
+        const outTotal = { bytes: 0 };
+        const errTotal = { bytes: 0 };
+        let settled = false; // Promise 是否已敲定（防止重复 resolve/reject）
+        let timedOut = false; // 是否因超时被我们杀掉
+        let aborted = false; // 是否因调用方取消被我们杀掉
+        // 墙钟超时保护：到点先 SIGTERM，再补刀 SIGKILL。
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGTERM');
+            setTimeout(() => child.kill('SIGKILL'), 2000).unref();
+        }, options.timeoutMs);
+        timer.unref();
+        // 调用方取消（比如用户在 dsh UI 里停止了这条消息）：同样杀进程。
+        const onAbort = () => {
+            aborted = true;
+            child.kill('SIGTERM');
+            setTimeout(() => child.kill('SIGKILL'), 2000).unref();
+        };
+        if (options.signal?.aborted)
+            onAbort(); // 传进来时就已取消的情况
+        options.signal?.addEventListener('abort', onAbort, { once: true });
+        // 统一的"只敲定一次"出口：清定时器、摘监听器，再执行真正的 resolve/reject。
+        const settle = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            options.signal?.removeEventListener('abort', onAbort);
+            fn();
+        };
+        child.stdout.on('data', (chunk) => capConcat(stdout, chunk, outTotal));
+        child.stderr.on('data', (chunk) => capConcat(stderr, chunk, errTotal));
+        // 'error'：进程根本没起来（最典型：launcher 文件不存在）。
+        child.on('error', (error) => settle(() => reject(spawnFailure(options.launcherPath, error))));
+        // 'close'：进程退出且 stdio 全部排空——在这里做最终判定。
+        child.on('close', (exitCode) => {
+            settle(() => {
+                const stdoutText = Buffer.concat(stdout).toString('utf8').trim();
+                const stderrText = Buffer.concat(stderr).toString('utf8').trim();
+                // 优先级：取消 > 超时 > 正常退出码判定。
+                if (aborted) {
+                    reject(new TabbitCliError({
+                        kind: 'timeout',
+                        code: 'CANCELLED',
+                        message: 'Tabbit CLI call was cancelled',
+                        exitCode,
+                        stderrRaw: stderrText,
+                    }));
+                    return;
+                }
+                if (timedOut) {
+                    reject(new TabbitCliError({
+                        kind: 'timeout',
+                        code: 'CLIENT_TIMEOUT',
+                        message: `Tabbit CLI did not respond within ${options.timeoutMs}ms and was killed`,
+                        exitCode,
+                        stderrRaw: stderrText,
+                    }));
+                    return;
+                }
+                if (exitCode === 0) {
+                    // 成功路径：stdout 要么为空（无返回值命令），要么是一个 JSON 值。
+                    if (stdoutText.length === 0) {
+                        resolve(undefined);
+                        return;
+                    }
+                    try {
+                        resolve(JSON.parse(stdoutText));
+                    }
+                    catch {
+                        reject(new TabbitCliError({
+                            kind: 'protocol',
+                            code: 'BAD_STDOUT',
+                            message: `Tabbit CLI printed non-JSON output: ${stdoutText.slice(0, 300)}`,
+                            exitCode,
+                            stderrRaw: stderrText,
+                        }));
+                    }
+                    return;
+                }
+                // 非零退出码：去 stderr 里解码失败原因。
+                reject(decodeFailure(exitCode, stderrText));
+            });
+        });
+        child.stdin.on('error', () => {
+            /* EPIPE：CLI 没读完 stdin 就退出了（比如立刻报错）。写入失败无所谓，
+               最终结论由 close 处理器根据退出码/输出决定，这里只需吞掉异常防止崩溃。 */
+        });
+        // 写入代码并【必须关闭 stdin】——launcher 每次都读 stdin 到 EOF（见文件头契约）。
+        child.stdin.end(stdin, 'utf8');
+    });
+}
+/*
+ * 把"进程起不来"翻译成分类错误。
+ * ENOENT（文件不存在）/EACCES（无执行权限）= 用户没装或没启动过 Tabbit
+ * （launcher 是浏览器首次启动时注册的），给出可操作的提示。
+ */
+function spawnFailure(launcherPath, error) {
+    const code = error?.code;
+    if (code === 'ENOENT' || code === 'EACCES') {
+        return new TabbitCliError({
+            kind: 'launcher-missing',
+            code: 'LAUNCHER_MISSING',
+            message: `Tabbit CLI launcher not found or not executable at ${launcherPath}. Install and launch Tabbit Browser once to register it.`,
+        });
+    }
+    return new TabbitCliError({
+        kind: 'protocol',
+        code: 'SPAWN_FAILED',
+        message: `Failed to start Tabbit CLI: ${String(error?.message ?? error)}`,
+    });
+}
+/*
+ * 解码非零退出码的失败。两种来源（见文件头契约）：
+ *  1. 原生 CLI：stderr 里找以 '{' 开头的那一行，按 JSON 解析出
+ *     {error:{name,code,message}}，交给 classifyAppError 归类；
+ *  2. 外壳脚本：纯文本 stderr——退出码 69 时归类为"实例选择"问题
+ *     （外壳只在这种情况下自己报错），其余归为协议层未知失败。
+ */
+function decodeFailure(exitCode, stderrText) {
+    // stderr 可能混有日志行，只认以 '{' 开头的那一行 JSON。
+    const jsonLine = stderrText
+        .split('\n')
+        .map((line) => line.trim())
+        .find((line) => line.startsWith('{'));
+    if (jsonLine) {
+        try {
+            const parsed = JSON.parse(jsonLine);
+            const error = parsed.error ?? {};
+            return new TabbitCliError({
+                kind: classifyAppError(error),
+                code: error.code ?? 'REQUEST_FAILED',
+                message: error.message ?? 'Unknown error',
+                exitCode,
+                stderrRaw: stderrText,
+            });
+        }
+        catch {
+            /* JSON 解析失败：落回下面的纯文本处理 */
+        }
+    }
+    if (exitCode === 69) {
+        return new TabbitCliError({
+            kind: 'instance-selection',
+            code: 'INSTANCE_SELECTION',
+            message: stderrText || 'The Tabbit CLI launcher could not select a Tabbit Browser instance.',
+            exitCode,
+            stderrRaw: stderrText,
+        });
+    }
+    return new TabbitCliError({
+        kind: 'protocol',
+        code: 'CLI_FAILED',
+        message: stderrText || `Tabbit CLI exited with code ${exitCode}`,
+        exitCode,
+        stderrRaw: stderrText,
+    });
+}