dsh-builtin-browser 0.3.1 → 0.4.1

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

@@ -868,9 +868,12 @@ export class RemoteElectronViewHost {
     }
     /** The child died: tear down so the next use starts a fresh child. */
     onChildExit() {
-        if (this.disposed)
-            return;
-        process.stderr.write('[dsh-browser host] browser host gone; will restart on next use\n');
+        // A disposed host still has to drop these: returning here left a child that had
+        // already been replaced during a dispose race in no map at all, so nothing would
+        // ever kill it. Only the restart is suppressed, not the cleanup.
+        const wasDisposed = this.disposed;
+        if (!wasDisposed)
+            process.stderr.write('[dsh-browser host] browser host gone; will restart on next use\n');
         this.client = undefined;
         this.server?.close();
         this.server = undefined;

package/lib/browser-electron/settings-store.js

@@ -157,11 +157,17 @@ export class SettingsStore {
             mkdirSync(dirname(this.file), { recursive: true });
             writeFileSync(this.file, `${JSON.stringify(merged, null, 2)}\n`);
         }
-        catch {
-            // Keep the merged value in memory even when the write fails.
+        catch (error) {
+            // Do NOT publish the new value as cached, and do not pretend the file changed: a
+            // reader compares the file's mtime against this stamp, so stamping "now" on a failed
+            // write made the next get() re-read the file and silently revert the user's change.
+            // Clear the cache before failing: the value on disk is still the old one, so leaving
+            // the merged document cached would hand the next reader something that does not exist —
+            // and the stamp would make it look fresh until the mtime comparison rolled it back.
+            this.cached = undefined;
+            this.cachedMtimeMs = -1;
+            throw new Error(`dsh-builtin-browser: settings could not be saved: ${error instanceof Error ? error.message : String(error)}`);
         }
-        this.cached = merged;
-        this.cachedMtimeMs = Date.now();
         return merged;
     }
 }

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

