dsh-builtin-browser 0.1.10 → 0.1.12

package/README.md

@@ -1,80 +1,162 @@
-# dsh-builtin-browser（DeepSeek Harness 内置共享真实浏览器插件）
+<p align="center">
+  <img src="https://img.shields.io/github/stars/wqty123/dsh-browser?style=flat&amp;label=%E2%98%85&amp;color=08C" alt="GitHub stars">
+  <img src="https://img.shields.io/npm/v/dsh-builtin-browser?style=flat&amp;label=npm&amp;color=CB3837" alt="npm version">
+  <img src="https://img.shields.io/badge/license-MIT-2EA44F?style=flat" alt="MIT License">
+  <img src="https://img.shields.io/badge/DSH-Plugin-47848F?style=flat" alt="DeepSeek Harness plugin">
+  <img src="https://img.shields.io/badge/Windows%20%7C%20macOS%20%7C%20Linux-4493F8?style=flat-square" alt="Platforms">
+</p>
 
-[English](README.en.md) | 中文
+<p align="center"><sub>中文 · <a href="README.en.md">English</a></sub></p>
 
-面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的**共享真实浏览器**能力插件:装好即可用——agent 通过 CDP 驱动一个真实、可见、可随时人工接管的浏览器,人与 agent 操作的是**同一个页面**。
+<h3 align="center">为 DeepSeek Harness 生态打造的<b>共享真实浏览器</b>插件（装好即用，人机同页）</h3>
 
-**我们的优势**
+<h4 align="center">agent 驱动一个真实、可见、可随时人工接管的浏览器——人与 agent 操作的是<b>同一个页面</b>。</h4>
 
-- **装好即用**:有桌面外壳时嵌入外壳视图;纯 `dsh web` 也能**自托管**拉起自己的 Electron 窗口,不需要任何额外配置。
-- **真实可见、人工可接管**:不是无头截屏或转播,用户随时能看到页面并直接接手操作。
-- **DOM 级驱动,框架友好**:React/Vue 受控组件也能可靠填写。
-- **并发安全**:任务级浏览器会话隔离,多个任务并行互不抢页面、不互相污染。
-- **面向真实世界**:人机验证识别、登录态持久化、批量填表、带登录态下载、操作回放、动作限制,一应俱全。
+## 这是什么
 
-## 功能
+`dsh-builtin-browser` 给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 提供浏览器能力:
 
-**浏览器能力**
+- **真实视图,而非转播**:浏览器是原生 `WebContentsView`,用户直接看到 agent 在做什么,随时可以上手接管;
+- **装好即用**:有桌面外壳时嵌入外壳视图;纯 `dsh web` 也能**自托管**——插件自己拉起一个 Electron 窗口,不需要任何额外配置;
+- **一插件即一套工具**:安装后 agent 自动获得 20 个 `browser_*` 工具(打开、查看、操作、填表、截图、下载、登录态管理……)。
 
-- **真实视图,而非转播。** 浏览器是原生视图(`WebContentsView`),用户可直接看到并操作;agent 驱动的是同一个页面。视图由宿主外壳提供,插件负责驱动。
-- **DOM 引用,而非猜坐标。** `browser_snapshot` 返回带编号的交互元素;`browser_execute` 在页面里执行 JS(框架输入用原生 setter),在 React/Vue 页面上也能可靠交互。
-- **多标签会话。** 并行打开 URL、查看/切换/关闭/重置标签,状态保持。
-- **多格式内容。** 以 html / markdown / txt / json 抓取页面,支持 selector 限定、长度与超时上限。
+一句话:**安装插件 = 获得一个与用户共享、可被 agent 驱动的真实浏览器。**
 
