dsh-builtin-browser 0.1.5 → 0.1.7

package/lib/browser-electron/provider.js

@@ -1,13 +1,41 @@
 /**
  * Electron-backed browser provider: `WebContentsView` sessions driven over
- * `webContents.debugger` (CDP). The provider itself does not import Electron 鈥? * it operates through the {@link ElectronBrowserViewHost} seam, which the
+ * `webContents.debugger` (CDP). The provider itself does not import Electron — it operates through the {@link ElectronBrowserViewHost} seam, which the
  * desktop shell implements with real Electron objects. That keeps this
  * package testable under plain Node and leaves the Electron dependency to the
  * shell that owns the `BrowserWindow`.
  * @module dsh-browser/browser-electron
  */
 import { randomUUID } from 'node:crypto';
+import { writeFileSync } from 'node:fs';
 import { BrowserError } from "../browser/types.js";
+/**
+ * Page-context human-verification (CAPTCHA / bot-detection) detection. Runs
+ * inside the page; returns `{ blocked, kind?, reason? }`. Marker-based and
+ * best-effort: checks for Cloudflare's interstitial, hCaptcha, reCAPTCHA,
+ * Turnstile, and generic challenge wording.
+ */
+const CHALLENGE_DETECT_EXPRESSION = `(() => {
+  const title = (document.title || '').trim()
+  const bodyText = (document.body && document.body.innerText || '').slice(0, 4000)
+  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)
+    || !!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 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' }
+  if (hasRecaptcha) return { blocked: true, kind: 'recaptcha', reason: 'Google reCAPTCHA verification' }
+  if (hasTurnstile) return { blocked: true, kind: 'turnstile', reason: 'Cloudflare Turnstile verification' }
+  if (verifyWording && /challenge|captcha|verification|security check|access denied|blocked|\\u9a8c\\u8bc1/i.test(lower)) {
+    return { blocked: true, kind: 'generic', reason: 'Human-verification challenge' }
+  }
+  return { blocked: false }
+})()`;
 /** Stable provider id registered with `ctx.browser`. */
 export const ELECTRON_BROWSER_PROVIDER_ID = 'electron';
 /** CDP method for a full-page screenshot capture. */
@@ -43,20 +71,16 @@ export class ElectronBrowserProvider {
         return true;
     }
     /**
-     * Get the shared browser session: the one the host already owns, or a new
-     * one on first use. Shared-browser semantics (Cherry Studio's
-     * `getOrCreateWindow` pattern): the host's startup view and every later
-     * agent call must land on the SAME session and view, so opening again
-     * returns the existing session instead of creating a second view the human
-     * cannot see. Closing the session resets this; the next open starts fresh.
+     * Open a NEW browser session with its own view. Every call mints a fresh
+     * session id and backing view; per-task reuse is owned by the caller (the
+     * tool layer caches one session per DSH task). Sessions are isolated from
+     * each other: each keeps its own tabs, active tab, and history, and only
+     * the active tab of a session is made visible.
      */
     open() {
-        const [existing] = this.sessions.keys();
-        if (existing !== undefined)
-            return Promise.resolve(existing);
         const handle = this.host.createView();
         const id = `browser:${randomUUID()}`;
-        this.sessions.set(id, { id, tabs: [{ id: `tab:${randomUUID()}`, handle }], activeIndex: 0 });
+        this.sessions.set(id, { id, tabs: [{ id: `tab:${randomUUID()}`, handle }], activeIndex: 0, history: [] });
         return Promise.resolve(id);
     }
     /** Open a URL in the active tab (default) or a new tab. */
