dsh-builtin-browser 0.3.1 → 0.4.1

package/lib/tool-browser/index.js

@@ -14,12 +14,35 @@
  * @module dsh-browser/tool-browser
  */
 import { defineTool } from '@deepseek-ai/dsh-tools';
+/**
+ * Register a cleanup that runs once when the process exits.
+ *
+ * A single hook per process, holding a list of callbacks, rather than one listener per
+ * session: sessions come and go, listeners do not, and Node warns when a listener count
+ * passes ten.
+ */
+const exitCleanups = new Set();
+let exitHookInstalled = false;
+function registerExitCleanup(cleanup) {
+    exitCleanups.add(cleanup);
+    if (exitHookInstalled)
+        return;
+    exitHookInstalled = true;
+    process.on('exit', () => {
+        for (const run of exitCleanups) {
+            try {
+                run();
+            }
+            catch { /* exiting; nothing useful to do */ }
+        }
+    });
+}
 /** Plugin name used by loader diagnostics. */
 export const name = 'tool-browser';
 /** The tool registry, browser seam, and system-prompt registry this tool layer consumes. */
 export const inject = ['tools', 'browser', 'systemPrompt'];
 function createState() {
-    return { sessionsByTask: new Map(), pendingOpens: new Map(), restrictedTo: undefined };
+    return { sessionsByTask: new Map(), pendingOpens: new Map(), configRestrictedTo: undefined, restrictedByTask: new Map() };
 }
 /** Every live state, for the test hook (introspection only, never shared). */
 const liveStates = new Set();
@@ -29,13 +52,43 @@ const liveStates = new Set();
  * @param state - the calling context's tool state.
  * @param toolName - the browser tool about to run.
  */
