dsh-builtin-browser 0.1.5 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-builtin-browser",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Shared real browser capability for DeepSeek Harness: a visible browser the human watches and can take over, driven by the agent over CDP (snapshot/execute/content/tab management); host-side seam, provider, and browser_* tools",
   "type": "module",
   "main": "lib/index.js",
@@ -30,13 +30,15 @@
   },
   "files": [
     "lib",
+    "src",
     "cordis.patch.yml",
     "README.md",
     "README.en.md",
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json"
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build"
   },
   "keywords": [
     "dsh-plugin",

package/src/browser/runtime.ts

@@ -0,0 +1,260 @@
+/**
+ * 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,
+  BrowserDownloadRequest,
+  BrowserExecuteRequest,
+  BrowserExecuteResult,
+  BrowserFillRequest,
+  BrowserFillResult,
+  BrowserHistoryEntry,
+  BrowserNavigateRequest,
+  BrowserOpenRequest,
+  BrowserProvider,
+  BrowserScreenshotRequest,
+  BrowserScreenshotResult,
+  BrowserSessionId,
+  BrowserSnapshotResult,
+  BrowserTab,
+  BrowserTypeRequest,
+  BrowserChallenge,
+  ExportedCookie,
+} from './types.ts'
+import { BrowserError } from './types.ts'
+
+export {
+  BrowserError,
+} 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
+  }
+}
+
+/**
+ * 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 class BrowserRuntime extends Service {
+  /** Provider selection config. */
+  static Config: z<BrowserRuntimeConfig> = z.object({
+    browserProvider: z.string(),
+  })
+
+  private providers = new Map<string, BrowserProvider>()
+  private readonly providerId: string | undefined
+
+  constructor(ctx: Context, config: BrowserRuntimeConfig = {}) {
+    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: BrowserProvider): () => void {
+    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: BrowserRuntime) {
+      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}. */
+  private resolveProvider(): BrowserProvider {
+    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(): Promise<BrowserSessionId> {
+    return this.resolveProvider().open()
+  }
+
+  /** Open a URL through the selected provider, optionally in a new tab. */
+  async openUrl(session: BrowserSessionId, request: BrowserOpenRequest, signal?: AbortSignal): Promise<void> {
+    return this.resolveProvider().openUrl(session, request, signal)
+  }
+
+  /** List the session's tabs through the selected provider. */
+  async listTabs(session: BrowserSessionId): Promise<readonly BrowserTab[]> {
+    return this.resolveProvider().listTabs(session)
+  }
+
+  /** Switch to a tab through the selected provider. */
+  async switchTab(session: BrowserSessionId, tabId: string): Promise<void> {
+    return this.resolveProvider().switchTab(session, tabId)
+  }
+
+  /** Close one tab through the selected provider. */
+  async closeTab(session: BrowserSessionId, tabId: string): Promise<void> {
+    return this.resolveProvider().closeTab(session, tabId)
+  }
+
+  /** Close every tab and reset the session through the selected provider. */
+  async reset(session: BrowserSessionId): Promise<void> {
+    return this.resolveProvider().reset(session)
+  }
+
+  /** Navigate the session's page through the selected provider. */
+  async navigate(session: BrowserSessionId, request: BrowserNavigateRequest, signal?: AbortSignal): Promise<void> {
+    return this.resolveProvider().navigate(session, request, signal)
+  }
+
+  /** Execute JS in the session's page context through the selected provider. */
+  async execute(session: BrowserSessionId, request: BrowserExecuteRequest, signal?: AbortSignal): Promise<BrowserExecuteResult> {
+    return this.resolveProvider().execute(session, request, signal)
+  }
+
+  /** Produce an AI-friendly snapshot of the session's page. */
+  async snapshot(session: BrowserSessionId, signal?: AbortSignal): Promise<BrowserSnapshotResult> {
+    return this.resolveProvider().snapshot(session, signal)
+  }
+
+  /** Fetch page content in a requested format. */
+  async content(session: BrowserSessionId, request: BrowserContentRequest, signal?: AbortSignal): Promise<BrowserContentResult> {
+    return this.resolveProvider().content(session, request, signal)
+  }
+
+  /** Click at viewport coordinates through the selected provider. */
+  async click(session: BrowserSessionId, request: BrowserClickRequest, signal?: AbortSignal): Promise<void> {
+    return this.resolveProvider().click(session, request, signal)
+  }
+
+  /** Type into the focused element through the selected provider. */
+  async type(session: BrowserSessionId, request: BrowserTypeRequest, signal?: AbortSignal): Promise<void> {
+    return this.resolveProvider().type(session, request, signal)
+  }
+
+  /** Fill a form's fields in one batch through the selected provider. */
+  async fillForm(session: BrowserSessionId, request: BrowserFillRequest, signal?: AbortSignal): Promise<BrowserFillResult> {
+    return this.resolveProvider().fillForm(session, request, signal)
+  }
+
+  /** Capture the current page through the selected provider. */
+  async screenshot(session: BrowserSessionId, request?: BrowserScreenshotRequest, signal?: AbortSignal): Promise<BrowserScreenshotResult> {
+    return this.resolveProvider().screenshot(session, request, signal)
+  }
+
+  /** Check for a human-verification challenge on the active tab. */
+  async detectChallenge(session: BrowserSessionId, signal?: AbortSignal): Promise<BrowserChallenge> {
+    return this.resolveProvider().detectChallenge(session, signal)
+  }
+
+  /** Return the session's chronological operation log through the provider. */
+  async history(session: BrowserSessionId): Promise<readonly BrowserHistoryEntry[]> {
+    return this.resolveProvider().history(session)
+  }
+
+  /** Replay one recorded operation by sequence number through the provider. */
+  async replay(session: BrowserSessionId, seq: number): Promise<void> {
+    return this.resolveProvider().replay(session, seq)
+  }
+
+  /** Download a URL to a local file through the provider. */
+  async download(session: BrowserSessionId, request: BrowserDownloadRequest, signal?: AbortSignal): Promise<{ readonly path: string }> {
+    return this.resolveProvider().download(session, request, signal)
+  }
+
+  /** Export the session's cookies through the provider. */
+  async flushAuth(session: BrowserSessionId): Promise<readonly ExportedCookie[]> {
+    return this.resolveProvider().flushAuth(session)
+  }
+
+  /** Import cookies into the session through the provider. */
+  async restoreAuth(session: BrowserSessionId, cookies: readonly ExportedCookie[]): Promise<number> {
+    return this.resolveProvider().restoreAuth(session, cookies)
+  }
+
+  /** Close the session through the selected provider. Idempotent. */
+  async close(session: BrowserSessionId): Promise<void> {
+    return this.resolveProvider().close(session)
+  }
+}
+
+export default BrowserRuntime
+

package/src/browser/types.ts

@@ -0,0 +1,338 @@
+/**
+ * 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, 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
+ * 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
+}
+
+/** 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
+ * (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
+  /** 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:
+ * 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[]
+  /** Evaluation budget in ms; a wedged page rejects with a timeout. Default 30000. */
+  readonly timeoutMs?: number
+}
+
+/**
+ * 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
+  /** 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
+ * 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, and so on). 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>
+  /** 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
+ * 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 {}
+

package/src/browser-electron/entry.ts

@@ -0,0 +1,58 @@
+/**
+ * Electron browser provider plugin entry: registers the Electron-backed
+ * `BrowserProvider` with `ctx.browser`. The provider needs a view host (real
+ * Electron `WebContentsView` objects). When a desktop shell supplies
+ * `ctx.electronViewHost`, that host is used (embedded, human-machine shared
+ * view). Otherwise the plugin self-hosts: it spawns its own Electron child
+ * (`host-main.js`) and drives it over a local TCP JSON-RPC socket, so
+ * installing the plugin is enough for `browser_*` tools to work on any
+ * surface.
+ * @module dsh-browser/browser-electron
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import type { BrowserRuntime } from '../browser/runtime.ts'
+import { ElectronBrowserProvider } from './provider.ts'
+import type { ElectronBrowserViewHost } from './provider.ts'
+import { defaultHostMainPath, RemoteElectronViewHost } from './remote-host.ts'
+
+export {
+  ELECTRON_BROWSER_PROVIDER_ID,
+  ElectronBrowserProvider,
+} from './provider.ts'
+export type { ElectronBrowserViewHost, ElectronViewHandle } from './provider.ts'
+export { RemoteElectronViewHost, defaultHostMainPath } from './remote-host.ts'
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'browser-electron'
+
+/** The browser seam this provider registers into. */
+export const inject = ['browser']
+
+/** Plugin config: an optional externally-supplied view host. */
+export interface Config {
+  /** View host supplied by a desktop shell; absent -> self-host. */
+  readonly viewHost?: ElectronBrowserViewHost
+  /** Allow navigation only to HTTP(S) URLs. Default true. */
+  readonly httpOnly?: boolean
+}
+
+export const Config: z<Config> = z.object({
+  // Absent on surfaces without a desktop shell; the plugin self-hosts then.
+  viewHost: z.any(),
+  httpOnly: z.boolean().default(true),
+})
+
+/** Register the Electron browser provider with `ctx.browser`. */
+export function apply(ctx: Context & { browser: BrowserRuntime }, config: Config): void {
+  // External host (desktop shell) wins; otherwise self-host. The self-hosted
+  // child is disposed with the fiber, mirroring the shell's lifetime.
+  const host: ElectronBrowserViewHost = config.viewHost ?? new RemoteElectronViewHost(defaultHostMainPath())
+  ctx.effect(() => () => {
+    if (config.viewHost === undefined && host instanceof RemoteElectronViewHost) {
+      host.dispose()
+    }
+  })
+  ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(host, { httpOnly: config.httpOnly }))
+}