dsh-builtin-browser 0.4.6 → 0.4.8

package/lib/browser-electron/provider.js

@@ -99,7 +99,7 @@ export function layoutSize(metrics) {
     return { width: content.width, height: content.height, viewportHeight: viewport?.height ?? content.height };
 }
 /**
- * Map CDP cookies onto the shape `browser_auth` exports.
+ * Map CDP cookies onto the shape `dsh_browser_auth` exports.
  *
  * CDP reports a cookie as domain + path rather than a URL, and in seconds rather than
  * milliseconds, so both are converted. Entries missing a name, value or domain are
@@ -352,7 +352,7 @@ export class ElectronBrowserProvider {
         // session), carrying the label for the window title. Hosts without
         // groupView keep the shared-window behavior.
         this.host.groupView?.(handle, id, label);
-        this.sessions.set(id, { id, label, tabs: [{ id: `tab:${randomUUID()}`, handle }], activeIndex: 0, history: [], nextSeq: 1 });
+        this.sessions.set(id, { id, label, tabs: [{ id: `tab:${randomUUID()}`, handle, url: '' }], activeIndex: 0, history: [], nextSeq: 1 });
         return Promise.resolve(id);
     }
     /** Open a URL in the active tab (default) or a new tab. */
@@ -371,9 +371,16 @@ export class ElectronBrowserProvider {
             const tab = s.tabs[i];
             if (tab === undefined)
                 continue; // defensive: array can shift under concurrency
+            // A tab we know has never navigated is NOT probed: its view has committed no document, so
+            // the round trip can only answer nothing — and it is the round trip that costs. A tab that
+            // HAS navigated is re-read, because the page may have moved itself since; a read that fails
+            // keeps the last accepted URL rather than reporting the tab as blank.
+            const liveUrl = tab.url === '' ? '' : await this.currentUrl(tab.handle).catch(() => tab.url);
+            if (liveUrl !== '')
+                tab.url = liveUrl;
             result.push({
                 id: tab.id,
-                url: await this.currentUrl(tab.handle).catch(() => ''),
+                url: liveUrl,
                 active: i === s.activeIndex,
             });
         }
