dsh-builtin-browser 0.3.0 → 0.3.1

package/README.en.md

@@ -232,7 +232,7 @@ agent (browser_* tools)
 
 - **Seam** (`browser` row): provides the `ctx.browser` service — provider registration, session lifecycle, error codes — decoupled from any implementation.
 - **Provider** (`browser-electron` row): operates views through the `ElectronBrowserViewHost` seam (create/destroy/show, `sendCommand`), implemented with real Electron objects by the shell.
-- **Tools** (`tool-browser` row): the 33 model-facing `browser_*` tools, maintaining one browser session per calling task (DSH session).
+- **Tools** (`tool-browser` row): the 34 model-facing `browser_*` tools, maintaining one browser session per calling task (DSH session).
 
 **Self-hosted mode**: without a desktop shell, the plugin spawns its own Electron child process (`host-main.js`) and drives it over loopback TCP JSON-RPC. The RPC is authenticated with a random per-spawn token delivered over **both stdin and an environment variable** — on Windows the Electron GUI process never receives piped stdin, so the env fallback keeps the handshake reliable. The child auto-restarts after a crash; the plugin prefers its own bundled electron package — packaged app executables (e.g. DSH Desktop.exe) are never reused as the spawnable binary, which would launch the app itself and exit immediately; screenshots prefer Electron's native `capturePage` (CDP capture can hang with multiple views in the window); the Electron lookup order follows below (33.x has a compositor defect; ≥ 40 recommended; the electron 44+ package no longer downloads its binary at install time — if it is missing on first use, the tool errors and tells you to run `npx install-electron` first, needs network).
 
@@ -242,7 +242,7 @@ agent (browser_* tools)
 
 ## Division of labor with the desktop shell
 
-There are three carriers, and the plugin picks one automatically — **no configuration**:
+The plugin picks a carrier automatically, and the setting can override it (four in total):
 
 **① Desktop: drive the official sidebar's page (one page for both parties)**
 
