dsh-builtin-browser 0.1.22 → 0.2.0

package/lib/browser/runtime.js

@@ -70,7 +70,15 @@ export class BrowserRuntime extends Service {
         const usable = [...providers.values()].filter(provider => provider.available());
         const [single] = usable;
         if (single === undefined) {
-            throw new BrowserError('no usable browser provider is registered', 'BROWSER_PROVIDER_UNAVAILABLE');
+            // Two very different causes used to read identically here — nothing is
+            // registered, or something is registered but cannot run — and only the
+            // second one has a fix the user can apply without reinstalling.
+            const registered = [...providers.values()].map(provider => provider.id);
+            if (registered.length === 0) {
+                throw new BrowserError('no browser provider is registered — install a browser plugin (e.g. dsh-builtin-browser) and enable it in this profile', 'BROWSER_PROVIDER_UNAVAILABLE');
+            }
+            throw new BrowserError(`browser provider(s) ${registered.join(', ')} are registered but report themselves unavailable — `
+                + 'for dsh-builtin-browser this means no spawnable Electron binary was found; run `npx install-electron` in the active profile or set ELECTRON_PATH', 'BROWSER_PROVIDER_UNAVAILABLE');
         }
         if (usable.length > 1) {
             const ids = usable.map(provider => provider.id).join(', ');
@@ -194,6 +202,25 @@ export class BrowserRuntime extends Service {
     async history(session) {
         return this.resolveProvider().history(session);
     }
+    /**
+     * Persisted visits, newest first — the record that outlives the browser
+     * process, as opposed to {@link history}'s session-scoped operation log.
+     * @param options - result cap and an optional hostname filter.
+     * @returns the retained visits (empty when history recording is disabled).
+     */
+    visited(options) {
+        return this.resolveProvider().visited(options);
+    }
+    /**
+     * Whether a session is still live. Sessions can end outside the tool layer
+     * (the human closed its window), so a cached id must be re-checked before
+     * reuse; a provider that does not implement the check counts as live.
+     * @param session - the session id to test.
+     */
+    exists(session) {
+        const provider = this.resolveProvider();
+        return provider.exists === undefined ? true : provider.exists(session);
+    }
     /** Replay one recorded operation by sequence number through the provider. */
     async replay(session, seq) {
         return this.resolveProvider().replay(session, seq);

package/lib/browser/types.d.ts

@@ -544,11 +544,44 @@ export interface BrowserProvider {
     restoreAuth(session: BrowserSessionId, cookies: readonly ExportedCookie[]): Promise<number>;
     /** Return the session's chronological operation log. */
     history(session: BrowserSessionId): Promise<readonly BrowserHistoryEntry[]>;
+    /**
+     * Persisted visits, newest first: what survives the browser process, so a
+     * human or an Agent can find a page again after the interface was closed.
+     * @param options - result cap and an optional hostname filter.
+     * @returns the retained visits (empty when history is disabled).
+     */
+    visited(options?: {
+        readonly limit?: number;
+        readonly domain?: string;
+    }): readonly VisitedPage[];
+    /**
+     * Optional: whether a session is still live. A session can end outside the
+     * tool layer — the human closed the browser window — so a cached id must be
+     * checked before it is reused. Providers that never end a session on their own
+     * can omit this, and callers treat absence as "still live".
+     * @param session - the session id to test.
+     */
+    exists?(session: BrowserSessionId): boolean;
     /** Replay one recorded operation by sequence number. */
     replay(session: BrowserSessionId, seq: number): Promise<void>;
     /** Close the session and destroy its backing surface. Idempotent. */
     close(session: BrowserSessionId): Promise<void>;
 }
+/**
+ * One visited page in the persistent browsing history — the durable record that
+ * outlives sessions, unlike {@link BrowserHistoryEntry}, which is a
+ * session-scoped operation log (navigate/click/type/…).
+ */
+export interface VisitedPage {
+    /** Epoch milliseconds when the visit was recorded. */
+    readonly at: number;
+    /** Absolute URL of the visited document. */
+    readonly url: string;
+    /** Document title at visit time, when the page exposed one. */
+    readonly title?: string;
+    /** Session/task label that drove the visit, when the provider knows it. */
+    readonly session?: string;
+}
 /** One recorded browser operation, in chronological order (seq 1, 2, 3…). */
 export interface BrowserHistoryEntry {
     /** Monotonic sequence number within the session. */

package/lib/browser-electron/entry.js

@@ -12,6 +12,7 @@
 import z from '@deepseek-ai/schemastery';
 import { ElectronBrowserProvider } from './provider.js';
 import { defaultHostMainPath, RemoteElectronViewHost } from './remote-host.js';
+import { SettingsStore } from './settings-store.js';
 export { ELECTRON_BROWSER_PROVIDER_ID, ElectronBrowserProvider, } from './provider.js';
 export { RemoteElectronViewHost, defaultHostMainPath } from './remote-host.js';
 /** Cordis plugin name used by loader diagnostics. */
@@ -31,6 +32,9 @@ 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
@@ -40,6 +44,7 @@ export function apply(ctx, config) {
         downloadDir: config.downloadDir,
         snapshotMaxElements: config.snapshotMaxElements,
         contentMaxChars: config.contentMaxChars,
+        settings: () => settings.get(),
     }));
     ctx.effect(() => () => {
         unregister();
@@ -47,4 +52,114 @@ export function apply(ctx, config) {
             host.dispose();
         }
     });
+    installSettingsRoute(ctx, settings);
+}
+/** Route the settings panel reads and writes. */
+const SETTINGS_ROUTE = '/dsh-builtin-browser/settings';
+/**
+ * Expose the settings document over the host's web server, which is how the
+ * settings panel reads and writes it. A host without that service (headless /
+ * CLI surfaces) simply skips this: the panel is then unreachable and the file
+ * stays hand-editable — never a plugin-startup failure.
+ * @param ctx - the plugin context.
+ * @param settings - the settings document to expose.
+ */
+function installSettingsRoute(ctx, settings) {
+    const inject = ctx.inject;
+    if (typeof inject !== 'function')
+        return;
+    try {
+        inject(['webServer'], (host) => {
+            host.effect(() => host.webServer.register({
+                kind: 'exact',
+                path: SETTINGS_ROUTE,
+                handler: (request, response) => handleSettingsRequest(request, response, settings),
+            }, 'dsh-builtin-browser: settings'));
+        });
+    }
+    catch {
+        // No web server on this surface: the settings file remains the interface.
+    }
+}
+/**
+ * Same-origin guard. Settings are machine-local configuration, so a page loaded
+ * elsewhere must not be able to read or rewrite them.
+ * @param request - the incoming request.
+ * @returns whether the request may touch the settings document.
+ */
+function sameOrigin(request) {
+    const site = String(request.headers['sec-fetch-site'] ?? '').toLowerCase();
+    if (site === 'cross-site')
+        return false;
+    const origin = String(request.headers.origin ?? '').trim();
+    if (origin === 'null')
+        return false;
+    if (origin === '')
+        return true;
+    try {
+        return new URL(origin).host.toLowerCase() === String(request.headers.host ?? '').trim().toLowerCase();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * One settings round-trip: `GET` reads the document, `PUT`/`POST` merges a
+ * partial patch into it.
+ * @param request - the incoming request.
+ * @param response - the response to write.
+ * @param settings - the settings document.
+ */
+async function handleSettingsRequest(request, response, settings) {
+    const json = (status, body) => {
+        response.writeHead(status, {
+            'content-type': 'application/json; charset=utf-8',
+            'cache-control': 'no-store',
+        });
+        response.end(JSON.stringify(body));
+    };
+    if (!sameOrigin(request)) {
+        json(403, { ok: false, error: 'cross-origin request refused' });
+        return;
+    }
+    const method = request.method ?? 'GET';
+    if (method === 'GET') {
+        json(200, { ok: true, settings: settings.get(), path: settings.path() });
+        return;
+    }
+    if (method !== 'PUT' && method !== 'POST') {
+        response.writeHead(405, { allow: 'GET, PUT' });
+        response.end();
+        return;
+    }
+    try {
+        const body = await readBody(request);
+        const patch = body.trim() === '' ? {} : JSON.parse(body);
+        json(200, { ok: true, settings: settings.update(patch) });
+    }
+    catch (error) {
+        json(400, { ok: false, error: `invalid settings patch: ${String(error)}` });
+    }
+}
+/**
+ * Read a request body with a hard cap (the settings patch is tiny, and an
+ * unbounded read would let any same-origin caller exhaust memory).
+ * @param request - the incoming request.
+ * @param limit - maximum accepted characters.
+ * @returns the body text.
+ */
+function readBody(request, limit = 64 * 1024) {
+    return new Promise((resolve, reject) => {
+        let text = '';
+        request.setEncoding('utf8');
+        request.on('data', chunk => {
+            text += String(chunk);
+            if (text.length > limit) {
+                request.destroy();
+                reject(new Error('settings patch too large'));
+            }
+        });
+        request.on('end', () => resolve(text));
+        request.on('error', reject);
+    });
 }

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

@@ -0,0 +1,71 @@
+/**
+ * Persistent browsing history: which pages the shared browser actually visited,
+ * kept independently from any session's operation log (`browser_history`) and
+ * from the browser process's lifetime.
+ *
+ * It lives beside the browser profile (`$DSH_HOME/dsh-builtin-browser-host/
+ * history.jsonl`), so it follows the same persistence rules as the login state:
+ * closing the interface releases the process, never the record.
+ *
+ * Format: one JSON object per line, append-only. Appending stays cheap for a
+ * long session, and a half-written tail (crash, power loss) is dropped on read
+ * instead of poisoning the whole file.
+ * @module dsh-browser/browser-electron/history-store
+ */
+import type { VisitedPage } from '../browser/types.js';
+export type { VisitedPage };
+/** Retention limits; whichever is hit first starts trimming. */
+export interface HistoryLimits {
+    /** Maximum retained entries. Default 5000. */
+    readonly maxEntries?: number;
+    /** Maximum age in days. Default 90. */
+    readonly maxAgeDays?: number;
+}
+/**
+ * Absolute path of the browsing-history file, beside the browser profile so the
+ * record shares the login state's persistence rules.
+ * @returns the history file path.
+ */
+export declare function visitedHistoryPath(): string;
+/**
+ * Append-only browsing history with bounded retention. Every method tolerates a
+ * missing or damaged file: recording a visit must never fail a navigation, and
+ * a corrupted line must never hide the rest of the history.
+ */
+export declare class HistoryStore {
+    private readonly file;
+    private readonly maxEntries;
+    private readonly maxAgeMs;
+    /**
+     * @param file - absolute path of the JSONL history file.
+     * @param limits - retention overrides (entry count and age).
+     */
+    constructor(file?: string, limits?: HistoryLimits);
+    /** Whether the history file exists yet (diagnostics and tests). */
+    exists(): boolean;
+    /**
+     * Record one visit. Failures are swallowed by design: history is a
+     * convenience, and losing an entry must never break the tool call that
+     * produced it.
+     * @param page - the visited page.
+     */
+    append(page: VisitedPage): void;
+    /**
+     * 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.
+     * @returns the matching visits, newest first.
+     */
+    list(options?: {
+        readonly limit?: number;
+        readonly domain?: string;
+    }): VisitedPage[];
+    /**
+     * Enforce retention: drop entries past the age limit, then the oldest beyond
+     * the count cap. Cheap no-op until the file grows past the cap, so callers can
+     * run it after every append.
+     */
+    prune(): void;
+    /** Parse the whole file, skipping blank and damaged lines. */
+    private readAll;
+}

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

@@ -0,0 +1,151 @@
+/**
+ * Persistent browsing history: which pages the shared browser actually visited,
+ * kept independently from any session's operation log (`browser_history`) and
+ * from the browser process's lifetime.
+ *
+ * It lives beside the browser profile (`$DSH_HOME/dsh-builtin-browser-host/
+ * history.jsonl`), so it follows the same persistence rules as the login state:
+ * closing the interface releases the process, never the record.
+ *
+ * Format: one JSON object per line, append-only. Appending stays cheap for a
+ * long session, and a half-written tail (crash, power loss) is dropped on read
+ * instead of poisoning the whole file.
+ * @module dsh-browser/browser-electron/history-store
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/** Default entry cap — mirrors the documented retention rule. */
+const DEFAULT_MAX_ENTRIES = 5_000;
+/** Default age cap in days. */
+const DEFAULT_MAX_AGE_DAYS = 90;
+/** Rewrite the file only once it has grown this far past the cap. */
+const PRUNE_SLACK = 500;
+/**
+ * Absolute path of the browsing-history file, beside the browser profile so the
+ * record shares the login state's persistence rules.
+ * @returns the history file path.
+ */
+export function visitedHistoryPath() {
+    const home = process.env.DSH_HOME ?? join(homedir(), '.dsh');
+    return join(home, 'dsh-builtin-browser-host', 'history.jsonl');
+}
+/**
+ * Append-only browsing history with bounded retention. Every method tolerates a
+ * missing or damaged file: recording a visit must never fail a navigation, and
+ * a corrupted line must never hide the rest of the history.
+ */
+export class HistoryStore {
+    file;
+    maxEntries;
+    maxAgeMs;
+    /**
+     * @param file - absolute path of the JSONL history file.
+     * @param limits - retention overrides (entry count and age).
+     */
+    constructor(file = visitedHistoryPath(), limits = {}) {
+        this.file = file;
+        this.maxEntries = limits.maxEntries ?? DEFAULT_MAX_ENTRIES;
+        this.maxAgeMs = (limits.maxAgeDays ?? DEFAULT_MAX_AGE_DAYS) * 24 * 60 * 60 * 1000;
+    }
+    /** Whether the history file exists yet (diagnostics and tests). */
+    exists() {
+        return existsSync(this.file);
+    }
+    /**
+     * Record one visit. Failures are swallowed by design: history is a
+     * convenience, and losing an entry must never break the tool call that
+     * produced it.
+     * @param page - the visited page.
+     */
+    append(page) {
+        try {
+            mkdirSync(dirname(this.file), { recursive: true });
+            appendFileSync(this.file, `${JSON.stringify(page)}\n`);
+        }
+        catch {
+            // Best-effort: history is not worth failing a navigation over.
+        }
+    }
+    /**
+     * 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.
+     * @returns the matching visits, newest first.
+     */
+    list(options = {}) {
+        const all = this.readAll();
+        const cutoff = Date.now() - this.maxAgeMs;
+        const domain = options.domain?.toLowerCase();
+        const matches = all.filter(page => {
+            if (page.at < cutoff)
+                return false;
+            if (domain === undefined)
+                return true;
+            try {
+                return new URL(page.url).hostname.toLowerCase().includes(domain);
+            }
+            catch {
+                return page.url.toLowerCase().includes(domain);
+            }
+        });
+        matches.reverse();
+        return options.limit === undefined ? matches : matches.slice(0, Math.max(0, options.limit));
+    }
+    /**
+     * Enforce retention: drop entries past the age limit, then the oldest beyond
+     * the count cap. Cheap no-op until the file grows past the cap, so callers can
+     * run it after every append.
+     */
+    prune() {
+        const all = this.readAll();
+        const cutoff = Date.now() - this.maxAgeMs;
+        const fresh = all.filter(page => page.at >= cutoff);
+        const kept = fresh.length > this.maxEntries ? fresh.slice(fresh.length - this.maxEntries) : fresh;
+        // Only rewrite when something actually fell off, and only once the excess
+        // is worth a full rewrite.
+        if (kept.length === all.length)
+            return;
+        if (all.length - kept.length < PRUNE_SLACK && fresh.length <= this.maxEntries)
+            return;
+        try {
+            const body = kept.map(page => `${JSON.stringify(page)}\n`).join('');
+            writeFileSync(this.file, body);
+        }
+        catch {
+            // Best-effort: an unpruned file still reads correctly.
+        }
+    }
+    /** Parse the whole file, skipping blank and damaged lines. */
+    readAll() {
+        let raw;
+        try {
+            raw = readFileSync(this.file, 'utf8');
+        }
+        catch {
+            return [];
+        }
+        const pages = [];
+        for (const line of raw.split('\n')) {
+            const trimmed = line.trim();
+            if (trimmed === '')
+                continue;
+            try {
+                const parsed = JSON.parse(trimmed);
+                if (typeof parsed.at !== 'number' || typeof parsed.url !== 'string')
+                    continue;
+                pages.push({
+                    at: parsed.at,
+                    url: parsed.url,
+                    ...typeof parsed.title === 'string' && parsed.title !== '' ? { title: parsed.title } : {},
+                    ...typeof parsed.session === 'string' && parsed.session !== '' ? { session: parsed.session } : {},
+                });
+            }
+            catch {
+                // A damaged line (typically a truncated tail) must not hide the rest.
+                continue;
+            }
+        }
+        return pages;
+    }
+}

package/lib/browser-electron/host-main.d.ts

@@ -13,6 +13,7 @@
  *      { id, op: 'destroyView', viewId } | { id, op: 'showView', viewId } |
  *      { id, op: 'groupView', viewId, windowId, label? } |
  *      { id, op: 'command', viewId, method, params } |
+ *      { id, op: 'focus', viewId } |
  *      { id, op: 'userActionError', windowId, message }
  *   -> { id: 0, op: 'hello', token } (our FIRST message — proves we know the
  *      parent's stdin token; the parent refuses the connection otherwise)

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

@@ -13,6 +13,7 @@
  *      { id, op: 'destroyView', viewId } | { id, op: 'showView', viewId } |
  *      { id, op: 'groupView', viewId, windowId, label? } |
  *      { id, op: 'command', viewId, method, params } |
+ *      { id, op: 'focus', viewId } |
  *      { id, op: 'userActionError', windowId, message }
  *   -> { id: 0, op: 'hello', token } (our FIRST message — proves we know the
  *      parent's stdin token; the parent refuses the connection otherwise)
@@ -235,6 +236,13 @@ function withTimeout(promise, ms, label) {
  * only the tool layer's 10–30s timeout eventually cuts off.
  */
 const COMMAND_TIMEOUT_MS = 20000;
+/**
+ * How long to let a `focus` request land before answering it. Focus moves
+ * asynchronously and a key dispatched in the same turn as the request is still
+ * dropped, so the caller needs this settle — but only on the call where focus
+ * actually had to move.
+ */
+const FOCUS_SETTLE_MS = 80;
 /**
  * A brand-new WebContentsView has no renderer process until something loads,
  * and CDP commands (Runtime.evaluate …) sent to a renderer-less view never
@@ -330,7 +338,34 @@ function windowFor(windowId) {
     if (existing !== undefined)
         return existing;
     const w = new BrowserWindow({ width: 1400, height: 900, show: true, title: 'dsh-browser' });
-    w.on('closed', () => { windows.delete(key); });
+    w.on('closed', () => {
+        const closing = windows.get(key);
+        windows.delete(key);
+        // A BrowserWindow does not destroy its child views: their webContents (the
+        // renderer process, its timers and audio) outlive the window unless closed
+        // explicitly, so release them here instead of leaking a renderer per window.
+        if (closing !== undefined) {
+            for (const view of closing.views.values()) {
+                try {
+                    view.webContentsView.webContents.close();
+                }
+                catch {
+                    // Already destroyed along with the window.
+                }
+            }
+            closing.views.clear();
+        }
+        // The interface is gone for good. Report it, so the plugin ends that session
+        // instead of holding one whose window the human already closed. Browsing
+        // history and login state live on disk, so the next open starts a clean
+        // session rather than resurrecting this one.
+        try {
+            rpcSocket?.write(JSON.stringify({ id: 0, op: 'viewClosed', windowId: key }) + '\n');
+        }
+        catch {
+            // Socket already gone (parent shutting down): nothing left to report to.
+        }
+    });
     const win = { windowId: key, window: w, toolbarView: undefined, views: new Map(), visibleViewId: undefined, lastFocusedViewId: undefined, closeTimer: undefined };
     // Keep every view (and the toolbar) filling the window as the human
     // resizes it; otherwise pages stay at their original size and break.
@@ -725,6 +760,29 @@ async function handle(op, msg) {
                 reply(msg.id, { ok: true, result });
                 return;
             }
+            case 'focus': {
+                const viewId = msg.viewId;
+                if (viewId === undefined)
+                    throw new Error('focus missing viewId');
+                const win = windowOfView(viewId);
+                const entry = win?.views.get(viewId);
+                if (win === undefined || entry === undefined)
+                    throw new Error(`focus: unknown view ${viewId}`);
+                // Keys go to the view that holds web focus. A view that was never
+                // clicked holds none, so the FIRST browser_key of a session was dropped
+                // by the renderer while CDP still answered the dispatch with success —
+                // and `document.hasFocus()` inside the page even read true.
+                const contents = entry.webContentsView.webContents;
+                const hadWebFocus = contents.isFocused();
+                contents.focus();
+                // Focus lands asynchronously, and a key dispatched in the same turn as
+                // the request is still dropped, so hold the reply until the renderer can
+                // take input. Only on the call where focus actually had to move.
+                if (!hadWebFocus)
+                    await new Promise(resolve => setTimeout(resolve, FOCUS_SETTLE_MS));
+                reply(msg.id, { ok: true, focused: contents.isFocused() });
+                return;
+            }
             case 'capture': {
                 const viewId = msg.viewId;
                 if (viewId === undefined)
@@ -997,6 +1055,35 @@ async function handle(op, msg) {
         reply(msg.id, { ok: false, err: String(error) });
     }
 }
+/**
+ * Chromium's native-window occlusion tracker (Windows only) asks DWM whether a
+ * window is covered by another window and, when it is, moves the WebContents to
+ * `Visibility::HIDDEN`. That is the wrong model for this host: the shared
+ * browser window normally sits *behind* whatever the human is working in, and
+ * that is exactly the state the agent drives it from. A hidden WebContents
+ * produces no frames at all (`requestAnimationFrame` never fires) and
+ * `RenderWidgetHostImpl::CanReceiveInput()` returns false, so every
+ * `Input.dispatchMouseEvent`/`dispatchKeyEvent` sent over CDP is dropped on the
+ * floor while the CDP call itself still answers `{}` — clicks and keys that
+ * silently do nothing, with no error anywhere. Keep the window's visibility
+ * state application-controlled instead; the parent already shows/raises views
+ * explicitly, and `webContentsView.setVisible()` remains the single source of
+ * truth for whether a view renders.
+ */
+function keepWindowsNonOccluding() {
+    if (process.platform !== 'win32')
+        return;
+    const DISABLED = 'CalculateNativeWinOcclusion';
+    const current = app.commandLine.getSwitchValue('disable-features') ?? '';
+    const features = current
+        .split(',')
+        .map(part => part.trim())
+        .filter(part => part !== '');
+    if (!features.includes(DISABLED))
+        features.push(DISABLED);
+    app.commandLine.appendSwitch('disable-features', features.join(','));
+}
+keepWindowsNonOccluding();
 /**
  * Electron entry: connect back to the parent's RPC server (port from
  * `--rpc-port`) and serve line-delimited JSON-RPC. `ELECTRON_RUN_AS_NODE` is