dsh-builtin-browser 0.1.7 → 0.1.9

package/lib/tool-browser/index.js

@@ -20,6 +20,8 @@ export const name = 'tool-browser';
 export const inject = ['tools', 'browser', 'systemPrompt'];
 /** Per-task browser sessions, keyed by the calling DSH session id. */
 const sessionsByTask = new Map();
+/** In-flight first-open per task key, so concurrent first calls share one session. */
+const pendingOpens = new Map();
 /**
  * Action restriction state: an allow-list of browser tool names, or undefined
  * for unrestricted. When set, any browser_* tool not in the list is refused
@@ -48,25 +50,29 @@ function taskKey(exec) {
 }
 /**
  * Resolve the calling task's browser session, opening one on first use.
+ * Concurrent first calls for the same key share a single open.
  * @param browser - the seam service.
  * @param key - the task key (see {@link taskKey}).
  * @returns the task's session id.
  */
 async function ensureSession(browser, key) {
-    let session = sessionsByTask.get(key);
-    if (session === undefined) {
-        session = await browser.open();
-        sessionsByTask.set(key, session);
-    }
-    return session;
+    const existing = sessionsByTask.get(key);
+    if (existing !== undefined)
+        return existing;
+    const pending = pendingOpens.get(key);
+    if (pending !== undefined)
+        return pending;
+    const opening = browser.open().then(session => { sessionsByTask.set(key, session); pendingOpens.delete(key); return session; }, error => { pendingOpens.delete(key); throw error; });
+    pendingOpens.set(key, opening);
+    return opening;
 }
-/** Coerce a tool-provided string value back to boolean/number when it looks like one. */
+/** Coerce a tool-provided string value back to boolean/number only when lossless. */
 function parseFillValue(v) {
     if (v === 'true')
         return true;
     if (v === 'false')
         return false;
-    if (v !== undefined && /^-?\d+(\.\d+)?$/.test(v))
+    if (v !== undefined && /^-?\d+(\.\d+)?$/.test(v) && String(Number(v)) === v)
         return Number(v);
     return v ?? '';
 }
