dsh-builtin-browser 0.1.21 → 0.1.23

package/src/browser-electron/provider.ts

@@ -8,9 +8,9 @@
  */
 
 import { randomUUID } from 'node:crypto'
-import { writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
-import { isAbsolute, join, resolve, sep } from 'node:path'
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path'
 import type {
   BrowserA11yRequest,
   BrowserA11yResult,
@@ -134,6 +134,20 @@ export interface ElectronBrowserViewHost {
    * tell which task's page is currently visible.
    */
   showView?(handle: ElectronViewHandle, label?: string): void
+  /**
+   * Optional: (re)present a view and WAIT until the host confirms it. Chromium
+   * silently drops CDP-synthesized input (`Input.*`) for a view that has no
+   * display surface, which made clicks/typing report success while the page
+   * received nothing (and made the first input after a navigation vanish,
+   * because the replaced renderer has no surface yet). Unlike
+   * {@link showView}, this round-trips an RPC barrier that is ordered AFTER
+   * the show on the same socket, so its reply means the view is on screen.
+   * Rejects when the view cannot be presented; a host without this method is
+   * assumed to present every view (headless/probe hosts).
+   * @param handle - the handle to present.
+   * @param label - human-readable session/task label, as in {@link showView}.
+   */
+  presentView?(handle: ElectronViewHandle, label?: string): Promise<void>
   /**
    * Optional cheap usability probe (no network): whether the host can back
    * views at all right now. The self-hosted host checks for a usable Electron
@@ -193,6 +207,12 @@ export interface ElectronViewHandle {
    * @returns the CDP `result` object.
    */
   sendCommand(method: string, params?: Record<string, unknown>): Promise<Record<string, unknown>>
+  /**
+   * Give the backing view web focus so keyboard input reaches its page.
+   * Optional: an adapter that cannot focus a view omits it, and the provider
+   * then behaves exactly as before.
+   */
+  focus?(): Promise<void>
 }
 
 /** One tab inside a session: its view plus a stable id. */
@@ -240,14 +260,16 @@ export interface CdpNavigateParams {
 }
 
 /**
- * CDP method/params for `Input.dispatchMouseEvent` (a click press+release pair).
+ * CDP method/params for `Input.dispatchMouseEvent`: a pointer move, or one half
+ * of a click's press+release pair. `button`/`clickCount` belong to the press and
+ * release halves; a move carries only the position.
  */
 export interface CdpMouseParams {
-  readonly type: 'mousePressed' | 'mouseReleased'
+  readonly type: 'mouseMoved' | 'mousePressed' | 'mouseReleased'
   readonly x: number
   readonly y: number
-  readonly button: 'left'
-  readonly clickCount: number
+  readonly button?: 'left'
+  readonly clickCount?: number
 }
 
 /** CDP method/params for `Input.insertText`. */
@@ -303,6 +325,31 @@ const KEY_SPECS: Readonly<Record<string, { readonly key: string; readonly code:
 /** Supported key names, exported for the tool's enum and error messages. */
 export const BROWSER_KEY_NAMES: readonly string[] = Object.keys(KEY_SPECS)
 
+/**
+ * Localized names a system Downloads folder may carry, in probe order: the
+ * English default first, then the Chinese spellings — a zh-CN desktop calls
+ * the folder `下载`, a zh-TW one `下載`, and neither is `Downloads`.
+ */
+const DOWNLOAD_DIR_NAMES: readonly string[] = ['Downloads', '下载', '下載']
+
+/**
+ * Resolve the default download directory when the config names none: an
+ * existing `XDG_DOWNLOAD_DIR` wins (the freedesktop standard, which is what a
+ * localized Linux desktop writes), then the first localized `Downloads` folder
+ * that exists under the home directory, and finally the English name — created
+ * on first use — when none exists yet.
+ * @returns the absolute default download directory.
+ */
+function defaultDownloadDir(): string {
+  const xdg = process.env.XDG_DOWNLOAD_DIR
+  if (typeof xdg === 'string' && xdg !== '' && existsSync(xdg)) return xdg
+  for (const name of DOWNLOAD_DIR_NAMES) {
+    const candidate = join(homedir(), name)
+    if (existsSync(candidate)) return candidate
+  }
+  return join(homedir(), DOWNLOAD_DIR_NAMES[0] ?? 'Downloads')
+}
+
 /**
  * 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
@@ -326,9 +373,12 @@ export class ElectronBrowserProvider implements BrowserProvider {
     this.httpOnly = config.httpOnly ?? true
     this.snapshotMaxElements = config.snapshotMaxElements ?? 60
     this.contentMaxChars = config.contentMaxChars ?? 100_000
-    // Confine downloads to a dedicated directory by default: the OS Downloads
-    // folder is the human-visible, browser-natural place for downloaded files.
-    this.downloadDir = config.downloadDir ?? join(homedir(), 'Downloads')
+    // 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
+    // sandbox does not have to arbitrate. The localized name is probed so a
+    // Chinese desktop (`~/下载`) works without configuring `downloadDir`.
+    this.downloadDir = config.downloadDir ?? defaultDownloadDir()
     // Route toolbar (host UI) actions into the session model: the human and
     // the agent then always drive the same tabs, history, and navigation.
     this.host.onUserAction?.(action => { void this.handleUserAction(action) })
@@ -433,10 +483,15 @@ export class ElectronBrowserProvider implements BrowserProvider {
    */
   private locateTab(session: BrowserSessionId, tabId: string): { s: Session; index: number } {
     const s = this.session(session)
-    const own = s.tabs.findIndex(tab => tab.id === tabId)
+    // Accept the bare uuid as well as the "tab:<uuid>" form the tools print:
+    // ids are globally unique, so requiring the printed prefix only produced a
+    // misleading "is not open in this session" error that listed the very tab
+    // the caller had just named.
+    const wanted = stripTabPrefix(tabId)
+    const own = s.tabs.findIndex(tab => stripTabPrefix(tab.id) === wanted)
     if (own >= 0) return { s, index: own }
     for (const other of this.sessions.values()) {
-      const index = other.tabs.findIndex(tab => tab.id === tabId)
+      const index = other.tabs.findIndex(tab => stripTabPrefix(tab.id) === wanted)
       if (index >= 0) return { s: other, index }
     }
     const ownIds = s.tabs.map(t => t.id).join(', ') || '(none)'
@@ -479,6 +534,8 @@ export class ElectronBrowserProvider implements BrowserProvider {
       // evaluate paths so a wedged navigation surfaces as an error instead of
       // blocking the tool call forever.
       const timeoutMs = 30_000
+      // Document identity of the page we are leaving (see settleDocument).
+      const before = await this.documentStamp(handle)
       const result = await withTimeout(
         handle.sendCommand(CDP_PAGE_NAVIGATE, { url } satisfies CdpNavigateParams),
         timeoutMs,
@@ -494,7 +551,11 @@ export class ElectronBrowserProvider implements BrowserProvider {
       if (typeof errorText === 'string' && errorText !== '') {
         throw new BrowserError(`browser: navigation to "${url}" failed: ${errorText}`, 'BROWSER_NAVIGATION_FAILED')
       }
+      // Record as soon as the navigation has committed: history bookkeeping must
+      // not wait on the best-effort settle below (which only delays what the
+      // NEXT observation sees, not whether this action happened).
       this.record(s, 'navigate', { url }, true)
+      await this.settleDocument(handle, before, signal)
       this.showActive(s)
     } catch (error) {
       if (!(error instanceof BrowserError && (error as { code?: string }).code === 'BROWSER_NAVIGATION_BLOCKED')) {
@@ -504,6 +565,133 @@ export class ElectronBrowserProvider implements BrowserProvider {
     }
   }
 
+  /**
+   * A per-document stamp: `performance.timeOrigin` is unique per document load,
+   * so it tells a same-URL reload and an A→B→A redirect apart from the document
+   * that was current before the navigation. Empty string when unreadable.
+   */
+  private async documentStamp(handle: ElectronViewHandle): Promise<string> {
+    const probe = await this.documentProbe(handle)
+    return probe?.stamp ?? ''
+  }
+
+  /**
+   * One cheap in-page reading of the document's identity and parse state.
+   *
+   * Returns null when the page did NOT answer (mid-commit, execution context
+   * destroyed) — the caller keeps waiting. A page that answered with an
+   * unexpected shape (an override or a non-conforming host; the production
+   * expression always yields a string) is reported as `unknown` rather than as
+   * "no answer": blocking the navigation for the whole budget on a page that
+   * demonstrably responded has no upside.
+   */
+  private async documentProbe(handle: ElectronViewHandle): Promise<{ stamp: string; readyState: string } | null> {
+    try {
+      const result = await withTimeout(
+        handleSendEvaluate(handle, 'String(performance.timeOrigin) + "|" + document.readyState'),
+        3_000,
+        undefined,
+        'browser: document probe timed out',
+      )
+      if (!result.ok) return null
+      if (typeof result.value !== 'string') return { stamp: '', readyState: 'unknown' }
+      const [stamp = '', readyState = ''] = result.value.split('|')
+      return { stamp, readyState }
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * Page.navigate resolves at navigation COMMIT, not at load: the new document
+   * is already current (so location.href and document.title are the new page's)
+   * while its DOM is still being parsed. browser_open snapshots immediately
+   * after navigating, which is why it could report the right title with zero
+   * interactive elements — and why a separate browser_snapshot right after
+   * always found them.
+   *
+   * Wait — bounded, best-effort — for the new document to settle: readyState
+   * must reach interactive/complete AND the document identity must have
+   * changed. A page that never settles must not fail a navigation that already
+   * succeeded, so a timeout here is swallowed.
+   */
+  private async settleDocument(handle: ElectronViewHandle, before: string, signal?: AbortSignal): Promise<void> {
+    const started = Date.now()
+    const deadline = started + SETTLE_TIMEOUT_MS
+    for (;;) {
+      if (signal?.aborted === true) return
+      // A probe failure is expected while the navigation commits (the context is
+      // being destroyed) — keep polling rather than giving up.
+      const probe = await this.documentProbe(handle)
+      if (probe !== null) {
+        const settled = probe.readyState === 'interactive'
+          || probe.readyState === 'complete'
+          || probe.readyState === 'unknown'
+        const isNewDocument = before === '' || probe.stamp === '' || probe.stamp !== before
+        // The common case: the new document exists and is parsed — return now.
+        if (settled && isNewDocument) return
+        // Same document (hash navigation, cancelled/aborted load): there is no
+        // parse to wait for, so do not burn the budget. Outlast the brief
+        // window in which the OUTGOING document may still answer instead.
+        if (settled && Date.now() - started >= SETTLE_GRACE_MS) return
+      }
+      if (Date.now() >= deadline) return
+      await delay(SETTLE_POLL_MS, signal)
+    }
+  }
+
+  /**
+   * Make sure the active tab's view can actually receive synthesized input.
+   * 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.
+   */
+  private async present(s: Session, signal?: AbortSignal): Promise<void> {
+    const { handle } = this.activeTab(s)
+    const present = this.host.presentView?.bind(this.host)
+    if (present === undefined) {
+      this.showActive(s)
+      return
+    }
+    signal?.throwIfAborted()
+    const timeoutMs = 10_000
+    try {
+      await withTimeout(
+        present(handle, s.label),
+        timeoutMs,
+        signal,
+        `browser: presenting the page view timed out after ${timeoutMs}ms`,
+      )
+      this.showActive(s)
+    } 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 },
+      )
+    }
+  }
+
+  /**
+   * Give the view web focus before synthesizing keyboard input.
+   *
+   * A renderer only delivers key events to the view that holds web focus. A
+   * view that was created but never clicked holds none — and `Input` events
+   * injected over CDP do not grant it — so the FIRST `browser_key` of a fresh
+   * session vanished inside the renderer while the command still answered
+   * success. Hosts that cannot focus a view (a test double, a different shell
+   * adapter) simply have no `focus`, and nothing changes for them.
+   */
+  private async focusView(handle: ElectronViewHandle): Promise<void> {
+    if (handle.focus === undefined) return
+    try {
+      await handle.focus()
+    } catch {
+      // Best-effort: a view that refuses focus must not fail the caller's key
+      // press; the dispatch below reports a real channel failure itself.
+    }
+  }
+
   /** Execute JS in the active tab's page context. */
   async execute(session: BrowserSessionId, request: BrowserExecuteRequest, signal?: AbortSignal): Promise<BrowserExecuteResult> {
     const s = this.session(session)
@@ -1033,23 +1221,54 @@ export class ElectronBrowserProvider implements BrowserProvider {
       x = request.x
       y = request.y
     }
-    const press = (type: 'mousePressed' | 'mouseReleased'): Promise<Record<string, unknown>> =>
-      handle.sendCommand('Input.dispatchMouseEvent', { type, x, y, button: 'left', clickCount: 1 } satisfies CdpMouseParams)
+    // 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)
     const timeoutMs = 30_000
+    const send = (params: Record<string, unknown>, label: string): Promise<unknown> =>
+      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*
+    // hover target rather than hit-testing the coordinates, and a real pointer
+    // click is always preceded by movement. A view that has never received a
+    // mouse event has no hover target yet, so the press of the FIRST click on a
+    // fresh tab went nowhere while CDP still answered success; the second click
+    // landed because the first had quietly established the target. Move the
+    // pointer first so a click is self-contained.
+    try {
+      await send({ type: 'mouseMoved', x, y } satisfies CdpMouseParams, 'move')
+    } catch (error) {
+      throw new BrowserError(`browser: click failed: ${String(error)}`, 'BROWSER_CLICK_FAILED', { cause: error })
+    }
+    const release = (): void => {
+      void handle
+        .sendCommand('Input.dispatchMouseEvent', {
+          type: 'mouseReleased',
+          x,
+          y,
+          button: 'left',
+          clickCount: 1,
+        } satisfies CdpMouseParams)
+        .catch(() => {})
+    }
     try {
-      await withTimeout(press('mousePressed'), timeoutMs, signal, `browser: click press timed out after ${timeoutMs}ms`)
+      await send({ type: 'mousePressed', x, y, button: 'left', clickCount: 1 }, 'press')
     } catch (error) {
       // The press may still land late; release best-effort so the button is
       // never left in a stuck pressed state.
-      void press('mouseReleased').catch(() => {})
+      release()
       throw new BrowserError(`browser: click failed: ${String(error)}`, 'BROWSER_CLICK_FAILED', { cause: error })
     }
     try {
-      await withTimeout(press('mouseReleased'), timeoutMs, signal, `browser: click release timed out after ${timeoutMs}ms`)
+      await send({ type: 'mouseReleased', x, y, button: 'left', clickCount: 1 }, 'release')
     } catch (error) {
       // The press already landed; retry the release so the button is not
       // left pressed before surfacing the failure.
-      void press('mouseReleased').catch(() => {})
+      release()
       throw new BrowserError(`browser: click failed: ${String(error)}`, 'BROWSER_CLICK_FAILED', { cause: error })
     }
     this.record(s, 'click', 'target' in request ? { target: request.target } : { x, y }, true)
@@ -1078,6 +1297,9 @@ 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)
     try {
       await withTimeout(
         handle.sendCommand('Input.insertText', { text } satisfies CdpInsertTextParams),
@@ -1149,6 +1371,9 @@ export class ElectronBrowserProvider implements BrowserProvider {
     }
     const entry = entries[target]
     if (entry?.id === undefined) throw new BrowserError('browser: history entry missing id', 'BROWSER_HISTORY_INVALID')
+    // A history step is a navigation too: the classic A→B→A redirect would
+    // otherwise read the outgoing document's identity (see settleDocument).
+    const before = await this.documentStamp(handle)
     await withTimeout(
       handle.sendCommand('Page.navigateToHistoryEntry', { entryId: entry.id }),
       timeoutMs,
@@ -1157,6 +1382,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
       () => { void handle.sendCommand('Page.stopLoading').catch(() => {}) },
     )
     this.record(s, direction === -1 ? 'back' : 'forward', {}, true)
+    await this.settleDocument(handle, before, signal)
     this.showActive(s)
   }
 
@@ -1176,6 +1402,9 @@ export class ElectronBrowserProvider implements BrowserProvider {
     const { handle } = this.activeTab(s)
     signal?.throwIfAborted()
     const timeoutMs = 30_000
+    // Same-URL reload: only the per-load document identity can tell the new
+    // document from the old one, so capture it before reloading.
+    const before = await this.documentStamp(handle)
     await withTimeout(
       handle.sendCommand('Page.reload', { ignoreCache: false }),
       timeoutMs,
@@ -1185,6 +1414,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
       () => { void handle.sendCommand('Page.stopLoading').catch(() => {}) },
     )
     this.record(s, 'reload', {}, true)
+    await this.settleDocument(handle, before, signal)
     this.showActive(s)
   }
 
@@ -1199,6 +1429,9 @@ 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)
+    await this.focusView(handle)
     const release = (): Promise<Record<string, unknown>> =>
       handle.sendCommand('Input.dispatchKeyEvent', { type: 'keyUp', ...params })
     try {
@@ -1376,10 +1609,16 @@ export class ElectronBrowserProvider implements BrowserProvider {
    * (polling until it appears or the budget runs out) and then runs `body`
    * with `el` in scope. Shared by the target-based tools: click/type (②),
    * setValue/check/select/clear/getValue (③), and the scrape item wait.
+   * A selector that fails to PARSE is reported immediately instead of being
+   * polled until the budget expires — see the comment in `match`.
    */
   private buildTargetScript(spec: BrowserElementTarget, timeoutMs: number, body: string): string {
+    // `by` defaults to css in-page; report the strategy that WAS used, or a
+    // miss says only `{"value":"Learn more"}` and the caller cannot tell that a
+    // plain label was queried as a CSS selector.
+    const resolvedSpec = { ...spec, by: spec.by ?? 'css' }
     return `(async () => {
-      const spec = ${JSON.stringify(spec)}
+      const spec = ${JSON.stringify(resolvedSpec)}
       const timeoutMs = ${String(timeoutMs)}
       const sleep = ms => new Promise(r => setTimeout(r, ms))
       const isVisible = el => el instanceof HTMLElement && (el.offsetWidth > 0 || el.offsetHeight > 0 || el.getClientRects().length > 0)
@@ -1391,7 +1630,13 @@ export class ElectronBrowserProvider implements BrowserProvider {
         const index = typeof spec.index === 'number' ? spec.index : 0
         let els = []
         if (by === 'css') {
-          try { els = Array.from(document.querySelectorAll(value)) } catch { return null }
+          // 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)) }
+          catch (error) { throw new Error('invalid CSS selector ' + JSON.stringify(value) + ' (' + String((error && error.message) || error) + ')') }
         } else if (by === 'xpath') {
           try {
             const snap = document.evaluate(value, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null)
@@ -1399,7 +1644,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
               const n = snap.snapshotItem(i)
               if (n instanceof Element) els.push(n)
             }
-          } catch { return null }
+          } catch (error) { throw new Error('invalid XPath ' + JSON.stringify(value) + ' (' + String((error && error.message) || error) + ')') }
         } else {
           const all = Array.from(document.querySelectorAll('body *'))
           const exact = all.filter(el => isVisible(el) && ownText(el) === value)
@@ -1413,9 +1658,10 @@ export class ElectronBrowserProvider implements BrowserProvider {
       const deadline = Date.now() + timeoutMs
       let el = null
       for (;;) {
-        el = match()
+        // Only a parse error escapes the poll: see the comment in match() above.
+        try { el = match() } catch (error) { return { ok: false, error: String((error && error.message) || error) } }
         if (el !== null) break
-        if (Date.now() >= deadline) return { ok: false, error: 'element not found: ' + JSON.stringify(spec) }
+        if (Date.now() >= deadline) return { ok: false, error: 'element not found: ' + JSON.stringify(spec) + ' (looked for ' + timeoutMs + 'ms)' }
         await sleep(100)
       }
       ${body}
@@ -1435,9 +1681,14 @@ export class ElectronBrowserProvider implements BrowserProvider {
     errorCode: string,
     errorLabel: string,
   ): Promise<Record<string, unknown>> {
+    // The script polls for its whole `timeoutMs` and only then answers, so an
+    // outer budget of the same size fires at the same instant and wins: the
+    // caller saw `click timed out after 10000ms` while the page had already
+    // decided WHY (selector not found / malformed). Give the answer a chance to
+    // get back before the generic timeout replaces it.
     const result = await withTimeout(
       handleSendEvaluate(tab.handle, script),
-      timeoutMs,
+      timeoutMs + TARGET_SCRIPT_GRACE_MS,
       signal,
       `${errorLabel} timed out after ${timeoutMs}ms`,
       () => terminatePage(tab.handle),
@@ -1637,7 +1888,9 @@ export class ElectronBrowserProvider implements BrowserProvider {
       const deadline = Date.now() + timeoutMs
       let items = []
       for (;;) {
-        try { items = Array.from(document.querySelectorAll(itemSel)) } catch (e) { return { ok: false, error: String(e) } }
+        // Immediate, like match() above: an unparseable selector can never match.
+        try { items = Array.from(document.querySelectorAll(itemSel)) }
+        catch (error) { return { ok: false, error: 'invalid CSS selector ' + JSON.stringify(itemSel) + ' (' + String((error && error.message) || error) + ')' } }
         if (items.length > 0) break
         if (Date.now() >= deadline) return { ok: false, error: 'no elements matched: ' + itemSel }
         await sleep(100)
@@ -1677,13 +1930,54 @@ export class ElectronBrowserProvider implements BrowserProvider {
   }
 
   /**
-   * Download a URL to a local file, keeping the session's cookies/login.
-   * Requires the self-hosted host (which implements view-level download); the
-   * desktop shell's embedded views delegate downloads to the real browser UI.
-   * Admission: only HTTP(S) targets (the in-page fetch cannot meaningfully
-   * fetch anything else), and the save path must be absolute — confined to
-   * `downloadDir` when one is configured, so a prompt-injected agent cannot
-   * write arbitrary machine paths.
+   * 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
+   * must be absolute, must resolve inside `downloadDir`, and must not already
+   * exist. Without it a prompt-injected agent could write — or silently
+   * replace — any file the DSH process can reach, which also escapes the file
+   * sandbox every other tool in the set runs under.
+   * @param savePath - the caller's target path.
+   * @param kind - the operation, used in the error code and message.
+   * @returns the resolved absolute target path.
+   * @throws BrowserError when the path is relative, outside the directory, or occupied.
+   */
+  private admitSavePath(savePath: string, kind: 'download' | 'screenshot'): string {
+    const code = kind === 'download' ? 'BROWSER_DOWNLOAD_BLOCKED' : 'BROWSER_SCREENSHOT_BLOCKED'
+    if (!isAbsolute(savePath)) {
+      throw new BrowserError(`browser: ${kind} savePath must be an absolute path`, code)
+    }
+    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())) {
+        throw new BrowserError(`browser: ${kind} savePath must be inside downloadDir "${dir}"`, 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)) {
+      throw new BrowserError(`browser: refusing to overwrite existing file "${file}" — use another name`, code)
+    }
+    return file
+  }
+
+  /**
+   * Download an HTTP(S) URL with the session's cookies to a local file.
+   * Admission is the shared {@link admitSavePath} gate; only the self-hosted
+   * host implements it (the desktop shell's embedded views delegate downloads
+   * to the real browser UI). Both admitted paths and screenshots are confined
+   * to `downloadDir`, so a prompt-injected agent cannot write arbitrary
+   * machine paths.
+   * @param session - the session whose cookies are used.
+   * @param request - the URL plus the absolute target path.
+   * @param signal - optional cancellation.
+   * @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 }> {
     const s = this.session(session)
@@ -1701,23 +1995,9 @@ export class ElectronBrowserProvider implements BrowserProvider {
     if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
       throw new BrowserError(`browser: refusing download of non-HTTP(S) URL "${request.url}"`, 'BROWSER_DOWNLOAD_BLOCKED')
     }
-    // savePath admission: must be absolute; when downloadDir is configured it
-    // must resolve inside it (no ..-escape).
-    if (!isAbsolute(request.savePath)) {
-      throw new BrowserError('browser: download savePath must be an absolute path', 'BROWSER_DOWNLOAD_BLOCKED')
-    }
-    if (this.downloadDir !== undefined) {
-      const dir = resolve(this.downloadDir)
-      const file = resolve(request.savePath)
-      // 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())) {
-        throw new BrowserError(`browser: download savePath must be inside downloadDir "${dir}"`, 'BROWSER_DOWNLOAD_BLOCKED')
-      }
-    }
+    // savePath admission: the shared gate — absolute, inside `downloadDir`,
+    // and never an existing file. Screenshots use the very same one.
+    const savePath = this.admitSavePath(request.savePath, 'download')
     const downloadable = handle as { download?(url: string, savePath: string): Promise<void> }
     if (typeof downloadable.download !== 'function') {
       throw new BrowserError('browser: download is only available on the self-hosted browser', 'BROWSER_DOWNLOAD_UNSUPPORTED')
@@ -1730,13 +2010,13 @@ export class ElectronBrowserProvider implements BrowserProvider {
     // reply is harmlessly consumed by the RPC layer.
     const timeoutMs = 60_000
     await withTimeout(
-      downloadable.download(request.url, request.savePath),
+      downloadable.download(request.url, savePath),
       timeoutMs,
       signal,
       `browser: download timed out after ${timeoutMs}ms`,
     )
-    this.record(s, 'download', { url: request.url, savePath: request.savePath }, true, { result: request.savePath })
-    return { path: request.savePath }
+    this.record(s, 'download', { url: request.url, savePath }, true, { result: savePath })
+    return { path: savePath }
   }
 
   /**
@@ -1829,15 +2109,25 @@ export class ElectronBrowserProvider implements BrowserProvider {
     return this.saveScreenshot(data, request?.savePath, 'image/png')
   }
 
-  /** Build the data URL and optionally write the image to disk. */
+  /**
+   * Build the data URL and optionally write the image to disk. The caller's
+   * path goes through the SAME {@link admitSavePath} gate as a download — it
+   * must be absolute, resolve inside `downloadDir`, and not be an existing
+   * 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 } {
     if (savePath !== undefined) {
+      // Admission failures propagate unchanged: they describe the caller's
+      // path, not a disk problem.
+      const target = this.admitSavePath(savePath, 'screenshot')
       try {
-        writeFileSync(savePath, Buffer.from(base64, 'base64'))
-        return { dataUrl: `data:${mime};base64,${base64}`, path: savePath }
+        mkdirSync(dirname(target), { recursive: true })
+        writeFileSync(target, Buffer.from(base64, 'base64'))
+        return { dataUrl: `data:${mime};base64,${base64}`, path: target }
       } catch (error) {
         // Report the write problem but keep the capture usable.
-        throw new BrowserError(`browser: screenshot save to "${savePath}" failed: ${String(error)}`, 'BROWSER_SCREENSHOT_SAVE_FAILED', { cause: error })
+        throw new BrowserError(`browser: screenshot save to "${target}" failed: ${String(error)}`, 'BROWSER_SCREENSHOT_SAVE_FAILED', { cause: error })
       }
     }
     return { dataUrl: `data:${mime};base64,${base64}` }
@@ -2066,6 +2356,46 @@ export class ElectronBrowserProvider implements BrowserProvider {
   }
 }
 
+/**
+ * Hard cap on waiting for a navigation's new document to be parsed. Bounded and
+ * best-effort: a page that never settles must not fail the navigation.
+ */
+const SETTLE_TIMEOUT_MS = 5_000
+
+/**
+ * When the document already looks settled but its identity has NOT changed
+ * (same-document navigation, or the outgoing document still answering), wait
+ * only this long before returning — there is no parse in flight to wait for.
+ */
+const SETTLE_GRACE_MS = 150
+
+/** Poll interval for the document-settle loop. */
+const SETTLE_POLL_MS = 25
+
+/**
+ * Extra time the transport gets over an in-page locate script's own budget: the
+ * script polls for `timeoutMs` and answers only afterwards, so the outer wait
+ * must outlast it or its generic timeout hides the in-page reason.
+ */
+const TARGET_SCRIPT_GRACE_MS = 2_000
+
+/** `tab:<uuid>` ↔ `<uuid>`: ids accept either form (see locateTab). */
+function stripTabPrefix(id: string): string {
+  return id.startsWith('tab:') ? id.slice(4) : id
+}
+
+/** Abortable sleep used by the settle loop. */
+function delay(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve) => {
+    const timer = setTimeout(() => {
+      if (signal !== undefined) signal.removeEventListener('abort', onAbort)
+      resolve()
+    }, ms)
+    const onAbort = (): void => { clearTimeout(timer); resolve() }
+    if (signal !== undefined) signal.addEventListener('abort', onAbort, { once: true })
+  })
+}
+
 /**
  * Bound a promise so a wedged CDP call surfaces as an error instead of
  * hanging the tool call forever. The caller's signal, when provided, wins