dsh-builtin-browser 0.2.0 → 0.3.0

package/lib/browser-electron/desktop-bridge-host.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Desktop-sidebar browser host: drive the page the desktop shell shows in its
+ * sidebar, instead of spawning a second, parallel Electron window.
+ *
+ * WHY
+ * The plugin runs inside the desktop's Node-mode host, where there is no Electron
+ * API — which is why it self-hosts a whole browser today. The shell, however, can
+ * own views, and its sidebar already displays real web pages. This host borrows
+ * that page over the shell's bridge (see apps/desktop/bridge/plugin-browser-bridge.js),
+ * so the agent and the human end up on ONE page instead of two.
+ *
+ * CONTRACT
+ * It implements the same `ElectronBrowserViewHost` seam the self-hosted host does,
+ * so the provider, the tools, browsing history, the synthetic cursor and the
+ * teardown rules are all unchanged: only the carrier differs. Everything is
+ * lazily materialized — a fresh shell has no sidebar guest until something asks
+ * for a page, and the bridge creates one on demand.
+ *
+ * FALLBACK
+ * `discover()` returns undefined whenever the shell offers no usable bridge
+ * (older desktop build, plain `dsh web`, bridge not started), and the entry point
+ * then keeps the self-hosted Electron it has always used.
+ * @module dsh-browser/browser-electron/desktop-bridge-host
+ */
+import type { ElectronBrowserViewHost, ElectronViewHandle } from './provider.js';
+import type { BrowserUserAction } from './provider.js';
+/** Absolute path of the endpoint file the shell writes. */
+export declare function bridgeEndpointPath(): string;
+/**
+ * The desktop sidebar, presented as a browser view host.
+ *
+ * One sidebar exists per shell window, so every view this host hands out refers
+ * to the same guest: the provider keeps its tab bookkeeping, and the tabs simply
+ * share the visible page. That is the intended behaviour for this carrier — the
+ * point is a single page both parties can see.
+ */
+export declare class DesktopBridgeViewHost implements ElectronBrowserViewHost {
+    private readonly endpoint;
+    private readonly connection;
+    private readonly views;
+    /**
+     * Guests whose view is gone but whose page may still be open in the sidebar.
+     *
+     * The provider destroys its view handles before it asks for a release, so the
+     * mapping is dropped by then — keeping the guest ids here is what lets us close
+     * only our own tabs when several sessions are running (requirements §4: each
+     * session gets its own page).
+     */
+    private readonly orphaned;
+    private userActionHandler;
+    /**
+     * @param endpoint - the shell's published bridge endpoint.
+     */
+    private constructor();
+    /**
+     * Find a usable desktop bridge, if this surface has one.
+     *
+     * A stale endpoint (a shell that already exited, leaving its file behind) is
+     * rejected here rather than surfacing later as a mysterious ECONNREFUSED: the
+     * caller falls back to self-hosting, which always works.
+     * @returns the host, or undefined when no bridge is available.
+     */
+    static discover(): Promise<DesktopBridgeViewHost | undefined>;
+    /** Whether this host can back views: the bridge already answered `list`. */
+    available(): boolean;
+    /**
+     * The guest id backing a view, materialized on first use.
+     *
+     * The sidebar browser is itself a multi-tab surface, so each view gets its own
+     * tab's guest: the provider's tab bookkeeping then maps onto real tabs the human
+     * can see and switch between. Two rules keep that honest:
+     *   - a cached guest is used as-is: probing it first cost a round-trip on every
+     *     command, so liveness is established by the command failing instead;
+     *   - a fresh view takes an unclaimed guest, growing the tab strip only when
+     *     every existing guest is already spoken for.
+     * @param viewId - the view whose guest is wanted.
+     * @param url - address to use when a sidebar browser has to be opened first.
+     */
+    private guestFor;
+    /**
+     * Ask for at least `count` sidebar tabs and return their guest ids.
+     * @param count - minimum number of tabs.
+     */
+    private guestIds;
+    createView(): ElectronViewHandle;
+    destroyView(handle: ElectronViewHandle): void;
+    /**
+     * Nothing to show: the sidebar is already on screen, and showing it again is
+     * the shell's business (it owns the tab strip and the visibility toggle).
+     */
+    showView(): void;
+    /** Same as {@link showView}: the page is already presented by the shell. */
+    presentView(): Promise<void>;
+    /**
+     * The shell owns window grouping, and one sidebar serves every view, so there
+     * is nothing to record here. (It must not write a placeholder guest id either:
+     * a view whose guest is not yet materialized has to stay absent from the map,
+     * or the first real command would be sent to the placeholder.)
+     */
+    groupView(): void;
+    /** Focus is the shell's to manage, and there is no separate window to raise. */
+    focus(): Promise<void>;
+    onUserAction(handler: (action: BrowserUserAction) => void): void;
+    /** The shell reports its own window lifecycle; nothing to subscribe to here. */
+    onViewClosed(): void;
+    /**
+     * Release the sidebar's browser pages (requirements §3, `ui.closeWithSession`).
+     *
+     * Destroying our own view handles is not enough on this carrier: the sidebar
+     * belongs to the shell and would happily keep the page (and its renderer) alive.
+     * Closing the tabs is what actually ends the page — and only the page: cookies
+     * live in the partition, history on disk, so both survive.
+     * @returns a promise that settles once the shell has been asked.
+     */
+    releasePage(): Promise<void>;
+    /**
+     * Fold the sidebar away without ending the page (`ui.autoExpandOnce` is off, or
+     * the caller wants the screen back while work continues).
+     * @returns a promise that settles once the shell has been asked.
+     */
+    collapse(): Promise<void>;
+    /** No child process of our own to stop; close the shared connection instead. */
+    dispose(): void;
+}

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

