dsh-builtin-browser 0.1.0

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

@@ -0,0 +1,30 @@
+/**
+ * Electron browser provider plugin entry: registers the Electron-backed
+ * `BrowserProvider` with `ctx.browser`. The provider needs a view host (real
+ * Electron `WebContentsView` objects) that only a desktop shell can supply,
+ * so the view host arrives through plugin config (the bundle patch reads it
+ * from `ctx.get('electronViewHost')`).
+ * @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 type { ElectronBrowserViewHost } from './provider.ts';
+export { ELECTRON_BROWSER_PROVIDER_ID, ElectronBrowserProvider, } from './provider.ts';
+export type { ElectronBrowserViewHost, ElectronViewHandle } from './provider.ts';
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "browser-electron";
+/** The browser seam this provider registers into. */
+export declare const inject: string[];
+/** Plugin config: the view host supplied by the desktop shell. */
+export interface Config {
+    /** The Electron view host supplied by the desktop shell. */
+    readonly viewHost: ElectronBrowserViewHost;
+    /** Allow navigation only to HTTP(S) URLs. Default true. */
+    readonly httpOnly?: boolean;
+}
+export declare const Config: z<Config>;
+/** Register the Electron browser provider with `ctx.browser`. */
+export declare function apply(ctx: Context & {
+    browser: BrowserRuntime;
+}, config: Config): void;

package/lib/browser-electron/entry.js

@@ -0,0 +1,23 @@
+/**
+ * Electron browser provider plugin entry: registers the Electron-backed
+ * `BrowserProvider` with `ctx.browser`. The provider needs a view host (real
+ * Electron `WebContentsView` objects) that only a desktop shell can supply,
+ * so the view host arrives through plugin config (the bundle patch reads it
+ * from `ctx.get('electronViewHost')`).
+ * @module dsh-browser/browser-electron
+ */
+import z from '@deepseek-ai/schemastery';
+import { ElectronBrowserProvider } from "./provider.js";
+export { ELECTRON_BROWSER_PROVIDER_ID, ElectronBrowserProvider, } from "./provider.js";
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'browser-electron';
+/** The browser seam this provider registers into. */
+export const inject = ['browser'];
+export const Config = z.object({
+    viewHost: z.any(),
+    httpOnly: z.boolean().default(true),
+});
+/** Register the Electron browser provider with `ctx.browser`. */
+export function apply(ctx, config) {
+    ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(config.viewHost, { httpOnly: config.httpOnly }));
+}

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

