dsh-builtin-browser 0.1.22 → 0.2.0

package/src/browser-electron/remote-host.ts

@@ -440,12 +440,28 @@ class ElectronChildClient {
     private readonly token: string,
     private readonly onExit?: () => void,
     private readonly onUserAction?: (action: BrowserUserAction) => void,
+    /**
+     * Called when the human closes a browser window. The session it showed is
+     * over: the provider releases it, while history and login state stay on disk
+     * so the next open is a clean session rather than a resurrected one.
+     */
+    private readonly onViewClosed?: (windowId: string) => void,
     /** Test seam: the executable to spawn instead of the resolved Electron
      *  binary. Absent -> resolveElectronPath() (production behavior). */
     private readonly executable?: string,
   ) {
     const electron = this.executable ?? resolveElectronPath()
+    // Record what is about to be spawned — with existence checks — BEFORE the
+    // attempt. When Electron cannot load the app entry it exits 1 with EMPTY
+    // stderr, and that signature is otherwise indistinguishable from a missing
+    // binary: writing both paths (and whether they exist) in advance is what
+    // turns the next occurrence into a named cause instead of a guess.
     process.stderr.write(`[dsh-browser host] spawning electron: ${electron}\n`)
+    appendHostLog(
+      `${hostStamp()} spawning: electron=${electron} (exists=${String(existsSync(electron))})`
+      + ` hostMain=${this.hostMainPath} (exists=${String(existsSync(this.hostMainPath))})`
+      + ` port=${String(this.port)}\n`,
+    )
     // ELECTRON_RUN_AS_NODE (even an empty string) makes Electron run as plain
     // Node, breaking require('electron'); NODE_OPTIONS can inject flags that
     // break the child. Rebuild the env without either.
@@ -482,15 +498,26 @@ class ElectronChildClient {
     // A failed spawn (bad/corrupt binary) emits 'error' — without a listener
     // that would crash the whole DSH process.
     this.child.on('error', error => {
-      const line = `spawn error: ${String(error)}`
+      const line = `${hostStamp()} spawn error: ${String(error)} electron=${electron} hostMain=${this.hostMainPath}`
       process.stderr.write(`[dsh-browser host] ${line}\n`)
       appendHostLog(`${line}\n`)
       this.fail(new Error(`dsh-builtin-browser: browser host failed to start: ${String(error)}`))
     })
     this.child.on('exit', (code, signal) => {
       // The exit code/signal is the other half of a crash report; without it a
-      // restart loop is indistinguishable from a clean stop.
-      const line = `browser host exited (code=${String(code)} signal=${String(signal)})`
+      // restart loop is indistinguishable from a clean stop. The timestamp, pid
+      // and both paths are what turn a bare `code=1` into a diagnosis: Electron
+      // exits 1 with empty stderr precisely when it cannot load the app entry,
+      // so the dated `exists=` line written at spawn is the other half.
+      const entryExists = existsSync(this.hostMainPath)
+      const line = `${hostStamp()} browser host exited (code=${String(code)} signal=${String(signal)})`
+        + ` pid=${String(this.child?.pid)} electron=${electron} hostMain=${this.hostMainPath}`
+        + ` entryExists=${String(entryExists)}`
+        // Comparing this with the `exists=` recorded at spawn is the whole
+        // diagnosis: present at spawn and absent now means the installation was
+        // replaced underneath a running host, which is exactly how Electron ends
+        // up unable to load the app entry and exits 1 with empty stderr.
+        + (entryExists ? '' : ' [entry script missing at exit]')
       appendHostLog(`${line}\n`)
       this.fail(new Error(`dsh-builtin-browser: ${line}`))
     })
@@ -566,7 +593,7 @@ class ElectronChildClient {
       const line = this.buffer.slice(0, nl).trim()
       this.buffer = this.buffer.slice(nl + 1)
       if (line === '') continue
-      let msg: { id?: number; op?: string; token?: string; ok?: boolean; result?: unknown; err?: string; action?: unknown }
+      let msg: { id?: number; op?: string; token?: string; ok?: boolean; result?: unknown; err?: string; action?: unknown; windowId?: unknown }
       try {
         msg = JSON.parse(line) as typeof msg
       } catch {
@@ -580,6 +607,14 @@ class ElectronChildClient {
         this.onUserAction?.(msg.action as BrowserUserAction)
         continue
       }
+      if (msg.op === 'viewClosed') {
+        // Fire-and-forget notification from the child's own UI: the human closed
+        // the window, so the interface that session showed is gone. The provider
+        // decides what that ends — browsing history and login state survive on
+        // disk, only the session itself does not.
+        this.onViewClosed?.(typeof msg.windowId === 'string' ? msg.windowId : '')
+        continue
+      }
       if (this.awaitingHello) {
         // The FIRST line must be the child's hello carrying the spawn token.
         // Anything else (or a wrong token) means a spoofed connection: drop
@@ -657,6 +692,11 @@ class RemoteView implements ElectronViewHandle {
     })
   }
 
+  /** Give this view web focus in the child, so keyboard input reaches the page. */
+  focus(): Promise<void> {
+    return this.client.call<void>('focus', { viewId: this.id })
+  }
+
   /** Ask the child to download a URL to a local file (keeps cookies/login). */
   async download(url: string, savePath: string): Promise<void> {
     // The child writes the file itself (temp + rename); only a small
@@ -681,6 +721,15 @@ class RemoteView implements ElectronViewHandle {
   }
 }
 
+/**
+ * How long a FAILED Electron-binary probe is remembered before the binary
+ * search runs again (`available()`). A success is kept for the host's lifetime.
+ */
+const PROBE_RETRY_MS = (() => {
+  const raw = Number(process.env.DSH_BROWSER_PROBE_RETRY_MS)
+  return Number.isFinite(raw) && raw >= 0 ? raw : 30000
+})()
+
 /**
  * Self-hosted view host: spawns the plugin's Electron child on first use and
  * keeps it alive until dispose(). Fallback when no desktop shell provides
@@ -693,40 +742,59 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
   private readonly views = new Map<string, ElectronViewHandle>()
   private readyPromise: Promise<void> | undefined
   private disposed = false
-  /** Cached probe result so `available()` stays cheap after the first call. */
+  /** Last probe result. A success is kept for the host's lifetime; a failure
+   *  is retried after `PROBE_RETRY_MS` (see `available()`). */
   private electronAvailable: boolean | undefined
+  /** Earliest time the next probe may run after a negative one. */
+  private nextProbeAt = 0
   /** Window groups (windowId per view), re-sent on every materialization so
    *  a restarted child still places views in the right windows. */
   private readonly groups = new Map<string, { windowId: string; label?: string }>()
   /** The provider's user-action handler; routes toolbar actions into sessions. */
   private userActionHandler: ((action: BrowserUserAction) => void) | undefined
+  /**
+   * The provider's handler for a window the human closed. Closing the interface
+   * ends the session it showed: history and login state stay on disk, so the
+   * next open starts clean instead of resuming a window nobody can see.
+   */
+  private viewClosedHandler: ((windowId: string) => void) | undefined
 
   constructor(
     private readonly hostMainPath: string,
     /** Test seam: the executable to spawn instead of the resolved Electron
      *  binary. Absent -> resolveElectronPath() (production behavior). */
     private readonly spawnExecutable?: string,
+    /** Test seam: the binary probe behind `available()`. Absent ->
+     *  resolveElectronPath(). */
+    private readonly probe: () => void = resolveElectronPath,
   ) {}
 
   /**
    * Cheap usability probe: can we find an Electron binary to spawn? The scan
-   * is filesystem-only (no network), per the seam's contract, and the result
-   * is cached for the host's lifetime — a missing binary surfaces as
-   * `BROWSER_PROVIDER_UNAVAILABLE` at provider selection instead of a
-   * confusing spawn failure on first use.
+   * is filesystem-only (no network), per the seam's contract, so a missing
+   * binary surfaces as `BROWSER_PROVIDER_UNAVAILABLE` at provider selection
+   * instead of a confusing spawn failure on first use.
+   *
+   * A success is cached for the host's lifetime. A failure is NOT: an install
+   * (`npm i electron`, or the postinstall that fetches the binary) can land
+   * long after DSH started, and provider selection happens once per process —
+   * caching "no" permanently reported "no usable browser provider is
+   * registered" until DSH restarted, with no way back short of that. Retrying
+   * on a cooldown heals it by itself while keeping the scan off the hot path.
    */
   available(): boolean {
-    if (this.electronAvailable === undefined) {
-      try {
-        resolveElectronPath()
-        this.electronAvailable = true
-      } catch (error) {
-        this.electronAvailable = false
-        // The provider will be reported unavailable, so the detailed
-        // resolution error (install-electron / ELECTRON_PATH guidance) would
-        // otherwise never reach the user — surface it on stderr.
-        process.stderr.write(`[dsh-browser host] electron unavailable: ${error instanceof Error ? error.message : String(error)}\n`)
-      }
+    if (this.electronAvailable === true) return true
+    if (Date.now() < this.nextProbeAt) return false
+    this.nextProbeAt = Date.now() + PROBE_RETRY_MS
+    try {
+      this.probe()
+      this.electronAvailable = true
+    } catch (error) {
+      this.electronAvailable = false
+      // The provider will be reported unavailable, so the detailed
+      // resolution error (install-electron / ELECTRON_PATH guidance) would
+      // otherwise never reach the user — surface it on stderr.
+      process.stderr.write(`[dsh-browser host] electron unavailable: ${error instanceof Error ? error.message : String(error)}\n`)
     }
     return this.electronAvailable
   }
@@ -799,6 +867,7 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
       token,
       () => this.onChildExit(),
       action => this.userActionHandler?.(action),
+      windowId => this.viewClosedHandler?.(windowId),
       this.spawnExecutable,
     )
     if (this.pendingSocket !== undefined) {
@@ -932,6 +1001,11 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
     this.userActionHandler = handler
   }
 
+  /** Register the provider's handler for windows the human closed. */
+  onViewClosed(handler: (windowId: string) => void): void {
+    this.viewClosedHandler = handler
+  }
+
   /** Surface a failed user action to the child's toolbar (address bar etc.). */
   notifyUserActionError(windowId: string, message: string): void {
     void this.ready()
@@ -1027,6 +1101,10 @@ class DeferredRemoteView implements ElectronViewHandle {
     return this.withRecovery(view => view.capture(opts))
   }
 
+  async focus(): Promise<void> {
+    return this.withRecovery(view => view.focus())
+  }
+
   async flushAuth(): Promise<ExportedCookie[]> {
     return this.withRecovery(view => view.flushAuth())
   }
@@ -1049,6 +1127,16 @@ class DeferredRemoteView implements ElectronViewHandle {
  */
 const HOST_LOG_MAX_BYTES = 2 * 1024 * 1024
 
+/**
+ * ISO timestamp prefix for host-log lines. This log is the only place a spawn
+ * failure is recorded, and an undated line cannot be lined up with anything else
+ * that happened on the machine — a plugin update replacing the entry script, for
+ * instance — which is precisely the question this log gets asked.
+ */
+function hostStamp(): string {
+  return new Date().toISOString()
+}
+
 function appendHostLog(text: string): void {
   const home = process.env.DSH_HOME
   if (home === undefined || home === '') return
@@ -1056,7 +1144,12 @@ function appendHostLog(text: string): void {
     const dir = join(home, 'logs')
     const file = join(dir, 'dsh-builtin-browser-host.log')
     try {
-      if (statSync(file).size > HOST_LOG_MAX_BYTES) writeFileSync(file, '')
+      if (statSync(file).size > HOST_LOG_MAX_BYTES) {
+        // Discard the old bytes but leave a dated marker: truncating to empty
+        // makes a rotation look like "nothing ever happened", which is how the
+        // history of a crash loop gets silently swallowed.
+        writeFileSync(file, `${hostStamp()} log rotated: previous content exceeded ${String(HOST_LOG_MAX_BYTES)} bytes and was discarded\n`)
+      }
     } catch { /* first write, or unreadable: just append */ }
     mkdirSync(dir, { recursive: true })
     appendFileSync(file, text)

package/src/browser-electron/settings-store.ts

@@ -0,0 +1,198 @@
+/**
+ * Plugin-owned settings document — the switches the browser settings panel
+ * exposes, stored next to the browsing history so both follow the same rules:
+ * they survive the browser process and DSH restarts.
+ *
+ * Every field is optional on disk and falls back to a default, so a hand-edited
+ * or older file never breaks startup; an unreadable file is treated as "all
+ * defaults" rather than an error.
+ * @module dsh-browser/browser-electron/settings-store
+ */
+
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+/** Vision/operation strategy the provider prefers when the model can see. */
+export type VisionStrategy = 'auto' | 'nonVisual'
+
+/** The full settings document, with every field resolved. */
+export interface BrowserSettings {
+  /** Persistent browsing history (visited pages). */
+  readonly history: {
+    readonly enabled: boolean
+    readonly maxEntries: number
+    readonly maxAgeDays: number
+  }
+  /** Login-state retention: cookies and the browser profile. */
+  readonly cookies: {
+    readonly persist: boolean
+  }
+  /** Presentation behaviour. */
+  readonly ui: {
+    /** Auto-expand the side panel once per task, then leave the user alone. */
+    readonly autoExpandOnce: boolean
+    /** Release the browser when its session ends, instead of waiting for a close. */
+    readonly closeWithSession: boolean
+    /** Show the synthetic cursor/click feedback while the agent operates. */
+    readonly virtualCursor: boolean
+  }
+  /** Visual vs non-visual operation strategy. */
+  readonly vision: {
+    readonly strategy: VisionStrategy
+  }
+  /** Whether the agent may read cookies / export login state. */
+  readonly credentials: {
+    readonly allowRead: boolean
+  }
+}
+
+/** Defaults for every switch: the documented out-of-the-box behaviour. */
+export const DEFAULT_SETTINGS: BrowserSettings = {
+  history: { enabled: true, maxEntries: 5_000, maxAgeDays: 90 },
+  cookies: { persist: true },
+  ui: { autoExpandOnce: true, closeWithSession: false, virtualCursor: true },
+  vision: { strategy: 'auto' },
+  credentials: { allowRead: true },
+}
+
+/**
+ * Absolute path of the settings file, beside the browser profile and the
+ * browsing history.
+ * @returns the settings file path.
+ */
+export function settingsPath(): string {
+  const home = process.env.DSH_HOME ?? join(homedir(), '.dsh')
+  return join(home, 'dsh-builtin-browser-host', 'settings.json')
+}
+
+/** Coerce one boolean field, keeping the default when absent or mistyped. */
+function bool(value: unknown, fallback: boolean): boolean {
+  return typeof value === 'boolean' ? value : fallback
+}
+
+/** Coerce one positive-integer field, keeping the default when invalid. */
+function count(value: unknown, fallback: number): number {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback
+}
+
+/** Read one nested section of an unknown document, or an empty object. */
+function section(source: Record<string, unknown>, key: string): Record<string, unknown> {
+  const value = source[key]
+  return typeof value === 'object' && value !== null ? value as Record<string, unknown> : {}
+}
+
+/**
+ * Resolve a raw settings document (already parsed, shape unknown) into the full
+ * document, field by field. Unknown keys are dropped: the file is not a place to
+ * smuggle configuration.
+ * @param raw - the parsed file contents.
+ * @returns the resolved settings.
+ */
+export function resolveSettings(raw: unknown): BrowserSettings {
+  const source = typeof raw === 'object' && raw !== null ? raw as Record<string, unknown> : {}
+  const history = section(source, 'history')
+  const cookies = section(source, 'cookies')
+  const ui = section(source, 'ui')
+  const vision = section(source, 'vision')
+  const credentials = section(source, 'credentials')
+  return {
+    history: {
+      enabled: bool(history.enabled, DEFAULT_SETTINGS.history.enabled),
+      maxEntries: count(history.maxEntries, DEFAULT_SETTINGS.history.maxEntries),
+      maxAgeDays: count(history.maxAgeDays, DEFAULT_SETTINGS.history.maxAgeDays),
+    },
+    cookies: { persist: bool(cookies.persist, DEFAULT_SETTINGS.cookies.persist) },
+    ui: {
+      autoExpandOnce: bool(ui.autoExpandOnce, DEFAULT_SETTINGS.ui.autoExpandOnce),
+      closeWithSession: bool(ui.closeWithSession, DEFAULT_SETTINGS.ui.closeWithSession),
+      virtualCursor: bool(ui.virtualCursor, DEFAULT_SETTINGS.ui.virtualCursor),
+    },
+    vision: { strategy: vision.strategy === 'nonVisual' ? 'nonVisual' : DEFAULT_SETTINGS.vision.strategy },
+    credentials: { allowRead: bool(credentials.allowRead, DEFAULT_SETTINGS.credentials.allowRead) },
+  }
+}
+
+/**
+ * File-backed settings with an in-memory snapshot. Reads re-stat the file so an
+ * edit from another process (or the settings panel writing through a second
+ * code path) is picked up without a restart; writes are atomic enough for a
+ * single-writer plugin and never throw at the caller.
+ */
+export class SettingsStore {
+  private cached: BrowserSettings | undefined
+  /** Last observed mtime, used to invalidate the cache on external edits. */
+  private cachedMtimeMs = -1
+
+  /**
+   * @param file - settings file path (defaults beside the browser profile).
+   */
+  constructor(private readonly file: string = settingsPath()) {}
+
+  /** Path this store reads and writes. */
+  path(): string {
+    return this.file
+  }
+
+  /**
+   * Current settings, re-read when the file changed on disk.
+   * @returns the resolved settings document.
+   */
+  get(): BrowserSettings {
+    let mtimeMs = -1
+    let text: string | undefined
+    try {
+      if (existsSync(this.file)) {
+        mtimeMs = statSync(this.file).mtimeMs
+        text = readFileSync(this.file, 'utf8')
+      }
+    } catch {
+      // Unreadable file: fall through to defaults below.
+      mtimeMs = -1
+      text = undefined
+    }
+    if (this.cached !== undefined && mtimeMs === this.cachedMtimeMs) return this.cached
+    try {
+      this.cached = text === undefined ? DEFAULT_SETTINGS : resolveSettings(JSON.parse(text))
+    } catch {
+      // Malformed JSON: behave as defaults rather than fail startup.
+      this.cached = DEFAULT_SETTINGS
+    }
+    this.cachedMtimeMs = mtimeMs
+    return this.cached
+  }
+
+  /**
+   * Merge a partial patch into the stored document and persist it.
+   * @param patch - the fields to change (unknown keys are ignored).
+   * @returns the settings after the merge.
+   */
+  update(patch: unknown): BrowserSettings {
+    const current = this.get()
+    const merged = resolveSettings(deepMerge(current as unknown as Record<string, unknown>, patch))
+    try {
+      mkdirSync(dirname(this.file), { recursive: true })
+      writeFileSync(this.file, `${JSON.stringify(merged, null, 2)}\n`)
+    } catch {
+      // Keep the merged value in memory even when the write fails.
+    }
+    this.cached = merged
+    this.cachedMtimeMs = Date.now()
+    return merged
+  }
+}
+
+/** One-level-deep merge over the settings sections (patch wins). */
+function deepMerge(base: Record<string, unknown>, patch: unknown): Record<string, unknown> {
+  if (typeof patch !== 'object' || patch === null) return base
+  const result: Record<string, unknown> = { ...base }
+  for (const [key, value] of Object.entries(patch as Record<string, unknown>)) {
+    const existing = result[key]
+    if (typeof value === 'object' && value !== null && typeof existing === 'object' && existing !== null) {
+      result[key] = { ...existing as Record<string, unknown>, ...value as Record<string, unknown> }
+    } else {
+      result[key] = value
+    }
+  }
+  return result
+}

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

@@ -0,0 +1,82 @@
+/**
+ * Synthetic pointer feedback for a human watching the tab: an overlay drawn
+ * INSIDE the page, never the real system pointer. Its presence is the "the agent
+ * has taken over this tab" signal, so it also covers DOM-level operations that
+ * move no pointer at all.
+ *
+ * Implementation notes that matter:
+ * - The overlay is `position: fixed` and positioned from viewport coordinates,
+ *   which is exactly what the element locator already computes and what
+ *   `Input.dispatchMouseEvent` consumes.
+ * - All styling is inline and the ripple uses the Web Animations API: a
+ *   `<style>` element would be subject to the page's `style-src` CSP, an
+ *   injected script is not. Injected page feedback must never be silently
+ *   dropped by a strict CSP.
+ * - Every call is best-effort: feedback is never allowed to fail an operation.
+ * @module dsh-browser/browser-electron/virtual-cursor
+ */
+
+/** What the pointer is doing at the reported point. */
+export type CursorAction = 'move' | 'click'
+
+/** Element id of the overlay root, stable so repeat calls update one node. */
+const CURSOR_ID = '__dsh_agent_cursor__'
+
+/**
+ * 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.
+ * @returns a self-contained expression that evaluates to `true`.
+ */
+export function cursorScript(x: number, y: number, action: CursorAction): string {
+  return `(() => {
+  const id = ${JSON.stringify(CURSOR_ID)}
+  let root = document.getElementById(id)
+  if (!root) {
+    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'
+    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
+    ;(document.body || document.documentElement).appendChild(root)
+  }
+  root.style.transform = 'translate(${x}px, ${y}px)'
+  ${action === 'click' ? `const ripple = root.lastElementChild
+  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' },
+    )
+  }` : ''}
+  return true
+})()`
+}
+
+/**
+ * Draw (or move) the pointer overlay on one view's page.
+ *
+ * Fire-and-forget: a page that is mid-navigation, cross-origin-blocked, or
+ * otherwise unable to answer must not turn a successful operation into a
+ * failure, and the navigation that just committed may still be replacing the
+ * document this call would have painted into.
+ * @param handle - the view to paint into.
+ * @param x - viewport x in CSS pixels.
+ * @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).
+ */
+export function paintCursor<TView>(
+  handle: TView,
+  x: number,
+  y: number,
+  action: CursorAction,
+  evaluate: (handle: TView, expression: string) => Promise<unknown>,
+): void {
+  if (!Number.isFinite(x) || !Number.isFinite(y)) return
+  void evaluate(handle, cursorScript(Math.round(x), Math.round(y), action)).catch(() => {})
+}

package/src/index.ts

@@ -4,11 +4,29 @@
  *   - `dsh-builtin-browser/browser`          -> the ctx.browser seam (Service)
  *   - `dsh-builtin-browser/browser-electron` -> the Electron CDP provider
  *   - `dsh-builtin-browser/tool-browser`     -> the model-facing browser_* tools
- * This root entry only re-exports for programmatic use; the loader rows are
- * the composition surface.
+ * The capability itself is composed by those rows; this root entry exists for
+ * programmatic imports AND because the host's client-module scan identifies a
+ * package's browser half through a loader row whose specifier resolves to the
+ * PACKAGE ROOT. A row named after a subpath (`dsh-builtin-browser/browser`) is
+ * not a package specifier and is skipped by design, which is why the patch also
+ * registers a row under the bare package name — see cordis.patch.yml.
  * @module dsh-builtin-browser
  */
 
+/** Plugin identity for the root row (the composition surface is the subpath rows). */
+export const name = 'dsh-builtin-browser'
+
+/**
+ * Inert application for the root row: the browser seam, the Electron provider and
+ * the tools are mounted by the subpath rows, so this one only exists to give the
+ * package a loader row named after the package itself. Without it the host's
+ * client scan finds no row to resolve `dsh.client` from, and the settings panel
+ * never reaches the browser (the plugin works, its client half is invisible).
+ */
+export function apply(): void {
+  // Intentionally empty: see the module comment above.
+}
+
 export { BrowserError } from './browser/types.js'
 export type {
   BrowserA11yNode,

package/src/tool-browser/index.ts

@@ -105,7 +105,12 @@ function taskKey(exec: { agent?: { id?: string } } | undefined): string {
  */
 async function ensureSession(browser: NonNullable<Context['browser']>, state: ToolBrowserState, key: string, agent?: ExecAgent): Promise<BrowserSessionId> {
   const existing = state.sessionsByTask.get(key)
-  if (existing !== undefined) return existing
+  if (existing !== undefined) {
+    // The human closing a browser window ends that session, so a cached id can
+    // be stale: never hand a dead session back to a tool call.
+    if (browser.exists(existing)) return existing
+    state.sessionsByTask.delete(key)
+  }
   const pending = state.pendingOpens.get(key)
   if (pending !== undefined) return pending
   // The task key rides along as the session label so the window title shows
@@ -1327,6 +1332,71 @@ export function apply(ctx: Context, config: Config = {}): void {
     },
   }))
 
+  ctx.tools.register(defineTool({
+    name: 'browser_visited',
+    description: 'List pages the shared browser has visited, newest first, from the PERSISTENT browsing history: it survives closing the browser and restarting DSH, so it is how you (or the human) find a page again afterwards. Reopen one by passing its url to browser_open. Not to be confused with browser_history, which is only the current session\'s operation log (navigate/click/type) and disappears with the session.',
+    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).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          count: { type: 'number', required: true },
+          entries: {
+            type: 'array',
+            required: true,
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                at: { type: 'number', required: true },
+                url: { type: 'string', required: true },
+                title: { type: 'string' },
+                session: { type: 'string' },
+              },
+            },
+          },
+        },
+      },
+      render: (_args, value) => {
+        const entries = value.entries as Array<{ at: number; url: string; title?: string; session?: string }>
+        if (entries.length === 0) {
+          return [{ type: 'text', text: '(no recorded visits — nothing has been browsed yet, or history recording is turned off in settings)' }]
+        }
+        return [{
+          type: 'text',
+          text: entries.map(entry => {
+            const when = new Date(entry.at).toISOString().replace('T', ' ').slice(0, 19)
+            const title = entry.title !== undefined ? `${entry.title} — ` : ''
+            return `${when}  ${title}${entry.url}${entry.session !== undefined ? `  [${entry.session}]` : ''}`
+          }).join('\n'),
+        }]
+      },
+    },
+    timeoutMs,
+    isConcurrencySafe: () => true,
+    async execute(args, _exec) {
+      const browser = ctx.get('browser')
+      if (browser === undefined) throw new Error('tool-browser: browser service unavailable')
+      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 } : {} })
+      return {
+        count: entries.length,
+        entries: entries.map(entry => ({
+          at: entry.at,
+          url: entry.url,
+          ...entry.title !== undefined ? { title: entry.title } : {},
+          ...entry.session !== undefined ? { session: entry.session } : {},
+        })),
+      }
+    },
+  }))
+
   ctx.tools.register(defineTool({
     name: 'browser_replay',
     description: 'Replay one recorded browser operation by its history sequence number (from browser_history). Navigate/click/type are re-issued against the current page; execute re-runs its script. The replayed step is appended to history as a new entry.',