@@ -84,8 +90,8 @@ function formatSnapshot(snapshot) {
 /** Register all browser tools with `ctx.tools`. */
 export function apply(ctx, config = {}) {
     const timeoutMs = config.timeoutMs ?? 60_000;
-    if (config.allowedActions !== undefined)
-        restrictedTo = [...config.allowedActions];
+    // Re-apply resets the restriction: an omitted allowedActions lifts it.
+    restrictedTo = config.allowedActions !== undefined ? [...config.allowedActions] : undefined;
     ctx.systemPrompt.section({
         name: 'tool:browser',
         // Tool guidance band is 100-199; 150 keeps clear of the common 110/120
@@ -107,6 +113,7 @@ export function apply(ctx, config = {}) {
                 properties: {
                     url: { type: 'string', required: true },
                     title: { type: 'string' },
+                    truncated: { type: 'boolean' },
                     elements: {
                         type: 'array',
                         required: true,
@@ -168,6 +175,7 @@ export function apply(ctx, config = {}) {
                 properties: {
                     url: { type: 'string', required: true },
                     title: { type: 'string' },
+                    truncated: { type: 'boolean' },
                     elements: {
                         type: 'array',
                         required: true,
@@ -546,6 +554,7 @@ export function apply(ctx, config = {}) {
             timeoutMs,
             isConcurrencySafe: () => true,
             async execute(args, exec) {
+                assertAllowed('browser_switch_tab');
                 const browser = ctx.get('browser');
                 if (browser === undefined)
                     throw new Error('tool-browser: browser service unavailable');
@@ -629,7 +638,11 @@ export function apply(ctx, config = {}) {
                     return [{ type: 'text', text: '(no recorded operations yet)' }];
                 return [{
                         type: 'text',
-                        text: entries.map(e => `#${e.seq} ${e.action} ${e.ok ? 'ok' : 'FAIL'} ${JSON.stringify(e.params)}${e.result !== undefined ? ` -> ${e.result}` : ''}${e.error !== undefined ? ` !! ${e.error}` : ''}`).join('\n'),
+                        text: entries.map(e => {
+                            const rawParams = JSON.stringify(e.params);
+                            const shownParams = rawParams.length > 300 ? rawParams.slice(0, 300) + '…' : rawParams;
+                            return `#${e.seq} ${e.action} ${e.ok ? 'ok' : 'FAIL'} ${shownParams}${e.result !== undefined ? ` -> ${e.result}` : ''}${e.error !== undefined ? ` !! ${e.error}` : ''}`;
+                        }).join('\n'),
                     }];
             },
         },
@@ -738,9 +751,7 @@ export function apply(ctx, config = {}) {
             const browser = ctx.get('browser');
             if (browser === undefined)
                 throw new Error('tool-browser: browser service unavailable');
-            const key = taskKey(exec);
-            const session = sessionsByTask.get(key) ?? await browser.open();
-            sessionsByTask.set(key, session);
+            const session = await ensureSession(browser, taskKey(exec));
             const tabs = await browser.listTabs(session);
             return { session, tabs: tabs.map(t => ({ id: t.id, url: t.url, active: t.active })) };
         },
@@ -763,8 +774,14 @@ export function apply(ctx, config = {}) {
             const key = taskKey(exec);
             const session = sessionsByTask.get(key);
             if (session !== undefined) {
-                await browser.close(session);
-                sessionsByTask.delete(key);
+                try {
+                    await browser.close(session);
+                }
+                finally {
+                    // Always forget the mapping so the next call opens a fresh session,
+                    // even if the provider close threw (the session is half-closed).
+                    sessionsByTask.delete(key);
+                }
             }
             return { reset: true };
         },
@@ -787,8 +804,15 @@ export function apply(ctx, config = {}) {
         isConcurrencySafe: () => false,
         async execute(args, exec) {
             // Always allowed so the guard can be lifted.
-            restrictedTo = (args.allowed ?? []).filter((t) => t.startsWith('browser_'));
-            return { restrictedTo: [...restrictedTo] };
+            const allowed = args.allowed ?? [];
+            const unknown = allowed.filter((t) => !t.startsWith('browser_'));
+            if (unknown.length > 0) {
+                throw new Error(`browser_restrict: unknown tool name(s) ${unknown.map(t => `"${t}"`).join(', ')} (must start with "browser_")`);
+            }
+            // Empty list (or omitted) lifts the restriction; a non-empty list is the
+            // new allow-list.
+            restrictedTo = allowed.length === 0 ? undefined : [...allowed];
+            return { restrictedTo: restrictedTo === undefined ? [] : [...restrictedTo] };
         },
     }));
     ctx.tools.register(defineTool({
@@ -829,8 +853,8 @@ export function apply(ctx, config = {}) {
 }
 /** Test hook: inspect and reset the plugin-level session map (used by tests). */
 export const internals = {
-    /** The per-task session map (task key -> provider session id). */
-    get sessions() { return sessionsByTask; },
+    /** A copy of the per-task session map (task key -> provider session id). */
+    get sessions() { return new Map(sessionsByTask); },
     /** Drop one task's mapping without closing the provider session. */
     clearSession(key = 'default') { sessionsByTask.delete(key); },
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-builtin-browser",
-  "version": "0.1.7",
-  "description": "Shared real browser capability for DeepSeek Harness: a visible browser the human watches and can take over, driven by the agent over CDP (snapshot/execute/content/tab management); host-side seam, provider, and browser_* tools",
+  "version": "0.1.9",
+  "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",
   "types": "lib/index.d.ts",

package/src/browser/runtime.ts

@@ -250,9 +250,21 @@ export class BrowserRuntime extends Service {
     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: BrowserSessionId): Promise<void> {
-    return this.resolveProvider().close(session)
+    try {
+      await this.resolveProvider().close(session)
+    } catch (error) {
+      const code = error instanceof BrowserError ? (error as { code?: string }).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
+    }
   }
 }
 

package/src/browser/types.ts

@@ -313,7 +313,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/src/browser-electron/entry.ts

@@ -49,10 +49,15 @@ export function apply(ctx: Context & { browser: BrowserRuntime }, config: 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: ElectronBrowserViewHost = 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/src/browser-electron/host-main.ts

@@ -59,11 +59,13 @@ async function handle(op: string, msg: { id: number; viewId?: string; method?: s
           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 })
@@ -86,7 +88,19 @@ async function handle(op: string, msg: { id: number; viewId?: string; method?: s
         const viewId = msg.viewId
         if (viewId === undefined) throw new Error('showView missing viewId')
         const entry = views.get(viewId)
-        if (entry !== undefined) entry.webContentsView.setVisible(true)
+        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
       }
@@ -220,6 +234,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.
 })
 

package/src/browser-electron/provider.ts

@@ -39,11 +39,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' }
@@ -114,8 +114,10 @@ interface Session {
   readonly id: BrowserSessionId
   readonly tabs: Tab[]
   activeIndex: number
-  /** Chronological operation log (navigate/execute/click/type/screenshot). */
+  /** Chronological operation log (navigate/execute/click/type/fill/download/auth). */
   readonly history: BrowserHistoryEntry[]
+  /** Monotonic sequence counter for history entries (survives truncation). */
+  nextSeq: number
 }
 
 /** Provider config: navigation admission defaults and snapshot caps. */
@@ -207,7 +209,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
   open(): Promise<BrowserSessionId> {
     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)
   }
 
@@ -302,15 +304,24 @@ export class ElectronBrowserProvider implements BrowserProvider {
         }
       }
       signal?.throwIfAborted()
-      const result = await handle.sendCommand(CDP_PAGE_NAVIGATE, { url } satisfies CdpNavigateParams)
+      // 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 } satisfies CdpNavigateParams),
+        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 as { errorText?: string }).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 as { code?: string }).code === 'BROWSER_NAVIGATION_BLOCKED')) {
         this.record(s, 'navigate', { url }, false, { error: String(error) })
@@ -362,9 +373,15 @@ export class ElectronBrowserProvider implements BrowserProvider {
         return { ok: false, exception }
       }
       const value = (result.result as { value?: unknown } | undefined)?.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 })
     }
   }
@@ -476,13 +493,15 @@ export class ElectronBrowserProvider implements BrowserProvider {
       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 as { ok: boolean; reason?: string; content?: string; truncated?: boolean }
     if (!value.ok) throw new BrowserError(`browser: content fetch failed: ${value.reason ?? 'unknown'}`, 'BROWSER_CONTENT_FAILED')
@@ -505,7 +524,9 @@ export class ElectronBrowserProvider implements BrowserProvider {
     const { handle } = this.activeTab(s)
     signal?.throwIfAborted()
     await handle.sendCommand('Input.insertText', { text: request.text } satisfies CdpInsertTextParams)
-    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)
   }
 
   /**
@@ -565,7 +586,15 @@ export class ElectronBrowserProvider implements BrowserProvider {
         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
@@ -625,7 +654,9 @@ export class ElectronBrowserProvider implements BrowserProvider {
       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 }
       }
@@ -710,7 +741,15 @@ export class ElectronBrowserProvider implements BrowserProvider {
       // 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')
@@ -739,7 +778,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
     detail?: { result?: string; error?: string },
   ): void {
     const entry: BrowserHistoryEntry = {
-      seq: s.history.length + 1,
+      seq: s.nextSeq++,
       action,
       params,
       ok,
@@ -796,8 +835,10 @@ export class ElectronBrowserProvider implements BrowserProvider {
       case 'execute': {
         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): a is string => 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:
@@ -872,7 +913,12 @@ function withTimeout<T>(
     const timer = setTimeout(() => {
       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: () => void): void => {
       if (done) return

package/src/browser-electron/remote-host.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 } |
@@ -159,10 +159,13 @@ class ElectronChildClient {
   private socket: import('node:net').Socket | undefined
   private connected = false
   private outbox: string[] = []
+  /** Set once the child has exited; further calls fail fast instead of queueing. */
+  private dead = false
 
   constructor(
     private readonly hostMainPath: string,
     private readonly port: number,
+    private readonly onExit?: () => void,
   ) {
     const electron = resolveElectronPath()
     // ELECTRON_RUN_AS_NODE (even an empty string) makes Electron run as plain
@@ -181,24 +184,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. */
+  private fail(err: Error): void {
+    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: import('node:net').Socket): void {
     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) {
@@ -232,6 +256,9 @@ class ElectronChildClient {
 
   /** Send one command and await the reply. */
   call<T = unknown>(op: string, payload: Record<string, unknown> = {}): Promise<T> {
+    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<T>((resolve, reject) => {
@@ -292,10 +319,11 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
   private pendingSocket: Socket | undefined
   private readonly views = new Map<string, ElectronViewHandle>()
   private readyPromise: Promise<void> | undefined
+  private disposed = false
 
   constructor(private readonly 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(): Promise<void> {
     if (this.readyPromise !== undefined) return this.readyPromise
     this.readyPromise = this.start()
@@ -312,10 +340,15 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
       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
@@ -324,6 +357,18 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
     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. */
+  private onChildExit(): void {
+    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(): ElectronViewHandle {
     // The seam is synchronous; the provider uses the handle immediately, so
     // commands are deferred until the child is up and the view materialized.
@@ -344,7 +389,11 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
   }
 
   showView(handle: ElectronViewHandle): void {
-    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(() => { /* host unavailable */ })
   }
 
   destroyView(handle: ElectronViewHandle): void {
@@ -358,6 +407,7 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
 
   /** Shut the child and the RPC server down. */
   dispose(): void {
+    this.disposed = true
     this.client?.kill()
     this.client = undefined
     this.server?.close()

package/src/index.ts

@@ -1,22 +1,26 @@
 /**
- * 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 {
+  BrowserChallenge,
   BrowserClickRequest,
   BrowserContentFormat,
   BrowserContentRequest,
   BrowserContentResult,
   BrowserExecuteRequest,
   BrowserExecuteResult,
+  BrowserFillField,
+  BrowserFillRequest,
+  BrowserFillResult,
   BrowserNavigateRequest,
   BrowserOpenRequest,
   BrowserProvider,
@@ -27,7 +31,9 @@ export type {
   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'