-function assertAllowed(state, toolName) {
-    const { restrictedTo } = state;
-    if (restrictedTo === undefined)
+/**
+ * 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
+ * is in here so a task that restricted everything can still lift it.
+ */
+export const READ_ONLY_TOOLS = new Set([
+    // Tools that only observe.
+    'browser_snapshot', 'browser_a11y', 'browser_content', 'browser_scrape',
+    'browser_screenshot', 'browser_get_value', 'browser_wait', 'browser_challenge',
+    'browser_list_tabs', 'browser_session', 'browser_history', 'browser_visited',
+    // browser_auth reads cookies out of the browser: an observation, and one the
+    // credentials switch gates on its own (see credentials.allowRead in the settings).
+    'browser_auth',
+    // Getting out of a bad state, or lifting the restriction itself. Without these a task
+    // that restricted everything could neither recover nor be released.
+    'browser_restrict', 'browser_reset_session', 'browser_reset',
+]);
+function assertAllowed(state, toolName, task) {
+    // browser_restrict must stay usable, or a task that restricted everything
+    // could never lift it again.
+    // An allow-list is a statement about ACTIONS, so it must not take away the ability to
+    // look, or to get out of a bad state. The tool description and both READMEs promise
+    // that read-only tools are never blocked; before this they were, because only
+    // browser_restrict itself was exempt — a narrow list then locked browser_history,
+    // browser_reset_session and browser_auth away with no way back.
+    if (READ_ONLY_TOOLS.has(toolName) || toolName === 'browser_restrict')
         return;
-    if (restrictedTo.includes(toolName))
+    const config = state.configRestrictedTo;
+    if (config !== undefined && !config.includes(toolName)) {
+        throw new Error(`browser action "${toolName}" is restricted by the plugin configuration (allow-list: ${config.join(', ')})`);
+    }
+    const allowed = state.restrictedByTask.get(task);
+    if (allowed === undefined || allowed.includes(toolName))
         return;
-    throw new Error(`browser action "${toolName}" is restricted (allow-list: ${restrictedTo.join(', ')})`);
+    throw new Error(`browser action "${toolName}" is restricted (allow-list: ${allowed.join(', ')})`);
 }
 /** Extract the agent from a tool-execution context, when one exists. */
 function agentOf(exec) {
@@ -96,9 +149,10 @@ async function ensureSession(browser, state, key, agent) {
             else if (key === 'default') {
                 // Agentless / CLI probe: close the session on process exit so the
                 // window is not orphaned.
-                process.on('exit', () => {
-                    void browser.close(session).catch(() => { });
-                });
+                // One hook for the whole process, not one listener per session: a default session can
+                // be created repeatedly (a CLI probe does), and each registration lived for the life of
+                // the process — so the listener list grew without bound and Node warned at eleven.
+                registerExitCleanup(() => browser.close(session).catch(() => { }));
             }
         }
         catch (error) {
@@ -118,8 +172,10 @@ function parseFillValue(v) {
         return true;
     if (v === 'false')
         return false;
-    if (v !== undefined && /^-?\d+(\.\d+)?$/.test(v) && String(Number(v)) === v)
-        return Number(v);
+    // Deliberately NOT coerced to a number. The description says numbers are accepted in
+    // string form, and callers pass account numbers, postcodes and zero-padded ids through
+    // here: "007" became "7" and "1e3" became "1000", which silently rewrote the value they
+    // meant to type. A numeric-looking string is a string; the DOM decides how to store it.
     return v ?? '';
 }
 /**
@@ -154,7 +210,7 @@ export function apply(ctx, config = {}) {
     liveStates.add(state);
     ctx.effect(() => () => { liveStates.delete(state); });
     // Re-apply resets the restriction: an omitted allowedActions lifts it.
-    state.restrictedTo = config.allowedActions !== undefined ? [...config.allowedActions] : undefined;
+    state.configRestrictedTo = config.allowedActions !== undefined ? [...config.allowedActions] : undefined;
     ctx.systemPrompt.section({
         name: 'tool:browser',
         // Tool guidance band is 100-199; 150 keeps clear of the common 110/120
@@ -207,12 +263,12 @@ export function apply(ctx, config = {}) {
             // browser_open is an overview of what just loaded, not a locator: it has no
             // `coords` parameter, so coordinates stay off here (browser_snapshot owns
             // that switch for callers that actually target pixels).
-            render: (args, value) => [{ type: 'text', text: formatSnapshot(value, { coords: args.coords === true }) }],
+            render: (args, value) => [{ type: 'text', text: formatSnapshot(value, {}) }],
         },
         timeoutMs,
         isConcurrencySafe: () => false, // opens tabs / navigates; exclusive within a task
         async execute(args, exec) {
-            assertAllowed(state, 'browser_open');
+            assertAllowed(state, 'browser_open', taskKey(exec));
             const browser = ctx.get('browser');
             if (browser === undefined)
                 throw new Error('tool-browser: browser service unavailable');
@@ -477,7 +533,7 @@ export function apply(ctx, config = {}) {
         timeoutMs,
         isConcurrencySafe: () => false, // page JS can be stateful
         async execute(args, exec) {
-            assertAllowed(state, 'browser_execute');
+            assertAllowed(state, 'browser_execute', taskKey(exec));
             const browser = ctx.get('browser');
             if (browser === undefined)
                 throw new Error('tool-browser: browser service unavailable');
@@ -564,7 +620,7 @@ export function apply(ctx, config = {}) {
         timeoutMs,
         isConcurrencySafe: () => true,
         async execute(args, exec) {
-            assertAllowed(state, 'browser_scrape');
+            assertAllowed(state, 'browser_scrape', taskKey(exec));
             const browser = ctx.get('browser');
             if (browser === undefined)
                 throw new Error('tool-browser: browser service unavailable');
@@ -602,12 +658,18 @@ export function apply(ctx, config = {}) {
         timeoutMs,
         isConcurrencySafe: () => false,
         async execute(args, exec) {
-            assertAllowed(state, 'browser_click');
+            assertAllowed(state, 'browser_click', taskKey(exec));
             const browser = ctx.get('browser');
             if (browser === undefined)
                 throw new Error('tool-browser: browser service unavailable');
             const session = await ensureSession(browser, state, taskKey(exec), agentOf(exec));
             const target = args.target;
+            // A target whose value is empty is a caller mistake, not a request to fall back.
+            // Degrading silently sent typed text to whatever held focus — possibly a password
+            // field — or dropped the semantic target in favour of coordinates.
+            if (target !== undefined && typeof target.value === 'string' && target.value === '') {
+                throw new Error('target.value is empty; pass a css selector, visible text or XPath, or omit target entirely to use x/y');
+            }
             if (target !== undefined && typeof target.value === 'string' && target.value !== '') {
                 await browser.click(session, {
                     target: {
@@ -649,12 +711,18 @@ export function apply(ctx, config = {}) {
         timeoutMs,
         isConcurrencySafe: () => false,
         async execute(args, exec) {
-            assertAllowed(state, 'browser_type');
+            assertAllowed(state, 'browser_type', taskKey(exec));
             const browser = ctx.get('browser');
             if (browser === undefined)
                 throw new Error('tool-browser: browser service unavailable');
             const session = await ensureSession(browser, state, taskKey(exec), agentOf(exec));
             const target = args.target;
+            // A target whose value is empty is a caller mistake, not a request to fall back.
+            // Degrading silently sent typed text to whatever held focus — possibly a password
+            // field — or dropped the semantic target in favour of coordinates.
+            if (target !== undefined && typeof target.value === 'string' && target.value === '') {
+                throw new Error('target.value is empty; pass a css selector, visible text or XPath, or omit target entirely to use x/y');
+            }
             if (target !== undefined && typeof target.value === 'string' && target.value !== '') {
                 await browser.type(session, {
                     text: args.text,
@@ -688,7 +756,7 @@ export function apply(ctx, config = {}) {
         timeoutMs,
         isConcurrencySafe: () => false, // mutates page scroll state; exclusive within a task
         async execute(args, exec) {
-            assertAllowed(state, 'browser_scroll');
+            assertAllowed(state, 'browser_scroll', taskKey(exec));
             const browser = ctx.get('browser');
             if (browser === undefined)
                 throw new Error('tool-browser: browser service unavailable');
@@ -714,7 +782,7 @@ export function apply(ctx, config = {}) {
         timeoutMs,
         isConcurrencySafe: () => false, // mutates page state; exclusive within a task
         async execute(_args, exec) {
-            assertAllowed(state, 'browser_back');
+            assertAllowed(state, 'browser_back', taskKey(exec));
             const browser = ctx.get('browser');
             if (browser === undefined)
                 throw new Error('tool-browser: browser service unavailable');
@@ -734,7 +802,7 @@ export function apply(ctx, config = {}) {
         timeoutMs,
         isConcurrencySafe: () => false, // mutates page state; exclusive within a task
         async execute(_args, exec) {
-            assertAllowed(state, 'browser_forward');
+            assertAllowed(state, 'browser_forward', taskKey(exec));
             const browser = ctx.get('browser');
             if (browser === undefined)
                 throw new Error('tool-browser: browser service unavailable');
@@ -754,7 +822,7 @@ export function apply(ctx, config = {}) {
         timeoutMs,
         isConcurrencySafe: () => false, // reloads the page; exclusive within a task
         async execute(_args, exec) {
-            assertAllowed(state, 'browser_refresh');
+            assertAllowed(state, 'browser_refresh', taskKey(exec));
             const browser = ctx.get('browser');
             if (browser === undefined)
                 throw new Error('tool-browser: browser service unavailable');
@@ -776,7 +844,7 @@ export function apply(ctx, config = {}) {
         timeoutMs,
         isConcurrencySafe: () => false, // mutates page state; exclusive within a task
         async execute(args, exec) {
-            assertAllowed(state, 'browser_key');
+            assertAllowed(state, 'browser_key', taskKey(exec));
             const browser = ctx.get('browser');
             if (browser === undefined)
                 throw new Error('tool-browser: browser service unavailable');
@@ -801,7 +869,7 @@ export function apply(ctx, config = {}) {
                         label: { type: 'string', description: 'Match by associated <label> text or aria-label.' },
                         placeholder: { type: 'string', description: 'Match by placeholder text.' },
                         kind: { type: 'string', enum: ['text', 'textarea', 'checkbox', 'radio', 'select'], description: 'Field kind; defaults to text.' },
-                        value: { type: 'string', description: 'Value to set (string form; booleans/numbers accepted as strings).' },
+                        value: { type: 'string', required: true, description: 'Value to set (string form; booleans/numbers accepted as strings). Required: omitting it would be read as "set empty", which unchecks a checkbox and clears a text field while still reporting success.' },
                     },
                 },
             },
@@ -845,19 +913,29 @@ export function apply(ctx, config = {}) {
         timeoutMs,
         isConcurrencySafe: () => false,
         async execute(args, exec) {
-            assertAllowed(state, 'browser_fill');
+            assertAllowed(state, 'browser_fill', taskKey(exec));
             const browser = ctx.get('browser');
             if (browser === undefined)
                 throw new Error('tool-browser: browser service unavailable');
             const session = await ensureSession(browser, state, taskKey(exec), agentOf(exec));
-            const fields = (args.fields ?? []).map((f) => ({
-                ...f.selector !== undefined ? { selector: f.selector } : {},
-                ...f.name !== undefined ? { name: f.name } : {},
-                ...f.label !== undefined ? { label: f.label } : {},
-                ...f.placeholder !== undefined ? { placeholder: f.placeholder } : {},
-                ...f.kind !== undefined ? { kind: f.kind } : {},
-                value: parseFillValue(f.value),
-            }));
+            const fields = (args.fields ?? []).map((f) => {
+                // A missing value is a caller mistake, not a request to clear the field. Turning
+                // it into '' silently unchecks a checkbox or empties a text input while the tool
+                // still reports success, so it fails loudly. The schema marks value required, but
+                // a call can still arrive without it.
+                if (f.value === undefined) {
+                    const matcher = f.selector ?? f.name ?? f.label ?? f.placeholder ?? '(no matcher)';
+                    throw new Error(`browser_fill: field "${matcher}" has no "value"; pass one (use "false" to uncheck, or "" to clear deliberately)`);
+                }
+                return {
+                    ...f.selector !== undefined ? { selector: f.selector } : {},
+                    ...f.name !== undefined ? { name: f.name } : {},
+                    ...f.label !== undefined ? { label: f.label } : {},
+                    ...f.placeholder !== undefined ? { placeholder: f.placeholder } : {},
+                    ...f.kind !== undefined ? { kind: f.kind } : {},
+                    value: parseFillValue(f.value),
+                };
+            });
             const result = await browser.fillForm(session, {
                 fields,
                 ...args.submit === true ? { submit: true } : {},
@@ -903,7 +981,7 @@ export function apply(ctx, config = {}) {
         timeoutMs,
         isConcurrencySafe: () => false, // mutates a field; exclusive within a task
         async execute(args, exec) {
-            assertAllowed(state, 'browser_set_value');
+            assertAllowed(state, 'browser_set_value', taskKey(exec));
             const browser = ctx.get('browser');
             if (browser === undefined)
                 throw new Error('tool-browser: browser service unavailable');
@@ -934,7 +1012,7 @@ export function apply(ctx, config = {}) {
         timeoutMs,
         isConcurrencySafe: () => false, // mutates a field; exclusive within a task
         async execute(args, exec) {
-            assertAllowed(state, 'browser_check');
+            assertAllowed(state, 'browser_check', taskKey(exec));
             const browser = ctx.get('browser');
             if (browser === undefined)
                 throw new Error('tool-browser: browser service unavailable');
@@ -974,7 +1052,7 @@ export function apply(ctx, config = {}) {
         timeoutMs,
         isConcurrencySafe: () => false, // mutates a field; exclusive within a task
         async execute(args, exec) {
-            assertAllowed(state, 'browser_select');
+            assertAllowed(state, 'browser_select', taskKey(exec));
             const browser = ctx.get('browser');
             if (browser === undefined)
                 throw new Error('tool-browser: browser service unavailable');
@@ -1006,7 +1084,7 @@ export function apply(ctx, config = {}) {
         timeoutMs,
         isConcurrencySafe: () => false, // mutates a field; exclusive within a task
         async execute(args, exec) {
-            assertAllowed(state, 'browser_clear');
+            assertAllowed(state, 'browser_clear', taskKey(exec));
             const browser = ctx.get('browser');
             if (browser === undefined)
                 throw new Error('tool-browser: browser service unavailable');
@@ -1049,7 +1127,7 @@ export function apply(ctx, config = {}) {
         timeoutMs,
         isConcurrencySafe: () => true,
         async execute(args, exec) {
-            assertAllowed(state, 'browser_get_value');
+            assertAllowed(state, 'browser_get_value', taskKey(exec));
             const browser = ctx.get('browser');
             if (browser === undefined)
                 throw new Error('tool-browser: browser service unavailable');
@@ -1071,11 +1149,11 @@ export function apply(ctx, config = {}) {
     }));
     ctx.tools.register(defineTool({
         name: 'browser_screenshot',
-        description: 'Capture the current shared-browser page as a screenshot (PNG default, JPEG optional). This is for models that can read images: layout checks, charts, designs, CAPTCHAs, or locating an element by eye before clicking its coordinates. A model without image input gains nothing from it — browser_snapshot, browser_a11y and browser_content carry the same page as text, and browser_scrape extracts structured data. Supports full-page capture, save-to-file, JPEG encoding, and downscaling (maxWidth/maxHeight) to cut vision-tool token cost. JPEG is only available on the self-hosted native path; the desktop-shell path returns PNG.',
+        description: 'Capture the current shared-browser page as a screenshot (PNG default, JPEG optional). This is for models that can read images: layout checks, charts, designs, CAPTCHAs, or locating an element by eye before clicking its coordinates. A model without image input gains nothing from it — browser_snapshot, browser_a11y and browser_content carry the same page as text, and browser_scrape extracts structured data. Supports full-page capture, save-to-file, JPEG encoding, and downscaling (maxWidth/maxHeight) to cut vision-tool token cost. JPEG needs a browser whose CDP encoder works — the self-hosted browser and an installed Chrome/Edge; the desktop sidebar falls back to PNG because the Electron CDP JPEG encoder hangs. Downscaling works on every carrier.',
         parameters: {
             fullPage: { type: 'boolean', description: 'Capture the full scrollable page instead of the viewport (default false).' },
             savePath: { type: 'string', description: 'Absolute file path to also save the image to (e.g. for read_image vision location). Must resolve inside the configured downloadDir (default: the system Downloads folder, localized names such as ~/下载 included); an existing file is never overwritten.' },
-            format: { type: 'string', enum: ['png', 'jpeg'], description: 'Image format (default png; jpeg is self-hosted native path only).' },
+            format: { type: 'string', enum: ['png', 'jpeg'], description: 'Image format (default png; jpeg needs the self-hosted browser or an installed Chrome/Edge; the desktop sidebar returns PNG because the Electron CDP JPEG encoder hangs).' },
             quality: { type: 'number', description: 'JPEG quality 1-100 (default 80); ignored for PNG.' },
             maxWidth: { type: 'number', description: 'Downscale to fit within this width (aspect preserved).' },
             maxHeight: { type: 'number', description: 'Downscale to fit within this height (aspect preserved).' },
@@ -1167,7 +1245,7 @@ export function apply(ctx, config = {}) {
             timeoutMs,
             isConcurrencySafe: () => false, // mutates the active tab; exclusive within a task
             async execute(args, exec) {
-                assertAllowed(state, 'browser_switch_tab');
+                assertAllowed(state, 'browser_switch_tab', taskKey(exec));
                 const browser = ctx.get('browser');
                 if (browser === undefined)
                     throw new Error('tool-browser: browser service unavailable');
@@ -1189,7 +1267,7 @@ export function apply(ctx, config = {}) {
             timeoutMs,
             isConcurrencySafe: () => false, // mutates the tab list; exclusive within a task
             async execute(args, exec) {
-                assertAllowed(state, 'browser_close_tab');
+                assertAllowed(state, 'browser_close_tab', taskKey(exec));
                 const browser = ctx.get('browser');
                 if (browser === undefined)
                     throw new Error('tool-browser: browser service unavailable');
@@ -1209,7 +1287,7 @@ export function apply(ctx, config = {}) {
             timeoutMs,
             isConcurrencySafe: () => false, // closes every tab; exclusive within a task
             async execute(_args, exec) {
-                assertAllowed(state, 'browser_reset');
+                assertAllowed(state, 'browser_reset', taskKey(exec));
                 const browser = ctx.get('browser');
                 if (browser === undefined)
                     throw new Error('tool-browser: browser service unavailable');
@@ -1284,9 +1362,6 @@ export function apply(ctx, config = {}) {
                 if (e.action === 'replay' && params.of === 'type' && typeof params.text === 'string') {
                     params.text = '*'.repeat(Math.min(params.text.length, 64)) + ` (${params.text.length} chars)`;
                 }
-                if (e.action === 'replay' && params.of === 'setValue' && typeof params.value === 'string') {
-                    params.value = '*'.repeat(Math.min(params.value.length, 64)) + ` (${params.value.length} chars)`;
-                }
                 // Execute scripts may embed form tokens / credentials; mask script,
                 // args, and result for both direct execute and replay-of-execute.
                 const isExecute = e.action === 'execute' || (e.action === 'replay' && params.of === 'execute');
@@ -1404,7 +1479,7 @@ export function apply(ctx, config = {}) {
         timeoutMs,
         isConcurrencySafe: () => false,
         async execute(args, exec) {
-            assertAllowed(state, 'browser_replay');
+            assertAllowed(state, 'browser_replay', taskKey(exec));
             const browser = ctx.get('browser');
             if (browser === undefined)
                 throw new Error('tool-browser: browser service unavailable');
@@ -1427,7 +1502,7 @@ export function apply(ctx, config = {}) {
         timeoutMs,
         isConcurrencySafe: () => false,
         async execute(args, exec) {
-            assertAllowed(state, 'browser_download');
+            assertAllowed(state, 'browser_download', taskKey(exec));
             const browser = ctx.get('browser');
             if (browser === undefined)
                 throw new Error('tool-browser: browser service unavailable');
@@ -1488,7 +1563,7 @@ export function apply(ctx, config = {}) {
         timeoutMs,
         isConcurrencySafe: () => false, // closes the whole session; exclusive within a task
         async execute(_args, exec) {
-            assertAllowed(state, 'browser_reset_session');
+            assertAllowed(state, 'browser_reset_session', taskKey(exec));
             const browser = ctx.get('browser');
             if (browser === undefined)
                 throw new Error('tool-browser: browser service unavailable');
@@ -1530,17 +1605,21 @@ export function apply(ctx, config = {}) {
             if (unknown.length > 0) {
                 throw new Error(`browser_restrict: unknown tool name(s) ${unknown.map(t => `"${t}"`).join(', ')} (must start with "browser_")`);
             }
-            // Empty list (or omitted) lifts the restriction; a non-empty list is the
-            // new allow-list. Scoped to this plugin apply (this Cordis context).
-            // In DSH each agent has its own context, so the restriction never leaks
-            // between tasks.
-            state.restrictedTo = allowed.length === 0 ? undefined : [...allowed];
-            return { restrictedTo: state.restrictedTo === undefined ? [] : [...state.restrictedTo] };
+            // Empty list (or omitted) lifts this task's restriction; a non-empty list is its
+            // new allow-list. Per task, not per plugin: this state object is shared by every
+            // agent, so one value here used to lock every other task's browser tools.
+            //
+            if (allowed.length === 0)
+                state.restrictedByTask.delete(taskKey(exec));
+            else
+                state.restrictedByTask.set(taskKey(exec), [...allowed]);
+            const current = state.restrictedByTask.get(taskKey(exec));
+            return { restrictedTo: current === undefined ? [] : [...current] };
         },
     }));
     ctx.tools.register(defineTool({
         name: 'browser_auth',
-        description: 'Export or restore the browser session\'s cookies (login state). Use "flush" to get a JSON cookie list (save it to a private file to persist logins), or "restore" with that list to put logins back (e.g. after the browser host restarted). Available on the self-hosted browser. Exported cookies are LIVE CREDENTIALS: treat them as secrets — do not echo them into the conversation, keep them out of logs, and store the list in a private file.',
+        description: 'Export or restore the browser session\'s cookies (login state). Use "flush" to get a JSON cookie list (save it to a private file to persist logins), or "restore" with that list to put logins back (e.g. after the browser host restarted). Available on all three carriers: the self-hosted browser reads its own session, while the desktop sidebar and an installed Chrome/Edge go through CDP. Refused entirely when the credential switch is off. Exported cookies are LIVE CREDENTIALS: treat them as secrets — do not echo them into the conversation, keep them out of logs, and store the list in a private file.',
         parameters: {
             action: { type: 'string', required: true, enum: ['flush', 'restore'], description: 'flush = export cookies; restore = import cookies.' },
             cookies: { type: 'array', items: { type: 'object', additionalProperties: true }, description: 'Cookie list to restore (required when action=restore).' },
@@ -1559,7 +1638,7 @@ export function apply(ctx, config = {}) {
         timeoutMs,
         isConcurrencySafe: () => false,
         async execute(args, exec) {
-            assertAllowed(state, 'browser_auth');
+            assertAllowed(state, 'browser_auth', taskKey(exec));
             const browser = ctx.get('browser');
             if (browser === undefined)
                 throw new Error('tool-browser: browser service unavailable');
@@ -1568,7 +1647,13 @@ export function apply(ctx, config = {}) {
                 const cookies = await browser.flushAuth(session);
                 return { cookies: cookies.map(c => ({ ...c })) };
             }
-            const list = (args.cookies ?? []);
+            // The description says cookies are required for restore; without this check an
+            // empty call returned {restored: 0} and rendered 'Restored 0 cookies.', which
+            // reads as success and would leave the caller believing the login was restored.
+            if (!Array.isArray(args.cookies) || args.cookies.length === 0) {
+                throw new Error('browser_auth: action "restore" needs a non-empty "cookies" array (get one from action "export" on the same profile)');
+            }
+            const list = args.cookies;
             const restored = await browser.restoreAuth(session, list);
             return { restored };
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-builtin-browser",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Shared real browser plugin for DeepSeek Harness: install-and-use — a visible native browser the human can take over, driven by the agent over CDP. DOM-level interaction (React/Vue safe), per-task session isolation, cookie persistence (browser_auth), CAPTCHA detection, batch form fill (browser_fill), authenticated download, history/replay, action restriction",
   "type": "module",
   "main": "lib/index.js",

package/src/browser-electron/desktop-bridge-host.ts

@@ -25,7 +25,6 @@
 
 import { BridgeConnection, type BridgeEndpoint } from './bridge-connection.js'
 import { readFileSync } from 'node:fs'
-import { connect, type Socket } from 'node:net'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { randomUUID } from 'node:crypto'
@@ -69,12 +68,22 @@ export class DesktopBridgeViewHost implements ElectronBrowserViewHost {
    * session gets its own page).
    */
   private readonly orphaned = new Set<number>()
+  /**
+   * Registered by the provider, and deliberately never invoked on this carrier.
+   *
+   * The sidebar is the shell's own interface: a human clicking inside that page is an
+   * event the shell owns, and the bridge exposes no operation that reports it. The
+   * handler is stored anyway so the interface contract holds (a caller may register
+   * one and must not be surprised) and so a future bridge operation can deliver it
+   * without changing the provider. Consequently no user-action event is emitted while
+   * the desktop sidebar is the carrier — by design, not by omission.
+   */
   private userActionHandler: ((action: BrowserUserAction) => void) | undefined
 
   /**
    * @param endpoint - the shell's published bridge endpoint.
    */
-  private constructor(private readonly endpoint: BridgeEndpoint) {
+  private constructor(endpoint: BridgeEndpoint) {
     this.connection = new BridgeConnection(endpoint)
   }
 

package/src/browser-electron/entry.ts

@@ -21,7 +21,8 @@ import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { defaultHostMainPath, RemoteElectronViewHost } from './remote-host.js'
 import { DesktopBridgeViewHost } from './desktop-bridge-host.js'
-import { detectBrowser, SystemBrowserViewHost } from './system-browser.js'
+import { detectBrowser, searchSummary, SystemBrowserViewHost } from './system-browser.js'
+import { MissingSystemBrowserHost } from './missing-system-browser.js'
 import { SettingsStore } from './settings-store.js'
 
 export {
@@ -131,10 +132,25 @@ export function apply(ctx: Context & { browser: BrowserRuntime }, config: Config
   // spawns a browser window. (An earlier version launched it here, which meant a
   // browser appeared the moment the plugin loaded — reported and fixed.)
   const channel = settings.get().browser.channel
+  // Naming a browser is a decision about which one to use, so it also decides whether the
+  // desktop sidebar may take over. Skipping discovery for an explicit choice is what makes
+  // that choice real — otherwise a user who picked Chrome would silently get the sidebar,
+  // and a user who picked a browser that is not installed would never see the explanation
+  // written for exactly that case, because the sidebar would quietly replace it.
+  const explicitChoice = channel !== 'bundled' && channel !== 'auto'
   if (channel !== 'bundled') {
     const detected = detectBrowser(channel)
     if (detected === undefined) {
-      ctx.logger?.warn?.(`dsh-builtin-browser: ${channel} was requested but no installation was found; using the bundled browser`)
+      // `auto` promises to take whatever is available, so falling back is what it
+      // asked for. Naming a browser is a specific request, and quietly satisfying it
+      // with a different one turns the real problem ("no Chrome here") into a
+      // confusing error about Electron later on. Report it instead.
+      if (channel === 'auto') {
+        ctx.logger?.warn?.('dsh-builtin-browser: no installed browser was found; using the bundled browser')
+      } else {
+        adopt(new MissingSystemBrowserHost(channel, searchSummary(channel)),
+          `the selected ${channel} is not installed — commands will explain how to fix it`)
+      }
     } else {
       const home = process.env.DSH_HOME ?? homedir()
       // Login state lives in the browser profile, so the cookies setting decides where
@@ -150,6 +166,10 @@ export function apply(ctx: Context & { browser: BrowserRuntime }, config: Config
     }
   }
 
+  // An explicit choice was already adopted above; discovering the sidebar here would
+  // replace it, which is exactly what this guard prevents.
+  if (explicitChoice) return
+
   void DesktopBridgeViewHost.discover().then(sidebar => {
     // No bridge (plain `dsh web`, an older desktop build, or a shell that already
     // exited): keep self-hosting, which is what every surface has always done.

package/src/browser-electron/history-store.ts

@@ -149,7 +149,11 @@ export class HistoryStore {
       return []
     }
     const pages: VisitedPage[] = []
-    for (const line of raw.split('\n')) {
+    // Strip a BOM first: trim() does not remove U+FEFF (it is not whitespace in
+    // ECMAScript), so a file written by Notepad or PowerShell made the first line fail to
+    // parse and be discarded as corrupt — silently losing one visit, or the whole file when
+    // it holds one. settings-store strips one for the same reason.
+    for (const line of raw.replace(/^\uFEFF/, '').split('\n')) {
       const trimmed = line.trim()
       if (trimmed === '') continue
       try {