dsh-builtin-browser 0.4.0 → 0.4.2

package/docs/tool-reference.md

@@ -1,6 +1,6 @@
 # 工具参考
 
-全部 34 个 `browser_*` 工具。守卫列:✅ 表示该动作受 `browser_restrict` 白名单约束;只读工具永不拦截。
+全部 34 个 `browser_*` 工具。守卫列:✅ 表示该动作受 `browser_restrict` 白名单约束;**「– 豁免」表示无论白名单怎么写都不拦截**(豁免集合为 `READ_ONLY_TOOLS`,`src/tool-browser/index.ts` 导出:**只观察的工具** —— `snapshot`/`a11y`/`content`/`scrape`/`screenshot`/`get_value`/`wait`/`challenge`/`list_tabs`/`session`/`history`/`visited` —— 加上 **解除限制 / 从坏状态恢复的工具** `restrict`/`reset_session`/`reset`;`restrict` 在其中,否则限制到空的任务再也解不开);**「–」表示该工具只观察、不做动作**,故没有可拦的东西。两者之外的工具都受白名单约束 —— 例如 `browser_close_tab`、`browser_auth` 都不属于豁免集合(`browser_auth` 的 `restore` 会向任意域写 cookie,是动作,不是观察)。
 
 ## 页面与导航
 
@@ -8,16 +8,16 @@
 | --- | --- | --- | --- | --- |
 | `browser_open` | `url`(必填), `newTab?` | 快照(url/title/elements/truncated/challenge) | ✅ | 打开 URL,返回带编号元素的快照;`newTab: true` 在新标签打开 |
 | `browser_wait` | `timeoutMs?`, `url?`, `selector?` | `{ ready, reason }` | – | 等待页面加载完成(可选期望 URL / CSS 选择器);未就绪不抛错,返回原因 |
-| `browser_snapshot` | – | 快照 | – | 交互元素(输入框/按钮/链接)编号清单,供定位与点击;穿透同源 iframe 与 Shadow DOM,iframe 内元素标注 `frame` |
-| `browser_a11y` | `includeHidden?`, `maxNodes?`(10-5000,默认 500) | `{ url, title?, count, nodes[], truncated }` | – | 无障碍树:每个交互节点的 `role`/`name`/`value`/`states`/`depth`/`tag`/坐标;优先 Chrome `computedRole`/`computedName`,穿透同源 iframe 与 Shadow DOM;坐标可直接喂 `browser_click`/`browser_type` |
-| `browser_content` | `format`(html/markdown/txt/json,必填), `selector?`, `maxChars?`, `timeoutMs?` | `{ content, truncated }` | – | 抓取页面内容;`selector` 限定区域 |
+| `browser_snapshot` | – | 快照 | – | 交互元素(输入框/按钮/链接)编号清单,供定位与点击;穿透同源 iframe 与 Shadow DOM,iframe 内元素标注 `frame`。元素有 `id` 或 `name` 时,每行末尾附**可直接引用**的 `{#id}` / `{[name=x]}`(推导不出来时该段不出现),可原样作为 `browser_click`/`browser_type` 的 `target {by:"css", value:"…"}` |
+| `browser_a11y` | `includeHidden?`, `maxNodes?`(10-5000,**默认 150**), `coords?` | `{ url, title?, count, nodes[], truncated }` | – | 无障碍树:每个交互节点的 `role`/`name`/`value`/`states`/`depth`/`tag`/`selector`,优先 Chrome `computedRole`/`computedName`,穿透同源 iframe 与 Shadow DOM。**默认不返回坐标**(需要像素落点时传 `coords: true`;要按文本驱动目标,用节点的 `name` 配 `browser_click` 的 `target {by:"text"}`)。`states` **省略字面量 `enabled`（`unchecked`、`collapsed` 等仍会打印）** —— 没有 `states=` 就是 enabled;缩进为一层一个空格 |
+| `browser_content` | `format`(html/markdown/txt/json,必填), `selector?`, `maxChars?`, `timeoutMs?` | `{ content, truncated }` | – | 抓取页面内容;`selector` 限定区域。**字符上限按格式**(默认):`html`/`json` **50 000**,`txt`/`markdown` **20 000**,单次调用用 `maxChars` 覆盖;被截断时结果末尾提示如何收窄。`json` 返回 `{"html": "<元素 outerHTML>", "tag": "<标签名>"}` —— 不是空对象(DOM 节点自身没有可枚举属性,`JSON.stringify` 一个元素只会得到 `{}`) |
 | `browser_challenge` | – | `{ blocked, kind?, reason?, hint? }` | – | 检测人机验证(CAPTCHA/Cloudflare/reCAPTCHA/hCaptcha/Turnstile);阻塞时请用户处理 |
 
 ## 页面操作
 
 | 工具 | 参数 | 输出 | 守卫 | 说明 |
 | --- | --- | --- | --- | --- |
