dsh-builtin-browser 0.4.1 → 0.4.5

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

@@ -44,6 +44,22 @@ export interface BrowserSettings {
     readonly credentials: {
         readonly allowRead: boolean;
     };
+    /**
+     * What the agent is allowed to DO, as opposed to what it may look at.
+     *
+     * These are OPERATOR switches: the settings panel is not reachable from the model, so a
+     * value here refuses whatever the model asks for, and no tool can lift it. That is what
+     * separates them from `browser_restrict`, which is the model's own soft guardrail. All
+     * three default to on, which is the documented out-of-the-box behaviour.
+     */
+    readonly actions: {
+        /** Run arbitrary page scripts in the active tab (`browser_execute`). */
+        readonly allowExecute: boolean;
+        /** Download a URL to disk (`browser_download`). */
+        readonly allowDownload: boolean;
+        /** Write cookies — importing login state (`browser_auth` restore). */
+        readonly allowCredentialWrite: boolean;
+    };
 }
 /** Defaults for every switch: the documented out-of-the-box behaviour. */
 export declare const DEFAULT_SETTINGS: BrowserSettings;
@@ -90,3 +106,27 @@ export declare class SettingsStore {
      */
     update(patch: unknown): BrowserSettings;
 }
+/**
+ * Replace a file's contents atomically: write a sibling temporary file, then rename it over
+ * the target.
+ *
+ * `writeFileSync(target, …)` truncates and rewrites in place, so a crash, a full disk or an
+ * antivirus lock in the middle leaves HALF a JSON document. That used to be silent: the reader
+ * resolved an unparseable file to the defaults, so a torn write flipped `credentials.allowRead`
+ * and the action switches back ON, and the next successful update wrote those defaults to disk
+ * for good. The read side no longer does that (see {@link SETTINGS_WHEN_UNREADABLE}) — but the
+ * write side still has to stop producing torn files at all, because half a document is not
+ * something this plugin should ever leave behind.
+ *
+ * The rename is the commit point: a reader sees either the old document or the new one,
+ * never a partial one. It stays in the same directory so the rename is atomic on Windows
+ * as well as POSIX (`renameSync` maps to MoveFileEx there: same-volume replaces are
+ * atomic, cross-volume ones are not supported at all).
+ *
+ * The temporary is written with a unique suffix rather than a fixed `.tmp`, so two writers
+ * (the settings panel and a second DSH process) cannot rename each other's half-written
+ * file into place. Shared with the history store, which had the same hole.
+ * @param file - the target path.
+ * @param contents - the complete new document.
+ */
+export declare function writeFileAtomic(file: string, contents: string): void;

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

@@ -8,7 +8,7 @@
  * defaults" rather than an error.
  * @module dsh-browser/browser-electron/settings-store
  */
