dsh-builtin-browser 0.1.23 → 0.3.0

package/desktop-bridge/plugin-browser-bridge.js

@@ -0,0 +1,385 @@
+/**
+ * Plugin browser bridge (desktop side).
+ *
+ * WHY THIS EXISTS
+ * The `dsh-builtin-browser` plugin runs inside the Node-mode desktop host, where
+ * no Electron API exists — so today it spawns its own Electron window, completely
+ * parallel to the desktop shell. To make the sidebar carry the agent's page
+ * instead (one page, human and agent on it), somebody with Electron access has to
+ * own the view. That somebody is this process.
+ *
+ * WHAT IT DOES
+ * Exposes the desktop's webview guests (the sidebar browser's pages) over a
+ * token-authenticated loopback socket, and forwards CDP to them through
+ * `webContents.debugger`. It deliberately does NOT create windows or views yet:
+ * the first question is whether a sidebar guest can be driven from outside at
+ * all, and that is what `list` + `cdp` answer.
+ *
+ * HOW IT IS STARTED
+ * `lib/main.js` imports this module once the app is ready (see the bridge import
+ * appended before its `export {}`), and the endpoint is published to
+ * `$DSH_HOME/dsh-builtin-browser-bridge.json` so the plugin can find it without
+ * any user configuration.
+ */
+import { createServer } from 'node:net'
+import { randomBytes } from 'node:crypto'
+import { writeFileSync, mkdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { app, webContents } from 'electron'
+
+/** Absolute path of the endpoint file the plugin reads. */
+function endpointFile() {
+  const home = process.env.DSH_HOME ?? ''
+  return join(home, 'dsh-builtin-browser-bridge.json')
+}
+
+/** One CDP command against a guest, serialized per guest. */
+const queues = new Map()
+
+function guestById(id) {
+  for (const contents of webContents.getAllWebContents()) {
+    if (contents.id === id) return contents
+  }
+  return undefined
+}
+
+/** Describe one candidate guest. */
+function describe(contents) {
+  let url = ''
+  let title = ''
+  try { url = contents.getURL() } catch { /* destroyed */ }
+  try { title = contents.getTitle() } catch { /* destroyed */ }
+  return {
+    id: contents.id,
+    type: contents.getType(),
+    url,
+    title,
+    destroyed: contents.isDestroyed(),
+  }
+}
+
+/**
+ * Send one CDP command to a guest, attaching its debugger on first use.
+ * Attaching is per-webContents and idempotent; a destroyed guest drops the
+ * attachment so a later guest with a recycled id is not mistaken for this one.
+ */
+async function sendCdp(id, method, params) {
+  const guest = guestById(id)
+  if (guest === undefined || guest.isDestroyed()) throw new Error(`guest ${id} is not available`)
+  const previous = queues.get(id) ?? Promise.resolve()
+  const next = previous.then(async () => {
+    const current = guestById(id)
+    if (current === undefined || current.isDestroyed()) throw new Error(`guest ${id} is not available`)
+    if (!current.debugger.isAttached()) current.debugger.attach('1.3')
+    return await current.debugger.sendCommand(method, params ?? {})
+  })
+  // Keep the chain alive on failure so one bad command does not wedge the guest.
+  queues.set(id, next.catch(() => undefined))
+  return await next
+}
+
+/** Handle one JSON request line; every answer is a JSON line too. */
+async function handle(request) {
+  const op = String(request?.op ?? '')
+  if (op === 'list') {
+    const all = webContents.getAllWebContents().map(describe)
+    return { ok: true, guests: all, sidebar: all.filter(g => g.type === 'webview') }
+  }
+  if (op === 'cdp') {
+    const id = Number(request.id)
+    if (!Number.isFinite(id)) throw new Error('cdp requires a numeric id')
+    const result = await sendCdp(id, String(request.method ?? ''), request.params)
+    return { ok: true, result }
+  }
+  if (op === 'ensureSidebar') {
+    const url = request.url === undefined ? '' : String(request.url)
+    // Materialize a sidebar guest, optionally navigating it.
+    //
+    // The sidebar browser creates its guest lazily: an un-navigated sidebar is
+    // only an address bar and owns no webContents at all, so "there is no guest"
+    // is the normal state rather than a failure. When one already exists this is
+    // a no-op; otherwise the shell's own UI is driven to open the right sidebar
+    // and submit an address — the same thing a human would do, and the only
+    // supported way to make the sidebar own a page.
+    const existing = webContents.getAllWebContents().filter(contents => contents.getType() === 'webview')
+    if (existing.length > 0) {
+      const first = existing[0]
+      if (request.url !== undefined && String(request.url) !== '') {
+        await sendCdp(first.id, 'Page.navigate', { url: String(request.url) })
+      }
+      return { ok: true, created: false, id: first.id }
+    }
+    const shell = webContents.getAllWebContents().find(contents => contents.getType() === 'window')
+    if (shell === undefined) throw new Error('no shell window to drive')
+    // 1. Open the sidebar and put the caret in its address field IF that field is
+    //    reachable. It is not always: the sidebar may show another panel, or the
+    //    browser tab may be present but not active, in which case no address input
+    //    exists in the document at all. That must not be fatal — the restore route
+    //    below needs no address bar, and treating "no input" as a hard error is
+    //    exactly what made the first call after a restart fail.
+    const prepared = await sendCdp(shell.id, 'Runtime.evaluate', {
+      expression: shellPrepareSidebar(),
+      returnByValue: true,
+    })
+    const verdict = String(prepared?.result?.value ?? '')
+    // 2. Materialize a guest. Two routes, cheapest first:
+    //    a. the sidebar's own "restore last page" affordance — it navigates
+    //       without depending on how the address field handles focus or input;
+    //    b. otherwise type into the address field and submit with REAL key input
+    //       (synthetic events do not move React's controlled input, and the field
+    //       also loses focus to re-renders, so both halves are needed).
+    const restored = await sendCdp(shell.id, 'Runtime.evaluate', {
+      expression: `(() => {
+        const nodes = Array.from(document.querySelectorAll('button,a,[role=button],div[role=link]'));
+        const hit = nodes.find(n => /恢复页面|恢复上次|上次打开/.test((n.textContent || '').trim()));
+        if (hit === undefined) return 'NO_RESTORE';
+        hit.click();
+        return 'RESTORED';
+      })()`,
+      returnByValue: true,
+    })
+    if (restored?.result?.value !== 'RESTORED') {
+      if (url !== '') {
+        // Set the value the way React accepts it, then submit with real input.
+        await sendCdp(shell.id, 'Runtime.evaluate', {
+          expression: `(() => {
+            const inputs = Array.from(document.querySelectorAll('input')).filter(i => /HTTP|地址|url/i.test((i.placeholder || '') + (i.getAttribute('aria-label') || '')));
+            if (inputs.length === 0) return 'NO_ADDRESS_BAR';
+            const input = inputs[inputs.length - 1];
+            const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value').set;
+            setter.call(input, ${JSON.stringify(String(request.url ?? ''))});
+            input.dispatchEvent(new Event('input', { bubbles: true }));
+            input.focus();
+            return 'TYPED';
+          })()`,
+          returnByValue: true,
+        })
+        for (const type of ['keyDown', 'keyUp']) {
+          await sendCdp(shell.id, 'Input.dispatchKeyEvent', {
+            type,
+            key: 'Enter',
+            code: 'Enter',
+            windowsVirtualKeyCode: 13,
+            nativeVirtualKeyCode: 13,
+          })
+        }
+      }
+    }
+    // The guest attaches asynchronously once the renderer creates the webview.
+    for (let attempt = 0; attempt < 24; attempt++) {
+      await new Promise(resolve => setTimeout(resolve, 500))
+      const created = webContents.getAllWebContents().filter(contents => contents.getType() === 'webview')
+      if (created.length > 0) {
+        // Now that a guest exists, navigation is a plain CDP call: no UI involved.
+        if (url !== '') {
+          await sendCdp(created[0].id, 'Page.navigate', { url }).catch(() => undefined)
+        }
+        return { ok: true, created: true, id: created[0].id, via: restored?.result?.value === 'RESTORED' ? 'restore' : 'address' }
+      }
+    }
+    throw new Error(`the sidebar did not create a browser guest (prepare=${String(verdict)}, restore=${String(restored?.result?.value)})`)
+  }
+  if (op === 'ensureTabs') {
+    // Grow the sidebar's browser tab strip to `count` tabs and report every guest.
+    //
+    // Tabs are the renderer's, so this cannot create them directly — it drives the
+    // sidebar's own "new tab" control, the same affordance a human uses, and then
+    // reports the guest ids. Whatever already exists is reused, so repeated calls
+    // are cheap and a human-opened tab is never orphaned.
+    const want = Math.max(1, Math.min(8, Number(request.count ?? 1)))
+    const shell = webContents.getAllWebContents().find(contents => contents.getType() === 'window')
+    if (shell === undefined) throw new Error('no shell window to drive')
+    let lastVerdict = ''
+    for (let attempt = 0; attempt < 30; attempt++) {
+      const guests = webContents.getAllWebContents().filter(contents => contents.getType() === 'webview')
+      if (guests.length >= want) return { ok: true, ids: guests.map(contents => contents.id), verdict: lastVerdict }
+      const clicked = await sendCdp(shell.id, 'Runtime.evaluate', {
+        expression: `(() => {
+          const nodes = Array.from(document.querySelectorAll('button,[role=button]'));
+          const hit = nodes.find(b => /新标签页|新建标签|new tab/i.test((b.getAttribute('aria-label') || '') + (b.textContent || '') + (b.getAttribute('title') || '')));
+          if (hit === undefined) return 'NO_NEW_TAB_CONTROL';
+          hit.click();
+          return 'CLICKED';
+        })()`,
+        returnByValue: true,
+      })
+      lastVerdict = String(clicked?.result?.value ?? '')
+      if (lastVerdict === 'NO_NEW_TAB_CONTROL') {
+        throw new Error('the sidebar exposes no new-tab control (is the browser tab open?)')
+      }
+      await new Promise(resolve => setTimeout(resolve, 600))
+    }
+    throw new Error(`the sidebar stopped at fewer than ${want} tabs`)
+  }
+  if (op === 'closeSidebarBrowser') {
+    // Release the sidebar's browser pages by closing the tabs that host them.
+    //
+    // This is the desktop equivalent of "close the browser window": the guests are
+    // destroyed, so that agent's session ends and its next use starts a fresh page —
+    // while cookies and history live in the partition and on disk, and therefore
+    // survive (requirements §3).
+    //
+    // `titles` narrows the release to specific pages. It matters as soon as more
+    // than one session is running: each one owns its own tab (requirements §4), and
+    // ending one session must not tear down another's page. With no titles given the
+    // call means "release everything", which is only appropriate when the caller
+    // knows it owns them all.
+    const wanted = Array.isArray(request.titles) ? request.titles.map(title => String(title).slice(0, 24)).filter(title => title !== '') : undefined
+    const guests = webContents.getAllWebContents().filter(contents => contents.getType() === 'webview')
+    const titles = []
+    for (const guest of guests) {
+      try {
+        if (guest.isDestroyed()) continue
+        const title = guest.getTitle()
+        // With a filter, only the guest we intend to close contributes its title —
+        // otherwise a tab belonging to another session could match by accident.
+        if (wanted !== undefined && !wanted.some(w => title.startsWith(w))) continue
+        titles.push(title)
+      } catch { /* gone mid-read */ }
+    }
+    if (guests.length === 0) return { ok: true, closed: 0 }
+    const shell = webContents.getAllWebContents().find(contents => contents.getType() === 'window')
+    if (shell === undefined) throw new Error('no shell window to drive')
+    if (titles.length === 0 && wanted !== undefined) return { ok: true, closed: 0 }
+    const clicked = await sendCdp(shell.id, 'Runtime.evaluate', {
+      expression: `(() => {
+        const wanted = ${JSON.stringify(titles.map(title => title.slice(0, 24)))};
+        let closed = 0;
+        for (const tab of Array.from(document.querySelectorAll('[role=tab]'))) {
+          const label = (tab.textContent || '').trim();
+          if (!wanted.some(w => label.startsWith(w))) continue;
+          const own = Array.from(tab.querySelectorAll('button')).find(b => /关闭|close/i.test((b.getAttribute('aria-label') || '') + (b.getAttribute('title') || '')));
+          const sibling = Array.from(tab.parentElement ? tab.parentElement.querySelectorAll('button') : []).find(b => /关闭|close/i.test((b.getAttribute('aria-label') || '') + (b.getAttribute('title') || '')));
+          const button = own ?? sibling;
+          if (button !== undefined) { button.click(); closed += 1; }
+        }
+        return closed;
+      })()`,
+      returnByValue: true,
+    })
+    return { ok: true, closed: Number(clicked?.result?.value ?? 0) }
+  }
+  if (op === 'collapseSidebar') {
+    // Fold the sidebar away so the agent works without occupying the screen. The
+    // guest keeps running — collapsing is presentation, exactly as §3 asks.
+    const shell = webContents.getAllWebContents().find(contents => contents.getType() === 'window')
+    if (shell === undefined) throw new Error('no shell window to drive')
+    const folded = await sendCdp(shell.id, 'Runtime.evaluate', {
+      expression: `(() => {
+        const button = Array.from(document.querySelectorAll('button')).find(b => /收起右侧边栏/.test((b.getAttribute('aria-label') || '') + (b.textContent || '')));
+        if (button === undefined) return 'NOT_OPEN';
+        button.click();
+        return 'COLLAPSED';
+      })()`,
+      returnByValue: true,
+    })
+    return { ok: true, result: folded?.result?.value }
+  }
+  throw new Error(`unknown op ${JSON.stringify(op)}`)
+}
+
+/**
+ * In-page script that opens the right sidebar and focuses its address field.
+ *
+ * Only preparation happens here; the address itself is typed with real input
+ * (see `ensureSidebar`), because a controlled React input ignores text assigned
+ * through synthetic events.
+ * @returns a self-contained expression evaluating to a short verdict string.
+ */
+function shellPrepareSidebar() {
+  return `(() => {
+    const labelOf = el => ((el.getAttribute && el.getAttribute('aria-label')) || el.textContent || '').trim();
+    let opened = false;
+    for (const button of Array.from(document.querySelectorAll('button'))) {
+      if (/打开右侧边栏|右侧边栏/.test(labelOf(button))) { button.click(); opened = true; break; }
+    }
+    const inputs = Array.from(document.querySelectorAll('input')).filter(i => /HTTP|地址|url/i.test((i.placeholder || '') + (i.getAttribute('aria-label') || '')));
+    if (inputs.length === 0) return 'NO_ADDRESS_BAR:' + JSON.stringify(Array.from(document.querySelectorAll('input')).map(i => i.placeholder).slice(0, 6));
+    inputs[inputs.length - 1].focus();
+    return opened ? 'OPENED_AND_FOCUSED' : 'FOCUSED';
+  })()`
+}
+
+/**
+ * Publish the endpoint, and keep it published.
+ *
+ * A single write at startup is not enough: two shells can overlap during a
+ * restart (the outgoing one may write LAST, leaving the file pointing at a dead
+ * pid), and a reader that trusts it then fails with ECONNREFUSED for reasons
+ * that have nothing to do with the plugin. So the file is rewritten periodically
+ * by the process that actually owns the listener, and readers are told the pid
+ * so they can verify liveness themselves.
+ */
+function publishEndpoint(port, token) {
+  const payload = {
+    port,
+    token,
+    pid: process.pid,
+    startedAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  }
+  try {
+    const file = endpointFile()
+    mkdirSync(join(file, '..'), { recursive: true })
+    writeFileSync(file, JSON.stringify(payload, null, 2) + '\n')
+    return true
+  } catch (error) {
+    console.error('[dsh-browser-bridge] could not publish the endpoint file:', error)
+    return false
+  }
+}
+
+/** Start the bridge: loopback listener + published endpoint file + token. */
+export function start() {
+  const token = randomBytes(24).toString('hex')
+  const server = createServer(socket => {
+    let buffer = ''
+    let authed = false
+    socket.on('data', chunk => {
+      buffer += chunk.toString('utf8')
+      let newline = buffer.indexOf('\n')
+      while (newline !== -1) {
+        const line = buffer.slice(0, newline).trim()
+        buffer = buffer.slice(newline + 1)
+        newline = buffer.indexOf('\n')
+        if (line === '') continue
+        let request
+        try { request = JSON.parse(line) } catch { socket.write(JSON.stringify({ ok: false, error: 'bad json' }) + '\n'); continue }
+        if (!authed) {
+          if (request.token !== token) { socket.write(JSON.stringify({ ok: false, error: 'bad token' }) + '\n'); socket.destroy(); return }
+          authed = true
+          // The authenticating message is NOT a command: a client that sends the
+          // token on its own line would otherwise be answered `unknown op ""`.
+          // (A client may also put the token on its first real request; both work.)
+          if (typeof request.op !== 'string' || request.op === '') continue
+        }
+        void handle(request)
+          .then(answer => socket.write(JSON.stringify(answer) + '\n'))
+          .catch(error => socket.write(JSON.stringify({ ok: false, error: String(error?.message ?? error) }) + '\n'))
+      }
+    })
+    socket.on('error', () => { /* client went away */ })
+  })
+  server.on('error', error => { console.error('[dsh-browser-bridge] listen failed:', error) })
+  // Loopback only, port chosen by the OS: the endpoint file is the discovery
+  // mechanism, so a fixed port would only add collisions.
+  server.listen(0, '127.0.0.1', () => {
+    const address = server.address()
+    const port = typeof address === 'object' && address !== null ? address.port : 0
+    if (publishEndpoint(port, token)) {
+      console.log(`[dsh-browser-bridge] listening on 127.0.0.1:${port} (pid ${process.pid})`)
+    }
+  })
+  // Re-publish: a reader must never be handed an endpoint owned by a dead shell.
+  const keepalive = setInterval(() => {
+    const address = server.address()
+    const port = typeof address === 'object' && address !== null ? address.port : 0
+    if (port !== 0) publishEndpoint(port, token)
+  }, 15_000)
+  keepalive.unref?.()
+  app.on('will-quit', () => {
+    clearInterval(keepalive)
+    try { server.close() } catch { /* already closed */ }
+  })
+  return server
+}

package/docs/README.md

@@ -6,7 +6,7 @@
 | --- | --- |
 | 了解插件为什么存在、与无头方案的区别 | [为什么做共享真实浏览器](why-browser.md) |
 | 安装、配置、日常使用与常见问题 | [用户指南](user-guide.md) |
-| 全部 33 个工具的参数、输出与示例 | [工具参考](tool-reference.md) |
+| 全部 34 个工具的参数、输出与示例 | [工具参考](tool-reference.md) |
 | 了解 seam / provider / 工具三层与自托管实现 | [架构说明](architecture.md) |
 | 回到项目首页 | [README](../README.md) |
 

package/docs/architecture.md

@@ -37,7 +37,7 @@ agent (browser_* 工具)
 
 ### 工具层(`src/tool-browser/`)
 
-33 个 `browser_*` 工具,按**调用方任务**(`exec.agent.id`)维护独立浏览器会话:
+34 个 `browser_*` 工具,按**调用方任务**(`exec.agent.id`)维护独立浏览器会话:
 
 - 会话缓存 `sessionsByTask`:同一任务复用同一会话,并发首开去重;
 - `browser_reset_session` 关闭本任务会话并遗忘映射(即使 close 抛错也清除,下次调用重建);

package/docs/tool-reference.md

@@ -1,6 +1,6 @@
 # 工具参考
 
-全部 33 个 `browser_*` 工具。守卫列:✅ 表示该动作受 `browser_restrict` 白名单约束;只读工具永不拦截。
+全部 34 个 `browser_*` 工具。守卫列:✅ 表示该动作受 `browser_restrict` 白名单约束;只读工具永不拦截。
 
 ## 页面与导航
 
@@ -49,6 +49,7 @@
 | 工具 | 参数 | 输出 | 守卫 | 说明 |
 | --- | --- | --- | --- | --- |
 | `browser_history` | – | `{ entries[] }` | – | 操作日志(最新在后),含 seq/action/ok/params/result/error |
+| `browser_visited` | `limit`(默认 30,上限 200), `domain`(主机名包含匹配) | `{ count, entries[] }` | – | **持久化浏览历史**(访问过的页面,最新在前):与 cookie 同址落盘(`$DSH_HOME/dsh-builtin-browser-host/history.jsonl`),关闭浏览器与重启 DSH 后仍在;上限 5000 条或 90 天。重开某条用 `browser_open`;与 `browser_history`(会话内操作日志,随会话消失)是两件事;可在设置里关闭记录 |
 | `browser_replay` | `seq`(必填) | `{ replayed }` | ✅ | 按序号回放某一步(navigate/execute/click/type/scroll/key) |
 | `browser_download` | `url`(必填), `savePath`(必填) | `{ path }` | ✅ | 带会话 cookie 下载到本地(仅 http(s);`savePath` 必须为绝对路径且位于 `downloadDir` 内——默认系统下载目录,自动识别 `Downloads`/`下载`/`下載` 与 `XDG_DOWNLOAD_DIR`;不覆盖已有文件;上限 256MB,受 CORS 约束;由子进程直接落盘) |
 

package/lib/browser/runtime.d.ts

@@ -8,7 +8,7 @@
  */
 import { Context, Service } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
-import type { BrowserA11yRequest, BrowserA11yResult, BrowserCheckRequest, BrowserClearRequest, BrowserClickRequest, BrowserContentRequest, BrowserContentResult, BrowserDownloadRequest, BrowserElementTarget, BrowserExecuteRequest, BrowserExecuteResult, BrowserFillRequest, BrowserFillResult, BrowserGetValueRequest, BrowserGetValueResult, BrowserHistoryEntry, BrowserNavigateRequest, BrowserOpenRequest, BrowserProvider, BrowserScrapeRequest, BrowserScrapeResult, BrowserScreenshotRequest, BrowserScreenshotResult, BrowserSelectRequest, BrowserSelectResult, BrowserSessionId, BrowserSetValueRequest, BrowserSetValueResult, BrowserSnapshotResult, BrowserTab, BrowserTypeRequest, BrowserWaitRequest, BrowserWaitResult, BrowserScrollRequest, BrowserKeyRequest, BrowserChallenge, ExportedCookie } from './types.js';
+import type { BrowserA11yRequest, BrowserA11yResult, BrowserCheckRequest, BrowserClearRequest, BrowserClickRequest, BrowserContentRequest, BrowserContentResult, BrowserDownloadRequest, BrowserElementTarget, BrowserExecuteRequest, BrowserExecuteResult, BrowserFillRequest, BrowserFillResult, BrowserGetValueRequest, BrowserGetValueResult, BrowserHistoryEntry, BrowserNavigateRequest, BrowserOpenRequest, BrowserProvider, BrowserScrapeRequest, BrowserScrapeResult, BrowserScreenshotRequest, BrowserScreenshotResult, BrowserSelectRequest, BrowserSelectResult, BrowserSessionId, BrowserSetValueRequest, BrowserSetValueResult, BrowserSnapshotResult, BrowserTab, BrowserTypeRequest, BrowserWaitRequest, BrowserWaitResult, BrowserScrollRequest, BrowserKeyRequest, BrowserChallenge, ExportedCookie, VisitedPage } from './types.js';
 export { BrowserError, } from './types.js';
 export type { BrowserA11yNode, BrowserA11yRequest, BrowserA11yResult, BrowserChallenge, BrowserCheckRequest, BrowserClearRequest, BrowserClickRequest, BrowserContentFormat, BrowserElementTarget, BrowserGetValueRequest, BrowserGetValueResult, BrowserScrapeField, BrowserScrapeRequest, BrowserScrapeResult, BrowserSelectRequest, BrowserSelectResult, BrowserSetValueRequest, BrowserSetValueResult, BrowserWaitRequest, BrowserWaitResult, BrowserScrollRequest, BrowserKeyRequest, BrowserContentRequest, BrowserContentResult, BrowserDownloadRequest, BrowserExecuteRequest, BrowserExecuteResult, BrowserFillField, BrowserFillRequest, BrowserFillResult, BrowserHistoryEntry, BrowserNavigateRequest, BrowserOpenRequest, BrowserProvider, BrowserScreenshotRequest, BrowserScreenshotResult, BrowserSessionId, BrowserSnapshotElement, BrowserSnapshotResult, BrowserTab, BrowserTypeRequest, ExportedCookie, } from './types.js';
 declare module '@deepseek-ai/cordis' {
@@ -118,6 +118,23 @@ export declare class BrowserRuntime extends Service {
     detectChallenge(session: BrowserSessionId, signal?: AbortSignal): Promise<BrowserChallenge>;
     /** Return the session's chronological operation log through the provider. */
     history(session: BrowserSessionId): Promise<readonly BrowserHistoryEntry[]>;
+    /**
+     * Persisted visits, newest first — the record that outlives the browser
+     * process, as opposed to {@link history}'s session-scoped operation log.
+     * @param options - result cap and an optional hostname filter.
+     * @returns the retained visits (empty when history recording is disabled).
+     */
+    visited(options?: {
+        readonly limit?: number;
+        readonly domain?: string;
+    }): readonly VisitedPage[];
+    /**
+     * Whether a session is still live. Sessions can end outside the tool layer
+     * (the human closed its window), so a cached id must be re-checked before
+     * reuse; a provider that does not implement the check counts as live.
+     * @param session - the session id to test.
+     */
+    exists(session: BrowserSessionId): boolean;
     /** Replay one recorded operation by sequence number through the provider. */
     replay(session: BrowserSessionId, seq: number): Promise<void>;
     /** Download a URL to a local file through the provider. */

package/lib/browser/runtime.js

@@ -202,6 +202,25 @@ export class BrowserRuntime extends Service {
     async history(session) {
         return this.resolveProvider().history(session);
     }
+    /**
+     * Persisted visits, newest first — the record that outlives the browser
+     * process, as opposed to {@link history}'s session-scoped operation log.
+     * @param options - result cap and an optional hostname filter.
+     * @returns the retained visits (empty when history recording is disabled).
+     */
+    visited(options) {
+        return this.resolveProvider().visited(options);
+    }
+    /**
+     * Whether a session is still live. Sessions can end outside the tool layer
+     * (the human closed its window), so a cached id must be re-checked before
+     * reuse; a provider that does not implement the check counts as live.
+     * @param session - the session id to test.
+     */
+    exists(session) {
+        const provider = this.resolveProvider();
+        return provider.exists === undefined ? true : provider.exists(session);
+    }
     /** Replay one recorded operation by sequence number through the provider. */
     async replay(session, seq) {
         return this.resolveProvider().replay(session, seq);

package/lib/browser/types.d.ts

@@ -544,11 +544,44 @@ export interface BrowserProvider {
     restoreAuth(session: BrowserSessionId, cookies: readonly ExportedCookie[]): Promise<number>;
     /** Return the session's chronological operation log. */
     history(session: BrowserSessionId): Promise<readonly BrowserHistoryEntry[]>;
+    /**
+     * Persisted visits, newest first: what survives the browser process, so a
+     * human or an Agent can find a page again after the interface was closed.
+     * @param options - result cap and an optional hostname filter.
+     * @returns the retained visits (empty when history is disabled).
+     */
+    visited(options?: {
+        readonly limit?: number;
+        readonly domain?: string;
+    }): readonly VisitedPage[];
+    /**
+     * Optional: whether a session is still live. A session can end outside the
+     * tool layer — the human closed the browser window — so a cached id must be
+     * checked before it is reused. Providers that never end a session on their own
+     * can omit this, and callers treat absence as "still live".
+     * @param session - the session id to test.
+     */
+    exists?(session: BrowserSessionId): boolean;
     /** Replay one recorded operation by sequence number. */
     replay(session: BrowserSessionId, seq: number): Promise<void>;
     /** Close the session and destroy its backing surface. Idempotent. */
     close(session: BrowserSessionId): Promise<void>;
 }
+/**
+ * One visited page in the persistent browsing history — the durable record that
+ * outlives sessions, unlike {@link BrowserHistoryEntry}, which is a
+ * session-scoped operation log (navigate/click/type/…).
+ */
+export interface VisitedPage {
+    /** Epoch milliseconds when the visit was recorded. */
+    readonly at: number;
+    /** Absolute URL of the visited document. */
+    readonly url: string;
+    /** Document title at visit time, when the page exposed one. */
+    readonly title?: string;
+    /** Session/task label that drove the visit, when the provider knows it. */
+    readonly session?: string;
+}
 /** One recorded browser operation, in chronological order (seq 1, 2, 3…). */
 export interface BrowserHistoryEntry {
     /** Monotonic sequence number within the session. */

package/lib/browser-electron/bridge-connection.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Transport for the desktop shell's browser bridge: one long-lived connection to a
+ * loopback TCP service.
+ *
+ * WHY THIS IS ITS OWN MODULE
+ * The bridge used to be reached with a fresh connection per request, which measured
+ * at ~25ms per call (TCP handshake + token exchange) against ~0.2ms when the socket
+ * is reused. A single browser action issues several CDP commands, so that cost was
+ * multiplied on every tool call — the difference between a snappy agent and a
+ * visibly sluggish one. Reuse is therefore a property of the transport, and keeping
+ * it here means the view host above does not have to think about sockets at all.
+ *
+ * PROTOCOL
+ * The first line on a connection carries the token; the service marks the socket
+ * authenticated and ignores that line as a command. Requests and answers are then
+ * newline-delimited JSON, one answer per request, in order.
+ *
+ * @module dsh-browser/browser-electron/bridge-connection
+ */
+/** Where the shell publishes its bridge endpoint. */
+export interface BridgeEndpoint {
+    readonly port: number;
+    readonly token: string;
+    readonly pid: number;
+    readonly updatedAt?: string;
+}
+/**
+ * A reusable connection to the bridge.
+ *
+ * Requests are serialised by construction: one socket, one in-flight request at a
+ * time, answered in order. A broken socket is discarded so the next call dials
+ * again — a dead connection must never become a dead plugin.
+ */
+export declare class BridgeConnection {
+    private readonly endpoint;
+    private socket;
+    private buffer;
+    private readonly queue;
+    /**
+     * @param endpoint - the shell's published bridge endpoint.
+     */
+    constructor(endpoint: BridgeEndpoint);
+    /**
+     * Send one request, reusing the socket if it is still healthy.
+     * @param request - the request body (the token is added here).
+     * @param timeoutMs - how long to wait for the answer before dropping the socket.
+     * @returns the bridge's answer.
+     */
+    call(request: Record<string, unknown>, timeoutMs?: number): Promise<Record<string, unknown>>;
+    /** Close the socket and fail anything still waiting on it. */
+    close(): void;
+    /** The live socket, connecting and authenticating it on first use. */
+    private ensureSocket;
+    /** Resolve queued requests in order as answers arrive. */
+    private onData;
+    /** Tear the socket down, failing pending work. */
+    private reset;
+}