@@ -134,32 +158,44 @@ export class ElectronBrowserProvider {
     }
     /** Navigate the active tab's view to a URL, honoring HTTP(S)-only admission. */
     async navigate(session, request, signal) {
-        const { handle } = this.activeTab(this.session(session));
+        const s = this.session(session);
+        const { handle } = this.activeTab(s);
         const url = request.url;
-        if (this.httpOnly) {
-            let parsed;
-            try {
-                parsed = new URL(url);
-            }
-            catch {
-                throw new BrowserError(`browser: refusing navigation to unparseable URL "${url}"`, 'BROWSER_NAVIGATION_BLOCKED');
+        try {
+            if (this.httpOnly) {
+                let parsed;
+                try {
+                    parsed = new URL(url);
+                }
+                catch {
+                    throw new BrowserError(`browser: refusing navigation to unparseable URL "${url}"`, 'BROWSER_NAVIGATION_BLOCKED');
+                }
+                if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+                    throw new BrowserError(`browser: refusing navigation to non-HTTP(S) URL "${url}"`, 'BROWSER_NAVIGATION_BLOCKED');
+                }
             }
-            if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
-                throw new BrowserError(`browser: refusing navigation to non-HTTP(S) URL "${url}"`, 'BROWSER_NAVIGATION_BLOCKED');
+            signal?.throwIfAborted();
+            const result = await handle.sendCommand(CDP_PAGE_NAVIGATE, { url });
+            // 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);
         }
-        signal?.throwIfAborted();
-        const result = await handle.sendCommand(CDP_PAGE_NAVIGATE, { url });
-        // 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 !== '') {
-            throw new BrowserError(`browser: navigation to "${url}" failed: ${errorText}`, 'BROWSER_NAVIGATION_FAILED');
+        catch (error) {
+            if (!(error instanceof BrowserError && error.code === 'BROWSER_NAVIGATION_BLOCKED')) {
+                this.record(s, 'navigate', { url }, false, { error: String(error) });
+            }
+            throw error;
         }
     }
     /** Execute JS in the active tab's page context. */
     async execute(session, request, signal) {
-        const { handle } = this.activeTab(this.session(session));
+        const s = this.session(session);
+        const { handle } = this.activeTab(s);
         signal?.throwIfAborted();
         try {
             // Wrap the script in a Function so `return` statements are legal and
@@ -177,16 +213,25 @@ export class ElectronBrowserProvider {
             const expression = hasArgs
                 ? `(function(){ const __dshArgs = ${JSON.stringify(request.args)}; return Function(${JSON.stringify(body)}).apply(null, __dshArgs) })()`
                 : `(function(){ return Function(${JSON.stringify(body)})() })()`;
-            const result = await handle.sendCommand(CDP_RUNTIME_EVALUATE, {
+            // CDP Runtime.evaluate can hang indefinitely on a not-yet-loaded page
+            // (navigate returned but the renderer has not committed). Bound it so a
+            // stuck call surfaces as BROWSER_EXECUTE_TIMEOUT instead of wedging the
+            // whole tool call. The caller's signal wins when it fires first.
+            const timeoutMs = request.timeoutMs ?? 30_000;
+            const result = await withTimeout(handle.sendCommand(CDP_RUNTIME_EVALUATE, {
                 expression,
                 returnByValue: true,
                 awaitPromise: true,
-            });
+            }), timeoutMs, signal, `browser: execute timed out after ${timeoutMs}ms`);
             if (result.exceptionDetails !== undefined) {
                 const detail = result.exceptionDetails;
-                return { ok: false, exception: detail.exception?.description ?? detail.text ?? 'unknown exception' };
+                const exception = detail.exception?.description ?? detail.text ?? 'unknown exception';
+                this.record(s, 'execute', { script: request.script }, false, { error: exception });
+                return { ok: false, exception };
             }
-            return { ok: true, value: result.result?.value ?? null };
+            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) });
+            return { ok: true, value };
         }
         catch (error) {
             throw new BrowserError(`browser: execute failed: ${String(error)}`, 'BROWSER_EXECUTE_FAILED', { cause: error });
@@ -224,14 +269,31 @@ export class ElectronBrowserProvider {
           y: Math.round(r.y + r.height / 2),
         })
       }
