berry-agent 0.1.0-alpha.1

package/dist/api/tsconfig.paths.json

@@ -0,0 +1,12 @@
+{
+  "//": "插件侧 tsconfig paths 模板（API 治理公开面）——拷进插件 tsconfig 的 compilerOptions.paths；相对段按插件 tsconfig 所在目录调整（示例假插件与宿主包同级安装）；typebox 三键经插件自身 dependencies 解析（类型面同 npm 包，运行时仍走加载器注入防双实例），三行映射是等价兜底非必需；berry-agent/sqlite 键行随 SqliteFace 落码批补（届时见 COMPATIBILITY.md 版本注记）。",
+  "compilerOptions": {
+    "paths": {
+      "berry-agent": ["../node_modules/berry-agent/dist/api/berry-agent.d.ts"],
+      "berry-agent/llm": ["../node_modules/berry-agent/dist/api/berry-agent-llm.d.ts"],
+      "typebox": ["../node_modules/berry-agent/dist/api/typebox.d.ts"],
+      "typebox/value": ["../node_modules/berry-agent/dist/api/typebox-value.d.ts"],
+      "typebox/compile": ["../node_modules/berry-agent/dist/api/typebox-compile.d.ts"]
+    }
+  }
+}

package/dist/api/typebox-compile.d.ts

@@ -0,0 +1,2 @@
+/** 虚拟模块 `typebox/compile` 的类型面（编译产物/Code 生成） */
+export * from 'typebox/compile';

package/dist/api/typebox-value.d.ts

@@ -0,0 +1,2 @@
+/** 虚拟模块 `typebox/value` 的类型面（校验/默认值/错误格式化） */
+export * from 'typebox/value';

package/dist/api/typebox.d.ts

@@ -0,0 +1,2 @@
+/** 虚拟模块 `typebox` 的类型面（运行时由加载器注入宿主实例——双实例防线） */
+export * from 'typebox';

package/dist/browser/cdp.js

