dsh-builtin-browser 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-browser contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,89 @@
+# dsh-builtin-browser (built-in shared real browser plugin for DeepSeek Harness)
+
+中文 | [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.
+
+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.
+
+## Features
+
+- **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.
+
+## Requirements
+
+- DeepSeek Harness (dsh) with the `web` profile
+- A host that provides `ctx.electronViewHost` (a machine holding real Electron `WebContentsView`s, e.g. dsh's desktop shell). Without one, the plugin mounts the seam but the provider and tools stay disabled — plain `dsh web` is unaffected.
+
+## Install
+
+```sh
+dsh plugin --profile web add dsh-builtin-browser  # from npm once published
+# or from a checkout (one plugin, one repository):
+dsh plugin --profile web add <path-to-this-repo>
+```
+
+This links the plugin, adds `dsh-builtin-browser` to the profile's bundle layer, and mounts:
+
+| Row | Subpath | Role |
+|---|---|---|
+| `browser` | `dsh-builtin-browser/browser` | `ctx.browser` capability seam (always mounted) |
+| `browser-electron` | `dsh-builtin-browser/browser-electron` | Electron CDP provider (needs `electronViewHost`) |
+| `tool-browser` | `dsh-builtin-browser/tool-browser` | `browser_*` model-facing tools |
+
+The provider and tools are gated on `ctx.get('electronViewHost')` being present, so a composition without a desktop shell simply keeps the seam and nothing else.
+
+## Configuration
+
+The plugin mounts through `cordis.patch.yml`; per-row config:
+
+| Row | Key | Type | Default | Description |
+|---|---|---|---|---|
+| `browser-electron` | `viewHost` | object | required | `ElectronBrowserViewHost` supplied by the host shell (typically `!!js ctx.get('electronViewHost')`) |
+| `browser-electron` | `httpOnly` | boolean | `true` | Allow HTTP(S) navigation only; other protocols (e.g. `file:`/`data:`) are rejected (`BROWSER_NAVIGATION_BLOCKED`) |
+| `browser-electron` | `snapshotMaxElements` | number | `60` | Max snapshot elements before truncation |
+| `browser-electron` | `contentMaxChars` | number | `100000` | Default content character cap |
+| `tool-browser` | `timeoutMs` | number | `60000` | Cooperative tool timeout (ms) |
+| `tool-browser` | `tabTools` | boolean | `true` | Register tab-management tools (`browser_list_tabs` etc.) |
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `browser_open` | Open a URL (optionally a new tab); returns a snapshot |
+| `browser_snapshot` | Numbered inventory of interactive elements (inputs/buttons/links) |
+| `browser_execute` | Run JS in the page; args arrive as `arguments[0..n]` |
+| `browser_content` | Fetch the page as html / markdown / txt / json (selector, maxChars, timeoutMs) |
+| `browser_screenshot` | PNG capture, optional `fullPage` |
+| `browser_list_tabs` / `browser_switch_tab` / `browser_close_tab` / `browser_reset` | Multi-tab session management |
+
+## How it works
+
+```
+agent (browser_* tools)
+  → ctx.browser (seam, dsh-builtin-browser/browser)
+  → dsh-builtin-browser/browser-electron (provider)
+  → ElectronBrowserViewHost (supplied by the host shell)
+  → WebContentsView + webContents.debugger (CDP)
+```
+
+The provider is Electron-agnostic by construction: it operates through the `ElectronBrowserViewHost` seam (create/destroy/show views, `sendCommand`), which a real shell implements with Electron objects. The same seam lets a future relay provider (headless Chromium screenshot stream) serve remote deployments without touching the tools.
+
+## Division of labor with the desktop shell
+
+The browser's **visible view**, the **browser column layout**, and the **column-to-view alignment** belong to the host shell (e.g. dsh's `apps/desktop`), not this plugin. This plugin only consumes the shell-provided `electronViewHost` and owns the seam, provider, and tools. Installing the plugin without a matching shell leaves the capability disabled.
+
+## Known limitations
+
+- Screenshots are PNG-only (CDP JPEG hangs on Electron 43); JPEG awaits a non-CDP conversion path.
+- `fullPage` capture is flaky under software compositing on some hosts.
+- Session lifecycle is plugin-level (one session shared by the model), not per-agent yet.
+- Private mode (`privateMode`) is not implemented: it needs Electron session partitioning, which is host-layer territory; this plugin does not promise it.
+- This plugin contains no browser-column UI — that is host-shell territory; do not treat "browser column" as a plugin feature.
+
+## License
+
+MIT

package/README.md

@@ -0,0 +1,89 @@
+# dsh-builtin-browser（DeepSeek Harness 内置共享真实浏览器插件）
+
+[English](README.en.md) | 中文
+
+面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的共享真实浏览器能力插件:一个用户可见、可随时接管的浏览器,由 agent 通过 CDP 驱动。
+
+本插件提供 **host 侧能力**(浏览器 seam、Electron CDP provider、`browser_*` 模型工具)。浏览器本身的**原生视图**由宿主(桌面外壳)通过 `ctx.electronViewHost` 提供;插件不包含浏览器界面 UI。
+
+## 功能
+
+- **真实视图,而非转播。** 浏览器是原生视图(`WebContentsView`),用户可直接看到并操作;agent 驱动的是同一个页面。视图由宿主外壳提供,插件负责驱动。
+- **DOM 引用,而非猜坐标。** `browser_snapshot` 返回带编号的交互元素;`browser_execute` 在页面里执行 JS(框架输入用原生 setter),在 React/Vue 页面上也能可靠交互。
+- **多标签会话。** 并行打开 URL、查看/切换/关闭/重置标签,状态保持。
+- **多格式内容。** 以 html / markdown / txt / json 抓取页面,支持 selector 限定、长度与超时上限。
+
+## 环境要求
+
+- DeepSeek Harness(dsh)且安装了 `web` profile
+- 提供 `ctx.electronViewHost` 的宿主(持有真实 Electron `WebContentsView` 的主机,如 dsh 的桌面外壳)。没有它时,插件只挂载 seam,provider 与工具保持禁用——纯 `dsh web` 不受影响。
+
+## 安装
+
+```sh
+dsh plugin --profile web add dsh-builtin-browser   # 发布到 npm 后
+# 或从源码目录(独立仓库,一插件一仓库):
+dsh plugin --profile web add <本仓库路径>
+```
+
+这会链接插件、把 `dsh-builtin-browser` 加入 profile 的 bundle 层,并挂载:
+
+| 行 | 子路径 | 角色 |
+|---|---|---|
+| `browser` | `dsh-builtin-browser/browser` | `ctx.browser` 能力 seam(始终挂载) |
+| `browser-electron` | `dsh-builtin-browser/browser-electron` | Electron CDP provider(需要 `electronViewHost`) |
+| `tool-browser` | `dsh-builtin-browser/tool-browser` | `browser_*` 模型侧工具 |
+
+provider 与工具以 `ctx.get('electronViewHost')` 是否存在为门控,因此没有桌面外壳的组合只会保留 seam,其余不启用。
+
+## 配置
+
+插件通过 `cordis.patch.yml` 挂载,各行的配置:
+
+| 行 | 配置项 | 类型 | 默认 | 说明 |
+|---|---|---|---|---|
+| `browser-electron` | `viewHost` | 对象 | 必填 | 宿主提供的 `ElectronBrowserViewHost` 实例(通常 `!!js ctx.get('electronViewHost')`) |
+| `browser-electron` | `httpOnly` | 布尔 | `true` | 仅允许 HTTP(S) 导航;其余协议(如 `file:`/`data:`)拒绝(`BROWSER_NAVIGATION_BLOCKED`) |
+| `browser-electron` | `snapshotMaxElements` | 数字 | `60` | 快照最多收录的交互元素数,超出截断 |
+| `browser-electron` | `contentMaxChars` | 数字 | `100000` | 内容抓取默认字符上限 |
+| `tool-browser` | `timeoutMs` | 数字 | `60000` | 工具协作超时(ms) |
+| `tool-browser` | `tabTools` | 布尔 | `true` | 是否注册标签管理工具(`browser_list_tabs` 等) |
+
+## 工具
+
+| 工具 | 用途 |
+|---|---|
+| `browser_open` | 打开 URL(可选新标签);返回快照 |
+| `browser_snapshot` | 交互元素(输入框/按钮/链接)带编号清单 |
+| `browser_execute` | 在页面执行 JS;参数以 `arguments[0..n]` 传入 |
+| `browser_content` | 以 html / markdown / txt / json 抓取页面(selector、maxChars、timeoutMs) |
+| `browser_screenshot` | PNG 截图,可选 `fullPage` |
+| `browser_list_tabs` / `browser_switch_tab` / `browser_close_tab` / `browser_reset` | 多标签会话管理 |
+
+## 工作原理
+
+```
+agent (browser_* 工具)
+  → ctx.browser (seam, dsh-builtin-browser/browser)
+  → dsh-builtin-browser/browser-electron (provider)
+  → ElectronBrowserViewHost (由宿主外壳提供)
+  → WebContentsView + webContents.debugger (CDP)
+```
+
+provider 按构造与 Electron 解耦:它通过 `ElectronBrowserViewHost` 接缝操作(创建/销毁/显示视图、`sendCommand`),由真实外壳用 Electron 对象实现。同一接缝也让未来的转播 provider(无头 Chromium 截图流)服务远程部署,而无需改动工具。
+
+## 与桌面外壳的分工
+
+浏览器**可见视图**、**浏览器列布局**、**列与视图的对齐**都属于宿主外壳(如 dsh 的 `apps/desktop`),不在本插件内。本插件只消费外壳提供的 `electronViewHost`,负责 seam、provider 与工具。若你只装插件而没有配套外壳,插件功能保持禁用。
+
+## 已知限制
+
+- 截图仅 PNG(CDP JPEG 在 Electron 43 上挂起);JPEG 等待非 CDP 转换路径。
+- 部分主机在软件合成下 `fullPage` 截图不稳定。
+- 会话生命周期为插件级(模型共享一个会话),尚未做到按 agent 隔离。
+- 无痕模式(`privateMode`)未实现:它需要 Electron 的 session 分区能力,属于宿主层,本插件不承诺。
+- 本插件不含浏览器列 UI——那是宿主外壳的配套,别把"浏览器列"当成插件能力。
+
+## 许可证
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,19 @@
+# dsh-builtin-browser bundle patch: mounts the shared-browser capability into a
+# profile composition. The browser seam (ctx.browser) is always mounted; the
+# Electron provider activates only where the host provides `electronViewHost`
+# (the desktop shell or any host that supplies a view host through
+# `ctx.get('electronViewHost')`), and the model-facing tools ride the same
+# gate so plain `dsh web` (no native view) stays unaffected.
+- insert:
+    - id: browser
+      name: dsh-builtin-browser/browser
+
+    - id: browser-electron
+      name: dsh-builtin-browser/browser-electron
+      disabled: !!js ctx.get('electronViewHost') === undefined
+      config:
+        viewHost: !!js ctx.get('electronViewHost')
+
+    - id: tool-browser
+      name: dsh-builtin-browser/tool-browser
+      disabled: !!js ctx.get('electronViewHost') === undefined

package/lib/browser/runtime.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 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/browser
+ */
+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';
+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';
+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(): 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<void>;
+    /** 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>;
+    /** 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, signal?: AbortSignal): Promise<BrowserSnapshotResult>;
+    /** 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: BrowserClickRequest, signal?: AbortSignal): Promise<void>;
+    /** Type into the focused element through the selected provider. */
+    type(session: BrowserSessionId, request: BrowserTypeRequest, signal?: AbortSignal): Promise<void>;
+    /** Capture the current page through the selected provider. */
+    screenshot(session: BrowserSessionId, request?: BrowserScreenshotRequest, signal?: AbortSignal): Promise<BrowserScreenshotResult>;
+    /** Close the session through the selected provider. Idempotent. */
+    close(session: BrowserSessionId): Promise<void>;
+}
+export default BrowserRuntime;