@@ -0,0 +1,169 @@
+/**
+ * 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
+ * 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';
+/** Stable provider id registered with `ctx.browser`. */
+export declare const ELECTRON_BROWSER_PROVIDER_ID = "electron";
+/**
+ * The minimal Electron surface this provider needs. Implemented by the
+ * desktop shell with a real `WebContentsView`; a fake implements it in tests.
+ */
+export interface ElectronBrowserViewHost {
+    /**
+     * Create a new browser view and return a handle to its webContents-like
+     * surface. The host owns windowing (adding the view to the window, sizing,
+     * removal); the provider owns CDP-driven behavior.
+     */
+    createView(): ElectronViewHandle;
+    /**
+     * Destroy a view created by this host. Called on session close; idempotent
+     * for an already-destroyed view.
+     * @param handle - the handle returned by {@link createView}.
+     */
+    destroyView(handle: ElectronViewHandle): void;
+    /**
+     * Show one view as the session's visible surface. The host keeps exactly
+     * one visible; switching tabs reorders visibility without losing state.
+     * Optional: a host without visible-tab switching treats every view as
+     * always present (acceptable for headless/probe hosts).
+     * @param handle - the handle to make visible.
+     */
+    showView?(handle: ElectronViewHandle): void;
+}
+/**
+ * A CDP-capable view handle. This is the subset of Electron's
+ * `WebContents`/`WebContentsView` the provider drives; the shell's real
+ * implementation adapts `webContents.debugger` to it.
+ */
+export interface ElectronViewHandle {
+    /** Unique id of the backing view, used for diagnostics. */
+    readonly id: string;
+    /**
+     * Send one CDP command and resolve with its result. Rejects when the
+     * debugger is not attached or the command fails.
+     * @param method - CDP method, e.g. `Page.navigate`.
+     * @param params - CDP command parameters.
+     * @returns the CDP `result` object.
+     */
+    sendCommand(method: string, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
+}
+/** Provider config: navigation admission defaults and snapshot caps. */
+export interface ElectronBrowserProviderConfig {
+    /** Allow navigation only to HTTP(S) URLs; reject anything else. Default true. */
+    readonly httpOnly?: boolean;
+    /** Maximum snapshot elements before truncation. Default 60. */
+    readonly snapshotMaxElements?: number;
+    /** Maximum content characters before truncation when no maxChars is given. Default 100_000. */
+    readonly contentMaxChars?: number;
+}
+/**
+ * CDP method/params for `Page.navigate`, as sent to {@link ElectronViewHandle.sendCommand}.
+ */
+export interface CdpNavigateParams {
+    readonly url: string;
+}
+/**
+ * CDP method/params for `Input.dispatchMouseEvent` (a click press+release pair).
+ */
+export interface CdpMouseParams {
+    readonly type: 'mousePressed' | 'mouseReleased';
+    readonly x: number;
+    readonly y: number;
+    readonly button: 'left';
+    readonly clickCount: number;
+}
+/** CDP method/params for `Input.insertText`. */
+export interface CdpInsertTextParams {
+    readonly text: string;
+}
+/** CDP method/params for `Runtime.evaluate`. */
+export interface CdpEvaluateParams {
+    readonly expression: string;
+    readonly returnByValue: boolean;
+    readonly awaitPromise?: boolean;
+}
+/** CDP method for a full-page screenshot capture. */
+export declare const CDP_PAGE_CAPTURE_SCREENSHOT = "Page.captureScreenshot";
+/** CDP method for runtime evaluation (the execute path). */
+export declare const CDP_RUNTIME_EVALUATE = "Runtime.evaluate";
+/** CDP method for navigation. */
+export declare const CDP_PAGE_NAVIGATE = "Page.navigate";
+/**
+ * Browser provider over Electron views. Sessions hold an ordered list of
+ * tabs; each tab is one view created by the host. The active tab receives
+ * every operation; switching tabs calls the host's optional `showView` and
+ * never loses state. Navigation is admitted only for HTTP(S) targets unless
+ * {@link ElectronBrowserProviderConfig.httpOnly} is disabled.
+ */
+export declare class ElectronBrowserProvider implements BrowserProvider {
+    private readonly host;
+    readonly id = "electron";
+    private readonly sessions;
+    private readonly httpOnly;
+    private readonly snapshotMaxElements;
+    private readonly contentMaxChars;
+    constructor(host: ElectronBrowserViewHost, config?: ElectronBrowserProviderConfig);
+    /** 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(): Promise<BrowserSessionId>;
+    /** Open a URL in the active tab (default) or a new tab. */
+    openUrl(session: BrowserSessionId, request: BrowserOpenRequest, signal?: AbortSignal): Promise<void>;
+    /** List the session's tabs with their titles. */
+    listTabs(session: BrowserSessionId): Promise<readonly BrowserTab[]>;
+    /** Switch to a tab by id, making its view visible. */
+    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 to one blank tab. */
+    reset(session: BrowserSessionId): Promise<void>;
+    /** Navigate the active tab's view to a URL, honoring HTTP(S)-only admission. */
+    navigate(session: BrowserSessionId, request: {
+        readonly url: string;
+    }, 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 (CDP mousePressed + mouseReleased). */
+    click(session: BrowserSessionId, request: {
+        readonly x: number;
+        readonly y: number;
+    }, signal?: AbortSignal): Promise<void>;
+    /** Type into the focused element. */
+    type(session: BrowserSessionId, request: {
+        readonly text: string;
+    }, signal?: AbortSignal): Promise<void>;
+    /** Capture the current page, optionally full-page. PNG only (CDP JPEG hangs on Electron 43). */
+    screenshot(session: BrowserSessionId, request?: {
+        readonly fullPage?: boolean;
+    }, signal?: AbortSignal): Promise<{
+        readonly dataUrl: string;
+    }>;
+    /** Close the session and destroy all its views. Idempotent. */
+    close(session: BrowserSessionId): Promise<void>;
+    /** Look up a session or throw the unknown-session error. */
+    private session;
+    /** The active tab of a session. */
+    private activeTab;
+    /** Append a fresh tab and make it active. */
+    private newTab;
+    /** Ask the host to show the active tab's view. */
+    private showActive;
+    /** Read the current URL of a view through CDP. */
+    private currentUrl;
+}

package/lib/browser-electron/provider.js

@@ -0,0 +1,373 @@
+/**
+ * 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
+ * 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 { randomUUID } from 'node:crypto';
+import { BrowserError } from "../browser/types.js";
+/** Stable provider id registered with `ctx.browser`. */
+export const ELECTRON_BROWSER_PROVIDER_ID = 'electron';
+/** CDP method for a full-page screenshot capture. */
+export const CDP_PAGE_CAPTURE_SCREENSHOT = 'Page.captureScreenshot';
+/** CDP method for runtime evaluation (the execute path). */
+export const CDP_RUNTIME_EVALUATE = 'Runtime.evaluate';
+/** CDP method for navigation. */
+export const CDP_PAGE_NAVIGATE = 'Page.navigate';
+/** Cap on content returned by a snapshot fetch to keep the wire bounded. */
+const SNAPSHOT_LABEL_MAX = 120;
+/**
+ * Browser provider over Electron views. Sessions hold an ordered list of
+ * tabs; each tab is one view created by the host. The active tab receives
+ * every operation; switching tabs calls the host's optional `showView` and
+ * never loses state. Navigation is admitted only for HTTP(S) targets unless
+ * {@link ElectronBrowserProviderConfig.httpOnly} is disabled.
+ */
+export class ElectronBrowserProvider {
+    host;
+    id = ELECTRON_BROWSER_PROVIDER_ID;
+    sessions = new Map();
+    httpOnly;
+    snapshotMaxElements;
+    contentMaxChars;
+    constructor(host, config = {}) {
+        this.host = host;
+        this.httpOnly = config.httpOnly ?? true;
+        this.snapshotMaxElements = config.snapshotMaxElements ?? 60;
+        this.contentMaxChars = config.contentMaxChars ?? 100_000;
+    }
+    /** Usable whenever the host can create views (always in the desktop shell). */
+    available() {
+        return true;
+    }
+    /**
+     * 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() {
+        const [existing] = this.sessions.keys();
+        if (existing !== undefined)
+            return Promise.resolve(existing);
+        const handle = this.host.createView();
+        const id = `browser:${randomUUID()}`;
+        this.sessions.set(id, { id, tabs: [{ id: `tab:${randomUUID()}`, handle }], activeIndex: 0 });
+        return Promise.resolve(id);
+    }
+    /** Open a URL in the active tab (default) or a new tab. */
+    async openUrl(session, request, signal) {
+        const s = this.session(session);
+        if (request.newTab === true) {
+            this.newTab(s);
+        }
+        await this.navigate(session, { url: request.url }, signal);
+    }
+    /** List the session's tabs with their titles. */
+    async listTabs(session) {
+        const s = this.session(session);
+        const result = [];
+        for (let i = 0; i < s.tabs.length; i++) {
+            const tab = s.tabs[i];
+            if (tab === undefined)
+                continue; // defensive: array can shift under concurrency
+            result.push({
+                id: tab.id,
+                url: await this.currentUrl(tab.handle).catch(() => ''),
+                active: i === s.activeIndex,
+            });
+        }
+        return result;
+    }
+    /** Switch to a tab by id, making its view visible. */
+    switchTab(session, tabId) {
+        const s = this.session(session);
+        const index = s.tabs.findIndex(tab => tab.id === tabId);
+        if (index < 0) {
+            throw new BrowserError(`browser: tab "${tabId}" is not open in this session`, 'BROWSER_TAB_UNKNOWN');
+        }
+        s.activeIndex = index;
+        this.showActive(s);
+        return Promise.resolve();
+    }
+    /** Close one tab; closing the active tab activates the next. */
+    closeTab(session, tabId) {
+        const s = this.session(session);
+        const index = s.tabs.findIndex(tab => tab.id === tabId);
+        if (index < 0)
+            return Promise.resolve(); // idempotent
+        const removed = s.tabs[index];
+        if (removed !== undefined) {
+            s.tabs.splice(index, 1);
+            this.host.destroyView(removed.handle);
+        }
+        if (s.tabs.length === 0) {
+            // Session keeps one blank tab so it stays usable.
+            this.newTab(s);
+        }
+        else if (index < s.activeIndex) {
+            // Closing a tab before the active one shifts the array left; keep the
+            // same tab active by decrementing the index.
+            s.activeIndex -= 1;
+        }
+        else if (s.activeIndex >= s.tabs.length) {
+            // The active tab itself was closed; activate the last remaining one.
+            s.activeIndex = s.tabs.length - 1;
+        }
+        this.showActive(s);
+        return Promise.resolve();
+    }
+    /** Close every tab and reset to one blank tab. */
+    reset(session) {
+        const s = this.session(session);
+        for (const tab of s.tabs)
+            this.host.destroyView(tab.handle);
+        s.tabs.length = 0;
+        this.newTab(s);
+        s.activeIndex = 0;
+        this.showActive(s);
+        return Promise.resolve();
+    }
+    /** Navigate the active tab's view to a URL, honoring HTTP(S)-only admission. */
+    async navigate(session, request, signal) {
+        const { handle } = this.activeTab(this.session(session));
+        const url = request.url;
+        if (this.httpOnly) {
+            let parsed;
+            try {
+                parsed = new URL(url);
+            }
+            catch {
+                throw new BrowserError(`browser: refusing navigation to unparseable URL "${url}"`, 'BROWSER_NAVIGATION_BLOCKED');
+            }
+            if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+                throw new BrowserError(`browser: refusing navigation to non-HTTP(S) URL "${url}"`, 'BROWSER_NAVIGATION_BLOCKED');
+            }
+        }
+        signal?.throwIfAborted();
+        await handle.sendCommand(CDP_PAGE_NAVIGATE, { url });
+    }
+    /** Execute JS in the active tab's page context. */
+    async execute(session, request, signal) {
+        const { handle } = this.activeTab(this.session(session));
+        signal?.throwIfAborted();
+        try {
+            // Wrap the script in a Function so `return` statements are legal and
+            // request.args arrive as `arguments[0..n]`. A bare script handed to CDP
+            // Runtime.evaluate is an expression context — a leading `return` would
+            // be a syntax error, and an object-literal script (`{...}`) would parse
+            // as a block. So: if the script already starts with `return`, use it as
+            // the body verbatim; otherwise wrap it as `return (expr)` so both
+            // expression and object-literal forms evaluate to their value. Args are
+            // embedded as a JSON array literal; unserializable members become null.
+            const body = /^\s*return\b/.test(request.script)
+                ? request.script
+                : `return (${request.script})`;
+            const hasArgs = request.args !== undefined && request.args.length > 0;
+            const expression = hasArgs
+                ? `(function(){ const __dshArgs = ${JSON.stringify(request.args)}; return Function(${JSON.stringify(body)}).apply(null, __dshArgs) })()`
+                : `(function(){ return Function(${JSON.stringify(body)})() })()`;
+            const result = await handle.sendCommand(CDP_RUNTIME_EVALUATE, {
+                expression,
+                returnByValue: true,
+                awaitPromise: true,
+            });
+            if (result.exceptionDetails !== undefined) {
+                const detail = result.exceptionDetails;
+                return { ok: false, exception: detail.exception?.description ?? detail.text ?? 'unknown exception' };
+            }
+            return { ok: true, value: result.result?.value ?? null };
+        }
+        catch (error) {
+            throw new BrowserError(`browser: execute failed: ${String(error)}`, 'BROWSER_EXECUTE_FAILED', { cause: error });
+        }
+    }
+    /** Produce an AI-friendly snapshot of the active tab. */
+    async snapshot(session, signal) {
+        const s = this.session(session);
+        const tab = this.activeTab(s);
+        signal?.throwIfAborted();
+        const script = `(() => {
+      const cap = ${String(this.snapshotMaxElements)}
+      const url = location.href
+      const title = document.title || undefined
+      const els = [...document.querySelectorAll('input, textarea, select, button, a[href], [role="button"], [role="searchbox"], [contenteditable="true"]')]
+      const out = []
+      for (const el of els) {
+        if (out.length >= cap) break
+        const r = el.getBoundingClientRect()
+        const cs = getComputedStyle(el)
+        if (r.width < 4 || r.height < 4 || cs.visibility === 'hidden' || cs.display === 'none') continue
+        const kind = el.tagName === 'INPUT' ? (el.type === 'checkbox' ? 'checkbox' : (el.type === 'submit' || el.type === 'button' ? 'button' : 'input'))
+          : el.tagName === 'TEXTAREA' ? 'textarea'
+          : el.tagName === 'SELECT' ? 'select'
+          : el.tagName === 'BUTTON' ? 'button'
+          : el.tagName === 'A' ? 'link' : 'other'
+        const label = (el.getAttribute('aria-label') || el.placeholder || el.textContent || el.value || el.name || el.id || '').toString().replace(/\\s+/g, ' ').trim().slice(0, ${String(SNAPSHOT_LABEL_MAX)})
+        if (!label && kind !== 'link') continue
+        out.push({
+          ref: out.length + 1,
+          kind,
+          label,
+          selector: el.id ? '#' + el.id : (el.name ? '[name=' + JSON.stringify(el.name) + ']' : ''),
+          x: Math.round(r.x + r.width / 2),
+          y: Math.round(r.y + r.height / 2),
+        })
+      }
+      return { url, title, elements: out, truncated: out.length >= cap }
+    })()`;
+        const result = await handleSendEvaluate(tab.handle, script);
+        if (!result.ok)
+            throw new BrowserError(`browser: snapshot evaluation failed: ${result.exception}`, 'BROWSER_SNAPSHOT_FAILED');
+        const value = result.value;
+        return value;
+    }
+    /** Fetch page content in a requested format. */
+    async content(session, request, signal) {
+        const tab = this.activeTab(this.session(session));
+        signal?.throwIfAborted();
+        const maxChars = request.maxChars ?? this.contentMaxChars;
+        const selector = request.selector ?? '';
+        const format = request.format;
+        const script = `(() => {
+      const root = ${selector === '' ? 'document.body' : `document.querySelector(${JSON.stringify(selector)})`}
+      if (!root) return { ok: false, reason: 'selector not found' }
+      const fmt = ${JSON.stringify(format)}
+      let content = ''
+      if (fmt === 'txt') content = root.innerText || ''
+      else if (fmt === 'html') content = root.outerHTML || ''
+      else if (fmt === 'json') content = JSON.stringify(root)
+      else {
+        // markdown: headings, paragraphs, links, lists (best-effort)
+        const parts = []
+        const walk = (node) => {
+          if (node.nodeType === Node.TEXT_NODE) { const t = (node.textContent || '').trim(); if (t) parts.push(t); return }
+          if (node.nodeType !== Node.ELEMENT_NODE) return
+          const tag = node.tagName.toLowerCase()
+          if (tag === 'script' || tag === 'style' || tag === 'noscript') return
+          if (tag === 'h1' || tag === 'h2' || tag === 'h3' || tag === 'h4') parts.push('\\n' + '#'.repeat(Number(tag[1])) + ' ' + (node.textContent || '').trim() + '\\n')
+          else if (tag === 'a') { const t = (node.textContent || '').trim(); if (t) parts.push('[' + t + '](' + (node.href || '') + ')') }
+          else if (tag === 'li') parts.push('  - ' + (node.textContent || '').trim())
+          else if (tag === 'p' || tag === 'div' || tag === 'section' || tag === 'article') { const t = (node.textContent || '').trim(); if (t) parts.push(t + '\\n') }
+          else { for (const child of node.childNodes) walk(child) }
+        }
+        if (root.nodeType === Node.TEXT_NODE) walk(root)
+        else for (const child of root.childNodes) walk(child)
+        // Join without a separator: each part already carries its own trailing
+        // newline, so a space join would smear headings/links into run-on text.
+        content = parts.join('')
+      }
+      const truncated = content.length > ${String(maxChars)}
+      return { ok: true, content: content.slice(0, ${String(maxChars)}), truncated }
+    })()`;
+        // Honor a per-call timeout: content evaluation can hang on a heavy page,
+        // so a caller-supplied budget bounds it. AbortSignal.any merges the
+        // caller's signal with a timeout.
+        const timeoutMs = request.timeoutMs ?? 30_000;
+        const timeoutSignal = AbortSignal.timeout(timeoutMs);
+        const result = signal !== undefined
+            ? await handleSendEvaluate(tab.handle, script, AbortSignal.any([signal, timeoutSignal]))
+            : await handleSendEvaluate(tab.handle, script, timeoutSignal);
+        if (!result.ok)
+            throw new BrowserError(`browser: content evaluation failed: ${result.exception}`, 'BROWSER_CONTENT_FAILED');
+        const value = result.value;
+        if (!value.ok)
+            throw new BrowserError(`browser: content fetch failed: ${value.reason ?? 'unknown'}`, 'BROWSER_CONTENT_FAILED');
+        return { content: value.content ?? '', truncated: value.truncated ?? false };
+    }
+    /** Click at viewport coordinates (CDP mousePressed + mouseReleased). */
+    async click(session, request, signal) {
+        const { handle } = this.activeTab(this.session(session));
+        signal?.throwIfAborted();
+        await handle.sendCommand('Input.dispatchMouseEvent', { type: 'mousePressed', x: request.x, y: request.y, button: 'left', clickCount: 1 });
+        await handle.sendCommand('Input.dispatchMouseEvent', { type: 'mouseReleased', x: request.x, y: request.y, button: 'left', clickCount: 1 });
+    }
+    /** Type into the focused element. */
+    async type(session, request, signal) {
+        const { handle } = this.activeTab(this.session(session));
+        signal?.throwIfAborted();
+        await handle.sendCommand('Input.insertText', { text: request.text });
+    }
+    /** Capture the current page, optionally full-page. PNG only (CDP JPEG hangs on Electron 43). */
+    async screenshot(session, request, signal) {
+        const { handle } = this.activeTab(this.session(session));
+        signal?.throwIfAborted();
+        const params = {};
+        if (request?.fullPage === true) {
+            // `captureBeyondViewport` captures the full scrollable content; without
+            // a clip this yields the full-page image (CDP default is the viewport).
+            params.captureBeyondViewport = true;
+        }
+        const result = await handle.sendCommand(CDP_PAGE_CAPTURE_SCREENSHOT, params);
+        const data = result.data;
+        if (typeof data !== 'string') {
+            throw new BrowserError('browser: screenshot returned no image data', 'BROWSER_SCREENSHOT_FAILED');
+        }
+        return { dataUrl: `data:image/png;base64,${data}` };
+    }
+    /** Close the session and destroy all its views. Idempotent. */
+    close(session) {
+        const existing = this.sessions.get(session);
+        if (existing !== undefined) {
+            this.sessions.delete(session);
+            for (const tab of existing.tabs)
+                this.host.destroyView(tab.handle);
+        }
+        return Promise.resolve();
+    }
+    /** Look up a session or throw the unknown-session error. */
+    session(session) {
+        const existing = this.sessions.get(session);
+        if (existing === undefined) {
+            throw new BrowserError(`browser: session "${session}" is not open`, 'BROWSER_SESSION_UNKNOWN');
+        }
+        return existing;
+    }
+    /** The active tab of a session. */
+    activeTab(s) {
+        const tab = s.tabs[s.activeIndex];
+        if (tab === undefined)
+            throw new BrowserError('browser: session has no active tab', 'BROWSER_TAB_UNKNOWN');
+        return tab;
+    }
+    /** Append a fresh tab and make it active. */
+    newTab(s) {
+        const handle = this.host.createView();
+        s.tabs.push({ id: `tab:${randomUUID()}`, handle });
+        s.activeIndex = s.tabs.length - 1;
+        this.showActive(s);
+    }
+    /** Ask the host to show the active tab's view. */
+    showActive(s) {
+        this.host.showView?.(this.activeTab(s).handle);
+    }
+    /** Read the current URL of a view through CDP. */
+    async currentUrl(handle) {
+        const result = await handleSendEvaluate(handle, 'location.href');
+        return result.ok && typeof result.value === 'string' ? result.value : '';
+    }
+}
+/**
+ * Run a `Runtime.evaluate` through a view handle and normalize the result.
+ * Shared by execute, snapshot, content, and internal URL reads.
+ * @param handle - the view handle to evaluate in.
+ * @param expression - the JS expression.
+ * @param signal - optional abort signal; a fired signal rejects the call.
+ */
+async function handleSendEvaluate(handle, expression, signal) {
+    signal?.throwIfAborted();
+    const result = await handle.sendCommand(CDP_RUNTIME_EVALUATE, {
+        expression,
+        returnByValue: true,
+        awaitPromise: true,
+    });
+    if (result.exceptionDetails !== undefined) {
+        const detail = result.exceptionDetails;
+        return { ok: false, exception: detail.exception?.description ?? detail.text ?? 'unknown exception' };
+    }
+    return { ok: true, value: result.result?.value ?? null };
+}

package/lib/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * dsh-browser plugin entry: aggregates the shared-browser capability pieces.
+ * The cordis.patch.yml rows reference subpath exports:
+ *   - `dsh-browser/browser`            -> the ctx.browser seam (Service Definition)
+ *   - `dsh-browser/browser-electron`   -> the Electron CDP provider
+ *   - `dsh-browser/tool-browser`       -> the model-facing browser_* tools
+ * This root entry only re-exports for programmatic use; the loader rows are
+ * the composition surface.
+ * @module dsh-browser
+ */
+export { BrowserError } from './browser/types.ts';
+export type { BrowserClickRequest, BrowserContentFormat, BrowserContentRequest, BrowserContentResult, BrowserExecuteRequest, BrowserExecuteResult, BrowserNavigateRequest, BrowserOpenRequest, BrowserProvider, BrowserScreenshotRequest, BrowserScreenshotResult, BrowserSessionId, BrowserSnapshotElement, BrowserSnapshotResult, BrowserTab, BrowserTypeRequest, } from './browser/types.ts';
+export { BrowserRuntime } from './browser/runtime.ts';
+export { ElectronBrowserProvider } from './browser-electron/provider.ts';
+export type { ElectronBrowserViewHost, ElectronViewHandle } from './browser-electron/provider.ts';

package/lib/index.js

@@ -0,0 +1,13 @@
+/**
+ * dsh-browser plugin entry: aggregates the shared-browser capability pieces.
+ * The cordis.patch.yml rows reference subpath exports:
+ *   - `dsh-browser/browser`            -> the ctx.browser seam (Service Definition)
+ *   - `dsh-browser/browser-electron`   -> the Electron CDP provider
+ *   - `dsh-browser/tool-browser`       -> the model-facing browser_* tools
+ * This root entry only re-exports for programmatic use; the loader rows are
+ * the composition surface.
+ * @module dsh-browser
+ */
+export { BrowserError } from "./browser/types.js";
+export { BrowserRuntime } from "./browser/runtime.js";
+export { ElectronBrowserProvider } from "./browser-electron/provider.js";

package/lib/tool-browser/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Model-facing browser tools over `ctx.browser`: `browser_open`,
+ * `browser_snapshot`, `browser_execute`, `browser_content`,
+ * `browser_screenshot`, and tab management (`browser_list_tabs`,
+ * `browser_switch_tab`, `browser_close_tab`, `browser_reset`).
+ *
+ * The tool layer owns only the model-facing schema, argument validation, and
+ * result formatting 鈥?never provider selection or page driving, which belong
+ * to the seam. Session lifecycle is owned here at the plugin level: the
+ * first `browser_open` (or any tool when no session exists) opens a session;
+ * later tools reuse it. Per-agent isolation is a follow-up.
+ * @module dsh-browser/tool-browser
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { BrowserSessionId } from '../browser/types.ts';
+/** Plugin name used by loader diagnostics. */
+export declare const name = "tool-browser";
+/** The tool registry, browser seam, and system-prompt registry this tool layer consumes. */
+export declare const inject: string[];
+/** Plugin config: tool timeouts and session defaults. */
+export interface Config {
+    /** Cooperative tool-call budget in ms. Default 60000. */
+    readonly timeoutMs?: number;
+    /** Whether to offer tab-management tools. Default true. */
+    readonly tabTools?: boolean;
+}
+/** Register all browser tools with `ctx.tools`. */
+export declare function apply(ctx: Context, config?: Config): void;
+/** Test hook: clear the plugin-level session (used by tests and on reset). */
+export declare const internals: {
+    readonly session: BrowserSessionId | undefined;
+    clearSession(): void;
+};