@@ -0,0 +1,256 @@
+/**
+ * CDP 连接件（03 §10.3 形态条款——手写 CDP 桥，零新增依赖）。
+ *
+ * 线形：browser 级单连接上的 JSON 文本帧（Chrome DevTools Protocol）——
+ * 命令帧 {id, method, params, sessionId?} / 应答帧 {id, result|error} /
+ * 事件帧 {method, params, sessionId?}。flat 模式下 per-session 命令带
+ * sessionId 字段、事件按 sessionId 分流路由（Target.attachToTarget
+ * {flatten:true} 产物）。
+ *
+ * 失败语义分账：连接级失败（ws 关闭/建立失败）= BROWSER_CONNECT_FAILED
+ * （在途全结清 + onDown 通知）；单命令超时 = 普通 Error（连接仍活，调用方
+ * 自决重试）——两分防「慢命令」误杀活连接。
+ */
+import { BaseError } from '../contracts/index.js';
+import { BROWSER_CDP_COMMAND_TIMEOUT_MS } from './types.js';
+/** CDP 命令应答错误（wire error 对象） */
+export class CdpCommandError extends Error {
+    cdpCode;
+    cdpMessage;
+    constructor(cdpCode, cdpMessage) {
+        super(`CDP 命令被拒（code ${cdpCode}）：${cdpMessage}`);
+        this.cdpCode = cdpCode;
+        this.cdpMessage = cdpMessage;
+    }
+}
+/**
+ * 组 CDP 连接（ws 面之上——请求关联表 + 事件分流路由）。
+ * ws.opened 由调用方（引擎层）先行 await——本件只消费已建立的连接。
+ */
+export function createCdpConnection(ws, deps = {}) {
+    const logger = deps.logger;
+    const commandTimeout = deps.commandTimeoutMs ?? BROWSER_CDP_COMMAND_TIMEOUT_MS;
+    const pending = new Map();
+    /** 事件等待账（`${method}\0${sessionId ?? ''}` → 等待者队列） */
+    const eventWaiters = new Map();
+    const eventListeners = new Set();
+    /** 已注册的 onDown 监听者（settleDown 快照送达 + 迟到订阅即回调共用账） */
+    const downListeners = new Set();
+    let downGate = false; // 幂等闸（true = 已收口）
+    let deadReason = '';
+    let nextId = 1;
+    const isDead = () => downGate;
+    /** 连接级收口（幂等闸）：在途命令 + 事件等待全结清 + onDown 一次性送达 */
+    const settleDown = (reason) => {
+        if (downGate)
+            return;
+        downGate = true;
+        deadReason = reason;
+        for (const entry of pending.values()) {
+            clearTimeout(entry.timer);
+            entry.reject(new BaseError('BROWSER_CONNECT_FAILED', `CDP 连接已断（${reason}）——在途命令 ${entry.method} 结清`));
+        }
+        pending.clear();
+        for (const queue of eventWaiters.values()) {
+            for (const waiter of queue) {
+                clearTimeout(waiter.timer);
+                // 事件流随连接死而终结（普通 Error——单事件等待非连接码域）
+                waiter.reject(new Error(`CDP 连接已断（${reason}）——事件等待结清`));
+            }
+        }
+        eventWaiters.clear();
+        for (const listener of downListeners)
+            listener(deadReason);
+    };
+    /** 事件分发：等待账优先（配对即清）→ 广播监听者 */
+    const dispatchEvent = (event) => {
+        const key = `${event.method}\0${event.sessionId ?? ''}`;
+        const queue = eventWaiters.get(key);
+        if (queue !== undefined && queue.length > 0) {
+            const waiter = queue.shift();
+            clearTimeout(waiter.timer);
+            waiter.resolve(event.params);
+            if (queue.length === 0)
+                eventWaiters.delete(key);
+            return; // 配对等待者独占（loadEventFired 一类单发事件不容双消费）
+        }
+        for (const listener of eventListeners) {
+            try {
+                listener(event);
+            }
+            catch (err) {
+                logger?.warn?.(`CDP 事件监听者抛错（contained 吞）：${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    };
+    /** 入站文本帧路由：应答帧（带 id）→ 关联表；事件帧（带 method）→ 分发 */
+    ws.onMessage((text) => {
+        let msg;
+        try {
+            msg = JSON.parse(text);
+        }
+        catch {
+            logger?.warn?.(`CDP 入站帧非 JSON（丢弃）：${text.slice(0, 120)}`);
+            return;
+        }
+        if (typeof msg.id === 'number') {
+            const entry = pending.get(msg.id);
+            if (entry === undefined)
+                return; // 迟到应答（超时已结清）——静默
+            pending.delete(msg.id);
+            clearTimeout(entry.timer);
+            if (msg.error !== null && msg.error !== undefined) {
+                const err = msg.error;
+                entry.reject(new CdpCommandError(typeof err.code === 'number' ? err.code : 0, typeof err.message === 'string' ? err.message : '未知错误'));
+            }
+            else {
+                entry.resolve(msg.result);
+            }
+            return;
+        }
+        if (typeof msg.method === 'string') {
+            dispatchEvent({
+                method: msg.method,
+                params: msg.params,
+                ...(typeof msg.sessionId === 'string' ? { sessionId: msg.sessionId } : {}),
+            });
+        }
+        // 既无 id 又无 method——协议面外噪声，静默
+    });
+    ws.onClose(() => settleDown('WebSocket 已关闭'));
+    const conn = {
+        get isDead() {
+            return isDead();
+        },
+        onDown(listener) {
+            if (downGate) {
+                listener(deadReason); // 迟到订阅即回调（mcp/lsp onExit 同律）
+                return;
+            }
+            downListeners.add(listener);
+        },
+        onEvent(listener) {
+            eventListeners.add(listener);
+            return () => eventListeners.delete(listener);
+        },
+        waitEvent(method, sessionId, timeoutMs) {
+            return new Promise((resolve, reject) => {
+                if (isDead()) {
+                    reject(new BaseError('BROWSER_CONNECT_FAILED', `CDP 连接已断（${deadReason}）——等待 ${method} 不可达`));
+                    return;
+                }
+                const key = `${method}\0${sessionId ?? ''}`;
+                const waiter = {
+                    resolve,
+                    reject,
+                    timer: setTimeout(() => {
+                        const queue = eventWaiters.get(key);
+                        if (queue !== undefined) {
+                            const idx = queue.indexOf(waiter);
+                            if (idx >= 0)
+                                queue.splice(idx, 1);
+                            if (queue.length === 0)
+                                eventWaiters.delete(key);
+                        }
+                        reject(new Error(`CDP 事件 ${method} 等待超时（${timeoutMs}ms）`));
+                    }, timeoutMs),
+                };
+                const queue = eventWaiters.get(key);
+                if (queue !== undefined)
+                    queue.push(waiter);
+                else
+                    eventWaiters.set(key, [waiter]);
+            });
+        },
+        send(method, params = {}, opts = {}) {
+            return new Promise((resolve, reject) => {
+                if (isDead()) {
+                    reject(new BaseError('BROWSER_CONNECT_FAILED', `CDP 连接已断（${deadReason}）——命令 ${method} 快拒`));
+                    return;
+                }
+                const id = nextId++;
+                const timeoutMs = opts.timeoutMs ?? commandTimeout;
+                const entry = {
+                    resolve,
+                    reject,
+                    method,
+                    timer: setTimeout(() => {
+                        pending.delete(id);
+                        reject(new Error(`CDP 命令 ${method} 超时（${timeoutMs}ms）——连接仍在，单命令结清`));
+                    }, timeoutMs),
+                };
+                pending.set(id, entry);
+                const frame = { id, method, params };
+                if (opts.sessionId !== undefined)
+                    frame.sessionId = opts.sessionId;
+                try {
+                    ws.send(JSON.stringify(frame));
+                }
+                catch (err) {
+                    pending.delete(id);
+                    clearTimeout(entry.timer);
+                    reject(err instanceof Error ? err : new Error(String(err)));
+                }
+            });
+        },
+        close() {
+            settleDown('主动关闭');
+            ws.close();
+        },
+    };
+    return conn;
+}
+/* ---------------- 生产 ws 面（Node ≥22 原生 WebSocket 包装） ---------------- */
+/**
+ * 缺省 ws 面：全局 WebSocket（undici 产物，Node ≥22 免 flag）。只暴露桥所需
+ * 最小子集——opened 建立门 + 文本帧收发 + 关闭挂线。
+ */
+export function defaultWsFace() {
+    return {
+        connect(url) {
+            const socket = new WebSocket(url);
+            let messageListener;
+            let closeListener;
+            let closed = false;
+            socket.addEventListener('message', (event) => {
+                // CDP 线形恒文本帧；二进制帧（协议面外）丢弃
+                if (typeof event.data === 'string')
+                    messageListener?.(event.data);
+            });
+            socket.addEventListener('close', () => {
+                if (closed)
+                    return;
+                closed = true;
+                closeListener?.();
+            });
+            socket.addEventListener('error', () => {
+                // error 不单独语义化：close 必随后到（undici 生命周期）——关联回归一处
+            });
+            const connection = {
+                send: (text) => socket.send(text),
+                close: () => {
+                    if (closed)
+                        return;
+                    try {
+                        socket.close();
+                    }
+                    catch {
+                        /* CLOSING 期重复 close——吞 */
+                    }
+                },
+                onMessage: (listener) => {
+                    messageListener = listener;
+                },
+                onClose: (listener) => {
+                    closeListener = listener;
+                },
+                opened: new Promise((resolve, reject) => {
+                    socket.addEventListener('open', () => resolve());
+                    socket.addEventListener('close', () => reject(new BaseError('BROWSER_CONNECT_FAILED', `WebSocket 建立失败（连接即关闭）：${url}`)));
+                    socket.addEventListener('error', () => reject(new BaseError('BROWSER_CONNECT_FAILED', `WebSocket 建立失败：${url}`)));
+                }),
+            };
+            return connection;
+        },
+    };
+}

package/dist/browser/codes.js

@@ -0,0 +1,31 @@
+/**
+ * browser 桥域错误码注册（03 §10.3——BROWSER_ 前缀族首批）。
+ *
+ * 前缀族明列见 contracts/errors.ts ERROR_CODE_PREFIXES（02 §5.3 #1）；码名清
+ * 单与语义真源 = 03 篇 §10.3 引擎发现序/生命周期条 + 02 §5.3 BROWSER_ 族四
+ * 码。本文件由模块公开面 index.ts 引入（注册纪律：写入点文件必须实际 import
+ * 本文件注册才发生——与 mcp/lsp 先例同款）。
+ */
+import { registerErrorCodes } from '../contracts/index.js';
+registerErrorCodes([
+    {
+        code: 'BROWSER_ENGINE_NOT_FOUND',
+        module: 'browser',
+        description: '引擎发现序四步全缺席（显式覆盖 / 系统 Chrome 知名位 + PATH / 数据目录专用引擎）——工具调用诚实缺席拒附安装指引，不自动下载；显式覆盖指名路径缺席同码（显式误配 fail-loud 不静默回退）',
+    },
+    {
+        code: 'BROWSER_CONNECT_FAILED',
+        module: 'browser',
+        description: '引擎 spawn 后 CDP 载体级失败（DevTools 侦听行缺席/启动超时、WebSocket 建立失败、连接中断）——结清在途请求 + 引擎降级（下用再试），不炸宿主',
+    },
+    {
+        code: 'BROWSER_DIGEST_MISMATCH',
+        module: 'browser',
+        description: '/browser install 同版本重装摘要不符即拒执行（TOFU 锚定执法——账本既有指纹 vs 本次实收指纹），既有引擎不动',
+    },
+    {
+        code: 'BROWSER_CONFIG_INVALID',
+        module: 'browser',
+        description: 'config.browser 行载荷坏（executablePath 非空字符串形 / providers 非数组形——装载时刻响亮拒）',
+    },
+]);

package/dist/browser/discover.js

@@ -0,0 +1,107 @@
+/**
+ * 引擎发现序（03 §10.3——四步：显式覆盖 → 系统 Chrome 知名位 + PATH →
+ * 数据目录专用引擎 → 诚实缺席）。
+ *
+ * 全缺席 = 诚实缺席：抛 BROWSER_ENGINE_NOT_FOUND 附安装指引——**不自动下载**
+ * （150MB 级惊喜下载不可接受；下载 = 显式命令 /browser install，归 install 件）。
+ * 显式覆盖（config executablePath / `BERRY_AGENT_BROWSER_PATH`）指名路径缺席
+ * 同码 fail-loud——显式误配不静默回退（回退会掩盖配置错误）。
+ */
+import { BaseError } from '../contracts/index.js';
+/** macOS 系统 Chrome 知名位（系统级 + 用户级两形） */
+function wellKnownDarwin(homeDir) {
+    return [
+        '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+        `${homeDir}/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`,
+    ];
+}
+/** Linux 系统 Chrome 知名位（发行版包名族 + snap 形） */
+function wellKnownLinux() {
+    return [
+        '/usr/bin/google-chrome',
+        '/usr/bin/google-chrome-stable',
+        '/usr/bin/google-chrome-beta',
+        '/usr/bin/chromium',
+        '/usr/bin/chromium-browser',
+        '/snap/bin/chromium',
+    ];
+}
+/** 系统 Chrome 知名位（win32 v1 诚实缺席——03 §10.3 明裁） */
+export function wellKnownPaths(platform, homeDir) {
+    if (platform === 'darwin')
+        return wellKnownDarwin(homeDir);
+    if (platform === 'linux')
+        return wellKnownLinux();
+    return []; // win32：知名位 v1 诚实缺席（PATH 探测腿仍活）
+}
+/** PATH 探测可执行名（win32 走 .exe；其余四名通扫） */
+function pathProbeNames(platform) {
+    if (platform === 'win32')
+        return ['chrome.exe'];
+    return ['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser'];
+}
+/** PATH 分隔符（win32 ';' 其余 ':'） */
+function pathDelimiter(platform) {
+    return platform === 'win32' ? ';' : ':';
+}
+/** 存在且为普通文件（access + stat isFile 双腿——目录形不算引擎） */
+async function isFileAt(fs, path) {
+    try {
+        const st = await fs.stat(path);
+        return st.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 四步发现序。返回首个命中步的绝对路径；全缺席抛 BROWSER_ENGINE_NOT_FOUND。
+ */
+export async function discoverEngine(deps) {
+    const { fs, readEnv, platform, homeDir, dataDir } = deps;
+    // ① 显式覆盖：行 config executablePath 或 BERRY_AGENT_BROWSER_PATH（config
+    // 优先——行面覆盖环境面）。指名即验：缺席不回退（显式误配 fail-loud）。
+    const explicit = deps.executablePath ?? readEnv('BERRY_AGENT_BROWSER_PATH');
+    if (explicit !== undefined && explicit !== '') {
+        if (await isFileAt(fs, explicit)) {
+            return { path: explicit, source: deps.executablePath !== undefined ? 'config' : 'env' };
+        }
+        throw new BaseError('BROWSER_ENGINE_NOT_FOUND', `显式指定的浏览器引擎路径不存在：${explicit}（config browser.executablePath / BERRY_AGENT_BROWSER_PATH 显式误配不静默回退——请修正路径或移除显式配置）`);
+    }
+    // ② 系统 Chrome 知名位（macOS/Linux；win32 v1 诚实缺席）→ PATH 探测
+    for (const candidate of wellKnownPaths(platform, homeDir)) {
+        if (await isFileAt(fs, candidate))
+            return { path: candidate, source: 'wellknown' };
+    }
+    const pathEnv = readEnv('PATH');
+    if (pathEnv !== undefined && pathEnv !== '') {
+        for (const dir of pathEnv.split(pathDelimiter(platform))) {
+            if (dir === '')
+                continue;
+            for (const name of pathProbeNames(platform)) {
+                const candidate = `${dir.endsWith('/') ? dir.slice(0, -1) : dir}/${name}`;
+                if (await isFileAt(fs, candidate))
+                    return { path: candidate, source: 'path' };
+            }
+        }
+    }
+    // ③ 数据目录专用引擎（/browser install 产物——账本记相对可执行位）
+    const ledgerPath = `${dataDir}/browser/engine/ledger.json`;
+    try {
+        const raw = await fs.readFile(ledgerPath, 'utf8');
+        const ledger = JSON.parse(raw);
+        if (typeof ledger.executableRel === 'string' && ledger.executableRel !== '') {
+            const candidate = `${dataDir}/browser/engine/${ledger.executableRel}`;
+            if (await isFileAt(fs, candidate))
+                return { path: candidate, source: 'dataDir' };
+        }
+    }
+    catch {
+        // 账本缺席/坏形——install 未跑过即无专用引擎，静默落第④步（诚实缺席）
+    }
+    // ④ 全缺席 = 诚实缺席（附安装指引——不自动下载）
+    throw new BaseError('BROWSER_ENGINE_NOT_FOUND', '未发现可用的浏览器引擎（系统 Chrome 知名位 / PATH / 数据目录专用引擎均缺席）。' +
+        '安装路径三选一：① 在会话中执行 /browser install 下载 Chromium for Testing 到数据目录；' +
+        '② 安装系统 Chrome（macOS/Linux 知名位或 PATH 可见即自动发现）；' +
+        '③ 经 config browser.executablePath 或 BERRY_AGENT_BROWSER_PATH 显式指定引擎路径');
+}

package/dist/browser/engine.js

@@ -0,0 +1,169 @@
+/**
+ * 引擎生命周期件（03 §10.3——惰性首用 spawn + DevTools 侦听行发现 + CDP 建立）。
+ *
+ * 编舞：发现序（discoverEngine）→ spawn（`--headless=new` +
+ * `--remote-debugging-port=0`〔自动分配零端口竞态〕+ `--user-data-dir` 钉数据
+ * 目录不碰用户日常档）→ stderr 侦听行解析（port=0 形态下引擎在 stderr 报
+ * `DevTools listening on ws://127.0.0.1:<port>/devtools/browser/<guid>`——
+ * 零端口即唯一出口）→ ws 建立（browser 级单连接）→ Browser.getVersion 握手
+ * 校验。全程同罩启动预算钟。
+ *
+ * 失败收口：任何一步失败 = BROWSER_CONNECT_FAILED + 子进程树杀（不留孤儿）。
+ * 运行期降级：ws 关闭/进程退出 → onDown 一次性收口（在途结清归 cdp 件）。
+ * 协议化关停 close()：Browser.close 命令 → 宽限等自退 → kill 兜底（幂等）。
+ */
+import { BaseError } from '../contracts/index.js';
+import { createCdpConnection } from './cdp.js';
+import { discoverEngine } from './discover.js';
+import { BROWSER_CLOSE_GRACE_MS, BROWSER_ENGINE_ENV_ALLOW, BROWSER_ENGINE_OWNER, BROWSER_STARTUP_TIMEOUT_MS, DEVTOOLS_LISTENING_RE, } from './types.js';
+/**
+ * 启动引擎（惰性首用的执行体——发现 → spawn → 侦听行 → ws → 握手）。
+ * 任何一步失败：kill 子进程 + 抛 BROWSER_ENGINE_NOT_FOUND（发现序缺席）或
+ * BROWSER_CONNECT_FAILED（载体级失败）。
+ */
+export async function launchBrowserEngine(deps) {
+    const logger = deps.logger;
+    const startupTimeoutMs = deps.startupTimeoutMs ?? BROWSER_STARTUP_TIMEOUT_MS;
+    const closeGraceMs = deps.closeGraceMs ?? BROWSER_CLOSE_GRACE_MS;
+    // 发现序（第①~④步——缺席即 BROWSER_ENGINE_NOT_FOUND 附安装指引）
+    const discovered = await discoverEngine({
+        fs: deps.fs,
+        readEnv: deps.readEnv,
+        platform: deps.platform,
+        homeDir: deps.homeDir,
+        dataDir: deps.dataDir,
+        ...(deps.config.executablePath !== undefined ? { executablePath: deps.config.executablePath } : {}),
+    });
+    logger?.info?.(`browser 引擎发现命中（${discovered.source}）：${discovered.path}`);
+    // profile 目录就位（--user-data-dir 钉数据目录——不碰用户日常档）
+    const profileDir = `${deps.dataDir}/browser/profile`;
+    await deps.fs.mkdir(profileDir, { recursive: true });
+    const child = deps.spawn.spawnInteractive({
+        argv: [
+            discovered.path,
+            '--headless=new',
+            '--remote-debugging-port=0',
+            `--user-data-dir=${profileDir}`,
+            '--no-first-run',
+            '--no-default-browser-check',
+            'about:blank',
+        ],
+        env: { allow: BROWSER_ENGINE_ENV_ALLOW },
+        owner: BROWSER_ENGINE_OWNER,
+    });
+    // 启动竞速收口旗：先到者封（握手持/进程退/预算钟三源）
+    let settled = false;
+    // stderr 累积 + 侦听行扫描（port=0 的唯一出口）。失败（预算钟尽/进程先退）
+    // = 树杀不留孤儿——已退场景 kill 无害，未退场景（超时腿）不杀即漏孤儿。
+    let wsUrl;
+    try {
+        wsUrl = await new Promise((resolve, reject) => {
+            let buffer = '';
+            const finish = (fn) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                fn();
+            };
+            const timer = setTimeout(() => finish(() => reject(new BaseError('BROWSER_CONNECT_FAILED', `引擎启动超时（${startupTimeoutMs}ms）未报 DevTools 侦听行——stderr 累积：${buffer.slice(-400)}`))), startupTimeoutMs);
+            child.stderr.on('data', (chunk) => {
+                buffer += chunk.toString('utf8');
+                const match = DEVTOOLS_LISTENING_RE.exec(buffer);
+                if (match !== null) {
+                    const url = match[1] ?? '';
+                    finish(() => resolve(url));
+                }
+            });
+            child.onExit((info) => finish(() => reject(new BaseError('BROWSER_CONNECT_FAILED', `引擎进程在 DevTools 侦听行产出前退出（${info.spawnError !== undefined ? `spawn 失败：${info.spawnError.message}` : `exit ${String(info.code)}`}）——路径：${discovered.path}`))));
+        });
+    }
+    catch (err) {
+        child.kill();
+        throw err;
+    }
+    // ws 建立（browser 级单连接）——失败即树杀不留孤儿
+    const wsConn = deps.ws.connect(wsUrl);
+    try {
+        await wsConn.opened;
+    }
+    catch (err) {
+        child.kill();
+        throw err instanceof BaseError
+            ? err
+            : new BaseError('BROWSER_CONNECT_FAILED', `WebSocket 建立失败：${err instanceof Error ? err.message : String(err)}`);
+    }
+    const conn = createCdpConnection(wsConn, { logger });
+    try {
+        // 握手校验（Browser.getVersion——CDP 线形活性验证）
+        await conn.send('Browser.getVersion', {}, { timeoutMs: startupTimeoutMs });
+    }
+    catch (err) {
+        conn.close();
+        child.kill();
+        throw err instanceof BaseError
+            ? err
+            : new BaseError('BROWSER_CONNECT_FAILED', `CDP 握手（Browser.getVersion）失败：${err instanceof Error ? err.message : String(err)}`);
+    }
+    // 运行期降级双源：进程退出 / ws 关闭（后者 cdp 件内已收口）——任一先到，
+    // 引擎侧标死 + onDown 一次性送达。进程退也兜底关 ws（幂等）。
+    let downGate = false;
+    let downReason = '';
+    const downListeners = new Set();
+    const markDown = (reason) => {
+        if (downGate)
+            return;
+        downGate = true;
+        downReason = reason;
+        conn.close(); // 在途结清 + 后续快拒（幂等）
+        for (const listener of downListeners)
+            listener(reason);
+    };
+    conn.onDown((reason) => markDown(`连接关闭：${reason}`));
+    child.onExit((info) => markDown(info.spawnError !== undefined ? `进程退出（spawn 失败）` : `进程退出（code ${String(info.code)}）`));
+    let closeGate = false;
+    const handle = {
+        conn,
+        discovered,
+        get alive() {
+            return !downGate;
+        },
+        onDown(listener) {
+            if (downGate) {
+                listener(downReason);
+                return;
+            }
+            downListeners.add(listener);
+        },
+        close() {
+            if (closeGate)
+                return Promise.resolve();
+            closeGate = true;
+            return (async () => {
+                // 告别命令先行（markDown 会结清在途并关 ws——顺序不可倒）；坏引擎
+                // 不响应即超时落宽限腿，不悬挂
+                if (!downGate) {
+                    try {
+                        await conn.send('Browser.close', {}, { timeoutMs: closeGraceMs });
+                    }
+                    catch {
+                        /* 协议告别失败走宽限兜底 */
+                    }
+                }
+                markDown('协议化关停');
+                // 宽限等自退 → kill 兜底（不因坏引擎悬挂）
+                await new Promise((resolve) => {
+                    const timer = setTimeout(() => {
+                        child.kill();
+                        resolve();
+                    }, closeGraceMs);
+                    child.onExit(() => {
+                        clearTimeout(timer);
+                        resolve();
+                    });
+                });
+            })();
+        },
+    };
+    return handle;
+}

package/dist/browser/index.js

@@ -0,0 +1,17 @@
+/**
+ * browser 模块公开面（L3 core: 官方插件 15 之 #7——02 §4.1 席 19 / 03 §10.3
+ * browser 桥件章：CDP 手写最小桥 + 引擎发现序 + 工具面十件）。
+ *
+ * 批 17b-3 工具面+编排腿：页面上下文 + 工具面十件 + 编排（惰性引擎/会话
+ * 路由/两级闲置回收）。批 17b-4 install 件：/browser install 下载原语
+ * （CfT 元数据 + 流式下载 + 手写 unzip + 摘要账本 TOFU 锚定）已入本面。
+ */
+import './codes.js';
+export { BROWSER_STARTUP_TIMEOUT_MS, BROWSER_CDP_COMMAND_TIMEOUT_MS, BROWSER_IDLE_MS, BROWSER_SWEEP_INTERVAL_MS, BROWSER_CLOSE_GRACE_MS, BROWSER_NAV_TIMEOUT_MS, BROWSER_CONSOLE_RING_CAP, BROWSER_SCREENSHOT_KEEP, BROWSER_SCREENSHOT_DIRNAME, BROWSER_ENGINE_OWNER, BROWSER_ENGINE_ENV_ALLOW, normalizeBrowserConfig, } from './types.js';
+export { wellKnownPaths, discoverEngine } from './discover.js';
+export { createCdpConnection, defaultWsFace, CdpCommandError } from './cdp.js';
+export { launchBrowserEngine } from './engine.js';
+export { createBrowserPage } from './page.js';
+export { buildBrowserTools } from './tools.js';
+export { createBrowserService } from './service.js';
+export { BROWSER_METADATA_URL, BROWSER_DOWNLOAD_HOSTS, BROWSER_ENGINE_DIRNAME, BROWSER_LEDGER_NAME, BROWSER_ZIP_MAX_BYTES, platformArtifact, defaultDownloadFace, unzipTo, installBrowserEngine, } from './install.js';