dsh-builtin-browser 0.2.0 → 0.3.1

package/src/browser-electron/system-browser.ts

@@ -0,0 +1,371 @@
+/**
+ * Drive the browser the user already has (Chrome / Edge / any Chromium) instead of
+ * the Electron we ship — the same approach Codex Browser Use takes.
+ *
+ * WHY
+ * The bundled Electron is a private copy with its own profile, so it can never see
+ * the logins the user already has in Chrome, and on a managed machine the user may
+ * simply prefer their own browser. Launching their browser with a *separate*
+ * `--user-data-dir` gives us a real Chromium we can drive over CDP without touching
+ * their everyday profile, bookmarks or windows: nothing of theirs is opened, locked
+ * or modified, and closing us never closes them.
+ *
+ * HOW
+ * Chromium exposes CDP on `--remote-debugging-port=0`, and writes the port it chose
+ * into `<profile>/DevToolsActivePort`. That file is the discovery mechanism — no
+ * port guessing, no collisions. From there everything is CDP over one WebSocket:
+ * `Target.createTarget` makes a page, `Target.attachToTarget` (flattened) gives a
+ * session for it, and the plugin's commands ride that session. Node 22 ships a global
+ * `WebSocket`, so this needs no dependency at all.
+ *
+ * WHAT IT IMPLEMENTS
+ * The same `ElectronBrowserViewHost` seam as the self-hosted and sidebar hosts, so
+ * the provider, the tools, history, the cursor and teardown rules are unchanged —
+ * only the carrier differs.
+ * @module dsh-browser/browser-electron/system-browser
+ */
+
+import { readFileSync, rmSync } from 'node:fs'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { spawn, type ChildProcess } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
+import type { ElectronBrowserViewHost, ElectronViewHandle } from './provider.js'
+
+/** Which browser the user asked for. */
+export type BrowserChannel = 'bundled' | 'chrome' | 'edge' | 'auto'
+
+/** A resolved browser installation. */
+export interface DetectedBrowser {
+  /** Which product this is. */
+  readonly kind: 'chrome' | 'edge' | 'brave'
+  /** Absolute path to the executable. */
+  readonly path: string
+}
+
+/**
+ * Where each Chromium product installs on Windows, plus the registry paths that
+ * survive a non-default install location. Only paths that exist are returned, so a
+ * caller can tell "not installed" from "installed elsewhere".
+ */
+const WINDOWS_LOCATIONS: Record<DetectedBrowser['kind'], string[]> = {
+  chrome: [
+    String.raw`C:\Program Files\Google\Chrome\Application\chrome.exe`,
+    String.raw`C:\Program Files (x86)\Google\Chrome\Application\chrome.exe`,
+  ],
+  edge: [
+    String.raw`C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe`,
+    String.raw`C:\Program Files\Microsoft\Edge\Application\msedge.exe`,
+  ],
+  brave: [
+    String.raw`C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe`,
+    String.raw`C:\Program Files (x86)\BraveSoftware\Brave-Browser\Application\brave.exe`,
+  ],
+}
+
+/**
+ * Find an installed Chromium browser.
+ *
+ * `auto` prefers Chrome, then Edge, then Brave — the order reflects how likely each
+ * is to be the browser a user actually chose rather than one Windows shipped.
+ * @param channel - the configured choice; `bundled` never resolves to a system browser.
+ * @param env - environment lookup, injected so tests need no real machine.
+ * @returns the detected browser, or undefined when the choice is unavailable.
+ */
+export function detectBrowser(channel: BrowserChannel, env: NodeJS.ProcessEnv = process.env): DetectedBrowser | undefined {
+  if (channel === 'bundled') return undefined
+  const order: DetectedBrowser['kind'][] = channel === 'auto' ? ['chrome', 'edge', 'brave'] : [channel as DetectedBrowser['kind']]
+  for (const kind of order) {
+    const fromEnv = (kind === 'chrome' ? env.DSH_BROWSER_CHROME_PATH : kind === 'edge' ? env.DSH_BROWSER_EDGE_PATH : undefined)
+    if (fromEnv !== undefined && fromEnv !== '' && existsSync(fromEnv)) return { kind, path: fromEnv }
+    for (const candidate of WINDOWS_LOCATIONS[kind] ?? []) {
+      if (existsSync(candidate)) return { kind, path: candidate }
+    }
+  }
+  return undefined
+}
+
+/** One CDP connection to a browser-level WebSocket, with flattened sessions. */
+class CdpClient {
+  private nextId = 1
+  private readonly pending = new Map<number, { resolve: (value: unknown) => void; reject: (error: Error) => void }>()
+  private readonly ready: Promise<void>
+
+  /**
+   * @param url - the browser's `webSocketDebuggerUrl`.
+   */
+  constructor(private readonly url: string) {
+    // Node 22 provides WebSocket globally; no dependency is added for this.
+    const socket = new WebSocket(url)
+    this.socket = socket
+    this.ready = new Promise<void>((resolve, reject) => {
+      socket.addEventListener('open', () => resolve())
+      socket.addEventListener('error', () => reject(new Error('dsh-builtin-browser: could not reach the browser over CDP')))
+    })
+    socket.addEventListener('message', event => this.onMessage(String((event as MessageEvent).data)))
+    socket.addEventListener('close', () => this.fail(new Error('dsh-builtin-browser: the browser closed the CDP connection')))
+  }
+
+  private readonly socket: WebSocket
+
+  /** Resolve once the socket is open. */
+  async whenReady(): Promise<void> {
+    await this.ready
+  }
+
+  /**
+   * Send one CDP command, optionally on an attached session.
+   * @param method - the CDP method.
+   * @param params - its parameters.
+   * @param sessionId - the flattened session to target, when this is a page command.
+   * @returns the CDP result.
+   */
+  async send(method: string, params?: Record<string, unknown>, sessionId?: string): Promise<unknown> {
+    await this.ready
+    const id = this.nextId++
+    const message = { id, method, ...params !== undefined ? { params } : {}, ...sessionId !== undefined ? { sessionId } : {} }
+    return await new Promise<unknown>((resolve, reject) => {
+      this.pending.set(id, { resolve, reject })
+      this.socket.send(JSON.stringify(message))
+      setTimeout(() => {
+        if (this.pending.delete(id)) reject(new Error(`dsh-builtin-browser: ${method} timed out`))
+      }, 30_000).unref?.()
+    })
+  }
+
+  /** Close the socket. */
+  close(): void {
+    try { this.socket.close() } catch { /* already closed */ }
+  }
+
+  /** Route one CDP message to its waiter. */
+  private onMessage(raw: string): void {
+    let message: { id?: number; result?: unknown; error?: { message?: string } }
+    try { message = JSON.parse(raw) } catch { return }
+    if (message.id === undefined) return
+    const entry = this.pending.get(message.id)
+    if (entry === undefined) return
+    this.pending.delete(message.id)
+    if (message.error !== undefined) entry.reject(new Error(`dsh-builtin-browser: CDP error: ${message.error.message ?? 'unknown'}`))
+    else entry.resolve(message.result)
+  }
+
+  /** Fail everything in flight. */
+  private fail(error: Error): void {
+    const pending = [...this.pending.values()]
+    this.pending.clear()
+    for (const entry of pending) entry.reject(error)
+  }
+}
+
+/** A system browser driven over CDP, presented as a browser view host. */
+export class SystemBrowserViewHost implements ElectronBrowserViewHost {
+  private readonly views = new Map<string, string>()
+  private disposed = false
+  /**
+   * The browser is started on FIRST USE, never on construction.
+   *
+   * A plugin that launches Chrome the moment its host loads is a plugin that takes
+   * over the machine before anyone asked it to: simply starting DSH would spawn a
+   * browser window. Registration must therefore be inert, and the process is only
+   * spawned when a view is actually needed.
+   */
+  private client: CdpClient | undefined
+  private child: ChildProcess | undefined
+  private starting: Promise<CdpClient> | undefined
+
+  /**
+   * @param browser - the detected installation to launch on first use.
+   * @param profileDir - a plugin-owned directory; the user's own profile is never touched.
+   * @param extraArgs - additional Chromium switches.
+   * @param ephemeralDir - a directory to delete on release, when the user has turned
+   *   persistence off so no login state outlives the session.
+   */
+  constructor(
+    private readonly browser: DetectedBrowser,
+    private readonly profileDir: string,
+    private readonly extraArgs: readonly string[] = [],
+    private readonly ephemeralDir?: string,
+  ) {}
+
+  /** Which product this host would drive (for diagnostics). */
+  get kind(): DetectedBrowser['kind'] {
+    return this.browser.kind
+  }
+
+  /** Whether the browser has actually been started yet (diagnostics and tests). */
+  get started(): boolean {
+    return this.child !== undefined
+  }
+
+  /**
+   * The CDP client, starting the browser on first use.
+   * @returns the connected client.
+   */
+  private async ensureClient(): Promise<CdpClient> {
+    if (this.client !== undefined) return this.client
+    // Concurrent first calls share one startup rather than racing two browsers.
+    this.starting ??= this.start().finally(() => { this.starting = undefined })
+    return await this.starting
+  }
+
+  /**
+   * Launch the browser with a private profile and connect over CDP.
+   *
+   * `--remote-debugging-port=0` plus the `DevToolsActivePort` file is the only
+   * reliable way to learn the port: a fixed port collides with whatever else the
+   * machine is running, and parsing stderr is fragile across versions.
+   * @returns the connected client.
+   */
+  private async start(): Promise<CdpClient> {
+    const args = [
+      '--remote-debugging-port=0',
+      `--user-data-dir=${this.profileDir}`,
+      // Behave like a fresh, unattended browser: no first-run UI, no default-browser
+      // prompt, no restore bubble, and no "Chrome is being controlled" infobar.
+      '--no-first-run',
+      '--no-default-browser-check',
+      '--disable-features=Translate,MediaRouter',
+      '--disable-session-crashed-bubble',
+      '--hide-crash-restore-bubble',
+      ...this.extraArgs,
+      'about:blank',
+    ]
+    const child = spawn(this.browser.path, args, { stdio: ['ignore', 'ignore', 'ignore'], windowsHide: false })
+    this.child = child
+    const portFile = join(this.profileDir, 'DevToolsActivePort')
+    const deadline = Date.now() + 30_000
+    for (;;) {
+      if (Date.now() > deadline) { child.kill(); this.child = undefined; break }
+      if (child.exitCode !== null) { this.child = undefined; break }
+      if (existsSync(portFile)) {
+        try {
+          const port = readFileSync(portFile, 'utf8').split('\n')[0]?.trim() ?? ''
+          if (port !== '') {
+            const version = await (await fetch(`http://127.0.0.1:${port}/json/version`)).json() as { webSocketDebuggerUrl?: string }
+            if (typeof version.webSocketDebuggerUrl === 'string') {
+              const client = new CdpClient(version.webSocketDebuggerUrl)
+              await client.whenReady()
+              this.client = client
+              return client
+            }
+          }
+        } catch {
+          // The file can exist a moment before the port answers; poll again.
+        }
+      }
+      await new Promise(resolve => setTimeout(resolve, 250))
+    }
+    throw new Error(`dsh-builtin-browser: ${this.browser.kind} did not expose CDP within 30s (${this.browser.path})`)
+  }
+
+  /**
+   * Whether this host can back views.
+   *
+   * True while the host is usable — including before the browser has been started,
+   * since the first command is what starts it. Reporting "unavailable" here would
+   * make the plugin fall back for no reason.
+   */
+  available(): boolean {
+    return !this.disposed
+  }
+
+  createView(): ElectronViewHandle {
+    const viewId = randomUUID()
+    return {
+      id: viewId,
+      sendCommand: async (method: string, params?: Record<string, unknown>) => {
+        const client = await this.ensureClient()
+        const session = this.views.get(viewId) ?? await this.ensureSession(viewId)
+        const result = await client.send(method, params, session)
+        return (result ?? {}) as Record<string, unknown>
+      },
+    }
+  }
+
+  destroyView(handle: ElectronViewHandle): void {
+    const session = this.views.get(handle.id)
+    this.views.delete(handle.id)
+    if (session === undefined) return
+    // A session id is not a target id: closing the page needs the target the session
+    // was attached to, which is why they are tracked separately.
+    const targetId = this.sessions.get(session)
+    this.sessions.delete(session)
+    // Nothing to close if the browser was never started.
+    if (targetId !== undefined && this.client !== undefined) {
+      // Best-effort: a page that is already gone is not an error.
+      void this.client.send('Target.closeTarget', { targetId }).catch(() => undefined)
+    }
+  }
+
+  /** Nothing to show: the browser owns its own windows. */
+  showView(): void {}
+
+  /** Same as {@link showView}. */
+  async presentView(): Promise<void> {}
+
+  /** The browser owns window grouping. */
+  groupView(): void {}
+
+  /**
+   * Bring the browser's window forward.
+   *
+   * The browser is a separate application, so there is no view to raise; focusing
+   * the process is the closest honest equivalent, and failing to do so (a minimized
+   * window, a locked session) is never worth an error.
+   */
+  async focus(): Promise<void> {
+    try { this.child?.kill('SIGCONT') } catch { /* not supported on Windows; harmless */ }
+  }
+
+  /** The browser reports its own window lifecycle. */
+  onUserAction(): void {}
+
+  /** The browser reports its own window lifecycle. */
+  onViewClosed(): void {}
+
+  /**
+   * Close the browser we launched, if we ever launched one.
+   *
+   * The user's own windows belong to a different process and are never touched. A
+   * host whose browser was never started (the common case when nobody used the
+   * browser) simply tears down its bookkeeping.
+   */
+  dispose(): void {
+    if (this.disposed) return
+    this.disposed = true
+    this.views.clear()
+    this.sessions.clear()
+    this.client?.close()
+    try { this.child?.kill() } catch { /* already gone */ }
+    const ephemeral = this.ephemeralDir
+    if (ephemeral !== undefined && this.child !== undefined) {
+      // The browser flushes its profile while shutting down, so deleting later avoids
+      // racing it. Leftovers are only a stray temp directory, never a live credential.
+      setTimeout(() => { try { rmSync(ephemeral, { recursive: true, force: true }) } catch { /* best effort */ } }, 3_000).unref?.()
+    } else if (ephemeral !== undefined) {
+      // Never started, so nothing can be holding it open.
+      try { rmSync(ephemeral, { recursive: true, force: true }) } catch { /* best effort */ }
+    }
+  }
+
+  /** The flattened session for a view, creating its page on first use. */
+  private async ensureSession(viewId: string): Promise<string> {
+    const existing = this.views.get(viewId)
+    if (existing !== undefined) return existing
+    const client = await this.ensureClient()
+    const created = await client.send('Target.createTarget', { url: 'about:blank' }) as { targetId?: string }
+    const targetId = created?.targetId
+    if (typeof targetId !== 'string') throw new Error('dsh-builtin-browser: the browser did not create a page')
+    const attached = await client.send('Target.attachToTarget', { targetId, flatten: true }) as { sessionId?: string }
+    const sessionId = attached?.sessionId
+    if (typeof sessionId !== 'string') throw new Error('dsh-builtin-browser: the browser did not attach to the new page')
+    // The session id is what page commands ride; the target id is what closes it.
+    this.sessions.set(sessionId, targetId)
+    this.views.set(viewId, sessionId)
+    return sessionId
+  }
+
+  /** sessionId -> targetId, so a destroyed view can close the right page. */
+  private readonly sessions = new Map<string, string>()
+}

