dsh-builtin-browser 0.1.7 → 0.1.9

package/README.en.md

@@ -2,17 +2,35 @@
 
 中文 | [English](README.en.md)
 
-A shared real browser capability plugin for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): a visible browser the human watches and can take over, driven by the agent over CDP.
+A shared **real browser** capability plugin for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): install and it just works — the agent drives a real, visible browser over CDP that the human can watch and take over at any time. Human and agent operate the **very same page**.
 
-This plugin provides the **host-side capability** (browser seam, Electron CDP provider, `browser_*` model tools). The browser's **native view itself** is supplied by the host (a desktop shell) through `ctx.electronViewHost`; the plugin contains no browser UI.
+**Why this plugin**
+
+- **Install-and-use.** With a desktop shell the shell's embedded view is used; on plain `dsh web` the plugin **self-hosts** — it spawns its own Electron window with zero extra configuration.
+- **Real and visible, human-takeover friendly.** Not a headless screenshot or a relay: the user sees the page and can grab control directly.
+- **DOM-level driving, framework-friendly.** React/Vue controlled inputs fill reliably.
+- **Concurrency-safe.** Task-level browser session isolation — parallel tasks never fight over the page or pollute each other.
+- **Built for the real world.** CAPTCHA detection, login persistence, batch form filling, authenticated downloads, operation replay, and action restriction — all included.
 
 ## Features
 
+**Browser capability**
+
 - **Real view, not a relay.** The browser is a native view (`WebContentsView`) the human can see and operate directly; the agent drives the very same page. The view is provided by the host shell; the plugin drives it.
 - **DOM-referenced, not coordinate-guessing.** `browser_snapshot` returns numbered interactive elements; `browser_execute` runs JS in the page (native setters for framework inputs), so interaction works on React/Vue pages.
 - **Multi-tab sessions.** Open URLs in parallel tabs, list/switch/close/reset, all keeping state.
 - **Multi-format content.** Fetch pages as html / markdown / txt / json, scoped by selector, capped by length and timeout.
 
+**Engineering capability**
+
+- **Per-task isolation.** Each DSH task (session) gets its own browser session (own tabs and history); concurrent tasks never interfere, and calls within one task reuse the same session (`browser_session` / `browser_reset_session`).
+- **Login persistence.** `browser_auth` exports/restores cookies, so logins survive host restarts.
+- **CAPTCHA / bot-detection awareness.** Cloudflare, reCAPTCHA, hCaptcha, Turnstile and generic challenges are detected automatically (`browser_challenge`, and flagged in snapshots); instead of blindly retrying, the agent asks the human to complete it in the shared window.
+- **Batch form filling.** `browser_fill` sets many fields in one call — matched by selector/name/label, handling controlled inputs, selects, checkboxes and radio groups, with optional submit.
+- **Operation history & replay.** `browser_history` records operations; `browser_replay` re-runs one step.
+- **Authenticated downloads.** `browser_download` fetches a URL with the session's cookies straight to a local file.
+- **Safety restriction.** `browser_restrict` limits which browser actions are allowed, preventing stray clicks/navigation.
+
 ## Requirements
 
 - DeepSeek Harness (dsh) with the `web` profile