-import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, renameSync, rmSync, 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. */
@@ -22,6 +22,7 @@ export const DEFAULT_SETTINGS = {
     // it starts a real Chrome/Edge with its own profile.
     browser: { channel: 'bundled' },
     credentials: { allowRead: true },
+    actions: { allowExecute: true, allowDownload: true, allowCredentialWrite: true },
 };
 /**
  * Absolute path of the settings file, beside the browser profile and the
@@ -36,6 +37,37 @@ export function settingsPath() {
 function bool(value, fallback) {
     return typeof value === 'boolean' ? value : fallback;
 }
+/**
+ * Coerce one boolean field that GATES A CAPABILITY.
+ *
+ * The difference from {@link bool} is what a mistyped value means. Absent still takes the
+ * default — a document written before the switch existed is the documented behaviour. But
+ * present-and-not-a-boolean is a document this code cannot read, and for a switch that gates
+ * something the operator chose to limit, unreadable resolves to OFF. `bool`'s fallback made
+ * `"false"` (a string), `null` (a truncated write) and `1` all mean the same as `true`, so a
+ * single dropped byte reopened every capability that had been turned off.
+ * @param value - the raw value from the settings document.
+ * @param fallback - the default, used only when the field is absent.
+ * @returns the value when it is a boolean, `false` when it is anything else.
+ */
+function gate(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    return value === true;
+}
+/**
+ * What an unreadable document resolves to.
+ *
+ * Only the capability gates are refused; everything else keeps its default. The distinction is
+ * deliberate: refusing history, presentation or browser choice would punish the user for a
+ * corrupt file without protecting anything, while refusing the gates is the whole point —
+ * "the operator's intent cannot be read" must not resolve to "the operator permits".
+ */
+const SETTINGS_WHEN_UNREADABLE = {
+    ...DEFAULT_SETTINGS,
+    credentials: { allowRead: false },
+    actions: { allowExecute: false, allowDownload: false, allowCredentialWrite: false },
+};
 /**
  * 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.
@@ -43,18 +75,42 @@ function bool(value, fallback) {
  * @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
@@ -71,21 +127,44 @@ export function resolveSettings(raw) {
     const vision = section(source, 'vision');
     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),
+        },
+        actions: {
+            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),
         },
-        vision: { strategy: vision.strategy === 'nonVisual' ? 'nonVisual' : DEFAULT_SETTINGS.vision.strategy },
-        browser: { channel: resolveChannel(browser.channel) },
-        credentials: { allowRead: bool(credentials.allowRead, DEFAULT_SETTINGS.credentials.allowRead) },
     };
 }
 /**
@@ -115,20 +194,35 @@ export class SettingsStore {
      */
     get() {
         let mtimeMs = -1;
-        let text;
         try {
-            if (existsSync(this.file)) {
-                mtimeMs = statSync(this.file).mtimeMs;
-                text = readFileSync(this.file, 'utf8');
-            }
+            // stat directly: existsSync costs about thirteen times what the stat does, and the
+            // stat already throws when the file is missing — which the catch below handles.
+            mtimeMs = statSync(this.file).mtimeMs;
         }
         catch {
             // Unreadable file: fall through to defaults below.
             mtimeMs = -1;
-            text = undefined;
         }
+        // Return the cache BEFORE reading. The read used to happen first "just in case", which
+        // made the cache pointless: every call paid for a synchronous read of the whole file and
+        // then discarded it. This is on the path of every tool call that consults a setting, so
+        // it was a stat plus a read per call where a single stat will do.
         if (this.cached !== undefined && mtimeMs === this.cachedMtimeMs)
             return this.cached;
+        let text;
+        if (mtimeMs !== -1) {
+            try {
+                text = readFileSync(this.file, 'utf8');
+            }
+            catch {
+                // It was there a moment ago (the stat above) and cannot be read now: permissions, a
+                // lock, a directory in the way. That is not "no document" — the file is not absent, so
+                // what it said is unknown, and unknown resolves to the refusing document.
+                this.cached = SETTINGS_WHEN_UNREADABLE;
+                this.cachedMtimeMs = mtimeMs;
+                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.
@@ -139,8 +233,12 @@ export class SettingsStore {
             this.cached = body === undefined ? DEFAULT_SETTINGS : resolveSettings(JSON.parse(body));
         }
         catch {
-            // Malformed JSON: behave as defaults rather than fail startup.
-            this.cached = DEFAULT_SETTINGS;
+            // A document that EXISTS but cannot be parsed is not the same as no document at all: the
+            // first is a corrupted or half-written file whose contents were the operator's decisions,
+            // the second is a first run. Resolving both to the defaults meant a kill during the write,
+            // or one stray character, silently reopened the capabilities that had been switched off —
+            // so this side refuses them instead (see SETTINGS_WHEN_UNREADABLE).
+            this.cached = SETTINGS_WHEN_UNREADABLE;
         }
         this.cachedMtimeMs = mtimeMs;
         return this.cached;
@@ -155,7 +253,7 @@ export class SettingsStore {
         const merged = resolveSettings(deepMerge(current, patch));
         try {
             mkdirSync(dirname(this.file), { recursive: true });
-            writeFileSync(this.file, `${JSON.stringify(merged, null, 2)}\n`);
+            writeFileAtomic(this.file, `${JSON.stringify(merged, null, 2)}\n`);
         }
         catch (error) {
             // Do NOT publish the new value as cached, and do not pretend the file changed: a
@@ -171,6 +269,45 @@ export class SettingsStore {
         return merged;
     }
 }
+/**
+ * Replace a file's contents atomically: write a sibling temporary file, then rename it over
+ * the target.
+ *
+ * `writeFileSync(target, …)` truncates and rewrites in place, so a crash, a full disk or an
+ * antivirus lock in the middle leaves HALF a JSON document. That used to be silent: the reader
+ * resolved an unparseable file to the defaults, so a torn write flipped `credentials.allowRead`
+ * and the action switches back ON, and the next successful update wrote those defaults to disk
+ * for good. The read side no longer does that (see {@link SETTINGS_WHEN_UNREADABLE}) — but the
+ * write side still has to stop producing torn files at all, because half a document is not
+ * something this plugin should ever leave behind.
+ *
+ * The rename is the commit point: a reader sees either the old document or the new one,
+ * never a partial one. It stays in the same directory so the rename is atomic on Windows
+ * as well as POSIX (`renameSync` maps to MoveFileEx there: same-volume replaces are
+ * atomic, cross-volume ones are not supported at all).
+ *
+ * The temporary is written with a unique suffix rather than a fixed `.tmp`, so two writers
+ * (the settings panel and a second DSH process) cannot rename each other's half-written
+ * file into place. Shared with the history store, which had the same hole.
+ * @param file - the target path.
+ * @param contents - the complete new document.
+ */
+export function writeFileAtomic(file, contents) {
+    const temporary = `${file}.${process.pid}.${Math.random().toString(36).slice(2, 10)}.tmp`;
+    try {
+        writeFileSync(temporary, contents);
+        renameSync(temporary, file);
+    }
+    catch (error) {
+        // The rename is the commit point, so a failure before it leaves the target untouched —
+        // only the temporary has to go, and it must not be left behind as garbage.
+        try {
+            rmSync(temporary, { force: true });
+        }
+        catch { /* the temp is already the least of it */ }
+        throw error;
+    }
+}
 /** One-level-deep merge over the settings sections (patch wins). */
 function deepMerge(base, patch) {
     if (typeof patch !== 'object' || patch === null)

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

@@ -24,9 +24,20 @@
  * only the carrier differs.
  * @module dsh-browser/browser-electron/system-browser
  */
+/**
+ * Starts a browser process and returns a handle to it.
+ *
+ * Injectable so tests can supply something that speaks CDP — the seam a recovery test needs
+ * and could not have while the launch was hardcoded to a stub that rejects Chromium's args.
+ * @param path - the executable to run.
+ * @param args - its arguments.
+ * @returns the child process.
+ */
+export type BrowserLauncher = (path: string, args: readonly string[]) => ReturnType<typeof spawn>;
+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. */
@@ -59,13 +70,26 @@ export declare function detectBrowser(channel: BrowserChannel, env?: NodeJS.Proc
  * @param platform - the platform whose names and locations apply.
  * @returns the launcher names (as PATH lookups) and the fixed locations checked.
  */
-export declare function searchSummary(kind: DetectedBrowser['kind'], platform?: NodeJS.Platform): string[];
+export declare function searchSummary(kind: DetectedBrowser['kind'], platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): string[];
 /** A system browser driven over CDP, presented as a browser view host. */
 export declare class SystemBrowserViewHost implements ElectronBrowserViewHost {
     private readonly browser;
     private readonly profileDir;
     private readonly extraArgs;
     private readonly ephemeralDir?;
+    private readonly launcher;
+    /**
+     * viewId -> the session that view rides, and the client that issued it.
+     *
+     * The client is part of the value on purpose. A session id means nothing to a browser other
+     * than the one that handed it out, and this host replaces browsers routinely: the process
+     * dies, or its debugging socket closes while the process lives on. Keeping only the id meant
+     * the host could start a NEW browser successfully and then send every command to it carrying
+     * a session the old one had issued — `Session with given id not found`, on every call, with a
+     * browser that answers /json/version perfectly well and nothing the user can do short of
+     * restarting DSH. Comparing identity catches it with no round trip; validating each cached
+     * session against the browser would put one on every page command.
+     */
     private readonly views;
     private disposed;
     /**
@@ -77,16 +101,40 @@ export declare class SystemBrowserViewHost implements ElectronBrowserViewHost {
      * spawned when a view is actually needed.
      */
     private client;
+    /**
+     * Set when a command went unanswered rather than being refused.
+     *
+     * A timeout says nothing about the connection: the page may simply be slow. It marks the
+     * client for a cheap check before the next command trusts it, which keeps a slow page
+     * from being mistaken for a dead browser while still catching one that has truly stopped
+     * answering.
+     */
+    private clientSuspect;
     private child;
     private starting;
+    /**
+     * Browsers that ignored a kill.
+     *
+     * They are no longer this host's child — a replacement has taken that slot — but they
+     * are still running, still holding the profile, and still something release must try to
+     * stop. Forgetting them is what allowed a launch this host could not undo.
+     */
+    private readonly stubborn;
     /**
      * @param browser - the detected installation to launch on first use.
      * @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 on release, when the user has turned
      *   persistence off so no login state outlives the session.
+     * @param launcher - how to start the browser, for tests.
+     *
+     *   Recovery after the browser dies was untestable without this: the suite spawns a stub
+     *   with Chromium's arguments, and a stub that is not a browser rejects them and exits, so
+     *   no CDP endpoint ever appears and no session is ever created. Verified by mutation —
+     *   removing every sessions.clear() left the recovery tests green. A launcher lets a test
+     *   provide something that actually speaks CDP, so the state those tests describe exists.
      */
-    constructor(browser: DetectedBrowser, profileDir: string, extraArgs?: readonly string[], ephemeralDir?: string | undefined);
+    constructor(browser: DetectedBrowser, profileDir: string, extraArgs?: readonly string[], ephemeralDir?: string | undefined, launcher?: BrowserLauncher);
     /** Which product this host would drive (for diagnostics). */
     get kind(): DetectedBrowser['kind'];
     /** Whether the browser has actually been started yet (diagnostics and tests). */
@@ -95,6 +143,29 @@ export declare class SystemBrowserViewHost implements ElectronBrowserViewHost {
      * The CDP client, starting the browser on first use.
      * @returns the connected client.
      */
+    /**
+     * Whether a client that reports itself open is actually answering.
+     *
+     * An open socket proves nothing: a browser can hold the connection and never reply, and
+     * that state must not be cached, or every later command waits out its own timeout. Asking
+     * the browser something cheap is a fact; reading the failure text is a guess, and the
+     * guess was wrong in both directions (it killed healthy browsers on a slow page, and it
+     * mistook the browser's own free text for a verdict).
+     *
+     * This is only reached when the socket is open, so the common path costs nothing.
+     * @param client - the client to question.
+     * @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.
@@ -117,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.
      *
@@ -134,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.
      *
@@ -146,8 +226,18 @@ export declare class SystemBrowserViewHost implements ElectronBrowserViewHost {
      * browser) simply tears down its bookkeeping.
      */
     dispose(): void;
-    /** The flattened session for a view, creating its page on first use. */
+    /**
+     * The flattened session for a view, creating its page on first use.
+     *
+     * No cache check here: the only caller has already established that the cached session does
+     * not belong to the client it is about to use. Re-checking would mean either a round trip or
+     * 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;
 }