dsh-builtin-browser 0.4.0 → 0.4.2

package/src/tool-browser/index.ts

@@ -102,7 +102,10 @@ export const READ_ONLY_TOOLS: ReadonlySet<string> = new Set([
   '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',
+  // browser_auth is deliberately NOT here. It reads cookies on "flush" but WRITES them on
+  // "restore", to arbitrary domains, which is an action like any other — exempting the tool
+  // would let a task that restricted its own actions rewrite the shared browser's logins.
+  //
   // 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',
@@ -137,6 +140,26 @@ function agentOf(exec: unknown): ExecAgent | undefined {
   return (exec as { agent?: ExecAgent } | undefined)?.agent
 }
 
+/**
+ * Read a target's `index`, refusing the values that cannot mean anything.
+ *
+ * The index is looked up in the page (`els[index] ?? null`), so a negative one — `-1`, the
+ * common "give me the last one" shorthand — matches nothing. The page script then treated
+ * that as "not on the page yet" and polled for its whole 10s budget before reporting
+ * "element not found", which reads like a slow page rather than a bad argument. Refusing it
+ * here names the real problem immediately.
+ * @param target - the caller's target, or undefined when there is none.
+ * @returns the index, or undefined to let the page default to 0.
+ */
+function targetIndex(target: { readonly index?: unknown } | undefined): number | undefined {
+  const index = target?.index
+  if (index === undefined) return undefined
+  if (typeof index !== 'number' || !Number.isSafeInteger(index) || index < 0) {
+    throw new Error(`target.index must be a non-negative integer (got ${JSON.stringify(index)}); it is a 0-based position among the matches, and negative values such as -1 match nothing — pass the position you want, or narrow the selector`)
+  }
+  return index
+}
+
 /**
  * The task key for a tool call: the calling DSH session id, or the shared
  * default key when the call carries no agent context (CLI probes, tests).
@@ -234,12 +257,12 @@ function parseFillValue(v: string | undefined): string | number | boolean {
 function formatSnapshot(snapshot: {
   url: string
   title?: string
-  elements: readonly { ref: number; kind: string; label: string; x: number; y: number; frame?: boolean }[]
+  elements: readonly { ref: number; kind: string; label: string; x: number; y: number; frame?: boolean; selector?: string }[]
   truncated?: boolean
   challenge?: { blocked: boolean; kind?: string; reason?: string }
 }, options: { coords?: boolean } = {}): string {
   const showCoords = options.coords === true
-  const lines = snapshot.elements.map(el => `[${el.ref}] ${el.kind}: ${el.label}${el.frame === true ? ' (iframe)' : ''}${showCoords ? ` (${el.x},${el.y})` : ''}`)
+  const lines = snapshot.elements.map(el => `[${el.ref}] ${el.kind}: ${el.label}${el.selector !== undefined && el.selector !== '' ? ` {${el.selector}}` : ''}${el.frame === true ? ' (iframe)' : ''}${showCoords ? ` (${el.x},${el.y})` : ''}`)
   const header = `URL: ${snapshot.url}${snapshot.title !== undefined ? `\nTitle: ${snapshot.title}` : ''}`
   const body = lines.length > 0 ? lines.join('\n') : '(no interactive elements found)'
   const tail = snapshot.truncated === true ? '\n(snapshot truncated)' : ''
@@ -252,6 +275,25 @@ function formatSnapshot(snapshot: {
 /** Register all browser tools with `ctx.tools`. */
 export function apply(ctx: Context, config: Config = {}): void {
   const timeoutMs = config.timeoutMs ?? 60_000
+  /**
+   * Longest wait `browser_wait` may poll for, leaving room for the tool call itself to
+   * finish and report.
+   *
+   * `browser_wait` promises a VERDICT — `{ready:false, reason}` — and the enclosing tool
+   * call aborts at `timeoutMs`. A caller-supplied budget longer than that aborted the call
+   * instead, so the documented verdict never arrived. Clamping to just inside the budget is
+   * what keeps the promise: the polling stops, the reason is returned.
+   */
+  const maxWaitMs = Math.max(250, timeoutMs - 5_000)
+  /**
+   * Most fields `browser_fill` accepts in one batch.
+   *
+   * The batch runs as ONE page evaluation, so hundreds of fields do not produce hundreds of
+   * per-field verdicts — they produce a single evaluate that exceeds the tool budget and
+   * throws, which is the opposite of the documented "per-field failures are reported instead
+   * of throwing". Real forms are far smaller than this; anything larger should be split.
+   */
+  const maxFillFields = 200
   // Per-context state: sessions, in-flight opens, and the restriction are
   // scoped to THIS plugin apply, so parallel contexts never share sessions
   // or leak restrictions into each other.
@@ -297,6 +339,12 @@ export function apply(ctx: Context, config: Config = {}): void {
                 x: { type: 'number', required: true },
                 y: { type: 'number', required: true },
                 frame: { type: 'boolean' },
+                // The page-side script computes this for every element and the tool layer
+                // passes it through. Without it in the schema, a declared
+                // additionalProperties: false rejects the whole result at run time — which is
+                // how this was found, on the very first real call, after a static review had
+                // called the change verified.
+                selector: { type: 'string' },
               },
             },
           },
@@ -331,7 +379,7 @@ export function apply(ctx: Context, config: Config = {}): void {
       return {
         url: snapshot.url,
         ...snapshot.title !== undefined ? { title: snapshot.title } : {},
-        elements: snapshot.elements.map(el => ({ ref: el.ref, kind: el.kind, label: el.label, x: el.x, y: el.y, ...el.frame === true ? { frame: true } : {} })),
+        elements: snapshot.elements.map(el => ({ ref: el.ref, kind: el.kind, label: el.label, selector: el.selector, x: el.x, y: el.y, ...el.frame === true ? { frame: true } : {} })),
         truncated: snapshot.truncated,
         ...snapshot.challenge !== undefined ? { challenge: snapshot.challenge } : {},
       }
@@ -365,6 +413,12 @@ export function apply(ctx: Context, config: Config = {}): void {
                 x: { type: 'number', required: true },
                 y: { type: 'number', required: true },
                 frame: { type: 'boolean' },
+                // The page-side script computes this for every element and the tool layer
+                // passes it through. Without it in the schema, a declared
+                // additionalProperties: false rejects the whole result at run time — which is
+                // how this was found, on the very first real call, after a static review had
+                // called the change verified.
+                selector: { type: 'string' },
               },
             },
           },