-      return { url, title, elements: out, truncated: out.length >= cap }
+      const challenge = ${CHALLENGE_DETECT_EXPRESSION}
+      return { url, title, elements: out, truncated: out.length >= cap, challenge }
     })()`;
-        const result = await handleSendEvaluate(tab.handle, script);
+        // Same hang guard as execute: a renderer that has not committed after
+        // navigate would otherwise block snapshot forever.
+        const timeoutMs = 30_000;
+        const result = await withTimeout(handleSendEvaluate(tab.handle, script), timeoutMs, signal, `browser: snapshot timed out after ${timeoutMs}ms`);
         if (!result.ok)
             throw new BrowserError(`browser: snapshot evaluation failed: ${result.exception}`, 'BROWSER_SNAPSHOT_FAILED');
         const value = result.value;
         return value;
     }
+    /** Check whether a human-verification challenge is blocking the active tab. */
+    async detectChallenge(session, signal) {
+        const s = this.session(session);
+        const tab = this.activeTab(s);
+        signal?.throwIfAborted();
+        const timeoutMs = 15_000;
+        const result = await withTimeout(handleSendEvaluate(tab.handle, CHALLENGE_DETECT_EXPRESSION), timeoutMs, signal, `browser: challenge detection timed out after ${timeoutMs}ms`);
+        if (!result.ok) {
+            throw new BrowserError(`browser: challenge detection failed: ${result.exception}`, 'BROWSER_CHALLENGE_DETECT_FAILED');
+        }
+        const value = result.value;
+        return { blocked: value.blocked === true, kind: value.kind, reason: value.reason };
+    }
     /** Fetch page content in a requested format. */
     async content(session, request, signal) {
         const tab = this.activeTab(this.session(session));
@@ -287,16 +349,199 @@ export class ElectronBrowserProvider {
     }
     /** Click at viewport coordinates (CDP mousePressed + mouseReleased). */
     async click(session, request, signal) {
-        const { handle } = this.activeTab(this.session(session));
+        const s = this.session(session);
+        const { handle } = this.activeTab(s);
         signal?.throwIfAborted();
         await handle.sendCommand('Input.dispatchMouseEvent', { type: 'mousePressed', x: request.x, y: request.y, button: 'left', clickCount: 1 });
         await handle.sendCommand('Input.dispatchMouseEvent', { type: 'mouseReleased', x: request.x, y: request.y, button: 'left', clickCount: 1 });
+        this.record(s, 'click', { x: request.x, y: request.y }, true);
     }
     /** Type into the focused element. */
     async type(session, request, signal) {
-        const { handle } = this.activeTab(this.session(session));
+        const s = this.session(session);
+        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);
+    }
+    /**
+     * Fill a form's fields in one batch. Runs one page-context script that
+     * resolves each field (selector, or name/label/placeholder among visible
+     * controls), sets its value with the native prototype setter (React/Vue
+     * controlled inputs included) plus input/change events, handles
+     * select/checkbox/radio/contenteditable, and optionally submits the form.
+     */
+    async fillForm(session, request, signal) {
+        const s = this.session(session);
+        const tab = this.activeTab(s);
+        signal?.throwIfAborted();
+        const specs = JSON.stringify(request.fields.map(f => ({
+            selector: f.selector ?? null,
+            name: f.name ?? null,
+            label: f.label ?? null,
+            placeholder: f.placeholder ?? null,
+            kind: f.kind ?? 'text',
+            value: f.value,
+        })));
+        const submitFlag = request.submit === true;
+        const script = `(() => {
+      const specs = ${specs}
+      const out = []
+      const setNative = (el, proto, value) => {
+        const setter = Object.getOwnPropertyDescriptor(proto, 'value')?.set
+        if (setter) setter.call(el, value)
+        else el.value = value
+      }
+      const visible = (el) => {
+        const r = el.getBoundingClientRect()
+        const cs = getComputedStyle(el)
+        return r.width >= 4 && r.height >= 4 && cs.visibility !== 'hidden' && cs.display !== 'none'
+      }
+      const describe = (spec) => spec.selector || spec.name || spec.label || spec.placeholder || '(unspecified)'
+      const matches = (el, spec) => {
+        if (spec.selector) { try { return el.matches(spec.selector) } catch { return false } }
+        if (spec.name && el.name === spec.name) return true
+        if (spec.placeholder && el.placeholder === spec.placeholder) return true
+        if (spec.label) {
+          if (el.getAttribute('aria-label') === spec.label) return true
+          if (el.id) {
+            const lbl = document.querySelector('label[for=' + JSON.stringify(el.id) + ']')
+            if (lbl && (lbl.textContent || '').trim() === spec.label) return true
+          }
+          const wrap = el.closest('label')
+          if (wrap && (wrap.textContent || '').trim() === spec.label) return true
+        }
+        return false
+      }
+      const candidates = (spec) => {
+        const all = spec.selector
+          ? [...document.querySelectorAll(spec.selector)]
+          : [...document.querySelectorAll('input, textarea, select, [contenteditable="true"]')].filter(el => matches(el, spec))
+        const vis = all.filter(visible)
+        return vis.length > 0 ? vis : all
+      }
+      for (const spec of specs) {
+        const els = candidates(spec)
+        if (els.length === 0) { out.push({ ok: false, error: 'field not found', target: describe(spec) }); continue }
+        const el = els[0]
+        const tag = el.tagName
+        const type = (el.type || '').toLowerCase()
+        try {
+          if (tag === 'SELECT') {
+            const wanted = String(spec.value)
+            if (el.multiple) {
+              const wantedList = wanted.split(',').map(x => x.trim())
+              let hit = false
+              for (const o of [...el.options]) {
+                o.selected = wantedList.includes(o.value) || wantedList.includes((o.textContent || '').trim())
+                if (o.selected) hit = true
+              }
+              if (!hit) { out.push({ ok: false, error: 'option not found: ' + wanted, target: describe(spec) }); continue }
+            } else {
+              let opt = [...el.options].find(o => o.value === wanted)
+              if (!opt) opt = [...el.options].find(o => (o.textContent || '').trim() === wanted)
+              if (!opt) { out.push({ ok: false, error: 'option not found: ' + wanted, target: describe(spec) }); continue }
+              setNative(el, HTMLSelectElement.prototype, opt.value)
+            }
+            el.dispatchEvent(new Event('input', { bubbles: true }))
+            el.dispatchEvent(new Event('change', { bubbles: true }))
+            out.push({ ok: true, method: 'select', target: describe(spec) })
+          } else if (type === 'file') {
+            out.push({ ok: false, error: 'file inputs cannot be set from script; use browser_download or ask the human', target: describe(spec) })
+          } else if (type === 'checkbox') {
+            const want = spec.value === true || spec.value === 'true' || spec.value === 'on'
+            if (el.checked !== want) el.click()
+            out.push({ ok: true, method: 'checkbox', target: describe(spec) })
+          } else if (type === 'radio') {
+            const wanted = String(spec.value)
+            const radio = [...document.querySelectorAll('input[type="radio"][name=' + JSON.stringify(el.name || '') + ']')]
+              .find(r => r.value === wanted || (r === el && (spec.value === true || spec.value === 'true')))
+            if (!radio) { out.push({ ok: false, error: 'radio option not found: ' + wanted, target: describe(spec) }); continue }
+            if (!radio.checked) radio.click()
+            out.push({ ok: true, method: 'radio', target: describe(spec) })
+          } else if (el.isContentEditable) {
+            el.textContent = String(spec.value)
+            el.dispatchEvent(new Event('input', { bubbles: true }))
+            out.push({ ok: true, method: 'contenteditable', target: describe(spec) })
+          } else if (tag === 'TEXTAREA') {
+            setNative(el, HTMLTextAreaElement.prototype, String(spec.value))
+            el.dispatchEvent(new Event('input', { bubbles: true }))
+            el.dispatchEvent(new Event('change', { bubbles: true }))
+            out.push({ ok: true, method: 'textarea', target: describe(spec) })
+          } else {
+            setNative(el, HTMLInputElement.prototype, String(spec.value))
+            el.dispatchEvent(new Event('input', { bubbles: true }))
+            el.dispatchEvent(new Event('change', { bubbles: true }))
+            out.push({ ok: true, method: 'input', target: describe(spec) })
+          }
+        } catch (e) {
+          out.push({ ok: false, error: String(e), target: describe(spec) })
+        }
+      }
+      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 } }
+        const form = last && (last.form || last.closest('form'))
+        if (form) { form.requestSubmit(); submitted = true }
+      }
+      return { fields: out, submitted }
+    })()`;
+        const timeoutMs = request.timeoutMs ?? 30_000;
+        const result = await withTimeout(handleSendEvaluate(tab.handle, script), timeoutMs, signal, `browser: fillForm timed out after ${timeoutMs}ms`);
+        if (!result.ok) {
+            throw new BrowserError(`browser: fillForm evaluation failed: ${result.exception}`, 'BROWSER_FILL_FAILED');
+        }
+        const value = result.value;
+        const okCount = value.fields.filter(f => f.ok).length;
+        this.record(s, 'fill', { fields: request.fields.length, submit: submitFlag }, okCount === value.fields.length, {
+            result: `${okCount}/${value.fields.length} fields filled${value.submitted ? ', form submitted' : ''}`,
+        });
+        return { fields: value.fields, submitted: value.submitted === true };
+    }
+    /**
+     * Download a URL to a local file, keeping the session's cookies/login.
+     * Requires the self-hosted host (which implements view-level download); the
+     * desktop shell's embedded views delegate downloads to the real browser UI.
+     */
+    async download(session, request, signal) {
+        const s = this.session(session);
+        const { handle } = this.activeTab(s);
+        signal?.throwIfAborted();
+        const downloadable = handle;
+        if (typeof downloadable.download !== 'function') {
+            throw new BrowserError('browser: download is only available on the self-hosted browser', 'BROWSER_DOWNLOAD_UNSUPPORTED');
+        }
+        await downloadable.download(request.url, request.savePath);
+        this.record(s, 'download', { url: request.url, savePath: request.savePath }, true, { result: request.savePath });
+        return { path: request.savePath };
+    }
+    /**
+     * Export the session's cookies (login state) as serializable objects.
+     * Self-hosted only; the desktop shell's embedded views use the real profile.
+     */
+    async flushAuth(session) {
+        const s = this.session(session);
+        const { handle } = this.activeTab(s);
+        const host = handle;
+        if (typeof host.flushAuth !== 'function') {
+            throw new BrowserError('browser: auth export is only available on the self-hosted browser', 'BROWSER_AUTH_UNSUPPORTED');
+        }
+        const cookies = await host.flushAuth();
+        this.record(s, 'flushAuth', {}, true, { result: `${cookies.length} cookies` });
+        return cookies;
+    }
+    /** Import cookies into the session (restore login state). Self-hosted only. */
+    async restoreAuth(session, cookies) {
+        const s = this.session(session);
+        const { handle } = this.activeTab(s);
+        const host = handle;
+        if (typeof host.restoreAuth !== 'function') {
+            throw new BrowserError('browser: auth restore is only available on the self-hosted browser', 'BROWSER_AUTH_UNSUPPORTED');
+        }
+        const restored = await host.restoreAuth(cookies);
+        this.record(s, 'restoreAuth', { count: cookies.length }, true, { result: `${restored} cookies` });
+        return restored;
     }
     /** Capture the current page, optionally full-page. PNG only (CDP JPEG hangs on Electron 43). */
     async screenshot(session, request, signal) {
@@ -313,8 +558,92 @@ export class ElectronBrowserProvider {
         if (typeof data !== 'string') {
             throw new BrowserError('browser: screenshot returned no image data', 'BROWSER_SCREENSHOT_FAILED');
         }
+        // Optional disk write so a vision tool (e.g. modlens read_image) can read
+        // the screenshot from a file path. Fire-and-forget: a write failure must
+        // not fail the capture.
+        if (request?.savePath !== undefined) {
+            try {
+                writeFileSync(request.savePath, Buffer.from(data, 'base64'));
+                return { dataUrl: `data:image/png;base64,${data}`, path: request.savePath };
+            }
+            catch (error) {
+                // Report the write problem but keep the capture usable.
+                throw new BrowserError(`browser: screenshot save to "${request.savePath}" failed: ${String(error)}`, 'BROWSER_SCREENSHOT_SAVE_FAILED', { cause: error });
+            }
+        }
         return { dataUrl: `data:image/png;base64,${data}` };
     }
+    /** Append one operation to the session's history. */
+    record(s, action, params, ok, detail) {
+        const entry = {
+            seq: s.history.length + 1,
+            action,
+            params,
+            ok,
+            ...detail?.result !== undefined ? { result: detail.result } : {},
+            ...detail?.error !== undefined ? { error: detail.error } : {},
+            at: Date.now(),
+        };
+        s.history.push(entry);
+        // Bound memory: keep the last 500 operations.
+        if (s.history.length > 500)
+            s.history.splice(0, s.history.length - 500);
+    }
+    /** Return the session's chronological operation log (newest last). */
+    async history(session) {
+        return this.session(session).history;
+    }
+    /**
+     * Replay one recorded operation by sequence number. Navigate/click/type are
+     * re-issued against the current page; execute re-runs its script. The
+     * replayed step is appended to history as a new entry.
+     * @param session - the session id.
+     * @param seq - the recorded entry's sequence number to replay.
+     */
+    async replay(session, seq) {
+        const s = this.session(session);
+        const entry = s.history.find(e => e.seq === seq);
+        if (entry === undefined) {
+            throw new BrowserError(`browser: no history entry with seq ${seq}`, 'BROWSER_HISTORY_UNKNOWN');
+        }
+        switch (entry.action) {
+            case 'navigate': {
+                const url = entry.params.url;
+                if (typeof url !== 'string')
+                    throw new BrowserError(`browser: history seq ${seq} navigate has no url`, 'BROWSER_HISTORY_INVALID');
+                await this.navigate(session, { url });
+                this.record(s, 'replay', { seq, of: entry.action, url }, true);
+                return;
+            }
+            case 'click': {
+                const x = entry.params.x;
+                const y = entry.params.y;
+                if (typeof x !== 'number' || typeof y !== 'number')
+                    throw new BrowserError(`browser: history seq ${seq} click has no coordinates`, 'BROWSER_HISTORY_INVALID');
+                await this.click(session, { x, y });
+                this.record(s, 'replay', { seq, of: entry.action, x, y }, true);
+                return;
+            }
+            case 'type': {
+                const text = entry.params.text;
+                if (typeof text !== 'string')
+                    throw new BrowserError(`browser: history seq ${seq} type has no text`, 'BROWSER_HISTORY_INVALID');
+                await this.type(session, { text });
+                this.record(s, 'replay', { seq, of: entry.action, text }, true);
+                return;
+            }
+            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 });
+                return;
+            }
+            default:
+                throw new BrowserError(`browser: history seq ${seq} action "${entry.action}" is not replayable`, 'BROWSER_HISTORY_NOT_REPLAYABLE');
+        }
+    }
     /** Close the session and destroy all its views. Idempotent. */
     close(session) {
         const existing = this.sessions.get(session);
@@ -357,6 +686,46 @@ export class ElectronBrowserProvider {
         return result.ok && typeof result.value === 'string' ? result.value : '';
     }
 }
+/**
+ * Bound a promise so a wedged CDP call surfaces as an error instead of
+ * hanging the tool call forever. The caller's signal, when provided, wins
+ * over the timeout if it fires first.
+ * @param promise - the operation to bound.
+ * @param ms - the timeout budget.
+ * @param signal - optional caller signal.
+ * @param message - the timeout error message.
+ * @returns the promise's value, or a rejected promise on timeout/abort.
+ */
+function withTimeout(promise, ms, signal, message) {
+    return new Promise((resolve, reject) => {
+        let done = false;
+        const timer = setTimeout(() => {
+            if (done)
+                return;
+            done = true;
+            reject(new Error(message));
+        }, ms);
+        const finish = (fn) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            if (signal !== undefined)
+                signal.removeEventListener('abort', onAbort);
+            fn();
+        };
+        const onAbort = () => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            reject(signal?.reason instanceof Error ? signal.reason : new Error('aborted'));
+        };
+        if (signal !== undefined)
+            signal.addEventListener('abort', onAbort, { once: true });
+        promise.then(value => finish(() => resolve(value)), error => finish(() => reject(error)));
+    });
+}
 /**
  * Run a `Runtime.evaluate` through a view handle and normalize the result.
  * Shared by execute, snapshot, content, and internal URL reads.

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

@@ -17,7 +17,7 @@
  */
 import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
-import { existsSync, readdirSync } from 'node:fs';
+import { existsSync, readdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { createServer } from 'node:net';
 import { fileURLToPath } from 'node:url';
@@ -268,6 +268,19 @@ class RemoteView {
             params: params ?? {},
         });
     }
+    /** Ask the child to download a URL to a local file (keeps cookies/login). */
+    async download(url, savePath) {
+        const result = await this.client.call('download', { viewId: this.id, url, savePath });
+        writeFileSync(savePath, Buffer.from(result.base64, 'base64'));
+    }
+    /** Export the session's cookies (login state). */
+    flushAuth() {
+        return this.client.call('flushAuth', { viewId: this.id }).then(r => r.cookies);
+    }
+    /** Import cookies into the session (restore login state). */
+    restoreAuth(cookies) {
+        return this.client.call('restoreAuth', { viewId: this.id, cookies }).then(r => r.restored);
+    }
 }
 /**
  * Self-hosted view host: spawns the plugin's Electron child on first use and
@@ -358,14 +371,34 @@ export class RemoteElectronViewHost {
 class DeferredRemoteView {
     id;
     materialize;
+    materialized;
     constructor(id, materialize) {
         this.id = id;
         this.materialize = materialize;
     }
     async sendCommand(method, params) {
-        const view = await this.materialize();
+        // Materialize once and cache: every sendCommand on the same handle must
+        // target the SAME child view. Re-materializing would re-run createView
+        // (duplicate window) and drop the established view.
+        this.materialized ??= this.materialize();
+        const view = await this.materialized;
         return view.sendCommand(method, params);
     }
+    async download(url, savePath) {
+        this.materialized ??= this.materialize();
+        const view = await this.materialized;
+        return view.download(url, savePath);
+    }
+    async flushAuth() {
+        this.materialized ??= this.materialize();
+        const view = await this.materialized;
+        return view.flushAuth();
+    }
+    async restoreAuth(cookies) {
+        this.materialized ??= this.materialize();
+        const view = await this.materialized;
+        return view.restoreAuth(cookies);
+    }
 }
 /** Reject a promise if it does not settle within the budget. */
 function withTimeout(promise, ms, message) {

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

@@ -5,10 +5,12 @@
  * `browser_switch_tab`, `browser_close_tab`, `browser_reset`).
  *
  * The tool layer owns only the model-facing schema, argument validation, and
- * result formatting 鈥?never provider selection or page driving, which belong
- * to the seam. Session lifecycle is owned here at the plugin level: the
- * first `browser_open` (or any tool when no session exists) opens a session;
- * later tools reuse it. Per-agent isolation is a follow-up.
+ * result formatting — never provider selection or page driving, which belong
+ * to the seam. Session lifecycle is owned here at the plugin level: each
+ * calling task (a DSH session) gets its own browser session — the first
+ * `browser_open` (or any tool when no session exists) opens it, and later
+ * tools in the same task reuse it. Concurrent tasks therefore never fight
+ * over tabs, history, or navigation state.
  * @module dsh-browser/tool-browser
  */
 import type { Context } from '@deepseek-ai/cordis';
@@ -23,11 +25,15 @@ export interface Config {
     readonly timeoutMs?: number;
     /** Whether to offer tab-management tools. Default true. */
     readonly tabTools?: boolean;
+    /** Optional initial allow-list of browser tool names; other tools are refused. */
+    readonly allowedActions?: readonly string[];
 }
 /** Register all browser tools with `ctx.tools`. */
 export declare function apply(ctx: Context, config?: Config): void;
-/** Test hook: clear the plugin-level session (used by tests and on reset). */
+/** Test hook: inspect and reset the plugin-level session map (used by tests). */
 export declare const internals: {
-    readonly session: BrowserSessionId | undefined;
-    clearSession(): void;
+    /** 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;
 };