-| `browser_execute` | `script`(必填), `args?` | `{ ok, value? / exception? }` | ✅ | 在页面执行 JS;脚本以 `return` 开头或作为表达式;`args` 以 `arguments[0..n]` 传入 |
+| `browser_execute` | `script`(必填), `args?` | `{ ok, value? / exception? }` | ✅ | 在页面执行 JS;脚本以 `return` 开头或作为表达式;`args` 以 `arguments[0..n]` 传入。**返回值上限 50 000 字符**,超出时结果里写明"截断于 50 000 / 实际 N 字符"(要完整内容请让表达式返回更小的值)。受设置「Agent 能做什么 → 允许在页面里执行脚本」门控,关闭后一律被拒(`BROWSER_EXECUTE_DISABLED`),且没有任何工具能把它打开 |
 | `browser_click` | `target?`(css/text/xpath), `x?`, `y?`(target 与坐标二选一) | `{ clicked }` | ✅ | 语义目标点击:按 `target` 定位、滚动到视口中央再点中心;或视口坐标点击(配合截图做视觉定位) |
 | `browser_type` | `text`(必填), `target?` | `{ typed }` | ✅ | 输入文本;传 `target` 先聚焦该元素(CDP `Input.insertText`) |
 | `browser_key` | `key`(必填,枚举) | `{ pressed }` | ✅ | 按命名按键:Enter/Tab/Escape/Backspace/Delete/方向键/Home/End/PageUp/PageDown/Space |
@@ -30,41 +30,41 @@
 | `browser_check` | `target`(必填), `checked?` | `{ checked }` | ✅ | 勾选/取消勾选 checkbox 或 radio(按 target 定位) |
 | `browser_select` | `target`(必填), `optionValue?`/`optionText?`/`optionIndex?`(三选一) | `{ value, text }` | ✅ | 选中 `<select>` 的某个选项(按 target 定位) |
 | `browser_clear` | `target`(必填) | `{ cleared }` | ✅ | 清空输入/文本域/contenteditable,或取消勾选 checkbox/radio |
-| `browser_get_value` | `target`(必填) | `{ value?, checked?, selectedText? }` | – | 读取元素当前值,用于操作后验证 |
-| `browser_scrape` | `item`(必填), `fields`(必填,映射), `timeoutMs?` | `{ count, items[] }` | – | 结构化提取:容器选择器 + 字段映射(如 `{"title": "h3", "url": "a@href"}`);静态 CSS 查询、不执行任意代码、CSP 安全;等待 item 出现(默认 5s) |
+| `browser_get_value` | `target`(必填) | `{ value?, checked?, selectedText? }` | – 豁免 | 读取元素当前值,用于操作后验证 |
+| `browser_scrape` | `item`(必填), `fields`(必填,映射), `timeoutMs?` | `{ count, items[] }` | – 豁免 | 结构化提取:容器选择器 + 字段映射(如 `{"title": "h3", "url": "a@href"}`);静态 CSS 查询、不执行任意代码、CSP 安全;等待 item 出现(默认 5s)。**结果是最紧凑的 JSON**(不缩进),条目数在最前面 |
 
 ## 标签与会话
 
 | 工具 | 参数 | 输出 | 守卫 | 说明 |
 | --- | --- | --- | --- | --- |
-| `browser_list_tabs` | – | `{ session, tabs[] }` | – | 当前会话的标签列表 |
+| `browser_list_tabs` | – | `{ tabs: [{ id, url, active }] }` | – | 当前会话的标签列表(输出 schema 只有 `tabs`,**没有 `session` 字段**;会话标识请用 `browser_session`) |
 | `browser_switch_tab` | `tabId`(必填) | `{ switched }` | ✅ | 按 id 切换标签;自托管下同步切换可见视图 |
-| `browser_close_tab` | `tabId`(必填) | `{ closed }` | – | 关闭标签;关闭活动标签后激活下一个 |
-| `browser_reset` | – | `{ reset }` | ✅ | 关闭本任务所有标签,回到一个空白标签 |
+| `browser_close_tab` | `tabId`(必填) | `{ closed }` | ✅ | 关闭标签;关闭活动标签后激活下一个。**不属于只读豁免集合,受白名单约束**;`tabId` 只在本会话内查找(接受 `tab:<uuid>` 或裸 uuid),陈旧 id 不会关掉别的任务的标签页 |
+| `browser_reset` | – | `{ reset }` | – 豁免 | 关闭本任务所有标签,回到一个空白标签(列入 `READ_ONLY_TOOLS`:限制到空的任务也必须能复位,否则白名单成了陷阱) |
 | `browser_session` | – | `{ session, tabs[] }` | – | 查看本任务的浏览器会话与标签 |
-| `browser_reset_session` | – | `{ reset }` | ✅ | 关闭并重建本任务的浏览器会话(崩溃/卡死后恢复) |
+| `browser_reset_session` | – | `{ reset }` | – 豁免 | 关闭并重建本任务的浏览器会话(崩溃/卡死后恢复;同上,永远可用) |
 
 ## 历史与下载
 
 | 工具 | 参数 | 输出 | 守卫 | 说明 |
 | --- | --- | --- | --- | --- |
