dsh-builtin-browser 0.4.1 → 0.4.5

package/lib/browser-electron/provider.js

@@ -7,7 +7,7 @@
  * @module dsh-browser/browser-electron
  */
 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 } from './history-store.js';
@@ -225,6 +225,58 @@ function defaultDownloadDir() {
     }
     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) {
+    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) {
+    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
@@ -251,7 +303,7 @@ export class ElectronBrowserProvider {
         this.host = host;
         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
@@ -291,7 +343,10 @@ export class ElectronBrowserProvider {
      * in the window title so a human can tell which task's page is visible.
      */
     open(label) {
-        const handle = this.host.createView();
+        // The label is the calling DSH task, and it is handed to the view as its owner: a host shared
+        // by several conversations (the desktop's) keeps one conversation's page out of another's on
+        // the strength of it, so it is not decoration.
+        const handle = this.host.createView(label);
         const id = `browser:${randomUUID()}`;
         // Group the session's views under its own window (one window per
         // session), carrying the label for the window title. Hosts without
@@ -536,13 +591,16 @@ export class ElectronBrowserProvider {
      * 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.
      */
     async present(s, signal) {
         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;
@@ -553,6 +611,42 @@ export class ElectronBrowserProvider {
         catch (error) {
             throw new BrowserError(`browser: the page view is not presented, so synthesized input would be silently dropped (${String(error)})`, 'BROWSER_VIEW_NOT_PRESENTED', { 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.
+     */
+    assertSameView(session, locateHandle, liveHandle) {
+        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');
     }
     /**
      * Give the view web focus before synthesizing keyboard input.
@@ -581,6 +675,7 @@ export class ElectronBrowserProvider {
     }
     /** Execute JS in the active tab's page context. */
     async execute(session, request, signal) {
+        this.assertActionAllowed('execute');
         const s = this.session(session);
         const { handle } = this.activeTab(s);
         signal?.throwIfAborted();
@@ -804,7 +899,9 @@ export class ElectronBrowserProvider {
         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)}
@@ -946,6 +1043,11 @@ export class ElectronBrowserProvider {
             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),
@@ -981,9 +1083,18 @@ export class ElectronBrowserProvider {
     async content(session, request, signal) {
         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' }
@@ -1027,7 +1138,12 @@ export class ElectronBrowserProvider {
         }
       }
       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 = []
@@ -1073,7 +1189,9 @@ export class ElectronBrowserProvider {
      */
     async click(session, request, signal) {
         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;
@@ -1105,8 +1223,14 @@ export class ElectronBrowserProvider {
             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, label) => withTimeout(handle.sendCommand('Input.dispatchMouseEvent', params), timeoutMs, signal, `browser: click ${label} timed out after ${timeoutMs}ms`);
         // Chromium routes a synthesized `mousePressed` to the widget's *current*
@@ -1128,6 +1252,10 @@ export class ElectronBrowserProvider {
         // 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 = () => {
+            // 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',
@@ -1164,7 +1292,10 @@ export class ElectronBrowserProvider {
      */
     async type(session, request, signal) {
         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) {
@@ -1182,8 +1313,14 @@ export class ElectronBrowserProvider {
         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 }), timeoutMs, signal, `browser: type timed out after ${timeoutMs}ms`);
         }
@@ -1278,7 +1415,6 @@ export class ElectronBrowserProvider {
     /** Press one named key (Enter/Tab/arrows/…) via CDP key events. */
     async key(session, request, signal) {
         const s = this.session(session);
-        const { handle } = this.activeTab(s);
         signal?.throwIfAborted();
         const spec = KEY_SPECS[request.key];
         if (spec === undefined) {
@@ -1286,8 +1422,13 @@ export class ElectronBrowserProvider {
         }
         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 = () => handle.sendCommand('Input.dispatchKeyEvent', { type: 'keyUp', ...params });
         try {
@@ -1325,7 +1466,13 @@ export class ElectronBrowserProvider {
             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;
@@ -1358,10 +1505,34 @@ export class ElectronBrowserProvider {
         }
         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
       }
@@ -1379,7 +1550,9 @@ export class ElectronBrowserProvider {
         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
@@ -1387,6 +1560,12 @@ export class ElectronBrowserProvider {
             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)
@@ -1501,33 +1680,78 @@ export class ElectronBrowserProvider {
       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
@@ -1803,6 +2027,35 @@ export class ElectronBrowserProvider {
         this.record(s, 'scrape', { item: request.item, fields: request.fields.map(f => f.name) }, true, { result: `${items.length} items` });
         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.
+     */
+    assertActionAllowed(action) {
+        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
@@ -1823,19 +2076,56 @@ export class ElectronBrowserProvider {
         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) => value.toLowerCase() : (value) => 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;
+            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;
@@ -1853,6 +2143,9 @@ export class ElectronBrowserProvider {
      * @returns the path the file was written to.
      */
     async download(session, request, signal) {
+        // 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();
@@ -1912,19 +2205,37 @@ export class ElectronBrowserProvider {
         // 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.
-        const result = await withTimeout(handle.sendCommand('Storage.getCookies', {}), timeoutMs, undefined, `browser: auth export timed out after ${timeoutMs}ms`);
+        // 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('Network.getCookies', { urls: [cookiesUrl] }), timeoutMs, undefined, `browser: auth export timed out after ${timeoutMs}ms`);
         const cookies = toExportedCookies(result.cookies);
         this.record(s, 'flushAuth', {}, true, { result: `${cookies.length} cookies (CDP)` });
         return cookies;
     }
     /** Import cookies into the session (restore login state). Self-hosted only. */
     async restoreAuth(session, cookies) {
-        // 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;
@@ -1937,9 +2248,23 @@ export class ElectronBrowserProvider {
         // 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.
-        const result = await withTimeout(handle.sendCommand('Storage.setCookies', { cookies: cookies.map(toCdpCookie) }), 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)` });
+        //
+        // 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 !== 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: convertible }), timeoutMs, undefined, `browser: auth restore timed out after ${timeoutMs}ms`);
+        // 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;
     }
     /** Capture the current page, optionally full-page, PNG or JPEG, scalable. */
@@ -1967,7 +2292,13 @@ export class ElectronBrowserProvider {
             if (shot.base64 === '') {
                 throw new BrowserError('browser: capture returned an empty image (view not painted); retry shortly', 'BROWSER_SCREENSHOT_FAILED');
             }
-            return this.saveScreenshot(shot.base64, request?.savePath, shot.mime ?? 'image/png');
+            return this.saveScreenshot(shot.base64, request?.savePath, shot.mime ?? 'image/png', 
+            // The child measured these after applying any downscale, and they describe the image
+            // the caller receives. Without them this path — the default self-hosted one — could
+            // never answer the width/height its own tool schema declares.
+            shot.width !== undefined && shot.height !== undefined
+                ? { width: shot.width, height: shot.height }
+                : undefined);
         }
         // Fallback: a handle without a native capture() (the sidebar, or an installed Chrome
         // or Edge) uses CDP; full-page needs `captureBeyondViewport`, which capturePage lacks.
@@ -1994,6 +2325,7 @@ export class ElectronBrowserProvider {
         // 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;
         if (request?.maxWidth !== undefined || request?.maxHeight !== undefined) {
             const metrics = await withTimeout(handle.sendCommand('Page.getLayoutMetrics', {}), timeoutMs, signal, `browser: screenshot timed out after ${timeoutMs}ms`);
             const size = layoutSize(metrics);
@@ -2002,6 +2334,9 @@ export class ElectronBrowserProvider {
                 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.
@@ -2014,7 +2349,12 @@ export class ElectronBrowserProvider {
         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);
     }
     /**
      * Build the data URL and optionally write the image to disk. The caller's
@@ -2023,7 +2363,7 @@ export class ElectronBrowserProvider {
      * file — so a screenshot cannot be used to write to, or silently replace,
      * files anywhere the DSH process happens to have permission (issue #13).
      */
-    saveScreenshot(base64, savePath, mime) {
+    saveScreenshot(base64, savePath, mime, rendered) {
         if (savePath !== undefined) {
             // Admission failures propagate unchanged: they describe the caller's
             // path, not a disk problem.
@@ -2031,14 +2371,14 @@ export class ElectronBrowserProvider {
             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. */
     record(s, action, params, ok, detail) {
@@ -2072,9 +2412,15 @@ export class ElectronBrowserProvider {
         if (store === undefined)
             return;
         // The settings panel can switch recording off at runtime; the static config
-        // only supplies the startup default.
-        if (this.settingsSource !== undefined && !this.settingsSource().history.enabled)
-            return;
+        // only supplies the startup default. The RETENTION limits are read here too: they were
+        // parsed and stored but never handed to the store, so editing maxEntries or maxAgeDays in
+        // the file changed nothing — the switch worked and the numbers beside it did not.
+        if (this.settingsSource !== undefined) {
+            const live = this.settingsSource().history;
+            if (!live.enabled)
+                return;
+            store.updateLimits({ maxEntries: live.maxEntries, maxAgeDays: live.maxAgeDays });
+        }
         void handleSendEvaluate(handle, 'location.href + "\\u0000" + (document.title || "")')
             .then(result => {
             if (!result.ok || typeof result.value !== 'string')
@@ -2206,7 +2552,9 @@ export class ElectronBrowserProvider {
             // the views above; the desktop's sidebar does not, so it is asked explicitly
             // — and its cookies plus the browsing history outlive the page either way.
             if (this.settingsSource !== undefined && this.settingsSource().ui.closeWithSession) {
-                void this.host.releasePage?.().catch(() => undefined);
+                // Named, because one host serves every conversation: an unnamed release would end the
+                // pages of conversations that are still running.
+                void this.host.releasePage?.(existing.label).catch(() => undefined);
             }
         }
         return Promise.resolve();
@@ -2228,7 +2576,7 @@ export class ElectronBrowserProvider {
     }
     /** Append a fresh tab and make it active. */
     newTab(s) {
-        const handle = this.host.createView();
+        const handle = this.host.createView(s.label);
         // Same window as the session's other tabs.
         this.host.groupView?.(handle, s.id, s.label);
         s.tabs.push({ id: `tab:${randomUUID()}`, handle });
@@ -2333,11 +2681,10 @@ export class ElectronBrowserProvider {
         const message = `action ${action.type} failed: ${String(error)}`;
         let reported = false;
         try {
-            const host = this.host;
-            const notify = host.notifyUserActionError;
-            if (typeof notify === 'function') {
-                // Called on its owner: an unbound call here kills the host process.
-                notify.call(host, action.windowId, message);
+            const notify = this.host.notifyUserActionError?.bind(this.host);
+            if (notify !== undefined) {
+                // Bound at the call: an unbound call here kills the host process (issue #16).
+                notify(action.windowId, message);
                 reported = true;
             }
         }