dsh-builtin-browser 0.4.2 → 0.4.6

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

@@ -832,6 +832,7 @@ async function handle(op, msg) {
                 catch { /* not minimized */ }
                 win.window.focus();
                 let base64 = '';
+                let renderedSize;
                 try {
                     let image;
                     try {
@@ -856,6 +857,10 @@ async function handle(op, msg) {
                     }
                     if (w > 0 && h > 0 && (w !== size.width || h !== size.height))
                         image = image.resize({ width: w, height: h });
+                    // What the caller actually receives: after the downscale, not the captured size.
+                    // Recorded here because this is the last point that knows both.
+                    if (w > 0 && h > 0)
+                        renderedSize = { width: w, height: h };
                     const buf = wantFormat === 'jpeg' ? image.toJPEG(wantQuality) : image.toPNG();
                     if (wantFormat === 'jpeg')
                         mime = 'image/jpeg';
@@ -914,7 +919,12 @@ async function handle(op, msg) {
                 if (base64 === '') {
                     throw new Error('capture produced no image (view not painted)');
                 }
-                reply(msg.id, { ok: true, result: { base64, mime } });
+                // The measured size travels with the image. Without it the native path — which is the
+                // default self-hosted one — could never answer `browser_screenshot`'s width/height,
+                // because the seam's only channel was {base64, mime} and the provider had nothing to
+                // forward. The caller's `maxWidth`/`maxHeight` are applied here, so this is the only
+                // place that knows what came back.
+                reply(msg.id, { ok: true, result: { base64, mime, width: renderedSize?.width, height: renderedSize?.height } });
                 return;
             }
             case 'download': {

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

@@ -20,8 +20,13 @@ export interface ElectronBrowserViewHost {
      * Create a new browser view and return a handle to its webContents-like
      * surface. The host owns windowing (adding the view to the window, sizing,
      * removal); the provider owns CDP-driven behavior.
+     * @param owner - the conversation this view serves. A host shared by several conversations
+     *   needs it to keep one conversation's page out of another's; a host with one conversation per
+     *   process may ignore it. It is per VIEW and not per host on purpose: the desktop's host is a
+     *   single instance that every conversation runs through, so an owner held there would be one
+     *   conversation's id applied to all of them.
      */
-    createView(): ElectronViewHandle;
+    createView(owner?: string): ElectronViewHandle;
     /**
      * Destroy a view created by this host. Called on session close; idempotent
      * for an already-destroyed view.
@@ -61,6 +66,18 @@ export interface ElectronBrowserViewHost {
      * of failing only at first use.
      */
     available?(): boolean;
+    /**
+     * Tell the human that a toolbar action the agent could not complete has failed.
+     *
+     * Optional. Declared rather than reached through a cast because this is what issue #16 was:
+     * the call used to be unbound, so `this` inside the host's implementation was undefined and
+     * its first statement threw — inside an async catch, which turned it into an unhandled
+     * rejection that took the whole DSH process down. A declared member is checkable; a cast is
+     * not.
+     * @param windowId - the window the action came from.
+     * @param message - what to show the human.
+     */
+    notifyUserActionError?(windowId: string, message: string): void;
     /**
      * Optional: associate a view with a window group. Views grouped under the
      * same `windowId` share one window (one window per browser session); a host
@@ -96,7 +113,12 @@ export interface ElectronBrowserViewHost {
      * (settings: ui.closeWithSession) has to be asked for explicitly there.
      * @returns a promise that settles once the release was attempted.
      */
-    releasePage?(): Promise<void>;
+    /**
+     * Release this carrier's browser pages for one conversation.
+     * @param owner - the conversation whose pages to close. Omit to close every conversation's,
+     *   which is only correct from a teardown that is itself global.
+     */
+    releasePage?(owner?: string): Promise<void>;
     /**
      * Fold the carrier's presentation away while keeping the page alive.
      *
@@ -175,6 +197,42 @@ export interface ElectronViewHandle {
      * then behaves exactly as before.
      */
     focus?(): Promise<void>;
+    /**
+     * Save a URL straight to disk, when the backing view can do that itself.
+     *
+     * Optional. Declared here rather than reached through a structural cast at the call site:
+     * a cast tells the compiler nothing, so a host that implements the interface without this
+     * method compiles and then silently does nothing.
+     * @param url - the URL to fetch.
+     * @param savePath - where to write it.
+     */
+    download?(url: string, savePath: string): Promise<void>;
+    /**
+     * Export this view's cookies. Optional; see {@link download} for why it is declared.
+     * @returns the cookies, scoped to the view's own page.
+     */
+    flushAuth?(): Promise<readonly ExportedCookie[]>;
+    /**
+     * Import cookies into this view. Optional.
+     * @param cookies - the cookies to write.
+     * @returns how many were accepted.
+     */
+    restoreAuth?(cookies: readonly ExportedCookie[]): Promise<number>;
+    /**
+     * Capture this view natively, returning the image and its measured size.
+     *
+     * Optional. The size is part of the contract because the caller's own tool schema declares
+     * `width`/`height`; a host that can measure the image should say so here rather than leaving
+     * the provider to guess.
+     * @param opts - format, quality and downscale bounds.
+     * @returns the encoded image and the pixel size the caller will receive.
+     */
+    capture?(opts?: ScreenshotOptions): Promise<{
+        base64: string;
+        mime: string;
+        width?: number;
+        height?: number;
+    }>;
 }
 /** Provider config: navigation admission defaults and snapshot caps. */
 export interface ElectronBrowserProviderConfig {
@@ -583,6 +641,8 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
     screenshot(session: BrowserSessionId, request?: BrowserScreenshotRequest, signal?: AbortSignal): Promise<{
         readonly dataUrl: string;
         readonly path?: string;
+        readonly width?: number;
+        readonly height?: number;
     }>;
     /**
      * Build the data URL and optionally write the image to disk. The caller's

package/lib/browser-electron/provider.js

@@ -343,7 +343,10 @@ export class ElectronBrowserProvider {
      * in the window title so a human can tell which task's page is visible.
      */
     open(label) {
-        const handle = this.host.createView();
+        // The label is the calling DSH task, and it is handed to the view as its owner: a host shared
+        // by several conversations (the desktop's) keeps one conversation's page out of another's on
+        // the strength of it, so it is not decoration.
+        const handle = this.host.createView(label);
         const id = `browser:${randomUUID()}`;
         // Group the session's views under its own window (one window per
         // session), carrying the label for the window title. Hosts without
@@ -2289,7 +2292,13 @@ export class ElectronBrowserProvider {
             if (shot.base64 === '') {
                 throw new BrowserError('browser: capture returned an empty image (view not painted); retry shortly', 'BROWSER_SCREENSHOT_FAILED');
             }
-            return this.saveScreenshot(shot.base64, request?.savePath, shot.mime ?? 'image/png');
+            return this.saveScreenshot(shot.base64, request?.savePath, shot.mime ?? 'image/png', 
+            // The child measured these after applying any downscale, and they describe the image
+            // the caller receives. Without them this path — the default self-hosted one — could
+            // never answer the width/height its own tool schema declares.
+            shot.width !== undefined && shot.height !== undefined
+                ? { width: shot.width, height: shot.height }
+                : undefined);
         }
         // Fallback: a handle without a native capture() (the sidebar, or an installed Chrome
         // or Edge) uses CDP; full-page needs `captureBeyondViewport`, which capturePage lacks.
@@ -2403,9 +2412,15 @@ export class ElectronBrowserProvider {
         if (store === undefined)
             return;
         // The settings panel can switch recording off at runtime; the static config
-        // only supplies the startup default.
-        if (this.settingsSource !== undefined && !this.settingsSource().history.enabled)
-            return;
+        // only supplies the startup default. The RETENTION limits are read here too: they were
+        // parsed and stored but never handed to the store, so editing maxEntries or maxAgeDays in
+        // the file changed nothing — the switch worked and the numbers beside it did not.
+        if (this.settingsSource !== undefined) {
+            const live = this.settingsSource().history;
+            if (!live.enabled)
+                return;
+            store.updateLimits({ maxEntries: live.maxEntries, maxAgeDays: live.maxAgeDays });
+        }
         void handleSendEvaluate(handle, 'location.href + "\\u0000" + (document.title || "")')
             .then(result => {
             if (!result.ok || typeof result.value !== 'string')
@@ -2537,7 +2552,9 @@ export class ElectronBrowserProvider {
             // the views above; the desktop's sidebar does not, so it is asked explicitly
             // — and its cookies plus the browsing history outlive the page either way.
             if (this.settingsSource !== undefined && this.settingsSource().ui.closeWithSession) {
-                void this.host.releasePage?.().catch(() => undefined);
+                // Named, because one host serves every conversation: an unnamed release would end the
+                // pages of conversations that are still running.
+                void this.host.releasePage?.(existing.label).catch(() => undefined);
             }
         }
         return Promise.resolve();
@@ -2559,7 +2576,7 @@ export class ElectronBrowserProvider {
     }
     /** Append a fresh tab and make it active. */
     newTab(s) {
-        const handle = this.host.createView();
+        const handle = this.host.createView(s.label);
         // Same window as the session's other tabs.
         this.host.groupView?.(handle, s.id, s.label);
         s.tabs.push({ id: `tab:${randomUUID()}`, handle });
@@ -2664,11 +2681,10 @@ export class ElectronBrowserProvider {
         const message = `action ${action.type} failed: ${String(error)}`;
         let reported = false;
         try {
-            const host = this.host;
-            const notify = host.notifyUserActionError;
-            if (typeof notify === 'function') {
-                // Called on its owner: an unbound call here kills the host process.
-                notify.call(host, action.windowId, message);
+            const notify = this.host.notifyUserActionError?.bind(this.host);
+            if (notify !== undefined) {
+                // Bound at the call: an unbound call here kills the host process (issue #16).
+                notify(action.windowId, message);
                 reported = true;
             }
         }

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

@@ -487,9 +487,11 @@ class ElectronChildClient {
     /**
      * Drop the escalation kill once there is nothing left for it to target.
      *
-     * Without this the timer would keep the parent's event loop alive for its full grace period
-     * after exactly the ordinary exit it was armed to catch as the bad case — and the child does
-     * not need killing once `fail()` has run for it.
+     * Called on the paths where the child is known to be gone — after an observed exit, and on
+     * release. It is deliberately NOT called from `fail()`: a dead socket says nothing about the
+     * process on the other end, and the timer exists for exactly the case where the child ignores
+     * the socket closing. Clearing it there disarmed the only escalation there was, which is how
+     * a child that ignored its socket could outlive dispose() and keep holding the profile.
      */
     clearKillGrace() {
         if (this.killGraceTimer === undefined)
@@ -515,7 +517,11 @@ class ElectronChildClient {
         // kept a live timer until it fired (harmless, but it is a dangling timer in a process
         // that may be shutting down).
         this.clearHelloTimer();
-        this.clearKillGrace();
+        // NOT clearKillGrace(): this path runs when the SOCKET died, which says nothing about
+        // whether the process did. Clearing the escalation here disarmed it for exactly the case it
+        // exists for — a child that ignores its socket closing — so dispose() could return with the
+        // child still running and still holding the profile. The timer clears itself when the child
+        // exits, and `kill()` replaces it on an explicit release.
         // Tag every failure as "host gone" so the view layer can tell a dead host
         // apart from a page-level error and rebuild against a fresh child.
         const wrapped = err instanceof HostGoneError ? err : new HostGoneError(err.message);
@@ -1245,11 +1251,18 @@ class DeferredRemoteView {
     materializeOnce() {
         if (this.materialized === undefined) {
             const pending = this.materialize();
-            this.materialized = pending.catch(error => {
-                if (this.materialized === pending)
+            // Compare against the promise actually stored — the derived one — not against `pending`.
+            // Storing `pending.catch(...)` and comparing `this.materialized === pending` compared two
+            // different objects, so the test was never true and the reset never ran: a materialization
+            // that failed with anything other than a HostGoneError (the child alive but not answering
+            // a ping, say) poisoned the handle for good, and the retry the comment below promises was
+            // unreachable.
+            const guarded = pending.catch(error => {
+                if (this.materialized === guarded)
                     this.materialized = undefined;
                 throw error;
             });
+            this.materialized = guarded;
         }
         return this.materialized;
     }

package/lib/browser-electron/rpc-ops.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The RPC operation vocabulary, in one place.
+ *
+ * The child (`host-main.ts`) switches on these names and the parent (`remote-host.ts`) sends
+ * them. Both spelled them out independently and nothing connected the two, so a rename on one
+ * side compiled fine and failed at run time as "unknown op" — and this pair has already
+ * produced one silent failure of that shape (`noteStartFailure`'s dedupe comparison, which was
+ * never true and meant a log line that never appeared).
+ *
+ * The lists are the source of truth for a test that reads both switch statements and asserts
+ * they agree, which is what makes a one-sided rename fail loudly instead of at run time.
+ */
+/** Operations the parent asks the child to perform. */
+export declare const RPC_OPS: readonly ["ping", "createView", "destroyView", "showView", "groupView", "focus", "command", "capture", "download", "flushAuth", "restoreAuth", "navigate", "new-tab", "activate", "close", "back", "forward", "reload", "userActionError"];
+/** Notifications the child sends the parent, which carry no reply. */
+export declare const RPC_NOTIFICATIONS: readonly ["userAction", "viewClosed"];
+/** One operation name. */
+export type RpcOp = (typeof RPC_OPS)[number];

package/lib/browser-electron/rpc-ops.js

@@ -0,0 +1,36 @@
+/**
+ * The RPC operation vocabulary, in one place.
+ *
+ * The child (`host-main.ts`) switches on these names and the parent (`remote-host.ts`) sends
+ * them. Both spelled them out independently and nothing connected the two, so a rename on one
+ * side compiled fine and failed at run time as "unknown op" — and this pair has already
+ * produced one silent failure of that shape (`noteStartFailure`'s dedupe comparison, which was
+ * never true and meant a log line that never appeared).
+ *
+ * The lists are the source of truth for a test that reads both switch statements and asserts
+ * they agree, which is what makes a one-sided rename fail loudly instead of at run time.
+ */
+/** Operations the parent asks the child to perform. */
+export const RPC_OPS = [
+    'ping',
+    'createView',
+    'destroyView',
+    'showView',
+    'groupView',
+    'focus',
+    'command',
+    'capture',
+    'download',
+    'flushAuth',
+    'restoreAuth',
+    'navigate',
+    'new-tab',
+    'activate',
+    'close',
+    'back',
+    'forward',
+    'reload',
+    'userActionError',
+];
+/** Notifications the child sends the parent, which carry no reply. */
+export const RPC_NOTIFICATIONS = ['userAction', 'viewClosed'];

package/lib/browser-electron/settings-route.d.ts

@@ -9,14 +9,14 @@
  * It is NOT authentication, and cannot be. The plugin has no credential to check: DSH hands
  * plugin routes the raw request (`packages/host/webserver/src/index.ts` registers handlers with
  * no gate of its own), so the strongest same-origin evidence available is what a browser
- * reliably sends — `Sec-Fetch-Site`, plus `Origin` on every write, same-origin included.
+ * reliably sends.
  *
  * What that buys and what it does not:
- *   - a plain HTTP client (curl, a script, another process) cannot WRITE any more, because it
- *     sends no `Origin`;
- *   - a page of THIS origin still can, because a browser sending a same-origin write looks
- *     exactly like the panel. That is inherent to exposing an HTTP endpoint at all, and it is
- *     why the settings panel's own text must not promise a lock that does not exist.
+ *   - a plain HTTP client (curl, a script, another process) cannot WRITE, because it sends no
+ *     `user-agent` and no `accept-language`;
+ *   - a page of THIS origin can, because a browser sending a same-origin write looks exactly
+ *     like the panel. That is inherent to exposing an HTTP endpoint at all, and it is why the
+ *     settings panel's own text must not promise a lock that does not exist.
  */
 import type { IncomingMessage } from 'node:http';
 /**

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

@@ -1,3 +1,20 @@
+/** The shell's own URL schemes. Only the shell can mint a document on one of these. */
+const APP_SCHEMES = ['dsh-app:', 'dsh-desktop:'];
+/**
+ * The scheme of a header value, when it names a URL.
+ * @param value - a raw header value.
+ * @returns the scheme, or undefined when the value is absent, opaque or unparseable.
+ */
+function schemeOf(value) {
+    if (value === '' || value === 'null')
+        return undefined;
+    try {
+        return new URL(value).protocol;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Whether a request may touch the settings document.
  * @param request - the incoming request.
@@ -5,22 +22,45 @@
  * @returns whether the request is admitted.
  */
 export function sameOrigin(request, writing = false) {
+    const origin = String(request.headers.origin ?? '').trim();
     const site = String(request.headers['sec-fetch-site'] ?? '').toLowerCase();
+    // A shell URL, in either the Origin or the referrer: the strongest evidence there is.
+    if (APP_SCHEMES.includes(schemeOf(origin) ?? ''))
+        return true;
+    if (APP_SCHEMES.includes(schemeOf(String(request.headers.referer ?? '')) ?? ''))
+        return true;
+    // MEASURED on the running desktop, and what three earlier attempts each guessed wrong: a
+    // request from the shell's own settings panel carries NO origin, NO sec-fetch-site and NO
+    // referer. It is not "dsh-app://app" and it is not "null" — the headers are simply absent,
+    // because Chromium attaches no cross-origin metadata to a request leaving a custom scheme.
+    //
+    // So the rule for that shape cannot be "a request without an Origin is a script", which is
+    // what refused every desktop save, and it cannot lean on `Sec-Fetch-Site` either. It has to
+    // test what a hand-rolled client does not send:
+    //   - a renderer sends a full Mozilla-compatible `user-agent` AND an `accept-language`;
+    //   - curl sends neither unless told to, and a local process that forges both can also read
+    //     the settings document directly — it sits readable on disk, as the panel's own text
+    //     says. This was never the boundary it looked like.
+    if (origin === '') {
+        const agent = String(request.headers['user-agent'] ?? '');
+        const language = String(request.headers['accept-language'] ?? '');
+        if (/^Mozilla\/5\.0/.test(agent) && language !== '')
+            return true;
+        // Reads stay open: they return the document the panel is already showing, and refusing them
+        // would only break hand-inspection of a file that sits readable on disk anyway.
+        return !writing;
+    }
     // `cross-site` is another origin entirely; `same-site` is another origin of the same site
     // (a.example.com -> b.example.com), which is not this panel either. Both are refused.
     if (site === 'cross-site' || site === 'same-site')
         return false;
-    const origin = String(request.headers.origin ?? '').trim();
-    // `Origin: null` is what a sandboxed or opaque-origin document sends. Never this panel.
+    // `Origin: null` is a sandboxed or opaque-origin document. Never this panel.
     if (origin === 'null')
         return false;
-    // Reads are let through without an Origin: they return the document the panel is already
-    // showing, and refusing them would only break hand-inspection of a file that sits readable
-    // on disk anyway. Writes are not: a browser always sends `Origin` on one.
-    if (origin === '')
-        return !writing;
     try {
-        return new URL(origin).host.toLowerCase() === String(request.headers.host ?? '').trim().toLowerCase();
+        const parsed = new URL(origin);
+        // The host comparison is for http(s), where a page and its route share one host.
+        return parsed.host.toLowerCase() === String(request.headers.host ?? '').trim().toLowerCase();
     }
     catch {
         return false;

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

@@ -75,18 +75,42 @@ const SETTINGS_WHEN_UNREADABLE = {
  * @returns a valid channel.
  */
 function resolveChannel(value) {
-    return value === 'chrome' || value === 'edge' || value === 'auto' || value === 'bundled'
+    return value === 'chrome' || value === 'edge' || value === 'auto' || value === 'bundled' || value === 'sidebar'
         ? value
         : DEFAULT_SETTINGS.browser.channel;
 }
 /** Coerce one positive-integer field, keeping the default when invalid. */
 function count(value, fallback) {
-    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return fallback;
+    const floored = Math.floor(value);
+    // A fractional value below 1 floors to 0, and 0 is not "very few" in either place these are
+    // used: as a history entry cap it means `slice(len - 0)`, i.e. keep nothing, so a hand-typed
+    // `0.5` silently wiped the history file on the next rewrite. Anything that survives the
+    // floor has to still be a usable limit.
+    return floored > 0 ? floored : fallback;
 }
 /** Read one nested section of an unknown document, or an empty object. */
+/**
+ * Read one section of the document, distinguishing ABSENT from UNREADABLE.
+ *
+ * Absent (the key is not there at all) is a document written before the section existed, and
+ * the defaults apply — that is the documented behaviour. Present-but-not-an-object
+ * (`"actions": false`, `null` from a truncated write, a stray string) is a document this code
+ * cannot read, and returning `{}` for it made every gate inside look absent, so each one took
+ * its permissive default. A whole section mistyped is exactly the shape a careless hand edit
+ * produces, and it opened every capability the section was there to bound.
+ * @param source - the parsed document.
+ * @param key - the section name.
+ * @returns the section, or undefined when it is present but not an object.
+ */
 function section(source, key) {
     const value = source[key];
-    return typeof value === 'object' && value !== null ? value : {};
+    if (value === undefined)
+        return {};
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
 }
 /**
  * Resolve a raw settings document (already parsed, shape unknown) into the full
@@ -104,25 +128,42 @@ export function resolveSettings(raw) {
     const credentials = section(source, 'credentials');
     const browser = section(source, 'browser');
     const actions = section(source, 'actions');
+    // A section that is present but unreadable refuses its gates rather than defaulting them
+    // open. The rest of a broken section keeps its defaults: refusing history or presentation
+    // would punish the user for a bad file without protecting anything.
+    const credentialsUsable = credentials ?? {};
+    const actionsUsable = actions ?? {};
     return {
         history: {
-            enabled: bool(history.enabled, DEFAULT_SETTINGS.history.enabled),
-            maxEntries: count(history.maxEntries, DEFAULT_SETTINGS.history.maxEntries),
-            maxAgeDays: count(history.maxAgeDays, DEFAULT_SETTINGS.history.maxAgeDays),
+            enabled: bool(history?.enabled, DEFAULT_SETTINGS.history.enabled),
+            maxEntries: count(history?.maxEntries, DEFAULT_SETTINGS.history.maxEntries),
+            maxAgeDays: count(history?.maxAgeDays, DEFAULT_SETTINGS.history.maxAgeDays),
         },
-        cookies: { persist: bool(cookies.persist, DEFAULT_SETTINGS.cookies.persist) },
+        cookies: { persist: bool(cookies?.persist, DEFAULT_SETTINGS.cookies.persist) },
         ui: {
-            autoExpandOnce: bool(ui.autoExpandOnce, DEFAULT_SETTINGS.ui.autoExpandOnce),
-            closeWithSession: bool(ui.closeWithSession, DEFAULT_SETTINGS.ui.closeWithSession),
-            virtualCursor: bool(ui.virtualCursor, DEFAULT_SETTINGS.ui.virtualCursor),
+            autoExpandOnce: bool(ui?.autoExpandOnce, DEFAULT_SETTINGS.ui.autoExpandOnce),
+            closeWithSession: bool(ui?.closeWithSession, DEFAULT_SETTINGS.ui.closeWithSession),
+            virtualCursor: bool(ui?.virtualCursor, DEFAULT_SETTINGS.ui.virtualCursor),
+        },
+        vision: { strategy: vision?.strategy === 'nonVisual' ? 'nonVisual' : DEFAULT_SETTINGS.vision.strategy },
+        browser: { channel: resolveChannel(browser?.channel) },
+        credentials: {
+            // `gate` returns false for anything present-and-not-a-boolean, so an unreadable section
+            // is refused here for free: the section itself is the "present but wrong" value.
+            allowRead: credentials === undefined
+                ? false
+                : gate(credentialsUsable.allowRead, DEFAULT_SETTINGS.credentials.allowRead),
         },
-        vision: { strategy: vision.strategy === 'nonVisual' ? 'nonVisual' : DEFAULT_SETTINGS.vision.strategy },
-        browser: { channel: resolveChannel(browser.channel) },
-        credentials: { allowRead: gate(credentials.allowRead, DEFAULT_SETTINGS.credentials.allowRead) },
         actions: {
-            allowExecute: gate(actions.allowExecute, DEFAULT_SETTINGS.actions.allowExecute),
-            allowDownload: gate(actions.allowDownload, DEFAULT_SETTINGS.actions.allowDownload),
-            allowCredentialWrite: gate(actions.allowCredentialWrite, DEFAULT_SETTINGS.actions.allowCredentialWrite),
+            allowExecute: actions === undefined
+                ? false
+                : gate(actionsUsable.allowExecute, DEFAULT_SETTINGS.actions.allowExecute),
+            allowDownload: actions === undefined
+                ? false
+                : gate(actionsUsable.allowDownload, DEFAULT_SETTINGS.actions.allowDownload),
+            allowCredentialWrite: actions === undefined
+                ? false
+                : gate(actionsUsable.allowCredentialWrite, DEFAULT_SETTINGS.actions.allowCredentialWrite),
         },
     };
 }

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

@@ -37,7 +37,7 @@ export type BrowserLauncher = (path: string, args: readonly string[]) => ReturnT
 import { spawn } from 'node:child_process';
 import type { ElectronBrowserViewHost, ElectronViewHandle } from './provider.js';
 /** Which browser the user asked for. */
-export type BrowserChannel = 'bundled' | 'chrome' | 'edge' | 'auto';
+export type BrowserChannel = 'bundled' | 'chrome' | 'edge' | 'auto' | 'sidebar';
 /** A resolved browser installation. */
 export interface DetectedBrowser {
     /** Which product this is. */
@@ -157,6 +157,15 @@ export declare class SystemBrowserViewHost implements ElectronBrowserViewHost {
      * @returns true when it answered.
      */
     private probeClient;
+    /**
+     * Forget which browser issued what, after that browser is gone.
+     *
+     * The two maps must move together: `views` maps a view id to a session id and `sessions`
+     * maps a session id to a target id, so clearing one alone leaves a mapping the next command
+     * will act on. Every path that abandons a browser calls this rather than spelling the pair
+     * out — four separate copies is how the third one came to be missing.
+     */
+    private forgetBrowserState;
     private ensureClient;
     /**
      * Launch the browser with a private profile and connect over CDP.
@@ -179,10 +188,23 @@ export declare class SystemBrowserViewHost implements ElectronBrowserViewHost {
     destroyView(handle: ElectronViewHandle): void;
     /** Nothing to show: the browser owns its own windows. */
     showView(): void;
-    /** Same as {@link showView}. */
-    presentView(): Promise<void>;
-    /** The browser owns window grouping. */
-    groupView(): void;
+    /**
+     * Bring the target's page to the front, then report success.
+     *
+     * The comment on `focus` below used to say this was impossible — that raising the page needs
+     * `Page.bringToFront` on a target session, which is a view-level concern the host cannot
+     * reach. The handle this method is handed IS that view, and it can send commands, so the
+     * capability was here all along; it just was not used. Without it `presentView` was an empty
+     * async method, so the provider's whole presentation barrier — the one that stops
+     * `Input.*` from being silently dropped for a view with no display surface, and reports
+     * `BROWSER_VIEW_NOT_PRESENTED` when it cannot present — never ran on this carrier.
+     *
+     * A failure is swallowed rather than propagated: a real Chrome window that refuses to come
+     * forward is not a reason to refuse the click that follows. The barrier exists to order the
+     * two, and the order is honoured either way.
+     * @param handle - the view to present.
+     */
+    presentView(handle: ElectronViewHandle): Promise<void>;
     /**
      * Best effort at bringing the browser's window forward.
      *
@@ -196,10 +218,6 @@ export declare class SystemBrowserViewHost implements ElectronBrowserViewHost {
      * view-level concern and not available to the host.
      */
     focus(): Promise<void>;
-    /** The browser reports its own window lifecycle. */
-    onUserAction(): void;
-    /** The browser reports its own window lifecycle. */
-    onViewClosed(): void;
     /**
      * Close the browser we launched, if we ever launched one.
      *
@@ -216,6 +234,10 @@ export declare class SystemBrowserViewHost implements ElectronBrowserViewHost {
      * a second copy of that rule.
      */
     private ensureSession;
+    /** Create and attach the target for one view. Serialised by {@link ensureSession}. */
+    private buildSession;
+    /** 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. */
     private readonly sessions;
 }