@@ -0,0 +1,297 @@
+/**
+ * Desktop-sidebar browser host: drive the page the desktop shell shows in its
+ * sidebar, instead of spawning a second, parallel Electron window.
+ *
+ * WHY
+ * The plugin runs inside the desktop's Node-mode host, where there is no Electron
+ * API — which is why it self-hosts a whole browser today. The shell, however, can
+ * own views, and its sidebar already displays real web pages. This host borrows
+ * that page over the shell's bridge (see apps/desktop/bridge/plugin-browser-bridge.js),
+ * so the agent and the human end up on ONE page instead of two.
+ *
+ * CONTRACT
+ * It implements the same `ElectronBrowserViewHost` seam the self-hosted host does,
+ * so the provider, the tools, browsing history, the synthetic cursor and the
+ * teardown rules are all unchanged: only the carrier differs. Everything is
+ * lazily materialized — a fresh shell has no sidebar guest until something asks
+ * for a page, and the bridge creates one on demand.
+ *
+ * FALLBACK
+ * `discover()` returns undefined whenever the shell offers no usable bridge
+ * (older desktop build, plain `dsh web`, bridge not started), and the entry point
+ * then keeps the self-hosted Electron it has always used.
+ * @module dsh-browser/browser-electron/desktop-bridge-host
+ */
+import { BridgeConnection } from './bridge-connection.js';
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+/** Absolute path of the endpoint file the shell writes. */
+export function bridgeEndpointPath() {
+    const home = process.env.DSH_HOME ?? join(homedir(), '.dsh');
+    return join(home, 'dsh-builtin-browser-bridge.json');
+}
+/**
+ * Whether a command failed because the page is no longer there (as opposed to
+ * failing on its own merits). Only these are worth retrying on a fresh guest.
+ * @param error - the failure to classify.
+ */
+function isGuestGone(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /guest \d+ is not available|sidebar unavailable|did not create a browser guest/i.test(message);
+}
+/**
+ * The desktop sidebar, presented as a browser view host.
+ *
+ * One sidebar exists per shell window, so every view this host hands out refers
+ * to the same guest: the provider keeps its tab bookkeeping, and the tabs simply
+ * share the visible page. That is the intended behaviour for this carrier — the
+ * point is a single page both parties can see.
+ */
+export class DesktopBridgeViewHost {
+    endpoint;
+    connection;
+    views = new Map();
+    /**
+     * Guests whose view is gone but whose page may still be open in the sidebar.
+     *
+     * The provider destroys its view handles before it asks for a release, so the
+     * mapping is dropped by then — keeping the guest ids here is what lets us close
+     * only our own tabs when several sessions are running (requirements §4: each
+     * session gets its own page).
+     */
+    orphaned = new Set();
+    userActionHandler;
+    /**
+     * @param endpoint - the shell's published bridge endpoint.
+     */
+    constructor(endpoint) {
+        this.endpoint = endpoint;
+        this.connection = new BridgeConnection(endpoint);
+    }
+    /**
+     * Find a usable desktop bridge, if this surface has one.
+     *
+     * A stale endpoint (a shell that already exited, leaving its file behind) is
+     * rejected here rather than surfacing later as a mysterious ECONNREFUSED: the
+     * caller falls back to self-hosting, which always works.
+     * @returns the host, or undefined when no bridge is available.
+     */
+    static async discover() {
+        let endpoint;
+        try {
+            const raw = JSON.parse(readFileSync(bridgeEndpointPath(), 'utf8'));
+            if (typeof raw.port !== 'number' || typeof raw.token !== 'string' || typeof raw.pid !== 'number')
+                return undefined;
+            endpoint = { port: raw.port, token: raw.token, pid: raw.pid, ...raw.updatedAt !== undefined ? { updatedAt: raw.updatedAt } : {} };
+        }
+        catch {
+            return undefined;
+        }
+        try {
+            // A throwaway connection for discovery: the adopted host opens its own, and a
+            // rejected endpoint must not leave a socket behind.
+            const probe = new BridgeConnection(endpoint);
+            try {
+                const answer = await probe.call({ op: 'list' }, 5_000);
+                return answer.ok === true ? new DesktopBridgeViewHost(endpoint) : undefined;
+            }
+            finally {
+                probe.close();
+            }
+        }
+        catch {
+            // Dead endpoint or an older bridge: self-hosting remains the answer.
+            return undefined;
+        }
+    }
+    /** Whether this host can back views: the bridge already answered `list`. */
+    available() {
+        return true;
+    }
+    /**
+     * The guest id backing a view, materialized on first use.
+     *
+     * The sidebar browser is itself a multi-tab surface, so each view gets its own
+     * tab's guest: the provider's tab bookkeeping then maps onto real tabs the human
+     * can see and switch between. Two rules keep that honest:
+     *   - a cached guest is used as-is: probing it first cost a round-trip on every
+     *     command, so liveness is established by the command failing instead;
+     *   - a fresh view takes an unclaimed guest, growing the tab strip only when
+     *     every existing guest is already spoken for.
+     * @param viewId - the view whose guest is wanted.
+     * @param url - address to use when a sidebar browser has to be opened first.
+     */
+    async guestFor(viewId, url) {
+        const existing = this.views.get(viewId);
+        // No liveness check here: verifying the cached guest cost a round-trip on every
+        // command. A guest that has gone away is detected by the command itself failing,
+        // and `createView`'s sendCommand then discards the cache and calls back in here.
+        if (existing !== undefined)
+            return existing;
+        // The browser tab must exist before its strip can be extended: `ensureSidebar`
+        // opens the sidebar (and, on a fresh shell, materializes the first guest).
+        const sidebar = await this.connection.call({
+            op: 'ensureSidebar',
+            ...url !== undefined ? { url } : {},
+        });
+        if (sidebar.ok !== true)
+            throw new Error(`dsh-builtin-browser: sidebar unavailable (${String(sidebar.error)})`);
+        const wanted = this.views.size + 1;
+        let ids = await this.guestIds(Math.max(1, wanted));
+        const taken = new Set(this.views.values());
+        let free = ids.find(id => !taken.has(id));
+        if (free === undefined) {
+            // Every tab is already driving something: the strip has to grow.
+            ids = await this.guestIds(ids.length + 1);
+            free = ids.find(id => !taken.has(id));
+        }
+        if (free === undefined)
+            throw new Error('dsh-builtin-browser: the sidebar reported no free browser tab');
+        this.views.set(viewId, free);
+        return free;
+    }
+    /**
+     * Ask for at least `count` sidebar tabs and return their guest ids.
+     * @param count - minimum number of tabs.
+     */
+    async guestIds(count) {
+        const answer = await this.connection.call({ op: 'ensureTabs', count });
+        if (answer.ok !== true)
+            throw new Error(`dsh-builtin-browser: could not open a sidebar tab (${String(answer.error)})`);
+        const ids = Array.isArray(answer.ids) ? answer.ids.map(Number).filter(Number.isFinite) : [];
+        if (ids.length === 0)
+            throw new Error('dsh-builtin-browser: the sidebar reported no browser tabs');
+        return ids;
+    }
+    createView() {
+        const viewId = randomUUID();
+        const navigateUrl = (method, params) => method === 'Page.navigate' ? String(params?.url ?? '') : undefined;
+        const run = async (guest, method, params) => {
+            const answer = await this.connection.call({ op: 'cdp', id: guest, method, params });
+            if (answer.ok !== true)
+                throw new Error(`dsh-builtin-browser: sidebar command failed: ${String(answer.error)}`);
+            // The bridge forwards whatever CDP answered; the seam expects an object.
+            return (answer.result ?? {});
+        };
+        return {
+            id: viewId,
+            sendCommand: async (method, params) => {
+                // No liveness probe up front. Checking first cost a whole round-trip on
+                // every command; instead the command runs and its failure is what triggers
+                // recovery. Only a genuinely missing guest is retried, so a real error (a
+                // bad selector, a timeout) still surfaces unchanged.
+                const url = navigateUrl(method, params);
+                let guest = await this.guestFor(viewId, url);
+                try {
+                    return await run(guest, method, params);
+                }
+                catch (error) {
+                    if (!isGuestGone(error))
+                        throw error;
+                    // The human closed the tab: the page is gone, so take a fresh one and
+                    // replay the command once. This is the "closing the interface ends the
+                    // session" rule, now paid for only when it actually happens.
+                    this.views.delete(viewId);
+                    guest = await this.guestFor(viewId, url);
+                    return await run(guest, method, params);
+                }
+            },
+        };
+    }
+    destroyView(handle) {
+        const guest = this.views.get(handle.id);
+        if (guest !== undefined) {
+            // Remember it: the page outlives our handle, and a later release must be able
+            // to name exactly the tabs this plugin opened.
+            this.orphaned.add(guest);
+            this.views.delete(handle.id);
+        }
+    }
+    /**
+     * Nothing to show: the sidebar is already on screen, and showing it again is
+     * the shell's business (it owns the tab strip and the visibility toggle).
+     */
+    showView() { }
+    /** Same as {@link showView}: the page is already presented by the shell. */
+    async presentView() { }
+    /**
+     * The shell owns window grouping, and one sidebar serves every view, so there
+     * is nothing to record here. (It must not write a placeholder guest id either:
+     * a view whose guest is not yet materialized has to stay absent from the map,
+     * or the first real command would be sent to the placeholder.)
+     */
+    groupView() { }
+    /** Focus is the shell's to manage, and there is no separate window to raise. */
+    async focus() { }
+    onUserAction(handler) {
+        this.userActionHandler = handler;
+    }
+    /** The shell reports its own window lifecycle; nothing to subscribe to here. */
+    onViewClosed() { }
+    /**
+     * Release the sidebar's browser pages (requirements §3, `ui.closeWithSession`).
+     *
+     * Destroying our own view handles is not enough on this carrier: the sidebar
+     * belongs to the shell and would happily keep the page (and its renderer) alive.
+     * Closing the tabs is what actually ends the page — and only the page: cookies
+     * live in the partition, history on disk, so both survive.
+     * @returns a promise that settles once the shell has been asked.
+     */
+    async releasePage() {
+        // Only our own tabs: the ids come from the views we handed out (and their
+        // orphans), never from "every webview currently visible". With two sessions
+        // live, releasing one must leave the other's page alone.
+        const mine = [...this.views.values(), ...this.orphaned];
+        this.views.clear();
+        this.orphaned.clear();
+        // Nothing of ours is open: release nothing. Falling through to an unfiltered
+        // release here would close tabs a human opened, or another session's page.
+        if (mine.length === 0)
+            return;
+        let titles;
+        try {
+            const answer = await this.connection.call({ op: 'list' }, 5_000);
+            const sidebar = Array.isArray(answer.sidebar) ? answer.sidebar : [];
+            titles = sidebar
+                .filter(guest => mine.includes(Number(guest.id)))
+                .map(guest => String(guest.title ?? ''))
+                .filter(title => title !== '');
+        }
+        catch {
+            // Could not read the titles back; releasing nothing is safer than closing
+            // tabs that belong to somebody else.
+            return;
+        }
+        if (titles.length === 0)
+            return;
+        try {
+            await this.connection.call({ op: 'closeSidebarBrowser', titles }, 10_000);
+        }
+        catch {
+            // Best effort: the setting expresses a preference, and a shell that cannot
+            // be reached is no reason to fail the session teardown that called us.
+        }
+    }
+    /**
+     * Fold the sidebar away without ending the page (`ui.autoExpandOnce` is off, or
+     * the caller wants the screen back while work continues).
+     * @returns a promise that settles once the shell has been asked.
+     */
+    async collapse() {
+        try {
+            await this.connection.call({ op: 'collapseSidebar' }, 10_000);
+        }
+        catch {
+            // Presentation only; failing to fold is never worth an error.
+        }
+    }
+    /** No child process of our own to stop; close the shared connection instead. */
+    dispose() {
+        this.connection.close();
+        this.views.clear();
+        this.orphaned.clear();
+        this.userActionHandler = undefined;
+    }
+}

