dsh-builtin-browser 0.4.0 → 0.4.2

package/src/browser-electron/provider.ts

@@ -8,7 +8,7 @@
  */
 
 import { randomUUID } from 'node:crypto'
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { existsSync, lstatSync, mkdirSync, realpathSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, isAbsolute, join, resolve, sep } from 'node:path'
 import { HistoryStore, type VisitedPage } from './history-store.js'
@@ -306,7 +306,16 @@ export interface ElectronBrowserProviderConfig {
   readonly settings?: () => BrowserSettings
   /** Maximum snapshot elements before truncation. Default 60. */
   readonly snapshotMaxElements?: number
-  /** Maximum content characters before truncation when no maxChars is given. Default 100_000. */
+  /**
+   * Explicit content cap, overriding the per-format default when set.
+   *
+   * Honoured again, and it is worth saying why that is a fix rather than a feature: this was
+   * `config.contentMaxChars ?? 100_000`, one number for every format, and when the caps became
+   * per-format (html and json 50 000, otherwise 20 000) the field was left assigned and never
+   * read. A configuration knob that silently does nothing is worse than no knob — it is an
+   * operator's decision that quietly went nowhere. Leaving it unset means the per-format
+   * default; setting it means the operator meant it.
+   */
   readonly contentMaxChars?: number
   /**
    * Directory `browser_download` save paths must resolve inside (prevents a
@@ -524,6 +533,57 @@ function defaultDownloadDir(): string {
   return join(homedir(), DOWNLOAD_DIR_NAMES[0] ?? 'Downloads')
 }
 
+/**
+ * Whether a directory entry exists at `path`, judging the ENTRY rather than what it
+ * points at.
+ *
+ * `existsSync` follows links, so a DANGLING symlink — a link whose target does not
+ * exist — reads as "nothing here", and a write to that path creates the target
+ * instead: outside `downloadDir` whenever the link points out of it. `lstatSync`
+ * sees the link itself, which is the only correct answer to "is this name free".
+ * @param path - the path to judge.
+ * @returns true when any entry (file, directory, link) occupies the name.
+ */
+function entryExists(path: string): boolean {
+  try {
+    lstatSync(path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * The real path of the deepest existing ancestor of `path` — `path` itself when it
+ * exists, otherwise the nearest directory above it that does.
+ *
+ * `resolve()` normalizes `..` but never follows a link, so nothing textual can tell
+ * that `<downloadDir>/link/x.png` leaves the directory through `link`. The first
+ * ancestor that exists (judged by lstat, so a dangling link counts — the write would
+ * go through it) is the last component whose real location still determines where
+ * the bytes land, so that is the one to resolve and check.
+ * @param path - an absolute path that may not exist yet.
+ * @returns the resolved real path of its deepest existing ancestor.
+ */
+function realAncestorOf(path: string): string {
+  let current = path
+  for (let depth = 0; depth < 64; depth += 1) {
+    if (entryExists(current)) {
+      try {
+        return realpathSync(current)
+      } catch {
+        // The entry vanished between the two calls, or cannot be resolved: the
+        // textual path is the best available answer, and the write reports the rest.
+        return current
+      }
+    }
+    const parent = dirname(current)
+    if (parent === current) return current
+    current = parent
+  }
+  return current
+}
+
 /**
  * Browser provider over Electron views. Sessions hold an ordered list of
  * tabs; each tab is one view created by the host. The active tab receives
@@ -537,7 +597,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
   private readonly sessions = new Map<BrowserSessionId, Session>()
   private readonly httpOnly: boolean
   private readonly snapshotMaxElements: number
-  private readonly contentMaxChars: number
+  private readonly contentMaxChars: number | undefined
   private readonly downloadDir: string | undefined
   /**
    * Persistent browsing history, or `undefined` when the user turned it off.
@@ -553,7 +613,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
   ) {
     this.httpOnly = config.httpOnly ?? true
     this.snapshotMaxElements = config.snapshotMaxElements ?? 60
-    this.contentMaxChars = config.contentMaxChars ?? 100_000
+    this.contentMaxChars = config.contentMaxChars
     // Confine downloads AND screenshot saves to a dedicated directory by
     // default: the OS Downloads folder is the human-visible, browser-natural
     // place for written files, and it is the one directory the DSH file
@@ -850,13 +910,16 @@ export class ElectronBrowserProvider implements BrowserProvider {
    * Chromium drops `Input.*` events for a view with no display surface, so this
    * runs before click/type/key and fails loudly (BROWSER_VIEW_NOT_PRESENTED)
    * rather than reporting a success the page never saw.
+   * @param s - the session whose active view must be presented.
+   * @param signal - optional cancellation.
+   * @returns the view the session's active tab has AFTER the presentation barrier.
    */
-  private async present(s: Session, signal?: AbortSignal): Promise<void> {
+  private async present(s: Session, signal?: AbortSignal): Promise<ElectronViewHandle> {
     const { handle } = this.activeTab(s)
     const present = this.host.presentView?.bind(this.host)
     if (present === undefined) {
       this.showActive(s)
-      return
+      return this.activeTab(s).handle
     }
     signal?.throwIfAborted()
     const timeoutMs = 10_000
@@ -875,6 +938,48 @@ export class ElectronBrowserProvider implements BrowserProvider {
         { cause: error },
       )
     }
+    // Read the active tab AGAIN. `present` is a round-trip that can take up to the budget
+    // above, and the human is invited to drive the same window (a toolbar tab switch, a
+    // closed window) while the agent waits. Chromium answers `Input.*` with success even
+    // for a view that has no display surface, so dispatching to a handle that is no longer
+    // the visible one does not fail — it silently lands nowhere, or on the wrong page.
+    //
+    // Returning the re-read handle was wrong, though: `handle` above is the one that was
+    // actually presented, and if the active tab changed during the round trip then the
+    // re-read one was never presented at all. Handing it back meant the caller dispatched
+    // to a view with no display surface — the exact failure this method exists to prevent,
+    // arrived at from the other side. Either the presented view is still the active one, or
+    // the caller must be told rather than given something else to aim at.
+    const live = this.activeTab(s).handle
+    if (live !== handle) {
+      throw new BrowserError(
+        'browser: the active tab changed while the page view was being presented, so synthesized input would go to an unshown view — retry, and the new page will be presented instead',
+        'BROWSER_VIEW_CHANGED',
+      )
+    }
+    return handle
+  }
+
+  /**
+   * Refuse to send synthesized input to a view that is no longer the one it was located
+   * against.
+   *
+   * `locateHandle` was captured before a page-side locate that can consume its whole
+   * 10s budget; the session's active tab is re-read afterwards. If they differ, the human
+   * switched tabs mid-flight (the product's whole point is that they can take over), and
+   * the coordinates belong to one page while the dispatch would go to another. Comparing
+   * the handles turns that into a loud, retryable error instead of input the caller
+   * believes landed.
+   * @param session - the session id, for the message.
+   * @param locateHandle - the view the locate ran in.
+   * @param liveHandle - the view that is active now.
+   */
+  private assertSameView(session: BrowserSessionId, locateHandle: ElectronViewHandle, liveHandle: ElectronViewHandle): void {
+    if (locateHandle === liveHandle) return
+    throw new BrowserError(
+      `browser: the session's active view changed while the element was being located (session ${session}); the operation was not dispatched — retry it`,
+      'BROWSER_VIEW_CHANGED',
+    )
   }
 
   /**
@@ -903,6 +1008,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
 
   /** Execute JS in the active tab's page context. */
   async execute(session: BrowserSessionId, request: BrowserExecuteRequest, signal?: AbortSignal): Promise<BrowserExecuteResult> {
+    this.assertActionAllowed('execute')
     const s = this.session(session)
     const { handle } = this.activeTab(s)
     signal?.throwIfAborted()
@@ -1140,7 +1246,9 @@ export class ElectronBrowserProvider implements BrowserProvider {
     const tab = this.activeTab(s)
     signal?.throwIfAborted()
     const includeHidden = request.includeHidden === true
-    const maxNodes = Math.max(10, Math.min(5000, Math.floor(request.maxNodes ?? 500)))
+    // 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.
+      const maxNodes = Math.max(10, Math.min(5000, Math.floor(request.maxNodes ?? 150)))
     const script = `(() => {
       const includeHidden = ${String(includeHidden)}
       const maxNodes = ${String(maxNodes)}
@@ -1282,6 +1390,11 @@ export class ElectronBrowserProvider implements BrowserProvider {
             value: valueOf(el),
             states: statesOf(el),
             depth: baseDepth + depthOf(el),
+            // Same derivation as the snapshot collector: an id or a name is what makes a node
+            // something the caller can point at without guessing at its text. The tool-layer
+            // schema declared this field before this line existed, so the schema was promising
+            // a value the tool never sent.
+            selector: el.id ? '#' + CSS.escape(el.id) : (el.name ? '[name=' + JSON.stringify(el.name) + ']' : ''),
             tag: el.tagName.toLowerCase(),
             x: Math.round(a.x + a.w / 2),
             y: Math.round(a.y + a.h / 2),
@@ -1330,9 +1443,18 @@ export class ElectronBrowserProvider implements BrowserProvider {
   async content(session: BrowserSessionId, request: BrowserContentRequest, signal?: AbortSignal): Promise<BrowserContentResult> {
     const tab = this.activeTab(this.session(session))
     signal?.throwIfAborted()
-    const maxChars = request.maxChars ?? this.contentMaxChars
     const selector = request.selector ?? ''
     const format = request.format
+    // Per-format caps. A full HTML document is enormous, but the same limit applied to
+    // plain text is no limit at all (a whole page of text measured 25,882 characters).
+    // This bounds the common case instead of letting one call spend 25k-33k tokens.
+    //
+    // The plugin config overrides the lot when it is set — see `contentMaxChars`. The caller's
+    // own `maxChars` still outranks both: an explicit per-call bound is the most specific
+    // statement of intent there is.
+    const maxChars = request.maxChars
+      ?? this.contentMaxChars
+      ?? (format === 'html' || format === 'json' ? 50_000 : 20_000)
     const script = `(() => {
       const root = ${selector === '' ? 'document.body' : `document.querySelector(${JSON.stringify(selector)})`}
       if (!root) return { ok: false, reason: 'selector not found' }
@@ -1376,7 +1498,12 @@ export class ElectronBrowserProvider implements BrowserProvider {
         }
       }
       else if (fmt === 'html') content = root.outerHTML || ''
-      else if (fmt === 'json') content = JSON.stringify(root)
+      // A DOM element has no own enumerable properties — everything lives on the prototype
+      // chain — so JSON.stringify(root) is always "{}". That is not a structured view of
+      // the page, it is an empty object the caller will read as "no data here" and then
+      // retry with other selectors. Serialise the markup instead, which is what a caller
+      // asking for JSON of an element can actually use.
+      else if (fmt === 'json') content = JSON.stringify({ html: root.outerHTML, tag: root.tagName.toLowerCase() })
       else {
         // markdown: headings, paragraphs, links, lists (best-effort)
         const parts = []
@@ -1431,7 +1558,9 @@ export class ElectronBrowserProvider implements BrowserProvider {
     signal?: AbortSignal,
   ): Promise<void> {
     const s = this.session(session)
-    const { handle } = this.activeTab(s)
+    // The view the locate runs against. It can stop being the session's active view while
+    // the locate waits (see prepareTarget), so every dispatch below re-reads the live one.
+    const locateHandle = this.activeTab(s).handle
     signal?.throwIfAborted()
     let x = 0
     let y = 0
@@ -1465,8 +1594,13 @@ export class ElectronBrowserProvider implements BrowserProvider {
       y = request.y
     }
     // Input.* is only delivered to a view with a current display surface; the
-    // barrier also re-presents after a navigation replaced the renderer.
-    await this.present(s, signal)
+    // barrier also re-presents after a navigation replaced the renderer. It returns the
+    // handle that may still be receiving input when it settles.
+    const handle = await this.present(s, signal)
+    // The locate (up to 10s) and the present barrier both ran against the view captured
+    // earlier; if the human switched tabs meanwhile, these coordinates belong to one page
+    // and the dispatch would go to another — and Chromium answers success either way.
+    if ('target' in request) this.assertSameView(session, locateHandle, handle)
     const timeoutMs = 30_000
     const send = (params: Record<string, unknown>, label: string): Promise<unknown> =>
       withTimeout(
@@ -1493,6 +1627,10 @@ export class ElectronBrowserProvider implements BrowserProvider {
     // tab" signal, so the bubble is what lets a human follow along without the log.
     this.showCursor(handle, x, y, 'click', 'click', true)
     const release = (): void => {
+      // Back to the handle the PRESS may have landed on, deliberately not to the currently
+      // active tab: this only runs after a failed press/release, and re-targeting a
+      // compensating half of a click to a view the human just switched to would press a
+      // button there. Best-effort either way.
       void handle
         .sendCommand('Input.dispatchMouseEvent', {
           type: 'mouseReleased',
@@ -1532,7 +1670,10 @@ export class ElectronBrowserProvider implements BrowserProvider {
     signal?: AbortSignal,
   ): Promise<void> {
     const s = this.session(session)
-    const { handle } = this.activeTab(s)
+    // The view the locate runs against. It can stop being the session's active view while
+    // the locate waits (the human is invited to drive the same window), so the input below
+    // goes to the handle `present` reports instead of this one.
+    const locateHandle = this.activeTab(s).handle
     signal?.throwIfAborted()
     const hasTarget = 'target' in request
     if (hasTarget) {
@@ -1549,8 +1690,13 @@ export class ElectronBrowserProvider implements BrowserProvider {
     const text = 'text' in request ? request.text : ''
     const timeoutMs = 30_000
     // Input.insertText goes through the Input domain: same display-surface
-    // requirement as click/key.
-    await this.present(s, signal)
+    // requirement as click/key. It also reports which view is active once the barrier has
+    // settled, which is what makes the tab-switch check below meaningful.
+    const handle = await this.present(s, signal)
+    // Focusing one page and inserting into another is exactly the silent mis-target this
+    // refuses: the element was focused in the located view, and the text would have gone to
+    // whichever page is now visible — possibly a password field there.
+    if (hasTarget) this.assertSameView(session, locateHandle, handle)
     try {
       await withTimeout(
         handle.sendCommand('Input.insertText', { text } satisfies CdpInsertTextParams),
@@ -1674,7 +1820,6 @@ export class ElectronBrowserProvider implements BrowserProvider {
   /** Press one named key (Enter/Tab/arrows/…) via CDP key events. */
   async key(session: BrowserSessionId, request: BrowserKeyRequest, signal?: AbortSignal): Promise<void> {
     const s = this.session(session)
-    const { handle } = this.activeTab(s)
     signal?.throwIfAborted()
     const spec = KEY_SPECS[request.key]
     if (spec === undefined) {
@@ -1682,8 +1827,13 @@ export class ElectronBrowserProvider implements BrowserProvider {
     }
     const params = { key: spec.key, code: spec.code, windowsVirtualKeyCode: spec.vk, nativeVirtualKeyCode: spec.vk, ...spec.text !== undefined ? { text: spec.text } : {} }
     const timeoutMs = 15_000
-    // Input.dispatchKeyEvent is subject to the same display-surface rule.
-    await this.present(s, signal)
+    // Input.dispatchKeyEvent is subject to the same display-surface rule. The handle comes
+    // back from the presentation barrier rather than from a capture taken before it: this
+    // session is shared with the human, who may switch tabs while the barrier round-trips,
+    // and a key sent to the view they left is silently dropped (or lands on the new page).
+    const handle = await this.present(s, signal)
+    // Focus the SAME view the key is dispatched to; focusing the pre-switch handle would
+    // grant web focus to a page that then receives nothing.
     await this.focusView(handle)
     const release = (): Promise<Record<string, unknown>> =>
       handle.sendCommand('Input.dispatchKeyEvent', { type: 'keyUp', ...params })
@@ -1721,7 +1871,13 @@ export class ElectronBrowserProvider implements BrowserProvider {
       name: f.name ?? null,
       label: f.label ?? null,
       placeholder: f.placeholder ?? null,
-      kind: f.kind ?? 'text',
+      // 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
+      // `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.
+      kind: f.kind ?? null,
       value: f.value,
     })))
     const submitFlag = request.submit === true
@@ -1754,10 +1910,34 @@ export class ElectronBrowserProvider implements BrowserProvider {
         }
         return false
       }
+      // Every root this page exposes: the top document plus its shadow trees (recursively)
+      // and same-origin iframes. The snapshot and waitFor already walk all of them, so an
+      // element inside one is shown to the model and can be waited for — resolving a click or
+      // a fill used to look at the top document alone and answer "not found" for something
+      // the model had just been handed a reference to. The two must agree about what exists.
+      // (Kept in step with the collector in the snapshot script above.)
+      const allRoots = () => {
+        const roots = []
+        const seen = new Set()
+        const visit = doc => {
+          if (seen.has(doc)) return
+          seen.add(doc)
+          roots.push(doc)
+          for (const el of doc.querySelectorAll('*')) {
+            if (el.shadowRoot) visit(el.shadowRoot)
+            if (el.tagName === 'IFRAME') {
+              try { const d = el.contentDocument; if (d) visit(d) } catch { /* cross-origin */ }
+            }
+          }
+        }
+        visit(document)
+        return roots
+      }
+      const roots = allRoots()
       const candidates = (spec) => {
         const all = spec.selector
-          ? [...document.querySelectorAll(spec.selector)]
-          : [...document.querySelectorAll('input, textarea, select, [contenteditable="true"]')].filter(el => matches(el, spec))
+          ? roots.flatMap(root => [...root.querySelectorAll(spec.selector)])
+          : roots.flatMap(root => [...root.querySelectorAll('input, textarea, select, [contenteditable="true"]')]).filter(el => matches(el, spec))
         const vis = all.filter(visible)
         return vis.length > 0 ? vis : all
       }
@@ -1775,7 +1955,9 @@ export class ElectronBrowserProvider implements BrowserProvider {
         let el = els[0]
         // The caller may name a kind. Honor it: the branches below read the element's own
         // tag/type, so without this a selector matching two different controls acted on
-        // whichever came first — usually right, which is what hid the mistake.
+        // whichever came first — usually right, which is what hid the mistake. A field that
+        // names NO kind gets no filter at all: the element's own tag then decides the
+        // branch, which is what "kind defaults to text" was always trying to say.
         if (spec.kind) {
           const matchesKind = (node) => {
             const nodeTag = node.tagName
@@ -1783,6 +1965,12 @@ export class ElectronBrowserProvider implements BrowserProvider {
             if (spec.kind === 'select') return nodeTag === 'SELECT'
             if (spec.kind === 'textarea') return nodeTag === 'TEXTAREA'
             if (spec.kind === 'checkbox' || spec.kind === 'radio') return nodeType === spec.kind
+            // 'text': the plain-value branch covers <input> AND <textarea>, and the batch
+            // already collects [contenteditable="true"] as a settable control — so all three
+            // must match. Requiring nodeTag === 'INPUT' here reported "no text control
+            // matched" for a textarea and left the contenteditable branch below unreachable.
+            if (nodeTag === 'TEXTAREA') return true
+            if (node.isContentEditable === true) return true
             return nodeTag === 'INPUT' && nodeType !== 'checkbox' && nodeType !== 'radio' && nodeType !== 'file'
           }
           const wanted = els.find(matchesKind)
@@ -1904,33 +2092,78 @@ export class ElectronBrowserProvider implements BrowserProvider {
       const match = () => {
         const by = typeof spec.by === 'string' ? spec.by : 'css'
         const value = String(spec.value ?? '')
-        const index = typeof spec.index === 'number' ? spec.index : 0
+        // Named matchIndex rather than index: this whole function is one host-side template
+        // literal, so a bare name declared here can silently shadow a host binding of the
+        // same name and turn an inner reference into a type error.
+        const matchIndex = typeof spec.index === 'number' ? spec.index : 0
+        // An index that cannot address an element can never match on a later poll, exactly
+        // like a selector that fails to parse — so it must not look like a miss either. A
+        // negative index, the common "last one" shorthand, otherwise burned the caller's
+        // whole locate budget (10s) and then reported "element not found", which reads like a
+        // slow page rather than a bad argument.
+        // (No backticks in this comment: it lives inside a template literal.)
+        if (!Number.isInteger(matchIndex) || matchIndex < 0) {
+          throw new Error('target.index must be a non-negative integer, got ' + JSON.stringify(spec.index))
+        }
         let els = []
+        // Every root this page exposes: the top document plus its shadow trees (recursively)
+        // and same-origin iframes. The snapshot and waitFor already walk all of them, so an
+        // element inside one is shown to the model and can be waited for — resolving a click or
+        // a fill used to look at the top document alone and answer "not found" for something
+        // the model had just been handed a reference to. The two must agree about what exists.
+        // (Kept in step with the collector in the snapshot script above.)
+        const allRoots = () => {
+          const roots = []
+          const seen = new Set()
+          const visit = doc => {
+            if (seen.has(doc)) return
+            seen.add(doc)
+            roots.push(doc)
+            for (const el of doc.querySelectorAll('*')) {
+              if (el.shadowRoot) visit(el.shadowRoot)
+              if (el.tagName === 'IFRAME') {
+                try { const d = el.contentDocument; if (d) visit(d) } catch { /* cross-origin */ }
+              }
+            }
+          }
+          visit(document)
+          return roots
+        }
+        const roots = allRoots()
         if (by === 'css') {
           // A selector that does not PARSE can never match on a later poll, so
           // it must not look like a miss: the old "return null" kept the caller
           // polling until the whole budget was gone, and "element not found
           // after 10s" reads like a slow page while the real cause is a
           // malformed selector (a label or plain text passed where one belongs).
-          try { els = Array.from(document.querySelectorAll(value)) }
+          // Parse on the top document first: a selector that does not PARSE must still be
+          // reported as a bad argument rather than as a miss, and that check is about syntax,
+          // not about which root holds the element.
+          try { document.querySelectorAll(value) }
           catch (error) { throw new Error('invalid CSS selector ' + JSON.stringify(value) + ' (' + String((error && error.message) || error) + ')') }
+          for (const root of roots) els.push(...root.querySelectorAll(value))
         } else if (by === 'xpath') {
           try {
-            const snap = document.evaluate(value, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null)
-            for (let i = 0; i < snap.snapshotLength; i++) {
-              const n = snap.snapshotItem(i)
-              if (n instanceof Element) els.push(n)
+            for (const root of roots) {
+              const snap = document.evaluate(value, root, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null)
+              for (let i = 0; i < snap.snapshotLength; i++) {
+                const n = snap.snapshotItem(i)
+                if (n instanceof Element) els.push(n)
+              }
             }
           } catch (error) { throw new Error('invalid XPath ' + JSON.stringify(value) + ' (' + String((error && error.message) || error) + ')') }
         } else {
-          const all = Array.from(document.querySelectorAll('body *'))
+          // '*' rather than 'body *': a shadow root and an iframe document have no body of
+          // their own to anchor to, and the visibility and own-text predicates below are what
+          // actually decide whether an element counts.
+          const all = roots.flatMap(root => [...root.querySelectorAll('*')])
           const exact = all.filter(el => isVisible(el) && ownText(el) === value)
           // Exact first, then contains; deepest element preferred (so a
           // button inside a card wins over the card itself).
           const pool = exact.length > 0 ? exact : all.filter(el => isVisible(el) && ownText(el).includes(value))
           els = pool.sort((a, b) => depth(b) - depth(a))
         }
-        return els[index] ?? null
+        return els[matchIndex] ?? null
       }
       const deadline = Date.now() + timeoutMs
       let el = null
@@ -2225,6 +2458,35 @@ export class ElectronBrowserProvider implements BrowserProvider {
     return { count: items.length, items }
   }
 
+  /**
+   * 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
+   * 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.
+   *
+   * Read through `settingsSource` on every call rather than captured at construction, so
+   * flipping a switch applies to the next command instead of the next restart — the same
+   * rule the credentials gate follows.
+   * @param action - which switch to consult.
+   * @throws BrowserError when that switch is off.
+   */
+  private assertActionAllowed(action: 'execute' | 'download' | 'credentialWrite'): void {
+    const settings = this.settingsSource?.()
+    if (settings === undefined) return
+    if (action === 'execute' && !settings.actions.allowExecute) {
+      throw new BrowserError('browser: running page scripts is switched off in settings (Browser → actions)', 'BROWSER_EXECUTE_DISABLED')
+    }
+    if (action === 'download' && !settings.actions.allowDownload) {
+      throw new BrowserError('browser: downloads are switched off in settings (Browser → actions)', 'BROWSER_DOWNLOAD_DISABLED')
+    }
+    if (action === 'credentialWrite' && !settings.actions.allowCredentialWrite) {
+      throw new BrowserError('browser: writing cookies is switched off in settings (Browser → actions)', 'BROWSER_AUTH_WRITE_DISABLED')
+    }
+  }
+
   /**
    * 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
@@ -2245,19 +2507,55 @@ export class ElectronBrowserProvider implements BrowserProvider {
     const file = resolve(savePath)
     if (this.downloadDir !== undefined) {
       const dir = resolve(this.downloadDir)
-      // Case-insensitive comparison: Windows paths are case-insensitive, and
-      // resolve() does not normalize case. Without this, C:\Users\X\Downloads
-      // and c:\users\x\downloads would be treated as different roots.
-      const dirLower = dir.toLowerCase()
-      const fileLower = file.toLowerCase()
-      if (fileLower !== dirLower && !fileLower.startsWith(dirLower + sep.toLowerCase())) {
+      // Windows paths are case-insensitive and resolve() does not normalize case, so there
+      // the containment check folds case — otherwise C:\Users\X\Downloads and
+      // c:\users\x\downloads would read as different roots. Everywhere else the fold is
+      // REMOVED: a case-sensitive filesystem (Linux) treats /home/u/DOWNLOADS and
+      // /home/u/Downloads as different directories, so folding case there let a savePath
+      // that merely differed in case pass admission — a directory-confinement escape, and
+      // one that mkdirSync below would then happily create.
+      const fold = process.platform === 'win32' ? (value: string): string => value.toLowerCase() : (value: string): string => value
+      const dirKey = fold(dir)
+      const fileKey = fold(file)
+      // The directory ITSELF is refused, not accepted: a save path that IS downloadDir names
+      // a directory, so there is no file to write — and mkdirSync would have created the
+      // directory when it did not exist. Two paths are "inside" only when the file path is
+      // strictly below the directory, which the separator check below already expresses.
+      if (!fileKey.startsWith(dirKey + fold(sep))) {
         throw new BrowserError(`browser: ${kind} savePath must be inside downloadDir "${dir}"`, code)
       }
+      // The check above is textual, and a symlink defeats it: resolve() normalizes `..`
+      // but never follows a link, so `<downloadDir>/out/x.png` passed every test above
+      // while `out` pointed at a directory outside the gate — and the write then landed
+      // there. Resolve the REAL location of the deepest existing ancestor (which is what
+      // decides where the bytes go) and require it to be inside the real directory too.
+      // A legitimate path is unaffected: its ancestor resolves to the directory itself.
+      //
+      // The directory is created first so that it can be resolved at all — mkdirSync is a
+      // no-op for one that already exists — and a directory that cannot be created or
+      // resolved falls back to its textual form, leaving the real filesystem error to the
+      // write instead of inventing one here.
+      let realDir: string
+      try {
+        mkdirSync(dir, { recursive: true })
+        realDir = fold(realpathSync(dir))
+      } catch {
+        realDir = fold(dir)
+      }
+      const realAncestor = fold(realAncestorOf(file))
+      if (realAncestor !== realDir && !realAncestor.startsWith(realDir + fold(sep))) {
+        throw new BrowserError(`browser: ${kind} savePath resolves outside downloadDir "${dir}" (a symlink leaves it)`, code)
+      }
     }
     // Never replace an existing file: its previous content is unrecoverable,
     // and the admitted directory may hold files the human put there. A new
     // name is one tool call away.
-    if (existsSync(file)) {
+    //
+    // Judged with lstat (see {@link entryExists}), not existsSync: existsSync FOLLOWS
+    // links, so a DANGLING symlink read as "nothing here" and the write below created
+    // its target — outside the directory whenever the link pointed out of it. It is the
+    // directory entry that has to be free, whatever that entry points at.
+    if (entryExists(file)) {
       throw new BrowserError(`browser: refusing to overwrite existing file "${file}" — use another name`, code)
     }
     return file
@@ -2276,6 +2574,9 @@ export class ElectronBrowserProvider implements BrowserProvider {
    * @returns the path the file was written to.
    */
   async download(session: BrowserSessionId, request: { readonly url: string; readonly savePath: string }, signal?: AbortSignal): Promise<{ readonly path: string }> {
+    // Before admission, and before the session is even resolved: a switched-off action is
+    // not a path problem, and the caller should hear the real reason.
+    this.assertActionAllowed('download')
     const s = this.session(session)
     const { handle } = this.activeTab(s)
     signal?.throwIfAborted()
@@ -2340,8 +2641,29 @@ export class ElectronBrowserProvider implements BrowserProvider {
     // Every other carrier drives a real browser over CDP, and cookies are part of CDP —
     // the sidebar goes through the shell's webContents.debugger, an installed Chrome or
     // Edge is the browser itself. So this works everywhere rather than only self-hosted.
+    // Scoped to the page this session is on. The jar itself is SHARED on purpose — every
+    // window and every task drives the same browser, so signing in once works everywhere,
+    // which is the whole point of "use your own browser". What must not be shared is the
+    // HANDING OVER: an unfiltered read puts every domain every task has visited, plus
+    // whatever the human is signed into, in front of one task's caller. Least exposure,
+    // not isolation.
+    //
+    // Two corrections to the previous attempt. It called Storage.getCookies with a `urls`
+    // parameter, but that method takes only browserContextId and ignores everything else, so
+    // the filter did nothing and the whole jar was still exported; `urls` belongs to
+    // Network.getCookies. And it silently fell back to an unfiltered read when the page URL
+    // was unavailable — an error path that asked for MORE than the normal one. Both are
+    // fixed: the method that honours the filter, and a failure that refuses instead of
+    // widening.
+    const cookiesUrl = await this.currentUrl(handle).catch(() => '')
+    if (cookiesUrl === '') {
+      throw new BrowserError(
+        'browser: cannot export cookies without knowing which page this session is on — the URL was unavailable, and reading the whole cookie jar would expose every other session\'s logins',
+        'BROWSER_AUTH_SCOPE_UNKNOWN',
+      )
+    }
     const result = await withTimeout(
-      handle.sendCommand('Storage.getCookies', {}),
+      handle.sendCommand('Network.getCookies', { urls: [cookiesUrl] }),
       timeoutMs,
       undefined,
       `browser: auth export timed out after ${timeoutMs}ms`,
@@ -2353,12 +2675,12 @@ export class ElectronBrowserProvider implements BrowserProvider {
 
   /** Import cookies into the session (restore login state). Self-hosted only. */
   async restoreAuth(session: BrowserSessionId, cookies: readonly ExportedCookie[]): Promise<number> {
-    // The settings panel offers "allow the agent to read cookies / export login state".
-    // Until now nothing read that switch, so turning it off changed nothing at all —
-    // the tool exported every cookie regardless.
-    if (this.settingsSource?.().credentials.allowRead === false) {
-      throw new BrowserError('browser: reading cookies is switched off in settings (Browser → credentials)', 'BROWSER_AUTH_DISABLED')
-    }
+    // Restore WRITES cookies, so it answers to the write switch — not to
+    // `credentials.allowRead`. It used to consult the read switch and report "reading
+    // cookies is switched off", which is both the wrong gate and the wrong sentence: an
+    // operator who allowed reading but wanted logins left alone had no switch at all,
+    // and one who turned reading off lost the restore path for the wrong reason.
+    this.assertActionAllowed('credentialWrite')
     const s = this.session(session)
     const { handle } = this.activeTab(s)
     const timeoutMs = 30_000
@@ -2371,14 +2693,28 @@ export class ElectronBrowserProvider implements BrowserProvider {
     // CDP again, for the same reason as the export: any carrier that drives a real
     // browser can set cookies on it. Storage.setCookies needs the cookie fields spelled
     // the CDP way, including the sameSite spelling and seconds rather than milliseconds.
+    //
+    // toCdpCookie returns undefined for a cookie it cannot place (no usable domain), and
+    // `cookies.map(...)` passed that undefined straight through: the array then held a
+    // JSON `null`, CDP rejected the WHOLE call, and every valid cookie failed with an error
+    // naming none of them. Filter the unusable ones out and say how many went.
+    const mapped = cookies.map(toCdpCookie)
+    const convertible = mapped.filter((cookie): cookie is Record<string, unknown> => cookie !== undefined)
+    const dropped = mapped.length - convertible.length
+    if (dropped > 0) {
+      process.stderr.write(`[dsh-browser] restoreAuth: dropped ${dropped} of ${mapped.length} cookie(s) with no usable domain; the rest were still restored\n`)
+    }
     const result = await withTimeout(
-      handle.sendCommand('Storage.setCookies', { cookies: cookies.map(toCdpCookie) }),
+      handle.sendCommand('Storage.setCookies', { cookies: convertible }),
       timeoutMs,
       undefined,
       `browser: auth restore timed out after ${timeoutMs}ms`,
     )
-    const restored = toExportedCookies(result.cookies).length
-    this.record(s, 'restoreAuth', { count: cookies.length }, true, { result: `${restored} cookies (CDP)` })
+    // Storage.setCookies returns nothing, so the count comes from what was actually
+    // sent. Reading result.cookies here was always undefined, which rendered as
+    // "Restored 0 cookies." while the write had succeeded.
+    const restored = convertible.length
+    this.record(s, 'restoreAuth', { count: cookies.length, dropped }, true, { result: `${restored} cookies (CDP)${dropped > 0 ? `; ${dropped} dropped` : ''}` })
     return restored
   }
 
@@ -2442,6 +2778,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
     // to the region it names, so it has to cover the whole document. The page's own size
     // is read first; when that is unavailable the capture proceeds unscaled rather than
     // failing — an image the caller can shrink itself beats no image at all.
+    let rendered: { width: number; height: number } | undefined
     if (request?.maxWidth !== undefined || request?.maxHeight !== undefined) {
       const metrics = await withTimeout(
         handle.sendCommand('Page.getLayoutMetrics', {}),
@@ -2455,6 +2792,9 @@ export class ElectronBrowserProvider implements BrowserProvider {
         const byWidth = request.maxWidth !== undefined && size.width > 0 ? request.maxWidth / size.width : 1
         const byHeight = request.maxHeight !== undefined && height > 0 ? request.maxHeight / height : 1
         const scale = Math.min(1, byWidth, byHeight)
+        // What the caller will actually receive. Recorded before the branch below, because the
+        // size is worth reporting even when no scaling happened (scale 1).
+        rendered = { width: Math.round(size.width * scale), height: Math.round(height * scale) }
         if (scale < 1) {
           params.clip = { x: 0, y: 0, width: size.width, height, scale }
           // The clip defines the captured area; captureBeyondViewport must not also apply.
@@ -2472,7 +2812,12 @@ export class ElectronBrowserProvider implements BrowserProvider {
     if (typeof data !== 'string') {
       throw new BrowserError('browser: screenshot returned no image data', 'BROWSER_SCREENSHOT_FAILED')
     }
-    return this.saveScreenshot(data, request?.savePath, 'image/png')
+    // The mime must name the format that was ACTUALLY requested (params.format), not PNG
+    // unconditionally: a carrier that sets supportsCdpJpeg asks for `format: 'jpeg'`, so
+    // hardcoding the PNG mime announced a JPEG body as a PNG — the data URL then carried a
+    // mislabelled image, and a caller that decodes by mime wrote the wrong file.
+    const mime = params.format === 'jpeg' ? 'image/jpeg' : 'image/png'
+    return this.saveScreenshot(data, request?.savePath, mime, rendered)
   }
 
   /**
@@ -2482,7 +2827,12 @@ export class ElectronBrowserProvider implements BrowserProvider {
    * file — so a screenshot cannot be used to write to, or silently replace,
    * files anywhere the DSH process happens to have permission (issue #13).
    */
-  private saveScreenshot(base64: string, savePath: string | undefined, mime: string): { dataUrl: string; path?: string } {
+  private saveScreenshot(
+    base64: string,
+    savePath: string | undefined,
+    mime: string,
+    rendered?: { width: number; height: number },
+  ): { dataUrl: string; path?: string; width?: number; height?: number } {
     if (savePath !== undefined) {
       // Admission failures propagate unchanged: they describe the caller's
       // path, not a disk problem.
@@ -2490,13 +2840,13 @@ export class ElectronBrowserProvider implements BrowserProvider {
       try {
         mkdirSync(dirname(target), { recursive: true })
         writeFileSync(target, Buffer.from(base64, 'base64'))
-        return { dataUrl: `data:${mime};base64,${base64}`, path: target }
+        return { dataUrl: `data:${mime};base64,${base64}`, path: target, ...rendered }
       } catch (error) {
         // Report the write problem but keep the capture usable.
         throw new BrowserError(`browser: screenshot save to "${target}" failed: ${String(error)}`, 'BROWSER_SCREENSHOT_SAVE_FAILED', { cause: error })
       }
     }
-    return { dataUrl: `data:${mime};base64,${base64}` }
+    return { dataUrl: `data:${mime};base64,${base64}`, ...rendered }
   }
 
   /** Append one operation to the session's history. */