package/lib/browser/runtime.js

@@ -0,0 +1,138 @@
+/**
+ * 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/browser
+ */
+import { Service } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { BrowserError } from "./types.js";
+export { BrowserError, } from "./types.js";
+/**
+ * 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 class BrowserRuntime extends Service {
+    /** Provider selection config. */
+    static Config = z.object({
+        browserProvider: z.string(),
+    });
+    providers = new Map();
+    providerId;
+    constructor(ctx, config = {}) {
+        super(ctx, 'browser');
+        this.providerId = config.browserProvider;
+    }
+    /**
+     * 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) {
+        if (this.providers.has(provider.id)) {
+            throw new BrowserError(`a browser provider with id "${provider.id}" is already registered`, 'BROWSER_DUPLICATE_PROVIDER');
+        }
+        // Bind the generator to this instance instead of aliasing `this` to a
+        // local (no-this-alias): the effect body mutates the instance registry.
+        const dispose = this.ctx.effect(function* () {
+            this.providers.set(provider.id, provider);
+            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.
+        return () => void dispose();
+    }
+    /** Resolve the selected provider or throw the matching {@link BrowserError}. */
+    resolveProvider() {
+        const { providerId, providers } = this;
+        if (providerId !== undefined) {
+            const provider = providers.get(providerId);
+            if (!provider) {
+                throw new BrowserError(`configured browser provider "${providerId}" is not registered`, 'BROWSER_PROVIDER_CONFIGURED_MISSING');
+            }
+            if (!provider.available()) {
+                throw new BrowserError(`configured browser provider "${providerId}" is registered but unavailable`, 'BROWSER_PROVIDER_CONFIGURED_UNAVAILABLE');
+            }
+            return provider;
+        }
+        const usable = [...providers.values()].filter(provider => provider.available());
+        const [single] = usable;
+        if (single === undefined) {
+            throw new BrowserError('no usable browser provider is registered', 'BROWSER_PROVIDER_UNAVAILABLE');
+        }
+        if (usable.length > 1) {
+            const ids = usable.map(provider => provider.id).join(', ');
+            throw new BrowserError(`multiple usable browser providers are registered (${ids}); configure one explicitly`, 'BROWSER_PROVIDER_AMBIGUOUS');
+        }
+        return single;
+    }
+    /** Open a new browser session through the selected provider. */
+    async open() {
+        return this.resolveProvider().open();
+    }
+    /** Open a URL through the selected provider, optionally in a new tab. */
+    async openUrl(session, request, signal) {
+        return this.resolveProvider().openUrl(session, request, signal);
+    }
+    /** List the session's tabs through the selected provider. */
+    async listTabs(session) {
+        return this.resolveProvider().listTabs(session);
+    }
+    /** Switch to a tab through the selected provider. */
+    async switchTab(session, tabId) {
+        return this.resolveProvider().switchTab(session, tabId);
+    }
+    /** Close one tab through the selected provider. */
+    async closeTab(session, tabId) {
+        return this.resolveProvider().closeTab(session, tabId);
+    }
+    /** Close every tab and reset the session through the selected provider. */
+    async reset(session) {
+        return this.resolveProvider().reset(session);
+    }
+    /** Navigate the session's page through the selected provider. */
+    async navigate(session, request, signal) {
+        return this.resolveProvider().navigate(session, request, signal);
+    }
+    /** Execute JS in the session's page context through the selected provider. */
+    async execute(session, request, signal) {
+        return this.resolveProvider().execute(session, request, signal);
+    }
+    /** Produce an AI-friendly snapshot of the session's page. */
+    async snapshot(session, signal) {
+        return this.resolveProvider().snapshot(session, signal);
+    }
+    /** Fetch page content in a requested format. */
+    async content(session, request, signal) {
+        return this.resolveProvider().content(session, request, signal);
+    }
+    /** Click at viewport coordinates through the selected provider. */
+    async click(session, request, signal) {
+        return this.resolveProvider().click(session, request, signal);
+    }
+    /** Type into the focused element through the selected provider. */
+    async type(session, request, signal) {
+        return this.resolveProvider().type(session, request, signal);
+    }
+    /** Capture the current page through the selected provider. */
+    async screenshot(session, request, signal) {
+        return this.resolveProvider().screenshot(session, request, signal);
+    }
+    /** Close the session through the selected provider. Idempotent. */
+    async close(session) {
+        return this.resolveProvider().close(session);
+    }
+}
+export default BrowserRuntime;

