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

package/lib/types/invariant.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-browser-bridge`.
+ * @module @deepseek-ai/dsh-browser-bridge/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "browser-bridge-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;

package/lib/types/invariant.js

@@ -0,0 +1,23 @@
+/**
+ * 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. */
+export const name = 'browser-bridge-invariant';
+/** Service required before the companion can reserve package ownership. */
+export 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.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+/* jscpd:ignore-end */

package/lib/types/policy.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 本机策略闸门：只读档（`readOnly`）与脚本开关（`allowScript`）。
+ *
+ * 这两张表与 `errors.ts` 里的 `WRITE_COMMANDS` **故意不是同一张**，别合并：
+ *
+ *   - `WRITE_COMMANDS` 回答「超时或掉线之后重试，会不会多留一次副作用」，那是
+ *     `effectState` 的语义。所以 `tabs.group` / `tabs.ungroup` 在那里**刻意算只读**：
+ *     重复把标签归进同一个组是空操作，重试安全。
+ *   - 这里回答的是「这条命令会不会改变页面、文件或浏览器状态」，用户开只读档时想要的
+ *     正是这个。所以 `tabs.group` / `tabs.ungroup` / `tabs.activate` / `emulate` /
+ *     `dialog` / `network.clear` 都不在白名单里。
+ *
+ * 白名单是**默认拒绝**：扩展以后新增一条命令，它自动被只读档拦下，等人判断完再放进来。
+ * `verify/verify_policy.mjs` 会把扩展 `COMMANDS` 表逐条对账，让这个判断无法被跳过。
+ *
+ * 第三张表 `LOCAL_DESTRUCTIVE_COMMANDS` 是给**不经过扩展**的插件本地命令的：闸门如果只长在
+ * `execute()` 上，这类调用就整个绕开只读档（`browser_cleanup` 合并进来时正是这样）。
+ */
+/** 只读档允许的命令：读页面、读扩展自己的缓冲、或者把页面**内容**落到本机文件。 */
+export declare const READ_ONLY_ALLOWED: ReadonlySet<string>;
+/**
+ * 会执行**任意页面脚本**的扩展命令。这条与只读档分开管，因为用户可能想「可以读、
+ * 也可以点，但别在我页面里跑任意 JS」——`browser_evaluate` 能绕开其他所有工具做的事。
+ */
+export declare const SCRIPT_COMMANDS: ReadonlySet<string>;
+/**
+ * 不经过扩展、直接在插件进程里改动本机文件的命令名。
+ *
+ * `browser_cleanup` 走 `BridgeController.cleanup()`，**不经过 `execute()`**，所以它天然
+ * 绕开了上面两张表管的那条路。只读档下仍然能删掉用户的整个截图目录，这正是「只读」
+ * 最不该允许的动作，所以单独列一张表，并且由 `cleanup()` 自己调闸门。
+ */
+export declare const LOCAL_DESTRUCTIVE_COMMANDS: ReadonlySet<string>;
+/**
+ * 明确登记「会改页面 DOM」的命令 —— 只读档里必须拒，理由写在名字旁边。
+ *
+ * 现在只有 `hold`（接管浮层）：它往页面 `<html>` 下插一个宿主元素。默认拒绝其实已经
+ * 盖住它（不在 `READ_ONLY_ALLOWED` 里），但「默认拒绝是对的」不等于「不需要解释」：
+ * 这一条要的不是安全性，是**拒绝理由**——告诉模型为什么一个「只是提示用户」的动作
+ * 在只读档里也算写操作。
+ *
+ * `hold` 是一条命令带 `action`（on/off/status）：on/off 改 DOM，**status 只读**
+ * （它读 session 里的条目 + 探一下页面上还有没有那层宿主），所以只读档放行 status。
+ * 这也是 `policyRefusal` 唯一需要看参数的地方——判据是「这个动作改不改东西」，
+ * 不是「这个命令名字在不在表里」。
+ */
+export declare const PAGE_MUTATING_COMMANDS: ReadonlySet<string>;
+/** 两个闸门的当前值。取自插件配置，热更新即生效（改完重启 dsh 也一样）。 */
+export interface PolicyFlags {
+    /** 只读档：true 时拒绝一切会改变页面/浏览器状态的命令。 */
+    readOnly: boolean;
+    /** 允许在页面里执行任意脚本（`browser_evaluate`）。 */
+    allowScript: boolean;
+}
+/**
+ * 判断一条命令是否被本机策略拦下。
+ * @param command - 扩展命令名（`click` / `eval` / `tabs.close` …），或 `LOCAL_DESTRUCTIVE_COMMANDS` 里的插件本地命令名。
+ * @param flags - 当前的两个闸门值。
+ * @param params - 这条命令的参数；只有带动作的命令（目前是 `hold`）需要它来分辨「这个动作改不改东西」。
+ * @returns 拒绝时写给 agent 的整句理由；放行时 `undefined`。
+ */
+export declare function policyRefusal(command: string, flags: PolicyFlags, params?: Record<string, unknown>): string | undefined;

package/lib/types/policy.js

@@ -0,0 +1,87 @@
+/**
+ * 本机策略闸门：只读档（`readOnly`）与脚本开关（`allowScript`）。
+ *
+ * 这两张表与 `errors.ts` 里的 `WRITE_COMMANDS` **故意不是同一张**，别合并：
+ *
+ *   - `WRITE_COMMANDS` 回答「超时或掉线之后重试，会不会多留一次副作用」，那是
+ *     `effectState` 的语义。所以 `tabs.group` / `tabs.ungroup` 在那里**刻意算只读**：
+ *     重复把标签归进同一个组是空操作，重试安全。
+ *   - 这里回答的是「这条命令会不会改变页面、文件或浏览器状态」，用户开只读档时想要的
+ *     正是这个。所以 `tabs.group` / `tabs.ungroup` / `tabs.activate` / `emulate` /
+ *     `dialog` / `network.clear` 都不在白名单里。
+ *
+ * 白名单是**默认拒绝**：扩展以后新增一条命令，它自动被只读档拦下，等人判断完再放进来。
+ * `verify/verify_policy.mjs` 会把扩展 `COMMANDS` 表逐条对账，让这个判断无法被跳过。
+ *
+ * 第三张表 `LOCAL_DESTRUCTIVE_COMMANDS` 是给**不经过扩展**的插件本地命令的：闸门如果只长在
+ * `execute()` 上，这类调用就整个绕开只读档（`browser_cleanup` 合并进来时正是这样）。
+ */
+/** 只读档允许的命令：读页面、读扩展自己的缓冲、或者把页面**内容**落到本机文件。 */
+export const READ_ONLY_ALLOWED = new Set([
+    // 身份与链路探测
+    'ping', 'browser.info',
+    // 读页面
+    'content', 'find', 'snapshot', 'screenshot', 'pdf', 'wait',
+    // 读扩展采集到的缓冲
+    'tabs.list', 'console.log', 'network.log',
+    // 读浏览器自己的状态（cookie 是凭据，但 get 不改任何东西；set/remove 不在此列）
+    'cookies.get',
+]);
+/**
+ * 会执行**任意页面脚本**的扩展命令。这条与只读档分开管，因为用户可能想「可以读、
+ * 也可以点，但别在我页面里跑任意 JS」——`browser_evaluate` 能绕开其他所有工具做的事。
+ */
+export const SCRIPT_COMMANDS = new Set(['eval']);
+/**
+ * 不经过扩展、直接在插件进程里改动本机文件的命令名。
+ *
+ * `browser_cleanup` 走 `BridgeController.cleanup()`，**不经过 `execute()`**，所以它天然
+ * 绕开了上面两张表管的那条路。只读档下仍然能删掉用户的整个截图目录，这正是「只读」
+ * 最不该允许的动作，所以单独列一张表，并且由 `cleanup()` 自己调闸门。
+ */
+export const LOCAL_DESTRUCTIVE_COMMANDS = new Set(['cleanup']);
+/**
+ * 明确登记「会改页面 DOM」的命令 —— 只读档里必须拒，理由写在名字旁边。
+ *
+ * 现在只有 `hold`（接管浮层）：它往页面 `<html>` 下插一个宿主元素。默认拒绝其实已经
+ * 盖住它（不在 `READ_ONLY_ALLOWED` 里），但「默认拒绝是对的」不等于「不需要解释」：
+ * 这一条要的不是安全性，是**拒绝理由**——告诉模型为什么一个「只是提示用户」的动作
+ * 在只读档里也算写操作。
+ *
+ * `hold` 是一条命令带 `action`（on/off/status）：on/off 改 DOM，**status 只读**
+ * （它读 session 里的条目 + 探一下页面上还有没有那层宿主），所以只读档放行 status。
+ * 这也是 `policyRefusal` 唯一需要看参数的地方——判据是「这个动作改不改东西」，
+ * 不是「这个命令名字在不在表里」。
+ */
+export const PAGE_MUTATING_COMMANDS = new Set(['hold']);
+const CONFIG_HINT = '开关在 profile 的 cordis.patch.yml 里（browser-bridge 的 config），改完重启 dsh；'
+    + 'dsh 0.1.7+ 的宿主也会在「设置 → 插件」里直接列出这两项';
+/**
+ * 判断一条命令是否被本机策略拦下。
+ * @param command - 扩展命令名（`click` / `eval` / `tabs.close` …），或 `LOCAL_DESTRUCTIVE_COMMANDS` 里的插件本地命令名。
+ * @param flags - 当前的两个闸门值。
+ * @param params - 这条命令的参数；只有带动作的命令（目前是 `hold`）需要它来分辨「这个动作改不改东西」。
+ * @returns 拒绝时写给 agent 的整句理由；放行时 `undefined`。
+ */
+export function policyRefusal(command, flags, params) {
+    if (!flags.allowScript && SCRIPT_COMMANDS.has(command)) {
+        return `在页面里执行任意脚本已被关闭（allowScript: false）：命令 ${command} 被拒绝，没有向浏览器发出任何操作。`
+            + `要读页面内容请改用 browser_read / browser_snapshot / browser_find；确实需要执行脚本时，${CONFIG_HINT}之后再说。`;
+    }
+    if (flags.readOnly && LOCAL_DESTRUCTIVE_COMMANDS.has(command)) {
+        return `只读模式已开启（readOnly: true）：命令 ${command} 会删除本机保存的截图与临时文件，删除不可逆，所以已被拒绝，没有任何文件被删除。`
+            + `只读档的含义是「什么都不要改」，清理属于改动；要释放磁盘请由用户自己关掉 readOnly，${CONFIG_HINT}。不要原地重试本命令。`;
+    }
+    // `hold` 带动作：on/off 改页面 DOM，status 只读（读 session 条目 + 探页面上那层还在不在），
+    // 所以只读档放行 status——只读档不该连「看一眼浮层现在是什么状态」都不让。
+    const isReadOnlyAction = command === 'hold' && params?.action === 'status';
+    if (flags.readOnly && PAGE_MUTATING_COMMANDS.has(command) && !isReadOnlyAction) {
+        return `只读模式已开启（readOnly: true）：命令 ${command} 会往页面里插入一层接管浮层（改页面 DOM），已被拒绝，没有向浏览器发出任何操作。`
+            + `浮层是给用户看的提示层，不是安全边界；只读档里连这种「只是提示」的改动也一并拒绝。要开浮层请由用户关掉 readOnly，${CONFIG_HINT}不要原地重试本命令。`;
+    }
+    if (flags.readOnly && !READ_ONLY_ALLOWED.has(command) && !isReadOnlyAction) {
+        return `只读模式已开启（readOnly: true）：命令 ${command} 会改变页面或浏览器状态，已被拒绝，没有向浏览器发出任何操作。`
+            + `只读模式下可用的工具是读页面与读日志那几类；要放开写操作，${CONFIG_HINT}不要原地重试本命令。`;
+    }
+    return undefined;
+}

package/lib/types/server.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Local WebSocket+HTTP bridge between one browser extension and dsh. The
+ * extension connects OUT to `ws://127.0.0.1:<port>/ws?token=...`, so no
+ * native-messaging host or registry setup exists; dsh drives commands through
+ * {@link BridgeServer.execute} and reads link state through {@link BridgeServer.status}.
+ * A small HTTP face (`/api/status`, `/api/command`, `/api/cleanup`, `/`) keeps
+ * the bridge usable from curl while the server runs. `/api/command` and
+ * `/api/cleanup` demand the same token as the WebSocket upgrade; `/` and
+ * `/api/status` stay readable because the status page needs them and they only
+ * report link state. No response carries `Access-Control-Allow-Origin`, and the
+ * upgrade checks `Host` plus `Origin` so neither a web page nor a rebound
+ * hostname can attach.
+ *
+ * Wire protocol (text frames, one JSON object each):
+ * - extension → server: `{type:'hello',…}`, `{type:'pong',t}`, `{type:'result',id,ok,result?|error}`
+ * - server → extension: `{type:'ping',t}`, `{type:'command',id,command,params}`
+ *
+ * Command names (sent in `command`) include: `ping`, `browser.info`, `tabs.list/open/close/activate`,
+ * `nav`, `eval`, `content`, `find`, `click`, `input`, `press`, `scroll`, `snapshot`, `screenshot`,
+ * `wait`, `dialog`, `console.log`, `network.log`, `network.clear`, `pdf`, `emulate`.
+ * @module @deepseek-ai/dsh-browser-bridge/server
+ */
+/**
+ * Wire protocol revision this bridge speaks. Kept separate from the package
+ * version: an extension that is one patch newer still works, an extension that
+ * speaks a different frame contract does not, and only the second case should
+ * light up.
+ */
+export declare const BRIDGE_PROTOCOL_VERSION = 1;
+/** Per-command ceiling when the caller passes none. */
+export declare const DEFAULT_COMMAND_TIMEOUT_MS = 60000;
+/** Hard ceiling accepted from callers; longer waits cannot be expressed. */
+export declare const MAX_COMMAND_TIMEOUT_MS = 300000;
+/** Identity the extension announces right after the handshake completes. */
+export interface BridgeHello {
+    readonly client: string;
+    readonly version: string;
+    /** Frame-contract revision the extension declared; 0 when it predates versioning. */
+    readonly protocol: number;
+    readonly browser: {
+        readonly name: string;
+        readonly version: string;
+        readonly ua: string;
+    };
+}
+/** Snapshot of the link and in-flight work, served verbatim on `/api/status`. */
+export interface BridgeServerStatus {
+    readonly listening: boolean;
+    readonly port: number | undefined;
+    readonly extensionConnected: boolean;
+    readonly connectedAt: string | undefined;
+    readonly hello: BridgeHello | undefined;
+    /** Protocol revision this bridge speaks. */
+    readonly bridgeProtocol: number;
+    /** Protocol revision the extension declared; absent/0 when it predates versioning. */
+    readonly extensionProtocol: number;
+    /** False when the two sides cannot agree on the frame contract, with the reason. */
+    readonly protocolCompatible: boolean;
+    readonly protocolNote: string | null;
+    readonly pendingCommands: number;
+    readonly lastError: string | undefined;
+    /** True when the active token is the published default or too short to be a secret. */
+    readonly insecureToken: boolean;
+}
+/** Caller controls for one {@link BridgeServer.execute} round-trip. */
+export interface BridgeExecuteOptions {
+    /** Fail the command after this many milliseconds; defaults to 60s, capped at 300s. */
+    readonly timeoutMs?: number;
+    /** Cancellation from the tool execution; aborting fails the in-flight command. */
+    readonly signal?: AbortSignal;
+}
+/** What {@link BridgeServer.cleanup} removed. */
+export interface CleanupResult {
+    /** Files deleted directly inside the screenshots directory. */
+    readonly shotsRemoved: number;
+    /** Scratch files deleted (agent temp scripts/artifacts matched by convention). */
+    readonly scratchRemoved: readonly string[];
+}
+export interface BridgeServerOptions {
+    readonly port: number;
+    readonly token: string;
+    /** Directory whose direct contents `cleanup()` clears; created on demand. */
+    readonly shotsDir: string;
+    /** Directory scanned for agent scratch files by `cleanup()`; defaults to the process working directory. */
+    readonly scratchDir?: string;
+    /** Optional line logger for lifecycle diagnostics. */
+    readonly log?: (line: string) => void;
+}
+/**
+ * Clear the screenshots directory and delete agent scratch files. Only the
+ * top level of each location is touched; nested trees stay untouched.
+ * @param options - `shotsDir` is cleared of direct file children; `scratchDir`
+ *   defaults to the process working directory and loses only scratch-named files.
+ * @returns counts and names of what was removed.
+ */
+export declare function cleanupArtifacts(options: {
+    shotsDir: string;
+    scratchDir?: string;
+}): Promise<CleanupResult>;
+/**
+ * One live bridge endpoint. Start/stop may cycle repeatedly on one instance;
+ * a fresh listener is built per start so a changed config reuses the class
+ * without re-allocation concerns. Exactly one extension link is held at a
+ * time; a newer WebSocket replaces the older one.
+ */
+export declare class BridgeServer {
+    private readonly options;
+    private httpServer;
+    private clientSocket;
+    private hello;
+    private connectedAt;
+    private readonly pending;
+    private lastError;
+    private continuationRemainder;
+    private continuationOpen;
+    constructor(options: BridgeServerOptions);
+    /** Current link state, also served verbatim as `/api/status`. */
+    get status(): BridgeServerStatus;
+    private get insecureToken();
+    /** Bind `127.0.0.1:<port>` and start accepting the extension plus HTTP calls. */
+    start(): Promise<void>;
+    /** Close the extension link, fail every pending command, and release the port. Idempotent. */
+    stop(): Promise<void>;
+    /**
+     * Send one command to the connected extension and await its result.
+     * Throws while no extension is linked; the rejection message names the fix.
+     */
+    execute(command: string, params: Record<string, unknown>, options?: BridgeExecuteOptions): Promise<unknown>;
+    /**
+     * Delete generated screenshots and agent scratch files via
+     * {@link cleanupArtifacts} using this server's configured directories.
+     */
+    cleanup(): Promise<CleanupResult>;
+    private log;
+    /**
+     * Mismatch description, or null when the two sides can talk. An older
+     * extension that declares nothing is treated as v1-compatible: it still
+     * answers every command this bridge has ever sent, so failing the link would
+     * break working installs for a cosmetic gap.
+     */
+    private get protocolNote();
+    /**
+     * Whether a request carries the bridge token, the same credential the WebSocket
+     * upgrade checks. Accepted forms: `Authorization: Bearer <token>`, `X-Token: <token>`
+     * and `?token=<token>` (the query form exists for curl and for the status page).
+     */
+    private authorized;
+    private rejectUnauthenticated;
+    private handleHttp;
+    private respondJson;
+    private handleCommandRequest;
+    private handleUpgrade;
+    private handleFrame;
+    private handleText;
+    private closeClientSocket;
+    private failAllPending;
+    private logVerbose;
+}