dsh-builtin-browser 0.4.8 → 0.4.10

package/lib/browser-electron/desktop-bridge-host.js

@@ -163,7 +163,27 @@ export class DesktopBridgeViewHost {
             const probe = new BridgeConnection(endpoint, bridgeEndpointPath());
             try {
                 const answer = await probe.call({ op: 'list' }, 5_000);
-                return answer.ok === true ? new DesktopBridgeViewHost(endpoint, sessionId) : undefined;
+                if (answer.ok !== true)
+                    return undefined;
+                // Refuse a panel this plugin cannot drive, before adopting it.
+                //
+                // The sidebar browser renders as a <webview> only where the shell exposes
+                // `dshDesktop.browser` and enables `webviewTag`. Where it renders as an <iframe> there is
+                // no webContents, no `getWebContentsId()` and no CDP endpoint — and every tool here is
+                // built on CDP, so adopting it means failing every call, with no path back to a carrier
+                // that works. Reported on DSH Desktop 2.0.17 with both conditions measured.
+                //
+                // Read here WITHOUT an owner on purpose, because the question is not about a conversation:
+                // whether the panel is a webview is decided by the shell's preload and window options, so
+                // it is the same answer for every conversation and needs no session context.
+                //
+                // `none` and `unknown` are NOT refusals: a panel that does not exist yet is created by the
+                // first open, and a probe that could not read the attribute has learned nothing.
+                if (String(answer.frame ?? 'unknown') === 'iframe') {
+                    DesktopBridgeViewHost.refuseIframe = true;
+                    return undefined;
+                }
+                return new DesktopBridgeViewHost(endpoint, sessionId);
             }
             finally {
                 probe.close();
@@ -174,10 +194,95 @@ export class DesktopBridgeViewHost {
             return undefined;
         }
     }
+    /**
+     * Whether the last discovery refused a bridge because its sidebar panel is an iframe.
+     *
+     * Recorded so the entry point can say WHY the plugin is self-hosting on a shell that does have a
+     * bridge. Otherwise the user sees a second browser window and no explanation, on a machine where
+     * they just followed instructions to install the bridge.
+     */
+    static refuseIframe = false;
+    /** Whether discovery refused a bridge for an undrivable sidebar panel (see {@link discover}). */
+    static refusedIframePanel() {
+        return this.refuseIframe;
+    }
     /** Whether this host can back views: the bridge already answered `list`. */
     available() {
         return true;
     }
+    /**
+     * Every page this conversation's sidebar panel currently holds.
+     *
+     * The shell owns page creation inside the panel: a link the user or the agent clicks may open a
+     * new page, and nothing tells the provider. Those pages are real — they are what the human sees
+     * — but without this the tab model reports only the ones the provider created, so the rest are
+     * invisible to `dsh_browser_list_tabs` and unclosable through `dsh_browser_close_tab`.
+     *
+     * The bridge's `list` already answers with the sidebar guests, which is the same information, so
+     * this asks for it rather than reaching into the shell again.
+     * @returns the panel's pages, or an empty list when the bridge cannot answer.
+     */
+    /**
+     * Every sidebar page this conversation holds that THIS HOST did not open.
+     *
+     * The shell owns page creation inside the panel: a link the user or the agent clicks may open a
+     * new page, and nothing tells the provider. Those pages are real — they are what the human sees
+     * — but without this the tab model reports only the ones the provider created, so the rest are
+     * invisible to `dsh_browser_list_tabs` and unclosable through `dsh_browser_close_tab`.
+     *
+     * Pages this host opened are EXCLUDED here rather than deduplicated by the caller, because the
+     * caller cannot do it: the provider knows a tab by its own id and the carrier knows a page by the
+     * guest id, and the two never match. The first version returned everything and relied on the
+     * caller to filter, which reported the same page twice — the mapping that makes the match
+     * possible exists only here.
+     * @returns the panel's pages that are not ours, or an empty list when the bridge cannot answer.
+     */
+    async listPages() {
+        try {
+            const answer = await this.connection.call({ op: 'list', owner: this.owner }, 5_000);
+            const guests = Array.isArray(answer.sidebar) ? answer.sidebar : [];
+            const ours = new Set();
+            for (const view of this.views.values()) {
+                if (typeof view.guest === 'number')
+                    ours.add(view.guest);
+            }
+            return guests
+                .filter((guest) => typeof guest?.id === 'number')
+                .filter(guest => !ours.has(guest.id))
+                .map(guest => ({
+                id: String(guest.id),
+                url: typeof guest.url === 'string' ? guest.url : '',
+            }));
+        }
+        catch {
+            // A bridge that cannot answer has a real problem, and the next command reports it. Failing
+            // the tab LIST here would make a listing worse than the driving it exists to describe.
+            return [];
+        }
+    }
+    /**
+     * Close one sidebar page by the id {@link listPages} reported.
+     *
+     * The bridge closes sidebar pages by TITLE, and only the ones the caller owns — that is what
+     * stopped one conversation's teardown from destroying another's page. So the title is looked up
+     * through the same listing, and a page that no longer appears is treated as already gone rather
+     * than as an error: the caller asked for it to be closed, and it is.
+     * @param id - the sidebar guest id, as a string.
+     */
+    async closePage(id) {
+        const numeric = Number(id);
+        if (!Number.isFinite(numeric))
+            throw new Error(`not a sidebar page id: ${id}`);
+        const answer = await this.connection.call({ op: 'list', owner: this.owner }, 5_000);
+        const guests = Array.isArray(answer.sidebar) ? answer.sidebar : [];
+        const title = guests
+            .filter((guest) => Number(guest?.id) === numeric)
+            .map(guest => String(guest.title ?? ''))
+            .find(candidate => candidate !== '');
+        if (title === undefined)
+            return;
+        await this.connection.call({ op: 'closeSidebarBrowser', titles: [title], owner: this.owner }, 10_000);
+    }
     /**
      * The guest backing a view, materialized on first use.
      *
@@ -214,8 +319,17 @@ export class DesktopBridgeViewHost {
             owner,
             ...url !== undefined && url !== '' ? { url } : {},
         }, 30_000);
-        if (answer.ok !== true)
+        if (answer.ok !== true) {
+            // A bridge that answers but cannot produce a page is as unusable as one that has exited, and
+            // the difference matters here: `onLost` is what returns the surface to the self-hosted
+            // browser. Without this the same failure repeats on every call until DSH is restarted — on a
+            // shell whose sidebar panel is an iframe, that is every call forever. Reported as "installing
+            // the bridge made it worse than not installing it": the carrier was switched to one that
+            // cannot work, with no path back to the one that does.
+            if (String(answer.error).includes('produced no page'))
+                this.reportLost();
             throw new Error(`dsh-builtin-browser: sidebar unavailable (${String(answer.error)})`);
+        }
         const id = Number(answer.id);
         if (!Number.isFinite(id) || id <= 0) {
             throw new Error('dsh-builtin-browser: the sidebar reported no browser page for this conversation');

package/lib/browser-electron/entry.js

@@ -303,6 +303,19 @@ export function apply(ctx, config) {
                 adopt(sidebar, 'driving the desktop sidebar browser');
                 return;
             }
+            // A bridge exists but its sidebar panel is an iframe. Saying nothing here would leave the user
+            // with a second browser window on a machine where they just followed the instructions to
+            // install the bridge, and no way to know the two facts are related. The carrier is not
+            // unavailable by accident: an iframe has no CDP endpoint, so adopting it would fail every call
+            // instead of falling back — see DesktopBridgeViewHost.discover.
+            if (DesktopBridgeViewHost.refusedIframePanel()) {
+                ctx.logger?.warn?.('dsh-builtin-browser: a desktop bridge is installed, but this shell renders the sidebar '
+                    + 'browser panel as an iframe rather than a webview, which exposes no CDP endpoint and '
+                    + 'cannot be driven. Using the browser this plugin hosts itself instead — that is the '
+                    + 'independent window, not the sidebar. A shell that exposes `dshDesktop.browser` and '
+                    + 'enables `webviewTag` would provide a drivable panel.');
+                return;
+            }
             // The user explicitly asked for the sidebar, so silence would leave them with a setting
             // that did nothing and no way to tell why. This is reachable on `dsh web`, and on a desktop
             // whose shell never published a bridge endpoint. An automatic attempt stays quiet (the

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

@@ -9,6 +9,7 @@
 import { type VisitedPage } from './history-store.js';
 import type { BrowserSettings } from './settings-store.js';
 import type { BrowserA11yRequest, BrowserA11yResult, BrowserChallenge, BrowserCheckRequest, BrowserClearRequest, BrowserClickRequest, BrowserContentRequest, BrowserContentResult, BrowserElementTarget, BrowserExecuteRequest, BrowserExecuteResult, BrowserFillRequest, BrowserFillResult, BrowserGetValueRequest, BrowserGetValueResult, BrowserHistoryEntry, BrowserOpenRequest, BrowserProvider, BrowserScrapeRequest, BrowserScrapeResult, BrowserScreenshotRequest, BrowserSelectRequest, BrowserSelectResult, BrowserSessionId, BrowserSetValueRequest, BrowserSetValueResult, BrowserSnapshotResult, BrowserTab, BrowserTypeRequest, BrowserWaitRequest, BrowserWaitResult, BrowserScrollRequest, BrowserKeyRequest, ExportedCookie } from '../browser/types.js';
+import type { CarrierPage } from '../browser/types.js';
 /** Stable provider id registered with `ctx.browser`. */
 export declare const ELECTRON_BROWSER_PROVIDER_ID = "electron";
 /**
@@ -58,6 +59,35 @@ export interface ElectronBrowserViewHost {
      * @param label - human-readable session/task label, as in {@link showView}.
      */
     presentView?(handle: ElectronViewHandle, label?: string): Promise<void>;
+    /**
+     * Optional: pages this carrier holds that the provider never created.
+     *
+     * A sidebar panel and an installed browser both own their own page creation. Clicking a link
+     * that opens a new page — or any `window.open` the page performs — produces a page the provider
+     * did not ask for and therefore never recorded. Those pages are real: they are what the human
+     * sees, they hold memory, and they persist until something closes them. Without this the tab
+     * model reports only what the provider itself made, so the extras are invisible to
+     * `dsh_browser_list_tabs` and unclosable through `dsh_browser_close_tab`, accumulating for the
+     * life of the browser.
+     *
+     * Views the host itself opened are NOT included. That exclusion belongs to the host, which is the
+     * only side that can make it: a provider tab is identified by the provider's own id and a carrier
+     * page by the carrier's, so a caller comparing the two matches nothing and reports every page
+     * twice. Measured on the sidebar carrier: three clicks produced three webview guests while
+     * `dsh_browser_list_tabs` reported one tab; on the installed-browser carrier the window held four
+     * pages and the tool reported one.
+     * @returns every page the carrier holds that this host did not open.
+     */
+    listPages?(): Promise<readonly CarrierPage[]>;
+    /**
+     * Optional: close one page reported by {@link listPages}.
+     *
+     * The pair exists because listing a page the caller cannot close is worse than not listing it:
+     * `dsh_browser_list_tabs` would report pages that `dsh_browser_close_tab` answers "not open in
+     * this session" about, which reads as a contradiction rather than a boundary.
+     * @param id - the carrier's own page id, as {@link listPages} reported it.
+     */
+    closePage?(id: string): Promise<void>;
     /**
      * Optional cheap usability probe (no network): whether the host can back
      * views at all right now. The self-hosted host checks for a usable Electron
@@ -303,6 +333,15 @@ export interface CdpNavigateParams {
  * CDP method/params for `Input.dispatchMouseEvent`: a pointer move, or one half
  * of a click's press+release pair. `button`/`clickCount` belong to the press and
  * release halves; a move carries only the position.
+ *
+ * `buttons` is a BITMASK of what is held down at the moment of the event, and it is not the same
+ * field as `button` — `button` says which one this event is about, `buttons` says which ones are
+ * down. Chromium needs both to recognise a synthesized press as a real button press: with
+ * `buttons` omitted (0), the event still reaches the page and a `click` listener still fires, but
+ * the element's DEFAULT ACTION does not run. Measured on the sidebar carrier: a click on an
+ * anchor sent `mousedown`/`mouseup`/`click` to the page with `isTrusted: true` and
+ * `defaultPrevented: false`, and the browser did not follow the link — including for an anchor
+ * injected by the test itself, so the page was not responsible.
  */
 export interface CdpMouseParams {
     readonly type: 'mouseMoved' | 'mousePressed' | 'mouseReleased';
@@ -310,6 +349,8 @@ export interface CdpMouseParams {
     readonly y: number;
     readonly button?: 'left';
     readonly clickCount?: number;
+    /** Buttons held during the event: 1 = primary down. A move carries 0. */
+    readonly buttons?: number;
 }
 /** CDP method/params for `Input.insertText`. */
 export interface CdpInsertTextParams {

package/lib/browser-electron/provider.js

@@ -384,6 +384,28 @@ export class ElectronBrowserProvider {
                 active: i === s.activeIndex,
             });
         }
+        // Pages the CARRIER holds that this provider never created.
+        //
+        // A sidebar panel and an installed browser both open pages on their own: a click on a link
+        // that targets a new page, or any `window.open`, produces a page nothing tells us about.
+        // Reporting only our own tabs made those invisible to this tool and unclosable through
+        // `dsh_browser_close_tab`, so they accumulated for the life of the browser. Measured on the
+        // sidebar carrier: three clicks produced three webview guests while this listed one tab.
+        //
+        // `listPages` already excludes the pages it opened the view for — that filtering cannot happen
+        // here, because a tab is known by this provider's own id and a carrier page by the carrier's,
+        // and the two never match. A first version compared them anyway and listed every page twice.
+        //
+        // They are appended under a `page:` prefix so a caller can tell the two kinds apart — the
+        // prefix is also what `closeTab` uses to decide whether to close a view or a carrier page.
+        const pages = await this.host.listPages?.().catch(() => undefined) ?? [];
+        for (const page of pages) {
+            // A page with no URL is a blank one the carrier opened for itself. Listing it would invite a
+            // caller to act on nothing, and the blank normalisation already closes those.
+            if (page.url === '' || page.url === 'about:blank')
+                continue;
+            result.push({ id: `page:${page.id}`, url: page.url, active: false });
+        }
         return result;
     }
     /** Switch to a tab by id, making its view visible. */
