dsh-builtin-browser 0.1.6 → 0.1.7

package/README.md

@@ -74,6 +74,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 +110,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}`);
         }

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

@@ -1,12 +1,12 @@
 /**
  * Electron-backed browser provider: `WebContentsView` sessions driven over
- * `webContents.debugger` (CDP). The provider itself does not import Electron 鈥? * it operates through the {@link ElectronBrowserViewHost} seam, which the
+ * `webContents.debugger` (CDP). The provider itself does not import Electron — it operates through the {@link ElectronBrowserViewHost} seam, which the
  * desktop shell implements with real Electron objects. That keeps this
  * package testable under plain Node and leaves the Electron dependency to the
  * shell that owns the `BrowserWindow`.
  * @module dsh-browser/browser-electron
  */
-import type { BrowserContentRequest, BrowserContentResult, BrowserExecuteRequest, BrowserExecuteResult, BrowserOpenRequest, BrowserProvider, BrowserSessionId, BrowserSnapshotResult, BrowserTab } from '../browser/types.ts';
+import type { BrowserChallenge, BrowserContentRequest, BrowserContentResult, BrowserExecuteRequest, BrowserExecuteResult, BrowserFillRequest, BrowserFillResult, BrowserHistoryEntry, BrowserOpenRequest, BrowserProvider, BrowserSessionId, BrowserSnapshotResult, BrowserTab, ExportedCookie } from '../browser/types.ts';
 /** Stable provider id registered with `ctx.browser`. */
 export declare const ELECTRON_BROWSER_PROVIDER_ID = "electron";
 /**
@@ -111,12 +111,11 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
     /** Usable whenever the host can create views (always in the desktop shell). */
     available(): boolean;
     /**
-     * Get the shared browser session: the one the host already owns, or a new
-     * one on first use. Shared-browser semantics (Cherry Studio's
-     * `getOrCreateWindow` pattern): the host's startup view and every later
-     * agent call must land on the SAME session and view, so opening again
-     * returns the existing session instead of creating a second view the human
-     * cannot see. Closing the session resets this; the next open starts fresh.
+     * Open a NEW browser session with its own view. Every call mints a fresh
+     * session id and backing view; per-task reuse is owned by the caller (the
+     * tool layer caches one session per DSH task). Sessions are isolated from
+     * each other: each keeps its own tabs, active tab, and history, and only
+     * the active tab of a session is made visible.
      */
     open(): Promise<BrowserSessionId>;
     /** Open a URL in the active tab (default) or a new tab. */
@@ -137,6 +136,8 @@ export declare class ElectronBrowserProvider implements 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 (CDP mousePressed + mouseReleased). */
@@ -148,12 +149,52 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
     type(session: BrowserSessionId, request: {
         readonly text: string;
     }, signal?: AbortSignal): Promise<void>;
+    /**
+     * Fill a form's fields in one batch. Runs one page-context script that
+     * resolves each field (selector, or name/label/placeholder among visible
+     * controls), sets its value with the native prototype setter (React/Vue
+     * controlled inputs included) plus input/change events, handles
+     * select/checkbox/radio/contenteditable, and optionally submits the form.
+     */
+    fillForm(session: BrowserSessionId, request: BrowserFillRequest, signal?: AbortSignal): Promise<BrowserFillResult>;
+    /**
+     * Download a URL to a local file, keeping the session's cookies/login.
+     * Requires the self-hosted host (which implements view-level download); the
+     * desktop shell's embedded views delegate downloads to the real browser UI.
+     */
+    download(session: BrowserSessionId, request: {
+        readonly url: string;
+        readonly savePath: string;
+    }, signal?: AbortSignal): Promise<{
+        readonly path: string;
+    }>;
+    /**
+     * Export the session's cookies (login state) as serializable objects.
+     * Self-hosted only; the desktop shell's embedded views use the real profile.
+     */
+    flushAuth(session: BrowserSessionId): Promise<readonly ExportedCookie[]>;
+    /** Import cookies into the session (restore login state). Self-hosted only. */
+    restoreAuth(session: BrowserSessionId, cookies: readonly ExportedCookie[]): Promise<number>;
     /** Capture the current page, optionally full-page. PNG only (CDP JPEG hangs on Electron 43). */
     screenshot(session: BrowserSessionId, request?: {
         readonly fullPage?: boolean;
+        readonly savePath?: string;
     }, signal?: AbortSignal): Promise<{
         readonly dataUrl: string;
+        readonly path?: string;
     }>;
+    /** Append one operation to the session's history. */
+    private record;
+    /** Return the session's chronological operation log (newest last). */
+    history(session: BrowserSessionId): Promise<readonly BrowserHistoryEntry[]>;
+    /**
+     * Replay one recorded operation by sequence number. Navigate/click/type are
+     * re-issued against the current page; execute re-runs its script. The
+     * replayed step is appended to history as a new entry.
+     * @param session - the session id.
+     * @param seq - the recorded entry's sequence number to replay.
+     */
+    replay(session: BrowserSessionId, seq: number): Promise<void>;
     /** Close the session and destroy all its views. Idempotent. */
     close(session: BrowserSessionId): Promise<void>;
     /** Look up a session or throw the unknown-session error. */