-| `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_history` | `verbose?` | `{ entries[] }` | – | 操作日志(最新在后),含 seq/action/ok/params/result/error。**默认只渲染最近 20 条,且不显示每条的参数**(参数就是你刚发出去的),首行先给总条数,免得把尾部当成全部;要看参数时传 `verbose: true`。返回的完整 `entries[]` 不受条数限制 |
+| `browser_visited` | `limit`(默认 30,上限 200), `domain`(主机名包含匹配), `query`(URL 或标题包含匹配), `session`(按来源会话标签过滤) | `{ count, entries[] }` | – | **持久化浏览历史**(访问过的页面,最新在前):与 cookie 同址落盘(`$DSH_HOME/dsh-builtin-browser-host/history.jsonl`),关闭浏览器与重启 DSH 后仍在;上限 5000 条或 90 天。重开某条用 `browser_open`;与 `browser_history`(会话内操作日志,随会话消失)是两件事;可在设置里关闭记录。渲染时**时间戳精确到分钟**,会话标记**只在切换时打印一次并取 8 位前缀** |
 | `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 约束;由子进程直接落盘) |
+| `browser_download` | `url`(必填), `savePath`(必填) | `{ path }` | ✅ | 带会话 cookie 下载到本地(仅 http(s);`savePath` 必须为绝对路径且位于 `downloadDir` 内——默认系统下载目录,自动识别 `Downloads`/`下载`/`下載` 与 `XDG_DOWNLOAD_DIR`;不覆盖已有文件;上限 256MB,受 CORS 约束;由子进程直接落盘)。受设置「允许下载文件到磁盘」门控(`BROWSER_DOWNLOAD_DISABLED`) |
 
 ## 登录态与安全
 
 | 工具 | 参数 | 输出 | 守卫 | 说明 |
 | --- | --- | --- | --- | --- |
-| `browser_auth` | `action`(flush/restore,必填), `cookies?` | `{ cookies[]? / restored? }` | ✅ | 导出/恢复 cookie(自托管可用);flush 返回 cookie 列表,restore 带列表写回 |
-| `browser_restrict` | `allowed?` | `{ restrictedTo[] }` | – | 设置动作白名单;空列表解除;未知工具名报错。**软护栏**——模型可自行解除,非安全边界 |
+| `browser_auth` | `action`(flush/restore,必填), `cookies?` | `{ cookies[]? / restored? }` | ✅ | 导出/恢复 cookie —— **三种载体都可用**:自托管走原生会话,桌面侧栏与本机 Chrome/Edge 走 CDP 的 `Network.getCookies` / `Storage.setCookies`;flush 返回 cookie 列表,restore 带列表写回。**flush 只导出当前页所属站点的 cookie**(不是整台机器的共享 cookie 罐),范围按本会话所在页面的 URL 收敛;**范围未知时直接拒绝而不是放宽**(自托管侧栏载体报"cookie 范围未知",CDP 载体报 `BROWSER_AUTH_SCOPE_UNKNOWN`)。`restored` 反映真的提交了多少(无法构成有效 URL 的 cookie 会被丢弃并报出条数)。**受白名单约束**:`restore` 会向任意域写 cookie,是动作而非观察,因此该工具**不在只读豁免集合**里。设置里「允许读取 cookies / 导出登录状态」关闭时,flush 与 restore **都**抛 `BROWSER_AUTH_DISABLED`。导出受设置「凭据」门控(`BROWSER_AUTH_DISABLED`),写入受「允许写入登录状态」门控(`BROWSER_AUTH_WRITE_DISABLED`)—— 两者独立 |
+| `browser_restrict` | `allowed?` | `{ restrictedTo[] }` | – | 设置动作白名单;空列表解除;**只校验名字是否以 `browser_` 开头**(写错的前缀会报错,`browser_typo` 这种拼错但前缀合法的名字会被接受、等同于拦掉该名字,不额外报错);守卫按名字匹配,因此白名单里列什么名字就只放行什么名字。**软护栏**——模型可自行解除,非安全边界 |
 
 ## 截图
 
 | 工具 | 参数 | 输出 | 守卫 | 说明 |
 | --- | --- | --- | --- | --- |
-| `browser_screenshot` | `fullPage?`, `savePath?`, `format?`(png/jpeg), `quality?`, `maxWidth?`, `maxHeight?` | `{ dataUrl, path? }` | – | 截图;PNG 默认,JPEG 仅自托管原生路径;`maxWidth`/`maxHeight` 等比缩放降低视觉模型开销;`savePath` 落盘供视觉模型读取(与 `browser_download` 同一准入门:必须位于 `downloadDir` 内且不覆盖已有文件) |
+| `browser_screenshot` | `fullPage?`, `savePath?`, `format?`(png/jpeg), `quality?`, `maxWidth?`, `maxHeight?` | `{ dataUrl, path? }` | – | 截图;PNG 默认,**JPEG 在自托管与本机 Chrome/Edge 上都可用**(自托管在原生 `capturePage` 路径编码,本机浏览器经 CDP 声明 `supportsCdpJpeg`;**桌面侧栏**的 Electron CDP JPEG 编码器会挂起,该载体下 JPEG 请求返回 PNG);`maxWidth`/`maxHeight` 等比缩放**三种载体都支持**;`fullPage` 会跳过原生 `capturePage`、三种载体统一走 CDP `captureBeyondViewport`;`savePath` 落盘供视觉模型读取(与 `browser_download` 同一准入门:必须位于 `downloadDir` 内且不覆盖已有文件) |
 
 ## 常用组合
 

package/docs/user-guide.md

@@ -17,10 +17,11 @@ dsh plugin --profile web add dsh-builtin-browser
 dsh plugin --profile web add <本仓库路径>
 ```
 
