dsh-builtin-browser 0.1.8 → 0.1.10

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

@@ -18,6 +18,8 @@ import { createInterface } from 'node:readline';
 import { createConnection } from 'node:net';
 /** CDP protocol version attached to every view's debugger. */
 const CDP_VERSION = '1.3';
+/** Download cap: the body is shipped base64 as one JSON line; bound the memory. */
+const MAX_DOWNLOAD_BYTES = 256 * 1024 * 1024;
 /** Views by the id the parent assigned at createView time. */
 const views = new Map();
 /** The single browser window; created lazily on first createView. */
@@ -48,12 +50,17 @@ async function handle(op, msg) {
                     window.on('closed', () => { window = undefined; });
                 }
                 const view = new WebContentsView();
+                // Attach the debugger BEFORE the view can be seen: an attach failure
+                // then leaves nothing in the window (no visible ghost view).
+                view.webContents.debugger.attach(CDP_VERSION);
+                // 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);
-                view.webContents.debugger.attach(CDP_VERSION);
+                if (views.size === 0)
+                    view.setVisible(true);
                 views.set(viewId, { webContentsView: view });
                 reply(msg.id, { ok: true });
                 return;
@@ -80,8 +87,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;
             }
@@ -119,6 +141,7 @@ async function handle(op, msg) {
             if (!r.ok) throw new Error('HTTP ' + r.status)
             const b = await r.arrayBuffer()
             const bytes = new Uint8Array(b)
+            if (bytes.length > ${String(MAX_DOWNLOAD_BYTES)}) throw new Error('download too large (limit ' + ${String(MAX_DOWNLOAD_BYTES)} + ' bytes, got ' + bytes.length + ')')
             let bin = ''
             for (let i = 0; i < bytes.length; i += 0x8000) bin += String.fromCharCode.apply(null, bytes.subarray(i, i + 0x8000))
             return btoa(bin)
@@ -144,16 +167,21 @@ async function handle(op, msg) {
                 // Export the session's cookies so login state can be saved/restored
                 // across browser hosts (or shared with another machine).
                 const cookies = await entry.webContentsView.webContents.session.cookies.get({});
-                const exported = cookies.map(c => ({
-                    url: `http${c.secure ? 's' : ''}://${c.domain.startsWith('.') ? c.domain.slice(1) : c.domain}${c.path}`,
-                    name: c.name,
-                    value: c.value,
-                    domain: c.domain,
-                    path: c.path,
-                    secure: c.secure,
-                    httpOnly: c.httpOnly,
-                    expirationDate: c.expirationDate,
-                }));
+                const exported = cookies.map(c => {
+                    const host = c.domain.startsWith('.') ? c.domain.slice(1) : c.domain;
+                    // IPv6 literal domains need brackets in a URL (e.g. http://[::1]/).
+                    const hostPart = host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
+                    return {
+                        url: `http${c.secure ? 's' : ''}://${hostPart}${c.path}`,
+                        name: c.name,
+                        value: c.value,
+                        domain: c.domain,
+                        path: c.path,
+                        secure: c.secure,
+                        httpOnly: c.httpOnly,
+                        expirationDate: c.expirationDate,
+                    };
+                });
                 reply(msg.id, { ok: true, result: { cookies: exported } });
                 return;
             }
@@ -167,6 +195,7 @@ async function handle(op, msg) {
                     throw new Error(`restoreAuth: unknown view ${viewId}`);
                 if (!Array.isArray(cookies))
                     throw new Error('restoreAuth missing cookies array');
+                let restored = 0;
                 for (const c of cookies) {
                     if (typeof c.url !== 'string' || typeof c.name !== 'string' || typeof c.value !== 'string')
                         continue;
@@ -180,8 +209,9 @@ async function handle(op, msg) {
                         ...typeof c.httpOnly === 'boolean' ? { httpOnly: c.httpOnly } : {},
                         ...typeof c.expirationDate === 'number' ? { expirationDate: c.expirationDate } : {},
                     });
+                    restored++;
                 }
-                reply(msg.id, { ok: true, result: { restored: cookies.length } });
+                reply(msg.id, { ok: true, result: { restored } });
                 return;
             }
             default:
@@ -228,6 +258,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 }
       }
@@ -512,7 +531,10 @@ export class ElectronBrowserProvider {
         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);
+        // The child fetches in-page with awaitPromise; a slow/hung network can
+        // block it well past the tool budget, so bound it like every other call.
+        const timeoutMs = 60_000;
+        await withTimeout(downloadable.download(request.url, request.savePath), timeoutMs, signal, `browser: download timed out after ${timeoutMs}ms`);
         this.record(s, 'download', { url: request.url, savePath: request.savePath }, true, { result: request.savePath });
         return { path: request.savePath };
     }
@@ -527,7 +549,8 @@ export class ElectronBrowserProvider {
         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();
+        const timeoutMs = 30_000;
+        const cookies = await withTimeout(host.flushAuth(), timeoutMs, undefined, `browser: auth export timed out after ${timeoutMs}ms`);
         this.record(s, 'flushAuth', {}, true, { result: `${cookies.length} cookies` });
         return cookies;
     }
@@ -539,7 +562,8 @@ export class ElectronBrowserProvider {
         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);
+        const timeoutMs = 30_000;
+        const restored = await withTimeout(host.restoreAuth(cookies), timeoutMs, undefined, `browser: auth restore timed out after ${timeoutMs}ms`);
         this.record(s, 'restoreAuth', { count: cookies.length }, true, { result: `${restored} cookies` });
         return restored;
     }
@@ -553,7 +577,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 +603,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 +663,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:
@@ -682,7 +711,9 @@ export class ElectronBrowserProvider {
     }
     /** Read the current URL of a view through CDP. */
     async currentUrl(handle) {
-        const result = await handleSendEvaluate(handle, 'location.href');
+        // Bound the read: a wedged renderer would otherwise hang listTabs.
+        const timeoutMs = 10_000;
+        const result = await withTimeout(handleSendEvaluate(handle, 'location.href'), timeoutMs, undefined, `browser: url read timed out after ${timeoutMs}ms`);
         return result.ok && typeof result.value === 'string' ? result.value : '';
     }
 }
@@ -703,7 +734,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;