dsh-browser-plus 0.0.0-stage → 0.5.1

package/docs/user-guide.md

@@ -0,0 +1,137 @@
+# 用户指南
+
+## 环境要求
+
+- DeepSeek Harness(dsh)且安装了 `web` profile
+- **Electron 运行时**(可选 package dependency):插件固定 `42.9.3` 并优先使用自身安装的 binary；纯 `dsh web` 下找不到该版本会明确失败，避免 43.x compositor 故障。
+
+## 安装
+
+```sh
+# 从 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 层,并挂载 **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_*` 工具照常可用。
+
+## 配置
+
+| 行 | 配置项 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| `browser-electron` | `viewHost` | 对象 | 必填 | 宿主提供的 `ElectronBrowserViewHost`(通常 `!!js ctx.get('electronViewHost')`) |
+| `browser-electron` | `httpOnly` | 布尔 | `true` | 仅允许 HTTP(S) 导航;`file:`/`data:` 等拒绝 |
+| `browser-electron` | `writeRoots` | 字符串数组 | `[工作目录, 系统临时目录]` | `browser_screenshot`/`browser_download` 允许写入的绝对目录;越界拒绝 |
+| `browser-electron` | `readRoots` | 字符串数组 | 同 `writeRoots` | `browser_upload_file` 与 `browser_auth action=restore file=…` 允许读取的绝对目录;越界拒绝 |
+| `browser-electron` | `chromeWorld` | `main` / `isolated` | `main` | 注入 chrome 所在的 JS 世界。`isolated` 让页面读不到任务状态与 binding token,但每个文档多一个 CDP context——**需先在真实窗口验证工具栏**(见 SOAK 第 8 节) |
+| `browser-electron` | `snapshotMaxElements` | 数字 | `60` | 快照最多收录的交互元素数 |
+| `browser-electron` | `contentMaxChars` | 数字 | `100000` | 内容抓取默认字符上限 |
+| `tool-browser` | `timeoutMs` | 数字 | `60000` | 工具协作超时(ms) |
+| `tool-browser` | `allowedActions` | 字符串数组 | 无 | 插件级初始动作白名单;每个任务可用 `browser_restrict` 为自己覆盖或解除 |
+| `tool-browser` | `tabTools` | 布尔 | `true` | 是否注册标签管理工具 |
+
+## 快速上手(给 agent 的提示词示例)
+
+```
+1. browser_open 打开 https://example.com
+2. browser_snapshot 查看页面有哪些可交互元素、编号和 snapshotId
+3. 优先 browser_click_ref(snapshotId, ref) 或 browser_scroll_into_view(snapshotId, ref),页面变化后重新快照
+4. 需要填表时用 browser_fill(按 name/label/placeholder 匹配,一次填多个字段)
+5. 后退、前进、刷新、停止和滚动使用 browser_back/browser_forward/browser_reload/browser_stop/browser_scroll
+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`;引用过期时重新快照，而不是猜测同名控件。
+- **常用浏览操作不用写脚本**:后退、前进、刷新、停止和滚动优先使用对应 `browser_*` 工具。
+- **表单优先批量填写**:React/Vue 页面用 `browser_fill`;坐标点击只保留给 canvas、图标等没有语义节点的控件。
+- **browser_execute 是最后手段**:只在新工具无法表达的页面特有操作中使用。
+- **DPR 注意**:CDP 输入使用 CSS 像素;高 DPI 屏上若点击落空,用 `elementFromPoint` 校准,不要盲试坐标。
+
+## 多任务并行
+
+每个 DSH 会话(任务)拥有独立的浏览器会话(独立标签页与历史),并发任务互不干扰:
+
+- `browser_session` 查看本任务的会话与标签;
+- `browser_reset_session` 关闭并重建本任务的会话(崩溃或卡死后用它恢复)。
+
+当前版本使用**一个共享可见浏览器窗口**，每个任务仍有隔离的任务视图、标签与历史。页面任务管理器切换可见任务；后台任务操作只更新自己的视图，不会抢走当前页面。`browser_space label="..."` 为本浏览器任务命名，`browser_space`(无参)列出全部浏览器任务。
+
+工具栏是**常驻顶栏**：和标签栏一起占视图的高度（84px，开书签栏时 118px），页面**不需要为它让位**，也不会滑出或收回。任务按钮打开左侧工作区面板，操作轨迹按钮在桌面端打开右侧工作区面板。顶部工具栏最右侧常驻“接管 / 交还 Agent”控件，不必先打开任务面板；任务卡继续显示执行中、等待用户、用户接管、失败和空闲状态。接管期间新的 Agent 页面操作会停止，快照和内容读取仍可用于确认状态。
+
+用户直接点击页面、编辑表单或使用非滚动键盘操作时，会自动切换为用户控制；滚轮、触摸拖动、滚动条操作，以及页面非编辑区的上下翻页键不会触发接管。Agent 自己的 CDP 鼠标和键盘输入带有短暂抑制标记，不会误交还控制权。
+
+任务与轨迹状态采用版本化增量更新：普通操作只更新受影响的任务卡和一条轨迹。缩略图仅在工作区打开时按需刷新当前可见任务，后台任务保留最后图像。
+
+页面原生 `alert/confirm/prompt` **默认**会被立刻接受(页面永不卡死),内容记录在 `browser_history`(`dialog` 条目)中。要驱动「确认删除」这类页面,先用 `browser_dialog` 设好**下一个**对话框怎么答(`accept`/`dismiss`,`prompt()` 可配 `promptText`)再触发它;`inspect` 报告上一次。
+
+按键、双击、悬停、文件上传、等待元素、快照引用和原生导航:见 `browser_press_key` / `browser_double_click` / `browser_hover` / `browser_upload_file` / `browser_wait_for` / `browser_click_ref` / `browser_back` 等工具(完整参考见 [工具参考](tool-reference.md))。
+
+登录态(cookie)为所有任务共享;可用 `browser_auth` 导出/恢复,重启后不丢。
+
+某些站点(带 WAF 挑战的站点)会用**轮换名称**续期挑战 Cookie,旧代不会自动消失;两代共存时站点可能直接返回 400/412。遇到这种情况用 `browser_auth action="clear" domain="example.com"`(可再加 `name` 只删一个)清掉旧代,不必清空整个 profile;清除只影响该域及其子域,其他站点登录态保留。
+
+## FAQ
+
+**Q:纯 `dsh web` 能用吗?**
+能。插件自托管:自己拉起 Electron 窗口,无需桌面外壳。
+
+**Q:找不到 Electron?**
+插件只接受 Electron `42.9.3`:优先自身 optional dependency，其次校验 `ELECTRON_PATH`、DSH 锚点与 pnpm store 候选。找不到时重新安装插件依赖，或把 `ELECTRON_PATH` 指向一个经 package metadata 验证为 `42.9.3` 的 binary。
+
+**Q:截图失败或挂起?**
+确认运行时是 Electron `42.9.3`，不要用 43.x。自托管截图优先走原生 `capturePage`，共享窗口内存在多个视图且目标未激活时自动兜底到 CDP。
+
+**Q:浏览器窗口不见了?**
+想主动把它叫回来:输入框里敲 `/browser`(或点 `+` 选「浏览器」),或者在右侧栏的「添加」列表里选「DSH-Browser-Plus」—— 两者都会打开或前置窗口,且**不产生模型消息**。窗口标题为 `dsh-browser-plus`(显示当前任务标签时为 `dsh-browser-plus — <名>`)；所有任务共享这一可见窗口，通过页面任务管理器切换各自隔离视图。若子进程崩溃会自动重启;重启后旧会话失效,调用 `browser_reset_session` 重建。
+
+**Q:下载报 CORS 错误?**
+`browser_download` 在页面上下文内 `fetch`,受同源/CORS 约束;跨域文件请先在同源页面内操作,或直接请求用户提供。
+
+**Q:如何禁止 agent 乱点?**
+`browser_restrict` 设置白名单(如只允许 `browser_snapshot`/`browser_content`);传空列表解除。**规则按任务隔离**:一个任务设的白名单不会影响其它并行任务;`tool-browser.allowedActions` 配置作为所有任务的默认值。
+
+**Q:能直接导入 Edge/Chrome 的登录状态吗?**
+**不能自动导入**,这是浏览器的安全机制而非本插件的限制:Chrome/Edge 127+ 用 **App-Bound Encryption** 加密 cookie 值(实测本机 Chrome 的 cookie 全部是 `v20` 前缀),密钥绑定浏览器自身可执行文件身份,**复制 profile 也解不开**——实测把 `Local State` + `Default/Network/Cookies` 复制到临时目录再启动 Chrome,`Storage.getCookies` 返回 0 条。两条可行路径:
+
+1. **在本插件自己的浏览器里登录一次(推荐)**:profile 是持久的(`<DSH_HOME>/dsh-browser-plus-host`),点页面工具栏的「接管」手动登录,之后 agent 的任务就一直带着这份登录态。
+2. **导入用户导出的 cookie 文件**:用扩展或 DevTools 导出成 JSON,然后 `browser_auth { action: "restore", file: "<路径>" }`。文件须在 `browser-electron.readRoots` 内(默认:工作目录与系统临时目录);接受裸数组或 `{"cookies": [...]}` 两种形状,**两种字段风格都认**:① 本插件导出的 `url` 风格;② **浏览器扩展(Cookie-Editor / EditThisCookie)与 Edge 自带导出的 `domain` + `path` 风格 —— 没有 `url` 字段,插件会自行推导**(这正是「从浏览器导出再导入」的实际用法)。`sameSite` 同时接受 Chromium 拼写(`no_restriction`)与 Playwright 拼写(`None`/`Lax`/`Strict`)。格式不合法的条目会被跳过并在 `failed` 里计数。
+
+## 故障排查
+
+| 现象 | 可能原因 | 处理 |
+| --- | --- | --- |
+| `BROWSER_SESSION_UNKNOWN` | 子进程重启后旧会话失效 | `browser_reset_session` |
+| 工具超时 | 页面卡死/未渲染完成 | 稍后重试;`browser_reset` 重置标签 |
+| 导航被拒 | 非 HTTP(S) 协议,或 URL 内嵌凭据 | 检查 URL;`httpOnly` 配置 |
+| `BROWSER_WRITE_PATH_DENIED` | 落盘路径不在允许根内 | 改存工作目录/临时目录,或在 `browser-electron.writeRoots` 追加该目录 |
+| `BROWSER_READ_PATH_DENIED` | 上传的文件不存在,或不在允许根内 | 改传工作目录/临时目录内的文件,或配置 `browser-electron.readRoots` |
+| 下载被拒 | 非 HTTP(S),或 URL 内嵌凭据 | 下载与导航共用 `admitUrl` 准入;凭据请走页面登录态 |
+| 快照为空 | 页面尚未加载 | 等待后重试 `browser_snapshot` |