@@ -391,7 +445,7 @@ export function apply(ctx: Context, config: Config = {}): void {
       return {
         url: snapshot.url,
         ...snapshot.title !== undefined ? { title: snapshot.title } : {},
-        elements: snapshot.elements.map(el => ({ ref: el.ref, kind: el.kind, label: el.label, x: el.x, y: el.y, ...el.frame === true ? { frame: true } : {} })),
+        elements: snapshot.elements.map(el => ({ ref: el.ref, kind: el.kind, label: el.label, selector: el.selector, x: el.x, y: el.y, ...el.frame === true ? { frame: true } : {} })),
         truncated: snapshot.truncated,
         ...snapshot.challenge !== undefined ? { challenge: snapshot.challenge } : {},
       }
@@ -400,10 +454,10 @@ export function apply(ctx: Context, config: Config = {}): void {
 
   ctx.tools.register(defineTool({
     name: 'browser_a11y',
-    description: 'Read the page\'s accessibility tree: every interactive node with its semantic role (button/link/textbox/checkbox/…), accessible name, current value, and states (enabled/disabled/checked/expanded/…), plus coordinates. Prefer this over browser_snapshot to understand a page\'s structure and find the right element: roles and names tell you WHAT each node is, and the coordinates let you drive it with browser_click/browser_type. Penetrates same-origin iframes and shadow roots.',
+    description: 'Read the page\'s accessibility tree: every interactive node with its semantic role (button/link/textbox/checkbox/…), accessible name, current value, and states (enabled/disabled/checked/expanded/…), (coordinates only when coords: true). Prefer this over browser_snapshot to understand a page\'s structure and find the right element: roles and names tell you WHAT each node is, and the name is what browser_click matches when you target by text. Penetrates same-origin iframes and shadow roots.',
     parameters: {
       includeHidden: { type: 'boolean', description: 'Include hidden elements (default false).' },
-      maxNodes: { type: 'number', description: 'Maximum nodes (default 500, range 10-5000).' },
+      maxNodes: { type: 'number', description: 'Maximum nodes (default 150, range 10-5000).' },
       coords: { type: 'boolean', description: 'Include each element\'s viewport coordinates. Off by default: a semantic target needs no coordinates, and they are pure noise unless a vision pass is going to click a pixel position.' },
     },
     output: {
@@ -432,13 +486,19 @@ export function apply(ctx: Context, config: Config = {}): void {
                 x: { type: 'number', required: true },
                 y: { type: 'number', required: true },
                 frame: { type: 'boolean' },
+                // The page-side script computes this for every element and the tool layer
+                // passes it through. Without it in the schema, a declared
+                // additionalProperties: false rejects the whole result at run time — which is
+                // how this was found, on the very first real call, after a static review had
+                // called the change verified.
+                selector: { type: 'string' },
               },
             },
           },
         },
       },
       render: (args, value) => {
-        const nodes = value.nodes as Array<{ ref: number; role: string; name: string; value?: string | null; states: string[]; depth: number; tag: string; x: number; y: number; frame?: boolean }>
+        const nodes = value.nodes as Array<{ ref: number; role: string; name: string; value?: string | null; states: string[]; depth: number; tag: string; x: number; y: number; frame?: boolean; selector?: string }>
         // Built for reading, not for imaging: containment is shown as indentation
         // (the depth was already collected and simply thrown away), an empty state
         // list adds nothing, and coordinates appear only when asked for — a model
@@ -447,13 +507,22 @@ export function apply(ctx: Context, config: Config = {}): void {
         const showCoords = args.coords === true
         const lines = nodes.map(n => {
           const valuePart = n.value !== undefined && n.value !== null ? ` value="${String(n.value).slice(0, 60)}"` : ''
-          const indent = '  '.repeat(Math.max(0, Math.min(8, Number(n.depth) || 0)))
+          // One space per level, not two: indentation was 19.7% of a measured 38,953-character
+          // result, and DOM depth is not a11y depth — deep wrapper divs push it to the cap.
+          const indent = ' '.repeat(Math.max(0, Math.min(8, Number(n.depth) || 0)))
           const coordsPart = showCoords ? ` (${n.x},${n.y})` : ''
-          const statePart = Array.isArray(n.states) && n.states.length > 0 ? ` states=[${n.states.join(',')}]` : ''
-          return `${indent}[${n.ref}] ${n.role} "${n.name}"${valuePart}${coordsPart}${statePart}${n.frame === true ? ' (iframe)' : ''}`
+          // Only states that are not the default. `states=[enabled]` was printed on 405 of 500
+          // nodes whose state WAS the default — 22% of the output for no information. Absence
+          // now means "enabled", which the description states.
+          const notableStates = Array.isArray(n.states) ? n.states.filter((state: string) => state !== 'enabled') : []
+          const statePart = notableStates.length > 0 ? ` states=[${notableStates.join(',')}]` : ''
+          // The provider computes this for a node with an id or a name; printing it is what
+          // makes the node something the caller can point at instead of guessing at its text.
+          const selectorPart = typeof n.selector === 'string' && n.selector !== '' ? ` {${n.selector}}` : ''
+          return `${indent}[${n.ref}] ${n.role} "${n.name}"${valuePart}${coordsPart}${statePart}${selectorPart}${n.frame === true ? ' (iframe)' : ''}`
         })
         const header = `URL: ${value.url}${value.title !== undefined ? `\nTitle: ${value.title}` : ''}`
-        const hint = showCoords ? '' : '\n(coordinates omitted — pass coords: true to include them, or click by semantic target)'
+        const hint = showCoords ? '' : '\n(no coords; pass coords: true)'
         return [{ type: 'text', text: `${header}\n\n${lines.length > 0 ? lines.join('\n') : '(no accessible interactive nodes)'}${value.truncated === true ? '\n(truncated)' : ''}${hint}` }]
       },
     },
@@ -480,6 +549,11 @@ export function apply(ctx: Context, config: Config = {}): void {
           states: [...n.states],
           depth: n.depth,
           tag: n.tag,
+          // The provider computes this and the renderer prints it, but this mapping is an
+          // explicit allow-list rather than a pass-through — so leaving it out here silently
+          // dropped the field between the two, and the tool promised a reference it never
+          // sent. The snapshot mapping lists its selector; this one did not.
+          selector: n.selector,
           x: n.x,
           y: n.y,
           ...n.frame === true ? { frame: true } : {},
@@ -554,7 +628,9 @@ export function apply(ctx: Context, config: Config = {}): void {
       if (browser === undefined) throw new Error('tool-browser: browser service unavailable')
       const session = await ensureSession(browser, state, taskKey(exec), agentOf(exec))
       const result = await browser.waitFor(session, {
-        ...args.timeoutMs !== undefined ? { timeoutMs: args.timeoutMs } : {},
+        // Capped so an over-budget argument returns the documented verdict (see maxWaitMs)
+        // rather than aborting the whole tool call.
+        ...args.timeoutMs !== undefined ? { timeoutMs: Math.min(args.timeoutMs, maxWaitMs) } : {},
         ...args.url !== undefined ? { url: args.url } : {},
         ...args.selector !== undefined ? { selector: args.selector } : {},
       }, exec.signal)
@@ -579,7 +655,18 @@ export function apply(ctx: Context, config: Config = {}): void {
           exception: { type: 'string' },
         },
       },
-      render: (_args, value) => [{ type: 'text', text: value.ok ? `Result: ${String(value.value)}` : `Exception: ${value.exception}` }],
+      // A return value is whatever the page produced, and `document.body.outerHTML` measured
+      // 157,350 characters — ~39-52k tokens from one call. Bounded, with the cut stated so the
+      // caller knows to narrow the expression rather than the value being silently short.
+      render: (_args, value) => {
+        if (!value.ok) return [{ type: 'text', text: `Exception: ${value.exception}` }]
+        const rendered = String(value.value ?? '')
+        const cap = 50_000
+        const text = rendered.length > cap
+          ? `Result: ${rendered.slice(0, cap)}\n(result truncated at ${cap} of ${rendered.length} characters — return a smaller value, or write it with browser_execute + a variable)`
+          : `Result: ${rendered}`
+        return [{ type: 'text', text }]
+      },
     },
     timeoutMs,
     isConcurrencySafe: () => false, // page JS can be stateful
@@ -619,7 +706,7 @@ export function apply(ctx: Context, config: Config = {}): void {
           truncated: { type: 'boolean', required: true },
         },
       },
-      render: (_args, value) => [{ type: 'text', text: value.content + (value.truncated ? '\n(truncated)' : '') }],
+      render: (_args, value) => [{ type: 'text', text: value.content + (value.truncated ? `\n(content truncated — narrow it with selector= or raise maxChars)` : '') }],
     },
     timeoutMs,
     isConcurrencySafe: () => true,