package/src/browser-electron/virtual-cursor.ts

@@ -22,15 +22,46 @@ export type CursorAction = 'move' | 'click'
 /** Element id of the overlay root, stable so repeat calls update one node. */
 const CURSOR_ID = '__dsh_agent_cursor__'
 
+/**
+ * Where the overlay was last placed, so an unchanged position is not repainted.
+ *
+ * A single tool call issues several CDP commands (locate, click, cursor), and the
+ * cursor is repainted for each one that moves it. Repainting to the same pixel is a
+ * wasted round-trip *and* a visible flicker: the transition restarts from the same
+ * place, which reads as a stutter rather than as movement.
+ */
+const lastPlaced = new WeakMap<object, { x: number; y: number; action: CursorAction }>()
+
+/**
+ * Whether a paint at this position would change anything on screen.
+ * @param handle - the view the overlay belongs to.
+ * @param x - viewport x in CSS pixels.
+ * @param y - viewport y in CSS pixels.
+ * @param action - the action being reported.
+ * @param force - paint even when unchanged (a click ripple must always fire).
+ * @returns true when the overlay should be painted.
+ */
+export function cursorNeedsPaint<TView>(handle: TView, x: number, y: number, action: CursorAction, force = false): boolean {
+  if (force) return true
+  const key = handle as unknown as object
+  if (key === null || typeof key !== 'object') return true
+  const previous = lastPlaced.get(key)
+  return previous === undefined || previous.x !== x || previous.y !== y || previous.action !== action
+}
+
 /**
  * The in-page expression that materializes or moves the overlay. Idempotent: the
  * first call creates the nodes, later calls only move them (and pulse).
  * @param x - viewport x in CSS pixels.
  * @param y - viewport y in CSS pixels.
  * @param action - whether to pulse a click ripple at the point.
+ * @param label - optional short description of the operation, shown beside the
+ *   pointer. The overlay is the only "the agent has taken over this tab" signal, so
+ *   saying *what* it is doing is what turns it from a decoration into an account of
+ *   the agent's actions that a human can follow without reading the tool log.
  * @returns a self-contained expression that evaluates to `true`.
  */