-**工程化能力**
-
-- **按任务隔离。** 每个 DSH 任务(会话)拥有独立的浏览器会话(独立标签页与历史),并发任务互不干扰;同一任务内多次调用复用同一会话(`browser_session` / `browser_reset_session`)。
-- **登录态持久化。** `browser_auth` 导出/恢复 cookie,重启后登录态不丢。
-- **人机验证识别。** 自动检测 Cloudflare / reCAPTCHA / hCaptcha / Turnstile 等挑战(`browser_challenge`,快照也会标注),提示人工在共享窗口完成,不再盲目重试。
-- **批量表单填充。** `browser_fill` 一次填写多个字段:按选择器/名称/标签匹配,支持受控输入、下拉、单选/复选,可选提交。
-- **操作历史与回放。** `browser_history` 记录操作日志,`browser_replay` 可回放某一步。
-- **带登录态下载。** `browser_download` 用会话 cookie 把文件取到本地,登录后内容可直接落盘。
-- **安全限制。** `browser_restrict` 限制允许的浏览器动作,防误点/误导航。
-
-## 环境要求
-
-- DeepSeek Harness(dsh)且安装了 `web` profile
-- **Electron 运行时**(可选 peer 依赖):桌面外壳自带;纯 `dsh web` 下需要能定位到 Electron 二进制(见下)
-- 有桌面外壳(`ctx.electronViewHost`)时用外壳嵌入视图;没有时插件**自托管**:自己拉起一个 Electron 窗口,`browser_*` 工具照常可用
-
-**Electron 定位顺序**:① `require('electron')`(peer 依赖已装)→ ② DSH 安装锚点 → ③ `node_modules/.pnpm` 虚拟仓库 → ④ `ELECTRON_PATH` 环境变量。找不到时工具会报清晰的错误提示。
-
-### 验证过的版本
-
-| 组件 | 版本 |
-|---|---|
-| DeepSeek Harness(dsh) | `0.1.0-rc.5` |
-| Electron | `43.4.0` |
-| Node.js | `22.20.0` |
-| dsh-builtin-browser | `0.1.7` |
-| 操作系统 | Windows 10 (10.0.26200) |
-
-> 插件声明 `electron >= 30`;其他平台(如 macOS/Linux)按同一协议运行,但仅在上表 Windows 环境实测。
-
-## 安装
+## 快速开始
 
 ```sh
-dsh plugin --profile web add dsh-builtin-browser   # 发布到 npm 后
-# 或从源码目录(独立仓库,一插件一仓库):
+# 方式一:从 npm 安装(已发布)
+dsh plugin --profile web add dsh-builtin-browser
+
+# 方式二:从源码目录安装(独立仓库,一插件一仓库)
 dsh plugin --profile web add <本仓库路径>
 ```
 