@@ -665,7 +752,10 @@ export function apply(ctx: Context, config: Config = {}): void {
       },
       render: (_args, value) => [{
         type: 'text',
-        text: `${value.count} item(s):\n${JSON.stringify(value.items, null, 2)}`,
+        // Compact, unlike the pretty-printed form this used to emit: two-space indentation
+        // carries no information a model can use and cost 13.7% of a measured 39,559-character
+        // result. The count leads so the caller can tell a short list from a capped one.
+        text: `${value.count} item(s):\n${JSON.stringify(value.items)}`,
       }],
     },
     timeoutMs,
@@ -720,12 +810,13 @@ export function apply(ctx: Context, config: Config = {}): void {
       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')
       }
+      const index = targetIndex(target)
       if (target !== undefined && typeof target.value === 'string' && target.value !== '') {
         await browser.click(session, {
           target: {
             by: (target.by === 'text' || target.by === 'xpath' ? target.by : 'css') as 'css' | 'text' | 'xpath',
             value: target.value,
-            ...target.index !== undefined ? { index: target.index } : {},
+            ...index !== undefined ? { index } : {},
           },
         }, exec.signal)
       } else {
@@ -772,13 +863,14 @@ export function apply(ctx: Context, config: Config = {}): void {
       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')
       }
+      const index = targetIndex(target)
       if (target !== undefined && typeof target.value === 'string' && target.value !== '') {
         await browser.type(session, {
           text: args.text,
           target: {
             by: (target.by === 'text' || target.by === 'xpath' ? target.by : 'css') as 'css' | 'text' | 'xpath',
             value: target.value,
-            ...target.index !== undefined ? { index: target.index } : {},
+            ...index !== undefined ? { index } : {},
           },
         }, exec.signal)
       } else {
@@ -966,7 +1058,11 @@ export function apply(ctx: Context, config: Config = {}): void {
       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: { selector?: string; name?: string; label?: string; placeholder?: string; kind?: string; value?: string }) => {
+      const requested = args.fields ?? []
+      if (requested.length > maxFillFields) {
+        throw new Error(`browser_fill: ${requested.length} fields in one call exceeds the ${maxFillFields}-field limit; split it into several calls so each one can report per-field results instead of timing out as a batch`)
+      }
+      const fields = requested.map((f: { selector?: string; name?: string; label?: string; placeholder?: string; kind?: string; value?: string }) => {
         // 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
@@ -1197,7 +1293,7 @@ export function apply(ctx: Context, config: Config = {}): void {
 
   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 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.',
+    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; some carriers (the desktop sidebar) return PNG instead. 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.' },
@@ -1211,7 +1307,9 @@ export function apply(ctx: Context, config: Config = {}): void {
         type: 'object',
         additionalProperties: false,
         properties: {
-          dataUrl: { type: 'string', required: true, description: 'Base64 PNG data URL of the screenshot.' },
+          dataUrl: { type: 'string', required: true, description: 'Base64 data URL of the screenshot (PNG, or JPEG when the carrier uses CDP JPEG).' },
+          width: { type: 'number', description: 'Pixel width of the returned image, when the capture was measured (present with maxWidth/maxHeight).' },
+          height: { type: 'number', description: 'Pixel height of the returned image, when the capture was measured.' },
           path: { type: 'string', description: 'The file path the screenshot was saved to, when savePath was given.' },
         },
       },
@@ -1348,7 +1446,9 @@ export function apply(ctx: Context, config: Config = {}): void {
   ctx.tools.register(defineTool({
     name: 'browser_history',
     description: 'List the shared browser session\'s recorded operation history (navigate/execute/click/type), newest last, with per-step success/error. Use to understand what the agent did and to pick a step to replay.',
-    parameters: {},
+    parameters: {
+      verbose: { type: 'boolean', description: "Include each operation's parameters (default false). They are what you just sent, so they are omitted unless asked for." },
+    },
     output: {
       schema: {
         type: 'object',
@@ -1372,17 +1472,20 @@ export function apply(ctx: Context, config: Config = {}): void {
           },
         },
       },
-      render: (_args, value) => {
+      render: (args, value) => {
         const entries = value.entries as Array<{ seq: number; action: string; ok: boolean; params: Record<string, unknown>; result?: string; error?: string }>
         if (entries.length === 0) return [{ type: 'text', text: '(no recorded operations yet)' }]
-        return [{
-          type: 'text',
-          text: entries.map(e => {
-            const rawParams = JSON.stringify(e.params)
-            const shownParams = rawParams.length > 300 ? rawParams.slice(0, 300) + '…' : rawParams
-            return `#${e.seq} ${e.action} ${e.ok ? 'ok' : 'FAIL'} ${shownParams}${e.result !== undefined ? ` -> ${e.result}` : ''}${e.error !== undefined ? ` !! ${e.error}` : ''}`
-          }).join('\n'),
-        }]
+        // The parameters are what the caller itself just sent, so echoing them back is cost
+        // without information — measured at 18,162 characters for 200 operations, of which the
+        // per-entry params dominated. Only the tail is shown by default: the recent steps are
+        // what a caller reasons about, and the count leads so the tail is not mistaken for all.
+        const recent = entries.slice(-20)
+        const omitted = entries.length - recent.length
+        const lines = recent.map(e => `#${e.seq} ${e.action} ${e.ok ? 'ok' : 'FAIL'}${e.result !== undefined ? ` -> ${e.result}` : ''}${e.error !== undefined ? ` !! ${e.error}` : ''}${args.verbose === true ? ` ${JSON.stringify(e.params)}` : ''}`)
+        const header = omitted > 0
+          ? `${entries.length} operations recorded; showing the last ${recent.length} (${args.verbose === true ? '' : ' (pass verbose: true for parameters)'}):`
+          : `${entries.length} operation(s):`
+        return [{ type: 'text', text: `${header}\n${lines.join('\n')}` }]
       },
     },
     timeoutMs,
@@ -1470,15 +1573,20 @@ export function apply(ctx: Context, config: Config = {}): void {
       },
       render: (_args, value) => {
         const entries = value.entries as Array<{ at: number; url: string; title?: string; session?: string }>
+        let lastSession: string | undefined
         if (entries.length === 0) {
           return [{ type: 'text', text: '(no recorded visits — nothing has been browsed yet, or history recording is turned off in settings)' }]
         }
         return [{
           type: 'text',
           text: entries.map(entry => {
-            const when = new Date(entry.at).toISOString().replace('T', ' ').slice(0, 19)
+            const when = new Date(entry.at).toISOString().replace('T', ' ').slice(0, 16)
             const title = entry.title !== undefined ? `${entry.title} — ` : ''
-            return `${when}  ${title}${entry.url}${entry.session !== undefined ? `  [${entry.session}]` : ''}`
+            const tag = entry.session !== undefined && entry.session !== lastSession
+              ? `  [session ${entry.session.slice(0, 8)}]`
+              : ''
+            lastSession = entry.session
+            return `${when}  ${title}${entry.url}${tag}`
           }).join('\n'),
         }]
       },
@@ -1628,7 +1736,7 @@ export function apply(ctx: Context, config: Config = {}): void {
 
   ctx.tools.register(defineTool({
     name: 'browser_restrict',
-    description: 'Restrict which browser actions are allowed, to prevent stray clicks/navigation. Pass a list of browser tool names (e.g. ["browser_snapshot","browser_content","browser_click"]) — any other browser_* call is refused. Pass an empty list or omit to lift the restriction. Read-only tools (snapshot/content/screenshot/session) are never blocked. IMPORTANT: this is a SOFT guardrail against accidental actions, NOT a security boundary — you (the model) can lift it yourself with an empty list.',
+    description: 'Restrict which browser actions are allowed, to prevent stray clicks/navigation. Pass a list of browser tool names (e.g. ["browser_snapshot","browser_content","browser_click"]) — any other browser_* call is refused. Pass an empty list or omit to lift the restriction. Never blocked, whatever the list says: the observing tools (snapshot/a11y/content/scrape/screenshot/get_value/wait/challenge/list_tabs/session/history/visited) and the three that lift a restriction or recover from a bad state (restrict/reset/reset_session) — so a restriction can always be read around and undone. IMPORTANT: this is a SOFT guardrail against accidental actions, NOT a security boundary — you (the model) can lift it yourself with an empty list.',
     parameters: {
       allowed: {
         type: 'array',
@@ -1662,7 +1770,7 @@ export function apply(ctx: Context, config: Config = {}): void {
 
   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).' },
@@ -1693,7 +1801,7 @@ export function apply(ctx: Context, config: Config = {}): void {
       // 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)')
+        throw new Error('browser_auth: action "restore" needs a non-empty "cookies" array (get one from action "flush" on the same profile)')
       }
       const list = args.cookies as unknown[]
       const restored = await browser.restoreAuth(session, list as never)