@@ -395,6 +417,16 @@ export class ElectronBrowserProvider {
     }
     /** Close one tab; closing the active tab activates the next. */
     closeTab(session, tabId) {
+        // A page the carrier owns rather than a view we created. It was reported by `listTabs` under
+        // this prefix, so closing it here is what keeps the two tools consistent — a page that can be
+        // listed must be closable, or the listing reads as a contradiction.
+        if (tabId.startsWith('page:')) {
+            const id = tabId.slice('page:'.length);
+            if (this.host.closePage === undefined) {
+                return Promise.reject(new BrowserError('browser: this carrier does not expose the pages it opens on its own, so that page cannot be closed', 'BROWSER_TAB_NOT_FOUND'));
+            }
+            return this.host.closePage(id);
+        }
         const found = this.locateTab(session, tabId);
         const s = found.s;
         const index = found.index;
@@ -1290,7 +1322,7 @@ export class ElectronBrowserProvider {
         // landed because the first had quietly established the target. Move the
         // pointer first so a click is self-contained.
         try {
-            await send({ type: 'mouseMoved', x, y }, 'move');
+            await send({ type: 'mouseMoved', x, y, buttons: 0 }, 'move');
         }
         catch (error) {
             throw new BrowserError(`browser: click failed: ${String(error)}`, 'BROWSER_CLICK_FAILED', { cause: error });
@@ -1311,12 +1343,13 @@ export class ElectronBrowserProvider {
                 x,
                 y,
                 button: 'left',
+                buttons: 0,
                 clickCount: 1,
             })
                 .catch(() => { });
         };
         try {
-            await send({ type: 'mousePressed', x, y, button: 'left', clickCount: 1 }, 'press');
+            await send({ type: 'mousePressed', x, y, button: 'left', buttons: 1, clickCount: 1 }, 'press');
         }
         catch (error) {
             // The press may still land late; release best-effort so the button is
@@ -1325,7 +1358,7 @@ export class ElectronBrowserProvider {
             throw new BrowserError(`browser: click failed: ${String(error)}`, 'BROWSER_CLICK_FAILED', { cause: error });
         }
         try {
-            await send({ type: 'mouseReleased', x, y, button: 'left', clickCount: 1 }, 'release');
+            await send({ type: 'mouseReleased', x, y, button: 'left', buttons: 0, clickCount: 1 }, 'release');
         }
         catch (error) {
             // The press already landed; retry the release so the button is not

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

@@ -36,6 +36,7 @@
 export type BrowserLauncher = (path: string, args: readonly string[]) => ReturnType<typeof spawn>;
 import { spawn } from 'node:child_process';
 import type { ElectronBrowserViewHost, ElectronViewHandle } from './provider.js';
+import type { CarrierPage } from '../browser/types.js';
 /** Which browser the user asked for. */
 export type BrowserChannel = 'bundled' | 'chrome' | 'edge' | 'auto' | 'sidebar';
 /** A resolved browser installation. */
@@ -111,6 +112,16 @@ export declare class SystemBrowserViewHost implements ElectronBrowserViewHost {
      */
     private clientSuspect;
     private child;
+    /**
+     * True when the browser in use was adopted from a previous run rather than launched here.
+     *
+     * Worth recording because the two differ on teardown: a browser this host spawned is its to
+     * kill, while one it merely took over belongs to a process that is already gone — closing it is
+     * still right (it holds the profile nobody else can use), but it is a decision, not cleanup.
+     */
+    private adoptedRunning;
+    /** Whether this connection's surplus blank pages have been collapsed already. */
+    private blanksNormalized;
     private starting;
     /**
      * Browsers that ignored a kill.
@@ -167,6 +178,25 @@ export declare class SystemBrowserViewHost implements ElectronBrowserViewHost {
      */
     private forgetBrowserState;
     private ensureClient;
+    /**
+     * Take over a browser already serving this profile, instead of racing it.
+     *
+     * A previous DSH process leaves its browser running: the child handle died with that process, so
+     * nothing here knows about it, and `start()`'s cleanup branch is skipped because it keys on
+     * `this.child`. Launching then does something worse than fail — on Windows Chrome hands the
+     * request to the instance already holding the profile and exits 0, and that exit is read as a
+     * launch failure. The user is told to go kill the leftovers by hand, on every restart, which is
+     * exactly what was reported.
+     *
+     * The launch loop deliberately refuses to trust a `<profile>/DevToolsActivePort` left by a
+     * previous launch, and it is right to: a stale port number can be reused by something that is
+     * not a browser at all. What makes adoption safe HERE is that this runs BEFORE launching, on a
+     * file that lives inside this plugin's own profile directory — only a browser started with this
+     * `--user-data-dir` writes it — and the endpoint is then asked to identify itself.
+     * @param why - a short phrase for the log, naming which attempt this is.
+     * @returns a connected client for the running browser, or undefined when there is none.
+     */
+    private adoptRunningBrowser;
     /**
      * Launch the browser with a private profile and connect over CDP.
      *
@@ -184,6 +214,45 @@ export declare class SystemBrowserViewHost implements ElectronBrowserViewHost {
      * make the plugin fall back for no reason.
      */
     available(): boolean;
+    /**
+     * Every page the browser currently holds, including ones this plugin did not create.
+     *
+     * Chrome and Edge own their own page creation. A click on a link that opens a new page — or any
+     * `window.open` — produces a page the provider never asked for, and nothing reports it back.
+     * Those pages are real: they hold memory and stay until something closes them. Measured on a real
+     * window: four pages present while `dsh_browser_list_tabs` reported one.
+     *
+     * Discovery is already on at connection time (see the blank-page normalisation), so
+     * `Target.getTargets` also lists pages that existed before this client connected.
+     * @returns the browser's pages, or an empty list when it cannot answer.
+     */
+    /**
+     * Every page the browser holds that THIS HOST did not open.
+     *
+     * Chrome and Edge own their own page creation. A click on a link that opens a new page — or any
+     * `window.open` — produces a page the provider never asked for, and nothing reports it back.
+     * Those pages are real: they hold memory and stay until something closes them. Measured on a real
+     * window: four pages present while `dsh_browser_list_tabs` reported one.
+     *
+     * Pages this host opened are EXCLUDED here rather than deduplicated by the caller, because the
+     * caller cannot do it: the provider knows a tab by its own id, the carrier knows a page by its
+     * CDP target id, and the two never match. The first version returned everything and relied on the
+     * caller to filter, which reported the same page twice.
+     *
+     * Discovery is already on at connection time (see the blank-page normalisation), so
+     * `Target.getTargets` also lists pages that existed before this client connected.
+     * @returns the browser's pages that are not ours, or an empty list when it cannot answer.
+     */
+    listPages(): Promise<readonly CarrierPage[]>;
+    /**
+     * Close one page by the target id {@link listPages} reported.
+     *
+     * `Target.closeTarget` is the browser's own close, so it works for pages this plugin never
+     * created. The page may already be gone if the human closed it in the meantime — the caller
+     * asked for it to be closed and it is, so that is not an error.
+     * @param id - the CDP target id.
+     */
+    closePage(id: string): Promise<void>;
     createView(): ElectronViewHandle;
     destroyView(handle: ElectronViewHandle): void;
     /** Nothing to show: the browser owns its own windows. */
@@ -236,6 +305,37 @@ export declare class SystemBrowserViewHost implements ElectronBrowserViewHost {
     private ensureSession;
     /** Create and attach the target for one view. Serialised by {@link ensureSession}. */
     private buildSession;
+    /**
+     * Take an unclaimed blank page, if the browser has one to spare.
+     *
+     * "Unclaimed" is what matters: a blank page the plugin is already driving belongs to a view, and
+     * handing the same target to a second view would make two views share one page. The page kept by
+     * {@link normalizeBlankPages} is exactly the unclaimed one this is looking for.
+     * @param client - the connected browser.
+     * @returns the target id to reuse, or undefined when a new page has to be created.
+     */
+    private adoptBlankTarget;
+    /** Create one page, refusing to go on without an id. */
+    private createTarget;
+    /**
+     * Collapse the blank pages a freshly started browser comes with down to one.
+     *
+     * Chrome opens more than one page when it is given a URL on top of its own start page, and this
+     * is the browser's behaviour rather than a session restore: measured on a cleanly exited profile
+     * as well as a crashed one, both pages appear within a second of launch. There is nothing to
+     * configure away — by the time a client can talk to the browser, both already exist.
+     *
+     * Left alone the surplus page is invisible to the plugin's tab model and therefore unclosable
+     * through the tools, so it survives every navigation and accumulates for as long as the window
+     * lives. One is kept deliberately: {@link buildSession} adopts it instead of creating a third.
+     *
+     * `Target.setDiscoverTargets` has to come first. Without it the browser may omit pages that
+     * existed before this client connected — which is precisely the page that needs closing, and the
+     * reason the first attempt at this fix failed silently.
+     * @param client - the connected browser.
+     * @returns how many surplus blank pages were closed.
+     */
+    private normalizeBlankPages;
     /** Views whose session is being created right now, so a second caller waits for the first. */
     private readonly sessionBuilding;
     /** sessionId -> targetId, so a destroyed view can close the right page. */