-export function cursorScript(x: number, y: number, action: CursorAction): string {
+export function cursorScript(x: number, y: number, action: CursorAction, label?: string): string {
   return `(() => {
   const id = ${JSON.stringify(CURSOR_ID)}
   let root = document.getElementById(id)
@@ -38,25 +69,56 @@ export function cursorScript(x: number, y: number, action: CursorAction): string
     root = document.createElement('div')
     root.id = id
     root.setAttribute('aria-hidden', 'true')
-    root.style.cssText = 'position:fixed;left:0;top:0;width:0;height:0;z-index:2147483647;pointer-events:none;transition:transform 120ms ease-out;will-change:transform'
+    root.style.cssText = 'position:fixed;left:0;top:0;width:0;height:0;z-index:2147483647;pointer-events:none;transition:transform 190ms cubic-bezier(.22,.85,.24,1);will-change:transform'
     const svg = '<svg width="22" height="22" viewBox="0 0 22 22" style="position:absolute;left:-2px;top:-2px;filter:drop-shadow(0 1px 2px rgba(0,0,0,.45))">'
       + '<path d="M4 2 L4 18 L8.4 13.8 L11.2 19.6 L13.8 18.4 L11 12.8 L17 12.6 Z" fill="#ffffff" stroke="#111111" stroke-width="1.4" stroke-linejoin="round"/></svg>'
-    const ripple = '<span style="position:absolute;left:0;top:0;width:34px;height:34px;margin:-17px 0 0 -17px;border-radius:50%;border:2px solid rgba(64,160,255,.9);opacity:0"></span>'
-    root.innerHTML = svg + ripple
+    const ripple = '<span data-dsh-role="ripple" style="position:absolute;left:0;top:0;width:34px;height:34px;margin:-17px 0 0 -17px;border-radius:50%;border:2px solid rgba(64,160,255,.9);opacity:0"></span>'
+    // The bubble sits below-right of the pointer tip and is capped in width so a long
+    // label cannot cover the page it is describing.
+    const bubble = '<span data-dsh-role="bubble" style="position:absolute;left:18px;top:16px;max-width:280px;padding:3px 8px;border-radius:5px;background:rgba(17,17,17,.92);color:#fff;font:12px/1.45 -apple-system,Segoe UI,Roboto,sans-serif;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;opacity:0;box-shadow:0 1px 3px rgba(0,0,0,.4)"></span>'
+    root.innerHTML = svg + ripple + bubble
     ;(document.body || document.documentElement).appendChild(root)
   }
   root.style.transform = 'translate(${x}px, ${y}px)'
-  ${action === 'click' ? `const ripple = root.lastElementChild
+  ${action === 'click' ? `const ripple = root.querySelector('[data-dsh-role="ripple"]')
   if (ripple && typeof ripple.animate === 'function') {
     ripple.animate(
       [{ transform: 'scale(.25)', opacity: 0.95 }, { transform: 'scale(1.6)', opacity: 0 }],
       { duration: 550, easing: 'ease-out' },
     )
   }` : ''}
+  ${label !== undefined && label !== '' ? `const bubble = root.querySelector('[data-dsh-role="bubble"]')
+  if (bubble) {
+    bubble.textContent = ${JSON.stringify(label)}
+    if (typeof bubble.animate === 'function') {
+      // Fade in, hold, fade out: the label is a narration of the action, not a
+      // permanent caption, so a stale one never lingers over later work.
+      bubble.animate(
+        [{ opacity: 0, transform: 'translateY(-3px)' }, { opacity: 1, transform: 'translateY(0)' }, { opacity: 1, offset: 0.6 }, { opacity: 0 }],
+        { duration: 2200, easing: 'ease-out', fill: 'forwards' },
+      )
+    } else {
+      bubble.style.opacity = '1'
+    }
+  }` : ''}
   return true
 })()`
 }
 
+/**
+ * Forget the remembered position for a view.
+ *
+ * Called when the document is replaced: the overlay lived in the old document and
+ * went with it, so the cache would otherwise claim the pointer is already where it
+ * needs to be and skip every later paint — the pointer would simply never return
+ * after a navigation.
+ * @param handle - the view whose cache should be dropped.
+ */
+export function forgetCursor<TView>(handle: TView): void {
+  const key = handle as unknown as object
+  if (key !== null && typeof key === 'object') lastPlaced.delete(key)
+}
+
 /**
  * Draw (or move) the pointer overlay on one view's page.
  *
@@ -69,6 +131,7 @@ export function cursorScript(x: number, y: number, action: CursorAction): string
  * @param y - viewport y in CSS pixels.
  * @param action - whether to pulse a click ripple.
  * @param evaluate - the provider's evaluate bridge (keeps the CDP coupling in one place).
+ * @param label - optional short description of the operation, shown beside the pointer.
  */
 export function paintCursor<TView>(
   handle: TView,
@@ -76,7 +139,14 @@ export function paintCursor<TView>(
   y: number,
   action: CursorAction,
   evaluate: (handle: TView, expression: string) => Promise<unknown>,
+  label?: string,
+  force = false,
 ): void {
   if (!Number.isFinite(x) || !Number.isFinite(y)) return
-  void evaluate(handle, cursorScript(Math.round(x), Math.round(y), action)).catch(() => {})
+  const roundedX = Math.round(x)
+  const roundedY = Math.round(y)
+  if (!cursorNeedsPaint(handle, roundedX, roundedY, action, force)) return
+  const key = handle as unknown as object
+  if (key !== null && typeof key === 'object') lastPlaced.set(key, { x: roundedX, y: roundedY, action })
+  void evaluate(handle, cursorScript(roundedX, roundedY, action, label)).catch(() => {})
 }

package/src/tool-browser/index.ts

@@ -161,15 +161,26 @@ function parseFillValue(v: string | undefined): string | number | boolean {
   return v ?? ''
 }
 
-/** Format a snapshot element list for the model. */
+/**
+ * Format a snapshot element list for the model.
+ *
+ * Coordinates are opt-in. They are only meaningful to a caller that intends to
+ * click a pixel position, which means a vision pass; for the far more common case
+ * of locating an element by role/label and passing a semantic target, they are the
+ * bulkiest and least useful part of every line. Omitting them keeps the listing
+ * readable — which is exactly what a model without image input has to work from.
+ * @param snapshot - the snapshot payload.
+ * @param options - `coords: true` to include each element's viewport position.
+ */
 function formatSnapshot(snapshot: {
   url: string
   title?: string
   elements: readonly { ref: number; kind: string; label: string; x: number; y: number; frame?: boolean }[]
   truncated?: boolean
   challenge?: { blocked: boolean; kind?: string; reason?: string }
-}): string {
-  const lines = snapshot.elements.map(el => `[${el.ref}] ${el.kind}: ${el.label}${el.frame === true ? ' (iframe)' : ''} (${el.x},${el.y})`)
+}, options: { coords?: boolean } = {}): string {
+  const showCoords = options.coords === true
+  const lines = snapshot.elements.map(el => `[${el.ref}] ${el.kind}: ${el.label}${el.frame === true ? ' (iframe)' : ''}${showCoords ? ` (${el.x},${el.y})` : ''}`)
   const header = `URL: ${snapshot.url}${snapshot.title !== undefined ? `\nTitle: ${snapshot.title}` : ''}`
   const body = lines.length > 0 ? lines.join('\n') : '(no interactive elements found)'
   const tail = snapshot.truncated === true ? '\n(snapshot truncated)' : ''
@@ -241,7 +252,10 @@ export function apply(ctx: Context, config: Config = {}): void {
           },
         },
       },
-      render: (_args, value) => [{ type: 'text', text: formatSnapshot(value) }],
+      // browser_open is an overview of what just loaded, not a locator: it has no
+      // `coords` parameter, so coordinates stay off here (browser_snapshot owns
+      // that switch for callers that actually target pixels).
+      render: (args, value) => [{ type: 'text', text: formatSnapshot(value, { coords: (args as { coords?: boolean }).coords === true }) }],
     },
     timeoutMs,
     isConcurrencySafe: () => false, // opens tabs / navigates; exclusive within a task
@@ -267,8 +281,10 @@ export function apply(ctx: Context, config: Config = {}): void {
 
   ctx.tools.register(defineTool({
     name: 'browser_snapshot',
-    description: 'Return an AI-friendly snapshot of the current shared-browser page: numbered interactive elements (inputs, buttons, links) the model can cite. Use this to understand an interactive page before driving it.',
-    parameters: {},
+    description: 'Return an AI-friendly snapshot of the current shared-browser page: numbered interactive elements (inputs, buttons, links) the model can cite. This is the primary way to understand a page, and it needs no image input — every listed element can afterwards be addressed by a semantic target (browser_click, browser_type, browser_check, …) rather than by coordinates.',
+    parameters: {
+      coords: { type: 'boolean', description: 'Also print each element\'s viewport coordinates. Off by default; only useful when a vision pass is going to click a pixel position.' },
+    },
     output: {
       schema: {
         type: 'object',
@@ -304,7 +320,7 @@ export function apply(ctx: Context, config: Config = {}): void {
           },
         },
       },
-      render: (_args, value) => [{ type: 'text', text: formatSnapshot(value) }],
+      render: (args, value) => [{ type: 'text', text: formatSnapshot(value, { coords: args.coords === true }) }],
     },
     timeoutMs,
     isConcurrencySafe: () => true,
@@ -329,6 +345,7 @@ export function apply(ctx: Context, config: Config = {}): void {
     parameters: {
       includeHidden: { type: 'boolean', description: 'Include hidden elements (default false).' },
       maxNodes: { type: 'number', description: 'Maximum nodes (default 500, range 10-5000).' },
+      coords: { type: 'boolean', description: 'Include each element\'s viewport coordinates. Off by default: a semantic target needs no coordinates, and they are pure noise unless a vision pass is going to click a pixel position.' },
     },
     output: {
       schema: {
@@ -361,14 +378,24 @@ export function apply(ctx: Context, config: Config = {}): void {
           },
         },
       },
-      render: (_args, value) => {
+      render: (args, value) => {
         const nodes = value.nodes as Array<{ ref: number; role: string; name: string; value?: string | null; states: string[]; depth: number; tag: string; x: number; y: number; frame?: boolean }>
+        // Built for reading, not for imaging: containment is shown as indentation
+        // (the depth was already collected and simply thrown away), an empty state
+        // list adds nothing, and coordinates appear only when asked for — a model
+        // working from the DOM never needs them, and they are the bulkiest part of
+        // every line.
+        const showCoords = args.coords === true
         const lines = nodes.map(n => {
           const valuePart = n.value !== undefined && n.value !== null ? ` value="${String(n.value).slice(0, 60)}"` : ''
-          return `[${n.ref}] ${n.role} "${n.name}"${valuePart} (${n.x},${n.y}) states=[${n.states.join(',')}]${n.frame === true ? ' (iframe)' : ''}`
+          const indent = '  '.repeat(Math.max(0, Math.min(8, Number(n.depth) || 0)))
+          const coordsPart = showCoords ? ` (${n.x},${n.y})` : ''
+          const statePart = Array.isArray(n.states) && n.states.length > 0 ? ` states=[${n.states.join(',')}]` : ''
+          return `${indent}[${n.ref}] ${n.role} "${n.name}"${valuePart}${coordsPart}${statePart}${n.frame === true ? ' (iframe)' : ''}`
         })
         const header = `URL: ${value.url}${value.title !== undefined ? `\nTitle: ${value.title}` : ''}`
-        return [{ type: 'text', text: `${header}\n\n${lines.length > 0 ? lines.join('\n') : '(no accessible interactive nodes)'}${value.truncated === true ? '\n(truncated)' : ''}` }]
+        const hint = showCoords ? '' : '\n(coordinates omitted — pass coords: true to include them, or click by semantic target)'
+        return [{ type: 'text', text: `${header}\n\n${lines.length > 0 ? lines.join('\n') : '(no accessible interactive nodes)'}${value.truncated === true ? '\n(truncated)' : ''}${hint}` }]
       },
     },
     timeoutMs,
@@ -601,7 +628,7 @@ export function apply(ctx: Context, config: Config = {}): void {
 
   ctx.tools.register(defineTool({
     name: 'browser_click',
-    description: 'Click in the shared browser. Two ways: (1) semantic target — pass target {by: css|text|xpath, value, index?} and the element is located, scrolled into view and clicked at its center; (2) viewport coordinates (x/y) — use with browser_screenshot when a vision model locates an element on the screenshot (covers icons, image buttons, and canvas that DOM locators cannot target). Provide exactly one of target or x/y.',
+    description: 'Click in the shared browser. Prefer the semantic target: pass target {by: css|text|xpath, value, index?} and the element is located from the DOM, scrolled into view and clicked at its centre — this needs no image input and is the only form that works without vision. The alternative is viewport coordinates (x/y), which are meaningful only after a vision model has located the element on a browser_screenshot; coordinate clicks are refused outright under the non-visual strategy. Provide exactly one of target or x/y.',
     parameters: {
       target: {
         type: 'object',
@@ -613,8 +640,8 @@ export function apply(ctx: Context, config: Config = {}): void {
         },
         description: 'Locate the element semantically and click it (css/text/xpath).',
       },
-      x: { type: 'number', description: 'Viewport x coordinate (CSS px), e.g. from a vision model reading the screenshot.' },
-      y: { type: 'number', description: 'Viewport y coordinate (CSS px).' },
+      x: { type: 'number', description: 'Viewport x coordinate (CSS px), taken from a browser_screenshot read by a vision model. Prefer a semantic target — it works without image input.' },
+      y: { type: 'number', description: 'Viewport y coordinate (CSS px), taken from the same screenshot as x.' },
     },
     output: {
       schema: { type: 'object', additionalProperties: false, properties: { clicked: { type: 'boolean', required: true } } },
@@ -1089,7 +1116,7 @@ export function apply(ctx: Context, config: Config = {}): void {
 
   ctx.tools.register(defineTool({
     name: 'browser_screenshot',
-    description: 'Capture the current shared-browser page as a screenshot (PNG default, JPEG optional). Use for visual confirmation of layout, charts, designs, or CAPTCHAs, or to feed a vision tool (read_image) that locates elements visually. Supports full-page capture, save-to-file, JPEG encoding, and downscaling (maxWidth/maxHeight) to cut vision-tool token cost. JPEG is only available on the self-hosted native path; the desktop-shell path returns PNG.',
+    description: 'Capture the current shared-browser page as a screenshot (PNG default, JPEG optional). This is for models that can read images: layout checks, charts, designs, CAPTCHAs, or locating an element by eye before clicking its coordinates. A model without image input gains nothing from it — browser_snapshot, browser_a11y and browser_content carry the same page as text, and browser_scrape extracts structured data. Supports full-page capture, save-to-file, JPEG encoding, and downscaling (maxWidth/maxHeight) to cut vision-tool token cost. JPEG is only available on the self-hosted native path; the desktop-shell path returns PNG.',
     parameters: {
       fullPage: { type: 'boolean', description: 'Capture the full scrollable page instead of the viewport (default false).' },
       savePath: { type: 'string', description: 'Absolute file path to also save the image to (e.g. for read_image vision location). Must resolve inside the configured downloadDir (default: the system Downloads folder, localized names such as ~/下载 included); an existing file is never overwritten.' },
@@ -1338,6 +1365,8 @@ export function apply(ctx: Context, config: Config = {}): void {
     parameters: {
       limit: { type: 'number', description: 'Maximum entries to return (default 30, capped at 200).' },
       domain: { type: 'string', description: 'Only visits whose hostname contains this text (case-insensitive).' },
+      query: { type: 'string', description: 'Only visits whose URL or title contains this text (case-insensitive).' },
+      session: { type: 'string', description: 'Only visits recorded by this task/session label — use it to separate your own pages from another session\'s or the human\'s.' },
     },
     output: {
       schema: {
@@ -1384,7 +1413,14 @@ export function apply(ctx: Context, config: Config = {}): void {
       const rawLimit = typeof args.limit === 'number' && Number.isFinite(args.limit) ? args.limit : 30
       const limit = Math.max(1, Math.min(200, Math.floor(rawLimit)))
       const domain = typeof args.domain === 'string' && args.domain.trim() !== '' ? args.domain.trim() : undefined
-      const entries = browser.visited({ limit, ...domain !== undefined ? { domain } : {} })
+      const query = typeof args.query === 'string' && args.query.trim() !== '' ? args.query.trim() : undefined
+      const session = typeof args.session === 'string' && args.session.trim() !== '' ? args.session.trim() : undefined
+      const entries = browser.visited({
+        limit,
+        ...domain !== undefined ? { domain } : {},
+        ...query !== undefined ? { query } : {},
+        ...session !== undefined ? { session } : {},
+      })
       return {
         count: entries.length,
         entries: entries.map(entry => ({