package/docs/why-browser.md

@@ -0,0 +1,45 @@
+# 为什么做共享真实浏览器
+
+## 问题
+
+LLM agent 需要"上网"。传统做法是给 agent 一个**无头浏览器**(Playwright/Puppeteer 等)或**网页抓取工具**:
+
+- 无头浏览器:agent 在看不见的页面里操作,用户无法确认它在做什么,也无法中途接管;遇到登录、验证码、人机检测时寸步难行。
+- 网页抓取:只能读不能交互,且大量现代网站依赖 JS 渲染,抓到的内容失真。
+
+这两条路都绕开了"用户"——浏览器成了 agent 的私有工具,而不是用户和 agent 共用的工具。
+
+## 方案:共享真实浏览器
+
+`dsh-browser-plus` 的思路很朴素:**让 agent 驱动用户眼前那个真实的浏览器窗口**。
+
+- 浏览器是原生 `WebContentsView`,用户直接看到 agent 的每一步操作(打开页面、填写表单、点击、滚动);
+- 用户**随时可以上手接管**:输入、点击、登录、过验证码——做完之后 agent 继续;
+- agent 通过 CDP 在同一个页面里执行 JS,拿到的是与用户所见完全一致的真实 DOM。
+
+一句话:浏览器不是 agent 的"黑盒工具",而是**用户与 agent 之间的共享工作台**。
+
+## 与无头方案的能力对比
+
+| 能力 | 无头浏览器 | 网页抓取 | 本插件(共享真实浏览器) |
+| --- | --- | --- | --- |
+| 真实页面渲染 | ✅ | 部分 | ✅ |
+| 复杂交互(填表/点击/拖拽) | ✅ | ❌ | ✅ |
+| 用户可见、可接管 | ❌ | ❌ | ✅ |
+| 保留登录态 | 需手动管理 | ❌ | ✅(`browser_auth` + cookie 落盘) |
+| 人工处理验证码 | ❌ 卡死 | ❌ | ✅ 请用户点一下即可 |
+| 多任务并行 | 需多实例 | – | ✅ 任务级会话隔离 |
+
+## 设计取舍
+
+- **登录态共享**:所有任务共享同一份 cookie(符合"用户登录一次,agent 到处可用");需要隔离时用 `browser_auth` 手动导出/恢复。
+- **任务级会话隔离**:每个 DSH 会话(任务)拥有独立的浏览器会话(标签页与历史),并发任务互不抢页面;但窗口只有一个,当前活动的任务视图可见。
+- **装好即用**:不依赖桌面外壳。有外壳时嵌入外壳视图;纯 `dsh web` 时插件自托管——自己拉起 Electron 窗口,通过本机 TCP JSON-RPC 驱动。
+- **边界清晰**:可见视图、浏览器列布局属于宿主外壳;插件只负责 seam、provider 与工具,不含任何 UI。
+- **人机验证不硬刚**:检测到 Cloudflare/reCAPTCHA/hCaptcha/Turnstile 时停下,请用户在共享窗口人工完成,而不是盲目重试。
+
+## 什么场景不适合
+
+- 需要**无头批量抓取**(成千上万页面):请用专门的抓取工具/服务,不必开窗口。
+- 需要**每个任务完全独立的登录态**(互不可见):本插件默认共享 cookie;如需强隔离,可用多个 DSH 实例或 `browser_auth` 手动管理。
+- 需要**浏览器列 UI / 布局管理**:那是宿主外壳的配套,本插件不包含。

