dsh-builtin-browser 0.1.22 → 0.2.0

package/README.en.md

@@ -18,7 +18,7 @@
 | --- | --- |
 | Why a shared real browser, and how it differs from headless approaches | [Why a shared real browser](docs/why-browser.md) |
 | Installation, configuration, day-to-day use | [User guide](docs/user-guide.md) |
-| All 33 tools: parameters, output, examples | [Tool reference](docs/tool-reference.md) |
+| All 34 tools: parameters, output, examples | [Tool reference](docs/tool-reference.md) |
 | How the seam / provider / tools layers and self-hosting work | [Architecture](docs/architecture.md) |
 | Documentation index and README split | [Docs index](docs/README.md) |
 
@@ -28,7 +28,7 @@
 
 - **A real view, not a relay**: the browser is a native `WebContentsView`; the human sees every step the agent takes and can grab control at any time;
 - **Install-and-use**: with a desktop shell the shell's embedded view is used; on plain `dsh web` the plugin **self-hosts** — it spawns its own Electron window with zero extra configuration;
-- **One plugin, one toolset**: after install the agent automatically gets 33 `browser_*` tools (open, a11y tree, wait, semantic/coordinate interaction, scroll, back/forward, batch and single-control form filling, keys, structured scraping, screenshot, download, auth management…).
+- **One plugin, one toolset**: after install the agent automatically gets 34 `browser_*` tools (open, a11y tree, wait, semantic/coordinate interaction, scroll, back/forward, batch and single-control form filling, keys, structured scraping, screenshot, download, auth management…).
 
 In one sentence: **installing the plugin gives you a real browser that is shared with the user and drivable by the agent.**
 
