dsh-browser-plus 0.5.0 → 0.5.1

package/client/index.js

@@ -0,0 +1,185 @@
+/**
+ * dsh-browser-plus — client half.
+ *
+ * One right-sidebar tab whose whole job is to put the shared browser window on
+ * screen: picking it from the rightbar's add list opens the window, and the
+ * panel keeps a button for raising it again. It is named after the plugin and
+ * carries the plugin's own mark, so it is not confused with the product's
+ * built-in browser tab. It talks to the plugin's own
+ * HTTP route (`src/http-browser/index.ts`), because a third-party client bundle
+ * has no generated Remote surface to call a server-side method through.
+ *
+ * This file is the browser bundle's source in the client-modules factory
+ * format: running it only registers the factory, and the module body runs when
+ * the plugin is first materialized. `scripts/build-client.mjs` copies it to
+ * `lib/client.js` — it is one file with no imports beyond the platform table,
+ * so no bundler is involved.
+ */
+window.__ModuleLoader__.load({
+  id: 'dsh-browser-plus',
+  factory: (require) => {
+    var module = { exports: {} }
+    var exports = module.exports
+    Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
+    const React = require('react')
+
+    /** Implementation identity; also the key its body registers under. */
+    const IMPLEMENTATION_ID = 'dsh-browser-plus'
+    /** Tab kind: a page type, opened by kind and recognizing no address. */
+    const KIND = 'dsh-browser-plus'
+    const OPEN_PATH = '/api/dsh-browser-plus/open'
+    const STATUS_PATH = '/api/dsh-browser-plus/status'
+
+    const COPY = {
+      zh: {
+        title: 'DSH-Browser-Plus',
+        description: '打开共享浏览器窗口',
+        open: '打开浏览器窗口',
+        busy: '正在打开…',
+        opened: '浏览器窗口已打开。',
+        failed: '打开失败：',
+        tasks: (count) => (count > 0 ? '当前有 ' + String(count) + ' 个浏览器任务' : '还没有浏览器任务'),
+      },
+      en: {
+        title: 'DSH-Browser-Plus',
+        description: 'Open the shared browser window',
+        open: 'Open browser window',
+        busy: 'Opening…',
+        opened: 'The browser window is open.',
+        failed: 'Could not open it: ',
+        tasks: (count) => (count > 0 ? String(count) + ' browser task(s) open' : 'no browser task yet'),
+      },
+    }
+
+    /** The panel's copy, read at render so a language switch needs no reload. */
+    function copy() {
+      try {
+        const declared = String(document.documentElement.getAttribute('lang') || navigator.language || '')
+        return declared.toLowerCase().indexOf('zh') === 0 ? COPY.zh : COPY.en
+      } catch (error) {
+        return COPY.zh
+      }
+    }
+
+    /** POST the open endpoint; resolve to a message, never throw at the renderer. */
+    function requestOpen() {
+      return fetch(OPEN_PATH, { method: 'POST' }).then((response) => response.json().catch(() => null).then((body) => {
+        if (!response.ok || body === null || body.ok !== true) {
+          throw new Error(body !== null && typeof body.error === 'string' ? body.error : 'HTTP ' + String(response.status))
+        }
+        return true
+      }))
+    }
+
+    /** Read the task count for the status line; a failure is not worth a notice. */
+    function requestStatus() {
+      return fetch(STATUS_PATH).then((response) => response.json()).then((body) => (body !== null && body.ok === true && typeof body.tasks === 'number' ? body.tasks : null)).catch(() => null)
+    }
+
+    /**
+     * The plugin's own mark, inlined from assets/dsh-browser-plus.svg so the
+     * bundle keeps requiring nothing but the platform table. The plate is part
+     * of the art: it is what keeps a white outline legible on a light surface.
+     */
+    function BrowserIcon(props) {
+      const size = props !== null && props !== undefined && props.size !== undefined ? props.size : 36
+      return React.createElement('svg', {
+        width: size,
+        height: size,
+        className: props !== null && props !== undefined ? props.className : undefined,
+        'aria-hidden': 'true',
+        viewBox: '0 0 256 256',
+        xmlns: 'http://www.w3.org/2000/svg',
+      },
+        React.createElement('rect', { x: 10, y: 10, width: 236, height: 236, rx: 54, fill: '#202124' }),
+        React.createElement('g', { transform: 'translate(20 20) scale(9)', fill: 'none', stroke: '#ffffff', strokeWidth: 1.8, strokeLinecap: 'round', strokeLinejoin: 'round' },
+          React.createElement('rect', { x: 3.25, y: 4.75, width: 17.5, height: 14.5, rx: 3.25 }),
+          React.createElement('path', { d: 'M3.25 9.4h17.5' }),
+          React.createElement('circle', { cx: 6.15, cy: 7.05, r: 0.9, fill: '#ffffff', stroke: 'none' }),
+          React.createElement('circle', { cx: 8.75, cy: 7.05, r: 0.9, fill: '#ffffff', stroke: 'none' }),
+        ),
+      )
+    }
+
+    const PANEL_STYLE = {
+      display: 'flex',
+      flexDirection: 'column',
+      gap: '10px',
+      padding: '16px',
+      color: 'inherit',
+      font: 'inherit',
+    }
+    const BUTTON_STYLE = {
+      alignSelf: 'flex-start',
+      padding: '6px 14px',
+      border: '1px solid currentColor',
+      borderRadius: '6px',
+      background: 'transparent',
+      color: 'inherit',
+      font: 'inherit',
+      cursor: 'pointer',
+    }
+    const NOTE_STYLE = { opacity: 0.7, fontSize: '12px' }
+
+    /** The panel body: it opens the window as soon as it is mounted. */
+    function BrowserPanel() {
+      const t = copy()
+      const [busy, setBusy] = React.useState(false)
+      const [note, setNote] = React.useState(null)
+      const [tasks, setTasks] = React.useState(null)
+
+      const open = React.useCallback(() => {
+        setBusy(true)
+        setNote(null)
+        requestOpen()
+          .then(() => {
+            setBusy(false)
+            setNote({ ok: true, text: t.opened })
+            return requestStatus().then((count) => setTasks(count))
+          })
+          .catch((error) => {
+            setBusy(false)
+            setNote({ ok: false, text: t.failed + String(error !== null && error !== undefined && error.message !== undefined ? error.message : error) })
+          })
+      }, [t])
+
+      // The tab itself is the affordance: opening it opens the window.
+      React.useEffect(() => {
+        open()
+        requestStatus().then((count) => setTasks(count))
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+      }, [])
+
+      return React.createElement('div', { style: PANEL_STYLE },
+        React.createElement('button', { type: 'button', style: BUTTON_STYLE, disabled: busy, onClick: open }, busy ? t.busy : t.open),
+        note !== null ? React.createElement('div', { style: NOTE_STYLE, role: 'status' }, note.text) : null,
+        tasks !== null ? React.createElement('div', { style: NOTE_STYLE }, t.tasks(tasks)) : null,
+      )
+    }
+
+    exports.inject = ['slots', 'sidebarRightTabs']
+    exports.apply = (ctx) => {
+      const slots = ctx.get('slots')
+      const tabs = ctx.get('sidebarRightTabs')
+      if (slots === undefined || tabs === undefined) return
+      ctx.effect(() => tabs.register({
+        id: IMPLEMENTATION_ID,
+        kind: KIND,
+        priority: 'extension',
+        title: () => copy().title,
+        guide: [{
+          id: 'open',
+          order: 40,
+          title: () => copy().title,
+          description: () => copy().description,
+          icon: BrowserIcon,
+        }],
+      }), 'dsh-browser-plus:type')
+      ctx.effect(() => slots.inject('sidebar.right.pane.tab', () => slots.register({
+        name: 'sidebar.right.pane.tab',
+        key: IMPLEMENTATION_ID,
+      }, BrowserPanel)), 'dsh-browser-plus:body')
+    }
+    return module.exports
+  },
+})

