dsh-browser-plus 0.0.0-stage → 0.5.0

package/scripts/smoke-chrome-world.mjs

@@ -0,0 +1,63 @@
+/**
+ * Verify chromeWorld: 'isolated' in a real window.
+ *
+ * This is the one declared feature that had never been exercised: the chrome is
+ * injected into an isolated world so the page's own scripts cannot read its
+ * globals. The claim has two halves -- the chrome still mounts, and the page's
+ * main world cannot see it -- and an A/B against the default mode proves the
+ * switch actually changes something rather than being inert.
+ *
+ * Run: npm run smoke:chrome-world
+ */
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { RemoteElectronViewHost, defaultHostMainPath } from '../lib/browser-electron/remote-host.js'
+
+const wait = ms => new Promise(resolve => setTimeout(resolve, ms))
+const results = []
+
+const probe = async (label, options) => {
+  const profile = mkdtempSync(join(tmpdir(), 'dsh-chrome-world-'))
+  process.env.DSH_BROWSER_PLUS_USER_DATA = profile
+  const host = new RemoteElectronViewHost(defaultHostMainPath(), options)
+  try {
+    const view = host.createView('chrome-world', 'Chrome World')
+    await view.sendCommand('Page.enable', {})
+    await view.sendCommand('Page.navigate', { url: 'https://example.com/' })
+    await wait(2500)
+    const reply = await view.sendCommand('Runtime.evaluate', {
+      expression: 'JSON.stringify({ chromeHost: document.getElementById("__dsh_browser_chrome_host__") !== null, binding: typeof window.__dshBrowserTaskAction, tasks: typeof window.__dshTasks, trail: typeof window.__dshTrail })',
+      returnByValue: true,
+    })
+    const value = JSON.parse(reply?.result?.value ?? '{}')
+    results.push({ label, ...value })
+    console.log('  ' + label.padEnd(22) + JSON.stringify(value))
+    return value
+  } finally {
+    host.dispose()
+    await wait(1500)
+    try { rmSync(profile, { recursive: true, force: true }) } catch { /* briefly locked */ }
+  }
+}
+
+const main = await probe('main (default)', {})
+const isolated = await probe('isolated', { chromeWorld: 'isolated' })
+
+// Assert only what chromeWorld claims. window.__dshBrowserTaskAction is reported
+// but not asserted: it appears asynchronously after load, so a fixed wait
+// measures it inconsistently (observed both ways at 2.5s and 3s).
+const failures = []
+if (main.chromeHost !== true) failures.push('the chrome did not mount in main mode')
+if (main.tasks !== 'object' || main.trail !== 'object') failures.push('main mode should leak the chrome globals, or the A/B proves nothing')
+if (isolated.chromeHost !== true) failures.push('the chrome did not mount in isolated mode')
+for (const key of ['binding', 'tasks', 'trail']) {
+  if (isolated[key] !== 'undefined') failures.push('isolated mode still leaks window.' + (key === 'binding' ? '__dshBrowserTaskAction' : '__dsh' + key[0].toUpperCase() + key.slice(1)))
+}
+console.log('')
+if (failures.length > 0) {
+  console.log(JSON.stringify({ ok: false, failures }))
+  process.exit(1)
+}
+console.log(JSON.stringify({ ok: true, note: 'the chrome mounts in both modes; only the default leaks its globals to the page' }))

package/scripts/smoke-electron-host.mjs

