dsh-builtin-browser 0.1.1 → 0.1.3

package/cordis.patch.yml

@@ -1,19 +1,17 @@
 # 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.
+# profile composition. The browser seam (ctx.browser) is always mounted. The
+# Electron provider and browser_* tools are ALWAYS registered: when the host
+# provides `electronViewHost` (the desktop shell) that embedded view is used,
+# and otherwise the plugin self-hosts its own Electron window, so installing
+# the plugin is enough for the browser to work anywhere.
 - 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-electron/entry.d.ts

@@ -1,9 +1,12 @@
 /**
  * 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')`).
+ * 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';
@@ -12,14 +15,15 @@ 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';
+export { RemoteElectronViewHost, defaultHostMainPath } from './remote-host.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. */
+/** Plugin config: an optional externally-supplied view host. */
 export interface Config {
-    /** The Electron view host supplied by the desktop shell. */
-    readonly viewHost: ElectronBrowserViewHost;
+    /** 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;
 }

package/lib/browser-electron/entry.js

@@ -1,23 +1,37 @@
 /**
  * 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')`).
+ * 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 z from '@deepseek-ai/schemastery';
 import { ElectronBrowserProvider } from "./provider.js";
+import { defaultHostMainPath, RemoteElectronViewHost } from "./remote-host.js";
 export { ELECTRON_BROWSER_PROVIDER_ID, ElectronBrowserProvider, } from "./provider.js";
+export { RemoteElectronViewHost, defaultHostMainPath } from "./remote-host.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({
+    // 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, config) {
-    ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(config.viewHost, { httpOnly: config.httpOnly }));
+    // External host (desktop shell) wins; otherwise self-host. The self-hosted
+    // child is disposed with the fiber, mirroring the shell's lifetime.
+    const host = 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 }));
 }

package/lib/browser-electron/host-main.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Self-hosted Electron browser host (child side): the Electron main process
+ * spawned by {@link RemoteElectronViewHost}. Owns one `BrowserWindow` plus
+ * `WebContentsView`s and their `webContents.debugger` (CDP), and answers
+ * line-delimited JSON-RPC on stdio.
+ *
+ * Protocol (one JSON object per line, both directions):
+ *   <- { id, op: 'ping' } | { id, op: 'createView', viewId } |
+ *      { id, op: 'destroyView', viewId } | { id, op: 'showView', viewId } |
+ *      { id, op: 'command', viewId, method, params }
+ *   -> { id, ok: true, result? } | { id, ok: false, err }
+ *
+ * The parent never parses stderr, so diagnostics may go there freely.
+ * @module dsh-browser/browser-electron/host-main
+ */
+export {};

package/lib/browser-electron/host-main.js

@@ -0,0 +1,151 @@
+/**
+ * Self-hosted Electron browser host (child side): the Electron main process
+ * spawned by {@link RemoteElectronViewHost}. Owns one `BrowserWindow` plus
+ * `WebContentsView`s and their `webContents.debugger` (CDP), and answers
+ * line-delimited JSON-RPC on stdio.
+ *
+ * Protocol (one JSON object per line, both directions):
+ *   <- { id, op: 'ping' } | { id, op: 'createView', viewId } |
+ *      { id, op: 'destroyView', viewId } | { id, op: 'showView', viewId } |
+ *      { id, op: 'command', viewId, method, params }
+ *   -> { id, ok: true, result? } | { id, ok: false, err }
+ *
+ * The parent never parses stderr, so diagnostics may go there freely.
+ * @module dsh-browser/browser-electron/host-main
+ */
+import { app, BrowserWindow, WebContentsView } from 'electron';
+import { createInterface } from 'node:readline';
+import { createConnection } from 'node:net';
+/** CDP protocol version attached to every view's debugger. */
+const CDP_VERSION = '1.3';
+/** Views by the id the parent assigned at createView time. */
+const views = new Map();
+/** The single browser window; created lazily on first createView. */
+let window;
+/** The RPC socket to the parent; set when the connection is established. */
+let rpcSocket;
+/** Reply to the parent over the RPC socket. */
+function reply(id, payload) {
+    if (rpcSocket === undefined) {
+        process.stderr.write(`[dsh-browser host] reply without socket (id=${id})\n`);
+        return;
+    }
+    rpcSocket.write(JSON.stringify({ id, ...payload }) + '\n');
+}
+/** Handle one command. */
+async function handle(op, msg) {
+    try {
+        switch (op) {
+            case 'ping':
+                reply(msg.id, { ok: true });
+                return;
+            case 'createView': {
+                const viewId = msg.viewId;
+                if (viewId === undefined)
+                    throw new Error('createView missing viewId');
+                if (window === undefined) {
+                    window = new BrowserWindow({ width: 1400, height: 900, show: true, title: 'dsh-browser' });
+                    window.on('closed', () => { window = undefined; });
+                }
+                const view = new WebContentsView();
+                view.setVisible(false);
+                window.contentView.addChildView(view);
+                const [width, height] = window.getContentSize();
+                view.setBounds({ x: 0, y: 0, width: width ?? 0, height: height ?? 0 });
+                view.setVisible(true);
+                view.webContents.debugger.attach(CDP_VERSION);
+                views.set(viewId, { webContentsView: view });
+                reply(msg.id, { ok: true });
+                return;
+            }
+            case 'destroyView': {
+                const viewId = msg.viewId;
+                if (viewId === undefined)
+                    throw new Error('destroyView missing viewId');
+                const entry = views.get(viewId);
+                if (entry !== undefined) {
+                    views.delete(viewId);
+                    try {
+                        entry.webContentsView.webContents.debugger.detach();
+                    }
+                    catch { /* already detached */ }
+                    entry.webContentsView.webContents.close();
+                    window?.contentView.removeChildView(entry.webContentsView);
+                }
+                reply(msg.id, { ok: true });
+                return;
+            }
+            case 'showView': {
+                const viewId = msg.viewId;
+                if (viewId === undefined)
+                    throw new Error('showView missing viewId');
+                const entry = views.get(viewId);
+                if (entry !== undefined)
+                    entry.webContentsView.setVisible(true);
+                reply(msg.id, { ok: true });
+                return;
+            }
+            case 'command': {
+                const viewId = msg.viewId;
+                if (viewId === undefined)
+                    throw new Error('command missing viewId');
+                const entry = views.get(viewId);
+                if (entry === undefined)
+                    throw new Error(`command: unknown view ${viewId}`);
+                const method = msg.method;
+                if (typeof method !== 'string')
+                    throw new Error('command missing method');
+                const result = await entry.webContentsView.webContents.debugger.sendCommand(method, msg.params ?? {});
+                reply(msg.id, { ok: true, result });
+                return;
+            }
+            default:
+                throw new Error(`unknown op ${op}`);
+        }
+    }
+    catch (error) {
+        reply(msg.id, { ok: false, err: String(error) });
+    }
+}
+/**
+ * Electron entry: connect back to the parent's RPC server (port from
+ * `--rpc-port`) and serve line-delimited JSON-RPC. `ELECTRON_RUN_AS_NODE` is
+ * cleared by the parent so `require('electron')` works; this file is loaded as
+ * the app entry so `app` is available immediately.
+ */
+void app.whenReady().then(() => {
+    const portArg = process.argv.indexOf('--rpc-port');
+    const port = portArg >= 0 ? Number(process.argv[portArg + 1]) : NaN;
+    if (!Number.isFinite(port)) {
+        process.stderr.write('[dsh-browser host] missing --rpc-port\n');
+        app.exit(1);
+        return;
+    }
+    const socket = createConnection({ host: '127.0.0.1', port });
+    rpcSocket = socket;
+    socket.setEncoding('utf8');
+    const rl = createInterface({ input: socket });
+    rl.on('line', line => {
+        const text = line.trim();
+        if (text === '')
+            return;
+        let msg;
+        try {
+            msg = JSON.parse(text);
+        }
+        catch {
+            return; // non-protocol noise
+        }
+        if (typeof msg.id !== 'number' || typeof msg.op !== 'string')
+            return;
+        void handle(msg.op, msg).catch(() => { });
+    });
+    socket.on('error', error => {
+        process.stderr.write(`[dsh-browser host] socket error: ${String(error)}\n`);
+    });
+    // Keep the process alive until the parent closes the socket or kills us.
+});
+// Diagnostics go to stderr, which the parent never parses as protocol.
+process.on('uncaughtException', error => {
+    process.stderr.write(`[dsh-browser host] uncaught: ${String(error)}\n`);
+});

package/lib/browser-electron/remote-host.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Self-hosted Electron browser host (parent side): an
+ * {@link ElectronBrowserViewHost} implementation that spawns the plugin's own
+ * Electron child process (host-main.js) and drives it over line-delimited
+ * JSON-RPC on stdio. This is what makes the plugin work on surfaces without a
+ * desktop shell's electronViewHost (plain dsh web): installing the plugin is
+ * enough — the browser window appears on first use.
+ *
+ * Protocol (one JSON object per line, both directions):
+ *   -> { id, op: 'createView' } | { id, op: 'destroyView', viewId } |
+ *      { id, op: 'showView', viewId } | { id, op: 'command', viewId, method, params }
+ *   <- { id, ok: true, result? } | { id, ok: false, err }
+ *
+ * The child is Electron's main process; host-main.js owns the BrowserWindow,
+ * WebContentsViews, and webContents.debugger (CDP).
+ * @module dsh-browser/browser-electron/remote-host
+ */
+import type { ElectronBrowserViewHost, ElectronViewHandle } from './provider.ts';
+/**
+ * Self-hosted view host: spawns the plugin's Electron child on first use and
+ * keeps it alive until dispose(). Fallback when no desktop shell provides
+ * ctx.electronViewHost.
+ */
+export declare class RemoteElectronViewHost implements ElectronBrowserViewHost {
+    private readonly hostMainPath;
+    private client;
+    private server;
+    private pendingSocket;
+    private readonly views;
+    private readyPromise;
+    constructor(hostMainPath: string);
+    /** Ensure the child is up and ready (lazy on first use). */
+    private ready;
+    private start;
+    createView(): ElectronViewHandle;
+    private ensureView;
+    showView(handle: ElectronViewHandle): void;
+    destroyView(handle: ElectronViewHandle): void;
+    /** Shut the child and the RPC server down. */
+    dispose(): void;
+}
+/** Default host-main path relative to this module's build output. */
+export declare function defaultHostMainPath(): string;

package/lib/browser-electron/remote-host.js

@@ -0,0 +1,380 @@
+/**
+ * Self-hosted Electron browser host (parent side): an
+ * {@link ElectronBrowserViewHost} implementation that spawns the plugin's own
+ * Electron child process (host-main.js) and drives it over line-delimited
+ * JSON-RPC on stdio. This is what makes the plugin work on surfaces without a
+ * desktop shell's electronViewHost (plain dsh web): installing the plugin is
+ * enough — the browser window appears on first use.
+ *
+ * Protocol (one JSON object per line, both directions):
+ *   -> { id, op: 'createView' } | { id, op: 'destroyView', viewId } |
+ *      { id, op: 'showView', viewId } | { id, op: 'command', viewId, method, params }
+ *   <- { id, ok: true, result? } | { id, ok: false, err }
+ *
+ * The child is Electron's main process; host-main.js owns the BrowserWindow,
+ * WebContentsViews, and webContents.debugger (CDP).
+ * @module dsh-browser/browser-electron/remote-host
+ */
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { createServer } from 'node:net';
+import { fileURLToPath } from 'node:url';
+/** How long to wait for the child to signal readiness before failing. */
+const READY_TIMEOUT_MS = 20_000;
+/**
+ * Locate the Electron binary, trying, in order:
+ *   1. require('electron') from this module (optional peer dependency),
+ *   2. require.resolve('electron') against DSH install anchors (global dsh
+ *      package, npm global root) — desktop-shell environments satisfy this,
+ *   3. a pnpm virtual store under common workspace layouts,
+ *   4. ELECTRON_PATH (explicit override).
+ * @returns the path to the Electron executable.
+ */
+function resolveElectronPath() {
+    const require = createRequire(import.meta.url);
+    // 1. Optional peer dependency.
+    try {
+        const resolved = require('electron');
+        if (typeof resolved === 'string' && resolved.length > 0)
+            return resolved;
+    }
+    catch {
+        // continue probing
+    }
+    // 2. DSH install anchors: the global dsh package and the npm global root
+    // both carry electron junctions under pnpm layouts.
+    const anchors = [];
+    const globalPrefix = process.env.npm_config_prefix ?? process.env.PREFIX;
+    if (globalPrefix !== undefined) {
+        anchors.push(join(globalPrefix, 'node_modules'));
+        anchors.push(join(globalPrefix, 'node_modules', '@deepseek-ai', 'dsh', 'node_modules'));
+    }
+    if (process.env.DSH_HOME !== undefined) {
+        anchors.push(join(process.env.DSH_HOME, 'profiles', 'node_modules'));
+    }
+    for (const anchor of anchors) {
+        try {
+            const resolved = require.resolve('electron', { paths: [anchor] });
+            if (typeof resolved === 'string' && resolved.length > 0) {
+                // electron's index.js is not the binary; find the dist executable
+                // next to the package root.
+                const exe = electronExeBeside(resolved);
+                if (exe !== undefined)
+                    return exe;
+            }
+        }
+        catch {
+            // continue probing
+        }
+    }
+    // 3. pnpm virtual store, walking up from several candidate roots: this
+    // module (its real path may differ from where the profile resolves it when
+    // installed via a junction/link), the process CWD, and the Node executable
+    // dir (DSH CLI typically runs from the workspace root).
+    const roots = new Set([
+        fileURLToPath(new URL('.', import.meta.url)),
+        process.cwd(),
+        dirname(process.execPath),
+    ]);
+    for (const root of roots) {
+        let dir = root;
+        for (let depth = 0; depth < 8; depth++) {
+            const store = join(dir, 'node_modules', '.pnpm');
+            if (existsSync(store)) {
+                const exe = findElectronExe(store);
+                if (exe !== undefined)
+                    return exe;
+            }
+            const parent = join(dir, '..');
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    // 4. Explicit override.
+    const override = process.env.ELECTRON_PATH;
+    if (typeof override === 'string' && override.length > 0 && existsSync(override))
+        return override;
+    throw new Error('dsh-builtin-browser: cannot locate the Electron binary. Install electron in the host profile ' +
+        '(e.g. `dsh plugin --profile web add electron`) or set ELECTRON_PATH to the electron executable.');
+}
+/** From an electron package entry file, find the dist executable beside it. */
+function electronExeBeside(entry) {
+    const candidates = [
+        join(dirname(entry), 'dist', 'electron.exe'),
+        join(dirname(entry), 'dist', 'electron'),
+        join(dirname(entry), '..', 'dist', 'electron.exe'),
+        join(dirname(entry), '..', 'dist', 'electron'),
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/** dirname without importing node:path's dirname separately. */
+function dirname(p) {
+    const i = p.lastIndexOf('/');
+    const j = p.lastIndexOf('\\');
+    const k = Math.max(i, j);
+    return k < 0 ? p : p.slice(0, k);
+}
+/** Search a pnpm virtual store for an Electron dist binary. */
+function findElectronExe(store) {
+    const entries = existsSync(store) ? readdirSync(store) : [];
+    for (const entry of entries) {
+        if (!entry.startsWith('electron@'))
+            continue;
+        const candidates = [
+            join(store, entry, 'node_modules', 'electron', 'dist', 'electron.exe'),
+            join(store, entry, 'node_modules', 'electron', 'dist', 'electron'),
+        ];
+        for (const candidate of candidates) {
+            if (existsSync(candidate))
+                return candidate;
+        }
+    }
+    return undefined;
+}
+/**
+ * Line-delimited JSON-RPC client over a local TCP socket. Electron's main
+ * process on Windows does not receive piped stdin, so the parent listens on a
+ * loopback port and passes it to the child via `--rpc-port`; the child
+ * connects back and speaks the same one-JSON-per-line protocol.
+ */
+class ElectronChildClient {
+    hostMainPath;
+    port;
+    child;
+    pending = new Map();
+    nextId = 1;
+    buffer = '';
+    socket;
+    connected = false;
+    outbox = [];
+    constructor(hostMainPath, port) {
+        this.hostMainPath = hostMainPath;
+        this.port = port;
+        const electron = resolveElectronPath();
+        // ELECTRON_RUN_AS_NODE (even an empty string) makes Electron run as plain
+        // Node, breaking require('electron'); NODE_OPTIONS can inject flags that
+        // break the child. Rebuild the env without either.
+        const env = { ...process.env };
+        delete env.ELECTRON_RUN_AS_NODE;
+        delete env.NODE_OPTIONS;
+        this.child = spawn(electron, [hostMainPath, '--rpc-port', String(port)], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: false,
+            env,
+        });
+        this.child.stderr.setEncoding('utf8');
+        this.child.stderr.on('data', chunk => {
+            // Diagnostics only; never parse stderr as protocol.
+            process.stderr.write(`[dsh-browser host] ${String(chunk)}`);
+        });
+        this.child.on('exit', (code, signal) => {
+            const err = new Error(`dsh-builtin-browser: browser host exited (code=${String(code)} signal=${String(signal)})`);
+            for (const pending of this.pending.values())
+                pending.reject(err);
+            this.pending.clear();
+        });
+    }
+    /** Accept the child's connection (called by the server). */
+    attach(socket) {
+        this.socket = socket;
+        this.connected = true;
+        socket.setEncoding('utf8');
+        socket.on('data', chunk => this.onData(chunk));
+        socket.on('close', () => {
+            this.connected = false;
+            const err = new Error('dsh-builtin-browser: browser host connection closed');
+            for (const pending of this.pending.values())
+                pending.reject(err);
+            this.pending.clear();
+        });
+        // Flush anything queued while disconnected.
+        if (this.outbox.length > 0) {
+            for (const line of this.outbox)
+                socket.write(line + '\n');
+            this.outbox = [];
+        }
+    }
+    onData(chunk) {
+        this.buffer += typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+        let nl;
+        while ((nl = this.buffer.indexOf('\n')) >= 0) {
+            const line = this.buffer.slice(0, nl).trim();
+            this.buffer = this.buffer.slice(nl + 1);
+            if (line === '')
+                continue;
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                // Non-protocol line; ignore.
+                continue;
+            }
+            if (typeof msg.id !== 'number')
+                continue;
+            const pending = this.pending.get(msg.id);
+            if (pending === undefined)
+                continue;
+            this.pending.delete(msg.id);
+            if (msg.ok === true)
+                pending.resolve(msg.result);
+            else
+                pending.reject(new Error(msg.err ?? 'browser host command failed'));
+        }
+    }
+    /** Send one command and await the reply. */
+    call(op, payload = {}) {
+        const id = this.nextId++;
+        const line = JSON.stringify({ id, op, ...payload });
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve: resolve, reject });
+            if (this.connected && this.socket !== undefined) {
+                this.socket.write(line + '\n');
+            }
+            else {
+                // Not connected yet: queue; attach() flushes on the child's arrival.
+                this.outbox.push(line);
+            }
+        });
+    }
+    /** Terminate the child. */
+    kill() {
+        try {
+            this.socket?.destroy();
+        }
+        catch { /* already closed */ }
+        this.child.kill();
+    }
+}
+/** One view in the child: its id, used for every command. */
+class RemoteView {
+    id;
+    client;
+    constructor(id, client) {
+        this.id = id;
+        this.client = client;
+    }
+    sendCommand(method, params) {
+        return this.client.call('command', {
+            viewId: this.id,
+            method,
+            params: params ?? {},
+        });
+    }
+}
+/**
+ * Self-hosted view host: spawns the plugin's Electron child on first use and
+ * keeps it alive until dispose(). Fallback when no desktop shell provides
+ * ctx.electronViewHost.
+ */
+export class RemoteElectronViewHost {
+    hostMainPath;
+    client;
+    server;
+    pendingSocket;
+    views = new Map();
+    readyPromise;
+    constructor(hostMainPath) {
+        this.hostMainPath = hostMainPath;
+    }
+    /** Ensure the child is up and ready (lazy on first use). */
+    ready() {
+        if (this.readyPromise !== undefined)
+            return this.readyPromise;
+        this.readyPromise = this.start();
+        return this.readyPromise;
+    }
+    async start() {
+        // Listen on an ephemeral loopback port; the child connects back.
+        const server = createServer(socket => {
+            if (this.client !== undefined)
+                this.client.attach(socket);
+            else
+                this.pendingSocket = socket;
+        });
+        await new Promise((resolve, reject) => {
+            server.once('error', reject);
+            server.listen(0, '127.0.0.1', () => resolve());
+        });
+        const address = server.address();
+        const port = typeof address === 'object' && address !== null ? address.port : 0;
+        this.server = server;
+        this.client = new ElectronChildClient(this.hostMainPath, port);
+        if (this.pendingSocket !== undefined) {
+            this.client.attach(this.pendingSocket);
+            this.pendingSocket = undefined;
+        }
+        // Wait for the child's connection + readiness ping.
+        await withTimeout(this.client.call('ping'), READY_TIMEOUT_MS, 'browser host did not become ready');
+    }
+    createView() {
+        // The seam is synchronous; the provider uses the handle immediately, so
+        // commands are deferred until the child is up and the view materialized.
+        const id = `view:${Math.random().toString(36).slice(2, 10)}`;
+        const view = new DeferredRemoteView(id, () => this.ensureView(id));
+        this.views.set(id, view);
+        return view;
+    }
+    async ensureView(id) {
+        await this.ready();
+        const client = this.client;
+        if (client === undefined)
+            throw new Error('browser host unavailable');
+        await client.call('createView', { viewId: id });
+        const view = new RemoteView(id, client);
+        this.views.set(id, view);
+        return view;
+    }
+    showView(handle) {
+        void this.ready().then(() => this.client?.call('showView', { viewId: handle.id }));
+    }
+    destroyView(handle) {
+        const view = this.views.get(handle.id);
+        if (view === undefined)
+            return;
+        this.views.delete(handle.id);
+        void this.ready()
+            .then(() => this.client?.call('destroyView', { viewId: handle.id }))
+            .catch(() => { });
+    }
+    /** Shut the child and the RPC server down. */
+    dispose() {
+        this.client?.kill();
+        this.client = undefined;
+        this.server?.close();
+        this.server = undefined;
+        this.readyPromise = undefined;
+        this.views.clear();
+    }
+}
+/** A view handle that waits for child readiness before issuing commands. */
+class DeferredRemoteView {
+    id;
+    materialize;
+    constructor(id, materialize) {
+        this.id = id;
+        this.materialize = materialize;
+    }
+    async sendCommand(method, params) {
+        const view = await this.materialize();
+        return view.sendCommand(method, params);
+    }
+}
+/** Reject a promise if it does not settle within the budget. */
+function withTimeout(promise, ms, message) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`${message} (${ms}ms)`)), ms);
+        promise.then(value => { clearTimeout(timer); resolve(value); }, error => { clearTimeout(timer); reject(error); });
+    });
+}
+/** Default host-main path relative to this module's build output. */
+export function defaultHostMainPath() {
+    return fileURLToPath(new URL('./host-main.js', import.meta.url));
+}