package/cordis.patch.yml

@@ -5,6 +5,13 @@
 # and otherwise the plugin self-hosts its own Electron window, so installing
 # the plugin is enough for the browser to work anywhere.
 - insert:
+    # Root row: no behaviour of its own, but the client module system only reads
+    # a package's `dsh.client` from a Loader row whose specifier is the EXACT
+    # package root (a subpath resolves to undefined and is skipped). Without this
+    # row the Web GUI panel is never composed, however many subpath rows exist.
+    - id: browser-plus
+      name: dsh-browser-plus
+
     - id: browser
       name: dsh-browser-plus/browser
 
@@ -15,3 +22,20 @@
 
     - id: tool-browser
       name: dsh-browser-plus/tool-browser
+
+    # Human-facing `/browser`: opens/raises the shared window without the model.
+    # Its own row on purpose — a composition without the command registry must
+    # still get the tools above.
+    - id: browser-command
+      name: dsh-browser-plus/command-browser
+
+    # The Web GUI panel's bridge: opens/raises the window from a button in the
+    # right sidebar. Needs the web server, so it is its own row too.
+    - id: browser-http
+      name: dsh-browser-plus/http-browser
+
+    # Bridges the Agent's todo list (DSH session projection) into the browser, so
+    # the floating orb can show what the Agent is working on. Its own row because
+    # it needs optional services the browser itself does not.
+    - id: browser-task-todos
+      name: dsh-browser-plus/task-todos

package/docs/README.md

@@ -6,7 +6,7 @@
 | --- | --- |
 | 了解插件为什么存在、与无头方案的区别 | [为什么做共享真实浏览器](why-browser.md) |
 | 安装、配置、日常使用与常见问题 | [用户指南](user-guide.md) |
-| 全部 41 个工具的参数、输出与示例 | [工具参考](tool-reference.md) |
+| 全部 43 个工具的参数、输出与示例 | [工具参考](tool-reference.md) |
 | 了解 seam / provider / 工具三层与自托管实现 | [架构说明](architecture.md) |
 | 重启 DSH 后的运行时验证清单 | [SOAK-CHECKLIST](SOAK-CHECKLIST.md) |
 | 切换到 dsh-browser-plus 与登录态搬运 | [迁移指南](MIGRATION.md) |