package/lib/browser/types.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Vocabulary for the browser capability seam (`ctx.browser`). One seam owns
+ * 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, 鈥?.
+ * @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
+ * and its host binding can interpret it.
+ */
+export type BrowserSessionId = string;
+/**
+ * What one browser-capable backend is asked to do. Navigation is the minimal
+ * operation every provider shares; the seam deliberately keeps the request
+ * minimal so a provider swap never changes how the model asks.
+ */
+export interface BrowserNavigateRequest {
+    /** The URL to open. Admission (HTTP(S) only, no credentials/private targets) is provider-owned. */
+    readonly url: string;
+}
+/**
+ * Click at viewport coordinates. Coordinates are viewport-relative pixels in
+ * 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 {
+    /** Viewport-relative x in CSS pixels. */
+    readonly x: number;
+    /** Viewport-relative y in CSS pixels. */
+    readonly y: number;
+}
+/** Type text into the focused element. */
+export interface BrowserTypeRequest {
+    /** The text to insert. */
+    readonly text: string;
+}
+/**
+ * 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
+ * (the human watches the real view in the desktop shape).
+ */
+export interface BrowserScreenshotResult {
+    /** Base64 data URL of the capture (PNG or JPEG per the request). */
+    readonly dataUrl: 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;
+}
+/**
+ * Execute arbitrary JavaScript in the session's page context. This is the
+ * 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.
+ */
+export interface BrowserExecuteRequest {
+    /** The JavaScript expression to evaluate in the page context. */
+    readonly script: string;
+    /** Optional arguments injected into the script scope as `arguments[0..n]`. */
+    readonly args?: readonly unknown[];
+}
+/**
+ * Result of an execute. Mirrors CDP `Runtime.evaluate` semantics: either a
+ * value (by value, not by reference) or the exception thrown.
+ */
+export type BrowserExecuteResult = {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly exception: string;
+};
+/**
+ * One interactive element in a snapshot, with a stable reference number the
+ * tool layer (and the model) can cite to target the element.
+ */
+export interface BrowserSnapshotElement {
+    /** 1-based reference number, stable for the lifetime of one snapshot. */
+    readonly ref: number;
+    /** Element kind: 'input' | 'button' | 'link' | 'textarea' | 'select' | 'checkbox' | 'other'. */
+    readonly kind: string;
+    /** Text content or placeholder/label, truncated for the snapshot. */
+    readonly label: string;
+    /** Best-effort CSS selector; may be empty when none is derivable. */
+    readonly selector: string;
+    /** Viewport-relative center, for coordinate fallbacks. */
+    readonly x: number;
+    readonly y: number;
+}
+/**
+ * AI-friendly page snapshot: a compact, numbered inventory of interactive
+ * elements plus page facts. Not raw HTML 鈥?the model dialogues with this.
+ */
+export interface BrowserSnapshotResult {
+    /** Final page URL. */
+    readonly url: string;
+    /** Page title, if any. */
+    readonly title?: string;
+    /** Numbered interactive elements. */
+    readonly elements: readonly BrowserSnapshotElement[];
+    /** True when the snapshot was truncated (element cap reached). */
+    readonly truncated: boolean;
+}
+/**
+ * Content fetch formats. `html` is the raw DOM; `markdown` is a structured
+ * reading view; `txt` is plain text (smallest); `json` is structured data.
+ */
+export type BrowserContentFormat = 'html' | 'markdown' | 'txt' | 'json';
+/** Content fetch request: format, optional selector scoping, and caps. */
+export interface BrowserContentRequest {
+    /** Desired format. */
+    readonly format: BrowserContentFormat;
+    /** Optional CSS selector limiting the fetch to one region (e.g. `#main`). */
+    readonly selector?: string;
+    /** Maximum characters of the returned content. */
+    readonly maxChars?: number;
+    /** Evaluation timeout in ms; the fetch aborts after this. Default 30000. */
+    readonly timeoutMs?: number;
+}
+/** A fetched page content in the requested format. */
+export interface BrowserContentResult {
+    /** The content in the requested format, capped at `maxChars`. */
+    readonly content: string;
+    /** True when the content was truncated. */
+    readonly truncated: boolean;
+}
+/**
+ * A tab inside a browser session. Tabs share the session's profile/cookies
+ * and are switchable without losing state.
+ */
+export interface BrowserTab {
+    /** Stable tab id within the session. */
+    readonly id: string;
+    /** Current URL, or empty for a blank tab. */
+    readonly url: string;
+    /** Page title, if any. */
+    readonly title?: string;
+    /** Whether this tab is the active one. */
+    readonly active: boolean;
+}
+/** Request to open a URL: into the active tab or a new tab. */
+export interface BrowserOpenRequest {
+    /** The URL to open. */
+    readonly url: string;
+    /** Open in a new tab (parallel). Default false (reuse the active tab). */
+    readonly newTab?: boolean;
+}
+/**
+ * A browser-capable backend. Registered with `ctx.browser.registerBrowserProvider`.
+ * `id` is a stable string, unique across the seam.
+ */
+export interface BrowserProvider {
+    readonly id: string;
+    /** Cheap local usability check; must not make network calls. */
+    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
+     * each other; a session must not be visible to any other session's caller.
+     */
+    open(): Promise<BrowserSessionId>;
+    /** Open a URL, optionally in a new tab. Honor `signal` for cancellation. */
+    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`. */
+    switchTab(session: BrowserSessionId, tabId: string): Promise<void>;
+    /** Close one tab. Closing the active tab activates the next. */
+    closeTab(session: BrowserSessionId, tabId: string): Promise<void>;
+    /** Close every tab and reset the session's state. */
+    reset(session: BrowserSessionId): Promise<void>;
+    /** Navigate the active tab. Honor `signal` for cancellation. */
+    navigate(session: BrowserSessionId, request: BrowserNavigateRequest, signal?: AbortSignal): Promise<void>;
+    /** Execute JS in the active tab's page context. */
+    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>;
+    /** 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>;
+    /** Capture the current page. Honor `signal` for cancellation. */
+    screenshot(session: BrowserSessionId, request?: BrowserScreenshotRequest, signal?: AbortSignal): Promise<BrowserScreenshotResult>;
+    /** Close the session and destroy its backing surface. Idempotent. */
+    close(session: BrowserSessionId): Promise<void>;
+}
+/**
+ * Typed browser error with a machine-routable, open-string `code` and chained
+ * `cause`. Consumers must tolerate provider-specific codes. Shared codes cover
+ * unavailable, missing, unusable, ambiguous, or duplicate providers, unknown
+ * or closed sessions, cancellation, and provider failure; a provider adds its
+ * own (e.g. `BROWSER_CDP_ATTACH_FAILED`).
+ */
+export declare class BrowserError extends HarnessError {
+}

package/lib/browser/types.js

@@ -0,0 +1,18 @@
+/**
+ * Vocabulary for the browser capability seam (`ctx.browser`). One seam owns
+ * 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, 鈥?.
+ * @module dsh-browser/browser/types
+ */
+import { HarnessError } from '@deepseek-ai/dsh-llm';
+/**
+ * Typed browser error with a machine-routable, open-string `code` and chained
+ * `cause`. Consumers must tolerate provider-specific codes. Shared codes cover
+ * unavailable, missing, unusable, ambiguous, or duplicate providers, unknown
+ * or closed sessions, cancellation, and provider failure; a provider adds its
+ * own (e.g. `BROWSER_CDP_ATTACH_FAILED`).
+ */
+export class BrowserError extends HarnessError {
+}