-安装会链接插件、把 `dsh-builtin-browser` 加入 profile 的 bundle 层,并挂载三行:
+安装会链接插件、把 `dsh-builtin-browser` 加入 profile 的 bundle 层,并挂载四行(一个惰性的根行 + 三个功能行):
 
 | 行 | 子路径 | 角色 |
 | --- | --- | --- |
+| `dsh-builtin-browser` | 包名本身 | **惰性根行**:不注册任何东西(空 `apply()`),只用来声明包名 —— 宿主的客户端插件扫描靠精确包名读到 `dsh.client`,少了这行设置栏不会出现 |
 | `browser` | `dsh-builtin-browser/browser` | `ctx.browser` 能力 seam(始终挂载) |
 | `browser-electron` | `dsh-builtin-browser/browser-electron` | Electron CDP provider |
 | `tool-browser` | `dsh-builtin-browser/tool-browser` | `browser_*` 模型侧工具 |
@@ -31,10 +32,10 @@ dsh plugin --profile web add <本仓库路径>
 
 | 行 | 配置项 | 类型 | 默认 | 说明 |
 | --- | --- | --- | --- | --- |
-| `browser-electron` | `viewHost` | 对象 | 必填 | 宿主提供的 `ElectronBrowserViewHost`(通常 `!!js ctx.get('electronViewHost')`) |
+| `browser-electron` | `viewHost` | 对象 | 可选 | 宿主提供的 `ElectronBrowserViewHost`(通常 `!!js ctx.get('electronViewHost')`)。**不传时插件自己选载体**:桌面端驱动官方侧栏、否则自托管;设置里显式选择的 Chrome/Edge 优先于两者 |
 | `browser-electron` | `httpOnly` | 布尔 | `true` | 仅允许 HTTP(S) 导航;`file:`/`data:` 等拒绝 |
 | `browser-electron` | `snapshotMaxElements` | 数字 | `60` | 快照最多收录的交互元素数 |
-| `browser-electron` | `contentMaxChars` | 数字 | `100000` | 内容抓取默认字符上限 |
+| `browser-electron` | `contentMaxChars` | 数字 | **不再被读取(已废弃)** | 曾经的"内容抓取默认字符上限"。**现在没有任何代码读它,改它不改变任何行为** —— 上限按格式固定:html 50 000、json 50 000、txt 20 000、markdown 20 000,单次调用用 `maxChars` 覆盖。保留该键只为不让既有配置因未知键而报错 |
 | `browser-electron` | `downloadDir` | 字符串 | 系统下载目录(自动识别 `Downloads`/`下载`/`下載`,或 `XDG_DOWNLOAD_DIR`) | 限定 `browser_download` 与 `browser_screenshot` 保存路径必须位于该目录内且不覆盖已有文件;默认收敛到系统下载目录,可改沙箱目录 |
 | `tool-browser` | `timeoutMs` | 数字 | `60000` | 工具协作超时(ms) |
 | `tool-browser` | `tabTools` | 布尔 | `true` | 是否注册标签管理工具 |
@@ -66,7 +67,7 @@ dsh plugin --profile web add <本仓库路径>
 - `browser_session` 查看本任务的会话与标签;
 - `browser_reset_session` 关闭并重建本任务的会话(崩溃或卡死后用它恢复)。
 
-登录态(cookie)为所有任务共享;可用 `browser_auth` 导出/恢复,重启后不丢。
+登录态(cookie)为所有任务共享;可用 `browser_auth` 导出/恢复,重启后不丢。注意 **`flush` 只导出当前页所属站点的 cookie**(按本会话所在页面的 URL 收敛),页面 URL 未知时**直接拒绝**而不是扩大范围去读整台机器的 cookie 罐;`restore` 会向任意域写 cookie,所以 `browser_auth` **同样受 `browser_restrict` 白名单约束**,不属于只读豁免。
 
 ## FAQ
 