package/docs/SOAK-CHECKLIST.md

@@ -7,7 +7,7 @@
 ```bash
 npm run smoke:browser-tools
 ```
-用**真实 Electron 宿主 + 真实 Chromium** 驱动**真实 provider**,覆盖 **31 项**:
+用**真实 Electron 宿主 + 真实 Chromium** 驱动**真实 provider**,覆盖 **87 项**(具体数字以脚本输出的 `passed` / `failed` 为准):
 
 - **provider 层(12 项)**:navigate / content / snapshot / screenshot / **click 三种寻址(坐标、选择器、文字)** /
   目标缺失的错误码 / waitForElement / **scrape 并发** / **cookie 导出→文件→清除→导入往返** / listTabs。

package/docs/tool-reference.md

@@ -1,6 +1,6 @@
 # 工具参考
 
-全部 41 个 `browser_*` 工具。守卫列:✅ 表示该动作受 `browser_restrict` 白名单约束(白名单**按调用任务隔离**,一个任务的规则不影响其它任务);只读工具永不拦截。
+全部 43 个 `browser_*` 工具。守卫列:✅ 表示该动作受 `browser_restrict` 白名单约束(白名单**按调用任务隔离**,一个任务的规则不影响其它任务);只读工具永不拦截。
 
 ## 页面与导航
 
@@ -13,7 +13,7 @@
 | `browser_reload` | – | `{ reloaded }` | ✅ | 刷新当前页 |
 | `browser_stop` | – | `{ stopped }` | ✅ | 停止当前页加载 |
 | `browser_scroll` | `deltaX?`, `deltaY?` | `{ x,y,maxX,maxY }` | ✅ | 按 CSS 像素滚动;无参数时向下一个视口 |
-| `browser_wait_for` | `selector`(必填), `timeoutMs?`, `visible?` | `{ found, selector, tag, text? }` | ✅ | 等待 CSS 选择器匹配的元素出现且可见(250ms 轮询,默认 15s 超时);SPA 动态内容交互前使用 |
+| `browser_wait_for` | `selector?`, `text?`, `state?`, `timeoutMs?`, `visible?` | `{ found, state, selector, tag, text? }` | ✅ | 等元素或文字出现 / 消失;**选择器与文字至少给一个**;`hidden` 与 `detached` 必须给选择器(要知道等谁消失) |
 | `browser_content` | `format`(html/markdown/txt/json,必填), `selector?`, `maxChars?`, `timeoutMs?` | `{ content, truncated }` | – | 抓取页面内容;`selector` 限定区域 |
 | `browser_challenge` | – | `{ blocked, kind?, reason?, hint? }` | – | 检测人机验证(CAPTCHA/Cloudflare/reCAPTCHA/hCaptcha/Turnstile);阻塞时请用户处理 |
 
@@ -68,11 +68,13 @@
 | --- | --- | --- | --- | --- |
 | `browser_scrape` | `action?`(start/status/stop/list), `urls?`, `script?`, `outPath?`, `waitFor?`, `timeoutMs?`, `concurrency?`, `id?` | `{ id?, state?, total?, done?, failed?, path?, error?, jobs[]? }` | ✅ | 后台批量访问 URL,把**每页一行 JSON** 追加到文件,结果**不经模型往返**——一千条与一条的 token 成本相同。`action=start` 立即返回,用 `action=status` 轮询。每行是 `{ seq, url, ok, data }` 或 `{ seq, url, ok, error }`(`seq` = 该 URL 在输入里的下标;并发时行按**完成顺序**落盘,按 `seq` 排序即可还原),**产生即落盘**,所以 `stop` 或中断都保留已抓到的行;单页失败不终止整批(计入 `failed`)。`outPath` 受 `writeRoots` 限制并在开始时截断。批次使用**自己的标签页**(不激活,所以不会抢走你正在看的页面,也不与同任务的工具调用争用),结束后销毁。`concurrency` 默认 1、上限 8,每个 worker 占一个标签页;后台批次**跳过 250ms 的绘制等待**(它只读 DOM 不读像素),实测单页开销约 6ms。
 
-## 截图
+## 截图与打印
 
 | 工具 | 参数 | 输出 | 守卫 | 说明 |
 | --- | --- | --- | --- | --- |
 | `browser_screenshot` | `fullPage?`, `savePath?` | `{ dataUrl, path? }` | – | PNG 截图;`savePath` 落盘供视觉模型读取,且必须落在 `browser-electron.writeRoots` 之内 |