package/lib/browser-electron/entry.js

@@ -11,7 +11,12 @@
  */
 import z from '@deepseek-ai/schemastery';
 import { ElectronBrowserProvider } from './provider.js';
+import { randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
 import { defaultHostMainPath, RemoteElectronViewHost } from './remote-host.js';
+import { DesktopBridgeViewHost } from './desktop-bridge-host.js';
+import { detectBrowser, SystemBrowserViewHost } from './system-browser.js';
 import { SettingsStore } from './settings-store.js';
 export { ELECTRON_BROWSER_PROVIDER_ID, ElectronBrowserProvider, } from './provider.js';
 export { RemoteElectronViewHost, defaultHostMainPath } from './remote-host.js';
@@ -29,30 +34,94 @@ export const Config = z.object({
 });
 /** Register the Electron browser provider with `ctx.browser`. */
 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());
     // One settings document per plugin instance: the settings panel writes it, the
     // provider reads it live, and both ends agree on the same file.
     const settings = new SettingsStore();
-    // 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, {
+    installSettingsRoute(ctx, settings);
+    const providerConfig = {
         httpOnly: config.httpOnly,
         downloadDir: config.downloadDir,
         snapshotMaxElements: config.snapshotMaxElements,
         contentMaxChars: config.contentMaxChars,
         settings: () => settings.get(),
-    }));
+    };
+    // A host supplied by the composition (the desktop shell's own seam) wins and is
+    // synchronous, so registration stays synchronous on that path.
+    if (config.viewHost !== undefined) {
+        const external = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(config.viewHost, providerConfig));
+        ctx.effect(() => () => { external(); });
+        return;
+    }
+    // Otherwise start self-hosted — a working browser from the first call, on every
+    // surface — and upgrade to the desktop sidebar if this machine has one. The
+    // upgrade is deliberately a swap of the whole provider: the two carriers own
+    // different lifetimes (a spawned child vs. the shell's view), and pretending
+    // otherwise would leave a stray window behind.
+    const selfHosted = new RemoteElectronViewHost(defaultHostMainPath());
+    let unregister = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(selfHosted, providerConfig));
+    let upgraded = false;
     ctx.effect(() => () => {
         unregister();
-        if (config.viewHost === undefined && host instanceof RemoteElectronViewHost) {
-            host.dispose();
-        }
+        selfHosted.dispose();
     });
