@angelky7/dsh-browser-control 0.0.0-stage → 1.1.0

package/lib/invariant.js

@@ -0,0 +1,25 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-browser-bridge`.
+* @module @deepseek-ai/dsh-browser-bridge/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-browser-bridge";
+/** Cordis companion plugin name. */
+const name = "browser-bridge-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: the bridge owns no durable session events or shared
+* mutable state; its socket lifecycle relations (dispose releases the port,
+* pending commands reject on link loss) are asserted by unit tests against
+* the private server instance.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/errors.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 工具调用失败时的结构化契约。
+ *
+ * Agent 拿到一句 `Error("...")` 文本时，其实无法决定下一步：该重试、该放弃、还是
+ * 该先去确认页面状态？真正需要区分的是两件事——
+ *
+ *   1. `code`：失败的可分类原因（链路没起、扩展没连、超时、扩展报错……）
+ *   2. `effectState`：这次调用的副作用**是否可能已经落到页面上**
+ *
+ * 第二条是重点：`click` 超时和"扩展中途断开"都属于**结果未知**——鼠标事件也许已经
+ * 发出去了。这时让 agent 盲目重试，就会点两次、提交两次表单。所以对写操作，
+ * 我们宁可报 `unknown` 并要求它先观察，也不假装"没发生"。
+ *
+ * 读操作（截图、读文本、查元素、列标签……）不改变页面，任何失败都是 `not_started`，
+ * 重试安全。
+ */
+/** 失败原因分类。 */
+export type BridgeErrorCode = 'bridge_disabled' | 'extension_offline' | 'command_timeout' | 'link_lost' | 'cancelled' | 'not_configured' | 'blocked_by_policy' | 'locked_by_user' | 'lock_unreadable' | 'held_by_user' | 'command_failed';
+/**
+ * 扩展侧拒绝命令时写在 error 文本最前面的两个标记。
+ *
+ * 结果帧里只有一个 `error` 字符串，没有 code 字段，所以「这条命令根本没发出去」
+ * 这个信息只能长在文本上穿过渡线上。字面量在 `extension/background.js` 里有一份
+ * 一模一样的，`verify/verify_errors.mjs` 会对账两边——少了对账就是一边改了前缀、
+ * 另一边静默退回 `command_failed` + `unknown`（写操作会被说成「可能已经落到页面上」，
+ * 而那恰好是假的）。
+ */
+export declare const LOCKED_BY_USER_MARKER = "browser-locked-by-user:";
+export declare const LOCK_UNREADABLE_MARKER = "browser-lock-unreadable:";
+/** 接管浮层上的「中止操作」。同样的线协议约定：字面量在扩展侧有一份，对账在 `verify_errors.mjs`。 */
+export declare const HOLD_ABORTED_MARKER = "browser-hold-aborted:";
+/** 副作用状态。 */
+export type EffectState = 
+/** 确定没有副作用落到页面上，重试安全。 */
+'not_started'
+/** 无法判断（写操作超时、在途掉线、扩展中途报错），重试前应先观察。 */
+ | 'unknown'
+/** 已确认执行完成（用于成功路径的显式标注，目前只在结果里出现）。 */
+ | 'committed';
+/** 该命令是否可能留下副作用。 */
+export declare function isWriteCommand(command: string): boolean;
+/** 带分类的桥接错误；`message` 面向模型，`toJSON()` 面向程序。 */
+export declare class BridgeError extends Error {
+    readonly code: BridgeErrorCode;
+    readonly effectState: EffectState;
+    readonly hint: string;
+    readonly command: string;
+    /** 原始失败描述：HTTP 面的 `error` 字段就是它，不含我们追加的契约文案。 */
+    readonly detail: string;
+    constructor(command: string, code: BridgeErrorCode, effectState: EffectState, message: string);
+    /** 给 HTTP 面用的扁平 JSON 形状。 */
+    toJSON(): {
+        ok: false;
+        error: string;
+        code: string;
+        effectState: string;
+        hint: string;
+    };
+}
+/**
+ * 把任意底层抛出的错误归类成 BridgeError。已经分类过的原样返回，
+ * 保证多次包裹不会把 code 洗掉。
+ */
+export declare function classify(command: string, error: unknown): BridgeError;

package/lib/types/errors.js

@@ -0,0 +1,161 @@
+/**
+ * 工具调用失败时的结构化契约。
+ *
+ * Agent 拿到一句 `Error("...")` 文本时，其实无法决定下一步：该重试、该放弃、还是
+ * 该先去确认页面状态？真正需要区分的是两件事——
+ *
+ *   1. `code`：失败的可分类原因（链路没起、扩展没连、超时、扩展报错……）
+ *   2. `effectState`：这次调用的副作用**是否可能已经落到页面上**
+ *
+ * 第二条是重点：`click` 超时和"扩展中途断开"都属于**结果未知**——鼠标事件也许已经
+ * 发出去了。这时让 agent 盲目重试，就会点两次、提交两次表单。所以对写操作，
+ * 我们宁可报 `unknown` 并要求它先观察，也不假装"没发生"。
+ *
+ * 读操作（截图、读文本、查元素、列标签……）不改变页面，任何失败都是 `not_started`，
+ * 重试安全。
+ */
+/**
+ * 扩展侧拒绝命令时写在 error 文本最前面的两个标记。
+ *
+ * 结果帧里只有一个 `error` 字符串，没有 code 字段，所以「这条命令根本没发出去」
+ * 这个信息只能长在文本上穿过渡线上。字面量在 `extension/background.js` 里有一份
+ * 一模一样的，`verify/verify_errors.mjs` 会对账两边——少了对账就是一边改了前缀、
+ * 另一边静默退回 `command_failed` + `unknown`（写操作会被说成「可能已经落到页面上」，
+ * 而那恰好是假的）。
+ */
+export const LOCKED_BY_USER_MARKER = 'browser-locked-by-user:';
+export const LOCK_UNREADABLE_MARKER = 'browser-lock-unreadable:';
+/** 接管浮层上的「中止操作」。同样的线协议约定：字面量在扩展侧有一份，对账在 `verify_errors.mjs`。 */
+export const HOLD_ABORTED_MARKER = 'browser-hold-aborted:';
+/**
+ * 会改变页面或不可逆地改变浏览器状态的命令；其余按只读处理。
+ *
+ * 表里绝大多数是**扩展命令名**（`classify()` 按调用方传进来的名字查表），但也包含
+ * 插件本地命令（见下面 `cleanup`）：判据始终是同一条——失败之后重试会不会多造成一次损害。
+ *
+ * 判据是「重试会不会造成额外损害」，不是「有没有动到浏览器」。所以标签分组
+ * （`tabs.group` / `tabs.ungroup`）不在这里：把已经在组里的标签再归一次是空操作，
+ * 拆组失败后再拆一次也不会多拆坏东西，重试安全；而 `tabs.open` 重试会多出标签页、
+ * `tabs.close` 重试可能关掉用户正在看的页面，必须报 unknown。
+ */
+const WRITE_COMMANDS = new Set([
+    'nav', 'click', 'input', 'press', 'scroll', 'eval', 'emulate',
+    'tabs.open', 'tabs.close', 'tabs.closeMany', 'tabs.activate', 'dialog',
+    // 这条不是扩展命令，而是插件本地命令 `browser_cleanup`：它逐条 rm，中途失败
+    // （Windows 上被占用的截图会 EPERM）时前面的文件已经没了，报 not_started
+    // 就是告诉模型「什么都没发生，重试安全」，而那正好是假的。
+    'cleanup',
+    // 往页面里插一个宿主元素 = 改页面 DOM。超时/掉线之后重试，可能多留一层浮层
+    //（旧的那层还挂着），所以报 unknown 而不是「没动过页面」。
+    'hold',
+]);
+/** 该命令是否可能留下副作用。 */
+export function isWriteCommand(command) {
+    return WRITE_COMMANDS.has(command);
+}
+/** 每个 code 对应的下一步建议（写给 agent，不是写给用户看的日志）。 */
+const HINTS = {
+    bridge_disabled: '桥接未启用：在 profile 的 cordis.patch.yml 里给 browser-bridge 配 enabled: true 后重启 dsh；不要重试本命令。',
+    extension_offline: '浏览器扩展没连上：让用户打开装了 DSH Browser Control 的那个浏览器（扩展图标应为绿色），确认端口与 Token 两边一致后再试。',
+    command_timeout: '扩展超时未回应：先别重试。用 browser_find / browser_snapshot 看页面当前状态，判断动作是否其实已经生效。',
+    link_lost: '命令在途时链路断了：动作可能已经落到页面上。先用只读工具确认页面状态，再决定是否重做。',
+    cancelled: '调用被取消：按需重新发起，不必当作错误处理。',
+    not_configured: '插件还没读到配置：确认 dsh 已加载本插件（dsh plugin list）后再试。',
+    held_by_user: '这是用户在页面上的接管浮层里按下的「中止操作」，不是故障：命令一条都没有发出。先与用户确认；他同意继续之后调用 browser_hold action=off 解除，然后再继续原来的步骤。不要重试，也不要换成别的工具绕过它。',
+    blocked_by_policy: '这是本机策略拦下的，不是故障：命令没有发给浏览器（零副作用）。要放开改 profile 的 cordis.patch.yml（browser-bridge 的 readOnly / allowScript）并重启 dsh，或换成本机允许的只读工具；不要原地重试。',
+    locked_by_user: '这是用户在扩展弹窗里按下的「锁定」，不是故障：命令一条都没有发出。请先与用户确认，由他在同一个弹窗里点「已锁定」解除；不要重试，也不要试图改配置绕过它。',
+    lock_unreadable: '扩展这次读不出锁的状态，按冻结处理了：命令没有发出。下一条命令会重新读一次，所以可以再试一次，但不要循环重试；一直如此就请用户重启浏览器或重装扩展。',
+    command_failed: '扩展报回失败：按 error 文本处理，通常是选择器没命中、标签页已关闭或页面不允许该操作。',
+};
+/**
+ * 失败文案里「该不该重试」那半句。
+ *
+ * 宿主的失败内容是 `Error: ${message}`（`@deepseek-ai/dsh-tools` `lib/index.js:3616-3623`），
+ * `code` / `effectState` / `hint` 这些结构化字段只进 `error.info` 与 HTTP 面，
+ * **模型读不到**。所以决定下一步所需的两个信息——副作用状态与下一步动作——必须写进
+ * message 本身，否则整个错误契约对 agent 失效（和「render 只写摘要」是同一类缺陷）。
+ */
+function effectClause(effectState) {
+    switch (effectState) {
+        case 'unknown':
+            return 'effectState=unknown：动作可能已经落到页面上，先用只读工具看当前状态，再决定要不要重做，不要直接重试';
+        case 'committed':
+            return 'effectState=committed：动作已经生效';
+        default:
+            return 'effectState=not_started：这次调用没有动到页面，重试安全';
+    }
+}
+/** 带分类的桥接错误；`message` 面向模型，`toJSON()` 面向程序。 */
+export class BridgeError extends Error {
+    code;
+    effectState;
+    hint;
+    command;
+    /** 原始失败描述：HTTP 面的 `error` 字段就是它，不含我们追加的契约文案。 */
+    detail;
+    constructor(command, code, effectState, message) {
+        super(`[${code}] ${message} — ${effectClause(effectState)}。下一步：${HINTS[code]}`);
+        this.name = 'BridgeError';
+        this.code = code;
+        this.effectState = effectState;
+        this.hint = HINTS[code];
+        this.command = command;
+        this.detail = message;
+    }
+    /** 给 HTTP 面用的扁平 JSON 形状。 */
+    toJSON() {
+        return {
+            ok: false,
+            error: this.detail,
+            code: this.code,
+            effectState: this.effectState,
+            hint: this.hint,
+        };
+    }
+}
+/**
+ * 把任意底层抛出的错误归类成 BridgeError。已经分类过的原样返回，
+ * 保证多次包裹不会把 code 洗掉。
+ */
+export function classify(command, error) {
+    if (error instanceof BridgeError)
+        return error;
+    const raw = error instanceof Error ? error.message : String(error);
+    // 扩展弹窗的锁把「这条命令根本没发出去」写在文本前缀上（结果帧里只有 error 一个
+    // 字符串可以带信息）。先认它，并把标记从给模型看的那句话里剥掉：它不该跟着
+    // 落到上下文中。认不出前缀的那些（老扩展、别的失败）照原路走。
+    const locked = raw.startsWith(LOCKED_BY_USER_MARKER) ? 'locked_by_user'
+        : raw.startsWith(LOCK_UNREADABLE_MARKER) ? 'lock_unreadable'
+            : raw.startsWith(HOLD_ABORTED_MARKER) ? 'held_by_user'
+                : undefined;
+    const markerLength = locked === 'locked_by_user' ? LOCKED_BY_USER_MARKER.length
+        : locked === 'lock_unreadable' ? LOCK_UNREADABLE_MARKER.length
+            : locked === 'held_by_user' ? HOLD_ABORTED_MARKER.length
+                : 0;
+    const message = locked ? raw.slice(markerLength).trim() : raw;
+    // 写操作一旦超时或掉线，结果就是未知的；读操作永远可以安全重试。
+    const unknownIsPossible = isWriteCommand(command);
+    let code;
+    if (locked !== undefined)
+        code = locked;
+    else if (/no browser extension connected/.test(message))
+        code = 'extension_offline';
+    else if (/disconnected mid-command|browser-bridge stopped/.test(message))
+        code = 'link_lost';
+    else if (/timed out after/.test(message))
+        code = 'command_timeout';
+    else if (/cancelled/.test(message))
+        code = 'cancelled';
+    else if (/尚未加载配置|not configured yet/.test(message))
+        code = 'not_configured';
+    else if (/未启用|not enabled|桥接启动失败|listen EADDR|settings integration/.test(message))
+        code = 'bridge_disabled';
+    else
+        code = 'command_failed';
+    const effectState = code === 'command_timeout' || code === 'link_lost'
+        ? (unknownIsPossible ? 'unknown' : 'not_started')
+        : code === 'command_failed'
+            ? (unknownIsPossible ? 'unknown' : 'not_started')
+            : 'not_started';
+    return new BridgeError(command, code, effectState, message);
+}

package/lib/types/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Browser-bridge plugin: one local WebSocket endpoint the DSH Browser Control
+ * extension connects to, plus the model-facing `browser_*` tools that drive
+ * it. The Settings-managed `enabled` flag starts and stops the listener live
+ * through dsh-settings' change hook — no reload needed.
+ *
+ * Settings integration is feature-detected, never assumed. The plugin bypasses the
+ * higher-level `installSettingsSection` helper (importing it on a build that does not
+ * export it crashes the plugin at module load) and calls the lower-level
+ * `sctx.settings.register` only when the host actually has it — dsh-settings up to
+ * 0.1.2-rc.1. 0.1.7-rc.2 and 0.2.x export `SettingsForms` with no `register`, so there
+ * the bridge converges from the profile config alone and the host projects this
+ * plugin's own `Config` schema into the settings page.
+ *
+ * Tools stay mounted whenever the plugin does; calling one while the bridge
+ * is disabled or the extension is offline fails with a message naming the
+ * fix, so the model can tell the user what to do instead of hanging.
+ * @module @deepseek-ai/dsh-browser-bridge
+ */
+import { type Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export { LOCAL_DESTRUCTIVE_COMMANDS, PAGE_MUTATING_COMMANDS, READ_ONLY_ALLOWED, SCRIPT_COMMANDS, policyRefusal } from './policy.ts';
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "browser-bridge";
+/** The tool registry this plugin contributes `browser_*` tools to. */
+export declare const inject: string[];
+/** Settings namespace carrying the bridge switch and endpoint options. */
+export declare const BROWSER_BRIDGE_SETTINGS_NAMESPACE = "browser-bridge";
+export interface Config {
+    /**
+     * Whether the local bridge listens. Defaults to true so the plugin is
+     * usable immediately after install; set false to keep the tools mounted but
+     * every call reports how to enable the bridge, so the opt-out stays explicit.
+     */
+    enabled?: boolean;
+    /** Loopback port the extension dials; the HTTP face shares it. */
+    port?: number;
+    /** Shared secret the extension presents on the WebSocket upgrade query. */
+    token?: string;
+    /**
+     * Directory screenshots are written to and `cleanup` clears. Relative paths
+     * resolve against the process working directory at resolve time.
+     */ shotsDir?: string;
+    /**
+     * Read-only mode: refuse every command that would change the page or the
+     * browser (click / input / press / nav / scroll / tabs.* / emulate / dialog /
+     * network.clear …) while reads keep working. Off by default. Takes effect
+     * live — the gate reads the current settings on every call.
+     */
+    readOnly?: boolean;
+    /**
+     * Allow running arbitrary page scripts (`browser_evaluate`). On by default,
+     * because that tool is the escape hatch when no dedicated command fits. Set
+     * false to keep clicks and reads while forbidding arbitrary JS in the page:
+     * `browser_evaluate` can do everything the other tools can, so "read-only"
+     * alone does not take arbitrary code off the table.
+     */
+    allowScript?: boolean;
+}
+export declare const Config: z<Config>;
+/** Cordis plugin entry: wire the settings-driven lifecycle plus the model-facing tools. */
+export declare function apply(ctx: Context, config: Config): void;