+| `browser_pdf` | `savePath`(必填), `landscape?`, `printBackground?`, `paperWidth?`, `paperHeight?` | `{ path, bytes }` | ✅ | 把当前标签打印成 PDF(Chrome 的「另存为 PDF」);`savePath` 必须落在 `browser-electron.writeRoots` 之内。走宿主的 `webContents.printToPDF`,**不是** CDP 的 `Page.printToPDF` —— Electron 的 debugger 没有那个方法;`paperWidth`/`paperHeight` 是**英寸**(宿主内部换算成微米),默认 8.5×11。`printBackground` 默认 true,否则深色页面会印成白纸。 |
+| `browser_highlight` | `selector?`, `clear?` | `{ matched, cleared, nodeId?, box? }` | ✅ | 用 DevTools 那套高亮框套住 `selector` 的第一个匹配元素,让**看着窗口的人**知道 Agent 正要动哪里;走 CDP Overlay,**不改页面 DOM**。`box` 与 `getBoundingClientRect()` 逐位一致(实测偏差 ~2e-6 px)。注意高亮框**不在页面渲染里**,所以 `browser_screenshot` 拍不到它 —— 要看它得抓真窗口。`clear: true` 撤掉;选择器没匹配到返回 `matched: false`。 |
 
 ## 对话框与诊断
 

package/docs/user-guide.md

@@ -8,20 +8,27 @@
 ## 安装
 
 ```sh
-# 从 npm 安装(已发布)
+# 从 npm 安装
+# dsh plugin --profile web add dsh-browser-plus
+
+# 或从 GitHub 安装(未发布新版本时用这条)
 dsh plugin --profile web add github:ParticleLight/dsh-browser-plus
 
 # 或从源码目录(独立仓库,一插件一仓库)
 dsh plugin --profile web add <本仓库路径>
 ```
 
-安装会链接插件、把 `dsh-browser-plus` 加入 profile 的 bundle 层,并挂载三行:
+安装会链接插件、把 `dsh-browser-plus` 加入 profile 的 bundle 层,并挂载 **7 行**:
 
 | 行 | 子路径 | 角色 |
 | --- | --- | --- |
 | `browser` | `dsh-browser-plus/browser` | `ctx.browser` 能力 seam(始终挂载) |
 | `browser-electron` | `dsh-browser-plus/browser-electron` | Electron CDP provider |
 | `tool-browser` | `dsh-browser-plus/tool-browser` | `browser_*` 模型侧工具 |
+| `browser-plus`(根行) | `dsh-browser-plus` | **空行为**的根行:只为让客户端半边(右侧栏面板)被 client-modules 扫到 |
+| `browser-command` | `dsh-browser-plus/command-browser` | `/browser` 斜杠命令(需要 `commands`) |
+| `browser-http` | `dsh-browser-plus/http-browser` | 面板用的 HTTP 路由(需要 `webServer`) |
+| `browser-task-todos` | `dsh-browser-plus/task-todos` | 把 Agent 的 `todo_write` 计划推给悬浮球(依赖可选的 `sessionProjections`) |
 
 > 没有桌面外壳时插件**自托管**:自己拉起一个标题为 `dsh-browser-plus` 的 Electron 窗口,`browser_*` 工具照常可用。
 