-    installSettingsRoute(ctx, settings);
+    /**
+     * Swap the provider to another carrier, releasing the previous one.
+     * @param host - the carrier to adopt.
+     * @param note - a one-line description for the log.
+     */
+    const adopt = (host, note) => {
+        if (upgraded) {
+            host.dispose?.();
+            return;
+        }
+        upgraded = true;
+        try {
+            unregister();
+            unregister = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(host, providerConfig));
+            selfHosted.dispose();
+            ctx.logger?.info?.(`dsh-builtin-browser: ${note}`);
+        }
+        catch (error) {
+            // Never leave the surface without a provider.
+            unregister = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(new RemoteElectronViewHost(defaultHostMainPath()), providerConfig));
+            ctx.logger?.warn?.(`dsh-builtin-browser: could not adopt ${note} (${String(error)})`);
+        }
+    };
+    // A browser the user explicitly asked for outranks every automatic choice: the
+    // whole point of the setting is that they know which browser they want. It is
+    // launched with a plugin-owned profile, so their own windows are untouched.
+    void (async () => {
+        const channel = settings.get().browser.channel;
+        if (channel === 'bundled')
+            return;
+        const detected = detectBrowser(channel);
+        if (detected === undefined) {
+            ctx.logger?.warn?.(`dsh-builtin-browser: ${channel} was requested but no installation was found; using the bundled browser`);
+            return;
+        }
+        const home = process.env.DSH_HOME ?? homedir();
+        // Login state lives in the browser profile, so the cookies setting decides where
+        // that profile goes: a stable directory keeps the user signed in across restarts
+        // (the point of using their own browser), while turning persistence off gets a
+        // throwaway directory that is removed when the browser is released.
+        const persist = settings.get().cookies.persist;
+        const profileDir = persist
+            ? join(home, 'dsh-builtin-browser-host', `${detected.kind}-profile`)
+            : join(home, 'dsh-builtin-browser-host', `${detected.kind}-profile-ephemeral-${randomUUID()}`);
+        const host = await SystemBrowserViewHost.launch(detected, profileDir, [], persist ? undefined : profileDir);
+        if (host === undefined) {
+            ctx.logger?.warn?.(`dsh-builtin-browser: ${detected.kind} did not start; using the bundled browser`);
+            return;
+        }
+        adopt(host, `driving the installed ${detected.kind} (${detected.path}${persist ? '' : ', ephemeral profile'})`);
+    })().catch(() => { });
+    void DesktopBridgeViewHost.discover().then(sidebar => {
+        // No bridge (plain `dsh web`, an older desktop build, or a shell that already
+        // exited): keep self-hosting, which is what every surface has always done.
+        if (sidebar === undefined)
+            return;
+        adopt(sidebar, 'driving the desktop sidebar browser');
+    }).catch(() => { });
 }
 /** Route the settings panel reads and writes. */
 const SETTINGS_ROUTE = '/dsh-builtin-browser/settings';

