dsh-builtin-browser 0.1.6 → 0.1.8

package/README.en.md

@@ -2,17 +2,35 @@
 
 中文 | [English](README.en.md)
 
-A shared real browser capability plugin for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): a visible browser the human watches and can take over, driven by the agent over CDP.
+A shared **real browser** capability plugin for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): install and it just works — the agent drives a real, visible browser over CDP that the human can watch and take over at any time. Human and agent operate the **very same page**.
 
-This plugin provides the **host-side capability** (browser seam, Electron CDP provider, `browser_*` model tools). The browser's **native view itself** is supplied by the host (a desktop shell) through `ctx.electronViewHost`; the plugin contains no browser UI.
+**Why this plugin**
+
+- **Install-and-use.** With a desktop shell the shell's embedded view is used; on plain `dsh web` the plugin **self-hosts** — it spawns its own Electron window with zero extra configuration.
+- **Real and visible, human-takeover friendly.** Not a headless screenshot or a relay: the user sees the page and can grab control directly.
+- **DOM-level driving, framework-friendly.** React/Vue controlled inputs fill reliably.
+- **Concurrency-safe.** Task-level browser session isolation — parallel tasks never fight over the page or pollute each other.
+- **Built for the real world.** CAPTCHA detection, login persistence, batch form filling, authenticated downloads, operation replay, and action restriction — all included.
 
 ## Features
 
+**Browser capability**
+
 - **Real view, not a relay.** The browser is a native view (`WebContentsView`) the human can see and operate directly; the agent drives the very same page. The view is provided by the host shell; the plugin drives it.
 - **DOM-referenced, not coordinate-guessing.** `browser_snapshot` returns numbered interactive elements; `browser_execute` runs JS in the page (native setters for framework inputs), so interaction works on React/Vue pages.
 - **Multi-tab sessions.** Open URLs in parallel tabs, list/switch/close/reset, all keeping state.
 - **Multi-format content.** Fetch pages as html / markdown / txt / json, scoped by selector, capped by length and timeout.
 
+**Engineering capability**
+
+- **Per-task isolation.** Each DSH task (session) gets its own browser session (own tabs and history); concurrent tasks never interfere, and calls within one task reuse the same session (`browser_session` / `browser_reset_session`).
+- **Login persistence.** `browser_auth` exports/restores cookies, so logins survive host restarts.
+- **CAPTCHA / bot-detection awareness.** Cloudflare, reCAPTCHA, hCaptcha, Turnstile and generic challenges are detected automatically (`browser_challenge`, and flagged in snapshots); instead of blindly retrying, the agent asks the human to complete it in the shared window.
+- **Batch form filling.** `browser_fill` sets many fields in one call — matched by selector/name/label, handling controlled inputs, selects, checkboxes and radio groups, with optional submit.
+- **Operation history & replay.** `browser_history` records operations; `browser_replay` re-runs one step.
+- **Authenticated downloads.** `browser_download` fetches a URL with the session's cookies straight to a local file.
+- **Safety restriction.** `browser_restrict` limits which browser actions are allowed, preventing stray clicks/navigation.
+
 ## Requirements
 
 - DeepSeek Harness (dsh) with the `web` profile
