dsh-builtin-browser 0.1.23 → 0.3.0

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

@@ -0,0 +1,92 @@
+/**
+ * Plugin-owned settings document — the switches the browser settings panel
+ * exposes, stored next to the browsing history so both follow the same rules:
+ * they survive the browser process and DSH restarts.
+ *
+ * Every field is optional on disk and falls back to a default, so a hand-edited
+ * or older file never breaks startup; an unreadable file is treated as "all
+ * defaults" rather than an error.
+ * @module dsh-browser/browser-electron/settings-store
+ */
+import type { BrowserChannel } from './system-browser.js';
+/** Vision/operation strategy the provider prefers when the model can see. */
+export type VisionStrategy = 'auto' | 'nonVisual';
+/** The full settings document, with every field resolved. */
+export interface BrowserSettings {
+    /** Persistent browsing history (visited pages). */
+    readonly history: {
+        readonly enabled: boolean;
+        readonly maxEntries: number;
+        readonly maxAgeDays: number;
+    };
+    /** Login-state retention: cookies and the browser profile. */
+    readonly cookies: {
+        readonly persist: boolean;
+    };
+    /** Presentation behaviour. */
+    readonly ui: {
+        /** Auto-expand the side panel once per task, then leave the user alone. */
+        readonly autoExpandOnce: boolean;
+        /** Release the browser when its session ends, instead of waiting for a close. */
+        readonly closeWithSession: boolean;
+        /** Show the synthetic cursor/click feedback while the agent operates. */
+        readonly virtualCursor: boolean;
+    };
+    /** Visual vs non-visual operation strategy. */
+    readonly vision: {
+        readonly strategy: VisionStrategy;
+    };
+    /** Which browser binary carries the agent's pages. */
+    readonly browser: {
+        readonly channel: BrowserChannel;
+    };
+    /** Whether the agent may read cookies / export login state. */
+    readonly credentials: {
+        readonly allowRead: boolean;
+    };
+}
+/** Defaults for every switch: the documented out-of-the-box behaviour. */
+export declare const DEFAULT_SETTINGS: BrowserSettings;
+/**
+ * Absolute path of the settings file, beside the browser profile and the
+ * browsing history.
+ * @returns the settings file path.
+ */
+export declare function settingsPath(): string;
+/**
+ * Resolve a raw settings document (already parsed, shape unknown) into the full
+ * document, field by field. Unknown keys are dropped: the file is not a place to
+ * smuggle configuration.
+ * @param raw - the parsed file contents.
+ * @returns the resolved settings.
+ */
+export declare function resolveSettings(raw: unknown): BrowserSettings;
+/**
+ * File-backed settings with an in-memory snapshot. Reads re-stat the file so an
+ * edit from another process (or the settings panel writing through a second
+ * code path) is picked up without a restart; writes are atomic enough for a
+ * single-writer plugin and never throw at the caller.
+ */
+export declare class SettingsStore {
+    private readonly file;
+    private cached;
+    /** Last observed mtime, used to invalidate the cache on external edits. */
+    private cachedMtimeMs;
+    /**
+     * @param file - settings file path (defaults beside the browser profile).
+     */
+    constructor(file?: string);
+    /** Path this store reads and writes. */
+    path(): string;
+    /**
+     * Current settings, re-read when the file changed on disk.
+     * @returns the resolved settings document.
+     */
+    get(): BrowserSettings;
+    /**
+     * Merge a partial patch into the stored document and persist it.
+     * @param patch - the fields to change (unknown keys are ignored).
+     * @returns the settings after the merge.
+     */
+    update(patch: unknown): BrowserSettings;
+}

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