@@ -28,7 +46,7 @@ This plugin provides the **host-side capability** (browser seam, Electron CDP pr
 | DeepSeek Harness (dsh) | `0.1.0-rc.5` |
 | Electron | `43.4.0` |
 | Node.js | `22.20.0` |
-| dsh-builtin-browser | `0.1.3` |
+| dsh-builtin-browser | `0.1.7` |
 | OS | Windows 10 (10.0.26200) |
 
 > The plugin declares `electron >= 30`; other platforms (macOS/Linux) run the same protocol but were only verified on the Windows environment above.

package/README.md

@@ -2,17 +2,35 @@
 
 [English](README.en.md) | 中文
 
-面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的共享真实浏览器能力插件:一个用户可见、可随时接管的浏览器,由 agent 通过 CDP 驱动。
+面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的**共享真实浏览器**能力插件:装好即可用——agent 通过 CDP 驱动一个真实、可见、可随时人工接管的浏览器,人与 agent 操作的是**同一个页面**。
 
-本插件提供 **host 侧能力**(浏览器 seam、Electron CDP provider、`browser_*` 模型工具)。浏览器本身的**原生视图**由宿主(桌面外壳)通过 `ctx.electronViewHost` 提供;插件不包含浏览器界面 UI。
+**我们的优势**
+
+- **装好即用**:有桌面外壳时嵌入外壳视图;纯 `dsh web` 也能**自托管**拉起自己的 Electron 窗口,不需要任何额外配置。
+- **真实可见、人工可接管**:不是无头截屏或转播,用户随时能看到页面并直接接手操作。
+- **DOM 级驱动,框架友好**:React/Vue 受控组件也能可靠填写。
+- **并发安全**:任务级浏览器会话隔离,多个任务并行互不抢页面、不互相污染。
+- **面向真实世界**:人机验证识别、登录态持久化、批量填表、带登录态下载、操作回放、动作限制,一应俱全。
 
 ## 功能
 
+**浏览器能力**
+
 - **真实视图,而非转播。** 浏览器是原生视图(`WebContentsView`),用户可直接看到并操作;agent 驱动的是同一个页面。视图由宿主外壳提供,插件负责驱动。
 - **DOM 引用,而非猜坐标。** `browser_snapshot` 返回带编号的交互元素;`browser_execute` 在页面里执行 JS(框架输入用原生 setter),在 React/Vue 页面上也能可靠交互。
 - **多标签会话。** 并行打开 URL、查看/切换/关闭/重置标签,状态保持。
 - **多格式内容。** 以 html / markdown / txt / json 抓取页面,支持 selector 限定、长度与超时上限。
 
+**工程化能力**
+
+- **按任务隔离。** 每个 DSH 任务(会话)拥有独立的浏览器会话(独立标签页与历史),并发任务互不干扰;同一任务内多次调用复用同一会话(`browser_session` / `browser_reset_session`)。
+- **登录态持久化。** `browser_auth` 导出/恢复 cookie,重启后登录态不丢。
+- **人机验证识别。** 自动检测 Cloudflare / reCAPTCHA / hCaptcha / Turnstile 等挑战(`browser_challenge`,快照也会标注),提示人工在共享窗口完成,不再盲目重试。
+- **批量表单填充。** `browser_fill` 一次填写多个字段:按选择器/名称/标签匹配,支持受控输入、下拉、单选/复选,可选提交。
+- **操作历史与回放。** `browser_history` 记录操作日志,`browser_replay` 可回放某一步。
+- **带登录态下载。** `browser_download` 用会话 cookie 把文件取到本地,登录后内容可直接落盘。
+- **安全限制。** `browser_restrict` 限制允许的浏览器动作,防误点/误导航。
+
 ## 环境要求
 
 - DeepSeek Harness(dsh)且安装了 `web` profile
@@ -28,7 +46,7 @@
 | DeepSeek Harness(dsh) | `0.1.0-rc.5` |
 | Electron | `43.4.0` |
 | Node.js | `22.20.0` |
-| dsh-builtin-browser | `0.1.3` |
+| dsh-builtin-browser | `0.1.7` |
 | 操作系统 | Windows 10 (10.0.26200) |
 
 > 插件声明 `electron >= 30`;其他平台(如 macOS/Linux)按同一协议运行,但仅在上表 Windows 环境实测。

package/lib/browser/runtime.d.ts

@@ -94,7 +94,8 @@ export declare class BrowserRuntime extends Service {
     flushAuth(session: BrowserSessionId): Promise<readonly ExportedCookie[]>;
     /** Import cookies into the session through the provider. */
     restoreAuth(session: BrowserSessionId, cookies: readonly ExportedCookie[]): Promise<number>;
-    /** Close the session through the selected provider. Idempotent. */
+    /** Close the session through the selected provider. Idempotent; a missing
+     *  provider is treated as already-closed so teardown paths stay no-ops. */
     close(session: BrowserSessionId): Promise<void>;
 }
 export default BrowserRuntime;

package/lib/browser/runtime.js

@@ -158,9 +158,22 @@ export class BrowserRuntime extends Service {
     async restoreAuth(session, cookies) {
         return this.resolveProvider().restoreAuth(session, cookies);
     }
-    /** Close the session through the selected provider. Idempotent. */
+    /** Close the session through the selected provider. Idempotent; a missing
+     *  provider is treated as already-closed so teardown paths stay no-ops. */
     async close(session) {
-        return this.resolveProvider().close(session);
+        try {
+            await this.resolveProvider().close(session);
+        }
+        catch (error) {
+            const code = error instanceof BrowserError ? error.code : undefined;
+            if (code === 'BROWSER_PROVIDER_UNAVAILABLE'
+                || code === 'BROWSER_PROVIDER_CONFIGURED_MISSING'
+                || code === 'BROWSER_PROVIDER_CONFIGURED_UNAVAILABLE'
+                || code === 'BROWSER_PROVIDER_AMBIGUOUS') {
+                return; // provider gone; nothing to close
+            }
+            throw error;
+        }
     }
 }
 export default BrowserRuntime;

package/lib/browser/types.d.ts

@@ -294,7 +294,8 @@ export interface BrowserProvider {
 export interface BrowserHistoryEntry {
     /** Monotonic sequence number within the session. */
     readonly seq: number;
-    /** The operation name: navigate | execute | click | type | replay. */
+    /** The operation name. Replayable: navigate | execute | click | type.
+     *  Also recorded (non-replayable): fill | download | flushAuth | restoreAuth. */
     readonly action: string;
     /** The operation's arguments. */
     readonly params: Record<string, unknown>;

package/lib/browser-electron/entry.js

@@ -28,10 +28,15 @@ export function apply(ctx, config) {
     // External host (desktop shell) wins; otherwise self-host. The self-hosted
     // child is disposed with the fiber, mirroring the shell's lifetime.
     const host = config.viewHost ?? new RemoteElectronViewHost(defaultHostMainPath());
+    // Own the disposer on THIS plugin's fiber: registerBrowserProvider's effect
+    // is bound to the seam's own fiber (the browser row), so a reload of this
+    // row would otherwise collide with the still-registered provider
+    // (BROWSER_DUPLICATE_PROVIDER) or leave a stale provider behind.
+    const unregister = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(host, { httpOnly: config.httpOnly }));
     ctx.effect(() => () => {
+        unregister();
         if (config.viewHost === undefined && host instanceof RemoteElectronViewHost) {
             host.dispose();
         }
     });
-    ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(host, { httpOnly: config.httpOnly }));
 }

package/lib/browser-electron/host-main.js

@@ -48,11 +48,14 @@ async function handle(op, msg) {
                     window.on('closed', () => { window = undefined; });
                 }
                 const view = new WebContentsView();
+                // New views start hidden: with several sessions/tabs only the shown
+                // one may be visible (they stack in contentView child order).
                 view.setVisible(false);
                 window.contentView.addChildView(view);
                 const [width, height] = window.getContentSize();
                 view.setBounds({ x: 0, y: 0, width: width ?? 0, height: height ?? 0 });
-                view.setVisible(true);
+                if (views.size === 0)
+                    view.setVisible(true);
                 view.webContents.debugger.attach(CDP_VERSION);
                 views.set(viewId, { webContentsView: view });
                 reply(msg.id, { ok: true });
@@ -80,8 +83,23 @@ async function handle(op, msg) {
                 if (viewId === undefined)
                     throw new Error('showView missing viewId');
                 const entry = views.get(viewId);
-                if (entry !== undefined)
+                if (entry !== undefined) {
+                    // Hide every other view, then show and RAISE the target so the
+                    // human actually sees the active tab/session (topmost child wins).
+                    for (const v of views.values()) {
+                        if (v === entry)
+                            continue;
+                        try {
+                            v.webContentsView.setVisible(false);
+                        }
+                        catch { /* destroyed */ }
+                    }
                     entry.webContentsView.setVisible(true);
+                    if (window !== undefined) {
+                        window.contentView.removeChildView(entry.webContentsView);
+                        window.contentView.addChildView(entry.webContentsView);
+                    }
+                }
                 reply(msg.id, { ok: true });
                 return;
             }
@@ -228,6 +246,12 @@ void app.whenReady().then(() => {
     socket.on('error', error => {
         process.stderr.write(`[dsh-browser host] socket error: ${String(error)}\n`);
     });
+    // The parent owns our lifetime: when it closes the socket (dispose) or dies
+    // without cleanup, exit so no zombie Electron window is left behind.
+    socket.on('close', () => {
+        process.stderr.write('[dsh-browser host] parent connection closed, exiting\n');
+        app.exit(0);
+    });
     // Keep the process alive until the parent closes the socket or kills us.
 });
 // Diagnostics go to stderr, which the parent never parses as protocol.

package/lib/browser-electron/provider.js

@@ -21,11 +21,11 @@ const CHALLENGE_DETECT_EXPRESSION = `(() => {
   const lower = (title + '\\n' + bodyText).toLowerCase()
   const frameSrcs = [...document.querySelectorAll('iframe')].map(f => f.src || '').join(' ')
   const framesLower = frameSrcs.toLowerCase()
-  const hasCfInterstitial = /just a moment|checking your browser|attention required|cf_chl|challenge-platform/i.test(lower)
+  const hasCfInterstitial = /just a moment|checking your browser|attention required|cf_chl/i.test(lower)
     || !!document.querySelector('#challenge-running, #challenge-stage, #cf-chl-container')
   const hasHCaptcha = !!window.hcaptcha || !!document.querySelector('.h-captcha') || /hcaptcha\\.com/i.test(framesLower)
   const hasRecaptcha = !!window.grecaptcha || !!document.querySelector('.g-recaptcha') || /recaptcha\\/api|google\\.com\\/recaptcha/i.test(framesLower)
-  const hasTurnstile = !!window.turnstile || /challenges\\.cloudflare\\.com/i.test(framesLower) || /turnstile/i.test(lower)
+  const hasTurnstile = !!window.turnstile || /challenges\\.cloudflare\\.com/i.test(framesLower) || /turnstile|challenge-platform/i.test(lower)
   const verifyWording = /verify you are human|verify you are not a robot|\\u4eba\\u673a\\u9a8c\\u8bc1|\\u5b89\\u5168\\u9a8c\\u8bc1|enable javascript and cookies|\\u8bf7.*\\u9a8c\\u8bc1/i.test(lower)
   if (hasCfInterstitial) return { blocked: true, kind: 'cloudflare', reason: 'Cloudflare "Just a moment" interstitial' }
   if (hasHCaptcha) return { blocked: true, kind: 'hcaptcha', reason: 'hCaptcha verification' }
@@ -80,7 +80,7 @@ export class ElectronBrowserProvider {
     open() {
         const handle = this.host.createView();
         const id = `browser:${randomUUID()}`;
-        this.sessions.set(id, { id, tabs: [{ id: `tab:${randomUUID()}`, handle }], activeIndex: 0, history: [] });
+        this.sessions.set(id, { id, tabs: [{ id: `tab:${randomUUID()}`, handle }], activeIndex: 0, history: [], nextSeq: 1 });
         return Promise.resolve(id);
     }
     /** Open a URL in the active tab (default) or a new tab. */
@@ -175,15 +175,19 @@ export class ElectronBrowserProvider {
                 }
             }
             signal?.throwIfAborted();
-            const result = await handle.sendCommand(CDP_PAGE_NAVIGATE, { url });
+            // Page.navigate can hang on an unreachable/slow host; bound it like the
+            // evaluate paths so a wedged navigation surfaces as an error instead of
+            // blocking the tool call forever.
+            const timeoutMs = 30_000;
+            const result = await withTimeout(handle.sendCommand(CDP_PAGE_NAVIGATE, { url }), timeoutMs, signal, `browser: navigation timed out after ${timeoutMs}ms`);
             // Page.navigate resolves even when the navigation fails; surface the
             // failure instead of leaving a silent white screen.
             const errorText = result.errorText;
             if (typeof errorText === 'string' && errorText !== '') {
-                this.record(s, 'navigate', { url }, false, { error: errorText });
                 throw new BrowserError(`browser: navigation to "${url}" failed: ${errorText}`, 'BROWSER_NAVIGATION_FAILED');
             }
             this.record(s, 'navigate', { url }, true);
+            this.showActive(s);
         }
         catch (error) {
             if (!(error instanceof BrowserError && error.code === 'BROWSER_NAVIGATION_BLOCKED')) {
@@ -230,10 +234,16 @@ export class ElectronBrowserProvider {
                 return { ok: false, exception };
             }
             const value = result.result?.value ?? null;
-            this.record(s, 'execute', { script: request.script }, true, { result: typeof value === 'string' ? value.slice(0, 500) : JSON.stringify(value).slice(0, 500) });
+            this.record(s, 'execute', {
+                script: request.script,
+                ...request.args !== undefined && request.args.length > 0 ? { args: request.args } : {},
+            }, true, { result: typeof value === 'string' ? value.slice(0, 500) : JSON.stringify(value).slice(0, 500) });
             return { ok: true, value };
         }
         catch (error) {
+            if (error instanceof Error && error.name === 'TimeoutError') {
+                throw new BrowserError(`browser: execute timed out after ${request.timeoutMs ?? 30_000}ms`, 'BROWSER_EXECUTE_TIMEOUT', { cause: error });
+            }
             throw new BrowserError(`browser: execute failed: ${String(error)}`, 'BROWSER_EXECUTE_FAILED', { cause: error });
         }
     }
@@ -333,13 +343,10 @@ export class ElectronBrowserProvider {
       return { ok: true, content: content.slice(0, ${String(maxChars)}), truncated }
     })()`;
         // Honor a per-call timeout: content evaluation can hang on a heavy page,
-        // so a caller-supplied budget bounds it. AbortSignal.any merges the
-        // caller's signal with a timeout.
+        // so a caller-supplied budget bounds it. Unlike a bare signal entry check,
+        // withTimeout also interrupts a call already in flight.
         const timeoutMs = request.timeoutMs ?? 30_000;
-        const timeoutSignal = AbortSignal.timeout(timeoutMs);
-        const result = signal !== undefined
-            ? await handleSendEvaluate(tab.handle, script, AbortSignal.any([signal, timeoutSignal]))
-            : await handleSendEvaluate(tab.handle, script, timeoutSignal);
+        const result = await withTimeout(handleSendEvaluate(tab.handle, script), timeoutMs, signal, `browser: content timed out after ${timeoutMs}ms`);
         if (!result.ok)
             throw new BrowserError(`browser: content evaluation failed: ${result.exception}`, 'BROWSER_CONTENT_FAILED');
         const value = result.value;
@@ -362,7 +369,9 @@ export class ElectronBrowserProvider {
         const { handle } = this.activeTab(s);
         signal?.throwIfAborted();
         await handle.sendCommand('Input.insertText', { text: request.text });
-        this.record(s, 'type', { text: request.text.slice(0, 200) }, true);
+        // Store the full text so replay re-issues the same input; the history
+        // tool truncates long values when rendering.
+        this.record(s, 'type', { text: request.text }, true);
     }
     /**
      * Fill a form's fields in one batch. Runs one page-context script that
@@ -421,7 +430,15 @@ export class ElectronBrowserProvider {
         return vis.length > 0 ? vis : all
       }
       for (const spec of specs) {
-        const els = candidates(spec)
+        let els
+        try {
+          els = candidates(spec)
+        } catch (e) {
+          // A malformed selector must not abort the whole batch; report the
+          // field as failed and continue with the rest.
+          out.push({ ok: false, error: String(e), target: describe(spec) })
+          continue
+        }
         if (els.length === 0) { out.push({ ok: false, error: 'field not found', target: describe(spec) }); continue }
         const el = els[0]
         const tag = el.tagName
@@ -481,7 +498,9 @@ export class ElectronBrowserProvider {
       let submitted = false
       if (${submitFlag}) {
         let last = null
-        for (const spec of specs) { const els = candidates(spec); if (els.length > 0) { last = els[0]; break } }
+        for (const spec of specs) {
+          try { const els = candidates(spec); if (els.length > 0) { last = els[0]; break } } catch { /* skip */ }
+        }
         const form = last && (last.form || last.closest('form'))
         if (form) { form.requestSubmit(); submitted = true }
       }