@@ -28,7 +46,7 @@ This plugin provides the **host-side capability** (browser seam, Electron CDP pr
 | DeepSeek Harness (dsh) | `0.1.0-rc.5` |
 | Electron | `43.4.0` |
 | Node.js | `22.20.0` |
-| dsh-builtin-browser | `0.1.3` |
+| dsh-builtin-browser | `0.1.7` |
 | OS | Windows 10 (10.0.26200) |
 
 > The plugin declares `electron >= 30`; other platforms (macOS/Linux) run the same protocol but were only verified on the Windows environment above.

package/README.md

@@ -2,17 +2,35 @@
 
 [English](README.en.md) | 中文
 
-面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的共享真实浏览器能力插件:一个用户可见、可随时接管的浏览器,由 agent 通过 CDP 驱动。
+面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的**共享真实浏览器**能力插件:装好即可用——agent 通过 CDP 驱动一个真实、可见、可随时人工接管的浏览器,人与 agent 操作的是**同一个页面**。
 
-本插件提供 **host 侧能力**(浏览器 seam、Electron CDP provider、`browser_*` 模型工具)。浏览器本身的**原生视图**由宿主(桌面外壳)通过 `ctx.electronViewHost` 提供;插件不包含浏览器界面 UI。
+**我们的优势**
+
+- **装好即用**:有桌面外壳时嵌入外壳视图;纯 `dsh web` 也能**自托管**拉起自己的 Electron 窗口,不需要任何额外配置。
+- **真实可见、人工可接管**:不是无头截屏或转播,用户随时能看到页面并直接接手操作。
+- **DOM 级驱动,框架友好**:React/Vue 受控组件也能可靠填写。
+- **并发安全**:任务级浏览器会话隔离,多个任务并行互不抢页面、不互相污染。
+- **面向真实世界**:人机验证识别、登录态持久化、批量填表、带登录态下载、操作回放、动作限制,一应俱全。
 
 ## 功能
 
+**浏览器能力**
+
 - **真实视图,而非转播。** 浏览器是原生视图(`WebContentsView`),用户可直接看到并操作;agent 驱动的是同一个页面。视图由宿主外壳提供,插件负责驱动。
 - **DOM 引用,而非猜坐标。** `browser_snapshot` 返回带编号的交互元素;`browser_execute` 在页面里执行 JS(框架输入用原生 setter),在 React/Vue 页面上也能可靠交互。
 - **多标签会话。** 并行打开 URL、查看/切换/关闭/重置标签,状态保持。
 - **多格式内容。** 以 html / markdown / txt / json 抓取页面,支持 selector 限定、长度与超时上限。
 
+**工程化能力**
+
+- **按任务隔离。** 每个 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
@@ -28,7 +46,7 @@
 | DeepSeek Harness(dsh) | `0.1.0-rc.5` |
 | Electron | `43.4.0` |
 | Node.js | `22.20.0` |
-| dsh-builtin-browser | `0.1.3` |
+| dsh-builtin-browser | `0.1.7` |
 | 操作系统 | Windows 10 (10.0.26200) |
 
 > 插件声明 `electron >= 30`;其他平台(如 macOS/Linux)按同一协议运行,但仅在上表 Windows 环境实测。
@@ -74,6 +92,13 @@ provider 与工具以 `ctx.get('electronViewHost')` 是否存在为门控,因此
 | `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` | 批量填充表单(选择器/名称/标签匹配,支持受控输入、下拉、单选/复选,可选提交) |
 
 ### 操作纪律(点击/填表)
 
@@ -103,7 +128,8 @@ provider 按构造与 Electron 解耦:它通过 `ElectronBrowserViewHost` 接缝
 
 - 截图仅 PNG(CDP JPEG 在 Electron 43 上挂起);JPEG 等待非 CDP 转换路径。
 - 部分主机在软件合成下 `fullPage` 截图不稳定。
-- 会话生命周期为插件级(模型共享一个会话),尚未做到按 agent 隔离。
+- 会话按任务隔离:每个调用方任务(DSH 会话)拥有独立的浏览器会话(独立标签页与历史),并发任务互不干扰;同一任务的多次调用复用同一会话。登录态(cookie)为共享,可用 `browser_auth` 导出/恢复。
+- 人机验证(CAPTCHA)无法自动解决:快照会标注检测到的挑战(`browser_challenge` 可显式检查),此时应请用户在共享窗口中人工完成,而不是反复重试。
 - 无痕模式(`privateMode`)未实现:它需要 Electron 的 session 分区能力,属于宿主层,本插件不承诺。
 - 本插件不含浏览器列 UI——那是宿主外壳的配套,别把"浏览器列"当成插件能力。
 

package/lib/browser/runtime.d.ts

@@ -8,9 +8,9 @@
  */
 import { Context, Service } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
-import type { BrowserClickRequest, BrowserContentRequest, BrowserContentResult, BrowserExecuteRequest, BrowserExecuteResult, BrowserNavigateRequest, BrowserOpenRequest, BrowserProvider, BrowserScreenshotRequest, BrowserScreenshotResult, BrowserSessionId, BrowserSnapshotResult, BrowserTab, BrowserTypeRequest } from './types.ts';
+import type { BrowserClickRequest, BrowserContentRequest, BrowserContentResult, BrowserDownloadRequest, BrowserExecuteRequest, BrowserExecuteResult, BrowserFillRequest, BrowserFillResult, BrowserHistoryEntry, BrowserNavigateRequest, BrowserOpenRequest, BrowserProvider, BrowserScreenshotRequest, BrowserScreenshotResult, BrowserSessionId, BrowserSnapshotResult, BrowserTab, BrowserTypeRequest, BrowserChallenge, ExportedCookie } from './types.ts';
 export { BrowserError, } from './types.ts';
-export type { BrowserClickRequest, BrowserContentFormat, BrowserContentRequest, BrowserContentResult, BrowserExecuteRequest, BrowserExecuteResult, BrowserNavigateRequest, BrowserOpenRequest, BrowserProvider, BrowserScreenshotRequest, BrowserScreenshotResult, BrowserSessionId, BrowserSnapshotElement, BrowserSnapshotResult, BrowserTab, BrowserTypeRequest, } from './types.ts';
+export type { BrowserChallenge, BrowserClickRequest, BrowserContentFormat, BrowserContentRequest, BrowserContentResult, BrowserDownloadRequest, BrowserExecuteRequest, BrowserExecuteResult, BrowserFillField, BrowserFillRequest, BrowserFillResult, BrowserHistoryEntry, BrowserNavigateRequest, BrowserOpenRequest, BrowserProvider, BrowserScreenshotRequest, BrowserScreenshotResult, BrowserSessionId, BrowserSnapshotElement, BrowserSnapshotResult, BrowserTab, BrowserTypeRequest, ExportedCookie, } from './types.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
         browser: BrowserRuntime;
@@ -29,12 +29,12 @@ export interface BrowserRuntimeConfig {
  * 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`.
+ * - 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. */
@@ -76,8 +76,24 @@ export declare class BrowserRuntime extends Service {
     click(session: BrowserSessionId, request: BrowserClickRequest, signal?: AbortSignal): Promise<void>;
     /** Type into the focused element through the selected provider. */
     type(session: BrowserSessionId, request: BrowserTypeRequest, 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>;
     /** Close the session through the selected provider. Idempotent. */
     close(session: BrowserSessionId): Promise<void>;
 }

package/lib/browser/runtime.js

@@ -15,12 +15,12 @@ export { BrowserError, } from "./types.js";
  * 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`.
+ * - 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 class BrowserRuntime extends Service {
     /** Provider selection config. */
@@ -51,7 +51,7 @@ export class BrowserRuntime extends Service {
             yield () => this.providers.delete(provider.id);
         }.bind(this), 'browser.registerProvider()');
         // ctx.effect's disposer returns Promise<void>; our disposer API is
-        // synchronous fire-and-forget 鈥?discard the (always-resolved) promise.
+        // synchronous fire-and-forget — discard the (always-resolved) promise.
         return () => void dispose();
     }
     /** Resolve the selected provider or throw the matching {@link BrowserError}. */
@@ -126,10 +126,38 @@ export class BrowserRuntime extends Service {
     async type(session, request, signal) {
         return this.resolveProvider().type(session, request, signal);
     }
+    /** Fill a form's fields in one batch through the selected provider. */
+    async fillForm(session, request, signal) {
+        return this.resolveProvider().fillForm(session, request, signal);
+    }
     /** Capture the current page through the selected provider. */
     async screenshot(session, request, signal) {
         return this.resolveProvider().screenshot(session, request, signal);
     }
+    /** Check for a human-verification challenge on the active tab. */
+    async detectChallenge(session, signal) {
+        return this.resolveProvider().detectChallenge(session, signal);
+    }
+    /** Return the session's chronological operation log through the provider. */
+    async history(session) {
+        return this.resolveProvider().history(session);
+    }
+    /** Replay one recorded operation by sequence number through the provider. */
+    async replay(session, seq) {
+        return this.resolveProvider().replay(session, seq);
+    }
+    /** Download a URL to a local file through the provider. */
+    async download(session, request, signal) {
+        return this.resolveProvider().download(session, request, signal);
+    }
+    /** Export the session's cookies through the provider. */
+    async flushAuth(session) {
+        return this.resolveProvider().flushAuth(session);
+    }
+    /** Import cookies into the session through the provider. */
+    async restoreAuth(session, cookies) {
+        return this.resolveProvider().restoreAuth(session, cookies);
+    }
     /** Close the session through the selected provider. Idempotent. */
     async close(session) {
         return this.resolveProvider().close(session);

package/lib/browser/types.d.ts

@@ -3,14 +3,14 @@
  * provider registration, session lifecycle, cancellation, errors, and product
  * configuration; providers differ only in what backs a session (an Electron
  * `WebContentsView` in the desktop shell, a headless Chromium relay for
- * remote deployments, 鈥?.
+ * remote deployments, and so on).
  * @module dsh-browser/browser/types
  */
 import { HarnessError } from '@deepseek-ai/dsh-llm';
 /**
  * Stable identity of one browser session, resolved by the Host through a
  * Typert `LookupMap` to the live session object (the same mechanism
- * `Agent 鈫?agentId` uses). The id is opaque to the wire; only the provider
+ * `Agent → agentId` uses). The id is opaque to the wire; only the provider
  * and its host binding can interpret it.
  */
 export type BrowserSessionId = string;
@@ -25,7 +25,7 @@ export interface BrowserNavigateRequest {
 }
 /**
  * Click at viewport coordinates. Coordinates are viewport-relative pixels in
- * the session's own coordinate space 鈥?the same space the human interacts
+ * the session's own coordinate space — the same space the human interacts
  * with, so a real view and a relay agree without scaling.
  */
 export interface BrowserClickRequest {
@@ -39,6 +39,48 @@ export interface BrowserTypeRequest {
     /** The text to insert. */
     readonly text: string;
 }
+/** 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. */
+    readonly selector?: string;
+    /** Match by the field's `name` attribute. */
+    readonly name?: string;
+    /** Match by associated `<label>` text or `aria-label`. */
+    readonly label?: string;
+    /** Match by `placeholder` text. */
+    readonly placeholder?: string;
+    /** Field kind; defaults to text. */
+    readonly kind?: 'text' | 'textarea' | 'checkbox' | 'radio' | 'select';
+    /** Value to set: string, number, or boolean (checkbox/radio). For a
+     *  multi-select or radio group, the option value (or visible text). */
+    readonly value: string | number | boolean;
+}
+/** Batch form fill: set several fields, optionally submitting the form. */
+export interface BrowserFillRequest {
+    /** The fields to fill, in order. */
+    readonly fields: readonly BrowserFillField[];
+    /** Submit the containing form after filling. Default false. */
+    readonly submit?: boolean;
+    /** Per-field evaluation budget in ms. Default 30000. */
+    readonly timeoutMs?: number;
+}
+/** One field's outcome in a batch fill. */
+export interface BrowserFillFieldResult {
+    readonly ok: boolean;
+    /** The field description matched (selector/name/label/placeholder). */
+    readonly target: string;
+    /** How the value was applied: input | textarea | select | checkbox | radio | contenteditable. */
+    readonly method?: string;
+    /** Error text when the field could not be filled. */
+    readonly error?: string;
+}
+/** Outcome of a batch form fill. */
+export interface BrowserFillResult {
+    /** Per-field outcomes, in request order. */
+    readonly fields: readonly BrowserFillFieldResult[];
+    /** Whether the containing form was submitted. */
+    readonly submitted: boolean;
+}
 /**
  * A screenshot of the current page state. `dataUrl` is a base64 data URL the
  * tool layer renders directly; the live view itself never crosses the wire
@@ -47,15 +89,38 @@ export interface BrowserTypeRequest {
 export interface BrowserScreenshotResult {
     /** Base64 data URL of the capture (PNG or JPEG per the request). */
     readonly dataUrl: string;
+    /** File path the capture was also saved to, when the request asked for it. */
+    readonly path?: string;
 }
 /** Screenshot capture options. PNG only (CDP JPEG hangs on Electron 43). */
 export interface BrowserScreenshotRequest {
     /** Capture the full scrollable page instead of the viewport. Default false. */
     readonly fullPage?: boolean;
+    /** Absolute file path to also save the PNG to (for vision-tool reads). */
+    readonly savePath?: string;
+}
+/** Download options: fetch a URL into a local file, keeping the session's cookies. */
+export interface BrowserDownloadRequest {
+    /** The URL to download. */
+    readonly url: string;
+    /** Absolute path of the file to write. */
+    readonly savePath: string;
+}
+/** A serializable cookie, exported from or imported into the browser session. */
+export interface ExportedCookie {
+    /** Cookie URL (scheme + domain + path), as accepted by cookies.set. */
+    readonly url: string;
+    readonly name: string;
+    readonly value: string;
+    readonly domain?: string;
+    readonly path?: string;
+    readonly secure?: boolean;
+    readonly httpOnly?: boolean;
+    readonly expirationDate?: number;
 }
 /**
  * Execute arbitrary JavaScript in the session's page context. This is the
- * primary interaction path 鈥?DOM-referenced, not screen-coordinate-based:
+ * primary interaction path — DOM-referenced, not screen-coordinate-based:
  * focus/input/click go through the page's own JS (native setters for
  * framework-controlled inputs), matching how a human-driven agent operates.
  */
@@ -97,7 +162,7 @@ export interface BrowserSnapshotElement {
 }
 /**
  * AI-friendly page snapshot: a compact, numbered inventory of interactive
- * elements plus page facts. Not raw HTML 鈥?the model dialogues with this.
+ * elements plus page facts. Not raw HTML — the model dialogues with this.
  */
 export interface BrowserSnapshotResult {
     /** Final page URL. */
@@ -108,6 +173,21 @@ export interface BrowserSnapshotResult {
     readonly elements: readonly BrowserSnapshotElement[];
     /** True when the snapshot was truncated (element cap reached). */
     readonly truncated: boolean;
+    /** Human-verification challenge blocking the page, when one is detected. */
+    readonly challenge?: BrowserChallenge;
+}
+/**
+ * A detected human-verification (bot-detection / CAPTCHA) challenge blocking
+ * the page. Detection is best-effort and marker-based; a clean result is not a
+ * guarantee that no challenge exists.
+ */
+export interface BrowserChallenge {
+    /** Whether a challenge currently blocks the page. */
+    readonly blocked: boolean;
+    /** Machine-readable kind: cloudflare | hcaptcha | recaptcha | turnstile | generic. */
+    readonly kind?: string;
+    /** Short human-readable description, e.g. 'Cloudflare "Just a moment" interstitial'. */
+    readonly reason?: string;
 }
 /**
  * Content fetch formats. `html` is the raw DOM; `markdown` is a structured
@@ -163,7 +243,7 @@ export interface BrowserProvider {
     available(): boolean;
     /**
      * Open a new session. The provider mints the session id and prepares its
-     * backing surface (a view, a headless page, 鈥?. Sessions are isolated from
+     * 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.
      */
     open(): Promise<BrowserSessionId>;
@@ -171,7 +251,7 @@ export interface BrowserProvider {
     openUrl(session: BrowserSessionId, request: BrowserOpenRequest, signal?: AbortSignal): Promise<void>;
     /** List the session's tabs. */
     listTabs(session: BrowserSessionId): Promise<readonly BrowserTab[]>;
-    /** Switch to a tab by id. Unknown id 鈫?`BROWSER_TAB_UNKNOWN`. */
+    /** Switch to a tab by id. Unknown id -> `BROWSER_TAB_UNKNOWN`. */
     switchTab(session: BrowserSessionId, tabId: string): Promise<void>;
     /** Close one tab. Closing the active tab activates the next. */
     closeTab(session: BrowserSessionId, tabId: string): Promise<void>;
@@ -183,17 +263,50 @@ export interface BrowserProvider {
     execute(session: BrowserSessionId, request: BrowserExecuteRequest, signal?: AbortSignal): Promise<BrowserExecuteResult>;
     /** Produce an AI-friendly snapshot of the active tab. */
     snapshot(session: BrowserSessionId, signal?: AbortSignal): Promise<BrowserSnapshotResult>;
+    /** Check whether a human-verification challenge is blocking the active tab. */
+    detectChallenge(session: BrowserSessionId, signal?: AbortSignal): Promise<BrowserChallenge>;
     /** Fetch page content in a requested format. */
     content(session: BrowserSessionId, request: BrowserContentRequest, signal?: AbortSignal): Promise<BrowserContentResult>;
     /** Click at viewport coordinates (fallback path; execute is preferred). Honor `signal` for cancellation. */
     click(session: BrowserSessionId, request: BrowserClickRequest, signal?: AbortSignal): Promise<void>;
     /** Type into the focused element (fallback path). Honor `signal` for cancellation. */
     type(session: BrowserSessionId, request: BrowserTypeRequest, signal?: AbortSignal): Promise<void>;
+    /** 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. */
     screenshot(session: BrowserSessionId, request?: BrowserScreenshotRequest, signal?: AbortSignal): Promise<BrowserScreenshotResult>;
+    /** Download a URL to a local file. Honor `signal` for cancellation. */
+    download(session: BrowserSessionId, request: BrowserDownloadRequest, signal?: AbortSignal): Promise<{
+        readonly path: string;
+    }>;
+    /** Export the session's cookies (login state). */
+    flushAuth(session: BrowserSessionId): Promise<readonly ExportedCookie[]>;
+    /** Import cookies into the session (restore login state). */
+    restoreAuth(session: BrowserSessionId, cookies: readonly ExportedCookie[]): Promise<number>;
+    /** Return the session's chronological operation log. */
+    history(session: BrowserSessionId): Promise<readonly BrowserHistoryEntry[]>;
+    /** Replay one recorded operation by sequence number. */
+    replay(session: BrowserSessionId, seq: number): Promise<void>;
     /** Close the session and destroy its backing surface. Idempotent. */
     close(session: BrowserSessionId): Promise<void>;
 }
+/** One recorded browser operation, in chronological order (seq 1, 2, 3…). */
+export interface BrowserHistoryEntry {
+    /** Monotonic sequence number within the session. */
+    readonly seq: number;
+    /** The operation name: navigate | execute | click | type | replay. */
+    readonly action: string;
+    /** The operation's arguments. */
+    readonly params: Record<string, unknown>;
+    /** Whether the operation succeeded. */
+    readonly ok: boolean;
+    /** Truncated result text, when the operation returned one. */
+    readonly result?: string;
+    /** Error text, when the operation failed. */
+    readonly error?: string;
+    /** Epoch millis of the operation. */
+    readonly at: number;
+}
 /**
  * Typed browser error with a machine-routable, open-string `code` and chained
  * `cause`. Consumers must tolerate provider-specific codes. Shared codes cover

package/lib/browser/types.js

@@ -3,7 +3,7 @@
  * provider registration, session lifecycle, cancellation, errors, and product
  * configuration; providers differ only in what backs a session (an Electron
  * `WebContentsView` in the desktop shell, a headless Chromium relay for
- * remote deployments, 鈥?.
+ * remote deployments, and so on).
  * @module dsh-browser/browser/types
  */
 import { HarnessError } from '@deepseek-ai/dsh-llm';

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

@@ -99,6 +99,91 @@ async function handle(op, msg) {
                 reply(msg.id, { ok: true, result });
                 return;
             }
+            case 'download': {
+                const viewId = msg.viewId;
+                const url = msg.url;
+                const savePath = msg.savePath;
+                if (viewId === undefined || typeof url !== 'string' || typeof savePath !== 'string') {
+                    throw new Error('download missing viewId/url/savePath');
+                }
+                const entry = views.get(viewId);
+                if (entry === undefined)
+                    throw new Error(`download: unknown view ${viewId}`);
+                // Fetch the URL inside the page context (keeps cookies/login), read
+                // the body as base64, and return it; the parent writes the file. This
+                // avoids Electron's download pipeline entirely (CDP debugger attach
+                // can interfere with will-download).
+                const result = await entry.webContentsView.webContents.debugger.sendCommand('Runtime.evaluate', {
+                    expression: `(async () => {
+            const r = await fetch(${JSON.stringify(url)}, { credentials: 'include' })
+            if (!r.ok) throw new Error('HTTP ' + r.status)
+            const b = await r.arrayBuffer()
+            const bytes = new Uint8Array(b)
+            let bin = ''
+            for (let i = 0; i < bytes.length; i += 0x8000) bin += String.fromCharCode.apply(null, bytes.subarray(i, i + 0x8000))
+            return btoa(bin)
+          })()`,
+                    awaitPromise: true,
+                    returnByValue: true,
+                });
+                const value = result.result?.value;
+                if (typeof value !== 'string') {
+                    const detail = result.exceptionDetails;
+                    throw new Error(`download failed: ${detail?.exception?.description ?? 'no data'}`);
+                }
+                reply(msg.id, { ok: true, result: { base64: value, savePath } });
+                return;
+            }
+            case 'flushAuth': {
+                const viewId = msg.viewId;
+                if (viewId === undefined)
+                    throw new Error('flushAuth missing viewId');
+                const entry = views.get(viewId);
+                if (entry === undefined)
+                    throw new Error(`flushAuth: unknown view ${viewId}`);
+                // Export the session's cookies so login state can be saved/restored
+                // across browser hosts (or shared with another machine).
+                const cookies = await entry.webContentsView.webContents.session.cookies.get({});
+                const exported = cookies.map(c => ({
+                    url: `http${c.secure ? 's' : ''}://${c.domain.startsWith('.') ? c.domain.slice(1) : c.domain}${c.path}`,
+                    name: c.name,
+                    value: c.value,
+                    domain: c.domain,
+                    path: c.path,
+                    secure: c.secure,
+                    httpOnly: c.httpOnly,
+                    expirationDate: c.expirationDate,
+                }));
+                reply(msg.id, { ok: true, result: { cookies: exported } });
+                return;
+            }
+            case 'restoreAuth': {
+                const viewId = msg.viewId;
+                const cookies = msg.cookies;
+                if (viewId === undefined)
+                    throw new Error('restoreAuth missing viewId');
+                const entry = views.get(viewId);
+                if (entry === undefined)
+                    throw new Error(`restoreAuth: unknown view ${viewId}`);
+                if (!Array.isArray(cookies))
+                    throw new Error('restoreAuth missing cookies array');
+                for (const c of cookies) {
+                    if (typeof c.url !== 'string' || typeof c.name !== 'string' || typeof c.value !== 'string')
+                        continue;
+                    await entry.webContentsView.webContents.session.cookies.set({
+                        url: c.url,
+                        name: c.name,
+                        value: c.value,
+                        ...typeof c.domain === 'string' ? { domain: c.domain } : {},
+                        ...typeof c.path === 'string' ? { path: c.path } : {},
+                        ...typeof c.secure === 'boolean' ? { secure: c.secure } : {},
+                        ...typeof c.httpOnly === 'boolean' ? { httpOnly: c.httpOnly } : {},
+                        ...typeof c.expirationDate === 'number' ? { expirationDate: c.expirationDate } : {},
+                    });
+                }
+                reply(msg.id, { ok: true, result: { restored: cookies.length } });
+                return;
+            }
             default:
                 throw new Error(`unknown op ${op}`);
         }