package/lib/tool-browser/index.js

@@ -42,7 +42,9 @@ export function apply(ctx, config = {}) {
     const timeoutMs = config.timeoutMs ?? 60_000;
     ctx.systemPrompt.section({
         name: 'tool:browser',
-        order: 110,
+        // Tool guidance band is 100-199; 150 keeps clear of the common 110/120
+        // tool sections so ordering does not depend on plugin load sequence.
+        order: 150,
         text: 'Use the browser_* tools to operate a real shared browser the human can see and take over. Locate elements by snapshot reference numbers (browser_snapshot) and drive them with browser_execute (DOM-referenced JS, native setters for framework inputs). browser_screenshot is for visual confirmation, not primary targeting. Keep the human informed of what you are doing on the page.',
     });
     ctx.tools.register(defineTool({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-builtin-browser",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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",
@@ -22,6 +22,9 @@
       "types": "./lib/tool-browser/index.d.ts",
       "default": "./lib/tool-browser/index.js"
     },
+    "./host-main": {
+      "default": "./lib/browser-electron/host-main.js"
+    },
     "./cordis.patch.yml": "./cordis.patch.yml",
     "./package.json": "./package.json"
   },
@@ -63,7 +66,13 @@
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-tools": "^0.0.1-rc.1"
+    "@deepseek-ai/dsh-tools": "^0.0.1-rc.1",
+    "electron": ">= 30.0.0"
+  },
+  "peerDependenciesMeta": {
+    "electron": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/node": "^22.0.0",