@@ -301,10 +301,10 @@ The settings panel can point the plugin at an **installed Chrome or Edge** (`bro
 
 | Component | Version |
 | --- | --- |
-| DeepSeek Harness (dsh) | `0.1.1-rc.2` (peer range `^0.1.1-rc.2`) |
+| DeepSeek Harness (dsh) | `0.2.0-rc.2` (peer range `>=0.1.1-rc.2 <0.3.0`) |
 | Electron | `44.0.0` (≥ 40 recommended; 33.x has a compositor defect) |
 | Node.js | `22.20.0` |
-| dsh-builtin-browser | `0.1.21` |
+| dsh-builtin-browser | `0.3.0` |
 | OS | Windows 10 (10.0.26200) |
 
 > The plugin declares `electron >= 30`; it has **only been verified on Windows** (macOS/Linux untested, not yet promised).
@@ -403,7 +403,7 @@ Code layout:
 | Round 20 addendum | 2026-10-01 | **Root cause of the invisible settings panel, plus crash diagnostics**: (1) On a real host the panel did not appear — the cause is that all three `cordis.patch.yml` rows were registered under **subpath** names (`dsh-builtin-browser/browser`), while the host's client-module scan resolves a row's specifier to a **package root** (`exactPackageSpecifier` returns `undefined` as soon as it sees a `/`), leaving the package with no row to read its `dsh.client` from. Fixed by adding an inert root row under the bare package name and giving the root entry `export const name` plus an empty `apply()`. Measured: boot entries 67 → **68**, the panel appears below "规则设定", and switches persist immediately. (2) Three host-log defects fixed: ISO timestamps, both paths plus their existence recorded before spawning, and a 2 MiB rotation that leaves a dated marker instead of wiping the file (which is how weeks of history vanished); the `exit` line gained `pid=` and `entryExists=` so "present at spawn, absent at exit" names an installation replaced underneath a running host. (3) Test pollution of the real log fixed: three spawn-based tests restored `DSH_HOME` in a `finally` while `dispose()` kills children asynchronously, so their synthetic exit lines landed in the operator's real log — now isolated at module scope. **70/70 tests** |
 | **0.2.0** | 2026-10-01 | **Release**: round 20 (persistent browsing history / the "Browser" settings section / synthetic cursor / teardown semantics) and its addendum ship as **0.2.0** — tool count **33 → 34** (new `browser_visited`), plus a new "Browser" section in Settings. Build clean, **70/70 tests pass**, tag `v0.2.0` |
 
-> The npm badge at the top is the authority on the registry's latest version: `0.1.23` is committed and tagged; if the badge still reads `0.1.22`, that version is not published yet.
+> The npm badge at the top is the authority on the registry's latest version. (was: `0.1.23` is committed and tagged; if the badge still reads `0.1.22`, that version is not published yet.
 
 ## Acknowledgements
 

package/README.md

@@ -236,13 +236,13 @@ agent (browser_* 工具)
 
 **自托管模式**:没有桌面外壳时,插件自己拉起一个 Electron 子进程(`host-main.js`),通过本机 TCP JSON-RPC 驱动。RPC 带随机 token 认证,token 经 **stdin + 环境变量双通道**传递——Windows 上 Electron 是 GUI 子系统进程、收不到 piped stdin,环境变量兜底保证握手稳定。子进程崩溃会自动重启;优先使用随插件安装的 electron 包(**打包应用如 DSH Desktop.exe 不会被误当作可复用二进制**,避免 spawn 秒退);截图优先走 Electron 原生 `capturePage`(CDP 截图在多视图下会挂起);Electron 的定位顺序见下(33.x 有合成器缺陷,建议 ≥ 40;44+ 的 electron 包不再随安装自动下载二进制,首次使用若缺失会按报错提示先 `npx install-electron`,需联网)。
 
-**自托管浏览器就是一台真正的浏览器**:每个任务(DSH 会话)拥有**独立的浏览器窗口**,窗口自带完整工具栏——地址栏、后退/前进/刷新按钮、标签条(新建/切换/关闭标签)。人可以直接像用 Chrome 一样使用它:在地址栏输入网址(自动补 `https://`)、点标签切换页面、开新标签;键盘焦点跟随点击——**点地址栏即可输入、点页面即可操作**(Windows 焦点路由,修复了点击不转移焦点导致地址栏无法输入的问题)。agent 与人的操作都汇入**同一个会话模型**(同一套标签、历史与导航),窗口标题实时显示当前任务标识与页面标题/URL,窗口缩放时视图自动跟随。任务结束后窗口随会话自动关闭。
+**自托管浏览器就是一台真正的浏览器**(Web 端、或没有桌面外壳时的形态):每个任务(DSH 会话)拥有**独立的浏览器窗口**,窗口自带完整工具栏——地址栏、后退/前进/刷新按钮、标签条(新建/切换/关闭标签)。人可以直接像用 Chrome 一样使用它:在地址栏输入网址(自动补 `https://`)、点标签切换页面、开新标签;键盘焦点跟随点击——**点地址栏即可输入、点页面即可操作**(Windows 焦点路由,修复了点击不转移焦点导致地址栏无法输入的问题)。agent 与人的操作都汇入**同一个会话模型**(同一套标签、历史与导航),窗口标题实时显示当前任务标识与页面标题/URL,窗口缩放时视图自动跟随。任务结束后窗口随会话自动关闭。
 
 **Electron 定位顺序**:① `ELECTRON_PATH`(显式覆盖,用户显式意图最优先)→ ② 随插件安装的 electron 包(纯文件系统探测,不触发 44+ 懒下载;覆盖 node_modules 与 pnpm store 两种布局)→ ③ DSH 安装锚点与 pnpm 虚拟仓库中**版本最新**者 → ④ 当前进程为**裸** Electron 时复用宿主二进制(开发模式)→ ⑤ 进程祖先树中的**裸** Electron 宿主(Windows 走 PowerShell CIM,仅最后手段)。**打包应用(如 `DSH Desktop.exe`)一律不复用**——它们不能按脚本参数拉起,误用会导致 spawn 秒退(issue #6);找不到时工具会报清晰的错误提示(含 `npx install-electron` 指引)。
 
 ## 与桌面外壳的分工
 
-有三种形态,插件会自动选择,**无需配置**:
+插件会自动选载体,也可以在设置里指定(共四种,见下):
 
 **① 桌面端:驱动官方侧栏的页面(人机同页)**
 
@@ -301,10 +301,11 @@ node desktop-bridge/install.mjs --revert   # 回滚
 
 | 组件 | 版本 |
 | --- | --- |
-| DeepSeek Harness(dsh) | `0.1.1-rc.2`(peer 声明 `^0.1.1-rc.2`) |
+| DeepSeek Harness(dsh) | `0.2.0-rc.2`(peer 声明 `>=0.1.1-rc.2 <0.3.0`) |
 | Electron | `44.0.0`(推荐 ≥ 40;33.x 存在合成器缺陷) |
 | Node.js | `22.20.0` |
-| dsh-builtin-browser | `0.1.21` |
+| 本机 Chrome / Edge(可选载体) | `154.0.8037.58` / `154.0.4258.37` |
+| dsh-builtin-browser | `0.3.0` |
 | 操作系统 | Windows 10 (10.0.26200) |
 
 > 插件声明 `electron >= 30`;**当前仅在 Windows 环境实测**(macOS/Linux 未验证,暂不承诺)。

package/lib/browser-electron/entry.js

@@ -90,31 +90,30 @@ export function apply(ctx, config) {
     // A browser the user explicitly asked for outranks every automatic choice: the
     // whole point of the setting is that they know which browser they want. It is
     // launched with a plugin-owned profile, so their own windows are untouched.
-    void (async () => {
-        const channel = settings.get().browser.channel;
-        if (channel === 'bundled')
-            return;
+    //
+    // Registration is INERT: constructing the host starts nothing. The browser only
+    // launches when a command actually needs a page, so merely running DSH never
+    // spawns a browser window. (An earlier version launched it here, which meant a
+    // browser appeared the moment the plugin loaded — reported and fixed.)
+    const channel = settings.get().browser.channel;
+    if (channel !== 'bundled') {
         const detected = detectBrowser(channel);
         if (detected === undefined) {
             ctx.logger?.warn?.(`dsh-builtin-browser: ${channel} was requested but no installation was found; using the bundled browser`);
-            return;
         }
-        const home = process.env.DSH_HOME ?? homedir();
-        // Login state lives in the browser profile, so the cookies setting decides where
-        // that profile goes: a stable directory keeps the user signed in across restarts
-        // (the point of using their own browser), while turning persistence off gets a
-        // throwaway directory that is removed when the browser is released.
-        const persist = settings.get().cookies.persist;
-        const profileDir = persist
-            ? join(home, 'dsh-builtin-browser-host', `${detected.kind}-profile`)
-            : join(home, 'dsh-builtin-browser-host', `${detected.kind}-profile-ephemeral-${randomUUID()}`);
-        const host = await SystemBrowserViewHost.launch(detected, profileDir, [], persist ? undefined : profileDir);
-        if (host === undefined) {
-            ctx.logger?.warn?.(`dsh-builtin-browser: ${detected.kind} did not start; using the bundled browser`);
-            return;
+        else {
+            const home = process.env.DSH_HOME ?? homedir();
+            // Login state lives in the browser profile, so the cookies setting decides where
+            // that profile goes: a stable directory keeps the user signed in across restarts
+            // (the point of using their own browser), while turning persistence off gets a
+            // throwaway directory that is removed when the browser is released.
+            const persist = settings.get().cookies.persist;
+            const profileDir = persist
+                ? join(home, 'dsh-builtin-browser-host', `${detected.kind}-profile`)
+                : join(home, 'dsh-builtin-browser-host', `${detected.kind}-profile-ephemeral-${randomUUID()}`);
+            adopt(new SystemBrowserViewHost(detected, profileDir, [], persist ? undefined : profileDir), `will drive the installed ${detected.kind} (${detected.path}${persist ? '' : ', ephemeral profile'})`);
         }
-        adopt(host, `driving the installed ${detected.kind} (${detected.path}${persist ? '' : ', ephemeral profile'})`);
-    })().catch(() => { });
+    }
     void DesktopBridgeViewHost.discover().then(sidebar => {
         // No bridge (plain `dsh web`, an older desktop build, or a shell that already
         // exited): keep self-hosting, which is what every surface has always done.

package/lib/browser-electron/system-browser.d.ts

@@ -46,30 +46,56 @@ export interface DetectedBrowser {
 export declare function detectBrowser(channel: BrowserChannel, env?: NodeJS.ProcessEnv): DetectedBrowser | undefined;
 /** A system browser driven over CDP, presented as a browser view host. */
 export declare class SystemBrowserViewHost implements ElectronBrowserViewHost {
-    private readonly child;
-    private readonly client;
-    readonly kind: DetectedBrowser['kind'];
+    private readonly browser;
+    private readonly profileDir;
+    private readonly extraArgs;
     private readonly ephemeralDir?;
     private readonly views;
     private disposed;
     /**
-     * @param child - the launched browser process.
-     * @param client - the CDP connection to it.
-     * @param kind - which product this is (for diagnostics).
-     * @param ephemeralDir - a throwaway profile to remove on release, when the user
-     *   has turned persistence off and no login state should outlive the session.
+     * The browser is started on FIRST USE, never on construction.
+     *
+     * A plugin that launches Chrome the moment its host loads is a plugin that takes
+     * over the machine before anyone asked it to: simply starting DSH would spawn a
+     * browser window. Registration must therefore be inert, and the process is only
+     * spawned when a view is actually needed.
      */
-    private constructor();
+    private client;
+    private child;
+    private starting;
     /**
-     * @param browser - the detected installation to launch.
+     * @param browser - the detected installation to launch on first use.
      * @param profileDir - a plugin-owned directory; the user's own profile is never touched.
      * @param extraArgs - additional Chromium switches.
-     * @param ephemeralDir - a directory to delete when the browser is released, used
-     *   when persistence is switched off so no login state outlives the session.
-     * @returns the host, or undefined when the browser refuses to come up.
+     * @param ephemeralDir - a directory to delete on release, when the user has turned
+     *   persistence off so no login state outlives the session.
+     */
+    constructor(browser: DetectedBrowser, profileDir: string, extraArgs?: readonly string[], ephemeralDir?: string | undefined);
+    /** Which product this host would drive (for diagnostics). */
+    get kind(): DetectedBrowser['kind'];
+    /** Whether the browser has actually been started yet (diagnostics and tests). */
+    get started(): boolean;
+    /**
+     * The CDP client, starting the browser on first use.
+     * @returns the connected client.
+     */
+    private ensureClient;
+    /**
+     * Launch the browser with a private profile and connect over CDP.
+     *
+     * `--remote-debugging-port=0` plus the `DevToolsActivePort` file is the only
+     * reliable way to learn the port: a fixed port collides with whatever else the
+     * machine is running, and parsing stderr is fragile across versions.
+     * @returns the connected client.
+     */
+    private start;
+    /**
+     * Whether this host can back views.
+     *
+     * True while the host is usable — including before the browser has been started,
+     * since the first command is what starts it. Reporting "unavailable" here would
+     * make the plugin fall back for no reason.
      */
-    static launch(browser: DetectedBrowser, profileDir: string, extraArgs?: readonly string[], ephemeralDir?: string): Promise<SystemBrowserViewHost | undefined>;
-    /** Whether this host can back views: the CDP connection is live. */
     available(): boolean;
     createView(): ElectronViewHandle;
     destroyView(handle: ElectronViewHandle): void;
@@ -91,7 +117,13 @@ export declare class SystemBrowserViewHost implements ElectronBrowserViewHost {
     onUserAction(): void;
     /** The browser reports its own window lifecycle. */
     onViewClosed(): void;
-    /** Close the browser we launched. The user's own windows are a different process. */
+    /**
+     * Close the browser we launched, if we ever launched one.
+     *
+     * The user's own windows belong to a different process and are never touched. A
+     * host whose browser was never started (the common case when nobody used the
+     * browser) simply tears down its bookkeeping.
+     */
     dispose(): void;
     /** The flattened session for a view, creating its page on first use. */
     private ensureSession;

package/lib/browser-electron/system-browser.js

@@ -155,37 +155,67 @@ class CdpClient {
 }
 /** A system browser driven over CDP, presented as a browser view host. */
 export class SystemBrowserViewHost {
-    child;
-    client;
-    kind;
+    browser;
+    profileDir;
+    extraArgs;
     ephemeralDir;
     views = new Map();
     disposed = false;
     /**
-     * @param child - the launched browser process.
-     * @param client - the CDP connection to it.
-     * @param kind - which product this is (for diagnostics).
-     * @param ephemeralDir - a throwaway profile to remove on release, when the user
-     *   has turned persistence off and no login state should outlive the session.
+     * The browser is started on FIRST USE, never on construction.
+     *
+     * A plugin that launches Chrome the moment its host loads is a plugin that takes
+     * over the machine before anyone asked it to: simply starting DSH would spawn a
+     * browser window. Registration must therefore be inert, and the process is only
+     * spawned when a view is actually needed.
      */
-    constructor(child, client, kind, ephemeralDir) {
-        this.child = child;
-        this.client = client;
-        this.kind = kind;
-        this.ephemeralDir = ephemeralDir;
-    }
+    client;
+    child;
+    starting;
     /**
-     * @param browser - the detected installation to launch.
+     * @param browser - the detected installation to launch on first use.
      * @param profileDir - a plugin-owned directory; the user's own profile is never touched.
      * @param extraArgs - additional Chromium switches.
-     * @param ephemeralDir - a directory to delete when the browser is released, used
-     *   when persistence is switched off so no login state outlives the session.
-     * @returns the host, or undefined when the browser refuses to come up.
+     * @param ephemeralDir - a directory to delete on release, when the user has turned
+     *   persistence off so no login state outlives the session.
      */
-    static async launch(browser, profileDir, extraArgs = [], ephemeralDir) {
+    constructor(browser, profileDir, extraArgs = [], ephemeralDir) {
+        this.browser = browser;
+        this.profileDir = profileDir;
+        this.extraArgs = extraArgs;
+        this.ephemeralDir = ephemeralDir;
+    }
+    /** Which product this host would drive (for diagnostics). */
+    get kind() {
+        return this.browser.kind;
+    }
+    /** Whether the browser has actually been started yet (diagnostics and tests). */
+    get started() {
+        return this.child !== undefined;
+    }
+    /**
+     * The CDP client, starting the browser on first use.
+     * @returns the connected client.
+     */
+    async ensureClient() {
+        if (this.client !== undefined)
+            return this.client;
+        // Concurrent first calls share one startup rather than racing two browsers.
+        this.starting ??= this.start().finally(() => { this.starting = undefined; });
+        return await this.starting;
+    }
+    /**
+     * Launch the browser with a private profile and connect over CDP.
+     *
+     * `--remote-debugging-port=0` plus the `DevToolsActivePort` file is the only
+     * reliable way to learn the port: a fixed port collides with whatever else the
+     * machine is running, and parsing stderr is fragile across versions.
+     * @returns the connected client.
+     */
+    async start() {
         const args = [
             '--remote-debugging-port=0',
-            `--user-data-dir=${profileDir}`,
+            `--user-data-dir=${this.profileDir}`,
             // Behave like a fresh, unattended browser: no first-run UI, no default-browser
             // prompt, no restore bubble, and no "Chrome is being controlled" infobar.
             '--no-first-run',
@@ -193,19 +223,23 @@ export class SystemBrowserViewHost {
             '--disable-features=Translate,MediaRouter',
             '--disable-session-crashed-bubble',
             '--hide-crash-restore-bubble',
-            ...extraArgs,
+            ...this.extraArgs,
             'about:blank',
         ];
-        const child = spawn(browser.path, args, { stdio: ['ignore', 'ignore', 'ignore'], windowsHide: false });
-        const portFile = join(profileDir, 'DevToolsActivePort');
+        const child = spawn(this.browser.path, args, { stdio: ['ignore', 'ignore', 'ignore'], windowsHide: false });
+        this.child = child;
+        const portFile = join(this.profileDir, 'DevToolsActivePort');
         const deadline = Date.now() + 30_000;
         for (;;) {
             if (Date.now() > deadline) {
                 child.kill();
-                return undefined;
+                this.child = undefined;
+                break;
+            }
+            if (child.exitCode !== null) {
+                this.child = undefined;
+                break;
             }
-            if (child.exitCode !== null)
-                return undefined;
             if (existsSync(portFile)) {
                 try {
                     const port = readFileSync(portFile, 'utf8').split('\n')[0]?.trim() ?? '';
@@ -214,7 +248,8 @@ export class SystemBrowserViewHost {
                         if (typeof version.webSocketDebuggerUrl === 'string') {
                             const client = new CdpClient(version.webSocketDebuggerUrl);
                             await client.whenReady();
-                            return new SystemBrowserViewHost(child, client, browser.kind, ephemeralDir);
+                            this.client = client;
+                            return client;
                         }
                     }
                 }
@@ -224,8 +259,15 @@ export class SystemBrowserViewHost {
             }
             await new Promise(resolve => setTimeout(resolve, 250));
         }
+        throw new Error(`dsh-builtin-browser: ${this.browser.kind} did not expose CDP within 30s (${this.browser.path})`);
     }
-    /** Whether this host can back views: the CDP connection is live. */
+    /**
+     * Whether this host can back views.
+     *
+     * True while the host is usable — including before the browser has been started,
+     * since the first command is what starts it. Reporting "unavailable" here would
+     * make the plugin fall back for no reason.
+     */
     available() {
         return !this.disposed;
     }
@@ -234,8 +276,9 @@ export class SystemBrowserViewHost {
         return {
             id: viewId,
             sendCommand: async (method, params) => {
+                const client = await this.ensureClient();
                 const session = this.views.get(viewId) ?? await this.ensureSession(viewId);
-                const result = await this.client.send(method, params, session);
+                const result = await client.send(method, params, session);
                 return (result ?? {});
             },
         };
@@ -249,7 +292,8 @@ export class SystemBrowserViewHost {
         // was attached to, which is why they are tracked separately.
         const targetId = this.sessions.get(session);
         this.sessions.delete(session);
-        if (targetId !== undefined) {
+        // Nothing to close if the browser was never started.
+        if (targetId !== undefined && this.client !== undefined) {
             // Best-effort: a page that is already gone is not an error.
             void this.client.send('Target.closeTarget', { targetId }).catch(() => undefined);
         }
@@ -269,7 +313,7 @@ export class SystemBrowserViewHost {
      */
     async focus() {
         try {
-            this.child.kill('SIGCONT');
+            this.child?.kill('SIGCONT');
         }
         catch { /* not supported on Windows; harmless */ }
     }
@@ -277,20 +321,26 @@ export class SystemBrowserViewHost {
     onUserAction() { }
     /** The browser reports its own window lifecycle. */
     onViewClosed() { }
-    /** Close the browser we launched. The user's own windows are a different process. */
+    /**
+     * Close the browser we launched, if we ever launched one.
+     *
+     * The user's own windows belong to a different process and are never touched. A
+     * host whose browser was never started (the common case when nobody used the
+     * browser) simply tears down its bookkeeping.
+     */
     dispose() {
         if (this.disposed)
             return;
         this.disposed = true;
         this.views.clear();
         this.sessions.clear();
-        this.client.close();
+        this.client?.close();
         try {
-            this.child.kill();
+            this.child?.kill();
         }
         catch { /* already gone */ }
         const ephemeral = this.ephemeralDir;
-        if (ephemeral !== undefined) {
+        if (ephemeral !== undefined && this.child !== undefined) {
             // The browser flushes its profile while shutting down, so deleting later avoids
             // racing it. Leftovers are only a stray temp directory, never a live credential.
             setTimeout(() => { try {
@@ -298,17 +348,25 @@ export class SystemBrowserViewHost {
             }
             catch { /* best effort */ } }, 3_000).unref?.();
         }
+        else if (ephemeral !== undefined) {
+            // Never started, so nothing can be holding it open.
+            try {
+                rmSync(ephemeral, { recursive: true, force: true });
+            }
+            catch { /* best effort */ }
+        }
     }
     /** The flattened session for a view, creating its page on first use. */
     async ensureSession(viewId) {
         const existing = this.views.get(viewId);
         if (existing !== undefined)
             return existing;
-        const created = await this.client.send('Target.createTarget', { url: 'about:blank' });
+        const client = await this.ensureClient();
+        const created = await client.send('Target.createTarget', { url: 'about:blank' });
         const targetId = created?.targetId;
         if (typeof targetId !== 'string')
             throw new Error('dsh-builtin-browser: the browser did not create a page');
-        const attached = await this.client.send('Target.attachToTarget', { targetId, flatten: true });
+        const attached = await client.send('Target.attachToTarget', { targetId, flatten: true });
         const sessionId = attached?.sessionId;
         if (typeof sessionId !== 'string')
             throw new Error('dsh-builtin-browser: the browser did not attach to the new page');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-builtin-browser",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Shared real browser plugin for DeepSeek Harness: install-and-use — a visible native browser the human can take over, driven by the agent over CDP. DOM-level interaction (React/Vue safe), per-task session isolation, cookie persistence (browser_auth), CAPTCHA detection, batch form fill (browser_fill), authenticated download, history/replay, action restriction",
   "type": "module",
   "main": "lib/index.js",

package/src/browser-electron/entry.ts

@@ -125,30 +125,30 @@ export function apply(ctx: Context & { browser: BrowserRuntime }, config: Config
   // A browser the user explicitly asked for outranks every automatic choice: the
   // whole point of the setting is that they know which browser they want. It is
   // launched with a plugin-owned profile, so their own windows are untouched.
-  void (async () => {
-    const channel = settings.get().browser.channel
-    if (channel === 'bundled') return
+  //
+  // Registration is INERT: constructing the host starts nothing. The browser only
+  // launches when a command actually needs a page, so merely running DSH never
+  // spawns a browser window. (An earlier version launched it here, which meant a
+  // browser appeared the moment the plugin loaded — reported and fixed.)
+  const channel = settings.get().browser.channel
+  if (channel !== 'bundled') {
     const detected = detectBrowser(channel)
     if (detected === undefined) {
       ctx.logger?.warn?.(`dsh-builtin-browser: ${channel} was requested but no installation was found; using the bundled browser`)
-      return
+    } else {
+      const home = process.env.DSH_HOME ?? homedir()
+      // Login state lives in the browser profile, so the cookies setting decides where
+      // that profile goes: a stable directory keeps the user signed in across restarts
+      // (the point of using their own browser), while turning persistence off gets a
+      // throwaway directory that is removed when the browser is released.
+      const persist = settings.get().cookies.persist
+      const profileDir = persist
+        ? join(home, 'dsh-builtin-browser-host', `${detected.kind}-profile`)
+        : join(home, 'dsh-builtin-browser-host', `${detected.kind}-profile-ephemeral-${randomUUID()}`)
+      adopt(new SystemBrowserViewHost(detected, profileDir, [], persist ? undefined : profileDir),
+        `will drive the installed ${detected.kind} (${detected.path}${persist ? '' : ', ephemeral profile'})`)
     }
-    const home = process.env.DSH_HOME ?? homedir()
-    // Login state lives in the browser profile, so the cookies setting decides where
-    // that profile goes: a stable directory keeps the user signed in across restarts
-    // (the point of using their own browser), while turning persistence off gets a
-    // throwaway directory that is removed when the browser is released.
-    const persist = settings.get().cookies.persist
-    const profileDir = persist
-      ? join(home, 'dsh-builtin-browser-host', `${detected.kind}-profile`)
-      : join(home, 'dsh-builtin-browser-host', `${detected.kind}-profile-ephemeral-${randomUUID()}`)
-    const host = await SystemBrowserViewHost.launch(detected, profileDir, [], persist ? undefined : profileDir)
-    if (host === undefined) {
-      ctx.logger?.warn?.(`dsh-builtin-browser: ${detected.kind} did not start; using the bundled browser`)
-      return
-    }
-    adopt(host, `driving the installed ${detected.kind} (${detected.path}${persist ? '' : ', ephemeral profile'})`)
-  })().catch(() => { /* the bundled browser stays in place */ })
+  }
 
   void DesktopBridgeViewHost.discover().then(sidebar => {
     // No bridge (plain `dsh web`, an older desktop build, or a shell that already

package/src/browser-electron/system-browser.ts

@@ -162,33 +162,65 @@ class CdpClient {
 export class SystemBrowserViewHost implements ElectronBrowserViewHost {
   private readonly views = new Map<string, string>()
   private disposed = false
+  /**
+   * The browser is started on FIRST USE, never on construction.
+   *
+   * A plugin that launches Chrome the moment its host loads is a plugin that takes
+   * over the machine before anyone asked it to: simply starting DSH would spawn a
+   * browser window. Registration must therefore be inert, and the process is only
+   * spawned when a view is actually needed.
+   */
+  private client: CdpClient | undefined
+  private child: ChildProcess | undefined
+  private starting: Promise<CdpClient> | undefined
 
   /**
-   * @param child - the launched browser process.
-   * @param client - the CDP connection to it.
-   * @param kind - which product this is (for diagnostics).
-   * @param ephemeralDir - a throwaway profile to remove on release, when the user
-   *   has turned persistence off and no login state should outlive the session.
+   * @param browser - the detected installation to launch on first use.
+   * @param profileDir - a plugin-owned directory; the user's own profile is never touched.
+   * @param extraArgs - additional Chromium switches.
+   * @param ephemeralDir - a directory to delete on release, when the user has turned
+   *   persistence off so no login state outlives the session.
    */
-  private constructor(
-    private readonly child: ChildProcess,
-    private readonly client: CdpClient,
-    readonly kind: DetectedBrowser['kind'],
+  constructor(
+    private readonly browser: DetectedBrowser,
+    private readonly profileDir: string,
+    private readonly extraArgs: readonly string[] = [],
     private readonly ephemeralDir?: string,
   ) {}
 
+  /** Which product this host would drive (for diagnostics). */
+  get kind(): DetectedBrowser['kind'] {
+    return this.browser.kind
+  }
+
+  /** Whether the browser has actually been started yet (diagnostics and tests). */
+  get started(): boolean {
+    return this.child !== undefined
+  }
+
   /**
-   * @param browser - the detected installation to launch.
-   * @param profileDir - a plugin-owned directory; the user's own profile is never touched.
-   * @param extraArgs - additional Chromium switches.
-   * @param ephemeralDir - a directory to delete when the browser is released, used
-   *   when persistence is switched off so no login state outlives the session.
-   * @returns the host, or undefined when the browser refuses to come up.
+   * The CDP client, starting the browser on first use.
+   * @returns the connected client.
    */
-  static async launch(browser: DetectedBrowser, profileDir: string, extraArgs: readonly string[] = [], ephemeralDir?: string): Promise<SystemBrowserViewHost | undefined> {
+  private async ensureClient(): Promise<CdpClient> {
+    if (this.client !== undefined) return this.client
+    // Concurrent first calls share one startup rather than racing two browsers.
+    this.starting ??= this.start().finally(() => { this.starting = undefined })
+    return await this.starting
+  }
+
+  /**
+   * Launch the browser with a private profile and connect over CDP.
+   *
+   * `--remote-debugging-port=0` plus the `DevToolsActivePort` file is the only
+   * reliable way to learn the port: a fixed port collides with whatever else the
+   * machine is running, and parsing stderr is fragile across versions.
+   * @returns the connected client.
+   */
+  private async start(): Promise<CdpClient> {
     const args = [
       '--remote-debugging-port=0',
-      `--user-data-dir=${profileDir}`,
+      `--user-data-dir=${this.profileDir}`,
       // Behave like a fresh, unattended browser: no first-run UI, no default-browser
       // prompt, no restore bubble, and no "Chrome is being controlled" infobar.
       '--no-first-run',
@@ -196,15 +228,16 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
       '--disable-features=Translate,MediaRouter',
       '--disable-session-crashed-bubble',
       '--hide-crash-restore-bubble',
-      ...extraArgs,
+      ...this.extraArgs,
       'about:blank',
     ]
-    const child = spawn(browser.path, args, { stdio: ['ignore', 'ignore', 'ignore'], windowsHide: false })
-    const portFile = join(profileDir, 'DevToolsActivePort')
+    const child = spawn(this.browser.path, args, { stdio: ['ignore', 'ignore', 'ignore'], windowsHide: false })
+    this.child = child
+    const portFile = join(this.profileDir, 'DevToolsActivePort')
     const deadline = Date.now() + 30_000
     for (;;) {
-      if (Date.now() > deadline) { child.kill(); return undefined }
-      if (child.exitCode !== null) return undefined
+      if (Date.now() > deadline) { child.kill(); this.child = undefined; break }
+      if (child.exitCode !== null) { this.child = undefined; break }
       if (existsSync(portFile)) {
         try {
           const port = readFileSync(portFile, 'utf8').split('\n')[0]?.trim() ?? ''
@@ -213,7 +246,8 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
             if (typeof version.webSocketDebuggerUrl === 'string') {
               const client = new CdpClient(version.webSocketDebuggerUrl)
               await client.whenReady()
-              return new SystemBrowserViewHost(child, client, browser.kind, ephemeralDir)
+              this.client = client
+              return client
             }
           }
         } catch {
@@ -222,9 +256,16 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
       }
       await new Promise(resolve => setTimeout(resolve, 250))
     }
+    throw new Error(`dsh-builtin-browser: ${this.browser.kind} did not expose CDP within 30s (${this.browser.path})`)
   }
 
-  /** Whether this host can back views: the CDP connection is live. */
+  /**
+   * Whether this host can back views.
+   *
+   * True while the host is usable — including before the browser has been started,
+   * since the first command is what starts it. Reporting "unavailable" here would
+   * make the plugin fall back for no reason.
+   */
   available(): boolean {
     return !this.disposed
   }
@@ -234,8 +275,9 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
     return {
       id: viewId,
       sendCommand: async (method: string, params?: Record<string, unknown>) => {
+        const client = await this.ensureClient()
         const session = this.views.get(viewId) ?? await this.ensureSession(viewId)
-        const result = await this.client.send(method, params, session)
+        const result = await client.send(method, params, session)
         return (result ?? {}) as Record<string, unknown>
       },
     }
@@ -249,7 +291,8 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
     // was attached to, which is why they are tracked separately.
     const targetId = this.sessions.get(session)
     this.sessions.delete(session)
-    if (targetId !== undefined) {
+    // Nothing to close if the browser was never started.
+    if (targetId !== undefined && this.client !== undefined) {
       // Best-effort: a page that is already gone is not an error.
       void this.client.send('Target.closeTarget', { targetId }).catch(() => undefined)
     }
@@ -272,7 +315,7 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
    * window, a locked session) is never worth an error.
    */
   async focus(): Promise<void> {
-    try { this.child.kill('SIGCONT') } catch { /* not supported on Windows; harmless */ }
+    try { this.child?.kill('SIGCONT') } catch { /* not supported on Windows; harmless */ }
   }
 
   /** The browser reports its own window lifecycle. */
@@ -281,19 +324,28 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
   /** The browser reports its own window lifecycle. */
   onViewClosed(): void {}
 
-  /** Close the browser we launched. The user's own windows are a different process. */
+  /**
+   * Close the browser we launched, if we ever launched one.
+   *
+   * The user's own windows belong to a different process and are never touched. A
+   * host whose browser was never started (the common case when nobody used the
+   * browser) simply tears down its bookkeeping.
+   */
   dispose(): void {
     if (this.disposed) return
     this.disposed = true
     this.views.clear()
     this.sessions.clear()
-    this.client.close()
-    try { this.child.kill() } catch { /* already gone */ }
+    this.client?.close()
+    try { this.child?.kill() } catch { /* already gone */ }
     const ephemeral = this.ephemeralDir
-    if (ephemeral !== undefined) {
+    if (ephemeral !== undefined && this.child !== undefined) {
       // The browser flushes its profile while shutting down, so deleting later avoids
       // racing it. Leftovers are only a stray temp directory, never a live credential.
       setTimeout(() => { try { rmSync(ephemeral, { recursive: true, force: true }) } catch { /* best effort */ } }, 3_000).unref?.()
+    } else if (ephemeral !== undefined) {
+      // Never started, so nothing can be holding it open.
+      try { rmSync(ephemeral, { recursive: true, force: true }) } catch { /* best effort */ }
     }
   }
 
@@ -301,10 +353,11 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
   private async ensureSession(viewId: string): Promise<string> {
     const existing = this.views.get(viewId)
     if (existing !== undefined) return existing
-    const created = await this.client.send('Target.createTarget', { url: 'about:blank' }) as { targetId?: string }
+    const client = await this.ensureClient()
+    const created = await client.send('Target.createTarget', { url: 'about:blank' }) as { targetId?: string }
     const targetId = created?.targetId
     if (typeof targetId !== 'string') throw new Error('dsh-builtin-browser: the browser did not create a page')
-    const attached = await this.client.send('Target.attachToTarget', { targetId, flatten: true }) as { sessionId?: string }
+    const attached = await client.send('Target.attachToTarget', { targetId, flatten: true }) as { sessionId?: string }
     const sessionId = attached?.sessionId
     if (typeof sessionId !== 'string') throw new Error('dsh-builtin-browser: the browser did not attach to the new page')
     // The session id is what page commands ride; the target id is what closes it.