@@ -51,6 +58,15 @@ dsh plugin --profile web add <本仓库路径>
 6. 遇到验证码(browser_challenge 或快照标注 CHALLENGE)时,调用 browser_handoff state=waiting-user,停下等待用户交还任务
 ```
 
+## 打开浏览器窗口
+
+窗口默认只在 Agent 第一次调用浏览器工具时出现。人也可以自己打开它:
+
+- **`/browser` 命令** —— 在输入框敲 `/`(或点 `+`)选「浏览器」,回车即打开或前置窗口。它**不产生模型消息**,只是把窗口带到眼前。
+- **右侧栏「DSH-Browser-Plus」** —— 在右侧栏的「添加」列表里选它(名字和图标都是这个插件自己的,避免和 DSH 自带的「浏览器」撞名),面板打开的同时窗口就被带出来了;面板里还有一个按钮可以随时再前置一次,并显示当前有几个浏览器任务。
+
+> 右侧栏里 DSH 自带的「浏览器」是另一个东西:DSH 自己的沙箱 iframe 浏览器,与这个自托管窗口无关。
+
 ## 操作纪律
 
 - **优先用快照引用**:先取得 `snapshotId`,再用 `browser_click_ref` 或 `browser_scroll_into_view`;引用过期时重新快照，而不是猜测同名控件。
@@ -68,7 +84,7 @@ dsh plugin --profile web add <本仓库路径>
 
 当前版本使用**一个共享可见浏览器窗口**，每个任务仍有隔离的任务视图、标签与历史。页面任务管理器切换可见任务；后台任务操作只更新自己的视图，不会抢走当前页面。`browser_space label="..."` 为本浏览器任务命名，`browser_space`(无参)列出全部浏览器任务。
 
-工具栏默认收在页面上方。鼠标移到页面顶部中间时会出现小圆形下箭头，点击后工具栏从上方滑出；工具栏最右侧的上箭头会收回工具栏，并同时关闭书签、任务与轨迹浮层。任务按钮打开左侧工作区面板，操作轨迹按钮在桌面端打开右侧工作区面板。顶部工具栏最右侧常驻“接管 / 交还 Agent”控件，不必先打开任务面板；任务卡继续显示执行中、等待用户、用户接管、失败和空闲状态。接管期间新的 Agent 页面操作会停止，快照和内容读取仍可用于确认状态。
+工具栏是**常驻顶栏**：和标签栏一起占视图的高度（84px，开书签栏时 118px），页面**不需要为它让位**，也不会滑出或收回。任务按钮打开左侧工作区面板，操作轨迹按钮在桌面端打开右侧工作区面板。顶部工具栏最右侧常驻“接管 / 交还 Agent”控件，不必先打开任务面板；任务卡继续显示执行中、等待用户、用户接管、失败和空闲状态。接管期间新的 Agent 页面操作会停止，快照和内容读取仍可用于确认状态。
 
 用户直接点击页面、编辑表单或使用非滚动键盘操作时，会自动切换为用户控制；滚轮、触摸拖动、滚动条操作，以及页面非编辑区的上下翻页键不会触发接管。Agent 自己的 CDP 鼠标和键盘输入带有短暂抑制标记，不会误交还控制权。
 
@@ -94,7 +110,7 @@ dsh plugin --profile web add <本仓库路径>
 确认运行时是 Electron `42.9.3`，不要用 43.x。自托管截图优先走原生 `capturePage`，共享窗口内存在多个视图且目标未激活时自动兜底到 CDP。
 
 **Q:浏览器窗口不见了?**
-窗口标题为 `dsh-browser-plus`(显示当前任务标签时为 `dsh-browser-plus — <名>`)；所有任务共享这一可见窗口，通过页面任务管理器切换各自隔离视图。若子进程崩溃会自动重启;重启后旧会话失效,调用 `browser_reset_session` 重建。
+想主动把它叫回来:输入框里敲 `/browser`(或点 `+` 选「浏览器」),或者在右侧栏的「添加」列表里选「DSH-Browser-Plus」—— 两者都会打开或前置窗口,且**不产生模型消息**。窗口标题为 `dsh-browser-plus`(显示当前任务标签时为 `dsh-browser-plus — <名>`)；所有任务共享这一可见窗口，通过页面任务管理器切换各自隔离视图。若子进程崩溃会自动重启;重启后旧会话失效,调用 `browser_reset_session` 重建。
 
 **Q:下载报 CORS 错误?**
 `browser_download` 在页面上下文内 `fetch`,受同源/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 { BrowserContentRequest, BrowserHandoffState, BrowserContentResult, BrowserDownloadRequest, BrowserExecuteRequest, BrowserExecuteResult, BrowserFillRequest, BrowserFillResult, BrowserHistoryEntry, BrowserNavigateRequest, BrowserOpenOptions, BrowserOpenRequest, BrowserDragRequest, BrowserDragResult, BrowserPointerResult, BrowserPointerTarget, BrowserPressKeyRequest, BrowserClearAuthRequest, BrowserScrapeRequest, BrowserScrapeStatus, BrowserClearAuthResult, BrowserProvider, BrowserRefRequest, BrowserScreenshotRequest, BrowserScreenshotResult, BrowserScrollIntoViewRequest, BrowserScrollRequest, BrowserScrollResult, BrowserSessionId, BrowserSnapshotResult, BrowserSpaceInfo, BrowserTaskInfo, BrowserTaskUpdate, BrowserTab, BrowserTypeRequest, BrowserUploadFileRequest, BrowserUploadFileResult, BrowserWaitForRequest, BrowserWaitForResult, BrowserChallenge, ExportedCookie } from './types.ts';
+import type { BrowserContentRequest, BrowserHandoffState, BrowserContentResult, BrowserDownloadRequest, BrowserExecuteRequest, BrowserExecuteResult, BrowserFillRequest, BrowserFillResult, BrowserHistoryEntry, BrowserNavigateRequest, BrowserOpenOptions, BrowserOpenRequest, BrowserDragRequest, BrowserDragResult, BrowserPointerResult, BrowserPointerTarget, BrowserPressKeyRequest, BrowserClearAuthRequest, BrowserScrapeRequest, BrowserScrapeStatus, BrowserClearAuthResult, BrowserProvider, BrowserRefRequest, BrowserScreenshotRequest, BrowserScreenshotResult, BrowserScrollIntoViewRequest, BrowserScrollRequest, BrowserScrollResult, BrowserSessionId, BrowserSnapshotResult, BrowserSpaceInfo, BrowserTaskInfo, BrowserTaskUpdate, BrowserTab, BrowserTypeRequest, BrowserUploadFileRequest, BrowserUploadFileResult, BrowserPdfRequest, BrowserPdfResult, BrowserHighlightRequest, BrowserHighlightResult, BrowserWaitForRequest, BrowserWaitForResult, BrowserChallenge, BrowserTaskTodo, ExportedCookie } from './types.ts';
 export { BrowserError, } from './types.ts';
 export type { BrowserChallenge, BrowserContentFormat, BrowserControlOwner, BrowserContentRequest, BrowserContentResult, BrowserDownloadRequest, BrowserExecuteRequest, BrowserExecuteResult, BrowserFillField, BrowserFillRequest, BrowserFillResult, BrowserHandoffState, BrowserHistoryEntry, BrowserNavigateRequest, BrowserOpenOptions, BrowserOpenRequest, BrowserDragRequest, BrowserDragResult, BrowserPointerResult, BrowserPointerTarget, BrowserPressKeyRequest, BrowserClearAuthRequest, BrowserScrapeRequest, BrowserScrapeStatus, BrowserClearAuthResult, BrowserProvider, BrowserRefRequest, BrowserScreenshotRequest, BrowserScreenshotResult, BrowserScrollIntoViewRequest, BrowserScrollRequest, BrowserScrollResult, BrowserSessionId, BrowserSnapshotElement, BrowserSnapshotResult, BrowserSpaceInfo, BrowserTaskInfo, BrowserTaskStatus, BrowserTaskUpdate, BrowserTab, BrowserTypeRequest, BrowserUploadFileRequest, BrowserUploadFileResult, BrowserWaitForRequest, BrowserWaitForResult, ExportedCookie, } from './types.ts';
 declare module '@deepseek-ai/cordis' {
@@ -168,6 +168,8 @@ export declare class BrowserRuntime extends Service {
     /** Attach a local file to a file input through the selected provider. */
     uploadFile(session: BrowserSessionId, request: BrowserUploadFileRequest, signal?: AbortSignal): Promise<BrowserUploadFileResult>;
     /** Wait for an element through the selected provider (bounded polling). */
+    highlight(session: BrowserSessionId, request: BrowserHighlightRequest, signal?: AbortSignal): Promise<BrowserHighlightResult>;
+    pdf(session: BrowserSessionId, request: BrowserPdfRequest, signal?: AbortSignal): Promise<BrowserPdfResult>;
     waitForElement(session: BrowserSessionId, request: BrowserWaitForRequest, signal?: AbortSignal): Promise<BrowserWaitForResult>;
     /** Type into the focused element through the selected provider. */
     type(session: BrowserSessionId, request: BrowserTypeRequest, signal?: AbortSignal): Promise<void>;
@@ -218,6 +220,17 @@ export declare class BrowserRuntime extends Service {
     updateTask(session: BrowserSessionId, update: BrowserTaskUpdate): Promise<BrowserTaskInfo>;
     /** Mark one session as waiting for the user or returned to Agent control. */
     setHandoff(session: BrowserSessionId, state: BrowserHandoffState): Promise<BrowserTaskInfo>;
+    /**
+     * Bring the shared browser window to the front through the selected
+     * provider, opening it when nothing is open yet.
+     */
+    ensureWindowVisible(): Promise<void>;
+    /**
+     * Mirror one task's Agent todo list into the shared window (the floating orb
+     * reads it there). A provider without a window has nowhere to put it, so this
+     * is a no-op rather than an error.
+     */
+    pushTaskTodos(taskKey: string, todos: readonly BrowserTaskTodo[]): Promise<void>;
     /** Close the session through the selected provider. Idempotent; a missing
      *  provider is treated as already-closed so teardown paths stay no-ops. */
     close(session: BrowserSessionId): Promise<void>;

package/lib/browser/runtime.js

@@ -190,6 +190,12 @@ export class BrowserRuntime extends Service {
         return this.resolveProvider().uploadFile(session, request, signal);
     }
     /** Wait for an element through the selected provider (bounded polling). */
+    async highlight(session, request, signal) {
+        return this.resolveProvider().highlight(session, request, signal);
+    }
+    async pdf(session, request, signal) {
+        return this.resolveProvider().pdf(session, request, signal);
+    }
     async waitForElement(session, request, signal) {
         return this.resolveProvider().waitForElement(session, request, signal);
     }
@@ -281,6 +287,28 @@ export class BrowserRuntime extends Service {
     async setHandoff(session, state) {
         return this.resolveProvider().setHandoff(session, state);
     }
+    /**
+     * Bring the shared browser window to the front through the selected
+     * provider, opening it when nothing is open yet.
+     */
+    async ensureWindowVisible() {
+        const provider = this.resolveProvider();
+        if (provider.ensureWindowVisible === undefined) {
+            throw new BrowserError('browser: this provider has no window to open', 'BROWSER_WINDOW_UNSUPPORTED');
+        }
+        return provider.ensureWindowVisible();
+    }
+    /**
+     * Mirror one task's Agent todo list into the shared window (the floating orb
+     * reads it there). A provider without a window has nowhere to put it, so this
+     * is a no-op rather than an error.
+     */
+    async pushTaskTodos(taskKey, todos) {
+        const provider = this.resolveProvider();
+        if (provider.pushTaskTodos === undefined)
+            return;
+        return provider.pushTaskTodos(taskKey, todos);
+    }
     /** Close the session through the selected provider. Idempotent; a missing
      *  provider is treated as already-closed so teardown paths stay no-ops. */
     async close(session) {

package/lib/browser/types.d.ts

@@ -131,24 +131,79 @@ export interface BrowserUploadFileResult {
     /** The path uploaded. */
     readonly path: string;
 }
-/** Wait for an element matching a CSS selector to appear (optionally visible). */
+/** Which state a wait is watching for. */
+export type BrowserWaitForState = 'visible' | 'attached' | 'hidden' | 'detached';
+/** Wait for a selector, some text, or both to reach a state. */
 export interface BrowserWaitForRequest {
-    /** CSS selector to wait for. */
-    readonly selector: string;
+    /** CSS selector to wait for. Omit to watch the document's own text (give `text`). */
+    readonly selector?: string;
+    /** Text that must be present: inside the matched element when a selector is given, otherwise anywhere in the document. */
+    readonly text?: string;
+    /**
+     * The state to wait for. `visible` (the default) needs a matching element at least 4x4 px and not
+     * visibility:hidden / display:none; `attached` only needs it to exist; `hidden` and `detached`
+     * wait for the opposite, so they are how you wait for something to go away.
+     */
+    readonly state?: BrowserWaitForState;
     /** Total budget in ms. Default 15000. */
     readonly timeoutMs?: number;
-    /** Wait for the element to be visible (at least 4x4 px and not visibility:hidden or display:none). Default true. */
+    /** Back-compat for `state: 'attached'` (`visible: false`). Prefer `state`. */
     readonly visible?: boolean;
 }
 /** Outcome of a successful wait. */
 export interface BrowserWaitForResult {
+    /** The awaited condition is now true. */
     readonly found: true;
+    /** Which state was awaited. */
+    readonly state: BrowserWaitForState;
+    /** The selector waited on, or `''` for a text-only wait. */
     readonly selector: string;
-    /** Matching element's tag name. */
+    /** Matched element's tag name, or `''` when nothing matched (a `detached` wait). */
     readonly tag: string;
-    /** Matching element's visible text (first 200 chars). */
+    /** Matched element's visible text (first 200 chars), or the document text that satisfied a text wait. */
     readonly text: string;
 }
+/** Print the active tab to a PDF file. */
+export interface BrowserPdfRequest {
+    /** Absolute path of the .pdf to write. Must be inside the write roots. */
+    readonly savePath: string;
+    /** Landscape orientation. Default portrait. */
+    readonly landscape?: boolean;
+    /** Include background colours and images. Default true. */
+    readonly printBackground?: boolean;
+    /** Paper width in inches. CDP default is 8.5. */
+    readonly paperWidth?: number;
+    /** Paper height in inches. CDP default is 11. */
+    readonly paperHeight?: number;
+}
+/** Where the PDF landed. */
+export interface BrowserPdfResult {
+    readonly path: string;
+    readonly bytes: number;
+}
+/** Draw or clear the DevTools-style highlight box over a selector's first match. */
+export interface BrowserHighlightRequest {
+    /** CSS selector whose first match to highlight. Ignored when clear is true. */
+    readonly selector?: string;
+    /** Remove any existing highlight instead of drawing one. */
+    readonly clear?: boolean;
+}
+/** What the highlight call found. */
+export interface BrowserHighlightResult {
+    /** A match was found and highlighted. */
+    readonly matched: boolean;
+    /** The highlight was cleared. */
+    readonly cleared: boolean;
+    /** CDP node id of the match, when there was one. */
+    readonly nodeId?: number;
+    /** Content box in CSS pixels, when the element has one. */
+    readonly box?: {
+        readonly x: number;
+        readonly y: number;
+        readonly width: number;
+        readonly height: number;
+    };
+}
 /** One field of a batch form fill. Match by selector, or by name/label/placeholder. */
 export interface BrowserFillField {
     /** CSS selector; when present, candidates are scoped to it. */
@@ -326,6 +381,17 @@ export interface BrowserSnapshotElement {
     /** Viewport-relative center, for coordinate fallbacks. */
     readonly x: number;
     readonly y: number;
+    /** Index into `frames` when the element lives inside an iframe; absent at the top level. */
+    readonly frame?: number;
+}
+/** One iframe found on the page. */
+export interface BrowserSnapshotFrame {
+    /** Index into the page's iframe list; matches `BrowserSnapshotElement.frame`. */
+    readonly index: number;
+    /** The frame's src, or its document URL when it has one. */
+    readonly url: string;
+    /** False when the frame is cross-origin, so its contents cannot be read. */
+    readonly readable: boolean;
 }
 /**
  * AI-friendly page snapshot: a compact, numbered inventory of interactive
@@ -342,6 +408,8 @@ export interface BrowserSnapshotResult {
     readonly elements: readonly BrowserSnapshotElement[];
     /** True when the snapshot was truncated (element cap reached). */
     readonly truncated: boolean;
+    /** Every iframe on the page, including the cross-origin ones that could not be read. */
+    readonly frames?: readonly BrowserSnapshotFrame[];
     /** Human-verification challenge blocking the page, when one is detected. */
     readonly challenge?: BrowserChallenge;
     /** True when a human interacted with the page within the last minute. */
@@ -588,6 +656,10 @@ export interface BrowserProvider {
     uploadFile(session: BrowserSessionId, request: BrowserUploadFileRequest, signal?: AbortSignal): Promise<BrowserUploadFileResult>;
     /** Wait until an element matching the selector exists (and optionally is visible). Honor `signal` for cancellation. */
     waitForElement(session: BrowserSessionId, request: BrowserWaitForRequest, signal?: AbortSignal): Promise<BrowserWaitForResult>;
+    /** Print the active tab to a PDF file. */
+    pdf(session: BrowserSessionId, request: BrowserPdfRequest, signal?: AbortSignal): Promise<BrowserPdfResult>;
+    /** Draw or clear the DevTools-style highlight box over a selector's first match. */
+    highlight(session: BrowserSessionId, request: BrowserHighlightRequest, signal?: AbortSignal): Promise<BrowserHighlightResult>;
     /** Fill a form's fields in one batch. Honor `signal` for cancellation. */
     fillForm(session: BrowserSessionId, request: BrowserFillRequest, signal?: AbortSignal): Promise<BrowserFillResult>;
     /** Capture the current page. Honor `signal` for cancellation. */
@@ -636,6 +708,24 @@ export interface BrowserProvider {
     setHandoff(session: BrowserSessionId, state: BrowserHandoffState): Promise<BrowserTaskInfo>;
     /** Close the session and destroy its backing surface. Idempotent. */
     close(session: BrowserSessionId): Promise<void>;
+    /**
+     * Bring the shared browser window to the front, creating it (and a default
+     * session) when nothing is open yet. Optional: a provider whose browser has
+     * no window of its own omits it, and callers must report that as unsupported
+     * rather than pretending a window was raised.
+     */
+    ensureWindowVisible?(): Promise<void>;
+    /**
+     * Mirror one task's Agent todo list into the shared window, where the floating
+     * orb renders it. Optional: a provider without a window of its own omits it.
+     * `taskKey` is the same task key the tools use (the calling Agent's id).
+     */
+    pushTaskTodos?(taskKey: string, todos: readonly BrowserTaskTodo[]): Promise<void>;
+}
+/** One entry of an Agent's todo list, as the floating orb shows it. */
+export interface BrowserTaskTodo {
+    readonly content: string;
+    readonly status: 'pending' | 'in_progress' | 'completed';
 }
 /** One recorded browser operation, in chronological order (seq 1, 2, 3…). */
 export interface BrowserHistoryEntry {

package/lib/browser-electron/chrome-state.d.ts

@@ -118,10 +118,24 @@ export interface ChromeWorkspaceState {
      * rounds before this made it visible.
      */
     readonly windowProbe?: string;
+    /** Where the human dragged the floating orb, in page CSS pixels. */
+    readonly orbPosition?: {
+        readonly x: number;
+        readonly y: number;
+    };
 }
 export interface ChromeBootstrapMessage extends ChromeWorkspaceState {
     readonly kind: 'bootstrap';
 }
+/**
+ * One entry of the Agent's todo list (`todo_write`) as the floating orb renders
+ * it: the same three states the model writes, so the orb spins on
+ * `in_progress` and ticks `completed` without translating anything.
+ */
+export interface ChromeTaskTodo {
+    readonly content: string;
+    readonly status: 'pending' | 'in_progress' | 'completed';
+}
 export type ChromePatchOperation = {
     readonly op: 'task.upsert';
     readonly task: ChromeTaskSummary;
@@ -136,6 +150,16 @@ export type ChromePatchOperation = {
     readonly key: string;
     readonly version: number;
     readonly dataUrl?: string;
+}
+/**
+ * The Agent's todo list for one task. Like the thumbnail it is NOT part of a
+ * summary — summaries are injected into every visited page's main world, and
+ * this is the Agent's own plan — so it travels only as a targeted patch.
+ */
+ | {
+    readonly op: 'task.todos';
+    readonly key: string;
+    readonly todos: readonly ChromeTaskTodo[];
 } | {
     readonly op: 'trail.append';
     readonly taskKey: string;

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

@@ -38,11 +38,18 @@ export interface Config {
      */
     readonly readRoots?: string[];
     /**
-     * Which JavaScript world the injected page chrome lives in. `main` (default)
-     * is the proven path; `isolated` keeps the chrome's task state and its
-     * binding token out of the page's own context, at the cost of an extra CDP
-     * context per document. Opt in only after confirming the toolbar in a real
-     * window (see docs/SOAK-CHECKLIST.md).
+     * Which JavaScript world the injected page chrome lives in.
+     *
+     * `isolated` (default) keeps the chrome's task state — including the Agent's
+     * plan, which the floating orb renders — and its binding token out of the
+     * page's own context: the page's scripts see `undefined` for every `__dsh*`
+     * global instead of a readable copy. It costs one extra CDP context per
+     * document, and the chrome reads the DOM through that context (the DOM itself
+     * is shared, so element lookups and layout still work).
+     *
+     * `main` puts everything in the page's world: the proven-against-everything
+     * path, but a page can read the plan by hooking `Map.prototype.set` or
+     * `document.createElement`. Use it only to bisect an isolated-world bug.
      */
     readonly chromeWorld?: 'main' | 'isolated';
     /**