package/lib/browser/runtime.d.ts

@@ -0,0 +1,238 @@
+/**
+ * Service Definition for the browser capability seam (`ctx.browser`): the
+ * provider registry and provider-selecting execution for browser sessions.
+ * Duplicate ids are rejected. At execution time, a configured provider must
+ * exist and be usable; without one, exactly one usable provider is required,
+ * so selection never depends on registration order.
+ * @module dsh-browser-plus/browser
+ */
+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, 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' {
+    interface Context {
+        browser: BrowserRuntime;
+    }
+}
+/**
+ * Config for the browser seam. `browserProvider` pins which provider wins;
+ * it is optional (a single registered usable provider auto-selects).
+ */
+export interface BrowserRuntimeConfig {
+    /** Explicit browser provider id. Omitted = auto-select when exactly one usable. */
+    readonly browserProvider?: string;
+}
+/**
+ * The browser access service. Registered as `ctx.browser` (one instance per
+ * context).
+ *
+ * Selection semantics (resolved at execution time, never order-dependent):
+ * - A configured id that is registered and `available()` → that provider.
+ * - A configured id not registered → `BROWSER_PROVIDER_CONFIGURED_MISSING`.
+ * - A configured id registered but unavailable → `BROWSER_PROVIDER_CONFIGURED_UNAVAILABLE`.
+ * - No id configured, exactly one registered usable provider → that provider.
+ * - No id configured, multiple usable providers → `BROWSER_PROVIDER_AMBIGUOUS`.
+ * - No id configured, no usable provider → `BROWSER_PROVIDER_UNAVAILABLE`.
+ */
+export declare class BrowserRuntime extends Service {
+    /** Provider selection config. */
+    static Config: z<BrowserRuntimeConfig>;
+    private providers;
+    private readonly providerId;
+    constructor(ctx: Context, config?: BrowserRuntimeConfig);
+    /**
+     * Register a browser provider. Throws {@link BrowserError}
+     * `BROWSER_DUPLICATE_PROVIDER` if its id is already registered. Returns a
+     * disposer; disposed with the calling fiber.
+     * @param provider - the provider; its `id` is the registry key.
+     * @returns the disposer that unregisters the provider.
+     */
+    registerBrowserProvider(provider: BrowserProvider): () => void;
+    /** Resolve the selected provider or throw the matching {@link BrowserError}. */
+    private resolveProvider;
+    /** Open a new browser session through the selected provider. */
+    open(options?: BrowserOpenOptions): Promise<BrowserSessionId>;
+    /** Open a URL through the selected provider, optionally in a new tab. */
+    openUrl(session: BrowserSessionId, request: BrowserOpenRequest, signal?: AbortSignal): Promise<void>;
+    /** List the session's tabs through the selected provider. */
+    listTabs(session: BrowserSessionId): Promise<readonly BrowserTab[]>;
+    /** Switch to a tab through the selected provider. */
+    switchTab(session: BrowserSessionId, tabId: string): Promise<void>;
+    /** Close one tab through the selected provider. */
+    closeTab(session: BrowserSessionId, tabId: string): Promise<boolean>;
+    /** Close every tab and reset the session through the selected provider. */
+    reset(session: BrowserSessionId): Promise<void>;
+    /** Navigate the session's page through the selected provider. */
+    navigate(session: BrowserSessionId, request: BrowserNavigateRequest, signal?: AbortSignal): Promise<void>;
+    /** Navigate to the previous history entry through the selected provider. */
+    back(session: BrowserSessionId, signal?: AbortSignal): Promise<boolean>;
+    /** Navigate to the next history entry through the selected provider. */
+    forward(session: BrowserSessionId, signal?: AbortSignal): Promise<boolean>;
+    /** Reload the active page through the selected provider. */
+    reload(session: BrowserSessionId, signal?: AbortSignal): Promise<void>;
+    /** Stop loading the active page through the selected provider. */
+    stopLoading(session: BrowserSessionId, signal?: AbortSignal): Promise<void>;
+    /** Execute JS in the session's page context through the selected provider. */
+    execute(session: BrowserSessionId, request: BrowserExecuteRequest, signal?: AbortSignal): Promise<BrowserExecuteResult>;
+    /** Produce an AI-friendly snapshot of the session's page. */
+    snapshot(session: BrowserSessionId, options?: {
+        query?: string;
+        limit?: number;
+    }, signal?: AbortSignal): Promise<BrowserSnapshotResult>;
+    /** Apply device/viewport/media emulation to the session's active tab. */
+    emulate(session: BrowserSessionId, options?: {
+        width?: number;
+        height?: number;
+        deviceScaleFactor?: number;
+        mobile?: boolean;
+        userAgent?: string;
+        colorScheme?: 'light' | 'dark' | 'no-preference';
+        clear?: boolean;
+    }): Promise<{
+        applied: string[];
+    }>;
+    /** Console messages the host captured for the session's active tab. */
+    consoleMessages(session: BrowserSessionId, options?: {
+        limit?: number;
+        level?: string;
+        clear?: boolean;
+    }): Promise<{
+        messages: Array<{
+            level: string;
+            text: string;
+            at: string;
+        }>;
+    }>;
+    /** Network requests the host captured for the session's active tab. */
+    networkRequests(session: BrowserSessionId, options?: {
+        limit?: number;
+        failedOnly?: boolean;
+        urlContains?: string;
+        clear?: boolean;
+    }): Promise<{
+        requests: Array<{
+            method: string;
+            url: string;
+            status?: number;
+            mime?: string;
+            kind?: string;
+            failed?: string;
+            ms?: number;
+            at: string;
+        }>;
+    }>;
+    /** Set how the host answers the next JS dialog, and report the state. */
+    setDialogPolicy(session: BrowserSessionId, policy: {
+        behavior: 'accept' | 'dismiss';
+        promptText?: string;
+    }): Promise<{
+        dialog: unknown;
+        policy: {
+            behavior: 'accept' | 'dismiss';
+            promptText?: string;
+        };
+    }>;
+    /** Drain any pending dialog, then report the last one and the current policy. */
+    inspectDialog(session: BrowserSessionId): Promise<{
+        dialog: unknown;
+        policy: {
+            behavior: 'accept' | 'dismiss';
+            promptText?: string;
+        };
+    }>;
+    /** The last JS dialog the host reported, plus the current policy. */
+    dialogState(session: BrowserSessionId): {
+        dialog: unknown;
+        policy: {
+            behavior: 'accept' | 'dismiss';
+            promptText?: string;
+        };
+    };
+    /** Click one element referenced by an exact snapshot. */
+    clickRef(session: BrowserSessionId, request: BrowserRefRequest, signal?: AbortSignal): Promise<void>;
+    /** Scroll one element referenced by an exact snapshot into view. */
+    scrollIntoView(session: BrowserSessionId, request: BrowserScrollIntoViewRequest, signal?: AbortSignal): Promise<BrowserScrollResult>;
+    /** Fetch page content in a requested format. */
+    content(session: BrowserSessionId, request: BrowserContentRequest, signal?: AbortSignal): Promise<BrowserContentResult>;
+    /** Click at viewport coordinates through the selected provider. */
+    click(session: BrowserSessionId, request: BrowserPointerTarget, signal?: AbortSignal): Promise<BrowserPointerResult>;
+    /** Double-click at viewport coordinates through the selected provider. */
+    doubleClick(session: BrowserSessionId, request: BrowserPointerTarget, signal?: AbortSignal): Promise<BrowserPointerResult>;
+    /** Press on one target, move to another, release, through the selected provider. */
+    drag(session: BrowserSessionId, request: BrowserDragRequest, signal?: AbortSignal): Promise<BrowserDragResult>;
+    hover(session: BrowserSessionId, request: BrowserPointerTarget, signal?: AbortSignal): Promise<BrowserPointerResult>;
+    /** Scroll the active page through the selected provider. */
+    scroll(session: BrowserSessionId, request: BrowserScrollRequest, signal?: AbortSignal): Promise<BrowserScrollResult>;
+    /** 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>;
+    /** Press a key into the session's page through the selected provider. */
+    pressKey(session: BrowserSessionId, request: BrowserPressKeyRequest, signal?: AbortSignal): Promise<void>;
+    /** Fill a form's fields in one batch through the selected provider. */
+    fillForm(session: BrowserSessionId, request: BrowserFillRequest, signal?: AbortSignal): Promise<BrowserFillResult>;
+    /** Capture the current page through the selected provider. */
+    screenshot(session: BrowserSessionId, request?: BrowserScreenshotRequest, signal?: AbortSignal): Promise<BrowserScreenshotResult>;
+    /** Check for a human-verification challenge on the active tab. */
+    detectChallenge(session: BrowserSessionId, signal?: AbortSignal): Promise<BrowserChallenge>;
+    /** Return the session's chronological operation log through the provider. */
+    history(session: BrowserSessionId): Promise<readonly BrowserHistoryEntry[]>;
+    /** 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. */
+    download(session: BrowserSessionId, request: BrowserDownloadRequest, signal?: AbortSignal): Promise<{
+        readonly path: string;
+    }>;
+    /** Export the session's cookies through the provider. */
+    flushAuth(session: BrowserSessionId): Promise<readonly ExportedCookie[]>;
+    /** Import cookies into the session through the provider. */
+    restoreAuth(session: BrowserSessionId, cookies: readonly ExportedCookie[]): Promise<number>;
+    /** Import cookies from a JSON export on disk through the provider. */
+    importAuth(session: BrowserSessionId, path: string): Promise<{
+        restored: number;
+        failed: number;
+    }>;
+    /** Start a background scrape batch through the provider. */
+    startScrape(session: BrowserSessionId, request: BrowserScrapeRequest): Promise<BrowserScrapeStatus>;
+    /** Progress of one scrape batch through the provider. */
+    scrapeStatus(id: string): Promise<BrowserScrapeStatus>;
+    /** Ask a running scrape batch to stop through the provider. */
+    stopScrape(id: string): Promise<BrowserScrapeStatus>;
+    /** Every scrape batch the provider knows about. */
+    listScrapes(): Promise<readonly BrowserScrapeStatus[]>;
+    /** Remove cookies for one site scope through the provider. */
+    clearAuth(session: BrowserSessionId, request: BrowserClearAuthRequest): Promise<BrowserClearAuthResult>;
+    /** Set the session's browser task label through the selected provider. */
+    setSpace(session: BrowserSessionId, label: string): Promise<void>;
+    /** List browser tasks (legacy spaces) with labels through the selected provider. */
+    listSpaces(): Promise<readonly BrowserSpaceInfo[]>;
+    /** List browser tasks with live collaboration status through the provider. */
+    listTasks(): Promise<readonly BrowserTaskInfo[]>;
+    /** Read one session's task collaboration state through the provider. */
+    getTask(session: BrowserSessionId): Promise<BrowserTaskInfo>;
+    /** Update one session's visible task state through the provider. */
+    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>;
+}
+export default BrowserRuntime;