package/lib/browser-electron/history-store.d.ts

@@ -53,12 +53,16 @@ export declare class HistoryStore {
     /**
      * Read visits, newest first. Unparseable lines are skipped; entries older
      * than the age limit are filtered out but left on disk until the next prune.
-     * @param options - optional result cap and domain filter.
+     * @param options - optional result cap plus three filters: `domain` (hostname),
+     *   `query` (substring of the URL or title) and `session` (the task that visited
+     *   it). Filters compose, so "the pages THIS task opened on that host" is one call.
      * @returns the matching visits, newest first.
      */
     list(options?: {
         readonly limit?: number;
         readonly domain?: string;
+        readonly query?: string;
+        readonly session?: string;
     }): VisitedPage[];
     /**
      * Enforce retention: drop entries past the age limit, then the oldest beyond

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

@@ -70,16 +70,27 @@ export class HistoryStore {
     /**
      * Read visits, newest first. Unparseable lines are skipped; entries older
      * than the age limit are filtered out but left on disk until the next prune.
-     * @param options - optional result cap and domain filter.
+     * @param options - optional result cap plus three filters: `domain` (hostname),
+     *   `query` (substring of the URL or title) and `session` (the task that visited
+     *   it). Filters compose, so "the pages THIS task opened on that host" is one call.
      * @returns the matching visits, newest first.
      */
     list(options = {}) {
         const all = this.readAll();
         const cutoff = Date.now() - this.maxAgeMs;
         const domain = options.domain?.toLowerCase();
+        const query = options.query?.toLowerCase();
+        const session = options.session;
         const matches = all.filter(page => {
             if (page.at < cutoff)
                 return false;
+            if (session !== undefined && page.session !== session)
+                return false;
+            if (query !== undefined) {
+                const haystack = `${page.url}\n${page.title ?? ''}`.toLowerCase();
+                if (!haystack.includes(query))
+                    return false;
+            }
             if (domain === undefined)
                 return true;
             try {

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

@@ -87,6 +87,31 @@ export interface ElectronBrowserViewHost {
      * @param handler - called with the group (session) key; must not throw.
      */
     onViewClosed?(handler: (windowId: string) => void): void;
+    /**
+     * Release the service's page(s) without ending the plugin's own lifetime.
+     *
+     * Only carriers that outlive a browser session need this. A self-hosted window
+     * dies with its view, but the desktop shell's sidebar keeps running no matter
+     * what the plugin does — so "release the browser when the session ends"
+     * (settings: ui.closeWithSession) has to be asked for explicitly there.
+     * @returns a promise that settles once the release was attempted.
+     */
+    releasePage?(): Promise<void>;
+    /**
+     * Fold the carrier's presentation away while keeping the page alive.
+     *
+     * The desktop sidebar keeps running regardless of the plugin, so "do not take
+     * over the screen" (settings: ui.autoExpandOnce = false) can only be honoured by
+     * asking the shell to fold it. A self-hosted window has no such state and simply
+     * does not implement this.
+     * @returns a promise that settles once the fold was attempted.
+     */
+    collapse?(): Promise<void>;
+    /**
+     * Release everything the carrier owns (a spawned browser, a socket, a child).
+     * Called when the plugin stops using it, never while it is still in service.
+     */
+    dispose?(): void;
 }
 /**
  * A user-initiated browser action from the host's own UI (toolbar). The
@@ -501,6 +526,8 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
     visited(options?: {
         readonly limit?: number;
         readonly domain?: string;
+        readonly query?: string;
+        readonly session?: string;
     }): readonly VisitedPage[];
     /**
      * Show the synthetic pointer on a view, unless the user switched it off. The
@@ -511,6 +538,9 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
      * @param x - viewport x in CSS pixels.
      * @param y - viewport y in CSS pixels.
      * @param action - click pulses a ripple; move only relocates.
+     * @param label - short description of the operation, shown beside the pointer.
+     * @param force - paint even when the pointer is already there (a click ripple must
+     *   always play; a bare move need not repeat).
      */
     private showCursor;
     /**
@@ -552,7 +582,18 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
      * is reported to the host (toolbar) when the host supports it, else logged.
      */
     private handleUserAction;
-    /** Report a failed user action to the host UI (toolbar), when supported. */
+    /**
+     * Report a failed user action to the host UI (toolbar), when supported.
+     *
+     * Two properties matter here, because this runs inside the catch of an async
+     * handler (issue #16):
+     *  - the receiver must be preserved. Reading the method off the host and calling
+     *    it unbound runs the host's implementation with `this === undefined`, so its
+     *    very first statement (`void this.ready()`) throws, the throw escapes the
+     *    async catch as an unhandled rejection, and the whole DSH host exits;
+     *  - this method must be incapable of throwing. Reporting a failed action is
+     *    diagnostics: it can never be allowed to become the failure.
+     */
     private notifyUserActionError;
     /** Ask the host to show the active tab's view, carrying the session label. */
     private showActive;