@@ -84,12 +85,20 @@ DSH Desktop 上②命中即可用(0.1.18+ 插件自带 electron 包;44+ 二进
 **Q:浏览器窗口不见了?**
 窗口标题为 `dsh-browser`(自托管)。若子进程崩溃(或宿主 DSH 重启)会自动重启;崩溃前已打开的会话在**下一次调用时自动重建**——仅页面状态丢失,无需手动 `browser_reset_session`。`browser_reset_session` 仍可用于主动重置。
 
+**Q:设置里的 `contentMaxChars` 改了没反应?**
+因为它**已经没有任何代码在读** —— 那是内容上限改为按格式固定之后的遗留键(html/json 50 000,txt/markdown 20 000)。上限请用单次调用的 `maxChars` 覆盖。
+
+**Q:本机 Chrome / Edge 被关掉之后还能继续用吗?**
+能。该载体观察进程退出并清掉**已失效的会话映射**,下一次调用会**重新拉起**浏览器并继续工作;重新拉起前会先 kill 旧进程并**最多等 3 秒**它真正退出,且**只认本次启动写下的 `DevToolsActivePort`**(被杀掉的浏览器没机会清理那个文件,照读会连到别的 Chromium 或 `node --inspect` 上)。反过来,页面只是**慢**不会让插件杀掉你的窗口:命令超时只把连接标记为存疑,下一次调用先用 `Browser.getVersion` 探一次再决定是否丢弃,只有 socket 已关闭才重启。
+
 **Q:下载报 CORS 错误?**
 `browser_download` 在页面上下文内 `fetch`,受同源/CORS 约束;跨域文件请先在同源页面内操作,或直接请求用户提供。仅支持 HTTP(S) URL;`savePath` 必须为绝对路径且位于 `downloadDir` 内(默认系统下载目录,自动识别 `Downloads`/`下载`/`下載`),不覆盖已有文件;`browser_screenshot` 的 `savePath` 受同一套限制。
 
 **Q:如何禁止 agent 乱点?**
 `browser_restrict` 设置白名单(如只允许 `browser_snapshot`/`browser_content`);传空列表解除。注意它是防误操作的**软护栏**,模型可自行解除,不是安全边界。
 
+要一个**模型自己解不掉**的限制,用设置页「Agent 能做什么」的三个开关(执行页面脚本 / 下载文件到磁盘 / 写入登录状态):它们写在设置文档里,而没有任何工具能写那个文档,所以模型只能被拒 —— 这与 `browser_restrict` 的区别不是"谁更强",而是"谁能改"。部署级(对所有人生效)还可以用 `tool-browser` 的 `allowedActions` 配置,见 `cordis.patch.yml` 的注释。
+
 ## 故障排查
 
 | 现象 | 可能原因 | 处理 |

package/docs/why-browser.md

@@ -32,8 +32,8 @@ LLM agent 需要"上网"。传统做法是给 agent 一个**无头浏览器**(Pl
 
 ## 设计取舍
 
-- **登录态共享**:所有任务共享同一份 cookie(符合"用户登录一次,agent 到处可用");需要隔离时用 `browser_auth` 手动导出/恢复。
-- **任务级会话隔离**:每个 DSH 会话(任务)拥有独立的浏览器会话(标签页与历史),并发任务互不抢页面;但窗口只有一个,当前活动的任务视图可见。
+- **登录态共享**:所有任务共享同一份 cookie(符合"用户登录一次,agent 到处可用");需要搬运时用 `browser_auth` 手动导出/恢复 —— 它的 `flush` **只导出当前页所属站点的 cookie**(按本会话所在页面的 URL 收敛,页面 URL 未知时拒绝而不是放宽),所以"导出"是逐站点的一步,不是一次性打包整个 cookie 罐。
+- **任务级会话隔离**:每个 DSH 会话(任务)拥有独立的浏览器会话(标签页与历史),并发任务互不抢页面;自托管载体下**每个会话连窗口都各自一份**(窗口按会话 id 分组,窗口标题带任务标识),侧栏与本机浏览器载体则是同一个宿主里切换当前可见视图。
 - **装好即用**:不依赖桌面外壳。有外壳时嵌入外壳视图;纯 `dsh web` 时插件自托管——自己拉起 Electron 窗口,通过本机 TCP JSON-RPC 驱动。
 - **边界清晰**:可见视图、浏览器列布局属于宿主外壳;插件只负责 seam、provider 与工具,不含任何 UI。
 - **人机验证不硬刚**:检测到 Cloudflare/reCAPTCHA/hCaptcha/Turnstile 时停下,请用户在共享窗口人工完成,而不是盲目重试。

package/lib/browser/types.d.ts

@@ -240,6 +240,14 @@ export interface BrowserWaitResult {
 export interface BrowserScreenshotResult {
     /** Base64 data URL of the capture (PNG or JPEG per the request). */
     readonly dataUrl: string;
+    /** Pixel size of the image in `dataUrl`, when the capture was measured and scaled.
+     *
+     * Present when the request carried `maxWidth`/`maxHeight` and the layout metrics were
+     * readable: the scaling happens inside CDP through a clip, and without this the only way to
+     * learn what came back was to decode the data URL. Undefined means "not measured", which is
+     * also what an unscaled capture reports. */
+    readonly width?: number;
+    readonly height?: number;
     /** File path the capture was also saved to, when the request asked for it. */
     readonly path?: string;
 }
@@ -366,6 +374,14 @@ export interface BrowserA11yNode {
     readonly depth: number;
     /** Element tag name (lowercase). */
     readonly tag: string;
+    /**
+     * A CSS selector for this node, when one can be derived from its id or name.
+     *
+     * Empty for the many elements that have neither. Present because a role and a name are not
+     * always enough to target a node: `{by: 'text'}` matches an accessible name only loosely,
+     * and this is what lets a caller point at the exact element it was shown.
+     */
+    readonly selector: string;
     /** Viewport-relative center, for coordinate fallbacks. */
     readonly x: number;
     readonly y: number;
@@ -460,7 +476,15 @@ export interface BrowserProvider {
     /**
      * Open a new session. The provider mints the session id and prepares its
      * backing surface (a view, a headless page, and so on). Sessions are isolated from
-     * each other; a session must not be visible to any other session's caller.
+     * each other in what they OWN — tabs, the active tab, history, the view — so one
+     * session must not be visible to any other session's caller.
+     *
+     * That isolation stops at the browser's own state, and is not meant to go further:
+     * cookies, logins and site storage are deliberately shared by every session, because
+     * every session drives the same browser and "sign in once, use it everywhere" is the
+     * point of using a real one. Reads that hand that state to a caller (see
+     * `flushAuth`) are scoped to the page in question, which is least exposure rather
+     * than a claim that the jar is per-session.
      * @param label - optional human-readable label (e.g. the calling DSH task
      * id) the provider may surface on the visible surface (window title) so a
      * human can tell which task's page is currently shown.

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

@@ -27,22 +27,44 @@ export interface BridgeEndpoint {
 /**
  * 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.
+ * Requests may be in flight CONCURRENTLY, so answers are correlated by id rather than by
+ * position: `call()` stamps a unique {@link REQUEST_ID_FIELD} on the request and `onData()`
+ * resolves the entry that carries the echoed id. A bridge that does not echo it is still
+ * supported — its answer is handed to the oldest outstanding request, which is the
+ * arrival-order rule the protocol states. Once such an answer has been seen, the connection
+ * stops keeping two requests in flight (a second one re-dials), so position can never be the
+ * only thing distinguishing two callers' answers. An answer that matches nothing is never
+ * handed to whichever request happens to be first: the socket is dropped instead.
+ *
+ * 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;
+    /** Outstanding requests by id. */
+    private readonly pending;
+    /** Ids of the requests sent on the current socket, oldest first. */
     private readonly queue;
+    private nextId;
+    /** True once any reply arrived without an id: this bridge does not echo request ids. */
+    private idLessBridge;
+    /** True once this connection may only have one request in flight at a time. */
+    private serialisable;
     /**
      * @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).
+     *
+     * Requests may overlap: the request is written as soon as it is queued, so two concurrent
+     * callers have two requests in flight. Each carries a unique {@link REQUEST_ID_FIELD}, and
+     * `onData()` resolves the entry that carries the echoed id — which is what makes
+     * correlation independent of arrival order. A bridge that does not echo the field (the
+     * shipped shell today) still works by arrival order; see {@link onData}.
+     * @param request - the request body (the token and the request id are added here).
      * @param timeoutMs - how long to wait for the answer before dropping the socket.
      * @returns the bridge's answer.
      */
@@ -51,8 +73,12 @@ export declare class BridgeConnection {
     close(): void;
     /** The live socket, connecting and authenticating it on first use. */
     private ensureSocket;
-    /** Resolve queued requests in order as answers arrive. */
+    /** Tear the connection down for an event raised by `source`, unless it is already gone. */
+    private socketFailed;
+    /** Resolve queued requests by id, or in order when the bridge does not echo one. */
     private onData;
+    /** Forget one request (its answer can no longer be matched). */
+    private forget;
     /** Tear the socket down, failing pending work. */
     private reset;
 }

package/lib/browser-electron/bridge-connection.js

@@ -18,18 +18,48 @@
  * @module dsh-browser/browser-electron/bridge-connection
  */
 import { connect } from 'node:net';
+/**
+ * Safety cap on one un-answered reply line. CDP answers from the sidebar (a screenshot's
+ * base64 is the big one) cross this socket, so the cap is generous; what it exists for is a
+ * peer that never sends a newline — `this.buffer += chunk` grew without bound, unlike the
+ * same buffer in remote-host.ts, which caps at 512 MiB.
+ */
+const MAX_BUFFER_BYTES = 128 * 1024 * 1024;
+/**
+ * Field this client adds to every request so the shell can echo it back and never relies on
+ * byte order to pair an answer with its request. Loosely named, and additive on purpose: a
+ * bridge that does not know it simply ignores it (the current shipped shell does), and the
+ * client then falls back to arrival order, which is what the protocol guaranteed before.
+ */
+const REQUEST_ID_FIELD = 'bridgeRequestId';
 /**
  * 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.
+ * Requests may be in flight CONCURRENTLY, so answers are correlated by id rather than by
+ * position: `call()` stamps a unique {@link REQUEST_ID_FIELD} on the request and `onData()`
+ * resolves the entry that carries the echoed id. A bridge that does not echo it is still
+ * supported — its answer is handed to the oldest outstanding request, which is the
+ * arrival-order rule the protocol states. Once such an answer has been seen, the connection
+ * stops keeping two requests in flight (a second one re-dials), so position can never be the
+ * only thing distinguishing two callers' answers. An answer that matches nothing is never
+ * handed to whichever request happens to be first: the socket is dropped instead.
+ *
+ * A broken socket is discarded so the next call dials again — a dead connection must never
+ * become a dead plugin.
  */
 export class BridgeConnection {
     endpoint;
     socket;
     buffer = '';
+    /** Outstanding requests by id. */
+    pending = new Map();
+    /** Ids of the requests sent on the current socket, oldest first. */
     queue = [];
+    nextId = 1;
+    /** True once any reply arrived without an id: this bridge does not echo request ids. */
+    idLessBridge = false;
+    /** True once this connection may only have one request in flight at a time. */
+    serialisable = false;
     /**
      * @param endpoint - the shell's published bridge endpoint.
      */
@@ -38,33 +68,67 @@ export class BridgeConnection {
     }
     /**
      * Send one request, reusing the socket if it is still healthy.
-     * @param request - the request body (the token is added here).
+     *
+     * Requests may overlap: the request is written as soon as it is queued, so two concurrent
+     * callers have two requests in flight. Each carries a unique {@link REQUEST_ID_FIELD}, and
+     * `onData()` resolves the entry that carries the echoed id — which is what makes
+     * correlation independent of arrival order. A bridge that does not echo the field (the
+     * shipped shell today) still works by arrival order; see {@link onData}.
+     * @param request - the request body (the token and the request id are added here).
      * @param timeoutMs - how long to wait for the answer before dropping the socket.
      * @returns the bridge's answer.
      */
     async call(request, timeoutMs = 20_000) {
-        const socket = this.ensureSocket();
+        // One re-dial, and only for the case this exists for: a socket that has already carried
+        // an id-less answer cannot have a second request in flight, because two outstanding
+        // requests would be matched by position — the swap this correlation prevents. It is a
+        // straight-line re-dial rather than a retry loop: an earlier revision re-entered call()
+        // from inside its own promise executor, which left an orphaned pending entry behind and,
+        // when the condition could not clear, spun until the process ran out of heap.
+        let socket = this.ensureSocket();
+        if (this.serialisable && this.queue.length > 0) {
+            this.reset(new Error('dsh-builtin-browser: bridge connection reopened so replies stay attributable'));
+            socket = this.ensureSocket();
+        }
+        const id = this.nextId++;
         return await new Promise((resolve, reject) => {
+            this.pending.set(id, {
+                resolve: answer => { clearTimeout(timer); resolve(answer); },
+                reject: error => { clearTimeout(timer); reject(error); },
+            });
+            this.queue.push(id);
             const timer = setTimeout(() => {
-                const index = this.queue.findIndex(entry => entry.resolve === resolve);
-                if (index !== -1)
-                    this.queue.splice(index, 1);
                 const error = new Error(`dsh-builtin-browser: bridge timed out after ${timeoutMs}ms`);
-                this.reset(error);
+                // An unanswered request desynchronises the stream for an id-less bridge, and leaves one
+                // outstanding for one that echoes ids — either way the next call should start on a
+                // fresh socket. Only when THIS request's socket is still the live one: tearing down the
+                // REPLACEMENT because an abandoned request timed out would break whatever is using it.
+                //
+                // This test used to read `this.pending.has(id) && this.socket === socket`, with
+                // `forget(id)` on the line above it — and forget() is what removes the entry that `has`
+                // was looking for, so the condition was false every single time and the rebuild never
+                // ran. A timed-out call therefore left the desynchronised socket in place, and every
+                // later call inherited exactly the ambiguity this reset exists to clear. Deciding
+                // before forgetting is the whole fix; the `else` still drops the stale entry.
+                if (this.socket === socket)
+                    this.reset(error);
+                else
+                    this.forget(id);
+                // reset() already rejected this entry through its wrapper when it ran, so this is
+                // either the only rejection or a no-op that guarantees the caller settles.
                 reject(error);
             }, timeoutMs);
-            this.queue.push({
-                resolve: answer => { clearTimeout(timer); resolve(answer); },
-                reject: error => { clearTimeout(timer); reject(error); },
-            });
             try {
-                socket.write(JSON.stringify({ token: this.endpoint.token, ...request }) + '\n');
+                // The id is added LAST so a request body can never shadow it, and the token is
+                // added here rather than by the caller.
+                socket.write(JSON.stringify({ token: this.endpoint.token, ...request, [REQUEST_ID_FIELD]: id }) + '\n');
             }
             catch (error) {
                 clearTimeout(timer);
-                this.queue.pop();
+                this.forget(id);
                 const failure = error instanceof Error ? error : new Error(String(error));
-                this.reset(failure);
+                if (this.socket === socket)
+                    this.reset(failure);
                 reject(failure);
             }
         });
@@ -80,16 +144,33 @@ export class BridgeConnection {
         const socket = connect({ host: '127.0.0.1', port: this.endpoint.port });
         socket.setEncoding('utf8');
         socket.on('data', chunk => this.onData(String(chunk)));
-        socket.on('error', error => this.reset(error));
-        socket.on('close', () => this.reset(new Error('dsh-builtin-browser: bridge connection closed')));
+        // Both handlers pass the socket they belong to, so a late event from a socket that was
+        // already replaced cannot tear down its successor: 'close' still fires for a socket that
+        // was removed mid-recycle, and acting on it there would kill a perfectly good connection.
+        socket.on('error', error => this.socketFailed(socket, error));
+        socket.on('close', () => this.socketFailed(socket, new Error('dsh-builtin-browser: bridge connection closed')));
         this.buffer = '';
         this.socket = socket;
         socket.write(JSON.stringify({ token: this.endpoint.token }) + '\n');
         return socket;
     }
-    /** Resolve queued requests in order as answers arrive. */
+    /** Tear the connection down for an event raised by `source`, unless it is already gone. */
+    socketFailed(source, error) {
+        if (this.socket !== source)
+            return;
+        this.reset(error);
+    }
+    /** Resolve queued requests by id, or in order when the bridge does not echo one. */
     onData(chunk) {
         this.buffer += chunk;
+        // A peer that never sends a newline must not grow this buffer without bound. Failing
+        // the connection is the honest outcome: the caller gets an error naming the cap, while
+        // the next call dials a fresh socket.
+        if (this.buffer.length > MAX_BUFFER_BYTES) {
+            this.buffer = '';
+            this.reset(new Error(`dsh-builtin-browser: bridge reply exceeded ${String(MAX_BUFFER_BYTES)} bytes`));
+            return;
+        }
         let newline = this.buffer.indexOf('\n');
         while (newline !== -1) {
             const line = this.buffer.slice(0, newline).trim();
@@ -97,9 +178,28 @@ export class BridgeConnection {
             newline = this.buffer.indexOf('\n');
             if (line === '')
                 continue;
-            const entry = this.queue.shift();
+            const echoed = echoOf(line);
+            const id = echoed ?? this.queue[0];
+            if (id === undefined) {
+                // Nothing is waiting for this answer: the peer is answering something this socket
+                // never asked (or answered twice). Drop the socket rather than trust the stream.
+                this.reset(new Error('dsh-builtin-browser: bridge answered with no request outstanding'));
+                return;
+            }
+            const index = this.queue.indexOf(id);
+            if (index !== -1)
+                this.queue.splice(index, 1);
+            const entry = this.pending.get(id);
             if (entry === undefined)
                 continue;
+            this.pending.delete(id);
+            // Id-less bridges pair by order, so a reply for the WRONG request cannot be told apart
+            // from the right one. Remember that this bridge does not echo ids, and serialise every
+            // later call so the ambiguity cannot arise again.
+            if (echoed === undefined) {
+                this.idLessBridge = true;
+                this.serialisable = true;
+            }
             try {
                 const answer = JSON.parse(line);
                 // A rejected token means the shell restarted with a new one, so this socket
@@ -117,6 +217,13 @@ export class BridgeConnection {
             }
         }
     }
+    /** Forget one request (its answer can no longer be matched). */
+    forget(id) {
+        this.pending.delete(id);
+        const index = this.queue.indexOf(id);
+        if (index !== -1)
+            this.queue.splice(index, 1);
+    }
     /** Tear the socket down, failing pending work. */
     reset(error) {
         if (this.socket !== undefined) {
@@ -126,8 +233,23 @@ export class BridgeConnection {
             socket.destroy();
         }
         this.buffer = '';
-        const pending = this.queue.splice(0, this.queue.length);
+        this.queue.length = 0;
+        const pending = [...this.pending.values()];
+        this.pending.clear();
         for (const entry of pending)
             entry.reject(error);
     }
 }
+/** The request id a raw answer line echoes back, when it carries one. */
+function echoOf(line) {
+    try {
+        const answer = JSON.parse(line);
+        const value = answer[REQUEST_ID_FIELD];
+        return typeof value === 'number' && Number.isSafeInteger(value) ? value : undefined;
+    }
+    catch {
+        // A malformed line cannot be matched by id; the caller consumes it in order and
+        // reports the parse failure itself.
+        return undefined;
+    }
+}

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

@@ -34,7 +34,7 @@ export interface Config {
     readonly downloadDir?: string;
     /** Maximum snapshot elements before truncation. Default 60. */
     readonly snapshotMaxElements?: number;
-    /** Maximum content characters before truncation when no maxChars is given. Default 100_000. */
+    /** Maximum content characters before truncation when no maxChars is given. No longer read: the cap is per format (html and json 50 000, otherwise 20 000). */
     readonly contentMaxChars?: number;
 }
 export declare const Config: z<Config>;