@@ -455,7 +462,8 @@ export class ElectronBrowserProvider {
     /** Navigate the active tab's view to a URL, honoring HTTP(S)-only admission. */
     async navigate(session, request, signal) {
         const s = this.session(session);
-        const { handle } = this.activeTab(s);
+        const tab = this.activeTab(s);
+        const { handle } = tab;
         const url = request.url;
         try {
             if (this.httpOnly) {
@@ -496,6 +504,11 @@ export class ElectronBrowserProvider {
             // the visit written to the persistent history for a navigation nobody awaits any more.
             signal?.throwIfAborted();
             this.record(s, 'navigate', { url }, true);
+            // The tab now holds a committed document, which is what the blank short-circuit in
+            // `snapshot`/`a11y` keys on. Recorded here rather than after the settle below: the
+            // navigation HAS committed, and a tab wrongly treated as blank would return empty results
+            // for a page that is really there.
+            tab.url = url;
             await this.settleDocument(handle, before, signal);
             this.recordVisit(s, handle);
             this.showActive(s);
@@ -543,9 +556,9 @@ export class ElectronBrowserProvider {
     /**
      * Page.navigate resolves at navigation COMMIT, not at load: the new document
      * is already current (so location.href and document.title are the new page's)
-     * while its DOM is still being parsed. browser_open snapshots immediately
+     * while its DOM is still being parsed. dsh_browser_open snapshots immediately
      * after navigating, which is why it could report the right title with zero
-     * interactive elements — and why a separate browser_snapshot right after
+     * interactive elements — and why a separate dsh_browser_snapshot right after
      * always found them.
      *
      * Wait — bounded, best-effort — for the new document to settle: readyState
@@ -653,7 +666,7 @@ export class ElectronBrowserProvider {
      *
      * A renderer only delivers key events to the view that holds web focus. A
      * view that was created but never clicked holds none — and `Input` events
-     * injected over CDP do not grant it — so the FIRST `browser_key` of a fresh
+     * injected over CDP do not grant it — so the FIRST `dsh_browser_key` of a fresh
      * session vanished inside the renderer while the command still answered
      * success. Hosts that cannot focus a view (a test double, a different shell
      * adapter) simply have no `focus`, and nothing changes for them.
@@ -663,7 +676,7 @@ export class ElectronBrowserProvider {
             return;
         try {
             // Bounded, unlike the rest of this call: the child RPC has no timeout of its own,
-            // and this runs before typing, so an unresponsive child would hang browser_key for
+            // and this runs before typing, so an unresponsive child would hang dsh_browser_key for
             // good. A timeout is caught below exactly like any other focus failure, so the
             // best-effort contract is unchanged.
             await withTimeout(handle.focus(), 5_000, undefined, 'browser: focusing the view timed out');
@@ -808,6 +821,11 @@ export class ElectronBrowserProvider {
         const s = this.session(session);
         const tab = this.activeTab(s);
         signal?.throwIfAborted();
+        // A tab that has never navigated is a blank, uncommitted view. The collector cannot answer in
+        // it — there is no document to commit — so the call would sit out its whole budget before
+        // saying anything. Answering the empty page immediately is both faster and more truthful.
+        if (tab.url === '')
+            return { url: '', elements: [], truncated: false };
         const script = `(() => {
       const cap = ${String(this.snapshotMaxElements)}
       const url = location.href
@@ -880,7 +898,22 @@ export class ElectronBrowserProvider {
         // Same hang guard as execute: a renderer that has not committed after
         // navigate would otherwise block snapshot forever.
         const timeoutMs = 30_000;
-        const result = await withTimeout(handleSendEvaluate(tab.handle, script), timeoutMs, signal, `browser: snapshot timed out after ${timeoutMs}ms`, () => terminatePage(tab.handle));
+        let result;
+        try {
+            result = await withTimeout(handleSendEvaluate(tab.handle, script), timeoutMs, signal, `browser: snapshot timed out after ${timeoutMs}ms`, () => terminatePage(tab.handle));
+        }
+        catch (error) {
+            // A timeout leaves the wedged view in the session, so every later read would pay the same
+            // 30 seconds again — and `terminatePage` only interrupts the running script, it does not
+            // make the view readable. Replacing it is what turns a permanent loss into one bad call:
+            // the tab keeps the id the caller holds, and the next dsh_browser_open with the real URL
+            // repopulates it.
+            if (error instanceof Error && error.name === 'TimeoutError') {
+                this.replaceTabWithBlank(s, tab);
+                throw new BrowserError('browser: snapshot timed out; the stuck tab was reset to blank. Call dsh_browser_open with the real target URL before reading it again.', 'BROWSER_SNAPSHOT_TIMEOUT', { cause: error });
+            }
+            throw error;
+        }
         if (!result.ok)
             throw new BrowserError(`browser: snapshot evaluation failed: ${result.exception}`, 'BROWSER_SNAPSHOT_FAILED');
         const value = result.value;
@@ -898,6 +931,10 @@ export class ElectronBrowserProvider {
         const s = this.session(session);
         const tab = this.activeTab(s);
         signal?.throwIfAborted();
+        // Same short-circuit as `snapshot`: a tab that never navigated has no committed document, so
+        // the tree cannot be read and the call would spend its whole budget discovering that.
+        if (tab.url === '')
+            return { url: '', title: undefined, count: 0, nodes: [], truncated: false };
         const includeHidden = request.includeHidden === true;
         // 150 rather than 500. The cap fills on any real page, and 500 nodes measured 38,953
         // characters — 10k-13k tokens for a single call. A caller that needs more asks for it.
@@ -1059,7 +1096,19 @@ export class ElectronBrowserProvider {
       return { url: location.href, title: document.title || undefined, count: out.length, nodes: out, truncated: out.length >= maxNodes }
     })()`;
         const timeoutMs = 30_000;
-        const result = await withTimeout(handleSendEvaluate(tab.handle, script), timeoutMs, signal, `browser: a11y timed out after ${timeoutMs}ms`, () => terminatePage(tab.handle));
+        let result;
+        try {
+            result = await withTimeout(handleSendEvaluate(tab.handle, script), timeoutMs, signal, `browser: a11y timed out after ${timeoutMs}ms`, () => terminatePage(tab.handle));
+        }
+        catch (error) {
+            // As in `snapshot`: a timeout means the view is wedged, and leaving it in the session would
+            // charge every later read the same 30 seconds. Replaced in place, so the tab id survives.
+            if (error instanceof Error && error.name === 'TimeoutError') {
+                this.replaceTabWithBlank(s, tab);
+                throw new BrowserError('browser: a11y timed out; the stuck tab was reset to blank. Call dsh_browser_open with the real target URL before reading it again.', 'BROWSER_A11Y_TIMEOUT', { cause: error });
+            }
+            throw error;
+        }
         if (!result.ok)
             throw new BrowserError(`browser: a11y evaluation failed: ${result.exception}`, 'BROWSER_A11Y_FAILED');
         const value = result.value;
@@ -1468,7 +1517,7 @@ export class ElectronBrowserProvider {
             placeholder: f.placeholder ?? null,
             // A field with NO kind is a field with no kind FILTER: absent, not 'text'. Defaulting
             // it to 'text' here made `if (spec.kind)` above always true, so every unspecified
-            // field was narrowed to an <input> — browser_fill on a <textarea> reported
+            // field was narrowed to an <input> — dsh_browser_fill on a <textarea> reported
             // `no "text" control matched`, and a contenteditable could not match any kind at all.
             // The value stays a string or null (never undefined): the in-page check tests truthiness,
             // and JSON drops an undefined member entirely, which is the same thing here.
@@ -1603,7 +1652,7 @@ export class ElectronBrowserProvider {
             el.dispatchEvent(new Event('change', { bubbles: true }))
             out.push({ ok: true, method: 'select', target: describe(spec) })
           } else if (type === 'file') {
-            out.push({ ok: false, error: 'file inputs cannot be set from script; use browser_download or ask the human', target: describe(spec) })
+            out.push({ ok: false, error: 'file inputs cannot be set from script; use dsh_browser_download or ask the human', target: describe(spec) })
           } else if (type === 'checkbox') {
             const want = spec.value === true || spec.value === 'true' || spec.value === 'on'
             if (el.checked !== want) el.click()
@@ -2031,7 +2080,7 @@ export class ElectronBrowserProvider {
      * Refuse an action the settings have switched off.
      *
      * These switches belong to the OPERATOR. The settings document is written through the
-     * plugin's own panel and no tool can reach it, so — unlike `browser_restrict`, which the
+     * plugin's own panel and no tool can reach it, so — unlike `dsh_browser_restrict`, which the
      * model owns and can lift at will — a refusal here stands for as long as the setting does.
      * That is the point of them: a deployment can take page-script execution, downloads, or
      * login-state writes off the table without relying on the model's cooperation.
@@ -2058,7 +2107,7 @@ export class ElectronBrowserProvider {
     }
     /**
      * Admit a caller-supplied save path for a file the browser writes to disk.
-     * ONE gate for both `browser_download` and `browser_screenshot`: the path
+     * ONE gate for both `dsh_browser_download` and `dsh_browser_screenshot`: the path
      * must be absolute, must resolve inside `downloadDir`, and must not already
      * exist. Without it a prompt-injected agent could write — or silently
      * replace — any file the DSH process can reach, which also escapes the file
@@ -2440,7 +2489,7 @@ export class ElectronBrowserProvider {
             .catch(() => { });
     }
     /**
-     * List persisted visits, newest first — what `browser_visited` reads back.
+     * List persisted visits, newest first — what `dsh_browser_visited` reads back.
      * @param options - result cap and an optional hostname filter.
      * @returns the matching visits, or an empty list when history is disabled.
      */
@@ -2579,10 +2628,42 @@ export class ElectronBrowserProvider {
         const handle = this.host.createView(s.label);
         // Same window as the session's other tabs.
         this.host.groupView?.(handle, s.id, s.label);
-        s.tabs.push({ id: `tab:${randomUUID()}`, handle });
+        s.tabs.push({ id: `tab:${randomUUID()}`, handle, url: '' });
         s.activeIndex = s.tabs.length - 1;
         this.showActive(s);
     }
+    /**
+     * Swap a wedged view for a fresh blank one, keeping the tab's public id.
+     *
+     * A view whose renderer never commits cannot be read again: every evaluate into it runs out its
+     * whole budget. Replacing it is what turns that from permanent into one bad call — the tab id
+     * callers hold stays valid, and the next `dsh_browser_open` with the real URL re-populates it.
+     *
+     * The old view is destroyed AFTER the new one is in place, so a failure here cannot leave the
+     * session holding a handle that is already gone.
+     * @param s - the session owning the tab.
+     * @param tab - the tab to reset.
+     */
+    replaceTabWithBlank(s, tab) {
+        const index = s.tabs.indexOf(tab);
+        if (index < 0)
+            return;
+        let handle;
+        try {
+            handle = this.host.createView(s.label);
+            this.host.groupView?.(handle, s.id, s.label);
+        }
+        catch {
+            // Creating the replacement failed: leaving the wedged tab in place is worse than nothing
+            // only for the caller, who is about to be told the tab timed out either way.
+            return;
+        }
+        const wedged = tab.handle;
+        s.tabs[index] = { id: tab.id, handle, url: '' };
+        if (index === s.activeIndex)
+            this.showActive(s);
+        this.host.destroyView(wedged);
+    }
     /** Find a session's tab by its backing view id (toolbar actions carry view ids). */
     tabByViewId(s, viewId) {
         return s.tabs.find(tab => tab.handle.id === viewId);

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

@@ -1275,7 +1275,7 @@ class DeferredRemoteView {
      * with "browser host is not running". Instead: drop the cache, rebuild the
      * view against a freshly spawned child, and retry the operation exactly
      * once — so sessions that survive a host death self-heal on their FIRST
-     * call after it, without a manual browser_reset_session. Page-level errors
+     * call after it, without a manual dsh_browser_reset_session. Page-level errors
      * are never retried (the view itself is fine).
      */
     async withRecovery(op) {

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

@@ -49,15 +49,15 @@ export interface BrowserSettings {
      *
      * 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
+     * separates them from `dsh_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`). */
+        /** Run arbitrary page scripts in the active tab (`dsh_browser_execute`). */
         readonly allowExecute: boolean;
-        /** Download a URL to disk (`browser_download`). */
+        /** Download a URL to disk (`dsh_browser_download`). */
         readonly allowDownload: boolean;
-        /** Write cookies — importing login state (`browser_auth` restore). */
+        /** Write cookies — importing login state (`dsh_browser_auth` restore). */
         readonly allowCredentialWrite: boolean;
     };
 }
@@ -69,6 +69,13 @@ export declare const DEFAULT_SETTINGS: BrowserSettings;
  * @returns the settings file path.
  */
 export declare function settingsPath(): string;
+/**
+ * The channels a settings document may name.
+ *
+ * Exported so the log line and the error message can quote the same set the parser accepts: a
+ * message that lists a value the code rejects (or omits one it takes) is worse than no message.
+ */
+export declare const BROWSER_CHANNELS: readonly ["chrome", "edge", "auto", "bundled", "sidebar"];
 /**
  * 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
@@ -76,7 +83,7 @@ export declare function settingsPath(): string;
  * @param raw - the parsed file contents.
  * @returns the resolved settings.
  */
-export declare function resolveSettings(raw: unknown): BrowserSettings;
+export declare function resolveSettings(raw: unknown, warn?: (message: string) => void): 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
@@ -85,13 +92,14 @@ export declare function resolveSettings(raw: unknown): BrowserSettings;
  */
 export declare class SettingsStore {
     private readonly file;
+    private readonly log?;
     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);
+    constructor(file?: string, log?: ((message: string) => void) | undefined);
     /** Path this store reads and writes. */
     path(): string;
     /**

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

@@ -68,16 +68,34 @@ const SETTINGS_WHEN_UNREADABLE = {
     credentials: { allowRead: false },
     actions: { allowExecute: false, allowDownload: false, allowCredentialWrite: false },
 };
+/**
+ * The channels a settings document may name.
+ *
+ * Exported so the log line and the error message can quote the same set the parser accepts: a
+ * message that lists a value the code rejects (or omits one it takes) is worse than no message.
+ */
+export const BROWSER_CHANNELS = ['chrome', 'edge', 'auto', 'bundled', 'sidebar'];
 /**
  * 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.
+ *
+ * Coercing is right; coercing QUIETLY is not. A typo and "the setting did nothing" look exactly
+ * the same to whoever typed it, which is why every discarded value is reported.
  * @param value - the raw value from the settings document.
+ * @param warn - where to report a discarded value, when the caller has somewhere to put it.
  * @returns a valid channel.
  */
-function resolveChannel(value) {
-    return value === 'chrome' || value === 'edge' || value === 'auto' || value === 'bundled' || value === 'sidebar'
-        ? value
-        : DEFAULT_SETTINGS.browser.channel;
+function resolveChannel(value, warn) {
+    // Absent is the ordinary case, not a mistake: a document that never mentioned the channel gets
+    // the default without a word.
+    if (value === undefined)
+        return DEFAULT_SETTINGS.browser.channel;
+    if (BROWSER_CHANNELS.includes(value))
+        return value;
+    warn?.(`dsh-builtin-browser: browser.channel ${JSON.stringify(value)} is not a known channel, so the `
+        + `default "${DEFAULT_SETTINGS.browser.channel}" was used instead. Expected one of: `
+        + `${BROWSER_CHANNELS.join(', ')}.`);
+    return DEFAULT_SETTINGS.browser.channel;
 }
 /** Coerce one positive-integer field, keeping the default when invalid. */
 function count(value, fallback) {
@@ -119,7 +137,7 @@ function section(source, key) {
  * @param raw - the parsed file contents.
  * @returns the resolved settings.
  */
-export function resolveSettings(raw) {
+export function resolveSettings(raw, warn) {
     const source = typeof raw === 'object' && raw !== null ? raw : {};
     const history = section(source, 'history');
     const cookies = section(source, 'cookies');
@@ -146,7 +164,7 @@ export function resolveSettings(raw) {
             virtualCursor: bool(ui?.virtualCursor, DEFAULT_SETTINGS.ui.virtualCursor),
         },
         vision: { strategy: vision?.strategy === 'nonVisual' ? 'nonVisual' : DEFAULT_SETTINGS.vision.strategy },
-        browser: { channel: resolveChannel(browser?.channel) },
+        browser: { channel: resolveChannel(browser?.channel, warn) },
         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.
@@ -175,14 +193,16 @@ export function resolveSettings(raw) {
  */
 export class SettingsStore {
     file;
+    log;
     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()) {
+    constructor(file = settingsPath(), log) {
         this.file = file;
+        this.log = log;
     }
     /** Path this store reads and writes. */
     path() {
@@ -230,7 +250,7 @@ export class SettingsStore {
             // 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));
+            this.cached = body === undefined ? DEFAULT_SETTINGS : resolveSettings(JSON.parse(body), m => this.log?.(m));
         }
         catch {
             // A document that EXISTS but cannot be parsed is not the same as no document at all: the
@@ -250,7 +270,7 @@ export class SettingsStore {
      */
     update(patch) {
         const current = this.get();
-        const merged = resolveSettings(deepMerge(current, patch));
+        const merged = resolveSettings(deepMerge(current, patch), m => this.log?.(m));
         try {
             mkdirSync(dirname(this.file), { recursive: true });
             writeFileAtomic(this.file, `${JSON.stringify(merged, null, 2)}\n`);

package/lib/index.d.ts

@@ -3,7 +3,7 @@
  * pieces. The cordis.patch.yml rows reference subpath exports:
  *   - `dsh-builtin-browser/browser`          -> the ctx.browser seam (Service)
  *   - `dsh-builtin-browser/browser-electron` -> the Electron CDP provider
- *   - `dsh-builtin-browser/tool-browser`     -> the model-facing browser_* tools
+ *   - `dsh-builtin-browser/tool-browser`     -> the model-facing dsh_browser_* tools
  * The capability itself is composed by those rows; this root entry exists for
  * programmatic imports AND because the host's client-module scan identifies a
  * package's browser half through a loader row whose specifier resolves to the

package/lib/index.js

@@ -3,7 +3,7 @@
  * pieces. The cordis.patch.yml rows reference subpath exports:
  *   - `dsh-builtin-browser/browser`          -> the ctx.browser seam (Service)
  *   - `dsh-builtin-browser/browser-electron` -> the Electron CDP provider
- *   - `dsh-builtin-browser/tool-browser`     -> the model-facing browser_* tools
+ *   - `dsh-builtin-browser/tool-browser`     -> the model-facing dsh_browser_* tools
  * The capability itself is composed by those rows; this root entry exists for
  * programmatic imports AND because the host's client-module scan identifies a
  * package's browser half through a loader row whose specifier resolves to the

package/lib/tool-browser/element-fields.d.ts

@@ -8,9 +8,9 @@
  * and the tool's `output.schema` declared the properties. Nothing connected them, and the
  * result is this project's most repeatable bug:
  *
- *   - `browser_a11y`'s `selector` — computed by the provider, declared by the schema,
+ *   - `dsh_browser_a11y`'s `selector` — computed by the provider, declared by the schema,
  *     printed by the renderer, and dropped by the projection. 134 tests stayed green.
- *   - `browser_screenshot`'s `width`/`height` — measured by the provider, declared by the
+ *   - `dsh_browser_screenshot`'s `width`/`height` — measured by the provider, declared by the
  *     schema, and dropped by the projection. 172 tests stayed green. It was found a round
  *     later, by reading the three places that agree and noticing the fourth did not.
  *
@@ -24,7 +24,7 @@
  * projection forgets is silently dropped. One table cannot get either wrong on its own.
  */
 /**
- * The `elements` item schema for browser_snapshot and browser_open.
+ * The `elements` item schema for dsh_browser_snapshot and dsh_browser_open.
  *
  * Written as a literal rather than generated, because `defineTool` validates the output schema
  * against its own `ValueSchemaSpec` and a generated `Record<string, …>` is too wide to satisfy
@@ -65,7 +65,7 @@ export declare const ELEMENT_ITEM_SCHEMA: {
     };
 };
 /**
- * The `nodes` item schema for browser_a11y.
+ * The `nodes` item schema for dsh_browser_a11y.
  *
  * Same reasoning as {@link ELEMENT_ITEM_SCHEMA}: literal for the type checker, table-backed by
  * test.

package/lib/tool-browser/element-fields.js

@@ -8,9 +8,9 @@
  * and the tool's `output.schema` declared the properties. Nothing connected them, and the
  * result is this project's most repeatable bug:
  *
- *   - `browser_a11y`'s `selector` — computed by the provider, declared by the schema,
+ *   - `dsh_browser_a11y`'s `selector` — computed by the provider, declared by the schema,
  *     printed by the renderer, and dropped by the projection. 134 tests stayed green.
- *   - `browser_screenshot`'s `width`/`height` — measured by the provider, declared by the
+ *   - `dsh_browser_screenshot`'s `width`/`height` — measured by the provider, declared by the
  *     schema, and dropped by the projection. 172 tests stayed green. It was found a round
  *     later, by reading the three places that agree and noticing the fourth did not.
  *
@@ -24,7 +24,7 @@
  * projection forgets is silently dropped. One table cannot get either wrong on its own.
  */
 /**
- * The fields of one entry in `browser_snapshot` / `browser_open`'s `elements`.
+ * The fields of one entry in `dsh_browser_snapshot` / `dsh_browser_open`'s `elements`.
  *
  * `selector` is the reason this file exists; see the header. It was added to the schema and
  * the projection separately, and only one of them landed.
@@ -39,7 +39,7 @@ const ELEMENT_FIELDS = {
     frame: { schema: { type: 'boolean' } },
 };
 /**
- * The fields of one entry in `browser_a11y`'s `nodes`.
+ * The fields of one entry in `dsh_browser_a11y`'s `nodes`.
  *
  * Different shape from an element on purpose: a role and an accessible name carry meaning a
  * tag and a label string do not, and `depth` is what renders the tree.
@@ -80,7 +80,7 @@ function project(fields, source) {
     return out;
 }
 /**
- * The `elements` item schema for browser_snapshot and browser_open.
+ * The `elements` item schema for dsh_browser_snapshot and dsh_browser_open.
  *
  * Written as a literal rather than generated, because `defineTool` validates the output schema
  * against its own `ValueSchemaSpec` and a generated `Record<string, …>` is too wide to satisfy
@@ -102,7 +102,7 @@ export const ELEMENT_ITEM_SCHEMA = {
     },
 };
 /**
- * The `nodes` item schema for browser_a11y.
+ * The `nodes` item schema for dsh_browser_a11y.
  *
  * Same reasoning as {@link ELEMENT_ITEM_SCHEMA}: literal for the type checker, table-backed by
  * test.

package/lib/tool-browser/index.d.ts

@@ -1,14 +1,14 @@
 /**
- * Model-facing browser tools over `ctx.browser`: `browser_open`,
- * `browser_snapshot`, `browser_execute`, `browser_content`,
- * `browser_screenshot`, and tab management (`browser_list_tabs`,
- * `browser_switch_tab`, `browser_close_tab`, `browser_reset`).
+ * Model-facing browser tools over `ctx.browser`: `dsh_browser_open`,
+ * `dsh_browser_snapshot`, `dsh_browser_execute`, `dsh_browser_content`,
+ * `dsh_browser_screenshot`, and tab management (`dsh_browser_list_tabs`,
+ * `dsh_browser_switch_tab`, `dsh_browser_close_tab`, `dsh_browser_reset`).
  *
  * The tool layer owns only the model-facing schema, argument validation, and
  * result formatting — never provider selection or page driving, which belong
  * to the seam. Session lifecycle is owned here at the plugin level: each
  * calling task (a DSH session) gets its own browser session — the first
- * `browser_open` (or any tool when no session exists) opens it, and later
+ * `dsh_browser_open` (or any tool when no session exists) opens it, and later
  * tools in the same task reuse it. Concurrent tasks therefore never fight
  * over tabs, history, or navigation state.
  * @module dsh-browser/tool-browser
@@ -38,7 +38,7 @@ export interface Config {
  * Tools that only observe, plus the ones that undo a restriction.
  *
  * Never subject to an allow-list: restricting what the agent may *do* must not also
- * blind it or trap it, and the tool descriptions promise as much. browser_restrict
+ * blind it or trap it, and the tool descriptions promise as much. dsh_browser_restrict
  * is in here so a task that restricted everything can still lift it.
  */
 export declare const READ_ONLY_TOOLS: ReadonlySet<string>;