@@ -0,0 +1,183 @@
+/**
+ * Plugin-owned settings document — the switches the browser settings panel
+ * exposes, stored next to the browsing history so both follow the same rules:
+ * they survive the browser process and DSH restarts.
+ *
+ * Every field is optional on disk and falls back to a default, so a hand-edited
+ * or older file never breaks startup; an unreadable file is treated as "all
+ * defaults" rather than an error.
+ * @module dsh-browser/browser-electron/settings-store
+ */
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/** Defaults for every switch: the documented out-of-the-box behaviour. */
+export const DEFAULT_SETTINGS = {
+    history: { enabled: true, maxEntries: 5_000, maxAgeDays: 90 },
+    cookies: { persist: true },
+    ui: { autoExpandOnce: true, closeWithSession: false, virtualCursor: true },
+    vision: { strategy: 'auto' },
+    // Bundled by default: it needs nothing installed, and on the desktop the carrier
+    // is the sidebar anyway. Choosing a system browser is an explicit opt-in because
+    // it starts a real Chrome/Edge with its own profile.
+    browser: { channel: 'bundled' },
+    credentials: { allowRead: true },
+};
+/**
+ * Absolute path of the settings file, beside the browser profile and the
+ * browsing history.
+ * @returns the settings file path.
+ */
+export function settingsPath() {
+    const home = process.env.DSH_HOME ?? join(homedir(), '.dsh');
+    return join(home, 'dsh-builtin-browser-host', 'settings.json');
+}
+/** Coerce one boolean field, keeping the default when absent or mistyped. */
+function bool(value, fallback) {
+    return typeof value === 'boolean' ? value : fallback;
+}
+/**
+ * Coerce the browser channel, keeping the default when it is not one of the
+ * known choices. A hand-edited typo must not silently select a different browser.
+ * @param value - the raw value from the settings document.
+ * @returns a valid channel.
+ */
+function resolveChannel(value) {
+    return value === 'chrome' || value === 'edge' || value === 'auto' || value === 'bundled'
+        ? 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;
+}
+/** Read one nested section of an unknown document, or an empty object. */
+function section(source, key) {
+    const value = source[key];
+    return typeof value === 'object' && value !== null ? value : {};
+}
+/**
+ * Resolve a raw settings document (already parsed, shape unknown) into the full
+ * document, field by field. Unknown keys are dropped: the file is not a place to
+ * smuggle configuration.
+ * @param raw - the parsed file contents.
+ * @returns the resolved settings.
+ */
+export function resolveSettings(raw) {
+    const source = typeof raw === 'object' && raw !== null ? raw : {};
+    const history = section(source, 'history');
+    const cookies = section(source, 'cookies');
+    const ui = section(source, 'ui');
+    const vision = section(source, 'vision');
+    const credentials = section(source, 'credentials');
+    const browser = section(source, 'browser');
+    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),
+        },
+        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),
+        },
+        vision: { strategy: vision.strategy === 'nonVisual' ? 'nonVisual' : DEFAULT_SETTINGS.vision.strategy },
+        browser: { channel: resolveChannel(browser.channel) },
+        credentials: { allowRead: bool(credentials.allowRead, DEFAULT_SETTINGS.credentials.allowRead) },
+    };
+}
+/**
+ * File-backed settings with an in-memory snapshot. Reads re-stat the file so an
+ * edit from another process (or the settings panel writing through a second
+ * code path) is picked up without a restart; writes are atomic enough for a
+ * single-writer plugin and never throw at the caller.
+ */
+export class SettingsStore {
+    file;
+    cached;
+    /** Last observed mtime, used to invalidate the cache on external edits. */
+    cachedMtimeMs = -1;
+    /**
+     * @param file - settings file path (defaults beside the browser profile).
+     */
+    constructor(file = settingsPath()) {
+        this.file = file;
+    }
+    /** Path this store reads and writes. */
+    path() {
+        return this.file;
+    }
+    /**
+     * Current settings, re-read when the file changed on disk.
+     * @returns the resolved settings document.
+     */
+    get() {
+        let mtimeMs = -1;
+        let text;
+        try {
+            if (existsSync(this.file)) {
+                mtimeMs = statSync(this.file).mtimeMs;
+                text = readFileSync(this.file, 'utf8');
+            }
+        }
+        catch {
+            // Unreadable file: fall through to defaults below.
+            mtimeMs = -1;
+            text = undefined;
+        }
+        if (this.cached !== undefined && mtimeMs === this.cachedMtimeMs)
+            return this.cached;
+        try {
+            // A leading BOM is what ordinary Windows editors (Notepad, PowerShell's
+            // `Set-Content -Encoding utf8`) leave behind, and `JSON.parse` rejects it.
+            // Without this strip, hand-editing the settings file silently discarded every
+            // value in it: the document looked correct, and the plugin quietly ran on
+            // defaults — including switches the user had just turned off.
+            const body = text?.replace(/^\uFEFF/, '');
+            this.cached = body === undefined ? DEFAULT_SETTINGS : resolveSettings(JSON.parse(body));
+        }
+        catch {
+            // Malformed JSON: behave as defaults rather than fail startup.
+            this.cached = DEFAULT_SETTINGS;
+        }
+        this.cachedMtimeMs = mtimeMs;
+        return this.cached;
+    }
+    /**
+     * Merge a partial patch into the stored document and persist it.
+     * @param patch - the fields to change (unknown keys are ignored).
+     * @returns the settings after the merge.
+     */
+    update(patch) {
+        const current = this.get();
+        const merged = resolveSettings(deepMerge(current, patch));
+        try {
+            mkdirSync(dirname(this.file), { recursive: true });
+            writeFileSync(this.file, `${JSON.stringify(merged, null, 2)}\n`);
+        }
+        catch {
+            // Keep the merged value in memory even when the write fails.
+        }
+        this.cached = merged;
+        this.cachedMtimeMs = Date.now();
+        return merged;
+    }
+}
+/** One-level-deep merge over the settings sections (patch wins). */
+function deepMerge(base, patch) {
+    if (typeof patch !== 'object' || patch === null)
+        return base;
+    const result = { ...base };
+    for (const [key, value] of Object.entries(patch)) {
+        const existing = result[key];
+        if (typeof value === 'object' && value !== null && typeof existing === 'object' && existing !== null) {
+            result[key] = { ...existing, ...value };
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}

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

@@ -0,0 +1,100 @@
+/**
+ * Drive the browser the user already has (Chrome / Edge / any Chromium) instead of
+ * the Electron we ship — the same approach Codex Browser Use takes.
+ *
+ * WHY
+ * The bundled Electron is a private copy with its own profile, so it can never see
+ * the logins the user already has in Chrome, and on a managed machine the user may
+ * simply prefer their own browser. Launching their browser with a *separate*
+ * `--user-data-dir` gives us a real Chromium we can drive over CDP without touching
+ * their everyday profile, bookmarks or windows: nothing of theirs is opened, locked
+ * or modified, and closing us never closes them.
+ *
+ * HOW
+ * Chromium exposes CDP on `--remote-debugging-port=0`, and writes the port it chose
+ * into `<profile>/DevToolsActivePort`. That file is the discovery mechanism — no
+ * port guessing, no collisions. From there everything is CDP over one WebSocket:
+ * `Target.createTarget` makes a page, `Target.attachToTarget` (flattened) gives a
+ * session for it, and the plugin's commands ride that session. Node 22 ships a global
+ * `WebSocket`, so this needs no dependency at all.
+ *
+ * WHAT IT IMPLEMENTS
+ * The same `ElectronBrowserViewHost` seam as the self-hosted and sidebar hosts, so
+ * the provider, the tools, history, the cursor and teardown rules are unchanged —
+ * only the carrier differs.
+ * @module dsh-browser/browser-electron/system-browser
+ */
+import type { ElectronBrowserViewHost, ElectronViewHandle } from './provider.js';
+/** Which browser the user asked for. */
+export type BrowserChannel = 'bundled' | 'chrome' | 'edge' | 'auto';
+/** A resolved browser installation. */
+export interface DetectedBrowser {
+    /** Which product this is. */
+    readonly kind: 'chrome' | 'edge' | 'brave';
+    /** Absolute path to the executable. */
+    readonly path: string;
+}
+/**
+ * Find an installed Chromium browser.
+ *
+ * `auto` prefers Chrome, then Edge, then Brave — the order reflects how likely each
+ * is to be the browser a user actually chose rather than one Windows shipped.
+ * @param channel - the configured choice; `bundled` never resolves to a system browser.
+ * @param env - environment lookup, injected so tests need no real machine.
+ * @returns the detected browser, or undefined when the choice is unavailable.
+ */
+export declare function detectBrowser(channel: BrowserChannel, env?: NodeJS.ProcessEnv): DetectedBrowser | undefined;
+/** A system browser driven over CDP, presented as a browser view host. */
+export declare class SystemBrowserViewHost implements ElectronBrowserViewHost {
+    private readonly child;
+    private readonly client;
+    readonly kind: DetectedBrowser['kind'];
+    private readonly ephemeralDir?;
+    private readonly views;
+    private disposed;
+    /**
+     * @param child - the launched browser process.
+     * @param client - the CDP connection to it.
+     * @param kind - which product this is (for diagnostics).
+     * @param ephemeralDir - a throwaway profile to remove on release, when the user
+     *   has turned persistence off and no login state should outlive the session.
+     */
+    private constructor();
+    /**
+     * @param browser - the detected installation to launch.
+     * @param profileDir - a plugin-owned directory; the user's own profile is never touched.
+     * @param extraArgs - additional Chromium switches.
+     * @param ephemeralDir - a directory to delete when the browser is released, used
+     *   when persistence is switched off so no login state outlives the session.
+     * @returns the host, or undefined when the browser refuses to come up.
+     */
+    static launch(browser: DetectedBrowser, profileDir: string, extraArgs?: readonly string[], ephemeralDir?: string): Promise<SystemBrowserViewHost | undefined>;
+    /** Whether this host can back views: the CDP connection is live. */
+    available(): boolean;
+    createView(): ElectronViewHandle;
+    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 browser's window forward.
+     *
+     * The browser is a separate application, so there is no view to raise; focusing
+     * the process is the closest honest equivalent, and failing to do so (a minimized
+     * window, a locked session) is never worth an error.
+     */
+    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. The user's own windows are a different process. */
+    dispose(): void;
+    /** The flattened session for a view, creating its page on first use. */
+    private ensureSession;
+    /** sessionId -> targetId, so a destroyed view can close the right page. */
+    private readonly sessions;
+}