@@ -0,0 +1,50 @@
+import assert from 'node:assert/strict'
+
+import { RemoteElectronViewHost, defaultHostMainPath } from '../lib/browser-electron/remote-host.js'
+
+function withTimeout(promise, timeoutMs, label) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(label + ' timed out after ' + String(timeoutMs) + 'ms')), timeoutMs)
+    promise.then(
+      value => { clearTimeout(timer); resolve(value) },
+      error => { clearTimeout(timer); reject(error) },
+    )
+  })
+}
+
+function delay(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+const host = new RemoteElectronViewHost(defaultHostMainPath())
+try {
+  const view = host.createView('electron-host-smoke', 'Electron Host Smoke')
+  await withTimeout(view.sendCommand('Page.navigate', { url: 'http://127.0.0.1:3080/' }), 15_000, 'Page.navigate')
+  const binding = await withTimeout(view.sendCommand('Runtime.evaluate', {
+    expression: 'typeof window.__dshBrowserTaskAction',
+    returnByValue: true,
+  }), 10_000, 'binding probe')
+  assert.equal(binding.result?.value, 'function', 'page task binding must be present')
+  const chromeReady = await withTimeout(view.sendCommand('Runtime.evaluate', {
+    expression: "new Promise(resolve => { const deadline = Date.now() + 3000; const inspect = () => { const host = document.getElementById('__dsh_browser_chrome_host__'); if (host?.getAttribute('data-dsh-browser-ready') === '1' || Date.now() >= deadline) { resolve(host?.getAttribute('data-dsh-browser-ready') || null); return } setTimeout(inspect, 50) }; inspect() })",
+    returnByValue: true,
+    awaitPromise: true,
+  }), 5_000, 'chrome ready probe')
+  assert.equal(chromeReady.result?.value, '1', 'page chrome must finish wiring interactive controls')
+
+  // The renderer's direct DOM interaction path is covered by page-chrome
+  // regression tests. CDP Input.dispatchMouseEvent does not surface a DOM
+  // pointer event in Electron 42, so it cannot faithfully stand in for a hand.
+  await delay(300)
+  await withTimeout(view.sendCommand('Runtime.evaluate', {
+    expression: "window.__dshBrowserTaskAction(JSON.stringify({ type: 'set-control-owner', taskKey: 'electron-host-smoke', control: 'human' })); 'sent'",
+    returnByValue: true,
+  }), 10_000, 'binding action')
+  await delay(300)
+  const task = await withTimeout(host.getTask('electron-host-smoke'), 10_000, 'task state query')
+  assert.equal(task?.control, 'human', 'Host must receive the page handoff')
+  assert.equal(task?.status, 'waiting-user', 'Host must show the handoff state')
+  console.log(JSON.stringify({ ok: true, task }))
+} finally {
+  host.dispose()
+}

package/src/browser/runtime.ts

@@ -0,0 +1,470 @@
+/**
+ * Service Definition for the browser capability seam (`ctx.browser`): the
+ * provider registry and provider-selecting execution for browser sessions.
+ * Duplicate ids are rejected. At execution time, a configured provider must
+ * exist and be usable; without one, exactly one usable provider is required,
+ * so selection never depends on registration order.
+ * @module dsh-browser-plus/browser
+ */
+
+import { Context, Service } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import type {
+  BrowserContentRequest,
+  BrowserHandoffState,
+  BrowserContentResult,
+  BrowserDownloadRequest,
+  BrowserExecuteRequest,
+  BrowserExecuteResult,
+  BrowserFillRequest,
+  BrowserFillResult,
+  BrowserHistoryEntry,
+  BrowserNavigateRequest,
+  BrowserOpenOptions,
+  BrowserOpenRequest,
+  BrowserDragRequest,
+  BrowserDragResult,
+  BrowserPointerResult,
+  BrowserPointerTarget,
+  BrowserPressKeyRequest,
+  BrowserClearAuthRequest,
+  BrowserScrapeRequest,
+  BrowserScrapeStatus,
+  BrowserClearAuthResult,
+  BrowserProvider,
+  BrowserRefRequest,
+  BrowserScreenshotRequest,
+  BrowserScreenshotResult,
+  BrowserScrollIntoViewRequest,
+  BrowserScrollRequest,
+  BrowserScrollResult,
+  BrowserSessionId,
+  BrowserSnapshotResult,
+  BrowserSpaceInfo,
+  BrowserTaskInfo,
+  BrowserTaskUpdate,
+  BrowserTab,
+  BrowserTypeRequest,
+  BrowserUploadFileRequest,
+  BrowserUploadFileResult,
+  BrowserWaitForRequest,
+  BrowserWaitForResult,
+  BrowserChallenge,
+  ExportedCookie,
+} from './types.ts'
+import { BrowserError } from './types.ts'
+
+export {
+  BrowserError,
+} from './types.ts'
+export type {
+  BrowserChallenge,
+  BrowserContentFormat,
+  BrowserControlOwner,
+  BrowserContentRequest,
+  BrowserContentResult,
+  BrowserDownloadRequest,
+  BrowserExecuteRequest,
+  BrowserExecuteResult,
+  BrowserFillField,
+  BrowserFillRequest,
+  BrowserFillResult,
+  BrowserHandoffState,
+  BrowserHistoryEntry,
+  BrowserNavigateRequest,
+  BrowserOpenOptions,
+  BrowserOpenRequest,
+  BrowserDragRequest,
+  BrowserDragResult,
+  BrowserPointerResult,
+  BrowserPointerTarget,
+  BrowserPressKeyRequest,
+  BrowserClearAuthRequest,
+  BrowserScrapeRequest,
+  BrowserScrapeStatus,
+  BrowserClearAuthResult,
+  BrowserProvider,
+  BrowserRefRequest,
+  BrowserScreenshotRequest,
+  BrowserScreenshotResult,
+  BrowserScrollIntoViewRequest,
+  BrowserScrollRequest,
+  BrowserScrollResult,
+  BrowserSessionId,
+  BrowserSnapshotElement,
+  BrowserSnapshotResult,
+  BrowserSpaceInfo,
+  BrowserTaskInfo,
+  BrowserTaskStatus,
+  BrowserTaskUpdate,
+  BrowserTab,
+  BrowserTypeRequest,
+  BrowserUploadFileRequest,
+  BrowserUploadFileResult,
+  BrowserWaitForRequest,
+  BrowserWaitForResult,
+  ExportedCookie,
+} from './types.ts'
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    browser: BrowserRuntime
+  }
+}
+
+/**
+ * Config for the browser seam. `browserProvider` pins which provider wins;
+ * it is optional (a single registered usable provider auto-selects).
+ */
+export interface BrowserRuntimeConfig {
+  /** Explicit browser provider id. Omitted = auto-select when exactly one usable. */
+  readonly browserProvider?: string
+}
+
+/**
+ * The browser access service. Registered as `ctx.browser` (one instance per
+ * context).
+ *
+ * Selection semantics (resolved at execution time, never order-dependent):
+ * - A configured id that is registered and `available()` → that provider.
+ * - A configured id not registered → `BROWSER_PROVIDER_CONFIGURED_MISSING`.
+ * - A configured id registered but unavailable → `BROWSER_PROVIDER_CONFIGURED_UNAVAILABLE`.
+ * - No id configured, exactly one registered usable provider → that provider.
+ * - No id configured, multiple usable providers → `BROWSER_PROVIDER_AMBIGUOUS`.
+ * - No id configured, no usable provider → `BROWSER_PROVIDER_UNAVAILABLE`.
+ */
+export 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(options?: BrowserOpenOptions): Promise<BrowserSessionId> {
+    return this.resolveProvider().open(options)
+  }
+
+  /** 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<boolean> {
+    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)
+  }
+
+  /** Navigate to the previous history entry through the selected provider. */
+  async back(session: BrowserSessionId, signal?: AbortSignal): Promise<boolean> {
+    return this.resolveProvider().back(session, signal)
+  }
+
+  /** Navigate to the next history entry through the selected provider. */
+  async forward(session: BrowserSessionId, signal?: AbortSignal): Promise<boolean> {
+    return this.resolveProvider().forward(session, signal)
+  }
+
+  /** Reload the active page through the selected provider. */
+  async reload(session: BrowserSessionId, signal?: AbortSignal): Promise<void> {
+    return this.resolveProvider().reload(session, signal)
+  }
+
+  /** Stop loading the active page through the selected provider. */
+  async stopLoading(session: BrowserSessionId, signal?: AbortSignal): Promise<void> {
+    return this.resolveProvider().stopLoading(session, 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, options: { query?: string; limit?: number } = {}, signal?: AbortSignal): Promise<BrowserSnapshotResult> {
+    return this.resolveProvider().snapshot(session, options, signal)
+  }
+
+  /** Apply device/viewport/media emulation to the session's active tab. */
+  async emulate(session: BrowserSessionId, options: { width?: number; height?: number; deviceScaleFactor?: number; mobile?: boolean; userAgent?: string; colorScheme?: 'light' | 'dark' | 'no-preference'; clear?: boolean } = {}): Promise<{ applied: string[] }> {
+    return this.resolveProvider().emulate(session, options)
+  }
+
+  /** Console messages the host captured for the session's active tab. */
+  async consoleMessages(session: BrowserSessionId, options: { limit?: number; level?: string; clear?: boolean } = {}): Promise<{ messages: Array<{ level: string; text: string; at: string }> }> {
+    return this.resolveProvider().consoleMessages(session, options)
+  }
+
+  /** Network requests the host captured for the session's active tab. */
+  async networkRequests(session: BrowserSessionId, options: { limit?: number; failedOnly?: boolean; urlContains?: string; clear?: boolean } = {}): Promise<{ requests: Array<{ method: string; url: string; status?: number; mime?: string; kind?: string; failed?: string; ms?: number; at: string }> }> {
+    return this.resolveProvider().networkRequests(session, options)
+  }
+
+  /** Set how the host answers the next JS dialog, and report the state. */
+  async setDialogPolicy(session: BrowserSessionId, policy: { behavior: 'accept' | 'dismiss'; promptText?: string }): Promise<{ dialog: unknown; policy: { behavior: 'accept' | 'dismiss'; promptText?: string } }> {
+    return this.resolveProvider().setDialogPolicy(session, policy)
+  }
+
+  /** Drain any pending dialog, then report the last one and the current policy. */
+  async inspectDialog(session: BrowserSessionId): Promise<{ dialog: unknown; policy: { behavior: 'accept' | 'dismiss'; promptText?: string } }> {
+    return this.resolveProvider().inspectDialog(session)
+  }
+
+  /** The last JS dialog the host reported, plus the current policy. */
+  dialogState(session: BrowserSessionId): { dialog: unknown; policy: { behavior: 'accept' | 'dismiss'; promptText?: string } } {
+    return this.resolveProvider().dialogState(session)
+  }
+
+  /** Click one element referenced by an exact snapshot. */
+  async clickRef(session: BrowserSessionId, request: BrowserRefRequest, signal?: AbortSignal): Promise<void> {
+    return this.resolveProvider().clickRef(session, request, signal)
+  }
+
+  /** Scroll one element referenced by an exact snapshot into view. */
+  async scrollIntoView(session: BrowserSessionId, request: BrowserScrollIntoViewRequest, signal?: AbortSignal): Promise<BrowserScrollResult> {
+    return this.resolveProvider().scrollIntoView(session, request, 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: BrowserPointerTarget, signal?: AbortSignal): Promise<BrowserPointerResult> {
+    return this.resolveProvider().click(session, request, signal)
+  }
+
+  /** Double-click at viewport coordinates through the selected provider. */
+  async doubleClick(session: BrowserSessionId, request: BrowserPointerTarget, signal?: AbortSignal): Promise<BrowserPointerResult> {
+    return this.resolveProvider().doubleClick(session, request, signal)
+  }
+
+  /** Press on one target, move to another, release, through the selected provider. */
+  async drag(session: BrowserSessionId, request: BrowserDragRequest, signal?: AbortSignal): Promise<BrowserDragResult> {
+    return this.resolveProvider().drag(session, request, signal)
+  }
+
+  async hover(session: BrowserSessionId, request: BrowserPointerTarget, signal?: AbortSignal): Promise<BrowserPointerResult> {
+    return this.resolveProvider().hover(session, request, signal)
+  }
+
+  /** Scroll the active page through the selected provider. */
+  async scroll(session: BrowserSessionId, request: BrowserScrollRequest, signal?: AbortSignal): Promise<BrowserScrollResult> {
+    return this.resolveProvider().scroll(session, request, signal)
+  }
+
+  /** Attach a local file to a file input through the selected provider. */
+  async uploadFile(session: BrowserSessionId, request: BrowserUploadFileRequest, signal?: AbortSignal): Promise<BrowserUploadFileResult> {
+    return this.resolveProvider().uploadFile(session, request, signal)
+  }
+
+  /** Wait for an element through the selected provider (bounded polling). */
+  async waitForElement(session: BrowserSessionId, request: BrowserWaitForRequest, signal?: AbortSignal): Promise<BrowserWaitForResult> {
+    return this.resolveProvider().waitForElement(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)
+  }
+
+  /** Press a key into the session's page through the selected provider. */
+  async pressKey(session: BrowserSessionId, request: BrowserPressKeyRequest, signal?: AbortSignal): Promise<void> {
+    return this.resolveProvider().pressKey(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)
+  }
+
+  /** Import cookies from a JSON export on disk through the provider. */
+  async importAuth(session: BrowserSessionId, path: string): Promise<{ restored: number; failed: number }> {
+    return this.resolveProvider().importAuth(session, path)
+  }
+
+  /** Start a background scrape batch through the provider. */
+  async startScrape(session: BrowserSessionId, request: BrowserScrapeRequest): Promise<BrowserScrapeStatus> {
+    return this.resolveProvider().startScrape(session, request)
+  }
+
+  /** Progress of one scrape batch through the provider. */
+  async scrapeStatus(id: string): Promise<BrowserScrapeStatus> {
+    return this.resolveProvider().scrapeStatus(id)
+  }
+
+  /** Ask a running scrape batch to stop through the provider. */
+  async stopScrape(id: string): Promise<BrowserScrapeStatus> {
+    return this.resolveProvider().stopScrape(id)
+  }
+
+  /** Every scrape batch the provider knows about. */
+  async listScrapes(): Promise<readonly BrowserScrapeStatus[]> {
+    return this.resolveProvider().listScrapes()
+  }
+
+  /** Remove cookies for one site scope through the provider. */
+  async clearAuth(session: BrowserSessionId, request: BrowserClearAuthRequest): Promise<BrowserClearAuthResult> {
+    return this.resolveProvider().clearAuth(session, request)
+  }
+
+  /** Set the session's browser task label through the selected provider. */
+  async setSpace(session: BrowserSessionId, label: string): Promise<void> {
+    return this.resolveProvider().setSpace(session, label)
+  }
+
+  /** List browser tasks (legacy spaces) with labels through the selected provider. */
+  async listSpaces(): Promise<readonly BrowserSpaceInfo[]> {
+    return this.resolveProvider().listSpaces()
+  }
+
+  /** List browser tasks with live collaboration status through the provider. */
+  async listTasks(): Promise<readonly BrowserTaskInfo[]> {
+    return this.resolveProvider().listTasks()
+  }
+
+  /** Read one session's task collaboration state through the provider. */
+  async getTask(session: BrowserSessionId): Promise<BrowserTaskInfo> {
+    return this.resolveProvider().getTask(session)
+  }
+
+  /** Update one session's visible task state through the provider. */
+  async updateTask(session: BrowserSessionId, update: BrowserTaskUpdate): Promise<BrowserTaskInfo> {
+    return this.resolveProvider().updateTask(session, update)
+  }
+
+  /** Mark one session as waiting for the user or returned to Agent control. */
+  async setHandoff(session: BrowserSessionId, state: BrowserHandoffState): Promise<BrowserTaskInfo> {
+    return this.resolveProvider().setHandoff(session, state)
+  }
+
+  /** Close the session through the selected provider. Idempotent; a missing
+   *  provider is treated as already-closed so teardown paths stay no-ops. */
+  async close(session: BrowserSessionId): Promise<void> {
+    try {
+      await this.resolveProvider().close(session)
+    } catch (error) {
+      const code = error instanceof BrowserError ? (error as { code?: string }).code : undefined
+      if (code === 'BROWSER_PROVIDER_UNAVAILABLE'
+        || code === 'BROWSER_PROVIDER_CONFIGURED_MISSING'
+        || code === 'BROWSER_PROVIDER_CONFIGURED_UNAVAILABLE'
+        || code === 'BROWSER_PROVIDER_AMBIGUOUS') {
+        return // provider gone; nothing to close
+      }
+      throw error
+    }
+  }
+}
+
+export default BrowserRuntime
+