@@ -553,7 +572,10 @@ export class ElectronBrowserProvider {
             // a clip this yields the full-page image (CDP default is the viewport).
             params.captureBeyondViewport = true;
         }
-        const result = await handle.sendCommand(CDP_PAGE_CAPTURE_SCREENSHOT, params);
+        // Bound the capture: a view that has not painted can wedge
+        // Page.captureScreenshot indefinitely (observed after view re-showing).
+        const timeoutMs = 30_000;
+        const result = await withTimeout(handle.sendCommand(CDP_PAGE_CAPTURE_SCREENSHOT, params), timeoutMs, signal, `browser: screenshot timed out after ${timeoutMs}ms`);
         const data = result.data;
         if (typeof data !== 'string') {
             throw new BrowserError('browser: screenshot returned no image data', 'BROWSER_SCREENSHOT_FAILED');
@@ -576,7 +598,7 @@ export class ElectronBrowserProvider {
     /** Append one operation to the session's history. */
     record(s, action, params, ok, detail) {
         const entry = {
-            seq: s.history.length + 1,
+            seq: s.nextSeq++,
             action,
             params,
             ok,
@@ -636,8 +658,10 @@ export class ElectronBrowserProvider {
                 const script = entry.params.script;
                 if (typeof script !== 'string')
                     throw new BrowserError(`browser: history seq ${seq} execute has no script`, 'BROWSER_HISTORY_INVALID');
-                const result = await this.execute(session, { script });
-                this.record(s, 'replay', { seq, of: entry.action, script }, result.ok, result.ok ? { result: String(result.value) } : { error: result.exception });
+                const recordedArgs = entry.params.args;
+                const args = Array.isArray(recordedArgs) ? recordedArgs.filter((a) => typeof a === 'string') : undefined;
+                const result = await this.execute(session, { script, ...args !== undefined && args.length > 0 ? { args } : {} });
+                this.record(s, 'replay', { seq, of: entry.action, script, ...args !== undefined && args.length > 0 ? { args } : {} }, result.ok, result.ok ? { result: String(result.value) } : { error: result.exception });
                 return;
             }
             default:
@@ -703,7 +727,13 @@ function withTimeout(promise, ms, signal, message) {
             if (done)
                 return;
             done = true;
-            reject(new Error(message));
+            // A fired timeout must also release the abort listener; { once: true }
+            // only releases it on the next abort, which may never come.
+            if (signal !== undefined)
+                signal.removeEventListener('abort', onAbort);
+            const error = new Error(message);
+            error.name = 'TimeoutError';
+            reject(error);
         }, ms);
         const finish = (fn) => {
             if (done)

package/lib/browser-electron/remote-host.d.ts

@@ -2,9 +2,9 @@
  * Self-hosted Electron browser host (parent side): an
  * {@link ElectronBrowserViewHost} implementation that spawns the plugin's own
  * Electron child process (host-main.js) and drives it over line-delimited
- * JSON-RPC on stdio. This is what makes the plugin work on surfaces without a
- * desktop shell's electronViewHost (plain dsh web): installing the plugin is
- * enough — the browser window appears on first use.
+ * JSON-RPC on a loopback TCP socket. This is what makes the plugin work on
+ * surfaces without a desktop shell's electronViewHost (plain dsh web):
+ * installing the plugin is enough — the browser window appears on first use.
  *
  * Protocol (one JSON object per line, both directions):
  *   -> { id, op: 'createView' } | { id, op: 'destroyView', viewId } |
@@ -28,10 +28,13 @@ export declare class RemoteElectronViewHost implements ElectronBrowserViewHost {
     private pendingSocket;
     private readonly views;
     private readyPromise;
+    private disposed;
     constructor(hostMainPath: string);
-    /** Ensure the child is up and ready (lazy on first use). */
+    /** Ensure the child is up and ready (lazy on first use; restarts after a crash). */
     private ready;
     private start;
+    /** The child died: tear down so the next use starts a fresh child. */
+    private onChildExit;
     createView(): ElectronViewHandle;
     private ensureView;
     showView(handle: ElectronViewHandle): void;

package/lib/browser-electron/remote-host.js

@@ -2,9 +2,9 @@
  * Self-hosted Electron browser host (parent side): an
  * {@link ElectronBrowserViewHost} implementation that spawns the plugin's own
  * Electron child process (host-main.js) and drives it over line-delimited
- * JSON-RPC on stdio. This is what makes the plugin work on surfaces without a
- * desktop shell's electronViewHost (plain dsh web): installing the plugin is
- * enough — the browser window appears on first use.
+ * JSON-RPC on a loopback TCP socket. This is what makes the plugin work on
+ * surfaces without a desktop shell's electronViewHost (plain dsh web):
+ * installing the plugin is enough — the browser window appears on first use.
  *
  * Protocol (one JSON object per line, both directions):
  *   -> { id, op: 'createView' } | { id, op: 'destroyView', viewId } |
@@ -147,6 +147,7 @@ function findElectronExe(store) {
 class ElectronChildClient {
     hostMainPath;
     port;
+    onExit;
     child;
     pending = new Map();
     nextId = 1;
@@ -154,9 +155,12 @@ class ElectronChildClient {
     socket;
     connected = false;
     outbox = [];
-    constructor(hostMainPath, port) {
+    /** Set once the child has exited; further calls fail fast instead of queueing. */
+    dead = false;
+    constructor(hostMainPath, port, onExit) {
         this.hostMainPath = hostMainPath;
         this.port = port;
+        this.onExit = onExit;
         const electron = resolveElectronPath();
         // ELECTRON_RUN_AS_NODE (even an empty string) makes Electron run as plain
         // Node, breaking require('electron'); NODE_OPTIONS can inject flags that
@@ -174,25 +178,45 @@ class ElectronChildClient {
             // Diagnostics only; never parse stderr as protocol.
             process.stderr.write(`[dsh-browser host] ${String(chunk)}`);
         });
+        // A failed spawn (bad/corrupt binary) emits 'error' — without a listener
+        // that would crash the whole DSH process.
+        this.child.on('error', error => {
+            process.stderr.write(`[dsh-browser host] spawn error: ${String(error)}\n`);
+            this.fail(new Error(`dsh-builtin-browser: browser host failed to start: ${String(error)}`));
+        });
         this.child.on('exit', (code, signal) => {
-            const err = new Error(`dsh-builtin-browser: browser host exited (code=${String(code)} signal=${String(signal)})`);
-            for (const pending of this.pending.values())
-                pending.reject(err);
-            this.pending.clear();
+            this.fail(new Error(`dsh-builtin-browser: browser host exited (code=${String(code)} signal=${String(signal)})`));
         });
     }
+    /** Reject everything in flight, mark the client dead, and notify the host. */
+    fail(err) {
+        if (this.dead)
+            return;
+        this.dead = true;
+        this.connected = false;
+        for (const pending of this.pending.values())
+            pending.reject(err);
+        this.pending.clear();
+        this.outbox = [];
+        this.onExit?.();
+    }
     /** Accept the child's connection (called by the server). */
     attach(socket) {
         this.socket = socket;
         this.connected = true;
         socket.setEncoding('utf8');
+        // Without an 'error' listener a remote reset (ECONNRESET/EPIPE) throws an
+        // uncaught 'error' event and crashes the whole DSH process; 'close' below
+        // does the cleanup.
+        socket.on('error', error => {
+            process.stderr.write(`[dsh-browser host] socket error: ${String(error)}\n`);
+        });
         socket.on('data', chunk => this.onData(chunk));
         socket.on('close', () => {
             this.connected = false;
-            const err = new Error('dsh-builtin-browser: browser host connection closed');
-            for (const pending of this.pending.values())
-                pending.reject(err);
-            this.pending.clear();
+            if (!this.dead) {
+                this.fail(new Error('dsh-builtin-browser: browser host connection closed'));
+            }
         });
         // Flush anything queued while disconnected.
         if (this.outbox.length > 0) {
@@ -231,6 +255,9 @@ class ElectronChildClient {
     }
     /** Send one command and await the reply. */
     call(op, payload = {}) {
+        if (this.dead) {
+            return Promise.reject(new Error('dsh-builtin-browser: browser host is not running'));
+        }
         const id = this.nextId++;
         const line = JSON.stringify({ id, op, ...payload });
         return new Promise((resolve, reject) => {
@@ -294,10 +321,11 @@ export class RemoteElectronViewHost {
     pendingSocket;
     views = new Map();
     readyPromise;
+    disposed = false;
     constructor(hostMainPath) {
         this.hostMainPath = hostMainPath;
     }
-    /** Ensure the child is up and ready (lazy on first use). */
+    /** Ensure the child is up and ready (lazy on first use; restarts after a crash). */
     ready() {
         if (this.readyPromise !== undefined)
             return this.readyPromise;
@@ -316,10 +344,15 @@ export class RemoteElectronViewHost {
             server.once('error', reject);
             server.listen(0, '127.0.0.1', () => resolve());
         });
+        // A later server error (rare on a loopback ephemeral port) must not crash
+        // the process; the client's fail path handles the actual recovery.
+        server.on('error', error => {
+            process.stderr.write(`[dsh-browser host] rpc server error: ${String(error)}\n`);
+        });
         const address = server.address();
         const port = typeof address === 'object' && address !== null ? address.port : 0;
         this.server = server;
-        this.client = new ElectronChildClient(this.hostMainPath, port);
+        this.client = new ElectronChildClient(this.hostMainPath, port, () => this.onChildExit());
         if (this.pendingSocket !== undefined) {
             this.client.attach(this.pendingSocket);
             this.pendingSocket = undefined;
@@ -327,6 +360,18 @@ export class RemoteElectronViewHost {
         // Wait for the child's connection + readiness ping.
         await withTimeout(this.client.call('ping'), READY_TIMEOUT_MS, 'browser host did not become ready');
     }
+    /** The child died: tear down so the next use starts a fresh child. */
+    onChildExit() {
+        if (this.disposed)
+            return;
+        this.client = undefined;
+        this.server?.close();
+        this.server = undefined;
+        this.pendingSocket = undefined;
+        this.readyPromise = undefined;
+        // Keep the views map: handles still resolve to ids; a fresh child simply
+        // has no such views yet, and reset_session reopens clean sessions.
+    }
     createView() {
         // The seam is synchronous; the provider uses the handle immediately, so
         // commands are deferred until the child is up and the view materialized.
@@ -346,7 +391,11 @@ export class RemoteElectronViewHost {
         return view;
     }
     showView(handle) {
-        void this.ready().then(() => this.client?.call('showView', { viewId: handle.id }));
+        // Fire-and-forget by design (visibility is best-effort), but a rejected
+        // promise must not become an unhandled rejection (crash on Node >= 15).
+        void this.ready()
+            .then(() => this.client?.call('showView', { viewId: handle.id }))
+            .catch(() => { });
     }
     destroyView(handle) {
         const view = this.views.get(handle.id);
@@ -359,6 +408,7 @@ export class RemoteElectronViewHost {
     }
     /** Shut the child and the RPC server down. */
     dispose() {
+        this.disposed = true;
         this.client?.kill();
         this.client = undefined;
         this.server?.close();

package/lib/index.d.ts

@@ -1,15 +1,16 @@
 /**
- * dsh-browser plugin entry: aggregates the shared-browser capability pieces.
- * The cordis.patch.yml rows reference subpath exports:
- *   - `dsh-browser/browser`            -> the ctx.browser seam (Service Definition)
- *   - `dsh-browser/browser-electron`   -> the Electron CDP provider
- *   - `dsh-browser/tool-browser`       -> the model-facing browser_* tools
+ * dsh-builtin-browser plugin entry: aggregates the shared-browser capability
+ * pieces. The cordis.patch.yml rows reference subpath exports:
+ *   - `dsh-builtin-browser/browser`          -> the ctx.browser seam (Service)
+ *   - `dsh-builtin-browser/browser-electron` -> the Electron CDP provider
+ *   - `dsh-builtin-browser/tool-browser`     -> the model-facing browser_* tools
  * This root entry only re-exports for programmatic use; the loader rows are
  * the composition surface.
- * @module dsh-browser
+ * @module dsh-builtin-browser
  */
 export { BrowserError } from './browser/types.ts';
-export type { BrowserClickRequest, BrowserContentFormat, BrowserContentRequest, BrowserContentResult, BrowserExecuteRequest, BrowserExecuteResult, BrowserNavigateRequest, BrowserOpenRequest, BrowserProvider, BrowserScreenshotRequest, BrowserScreenshotResult, BrowserSessionId, BrowserSnapshotElement, BrowserSnapshotResult, BrowserTab, BrowserTypeRequest, } from './browser/types.ts';
+export type { BrowserChallenge, BrowserClickRequest, BrowserContentFormat, BrowserContentRequest, BrowserContentResult, BrowserExecuteRequest, BrowserExecuteResult, BrowserFillField, BrowserFillRequest, BrowserFillResult, BrowserNavigateRequest, BrowserOpenRequest, BrowserProvider, BrowserScreenshotRequest, BrowserScreenshotResult, BrowserSessionId, BrowserSnapshotElement, BrowserSnapshotResult, BrowserTab, BrowserTypeRequest, ExportedCookie, } from './browser/types.ts';
 export { BrowserRuntime } from './browser/runtime.ts';
 export { ElectronBrowserProvider } from './browser-electron/provider.ts';
 export type { ElectronBrowserViewHost, ElectronViewHandle } from './browser-electron/provider.ts';
+export { RemoteElectronViewHost, defaultHostMainPath } from './browser-electron/remote-host.ts';

package/lib/index.js

@@ -1,13 +1,14 @@
 /**
- * dsh-browser plugin entry: aggregates the shared-browser capability pieces.
- * The cordis.patch.yml rows reference subpath exports:
- *   - `dsh-browser/browser`            -> the ctx.browser seam (Service Definition)
- *   - `dsh-browser/browser-electron`   -> the Electron CDP provider
- *   - `dsh-browser/tool-browser`       -> the model-facing browser_* tools
+ * dsh-builtin-browser plugin entry: aggregates the shared-browser capability
+ * pieces. The cordis.patch.yml rows reference subpath exports:
+ *   - `dsh-builtin-browser/browser`          -> the ctx.browser seam (Service)
+ *   - `dsh-builtin-browser/browser-electron` -> the Electron CDP provider
+ *   - `dsh-builtin-browser/tool-browser`     -> the model-facing browser_* tools
  * This root entry only re-exports for programmatic use; the loader rows are
  * the composition surface.
- * @module dsh-browser
+ * @module dsh-builtin-browser
  */
 export { BrowserError } from "./browser/types.js";
 export { BrowserRuntime } from "./browser/runtime.js";
 export { ElectronBrowserProvider } from "./browser-electron/provider.js";
+export { RemoteElectronViewHost, defaultHostMainPath } from "./browser-electron/remote-host.js";

package/lib/tool-browser/index.d.ts

@@ -32,7 +32,7 @@ export interface Config {
 export declare function apply(ctx: Context, config?: Config): void;
 /** Test hook: inspect and reset the plugin-level session map (used by tests). */
 export declare const internals: {
-    /** The per-task session map (task key -> provider session id). */
+    /** A copy of the per-task session map (task key -> provider session id). */
     readonly sessions: ReadonlyMap<string, BrowserSessionId>;
     /** Drop one task's mapping without closing the provider session. */
     clearSession(key?: string): void;