-这会链接插件、把 `dsh-builtin-browser` 加入 profile 的 bundle 层,并挂载:
+安装后,agent 即可使用浏览器工具,例如:
+
+| 想做什么 | 用哪个工具 | 说明 |
+| --- | --- | --- |
+| 打开页面 | `browser_open` | 打开 URL,返回带编号元素的快照 |
+| 了解页面 | `browser_snapshot` | 输入框/按钮/链接的编号清单,可据此定位 |
+| 操作页面 | `browser_execute` | 在页面里执行 JS(原生 setter,框架友好) |
+| 填写表单 | `browser_fill` | 一次填写多个字段,可选提交 |
+| 看到页面 | `browser_screenshot` | PNG 截图,可存文件交给视觉模型 |
+
+完整清单见[工具参考](#工具参考)。
+
+## 主要功能
+
+<table>
+  <tr>
+    <td width="50%" valign="top">
+      <h3>共享真实浏览器</h3>
+      <p>原生视图而非无头截屏。用户与 agent 操作同一个页面:用户能看到每一步,随时接管;agent 驱动的就是用户眼前那个窗口。</p>
+    </td>
+    <td width="50%" valign="top">
+      <h3>DOM 级驱动,框架友好</h3>
+      <p><code>browser_snapshot</code> 返回带编号的交互元素;<code>browser_execute</code> 在页面内执行 JS(受控输入用原生 setter + input/change 事件),React/Vue 页面也能可靠交互。</p>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%" valign="top">
+      <h3>多标签会话</h3>
+      <p>并行打开 URL,查看/切换/关闭/重置标签,每个会话的状态独立保持。</p>
+    </td>
+    <td width="50%" valign="top">
+      <h3>多格式内容</h3>
+      <p>以 html / markdown / txt / json 抓取页面,支持 CSS selector 限定、字符上限与超时控制。</p>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%" valign="top">
+      <h3>任务级会话隔离</h3>
+      <p>每个 DSH 任务(会话)拥有独立的浏览器会话(独立标签页与历史),并发任务互不抢页面、互不污染;同一任务内多次调用复用同一会话。</p>
+    </td>
+    <td width="50%" valign="top">
+      <h3>登录态持久化</h3>
+      <p><code>browser_auth</code> 导出/恢复 cookie,重启后登录态不丢;自托管实例的 cookie 本身也落盘持久。</p>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%" valign="top">
+      <h3>人机验证识别</h3>
+      <p>自动检测 Cloudflare / reCAPTCHA / hCaptcha / Turnstile 等挑战(<code>browser_challenge</code>,快照也会标注),提示人工在共享窗口完成,不再盲目重试。</p>
+    </td>
+    <td width="50%" valign="top">
+      <h3>批量表单填充</h3>
+      <p><code>browser_fill</code> 一次填写多个字段:按选择器/名称/标签匹配,支持受控输入、下拉、单选/复选,可选提交;单个字段失败不影响其余字段。</p>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%" valign="top">
+      <h3>操作历史与回放</h3>
+      <p><code>browser_history</code> 记录操作日志(打开/执行/点击/输入/填表/下载/登录),<code>browser_replay</code> 可按序号回放某一步。</p>
+    </td>
+    <td width="50%" valign="top">
+      <h3>带登录态下载</h3>
+      <p><code>browser_download</code> 在页面上下文内携带会话 cookie 拉取文件并落盘,登录后才能访问的内容也能直接下载。</p>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%" valign="top">
+      <h3>安全限制</h3>
+      <p><code>browser_restrict</code> 限制允许的浏览器动作(白名单),防止 agent 误点、误导航;只读工具(snapshot/content/screenshot)不受限。</p>
+    </td>
+    <td width="50%" valign="top">
+      <h3>截图即存即读</h3>
+      <p><code>browser_screenshot</code> 支持 <code>savePath</code> 直接落盘 PNG,交给视觉模型(modlens 等)做基于视觉的元素定位。</p>
+    </td>
+  </tr>
+</table>
+
+## 为什么选它
+
+- **装好即用,零配置**:不需要桌面外壳、不需要额外启动步骤;纯 `dsh web` 环境自托管拉起 Electron 窗口,`browser_*` 工具照常可用。
+- **人机协同,互不干扰**:用户能看到并接管 agent 的每一个动作;任务级会话隔离让多个并行任务各自拥有独立的标签页与历史。
+- **面向真实世界的自动化**:人机验证识别、登录态持久化、批量填表、带登录态下载、操作回放、动作限制——把"真实浏览器"变成可靠的 agent 能力。
+- **可测试、可替换的架构**:provider 与 Electron 通过 `ElectronBrowserViewHost` 接缝解耦,同一套工具层未来可对接无头转播 provider,无需改动模型侧。
+
+## 工具参考
+
+| 工具 | 用途 | 守卫 |
+| --- | --- | --- |
+| `browser_open` | 打开 URL(可选新标签),返回页面快照 | ✅ |
+| `browser_snapshot` | 交互元素(输入框/按钮/链接)带编号清单 | – |
+| `browser_execute` | 在页面执行 JS;参数以 `arguments[0..n]` 传入 | ✅ |
+| `browser_content` | 以 html / markdown / txt / json 抓取页面(selector、maxChars、timeoutMs) | – |
+| `browser_click` | 按视口坐标点击(配合截图做视觉定位) | ✅ |
+| `browser_type` | 向聚焦元素输入文本(CDP `Input.insertText`) | ✅ |
+| `browser_fill` | 批量填充表单(选择器/名称/标签匹配,受控输入、下拉、单选/复选,可选提交) | ✅ |
+| `browser_screenshot` | PNG 截图,可选 `fullPage` 与 `savePath` | – |
+| `browser_list_tabs` | 当前会话的标签列表 | – |
+| `browser_switch_tab` | 按 id 切换标签(自托管下同步切换可见视图) | ✅ |
+| `browser_close_tab` | 按 id 关闭标签;关闭活动标签后激活下一个 | – |
+| `browser_reset` | 关闭本任务所有标签,回到一个空白标签 | ✅ |
+| `browser_session` | 查看本任务的浏览器会话与标签 | – |
+| `browser_reset_session` | 关闭并重建本任务的浏览器会话 | ✅ |
+| `browser_history` | 操作日志(最新在后),含成功/失败与结果摘要 | – |
+| `browser_replay` | 按序号回放某一步(navigate/execute/click/type) | ✅ |
+| `browser_download` | 带会话 cookie 下载 URL 到本地文件(上限 256MB) | ✅ |
+| `browser_auth` | 导出/恢复 cookie(登录态持久化,自托管可用) | ✅ |
+| `browser_challenge` | 检测人机验证(CAPTCHA / Cloudflare / reCAPTCHA / hCaptcha / Turnstile) | – |
+| `browser_restrict` | 限制允许的浏览器动作(白名单;空列表解除) | – |
+
+> 「守卫」列:打 ✅ 的动作受 `browser_restrict` 白名单约束;只读工具(snapshot/content/screenshot/list_tabs/session/challenge/history)永不拦截。
 
-| 行 | 子路径 | 角色 |
-|---|---|---|
-| `browser` | `dsh-builtin-browser/browser` | `ctx.browser` 能力 seam(始终挂载) |
-| `browser-electron` | `dsh-builtin-browser/browser-electron` | Electron CDP provider(需要 `electronViewHost`) |
-| `tool-browser` | `dsh-builtin-browser/tool-browser` | `browser_*` 模型侧工具 |
+### 操作纪律(点击/填表)
 
-provider 与工具以 `ctx.get('electronViewHost')` 是否存在为门控,因此没有桌面外壳的组合只会保留 seam,其余不启用。
+- **优先用 DOM 语义而非坐标**:表单提交优先 `form.requestSubmit()`;点击优先 `element.click()`;坐标点击是最后手段。
+- **选中正确的元素**:页面常有隐藏副本(如移动端按钮),用 `browser_execute` 过滤可见元素(`getBoundingClientRect()` 宽高 > 0、`getComputedStyle` 非 `display:none`),再取坐标。
+- **取坐标后立即点击**:中间不要插入其他操作(填表、滚动会移动元素,旧坐标立即失效)。
+- **点击前验证命中**:`document.elementFromPoint(x, y)` 确认该坐标确实是目标元素(按钮/链接),再执行真实点击。
+- **DPR 注意**:CDP 输入使用 CSS 像素;高 DPI 屏上若点击落空,用 `elementFromPoint` 校准,不要盲试坐标。
 
 ## 配置
 
-插件通过 `cordis.patch.yml` 挂载,各行的配置:
+插件通过 `cordis.patch.yml` 挂载三行,各行配置:
 
 | 行 | 配置项 | 类型 | 默认 | 说明 |
-|---|---|---|---|---|
+| --- | --- | --- | --- | --- |
 | `browser-electron` | `viewHost` | 对象 | 必填 | 宿主提供的 `ElectronBrowserViewHost` 实例(通常 `!!js ctx.get('electronViewHost')`) |
 | `browser-electron` | `httpOnly` | 布尔 | `true` | 仅允许 HTTP(S) 导航;其余协议(如 `file:`/`data:`)拒绝(`BROWSER_NAVIGATION_BLOCKED`) |
 | `browser-electron` | `snapshotMaxElements` | 数字 | `60` | 快照最多收录的交互元素数,超出截断 |
@@ -82,32 +164,6 @@ provider 与工具以 `ctx.get('electronViewHost')` 是否存在为门控,因此
 | `tool-browser` | `timeoutMs` | 数字 | `60000` | 工具协作超时(ms) |
 | `tool-browser` | `tabTools` | 布尔 | `true` | 是否注册标签管理工具(`browser_list_tabs` 等) |
 
-## 工具
-
-| 工具 | 用途 |
-|---|---|
-| `browser_open` | 打开 URL(可选新标签);返回快照 |
-| `browser_snapshot` | 交互元素(输入框/按钮/链接)带编号清单 |
-| `browser_execute` | 在页面执行 JS;参数以 `arguments[0..n]` 传入 |
-| `browser_content` | 以 html / markdown / txt / json 抓取页面(selector、maxChars、timeoutMs) |
-| `browser_screenshot` | PNG 截图,可选 `fullPage` |
-| `browser_list_tabs` / `browser_switch_tab` / `browser_close_tab` / `browser_reset` | 多标签会话管理 |
-| `browser_session` / `browser_reset_session` | 查看/重置当前任务的浏览器会话(按任务隔离) |
-| `browser_history` / `browser_replay` | 查看操作记录并回放某一步 |
-| `browser_download` | 带会话 cookie 下载 URL 到本地文件 |
-| `browser_restrict` | 限制允许的浏览器动作,防误点/误导航 |
-| `browser_auth` | 导出/恢复 cookie,持久化登录态 |
-| `browser_challenge` | 检测人机验证(CAPTCHA / Cloudflare / reCAPTCHA / hCaptcha / Turnstile)是否拦截当前页 |
-| `browser_fill` | 批量填充表单(选择器/名称/标签匹配,支持受控输入、下拉、单选/复选,可选提交) |
-
-### 操作纪律(点击/填表)
-
-- **优先用 DOM 语义而非坐标**:表单提交优先 `form.requestSubmit()`;点击优先 `element.click()`;坐标点击是最后手段。
-- **选中正确的元素**:页面常有隐藏副本(如移动端按钮),用 `browser_execute` 过滤可见元素(`getBoundingClientRect()` 宽高 > 0、`getComputedStyle` 非 `display:none`),再取坐标。
-- **取坐标后立即点击**:中间不要插入其他操作(填表、滚动会移动元素,旧坐标立即失效)。
-- **点击前验证命中**:`document.elementFromPoint(x, y)` 确认该坐标确实是目标元素(按钮/链接),再执行真实点击。
-- **DPR 注意**:CDP 输入使用 CSS 像素;高 DPI 屏上若点击落空,用 `elementFromPoint` 校准,不要盲试坐标。
-
 ## 工作原理
 
 ```
@@ -118,21 +174,73 @@ agent (browser_* 工具)
   → WebContentsView + webContents.debugger (CDP)
 ```
 
-provider 按构造与 Electron 解耦:它通过 `ElectronBrowserViewHost` 接缝操作(创建/销毁/显示视图、`sendCommand`),由真实外壳用 Electron 对象实现。同一接缝也让未来的转播 provider(无头 Chromium 截图流)服务远程部署,而无需改动工具。
+- **seam 层**(`browser` 行)提供 `ctx.browser` 服务:provider 注册、会话生命周期、错误码,与具体实现解耦;
+- **provider 层**(`browser-electron` 行)通过 `ElectronBrowserViewHost` 接缝操作视图(创建/销毁/显示/`sendCommand`),由真实外壳用 Electron 对象实现;
+- **工具层**(`tool-browser` 行)提供模型侧的 20 个 `browser_*` 工具,按调用方任务(DSH 会话)维护独立的浏览器会话。
+
+**自托管模式**:没有桌面外壳时,插件自己拉起一个 Electron 子进程(`host-main.js`),通过本机 TCP JSON-RPC 驱动,窗口标题 `dsh-browser`。子进程崩溃会自动重启;截图优先走 Electron 原生 `capturePage`(CDP 截图在多视图下会挂起),并自动选择环境中**最新版本**的 Electron(33.x 有合成器缺陷,建议 ≥ 40)。
+
+**Electron 定位顺序**:① `require('electron')`(peer 依赖)→ ② `ELECTRON_PATH`(显式覆盖)→ ③ DSH 安装锚点与 pnpm 虚拟仓库中**版本最新**者。找不到时工具会报清晰的错误提示。
 
 ## 与桌面外壳的分工
 
-浏览器**可见视图**、**浏览器列布局**、**列与视图的对齐**都属于宿主外壳(如 dsh 的 `apps/desktop`),不在本插件内。本插件只消费外壳提供的 `electronViewHost`,负责 seam、provider 与工具。若你只装插件而没有配套外壳,插件功能保持禁用。
+浏览器**可见视图**、**浏览器列布局**、**列与视图的对齐**都属于宿主外壳(如 dsh 的 `apps/desktop`),不在本插件内。本插件只消费外壳提供的 `electronViewHost`,负责 seam、provider 与工具。没有配套外壳时插件**自托管**,功能照常可用。
+
+## 环境要求
+
+- DeepSeek Harness(dsh)且安装了 `web` profile
+- **Electron 运行时**(可选 peer 依赖):桌面外壳自带;纯 `dsh web` 下插件自动定位 Electron 二进制(见上,建议 ≥ 40)
+
+### 验证过的版本
+
+| 组件 | 版本 |
+| --- | --- |
+| DeepSeek Harness(dsh) | `0.1.0-rc.5` |
+| Electron | `43.4.0`(推荐 ≥ 40;33.x 存在合成器缺陷) |
+| Node.js | `22.20.0` |
+| dsh-builtin-browser | `0.1.11` |
+| 操作系统 | Windows 10 (10.0.26200) |
+
+> 插件声明 `electron >= 30`;其他平台(macOS/Linux)按同一协议运行,但仅在上表 Windows 环境实测。
 
 ## 已知限制
 
 - 截图仅 PNG(CDP JPEG 在 Electron 43 上挂起);JPEG 等待非 CDP 转换路径。
+- 自托管截图优先走 Electron 原生 `capturePage`(CDP `captureScreenshot` 在多视图下会挂起);截图前自动把目标标签置顶。
 - 部分主机在软件合成下 `fullPage` 截图不稳定。
-- 会话按任务隔离:每个调用方任务(DSH 会话)拥有独立的浏览器会话(独立标签页与历史),并发任务互不干扰;同一任务的多次调用复用同一会话。登录态(cookie)为共享,可用 `browser_auth` 导出/恢复。
-- 人机验证(CAPTCHA)无法自动解决:快照会标注检测到的挑战(`browser_challenge` 可显式检查),此时应请用户在共享窗口中人工完成,而不是反复重试。
+- 人机验证(CAPTCHA)无法自动解决:快照会标注检测到的挑战,此时应请用户在共享窗口中人工完成,而不是反复重试。
 - 无痕模式(`privateMode`)未实现:它需要 Electron 的 session 分区能力,属于宿主层,本插件不承诺。
+- `browser_download` 在页面上下文内 `fetch`(带登录态),受同源/CORS 约束;单文件上限 256MB。
+- `browser_auth` 的 cookie 往返不保留 `hostOnly`/`sameSite` 字段(host-only cookie 恢复后变成 domain cookie);仅自托管浏览器可用。
+- 自托管浏览器子进程崩溃后会自动重启,但崩溃前已打开的会话视图已失效,调用 `browser_reset_session` 重建即可。
 - 本插件不含浏览器列 UI——那是宿主外壳的配套,别把"浏览器列"当成插件能力。
 
-## 许可证
+## 开发
+
+```sh
+# 类型检查 + 构建(lib/)
+pnpm run build
+
+# 功能测试:启动本地页面服务器 + Electron probe(见仓库测试脚本)
+```
+
+代码结构:
+
+| 目录 | 职责 |
+| --- | --- |
+| `src/browser/` | `ctx.browser` seam 与全部请求/结果类型 |
+| `src/browser-electron/` | Electron CDP provider、自托管子进程(`host-main.ts`)与 RPC 层 |
+| `src/tool-browser/` | 模型侧 `browser_*` 工具 |
+| `src/types/` | electron 环境类型(shim,避免强制依赖 electron 类型) |
+
+## 特别感谢
+
+特别感谢 [DeepSeek Harness 原始仓库](https://github.com/deepseek-ai/deepseek-harness) 与 DeepSeek AI 团队:本插件的 seam、工具运行时与插件体系都构建在这个项目之上。
+
+同时感谢 [Cordis](https://github.com/cordiverse/cordis) 提供的插件化基础,以及所有参与讨论、测试、反馈和插件开发的社区成员。
+
+## License
+
+本项目遵循 [MIT License](LICENSE)。
 
-MIT
+> 本项目是 DeepSeek Harness 的社区插件,并非 DeepSeek 官方产品。

package/lib/browser-electron/host-main.js

@@ -16,6 +16,19 @@
 import { app, BrowserWindow, WebContentsView } from 'electron';
 import { createInterface } from 'node:readline';
 import { createConnection } from 'node:net';
+import { join } from 'node:path';
+// Isolate this host's profile from the DSH app's default Electron userData:
+// several Electron instances sharing Roaming\Electron fight over the GPU
+// cache/session locks, which can leave the window without a display surface
+// (capturePage then fails). A dedicated userData also persists cookies across
+// host restarts (on top of browser_auth). Must run before app is ready.
+try {
+    const base = process.env.DSH_HOME ?? app.getPath('appData');
+    app.setPath('userData', join(base, 'dsh-builtin-browser-host'));
+}
+catch (error) {
+    process.stderr.write(`[dsh-browser host] userData setup failed: ${String(error)}\n`);
+}
 /** CDP protocol version attached to every view's debugger. */
 const CDP_VERSION = '1.3';
 /** Download cap: the body is shipped base64 as one JSON line; bound the memory. */
@@ -121,6 +134,94 @@ async function handle(op, msg) {
                 reply(msg.id, { ok: true, result });
                 return;
             }
+            case 'capture': {
+                const viewId = msg.viewId;
+                if (viewId === undefined)
+                    throw new Error('capture missing viewId');
+                const entry = views.get(viewId);
+                if (entry === undefined)
+                    throw new Error(`capture: unknown view ${viewId}`);
+                // Two complementary paths, because each has a failure mode:
+                //  - capturePage: fast and reliable with several WebContentsViews in
+                //    the window, but needs a live display surface (fails when the
+                //    window is minimized/occluded/unpainted).
+                //  - CDP Page.captureScreenshot: works without a display surface, but
+                //    can hang when another hidden WebContentsView exists in the window.
+                // Try capturePage first (show/focus/restore + one retry), then CDP.
+                if (window !== undefined) {
+                    try {
+                        if (!window.isVisible())
+                            window.show();
+                    }
+                    catch { /* closing */ }
+                    try {
+                        window.restore();
+                    }
+                    catch { /* not minimized */ }
+                    window.focus();
+                }
+                let base64 = '';
+                try {
+                    let image;
+                    try {
+                        image = await entry.webContentsView.webContents.capturePage();
+                    }
+                    catch (error) {
+                        process.stderr.write(`[dsh-browser host] capturePage failed: ${String(error)}\n`);
+                        await new Promise(resolve => setTimeout(resolve, 400));
+                        image = await entry.webContentsView.webContents.capturePage();
+                    }
+                    const png = image.toPNG();
+                    if (png.length > 0)
+                        base64 = png.toString('base64');
+                }
+                catch (error) {
+                    const state = window !== undefined
+                        ? JSON.stringify({
+                            win: { visible: window.isVisible(), minimized: window.isMinimized(), focused: window.isFocused() },
+                        })
+                        : 'no-window';
+                    process.stderr.write(`[dsh-browser host] capturePage retry failed: ${String(error)} state=${state}\n`);
+                    base64 = '';
+                }
+                if (base64 === '') {
+                    // CDP fallback. Page.captureScreenshot can hang when OTHER views
+                    // (especially hidden attach-first ones) are in the window, so
+                    // temporarily detach the siblings, capture in single-view state,
+                    // then restore them (target stays on top).
+                    const siblings = [...views.values()].filter(v => v !== entry);
+                    for (const v of siblings) {
+                        try {
+                            window?.contentView.removeChildView(v.webContentsView);
+                        }
+                        catch { /* already gone */ }
+                    }
+                    try {
+                        const shot = await entry.webContentsView.webContents.debugger.sendCommand('Page.captureScreenshot', {});
+                        const data = shot.data;
+                        if (typeof data === 'string' && data.length > 0)
+                            base64 = data;
+                    }
+                    finally {
+                        for (const v of siblings) {
+                            try {
+                                window?.contentView.addChildView(v.webContentsView);
+                            }
+                            catch { /* destroyed */ }
+                        }
+                        try {
+                            window?.contentView.removeChildView(entry.webContentsView);
+                            window?.contentView.addChildView(entry.webContentsView);
+                        }
+                        catch { /* closing */ }
+                    }
+                }
+                if (base64 === '') {
+                    throw new Error('capture produced no image (view not painted)');
+                }
+                reply(msg.id, { ok: true, result: { base64, width: 0, height: 0 } });
+                return;
+            }
             case 'download': {
                 const viewId = msg.viewId;
                 const url = msg.url;

package/lib/browser-electron/provider.d.ts

@@ -183,6 +183,8 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
         readonly dataUrl: string;
         readonly path?: string;
     }>;
+    /** Build the data URL and optionally write the PNG to disk. */
+    private saveScreenshot;
     /** Append one operation to the session's history. */
     private record;
     /** Return the session's chronological operation log (newest last). */

package/lib/browser-electron/provider.js

@@ -569,36 +569,53 @@ export class ElectronBrowserProvider {
     }
     /** Capture the current page, optionally full-page. PNG only (CDP JPEG hangs on Electron 43). */
     async screenshot(session, request, signal) {
-        const { handle } = this.activeTab(this.session(session));
+        const s = this.session(session);
+        const { handle } = this.activeTab(s);
         signal?.throwIfAborted();
+        // Native capturePage path (self-hosted): CDP Page.captureScreenshot can
+        // hang indefinitely on a view once another (hidden) WebContentsView exists
+        // in the window; capturePage is fast for visible views and resolves
+        // immediately (empty) for hidden ones.
+        const capturable = handle;
+        if (request?.fullPage !== true && typeof capturable.capture === 'function') {
+            // Ensure the target view is the visible one before capturing.
+            this.showActive(s);
+            const timeoutMs = 30_000;
+            const shot = await withTimeout(capturable.capture(), timeoutMs, signal, `browser: screenshot timed out after ${timeoutMs}ms`);
+            if (shot.base64 === '') {
+                throw new BrowserError('browser: capture returned an empty image (view not painted); retry shortly', 'BROWSER_SCREENSHOT_FAILED');
+            }
+            return this.saveScreenshot(shot.base64, request?.savePath);
+        }
+        // Fallback: a desktop-shell handle (no capture()) or a full-page capture
+        // uses CDP; full-page needs `captureBeyondViewport` which capturePage lacks.
         const params = {};
         if (request?.fullPage === true) {
             // `captureBeyondViewport` captures the full scrollable content; without
             // a clip this yields the full-page image (CDP default is the viewport).
             params.captureBeyondViewport = true;
         }
-        // Bound the capture: a view that has not painted can wedge
-        // Page.captureScreenshot indefinitely (observed after view re-showing).
         const timeoutMs = 30_000;
         const result = await withTimeout(handle.sendCommand(CDP_PAGE_CAPTURE_SCREENSHOT, params), timeoutMs, signal, `browser: screenshot timed out after ${timeoutMs}ms`);
         const data = result.data;
         if (typeof data !== 'string') {
             throw new BrowserError('browser: screenshot returned no image data', 'BROWSER_SCREENSHOT_FAILED');
         }
-        // Optional disk write so a vision tool (e.g. modlens read_image) can read
-        // the screenshot from a file path. Fire-and-forget: a write failure must
-        // not fail the capture.
-        if (request?.savePath !== undefined) {
+        return this.saveScreenshot(data, request?.savePath);
+    }
+    /** Build the data URL and optionally write the PNG to disk. */
+    saveScreenshot(base64, savePath) {
+        if (savePath !== undefined) {
             try {
-                writeFileSync(request.savePath, Buffer.from(data, 'base64'));
-                return { dataUrl: `data:image/png;base64,${data}`, path: request.savePath };
+                writeFileSync(savePath, Buffer.from(base64, 'base64'));
+                return { dataUrl: `data:image/png;base64,${base64}`, path: savePath };
             }
             catch (error) {
                 // Report the write problem but keep the capture usable.
-                throw new BrowserError(`browser: screenshot save to "${request.savePath}" failed: ${String(error)}`, 'BROWSER_SCREENSHOT_SAVE_FAILED', { cause: error });
+                throw new BrowserError(`browser: screenshot save to "${savePath}" failed: ${String(error)}`, 'BROWSER_SCREENSHOT_SAVE_FAILED', { cause: error });
             }
         }
-        return { dataUrl: `data:image/png;base64,${data}` };
+        return { dataUrl: `data:image/png;base64,${base64}` };
     }
     /** Append one operation to the session's history. */
     record(s, action, params, ok, detail) {