@@ -117,6 +117,26 @@ See the full list in [Tool reference](#tool-reference).
       <p><code>browser_screenshot</code> supports <code>savePath</code> to write the PNG to disk, ready for vision models (modlens etc.) to locate elements visually.</p>
     </td>
   </tr>
+  <tr>
+    <td width="50%" valign="top">
+      <h3>Searchable browsing history</h3>
+      <p><code>browser_visited</code> reads the <b>persistent</b> record of visited pages (stored beside the browser profile, so it survives closing the browser and restarting DSH), filterable by domain and reopenable. It is a different thing from <code>browser_history</code>, which is the session's operation log.</p>
+    </td>
+    <td width="50%" valign="top">
+      <h3>Synthetic cursor</h3>
+      <p>While the agent works, a virtual pointer and click ripple are drawn inside the page — <b>its appearance means the agent has taken over that tab</b>. DOM-level actions (set value, check, select) also show a landing point. Can be switched off in settings.</p>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%" valign="top">
+      <h3>A "Browser" section in Settings</h3>
+      <p>Keep history / keep cookies / auto-expand the side panel / close the browser when a session ends / show the cursor / vision strategy / allow credential reads — switches take effect <b>immediately</b>, no restart.</p>
+    </td>
+    <td width="50%" valign="top">
+      <h3>Unambiguous teardown</h3>
+      <p><b>Closing the browser window ends that session</b> (the next open is a clean one) while browsing history and login state survive; <b>collapsing the interface is only a collapse</b> and the browser keeps running in the background.</p>
+    </td>
+  </tr>
 </table>
 
 ## Why this plugin
@@ -135,6 +155,7 @@ See the full list in [Tool reference](#tool-reference).
 | `browser_snapshot` | Numbered inventory of interactive elements (inputs/buttons/links; pierces same-origin iframes and Shadow DOM) | – |
 | `browser_a11y` | Accessibility tree: semantic role/name/value/states + coordinates per interactive node (pierces same-origin iframes and Shadow DOM) | – |
 | `browser_execute` | Run JS in the page; args arrive as `arguments[0..n]` | ✅ |
+| `browser_visited` | Read the persistent browsing history (visited pages, filterable by domain / capped); reopen with `browser_open` | – |
 | `browser_content` | Fetch the page as html / markdown / txt / json (selector, maxChars, timeoutMs) | – |
 | `browser_click` | Click a semantic target (`target`: css/text/xpath, scrolls into view and clicks center) or viewport coordinates (vision-located) | ✅ |
 | `browser_type` | Type text (optionally focusing a `target` element first; CDP `Input.insertText`) | ✅ |
@@ -243,6 +264,25 @@ The browser's **visible view**, the **browser column layout**, and the **column-
 
 > The plugin declares `electron >= 30`; it has **only been verified on Windows** (macOS/Linux untested, not yet promised).
 
+## Updating (the two hosts differ)
+
+The plugin has one installation per host, and the two are updated separately — **updating one does not update the other**.
+
+**Desktop (DSH Desktop)**
+- The plugin is a dependency of the desktop profile (usually `$DSH_HOME/profiles/desktop`). Updating means moving that dependency to the new version and then **restarting DSH Desktop**, which is when the settings panel and the tools pick up the new code.
+- The browser engine is the desktop app's own Electron; the plugin never downloads a second copy.
+- Upgrading the desktop app itself does not carry the plugin along; update it as described above.
+
+**Web (`dsh web`)**
+- The plugin is a dependency of the web profile (`$DSH_HOME/profiles/web`); **restart `dsh web`** after updating.
+- There is no desktop shell, so the shared browser is self-hosted by the plugin: the first install may need an Electron binary. If the package manager's build allow-list blocked it (pnpm v10+ blocks `electron`'s postinstall), run `npx install-electron` once to fetch it.
+- Update it the same way you installed it (npm package `dsh-builtin-browser`, the GitHub repo `wqty123/dsh-browser`, or a local directory).
+
+**What is the same on both**
+- The toolset (34 `browser_*` tools), the "Browser" section in Settings, and how browsing history and cookies persist are identical; only the carrier of the browser window differs (desktop shell vs. plugin-hosted).
+- Upgrading loses no data: history and settings live in `$DSH_HOME/dsh-builtin-browser-host/` (`history.jsonl`, `settings.json`), and login state sits in the same profile directory.
+- If history behaves unexpectedly after an upgrade, check **Settings → Browser**: history defaults to **on**, one-time auto-expand defaults to **on**, and closing the browser when a session ends defaults to **off**.
+
 ## Known limitations
 
 - JPEG screenshots are available only on the self-hosted native path (`capturePage` `toJPEG`); the desktop shell's CDP fallback stays PNG (CDP JPEG hangs on Electron 43).
@@ -310,8 +350,15 @@ Code layout:
 | 17 | 2026-09-16 | **Screenshot savePath confined + localized download dir** (issue #13): `browser_screenshot` wrote straight to `writeFileSync` — anywhere the process could reach, silently replacing existing files (bypassing the read-only sandbox's write protection) → one shared `admitSavePath` gate for downloads AND screenshots (absolute, inside `downloadDir`, never overwriting an existing file), plus parent-directory creation for screenshots; the default download directory is no longer hardcoded to `~/Downloads` but probed in order: `downloadDir` → `XDG_DOWNLOAD_DIR` → `~/Downloads` / `~/下载` / `~/下載` → fallback (a Chinese desktop needs no configuration) |
 
 | **0.1.22** | 2026-09-16 | **Release**: the macOS binary-probe fix (issues #9 / #14) and rounds 15–17 (issue #11 toolbar SyntaxError / #10 self-hosted trio / #13 screenshot savePath + download dir) ship as **0.1.22** (build clean, **35/35 tests pass**, tag `v0.1.22`) |
+| Round 18 | 2026-09-20 | **Windows on-device trio + probe self-healing + locate verdicts** (measured on a real self-hosted `dsh web` host; defects ①–④ were all the "CDP answered success, the page received nothing" kind): ① Chromium's `CalculateNativeWinOcclusion` marks the plugin window HIDDEN while another window covers it — the page stops producing frames and **every** synthesized mouse/key event is dropped by the renderer (`CanReceiveInput()` false) while CDP replies `{}` → the child appends `disable-features=CalculateNativeWinOcclusion` before `app.whenReady()` (win32 only); ② `click()` had no leading `mouseMoved`, so the first click on a fresh view was routed away and lost → now move→press→release; ③ a fresh view holds no web focus, so the FIRST `browser_key` of a session vanished → new host `focus` op (optional `focus?()` on the view handle), `key()` focuses best-effort before dispatch and waits 80ms only when focus had to move (focus lands asynchronously; a key dispatched in the same turn is still dropped); ④ `available()` cached a FAILED Electron probe for the host's lifetime while provider selection runs once per process, so an Electron that arrived after DSH started was never adopted → successes stay cached, failures re-probe after a cooldown (`DSH_BROWSER_PROBE_RETRY_MS`, default 30s), and `resolveProvider()` now distinguishes "no provider registered" from "registered but reports itself unavailable" with the matching remedy; ⑤ **a failed locate was masked by the outer timeout** — the in-page locate script polls for its whole budget and answers only afterwards, while the outer wait used the SAME budget, so `browser: click timed out after 10000ms` won the race and the in-page verdict never got out; a css/xpath **parse error** also reported as "not found yet", polling a selector that can never become valid. Now a parse error is terminal and names itself (`invalid CSS selector "…" / invalid XPath …`), the outer wait gives the in-page answer 2 s of transport grace, and a miss reports the strategy the provider assumed (`by` defaults to `"by":"css"`) plus the time spent; `scrape`'s item selector fails the same way at once. Same call: before `click timed out after 10000ms`, after `element not found: {"value":"Learn more","by":"css"} (looked for 10000ms)`. 7 new regression tests (**47/47 pass**), 17/17 end-to-end steps against the real host, plus 4/4 locate-verdict steps |
+
+| 19 | 2026-10-01 | **DSH 0.2 compatibility**: DSH moved to the 0.2 line (`@deepseek-ai/dsh@0.2.0-rc.2`, with `dsh-llm`/`dsh-tools`/`dsh-system-prompt` following to `0.2.0-rc.2`), while our declaration `>=0.1.1-rc.1 <0.2.0` shut 0.2 out → verified the plugin's (narrow) runtime dependency surface against a **real 0.2.0-rc.2 host** (`cordis` Context/Service, `dsh-tools` defineTool, `dsh-llm` HarnessError, `schemastery`) and found no breaking change: session, navigation, snapshot and the screenshot trio (outside-path refused / legal write / overwrite refused) all pass → peer ranges for the three dsh packages widened to `>=0.1.1-rc.2 <0.3.0`, `dsh.compatibility.dsh` widened to `>=0.1.1-rc.1 <0.3.0`, and `dshReleases` gained `0.2.0-rc.1`/`0.2.0-rc.2` = compatible |
+| **0.1.23** | 2026-10-01 | **Release**: round 18 (PR #15: the Windows synthesized-input trio + Electron probe self-healing + locate verdicts) and round 19 (DSH 0.2 compatibility) ship as **0.1.23** (build clean, **47/47 tests pass**, tag `v0.1.23`) |
+| Round 20 | 2026-10-01 | **Browsing history / settings panel / synthetic cursor / teardown**: (1) **persistent browsing history** (`history-store`: append-only JSONL beside the browser profile; capped at 5000 entries or 90 days, whichever comes first; a damaged line loses only itself) plus the new **`browser_visited`** tool (tool count **33 → 34**), reopening via `browser_open`; (2) a "Browser" section in Settings (hand-written client bundle registered into `settings.section` with `order: 60`, below the host's own rows) served by `GET/PUT /dsh-builtin-browser/settings` (same-origin guard, 64 KiB cap) over a `settings-store` document (per-field validation, unknown keys dropped, malformed file falls back to defaults) — **switches take effect immediately** because the provider reads the document on every use; (3) an in-page **synthetic cursor** (inline styles + Web Animations, so a page's `style-src` CSP cannot drop it; `buildTargetScript` now attaches the element centre as `__point`, which gives click / type / setValue / check / select / clear **a landing point**) — **its appearance means the agent has taken over that tab**; (4) **closing a window ends its session**: on `closed` the host releases every view's `webContents` (a BrowserWindow does not destroy child views, so each window would otherwise leak a renderer) and reports `viewClosed`; the provider ends that session and the seam gains `exists()` so the tool layer re-checks a cached session — the next call gets a **clean session** while browsing history and login state survive. 21 new tests (**68/68 pass**) |
+| Round 20 addendum | 2026-10-01 | **Root cause of the invisible settings panel, plus crash diagnostics**: (1) On a real host the panel did not appear — the cause is that all three `cordis.patch.yml` rows were registered under **subpath** names (`dsh-builtin-browser/browser`), while the host's client-module scan resolves a row's specifier to a **package root** (`exactPackageSpecifier` returns `undefined` as soon as it sees a `/`), leaving the package with no row to read its `dsh.client` from. Fixed by adding an inert root row under the bare package name and giving the root entry `export const name` plus an empty `apply()`. Measured: boot entries 67 → **68**, the panel appears below "规则设定", and switches persist immediately. (2) Three host-log defects fixed: ISO timestamps, both paths plus their existence recorded before spawning, and a 2 MiB rotation that leaves a dated marker instead of wiping the file (which is how weeks of history vanished); the `exit` line gained `pid=` and `entryExists=` so "present at spawn, absent at exit" names an installation replaced underneath a running host. (3) Test pollution of the real log fixed: three spawn-based tests restored `DSH_HOME` in a `finally` while `dispose()` kills children asynchronously, so their synthetic exit lines landed in the operator's real log — now isolated at module scope. **70/70 tests** |
+| **0.2.0** | 2026-10-01 | **Release**: round 20 (persistent browsing history / the "Browser" settings section / synthetic cursor / teardown semantics) and its addendum ship as **0.2.0** — tool count **33 → 34** (new `browser_visited`), plus a new "Browser" section in Settings. Build clean, **70/70 tests pass**, tag `v0.2.0` |
 
-> The npm badge at the top is the authority on the registry's latest version: `0.1.22` is committed and tagged; if the badge still reads `0.1.21`, that version is not published yet.
+> The npm badge at the top is the authority on the registry's latest version: `0.1.23` is committed and tagged; if the badge still reads `0.1.22`, that version is not published yet.
 
 ## Acknowledgements
 

package/README.md

@@ -18,7 +18,7 @@
 | --- | --- |
 | 了解插件为什么存在、与无头方案的区别 | [为什么做共享真实浏览器](docs/why-browser.md) |
 | 安装、配置与日常使用 | [用户指南](docs/user-guide.md) |
-| 全部 33 个工具的参数、输出与示例 | [工具参考](docs/tool-reference.md) |
+| 全部 34 个工具的参数、输出与示例 | [工具参考](docs/tool-reference.md) |
 | 了解 seam / provider / 工具三层与自托管实现 | [架构说明](docs/architecture.md) |
 | 查看全部文档与 README 分工 | [文档索引](docs/README.md) |
 
@@ -28,7 +28,7 @@
 
 - **真实视图,而非转播**:浏览器是原生 `WebContentsView`,用户直接看到 agent 在做什么,随时可以上手接管;
 - **装好即用**:有桌面外壳时嵌入外壳视图;纯 `dsh web` 也能**自托管**——插件自己拉起一个 Electron 窗口,不需要任何额外配置;
-- **一插件即一套工具**:安装后 agent 自动获得 33 个 `browser_*` 工具(打开、查看、无障碍树、等待、语义/坐标操作、滚动、回退、批量/单控件填表、按键、结构化提取、截图、下载、登录态管理……)。
+- **一插件即一套工具**:安装后 agent 自动获得 34 个 `browser_*` 工具(打开、查看、无障碍树、等待、语义/坐标操作、滚动、回退、批量/单控件填表、按键、结构化提取、截图、下载、登录态管理……)。
 
 一句话:**安装插件 = 获得一个与用户共享、可被 agent 驱动的真实浏览器。**
 
@@ -117,6 +117,26 @@ dsh plugin --profile web add <本仓库路径>
       <p><code>browser_screenshot</code> 支持 <code>savePath</code> 直接落盘 PNG,交给视觉模型(modlens 等)做基于视觉的元素定位。</p>
     </td>
   </tr>
+  <tr>
+    <td width="50%" valign="top">
+      <h3>可查的浏览历史</h3>
+      <p><code>browser_visited</code> 读取<b>持久化</b>的访问记录(与 cookie 同址落盘,关闭浏览器、重启 DSH 后仍在),可按域名过滤并重新打开任意一条。它与 <code>browser_history</code>(会话内的操作日志)是两件事。</p>
+    </td>
+    <td width="50%" valign="top">
+      <h3>可视化鼠标</h3>
+      <p>agent 操作时在页面内绘制虚拟光标与点击涟漪 —— <b>光标出现即表示它已接管该标签页</b>;DOM 级操作(填值/勾选/选择)同样有落点。可在设置里关闭。</p>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%" valign="top">
+      <h3>设置页里的「浏览器」栏</h3>
+      <p>历史与 cookie 是否保留、侧栏是否自动展开、会话结束时是否关闭浏览器、是否显示光标、视觉策略、是否允许读取凭据 —— 开关<b>即时生效</b>,无需重启。</p>
+    </td>
+    <td width="50%" valign="top">
+      <h3>收尾明确</h3>
+      <p><b>关掉浏览器窗口 = 结束该会话</b>(下次打开是干净的新会话),浏览历史与登录状态保留;<b>收起界面只是收起</b>,浏览器继续在后台运行。</p>
+    </td>
+  </tr>
 </table>
 
 ## 为什么选它
@@ -135,6 +155,7 @@ dsh plugin --profile web add <本仓库路径>
 | `browser_snapshot` | 交互元素(输入框/按钮/链接)带编号清单(穿透同源 iframe 与 Shadow DOM) | – |
 | `browser_a11y` | 无障碍树:每个交互节点的语义角色/名称/值/状态 + 坐标(穿透同源 iframe 与 Shadow DOM) | – |
 | `browser_execute` | 在页面执行 JS;参数以 `arguments[0..n]` 传入 | ✅ |
+| `browser_visited` | 读取持久化浏览历史(访问过的页面,可按域名过滤/限量);重开用 `browser_open` | – |
 | `browser_content` | 以 html / markdown / txt / json 抓取页面(selector、maxChars、timeoutMs) | – |
 | `browser_click` | 点击:语义目标(`target`: css/text/xpath,滚动到元素并点中心)或视口坐标(配合截图视觉定位) | ✅ |
 | `browser_type` | 输入文本(可先按 `target` 聚焦元素;CDP `Input.insertText`) | ✅ |
@@ -211,7 +232,7 @@ agent (browser_* 工具)
 
 - **seam 层**(`browser` 行)提供 `ctx.browser` 服务:provider 注册、会话生命周期、错误码,与具体实现解耦;
 - **provider 层**(`browser-electron` 行)通过 `ElectronBrowserViewHost` 接缝操作视图(创建/销毁/显示/`sendCommand`),由真实外壳用 Electron 对象实现;
-- **工具层**(`tool-browser` 行)提供模型侧的 33 个 `browser_*` 工具,按调用方任务(DSH 会话)维护独立的浏览器会话。
+- **工具层**(`tool-browser` 行)提供模型侧的 34 个 `browser_*` 工具,按调用方任务(DSH 会话)维护独立的浏览器会话。
 
 **自托管模式**:没有桌面外壳时,插件自己拉起一个 Electron 子进程(`host-main.js`),通过本机 TCP JSON-RPC 驱动。RPC 带随机 token 认证,token 经 **stdin + 环境变量双通道**传递——Windows 上 Electron 是 GUI 子系统进程、收不到 piped stdin,环境变量兜底保证握手稳定。子进程崩溃会自动重启;优先使用随插件安装的 electron 包(**打包应用如 DSH Desktop.exe 不会被误当作可复用二进制**,避免 spawn 秒退);截图优先走 Electron 原生 `capturePage`(CDP 截图在多视图下会挂起);Electron 的定位顺序见下(33.x 有合成器缺陷,建议 ≥ 40;44+ 的 electron 包不再随安装自动下载二进制,首次使用若缺失会按报错提示先 `npx install-electron`,需联网)。
 
@@ -243,6 +264,25 @@ agent (browser_* 工具)
 
 > 插件声明 `electron >= 30`;**当前仅在 Windows 环境实测**(macOS/Linux 未验证,暂不承诺)。
 
+## 更新方式(两端不同)
+
+插件在两种宿主里各有一份安装,更新路径也不同 —— **更新其中一端不会连带更新另一端**。
+
+**桌面端(DSH Desktop)**
+- 插件是桌面端 profile 里的依赖(profile 目录通常是 `$DSH_HOME/profiles/desktop`)。更新它 = 把该 profile 里的依赖更新到新版本,然后**重启 DSH Desktop**,客户端设置栏与工具才会换成新代码。
+- 浏览器内核由桌面端自带的 Electron 提供,插件不会再下载一份 Electron。
+- 桌面端自身的升级不会自动带来插件升级,需要按上面的方式单独更新。
+
+**Web 端(`dsh web`)**
+- 插件是 web profile 里的依赖(`$DSH_HOME/profiles/web`),更新后**重启 `dsh web`** 生效。
+- Web 端没有桌面外壳,共享浏览器由插件自托管拉起:首次安装可能需要 Electron 二进制;若包管理器的构建白名单拦下了它(pnpm v10+ 会拦 `electron` 的 postinstall),执行一次 `npx install-electron` 补上即可。
+- 更新方式与你首次安装它时一致(按 npm 包名 `dsh-builtin-browser`、按 GitHub 仓库 `wqty123/dsh-browser`,或本地目录)。
+
+**两端一致的体验**
+- 工具集(34 个 `browser_*`)、设置页里的「浏览器」栏、浏览历史与 cookie 的持久化行为完全相同;差别只在浏览器窗口由谁承载(桌面外壳 / 插件自托管)。
+- 升级不会丢数据:浏览历史与设置都在 `$DSH_HOME/dsh-builtin-browser-host/`(`history.jsonl`、`settings.json`),登录状态在同一 profile 目录里。
+- 升级后如果历史记录不符合预期,先去「设置 → 浏览器」确认这些开关:历史默认**开**、侧栏自动展开默认**开**、会话结束时自动关闭浏览器默认**关**。
+
 ## 已知限制
 
 - JPEG 截图仅自托管原生路径可用(`capturePage` 的 `toJPEG`);桌面壳的 CDP 回退路径仍为 PNG(CDP JPEG 在 Electron 43 上挂起)。
@@ -310,8 +350,15 @@ npm run build
 | 第十七轮 | 2026-09-16 | **截图 savePath 收敛 + 下载目录本地化**(issue #13):`browser_screenshot` 原先直接 `writeFileSync`,可写进程可达的任意路径并**静默覆盖**已有文件(等于绕过只读沙箱的写保护)→ 抽出唯一下载/截图共用准入门 `admitSavePath`(绝对路径 + `downloadDir` 内 + **不覆盖已存在文件**),截图补父目录自动创建;默认下载目录不再写死 `~/Downloads`,按序探测 `downloadDir` → `XDG_DOWNLOAD_DIR` → `~/Downloads`/`~/下载`/`~/下載` → 回退(中文桌面免配置) |
 
 | **0.1.22** | 2026-09-16 | **发布**:macOS 二进制探测修复(issue #9 / #14)与第十五~十七轮(issue #11 工具栏 SyntaxError / #10 自托管三连 / #13 截图 savePath + 下载目录)随 **0.1.22** 收录(构建零错误、**35 项测试全绿**,tag `v0.1.22`) |
+| 第十八轮 | 2026-09-20 | **Windows 真机三连 + 探测自愈 + 定位判词**(真实 `dsh web` 自托管宿主实测,缺陷①~④同为「CDP 报成功、页面没收到」):① Windows 的 `CalculateNativeWinOcclusion` 把被遮挡的插件窗口判定为 HIDDEN → 整站停帧,且每条合成鼠标/键盘事件被渲染端静默丢弃(CanReceiveInput=false)而 CDP 回 `{}` → 子进程 ready 前追加 `disable-features=CalculateNativeWinOcclusion`(仅 win32);② `click()` 缺前置 `mouseMoved`,新视图第一次点击落空 → 改为 move→press→release;③ 新视图从未持有 web focus,`browser_key` 第一次调用无效 → 宿主新增 `focus` op(view handle 可选 `focus?()`),`key()` 派发前 best-effort 聚焦,并在焦点需要移动时等 80ms(焦点落地异步,同轮派发的键仍会被丢);④ `available()` 把**失败**探测按宿主生命周期永久缓存,而 provider 选择每进程一次 → Electron 晚于 DSH 到位就永远接不上 → 成功仍缓存、失败 30s 冷却后重探(`DSH_BROWSER_PROBE_RETRY_MS`),`resolveProvider()` 报错区分「一个都没注册」与「注册了但自报不可用」并附处置;⑤ **定位失败被外层超时掩盖** —— 页内定位脚本会把预算轮询到底才回答,外层却用同一个预算,于是 `browser: click timed out after 10000ms` 抢走了页内早已写好的判词;而 css/xpath **解析失败**(选择器根本不合法)也被写成「还没找到」,对着永远不可能匹配的东西把预算轮完 → 解析失败即刻终止并报 `invalid CSS selector "…" / invalid XPath …`;外层给页内判词 2s 传输余量;未命中判词补上提供方实际采用的策略(`by` 缺省即 `"by":"css"`)与实际耗时;`scrape` 的 item 选择器同样即刻失败(同一个漏写 `by` 的调用:修前 `click timed out after 10000ms`,修后 `element not found: {"value":"Learn more","by":"css"} (looked for 10000ms)`);新增 7 条回归测试(**47/47 全绿**),真实宿主端到端 **17/17** + 定位判词 **4/4** |
+
+| 第十九轮 | 2026-10-01 | **DSH 0.2 兼容性**:DSH 进入 0.2 线(`@deepseek-ai/dsh@0.2.0-rc.2`,peer 包 `dsh-llm`/`dsh-tools`/`dsh-system-prompt` 同步到 `0.2.0-rc.2`),而原声明 `>=0.1.1-rc.1 <0.2.0` 把 0.2 挡在门外 → 在**真实 0.2.0-rc.2 宿主**上实测插件的运行时依赖面(`cordis` 的 Context/Service、`dsh-tools` 的 defineTool、`dsh-llm` 的 HarnessError、`schemastery`),确认无破坏性变更:会话、导航、快照、截图三态(越界拒绝/合法写入/覆盖拒绝)全部通过 → `peerDependencies` 三个 dsh 包范围改为 `>=0.1.1-rc.2 <0.3.0`,`dsh.compatibility.dsh` 放宽为 `>=0.1.1-rc.1 <0.3.0`,`dshReleases` 增加 `0.2.0-rc.1`/`0.2.0-rc.2` = compatible |
+| **0.1.23** | 2026-10-01 | **发布**:第十八轮(PR #15:Windows 合成输入三连 + Electron 探测自愈 + 定位判词)与第十九轮(DSH 0.2 兼容)随 **0.1.23** 发布(构建零错误、**47 项测试全绿**,tag `v0.1.23`) |
+| 第二十轮 | 2026-10-01 | **浏览历史 / 设置栏 / 可视化鼠标 / 收尾语义**:①新增**持久化浏览历史**(`history-store`:追加式 JSONL,落在 cookie 同一 profile 目录;5000 条或 90 天先到者为准;损坏行只丢该行)+ 新工具 **`browser_visited`**(工具数 **33 → 34**),重新打开沿用 `browser_open`;②新增设置页「浏览器」栏(手写客户端 bundle 注册到 `settings.section`,`order: 60` 排在宿主自带栏目下方)+ `GET/PUT /dsh-builtin-browser/settings`(同源防护、64 KiB 上限)+ 设置文档(`settings-store`:字段逐个校验、未知键丢弃、损坏文件按默认值),**开关即时生效**(provider 每次读取,无需重启);③新增页面内**虚拟光标**(内联样式 + Web Animations 以规避页面 `style-src` CSP;`buildTargetScript` 统一附加元素中心 `__point`,于是 click / type / setValue / check / select / clear **都有落点**),**光标出现即代表 agent 已接管该标签页**;④**关掉窗口 = 结束该会话**:窗口 `closed` 时释放其全部视图的 `webContents`(BrowserWindow 不连带销毁子视图,否则每个窗口泄漏一个渲染进程)并上报 `viewClosed`,provider 结束对应会话,seam 新增 `exists()` 供工具层核验会话缓存 —— 下一次调用得到**干净的新会话**,浏览历史与登录状态保留;新增 21 条测试(**68/68 全绿**) |
+| 第二十轮补记 | 2026-10-01 | **客户端设置栏"隐形"的根因 + 崩溃诊断**:①真机验证发现设置栏不出现 —— 根因是 `cordis.patch.yml` 三行全用**子路径名**(`dsh-builtin-browser/browser`)注册,而宿主的客户端模块扫描只接受**精确包名**(`exactPackageSpecifier` 遇 `/` 即返回 `undefined`),于是这个包在客户端侧没有任何行可供读取 `dsh.client`;修复 = 增加一行以**包名**注册的惰性根行 + 给根入口补 `export const name` 与空 `apply()`;实测启动图条目 67 → **68**、设置栏出现并排在「规则设定」下方、开关即时落盘。②宿主日志三处缺陷修复:加 **ISO 时间戳**、spawn 前记录 **两条路径与存在性**、2 MiB 轮转改为**留时间戳标记**(原先整体清空,几周历史就是这样消失的);`exit` 行加 `pid=`/`entryExists=`,使"启动时存在、退出时不存在"自动命名"安装被就地替换"。③修复**测试污染真实日志**:三个 spawn 类测试因 `dispose()` 异步杀子进程,exit 行写在 `finally` 恢复 `DSH_HOME` 之后 → 改为模块级隔离。测试 **70/70** |
+| **0.2.0** | 2026-10-01 | **发布**:第二十轮(浏览历史持久化 / 设置页「浏览器」栏 / 可视化鼠标 / 收尾语义)及其补记随 **0.2.0** 发布 —— 工具数 **33 → 34**(新增 `browser_visited`),设置页新增「浏览器」栏。构建零错误、**70/70 测试全绿**,tag `v0.2.0` |
 
-> registry 上的最新版本以顶部 npm 徽章为准:本次 `0.1.22` 已入库并打 tag;若徽章仍显示 `0.1.21`,说明该版本尚未 publish。
+> registry 上的最新版本以顶部 npm 徽章为准:本次 `0.1.23` 已入库并打 tag;若徽章仍显示 `0.1.22`,说明该版本尚未 publish。
 
 ## 特别感谢
 

package/client.js

@@ -0,0 +1,298 @@
+/**
+ * Browser settings panel (client half): the switches that decide how the shared
+ * browser behaves — history retention, login-state persistence, presentation,
+ * vision strategy and credential access.
+ *
+ * The host half owns the document and serves it at `/dsh-builtin-browser/settings`;
+ * this panel only renders it and sends patches, so the same file stays the single
+ * source of truth (and hand-editable when no panel is reachable).
+ *
+ * Registered into the settings page's `settings.section` slot with an order above
+ * the host's own rows, so it appears under them. Plain ModuleLoader bundle: no
+ * build step, matching how the host loads plugin client halves.
+ */
+window.__ModuleLoader__.load({ id: "dsh-builtin-browser", factory: (require) => {
+  var module = { exports: {} }
+  var exports = module.exports
+  Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" })
+
+  const react = require("react")
+  const h = react.createElement
+  const { useCallback, useEffect, useState } = react
+
+  const name = "dsh-builtin-browser"
+  const inject = ["slots", "locale"]
+  const NS = "settings.dsh-builtin-browser"
+  const ROUTE = "/dsh-builtin-browser/settings"
+  let translate = (key) => key
+
+  const zh = {
+    nav: "浏览器",
+    title: "浏览器(Browser Use)",
+    lead: "这些开关控制共享浏览器如何工作;改动立即生效,不需要重启 DSH。",
+    loading: "读取设置…",
+    failed: "读取设置失败:",
+    retry: "重试",
+    saved: "已保存",
+    path: "设置文件",
+    "history.title": "浏览历史",
+    "history.enabled": "保留浏览历史",
+    "history.hint": "记录访问过的页面;关闭浏览器后仍可查询并重新打开,关闭此开关后不再记录新访问。",
+    "cookies.title": "登录状态",
+    "cookies.persist": "保留 cookies",
+    "cookies.hint": "关闭后每次启动浏览器都是未登录状态。",
+    "ui.title": "展示",
+    "ui.autoExpandOnce": "侧栏自动展开(每轮一次)",
+    "ui.autoExpandOnce.hint": "Agent 首次操作时自动展开;你手动收起后,本轮不再打扰。",
+    "ui.closeWithSession": "会话结束时关闭浏览器",
+    "ui.closeWithSession.hint": "关闭会释放浏览器进程;浏览历史与登录状态会保留。",
+    "ui.virtualCursor": "显示可视化鼠标",
+    "ui.virtualCursor.hint": "让 Agent 正在操作的位置可见(出现即代表它在接管该标签页)。",
+    "vision.title": "视觉策略",
+    "vision.strategy": "默认策略",
+    "vision.auto": "Auto(按模型能力与页面情况自动切换)",
+    "vision.nonVisual": "纯非视觉(DOM / 无障碍树)",
+    "vision.hint": "模型不具备图像理解能力时必须使用非视觉方式。",
+    "credentials.title": "凭据",
+    "credentials.allowRead": "允许 Agent 读取 cookies / 导出登录状态",
+    "credentials.hint": "关闭后 browser_auth 会被拒绝。",
+  }
+
+  const en = {
+    nav: "Browser",
+    title: "Browser (Browser Use)",
+    lead: "These switches decide how the shared browser behaves; changes apply immediately, no DSH restart.",
+    loading: "Loading settings…",
+    failed: "Could not load settings:",
+    retry: "Retry",
+    saved: "Saved",
+    path: "Settings file",
+    "history.title": "Browsing history",
+    "history.enabled": "Keep browsing history",
+    "history.hint": "Records visited pages so they can be found and reopened after the browser is closed; off means no new visits are recorded.",
+    "cookies.title": "Login state",
+    "cookies.persist": "Keep cookies",
+    "cookies.hint": "Off makes every browser start a signed-out session.",
+    "ui.title": "Presentation",
+    "ui.autoExpandOnce": "Auto-expand the side panel (once per task)",
+    "ui.autoExpandOnce.hint": "Expands when the agent first operates; after you collapse it, this task stays quiet.",
+    "ui.closeWithSession": "Close the browser when the session ends",
+    "ui.closeWithSession.hint": "Closing releases the browser process; history and login state survive.",
+    "ui.virtualCursor": "Show the synthetic cursor",
+    "ui.virtualCursor.hint": "Makes the agent's operating position visible (its presence means the agent has taken over that tab).",
+    "vision.title": "Vision strategy",
+    "vision.strategy": "Default strategy",
+    "vision.auto": "Auto (switch by model capability and page)",
+    "vision.nonVisual": "Non-visual only (DOM / a11y tree)",
+    "vision.hint": "A model without image input always uses non-visual operation.",
+    "credentials.title": "Credentials",
+    "credentials.allowRead": "Allow the agent to read cookies / export login state",
+    "credentials.hint": "Off makes browser_auth refuse.",
+  }
+
+  /** Read or patch the host-owned settings document. */
+  async function callSettings(patch) {
+    const response = await fetch(ROUTE, patch === undefined
+      ? { method: "GET", headers: { accept: "application/json" } }
+      : {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(patch),
+      })
+    const data = await response.json().catch(() => undefined)
+    if (data === undefined || data.ok !== true) {
+      throw new Error((data && data.error) || `HTTP ${response.status}`)
+    }
+    return data
+  }
+
+  const styles = {
+    wrap: { display: "flex", flexDirection: "column", gap: "14px", padding: "4px 2px", fontSize: "13px" },
+    lead: { opacity: 0.75, lineHeight: 1.6, margin: 0 },
+    group: { border: "1px solid rgba(128,128,128,.28)", borderRadius: "8px", padding: "10px 12px" },
+    groupTitle: { margin: "0 0 8px", fontSize: "13px", fontWeight: 600 },
+    row: { display: "flex", gap: "10px", alignItems: "flex-start", padding: "5px 0" },
+    box: { marginTop: "2px" },
+    label: { display: "flex", flexDirection: "column", gap: "2px", cursor: "pointer" },
+    hint: { opacity: 0.68, lineHeight: 1.5 },
+    select: { marginTop: "4px", padding: "4px 6px", borderRadius: "6px", background: "transparent", color: "inherit", border: "1px solid rgba(128,128,128,.4)" },
+    status: { opacity: 0.7, minHeight: "18px" },
+    error: { color: "#e5534b" },
+    pathLine: { opacity: 0.6, wordBreak: "break-all", lineHeight: 1.5 },
+    button: { padding: "3px 10px", borderRadius: "6px", border: "1px solid rgba(128,128,128,.4)", background: "transparent", color: "inherit", cursor: "pointer" },
+  }
+
+  /** One boolean switch bound to a settings path. */
+  function Toggle(props) {
+    const t = translate
+    return h("div", { style: styles.row }, [
+      h("input", {
+        key: "i",
+        type: "checkbox",
+        style: styles.box,
+        checked: props.checked,
+        disabled: props.busy,
+        onChange: event => props.onChange(event.target.checked),
+      }),
+      h("label", { key: "l", style: styles.label, onClick: () => props.onChange(!props.checked) }, [
+        h("span", { key: "t" }, t(props.labelKey)),
+        h("span", { key: "h", style: styles.hint }, t(props.hintKey)),
+      ]),
+    ])
+  }
+
+  /** The settings page section. */
+  function SettingsRoot() {
+    const t = translate
+    const [settings, setSettings] = useState(null)
+    const [meta, setMeta] = useState({ path: "" })
+    const [error, setError] = useState("")
+    const [busy, setBusy] = useState(false)
+    const [saved, setSaved] = useState(false)
+
+    const load = useCallback(() => {
+      setError("")
+      callSettings().then(data => {
+        setSettings(data.settings)
+        setMeta({ path: data.path || "" })
+      }).catch(failure => setError(String(failure && failure.message ? failure.message : failure)))
+    }, [])
+
+    useEffect(() => { load() }, [load])
+
+    const patch = useCallback(next => {
+      setBusy(true)
+      setError("")
+      callSettings(next).then(data => {
+        setSettings(data.settings)
+        setSaved(true)
+        setTimeout(() => setSaved(false), 1200)
+      }).catch(failure => setError(String(failure && failure.message ? failure.message : failure)))
+        .then(() => setBusy(false))
+    }, [])
+
+    if (settings === null) {
+      return h("div", { style: styles.wrap }, [
+        h("p", { key: "l", style: styles.lead }, t("loading")),
+        error !== "" ? h("p", { key: "e", style: styles.error }, `${t("failed")} ${error}`) : null,
+      ])
+    }
+
+    const section = (titleKey, children) => h("div", { key: titleKey, style: styles.group }, [
+      h("p", { key: "t", style: styles.groupTitle }, t(titleKey)),
+      ...children,
+    ])
+
+    return h("div", { style: styles.wrap }, [
+      h("p", { key: "lead", style: styles.lead }, t("lead")),
+
+      section("history.title", [
+        h(Toggle, {
+          key: "enabled",
+          labelKey: "history.enabled",
+          hintKey: "history.hint",
+          checked: settings.history.enabled,
+          busy,
+          onChange: value => patch({ history: { enabled: value } }),
+        }),
+      ]),
+
+      section("cookies.title", [
+        h(Toggle, {
+          key: "persist",
+          labelKey: "cookies.persist",
+          hintKey: "cookies.hint",
+          checked: settings.cookies.persist,
+          busy,
+          onChange: value => patch({ cookies: { persist: value } }),
+        }),
+      ]),
+
+      section("ui.title", [
+        h(Toggle, {
+          key: "autoExpandOnce",
+          labelKey: "ui.autoExpandOnce",
+          hintKey: "ui.autoExpandOnce.hint",
+          checked: settings.ui.autoExpandOnce,
+          busy,
+          onChange: value => patch({ ui: { autoExpandOnce: value } }),
+        }),
+        h(Toggle, {
+          key: "closeWithSession",
+          labelKey: "ui.closeWithSession",
+          hintKey: "ui.closeWithSession.hint",
+          checked: settings.ui.closeWithSession,
+          busy,
+          onChange: value => patch({ ui: { closeWithSession: value } }),
+        }),
+        h(Toggle, {
+          key: "virtualCursor",
+          labelKey: "ui.virtualCursor",
+          hintKey: "ui.virtualCursor.hint",
+          checked: settings.ui.virtualCursor,
+          busy,
+          onChange: value => patch({ ui: { virtualCursor: value } }),
+        }),
+      ]),
+
+      section("vision.title", [
+        h("div", { key: "row", style: styles.row }, [
+          h("label", { key: "l", style: styles.label }, [
+            h("span", { key: "t" }, t("vision.strategy")),
+            h("select", {
+              key: "s",
+              style: styles.select,
+              value: settings.vision.strategy,
+              disabled: busy,
+              onChange: event => patch({ vision: { strategy: event.target.value } }),
+            }, [
+              h("option", { key: "auto", value: "auto" }, t("vision.auto")),
+              h("option", { key: "nonVisual", value: "nonVisual" }, t("vision.nonVisual")),
+            ]),
+            h("span", { key: "h", style: styles.hint }, t("vision.hint")),
+          ]),
+        ]),
+      ]),
+
+      section("credentials.title", [
+        h(Toggle, {
+          key: "allowRead",
+          labelKey: "credentials.allowRead",
+          hintKey: "credentials.hint",
+          checked: settings.credentials.allowRead,
+          busy,
+          onChange: value => patch({ credentials: { allowRead: value } }),
+        }),
+      ]),
+
+      h("div", { key: "status", style: styles.status }, [
+        saved ? h("span", { key: "s" }, t("saved")) : null,
+        error !== "" ? h("span", { key: "e", style: styles.error }, ` ${t("failed")} ${error} `) : null,
+        error !== "" ? h("button", { key: "r", style: styles.button, onClick: load }, t("retry")) : null,
+      ]),
+
+      meta.path !== "" ? h("div", { key: "path", style: styles.pathLine }, `${t("path")}: ${meta.path}`) : null,
+    ])
+  }
+
+  function apply(ctx) {
+    ctx.effect(() => ctx.locale.register(NS, { zh, en }), "dsh-builtin-browser: dictionaries")
+    const t = ctx.locale.bind(NS)
+    translate = t
+    ctx.slots.inject("settings.section", () => ctx.slots.register({
+      name: "settings.section",
+      id: "dsh-builtin-browser",
+      // Above the rows the host ships (its furthest sits at 40), so this panel
+      // lands beneath them in the settings page.
+      order: 60,
+      label: () => t("nav"),
+      locale: NS,
+      inject: () => ({ t }),
+    }, SettingsRoot))
+  }
+
+  exports.name = name
+  exports.inject = inject
+  exports.apply = apply
+  return module.exports
+}})

package/cordis.patch.yml

@@ -1,10 +1,29 @@
 # dsh-builtin-browser bundle patch: mounts the shared-browser capability into a
-# profile composition. The browser seam (ctx.browser) is always mounted. The
-# Electron provider and browser_* tools are ALWAYS registered: when the host
-# provides `electronViewHost` (the desktop shell) that embedded view is used,
-# and otherwise the plugin self-hosts its own Electron window, so installing
-# the plugin is enough for the browser to work anywhere.
+# profile composition.
+#
+# Row names matter beyond loading: the host's client-module scan resolves a row's
+# specifier to a PACKAGE ROOT and reads `dsh.client` from there. A row named after
+# a subpath (`dsh-builtin-browser/browser`) is not a package specifier and is
+# skipped by design, which would leave the settings panel permanently absent even
+# though every tool works — hence the inert root row under the bare package name.
+#
+# The browser seam (ctx.browser) is always mounted, and the Electron provider plus
+# the browser_* tools are always registered: when a host provides an embedded view
+# seam the provider drives that view, and otherwise it self-hosts its own Electron
+# window, so installing the plugin is enough for the browser to work anywhere.
+# DSH 0.2 no longer provides `electronViewHost` (the desktop shell's embedded
+# view), so `ctx.get('electronViewHost')` currently resolves to undefined and
+# every surface self-hosts. The row keeps reading it on purpose: a host that
+# reintroduces such a seam is then picked up without a code change.
 - insert:
+    # Root row. The host's client-module scan resolves a loader row's specifier
+    # to a PACKAGE ROOT; a row named after a subpath is skipped, and this package
+    # would then have no row to read its `dsh.client` declaration from — the
+    # browser would work while its settings panel never appeared. This row is
+    # inert (see src/index.ts) and exists only to name the package.
+    - id: dsh-builtin-browser
+      name: dsh-builtin-browser
+
     - id: browser
       name: dsh-builtin-browser/browser
 

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. */