@@ -38,12 +38,28 @@ export interface DetectedBrowser {
  * Find an installed Chromium browser.
  *
  * `auto` prefers Chrome, then Edge, then Brave — the order reflects how likely each
- * is to be the browser a user actually chose rather than one Windows shipped.
+ * is to be the browser a user actually chose rather than one the system shipped.
+ * Each candidate is looked up in three places, most specific first: an explicit
+ * environment override, then PATH, then the platform's conventional install
+ * locations. PATH comes before the fixed paths because it is what actually reflects
+ * how the browser was installed.
  * @param channel - the configured choice; `bundled` never resolves to a system browser.
  * @param env - environment lookup, injected so tests need no real machine.
+ * @param platform - the platform to use conventions for; injected for the same reason.
  * @returns the detected browser, or undefined when the choice is unavailable.
  */
-export declare function detectBrowser(channel: BrowserChannel, env?: NodeJS.ProcessEnv): DetectedBrowser | undefined;
+export declare function detectBrowser(channel: BrowserChannel, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): DetectedBrowser | undefined;
+/**
+ * Everything that was checked for one product, for reporting a miss.
+ *
+ * Detection returns undefined with no explanation, which left the caller able to say
+ * only "not found". This gives the user the actual list so they can see whether the
+ * plugin looked somewhere their browser is not.
+ * @param kind - the product to describe.
+ * @param platform - the platform whose names and locations apply.
+ * @returns the launcher names (as PATH lookups) and the fixed locations checked.
+ */
+export declare function searchSummary(kind: DetectedBrowser['kind'], platform?: NodeJS.Platform): string[];
 /** A system browser driven over CDP, presented as a browser view host. */
 export declare class SystemBrowserViewHost implements ElectronBrowserViewHost {
     private readonly browser;
@@ -106,11 +122,16 @@ export declare class SystemBrowserViewHost implements ElectronBrowserViewHost {
     /** The browser owns window grouping. */
     groupView(): void;
     /**
-     * Bring the browser's window forward.
+     * Best effort at bringing the browser's window forward.
      *
-     * The browser is a separate application, so there is no view to raise; focusing
-     * the process is the closest honest equivalent, and failing to do so (a minimized
-     * window, a locked session) is never worth an error.
+     * The browser is a separate application, so there is no view to raise. What this can
+     * actually do is ask its process to continue from a stopped state — which is a no-op on
+     * Windows, where `SIGCONT` is not a supported signal and the call throws. It is kept
+     * because it costs nothing and does help on POSIX (a process stopped with SIGSTOP
+     * resumes), but it must not be read as a promise that the window comes to the front;
+     * importantly, it does NOT raise a window that is merely behind another. Raising the
+     * page properly would need `Page.bringToFront` on a specific target session, which is a
+     * view-level concern and not available to the host.
      */
     focus(): Promise<void>;
     /** The browser reports its own window lifecycle. */

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

@@ -30,34 +30,121 @@ import { join } from 'node:path';
 import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 /**
- * Where each Chromium product installs on Windows, plus the registry paths that
- * survive a non-default install location. Only paths that exist are returned, so a
- * caller can tell "not installed" from "installed elsewhere".
+ * Launcher names to look for on PATH, per product and per platform.
+ *
+ * The names genuinely differ: Linux distributions package the launcher under a
+ * versioned name (`microsoft-edge-stable`, `google-chrome-stable`), Windows puts
+ * `chrome.exe` in an Application directory that may or may not be on PATH, and macOS
+ * ships the executable inside the .app bundle. PATH is still consulted first on every
+ * platform — it is what reflects how the user actually installed the browser.
+ */
+const PATH_NAMES = {
+    chrome: {
+        win32: ['chrome'],
+        darwin: ['Google Chrome', 'Chromium'],
+        linux: ['google-chrome-stable', 'google-chrome', 'chromium', 'chromium-browser'],
+    },
+    edge: {
+        win32: ['msedge'],
+        darwin: ['Microsoft Edge'],
+        linux: ['microsoft-edge-stable', 'microsoft-edge', 'microsoft-edge-dev'],
+    },
+    brave: {
+        win32: ['brave'],
+        darwin: ['Brave Browser'],
+        linux: ['brave-browser', 'brave'],
+    },
+};
+/**
+ * Where each product installs when its launcher is not on PATH.
+ *
+ * Windows keeps the executable inside a version-less Application directory; macOS
+ * keeps it inside the .app bundle; Linux distributions that do not use a launcher
+ * put it under /usr/bin or /opt. All are checked, and anything missed can be named
+ * explicitly with DSH_BROWSER_<KIND>_PATH.
  */
-const WINDOWS_LOCATIONS = {
-    chrome: [
-        String.raw `C:\Program Files\Google\Chrome\Application\chrome.exe`,
-        String.raw `C:\Program Files (x86)\Google\Chrome\Application\chrome.exe`,
-    ],
-    edge: [
-        String.raw `C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe`,
-        String.raw `C:\Program Files\Microsoft\Edge\Application\msedge.exe`,
-    ],
-    brave: [
-        String.raw `C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe`,
-        String.raw `C:\Program Files (x86)\BraveSoftware\Brave-Browser\Application\brave.exe`,
-    ],
+const INSTALL_LOCATIONS = {
+    chrome: {
+        win32: [
+            String.raw `C:\Program Files\Google\Chrome\Application\chrome.exe`,
+            String.raw `C:\Program Files (x86)\Google\Chrome\Application\chrome.exe`,
+        ],
+        darwin: [
+            '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+            '/Applications/Chromium.app/Contents/MacOS/Chromium',
+        ],
+        linux: [
+            '/usr/bin/google-chrome-stable',
+            '/usr/bin/google-chrome',
+            '/usr/bin/chromium',
+            '/opt/google/chrome/chrome',
+            '/snap/bin/chromium',
+        ],
+    },
+    edge: {
+        win32: [
+            String.raw `C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe`,
+            String.raw `C:\Program Files\Microsoft\Edge\Application\msedge.exe`,
+        ],
+        darwin: ['/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge'],
+        linux: [
+            '/usr/bin/microsoft-edge-stable',
+            '/usr/bin/microsoft-edge',
+            '/usr/bin/microsoft-edge-dev',
+        ],
+    },
+    brave: {
+        win32: [
+            String.raw `C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe`,
+            String.raw `C:\Program Files (x86)\BraveSoftware\Brave-Browser\Application\brave.exe`,
+        ],
+        darwin: ['/Applications/Brave Browser.app/Contents/MacOS/Brave Browser'],
+        linux: ['/usr/bin/brave-browser', '/usr/bin/brave', '/snap/bin/brave'],
+    },
 };
+/**
+ * Find an executable by name on PATH.
+ *
+ * PATH is read from the supplied environment rather than the process's own, so the
+ * detection stays testable. On Windows a bare name needs its extension; elsewhere
+ * the launcher is the file itself.
+ * @param names - candidate launcher names, in preference order.
+ * @param env - the environment to read PATH from.
+ * @param platform - the platform whose PATH and extension conventions apply.
+ * @returns the first existing absolute path, or undefined.
+ */
+function findOnPath(names, env, platform) {
+    // Windows spells it Path as often as PATH; the separator differs too.
+    const raw = env.PATH ?? env.Path ?? env.path ?? '';
+    const separator = platform === 'win32' ? ';' : ':';
+    const directories = raw.split(separator).map(entry => entry.trim()).filter(entry => entry !== '');
+    const suffixes = platform === 'win32' ? ['.exe', '.cmd', ''] : [''];
+    for (const name of names) {
+        for (const directory of directories) {
+            for (const suffix of suffixes) {
+                const candidate = join(directory, `${name}${suffix}`);
+                if (existsSync(candidate))
+                    return candidate;
+            }
+        }
+    }
+    return undefined;
+}
 /**
  * Find an installed Chromium browser.
  *
  * `auto` prefers Chrome, then Edge, then Brave — the order reflects how likely each
- * is to be the browser a user actually chose rather than one Windows shipped.
+ * is to be the browser a user actually chose rather than one the system shipped.
+ * Each candidate is looked up in three places, most specific first: an explicit
+ * environment override, then PATH, then the platform's conventional install
+ * locations. PATH comes before the fixed paths because it is what actually reflects
+ * how the browser was installed.
  * @param channel - the configured choice; `bundled` never resolves to a system browser.
  * @param env - environment lookup, injected so tests need no real machine.
+ * @param platform - the platform to use conventions for; injected for the same reason.
  * @returns the detected browser, or undefined when the choice is unavailable.
  */
-export function detectBrowser(channel, env = process.env) {
+export function detectBrowser(channel, env = process.env, platform = process.platform) {
     if (channel === 'bundled')
         return undefined;
     const order = channel === 'auto' ? ['chrome', 'edge', 'brave'] : [channel];
@@ -65,16 +152,33 @@ export function detectBrowser(channel, env = process.env) {
         const fromEnv = (kind === 'chrome' ? env.DSH_BROWSER_CHROME_PATH : kind === 'edge' ? env.DSH_BROWSER_EDGE_PATH : undefined);
         if (fromEnv !== undefined && fromEnv !== '' && existsSync(fromEnv))
             return { kind, path: fromEnv };
-        for (const candidate of WINDOWS_LOCATIONS[kind] ?? []) {
+        const onPath = findOnPath(PATH_NAMES[kind]?.[platform] ?? [], env, platform);
+        if (onPath !== undefined)
+            return { kind, path: onPath };
+        for (const candidate of INSTALL_LOCATIONS[kind]?.[platform] ?? []) {
             if (existsSync(candidate))
                 return { kind, path: candidate };
         }
     }
     return undefined;
 }
+/**
+ * Everything that was checked for one product, for reporting a miss.
+ *
+ * Detection returns undefined with no explanation, which left the caller able to say
+ * only "not found". This gives the user the actual list so they can see whether the
+ * plugin looked somewhere their browser is not.
+ * @param kind - the product to describe.
+ * @param platform - the platform whose names and locations apply.
+ * @returns the launcher names (as PATH lookups) and the fixed locations checked.
+ */
+export function searchSummary(kind, platform = process.platform) {
+    const onPath = (PATH_NAMES[kind]?.[platform] ?? []).map(name => `${name} (on PATH)`);
+    const located = INSTALL_LOCATIONS[kind]?.[platform] ?? [];
+    return [...onPath, ...located];
+}
 /** One CDP connection to a browser-level WebSocket, with flattened sessions. */
 class CdpClient {
-    url;
     nextId = 1;
     pending = new Map();
     ready;
@@ -82,7 +186,6 @@ class CdpClient {
      * @param url - the browser's `webSocketDebuggerUrl`.
      */
     constructor(url) {
-        this.url = url;
         // Node 22 provides WebSocket globally; no dependency is added for this.
         const socket = new WebSocket(url);
         this.socket = socket;
@@ -94,9 +197,42 @@ class CdpClient {
         socket.addEventListener('close', () => this.fail(new Error('dsh-builtin-browser: the browser closed the CDP connection')));
     }
     socket;
-    /** Resolve once the socket is open. */
+    /**
+     * Resolve once the socket is open.
+     *
+     * Bounded on purpose. `ready` settles on the socket's own `open` or `error` events, and
+     * a connection that is dropped by something in between may deliver neither — in which
+     * case an unbounded await here would hang the tool call forever, because the caller's
+     * own deadline is only checked between polls and this await happens inside one of them.
+     * @returns when the handshake completed.
+     */
+    /**
+     * Whether the socket is still usable.
+     *
+     * A dropped connection is not reported to the caller of send(); the pending command
+     * would simply never complete. Asking the socket directly is what lets a cached client
+     * be discarded instead of reused, which is the difference between a restart and a 30s
+     * hang on every subsequent call.
+     * @returns true while the socket is open.
+     */
+    isAlive() {
+        return this.socket.readyState === WebSocket.OPEN;
+    }
     async whenReady() {
-        await this.ready;
+        const timeoutMs = 30_000;
+        let timer;
+        try {
+            await Promise.race([
+                this.ready,
+                new Promise((_resolve, reject) => {
+                    timer = setTimeout(() => reject(new Error(`dsh-builtin-browser: the browser did not complete the CDP handshake within ${timeoutMs / 1000}s`)), timeoutMs);
+                }),
+            ]);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
     }
     /**
      * Send one CDP command, optionally on an attached session.
@@ -106,6 +242,11 @@ class CdpClient {
      * @returns the CDP result.
      */
     async send(method, params, sessionId) {
+        // Fail fast and say why. Waiting out the timeout on a closed socket produced
+        // only "timed out", which reads as a slow page and hides the real cause.
+        if (!this.isAlive()) {
+            throw new Error('dsh-builtin-browser: the browser connection is closed (the browser window was probably closed); the next command will start it again');
+        }
         await this.ready;
         const id = this.nextId++;
         const message = { id, method, ...params !== undefined ? { params } : {}, ...sessionId !== undefined ? { sessionId } : {} };
@@ -198,8 +339,19 @@ export class SystemBrowserViewHost {
      * @returns the connected client.
      */
     async ensureClient() {
-        if (this.client !== undefined)
-            return this.client;
+        // A disposed host must never start a browser: doing so would spawn a process
+        // nobody owns and nobody will kill.
+        if (this.disposed)
+            throw new Error('dsh-builtin-browser: this browser host was released');
+        // The exit listener clears this, but a socket can also die without the process doing so
+        // (the browser closing its debugging endpoint, a dropped connection). Checking the
+        // socket's own state costs nothing and turns a 30s hang into a restart.
+        if (this.client !== undefined) {
+            if (this.client.isAlive())
+                return this.client;
+            this.client.close();
+            this.client = undefined;
+        }
         // Concurrent first calls share one startup rather than racing two browsers.
         this.starting ??= this.start().finally(() => { this.starting = undefined; });
         return await this.starting;
@@ -228,16 +380,63 @@ export class SystemBrowserViewHost {
         ];
         const child = spawn(this.browser.path, args, { stdio: ['ignore', 'ignore', 'ignore'], windowsHide: false });
         this.child = child;
+        /**
+         * A launch that fails (ENOENT, no permission, a broken binary) is reported by an
+         * asynchronous 'error' event on the child, NOT by a throw here and NOT by exitCode.
+         * Without this listener Node treats it as unhandled and takes the whole host process
+         * down — one bad browser path would kill DSH, not just fail a tool call.
+         */
+        let launchError;
+        child.on('error', error => { launchError = error; });
+        // A browser that exits later is as unusable as one that never started, and the failure
+        // has to reach the NEXT call rather than being swallowed: clearing the client here is
+        // what makes ensureClient() start a fresh browser instead of returning a socket to a
+        // dead process and letting every command time out.
+        child.on('exit', () => {
+            if (this.child !== child)
+                return;
+            this.client?.close();
+            this.client = undefined;
+            this.child = undefined;
+        });
         const portFile = join(this.profileDir, 'DevToolsActivePort');
         const deadline = Date.now() + 30_000;
+        /**
+         * Why the loop stopped, so the failure can say what actually happened. Reporting
+         * every ending as "did not expose CDP within 30s" was wrong three ways: the cause,
+         * the words, and the elapsed time — a browser that cannot be launched says so in
+         * half a second, and the caller then looks for a CDP problem that does not exist.
+         */
+        let stopped = 'timeout';
         for (;;) {
+            // Released while we were starting: stop here rather than keep polling for a
+            // browser that dispose() has already killed, which would leave a connection
+            // to a dead process behind. The child is killed here too — dispose() may have
+            // run before this child was recorded, leaving nobody else to do it.
+            if (this.disposed) {
+                child.kill();
+                if (this.child === child)
+                    this.child = undefined;
+                stopped = 'released';
+                break;
+            }
+            if (launchError !== undefined) {
+                if (this.child === child)
+                    this.child = undefined;
+                stopped = 'launch-failed';
+                break;
+            }
             if (Date.now() > deadline) {
                 child.kill();
-                this.child = undefined;
+                if (this.child === child)
+                    this.child = undefined;
+                stopped = 'timeout';
                 break;
             }
             if (child.exitCode !== null) {
-                this.child = undefined;
+                if (this.child === child)
+                    this.child = undefined;
+                stopped = 'exited';
                 break;
             }
             if (existsSync(portFile)) {
@@ -248,6 +447,12 @@ export class SystemBrowserViewHost {
                         if (typeof version.webSocketDebuggerUrl === 'string') {
                             const client = new CdpClient(version.webSocketDebuggerUrl);
                             await client.whenReady();
+                            // Still wanted? A dispose() during the handshake has already killed the
+                            // process, so publishing the client would leave a dangling connection.
+                            if (this.disposed) {
+                                client.close();
+                                break;
+                            }
                             this.client = client;
                             return client;
                         }
@@ -259,7 +464,20 @@ export class SystemBrowserViewHost {
             }
             await new Promise(resolve => setTimeout(resolve, 250));
         }
-        throw new Error(`dsh-builtin-browser: ${this.browser.kind} did not expose CDP within 30s (${this.browser.path})`);
+        // Each ending gets its own message. The old single message blamed a CDP timeout for
+        // all of them, which sent the reader looking for a port problem when the browser had
+        // simply failed to launch.
+        const target = `${this.browser.kind} (${this.browser.path})`;
+        if (stopped === 'launch-failed') {
+            throw new Error(`dsh-builtin-browser: could not launch ${target}: ${launchError?.message ?? 'unknown error'}`);
+        }
+        if (stopped === 'exited') {
+            throw new Error(`dsh-builtin-browser: ${target} exited immediately after launch (exit code ${child.exitCode}); check that the path is a runnable browser`);
+        }
+        if (stopped === 'released') {
+            throw new Error(`dsh-builtin-browser: ${target} was released while it was starting`);
+        }
+        throw new Error(`dsh-builtin-browser: ${target} did not expose CDP within 30s`);
     }
     /**
      * Whether this host can back views.
@@ -275,11 +493,25 @@ export class SystemBrowserViewHost {
         const viewId = randomUUID();
         return {
             id: viewId,
+            // This is the real browser, not Electron: CDP's JPEG encoder works here, so the
+            // provider may pass format and quality through instead of falling back to PNG.
+            supportsCdpJpeg: true,
             sendCommand: async (method, params) => {
-                const client = await this.ensureClient();
-                const session = this.views.get(viewId) ?? await this.ensureSession(viewId);
-                const result = await client.send(method, params, session);
-                return (result ?? {});
+                // A command that never answered is the only signal that a client has wedged — the
+                // socket can stay OPEN while nothing comes back, which is the form the reporter saw with
+                // a live, healthy-looking Edge. Dropping the client here means the next call starts a new
+                // browser rather than hanging again, and the error names the cause instead of a timeout.
+                try {
+                    const client = await this.ensureClient();
+                    const session = this.views.get(viewId) ?? await this.ensureSession(viewId);
+                    const result = await client.send(method, params, session);
+                    return (result ?? {});
+                }
+                catch (error) {
+                    this.client?.close();
+                    this.client = undefined;
+                    throw error;
+                }
             },
         };
     }
@@ -305,17 +537,22 @@ export class SystemBrowserViewHost {
     /** The browser owns window grouping. */
     groupView() { }
     /**
-     * Bring the browser's window forward.
+     * Best effort at bringing the browser's window forward.
      *
-     * The browser is a separate application, so there is no view to raise; focusing
-     * the process is the closest honest equivalent, and failing to do so (a minimized
-     * window, a locked session) is never worth an error.
+     * The browser is a separate application, so there is no view to raise. What this can
+     * actually do is ask its process to continue from a stopped state — which is a no-op on
+     * Windows, where `SIGCONT` is not a supported signal and the call throws. It is kept
+     * because it costs nothing and does help on POSIX (a process stopped with SIGSTOP
+     * resumes), but it must not be read as a promise that the window comes to the front;
+     * importantly, it does NOT raise a window that is merely behind another. Raising the
+     * page properly would need `Page.bringToFront` on a specific target session, which is a
+     * view-level concern and not available to the host.
      */
     async focus() {
         try {
             this.child?.kill('SIGCONT');
         }
-        catch { /* not supported on Windows; harmless */ }
+        catch { /* Windows has no SIGCONT; nothing to do */ }
     }
     /** The browser reports its own window lifecycle. */
     onUserAction() { }

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

@@ -28,6 +28,20 @@ export interface Config {
     /** Optional initial allow-list of browser tool names; other tools are refused. */
     readonly allowedActions?: readonly string[];
 }
+/**
+ * Guard one browser tool call against the active restriction. Refuses calls
+ * not on the allow-list when a restriction is in effect.
+ * @param state - the calling context's tool state.
+ * @param toolName - the browser tool about to run.
+ */
+/**
+ * Tools that only observe, plus the ones that undo a restriction.
+ *
+ * Never subject to an allow-list: restricting what the agent may *do* must not also
+ * blind it or trap it, and the tool descriptions promise as much. browser_restrict
+ * is in here so a task that restricted everything can still lift it.
+ */
+export declare const READ_ONLY_TOOLS: ReadonlySet<string>;
 /** Register all browser tools with `ctx.tools`. */
 export declare function apply(ctx: Context, config?: Config): void;
 /** Test hook: inspect and reset session mappings across every live plugin apply. */