dsh-builtin-browser 0.1.21 → 0.1.23

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

@@ -83,6 +83,12 @@ declare function resolveElectronPathImpl(inputs: ElectronPathInputs): string;
  * resources dir at all) likewise cannot run a script argument.
  */
 declare function isBareElectron(exe: string): boolean;
+/** Candidate executable layouts used by the Electron npm package on one platform. */
+declare function electronDistCandidates(pkgRoot: string, platform?: NodeJS.Platform): string[];
+/** From an electron package entry file, find the dist executable beside it. */
+declare function electronExeBeside(entry: string, platform?: NodeJS.Platform): string | undefined;
+/** From an electron package root, find its dist executable. */
+declare function electronDistExe(pkgRoot: string, platform?: NodeJS.Platform): string | undefined;
 /**
  * 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
@@ -93,14 +99,20 @@ export declare class RemoteElectronViewHost implements ElectronBrowserViewHost {
     /** Test seam: the executable to spawn instead of the resolved Electron
      *  binary. Absent -> resolveElectronPath() (production behavior). */
     private readonly spawnExecutable?;
+    /** Test seam: the binary probe behind `available()`. Absent ->
+     *  resolveElectronPath(). */
+    private readonly probe;
     private client;
     private server;
     private pendingSocket;
     private readonly views;
     private readyPromise;
     private disposed;
-    /** Cached probe result so `available()` stays cheap after the first call. */
+    /** Last probe result. A success is kept for the host's lifetime; a failure
+     *  is retried after `PROBE_RETRY_MS` (see `available()`). */
     private electronAvailable;
+    /** Earliest time the next probe may run after a negative one. */
+    private nextProbeAt;
     /** Window groups (windowId per view), re-sent on every materialization so
      *  a restarted child still places views in the right windows. */
     private readonly groups;
@@ -109,13 +121,22 @@ export declare class RemoteElectronViewHost implements ElectronBrowserViewHost {
     constructor(hostMainPath: string, 
     /** Test seam: the executable to spawn instead of the resolved Electron
      *  binary. Absent -> resolveElectronPath() (production behavior). */
-    spawnExecutable?: string | undefined);
+    spawnExecutable?: string | undefined, 
+    /** Test seam: the binary probe behind `available()`. Absent ->
+     *  resolveElectronPath(). */
+    probe?: () => void);
     /**
      * Cheap usability probe: can we find an Electron binary to spawn? The scan
-     * is filesystem-only (no network), per the seam's contract, and the result
-     * is cached for the host's lifetime — a missing binary surfaces as
-     * `BROWSER_PROVIDER_UNAVAILABLE` at provider selection instead of a
-     * confusing spawn failure on first use.
+     * is filesystem-only (no network), per the seam's contract, so a missing
+     * binary surfaces as `BROWSER_PROVIDER_UNAVAILABLE` at provider selection
+     * instead of a confusing spawn failure on first use.
+     *
+     * A success is cached for the host's lifetime. A failure is NOT: an install
+     * (`npm i electron`, or the postinstall that fetches the binary) can land
+     * long after DSH started, and provider selection happens once per process —
+     * caching "no" permanently reported "no usable browser provider is
+     * registered" until DSH restarted, with no way back short of that. Retrying
+     * on a cooldown heals it by itself while keeping the scan off the hot path.
      */
     available(): boolean;
     /** Ensure the child is up and ready (lazy on first use; restarts after a crash). */
@@ -126,6 +147,22 @@ export declare class RemoteElectronViewHost implements ElectronBrowserViewHost {
     createView(): ElectronViewHandle;
     private ensureView;
     showView(handle: ElectronViewHandle, label?: string): void;
+    /**
+     * (Re)present a view and WAIT for the child to confirm it, so the provider
+     * can dispatch CDP `Input.*` knowing the view has a display surface.
+     *
+     * Two things this fixes, both silent before:
+     *  - showing a view that does not exist yet is a no-op in the child, so the
+     *    view must be materialized first (a fresh tab's createView races the
+     *    provider's showActive);
+     *  - a view whose renderer was replaced by a navigation is \"already\n   *    visible\" and therefore skipped by the child's flicker-avoidance fast
+     *    path, leaving the new renderer without a surface.
+     *
+     * The barrier ping is meaningful because the child handles messages strictly
+     * in order: its reply is queued behind the showView and so only arrives once
+     * the visibility change has been applied.
+     */
+    presentView(handle: ElectronViewHandle, label?: string): Promise<void>;
     /** Route a view into its session's own window (one window per session). */
     groupView(handle: ElectronViewHandle, windowId: string, label?: string): void;
     /** Register the provider's handler for user-initiated toolbar actions. */
@@ -144,6 +181,9 @@ export declare function defaultHostMainPath(): string;
  * steps; `resolveElectronPath` is the full resolution order.
  */
 export declare const internals: {
+    electronDistCandidates: typeof electronDistCandidates;
+    electronDistExe: typeof electronDistExe;
+    electronExeBeside: typeof electronExeBeside;
     isBareElectron: typeof isBareElectron;
     resolveElectronPath: typeof resolveElectronPath;
     resolveElectronPathImpl: typeof resolveElectronPathImpl;

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

@@ -25,6 +25,7 @@
  * @module dsh-browser/browser-electron/remote-host
  */
 import { execFileSync, spawn } from 'node:child_process';
+import { appendFileSync, mkdirSync, statSync, writeFileSync } from 'node:fs';
 import { randomBytes } from 'node:crypto';
 import { createRequire } from 'node:module';
 import { existsSync, readFileSync, readdirSync, readlinkSync } from 'node:fs';
@@ -33,6 +34,8 @@ 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;
+/** Budget for the present/barrier round-trips (see presentView). */
+const PRESENT_TIMEOUT_MS = 10_000;
 /** Safety cap on a single RPC reply line (base64 downloads are the big ones). */
 const MAX_RPC_BUFFER_BYTES = 512 * 1024 * 1024;
 function resolveElectronPath() {
@@ -316,23 +319,31 @@ function compareVersions(a, b) {
     }
     return 0;
 }
-/** 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'),
+/** Candidate executable layouts used by the Electron npm package on one platform. */
+function electronDistCandidates(pkgRoot, platform = process.platform) {
+    // macOS keeps the runnable binary inside the Electron.app bundle; unlike
+    // Windows/Linux there is no dist/electron(.exe) sibling to probe.
+    if (platform === 'darwin') {
+        return [join(pkgRoot, 'dist', 'Electron.app', 'Contents', 'MacOS', 'Electron')];
+    }
+    return [
+        join(pkgRoot, 'dist', 'electron.exe'),
+        join(pkgRoot, 'dist', 'electron'),
     ];
-    for (const candidate of candidates) {
-        if (existsSync(candidate))
+}
+/** From an electron package entry file, find the dist executable beside it. */
+function electronExeBeside(entry, platform = process.platform) {
+    const packageRoots = [dirname(entry), join(dirname(entry), '..')];
+    for (const packageRoot of packageRoots) {
+        const candidate = electronDistExe(packageRoot, platform);
+        if (candidate !== undefined)
             return candidate;
     }
     return undefined;
 }
 /** From an electron package root, find its dist executable. */
-function electronDistExe(pkgRoot) {
-    for (const candidate of [join(pkgRoot, 'dist', 'electron.exe'), join(pkgRoot, 'dist', 'electron')]) {
+function electronDistExe(pkgRoot, platform = process.platform) {
+    for (const candidate of electronDistCandidates(pkgRoot, platform)) {
         if (existsSync(candidate))
             return candidate;
     }
@@ -411,8 +422,13 @@ class ElectronChildClient {
         });
         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)}`);
+            // Diagnostics only; never parse stderr as protocol. Mirror to a log file
+            // as well: under a plain `dsh web` self-host these lines only ever reach
+            // the DSH process's stderr, so a host that crashes in a restart loop left
+            // the user with a string of timeouts and no stack to act on.
+            const text = String(chunk);
+            process.stderr.write(`[dsh-browser host] ${text}`);
+            appendHostLog(text);
         });
         // Send the spawn token over stdin (first line). The child reads it from
         // stdin instead of argv so the token is never visible in the process
@@ -423,11 +439,17 @@ class ElectronChildClient {
         // A failed spawn (bad/corrupt binary) emits 'error' — without a listener
         // that would crash the whole DSH process.
         this.child.on('error', error => {
-            process.stderr.write(`[dsh-browser host] spawn error: ${String(error)}\n`);
+            const line = `spawn error: ${String(error)}`;
+            process.stderr.write(`[dsh-browser host] ${line}\n`);
+            appendHostLog(`${line}\n`);
             this.fail(new Error(`dsh-builtin-browser: browser host failed to start: ${String(error)}`));
         });
         this.child.on('exit', (code, signal) => {
-            this.fail(new Error(`dsh-builtin-browser: browser host exited (code=${String(code)} signal=${String(signal)})`));
+            // The exit code/signal is the other half of a crash report; without it a
+            // restart loop is indistinguishable from a clean stop.
+            const line = `browser host exited (code=${String(code)} signal=${String(signal)})`;
+            appendHostLog(`${line}\n`);
+            this.fail(new Error(`dsh-builtin-browser: ${line}`));
         });
     }
     /** Reject everything in flight, mark the client dead, and notify the host. */
@@ -602,6 +624,10 @@ class RemoteView {
             params: params ?? {},
         });
     }
+    /** Give this view web focus in the child, so keyboard input reaches the page. */
+    focus() {
+        return this.client.call('focus', { viewId: this.id });
+    }
     /** Ask the child to download a URL to a local file (keeps cookies/login). */
     async download(url, savePath) {
         // The child writes the file itself (temp + rename); only a small
@@ -622,6 +648,14 @@ class RemoteView {
         return this.client.call('restoreAuth', { viewId: this.id, cookies }).then(r => r.restored);
     }
 }
+/**
+ * How long a FAILED Electron-binary probe is remembered before the binary
+ * search runs again (`available()`). A success is kept for the host's lifetime.
+ */
+const PROBE_RETRY_MS = (() => {
+    const raw = Number(process.env.DSH_BROWSER_PROBE_RETRY_MS);
+    return Number.isFinite(raw) && raw >= 0 ? raw : 30000;
+})();
 /**
  * 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
@@ -630,14 +664,18 @@ class RemoteView {
 export class RemoteElectronViewHost {
     hostMainPath;
     spawnExecutable;
+    probe;
     client;
     server;
     pendingSocket;
     views = new Map();
     readyPromise;
     disposed = false;
-    /** Cached probe result so `available()` stays cheap after the first call. */
+    /** Last probe result. A success is kept for the host's lifetime; a failure
+     *  is retried after `PROBE_RETRY_MS` (see `available()`). */
     electronAvailable;
+    /** Earliest time the next probe may run after a negative one. */
+    nextProbeAt = 0;
     /** Window groups (windowId per view), re-sent on every materialization so
      *  a restarted child still places views in the right windows. */
     groups = new Map();
@@ -646,30 +684,43 @@ export class RemoteElectronViewHost {
     constructor(hostMainPath, 
     /** Test seam: the executable to spawn instead of the resolved Electron
      *  binary. Absent -> resolveElectronPath() (production behavior). */
-    spawnExecutable) {
+    spawnExecutable, 
+    /** Test seam: the binary probe behind `available()`. Absent ->
+     *  resolveElectronPath(). */
+    probe = resolveElectronPath) {
         this.hostMainPath = hostMainPath;
         this.spawnExecutable = spawnExecutable;
+        this.probe = probe;
     }
     /**
      * Cheap usability probe: can we find an Electron binary to spawn? The scan
-     * is filesystem-only (no network), per the seam's contract, and the result
-     * is cached for the host's lifetime — a missing binary surfaces as
-     * `BROWSER_PROVIDER_UNAVAILABLE` at provider selection instead of a
-     * confusing spawn failure on first use.
+     * is filesystem-only (no network), per the seam's contract, so a missing
+     * binary surfaces as `BROWSER_PROVIDER_UNAVAILABLE` at provider selection
+     * instead of a confusing spawn failure on first use.
+     *
+     * A success is cached for the host's lifetime. A failure is NOT: an install
+     * (`npm i electron`, or the postinstall that fetches the binary) can land
+     * long after DSH started, and provider selection happens once per process —
+     * caching "no" permanently reported "no usable browser provider is
+     * registered" until DSH restarted, with no way back short of that. Retrying
+     * on a cooldown heals it by itself while keeping the scan off the hot path.
      */
     available() {
-        if (this.electronAvailable === undefined) {
-            try {
-                resolveElectronPath();
-                this.electronAvailable = true;
-            }
-            catch (error) {
-                this.electronAvailable = false;
-                // The provider will be reported unavailable, so the detailed
-                // resolution error (install-electron / ELECTRON_PATH guidance) would
-                // otherwise never reach the user — surface it on stderr.
-                process.stderr.write(`[dsh-browser host] electron unavailable: ${error instanceof Error ? error.message : String(error)}\n`);
-            }
+        if (this.electronAvailable === true)
+            return true;
+        if (Date.now() < this.nextProbeAt)
+            return false;
+        this.nextProbeAt = Date.now() + PROBE_RETRY_MS;
+        try {
+            this.probe();
+            this.electronAvailable = true;
+        }
+        catch (error) {
+            this.electronAvailable = false;
+            // The provider will be reported unavailable, so the detailed
+            // resolution error (install-electron / ELECTRON_PATH guidance) would
+            // otherwise never reach the user — surface it on stderr.
+            process.stderr.write(`[dsh-browser host] electron unavailable: ${error instanceof Error ? error.message : String(error)}\n`);
         }
         return this.electronAvailable;
     }
@@ -823,6 +874,35 @@ export class RemoteElectronViewHost {
             .then(() => this.client?.call('showView', { viewId: handle.id, ...label !== undefined ? { label } : {} }))
             .catch(() => { });
     }
+    /**
+     * (Re)present a view and WAIT for the child to confirm it, so the provider
+     * can dispatch CDP `Input.*` knowing the view has a display surface.
+     *
+     * Two things this fixes, both silent before:
+     *  - showing a view that does not exist yet is a no-op in the child, so the
+     *    view must be materialized first (a fresh tab's createView races the
+     *    provider's showActive);
+     *  - a view whose renderer was replaced by a navigation is \"already\n   *    visible\" and therefore skipped by the child's flicker-avoidance fast
+     *    path, leaving the new renderer without a surface.
+     *
+     * The barrier ping is meaningful because the child handles messages strictly
+     * in order: its reply is queued behind the showView and so only arrives once
+     * the visibility change has been applied.
+     */
+    async presentView(handle, label) {
+        await this.ready();
+        const client = this.client;
+        if (client === undefined)
+            throw new HostGoneError('browser host unavailable');
+        // A view created after the last createView does not exist in the child yet.
+        // ensureMaterialized also rebuilds it against a fresh child after a host
+        // death, which is the path that used to leave sessions timing out forever.
+        if (handle instanceof DeferredRemoteView) {
+            await withTimeout(handle.ensureMaterialized(), PRESENT_TIMEOUT_MS, 'browser host did not materialize the view');
+        }
+        await withTimeout(client.call('showView', { viewId: handle.id, ...label !== undefined ? { label } : {} }), PRESENT_TIMEOUT_MS, 'browser host did not confirm the view presentation');
+        await withTimeout(client.call('ping'), PRESENT_TIMEOUT_MS, 'browser host stopped answering');
+    }
     /** Route a view into its session's own window (one window per session). */
     groupView(handle, windowId, label) {
         this.groups.set(handle.id, { windowId, ...label !== undefined ? { label } : {} });
@@ -927,12 +1007,43 @@ class DeferredRemoteView {
     async capture(opts) {
         return this.withRecovery(view => view.capture(opts));
     }
+    async focus() {
+        return this.withRecovery(view => view.focus());
+    }
     async flushAuth() {
         return this.withRecovery(view => view.flushAuth());
     }
     async restoreAuth(cookies) {
         return this.withRecovery(view => view.restoreAuth(cookies));
     }
+    /** Materialize this view in the child (no-op when already there). */
+    async ensureMaterialized() {
+        await this.withRecovery(async () => undefined);
+    }
+}
+/**
+ * Append one host-diagnostics chunk to `$DSH_HOME/logs/dsh-builtin-browser-host.log`.
+ * Best-effort and self-limiting: diagnostics must never break the host or grow
+ * without bound, so failures are swallowed and the file is truncated when it
+ * gets large (a crash loop writes quickly).
+ */
+const HOST_LOG_MAX_BYTES = 2 * 1024 * 1024;
+function appendHostLog(text) {
+    const home = process.env.DSH_HOME;
+    if (home === undefined || home === '')
+        return;
+    try {
+        const dir = join(home, 'logs');
+        const file = join(dir, 'dsh-builtin-browser-host.log');
+        try {
+            if (statSync(file).size > HOST_LOG_MAX_BYTES)
+                writeFileSync(file, '');
+        }
+        catch { /* first write, or unreadable: just append */ }
+        mkdirSync(dir, { recursive: true });
+        appendFileSync(file, text);
+    }
+    catch { /* diagnostics are best-effort only */ }
 }
 /** Reject a promise if it does not settle within the budget. */
 function withTimeout(promise, ms, message) {
@@ -951,6 +1062,9 @@ export function defaultHostMainPath() {
  * steps; `resolveElectronPath` is the full resolution order.
  */
 export const internals = {
+    electronDistCandidates,
+    electronDistExe,
+    electronExeBeside,
     isBareElectron,
     resolveElectronPath,
     resolveElectronPathImpl,

package/lib/tool-browser/index.js

@@ -1042,7 +1042,7 @@ export function apply(ctx, config = {}) {
         description: 'Capture the current shared-browser page as a screenshot (PNG default, JPEG optional). Use for visual confirmation of layout, charts, designs, or CAPTCHAs, or to feed a vision tool (read_image) that locates elements visually. Supports full-page capture, save-to-file, JPEG encoding, and downscaling (maxWidth/maxHeight) to cut vision-tool token cost. JPEG is only available on the self-hosted native path; the desktop-shell path returns PNG.',
         parameters: {
             fullPage: { type: 'boolean', description: 'Capture the full scrollable page instead of the viewport (default false).' },
-            savePath: { type: 'string', description: 'Absolute file path to also save the image to (e.g. for read_image vision location).' },
+            savePath: { type: 'string', description: 'Absolute file path to also save the image to (e.g. for read_image vision location). Must resolve inside the configured downloadDir (default: the system Downloads folder, localized names such as ~/下载 included); an existing file is never overwritten.' },
             format: { type: 'string', enum: ['png', 'jpeg'], description: 'Image format (default png; jpeg is self-hosted native path only).' },
             quality: { type: 'number', description: 'JPEG quality 1-100 (default 80); ignored for PNG.' },
             maxWidth: { type: 'number', description: 'Downscale to fit within this width (aspect preserved).' },
@@ -1312,7 +1312,7 @@ export function apply(ctx, config = {}) {
         description: 'Download a URL to a local file, keeping the browser session\'s cookies and login state. Use for fetching files behind authentication or from the current page context. Available on the self-hosted browser; the desktop shell delegates downloads to the real browser UI.',
         parameters: {
             url: { type: 'string', required: true, description: 'The URL to download.' },
-            savePath: { type: 'string', required: true, description: 'Absolute path of the file to write.' },
+            savePath: { type: 'string', required: true, description: 'Absolute path of the file to write. Must resolve inside the configured downloadDir (default: the system Downloads folder, localized names such as ~/下载 included); an existing file is never overwritten.' },
         },
         output: {
             schema: { type: 'object', additionalProperties: false, properties: { path: { type: 'string', required: true } } },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-builtin-browser",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "Shared real browser plugin for DeepSeek Harness: install-and-use — a visible native browser the human can take over, driven by the agent over CDP. DOM-level interaction (React/Vue safe), per-task session isolation, cookie persistence (browser_auth), CAPTCHA detection, batch form fill (browser_fill), authenticated download, history/replay, action restriction",
   "type": "module",
   "main": "lib/index.js",
@@ -65,9 +65,9 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-tools": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-llm": ">=0.1.1-rc.2 <0.3.0",
+    "@deepseek-ai/dsh-tools": ">=0.1.1-rc.2 <0.3.0",
+    "@deepseek-ai/dsh-system-prompt": ">=0.1.1-rc.2 <0.3.0",
     "@deepseek-ai/schemastery": "^3.18.1"
   },
   "devDependencies": {
@@ -79,7 +79,7 @@
       "patch": "./cordis.patch.yml"
     },
     "compatibility": {
-      "dsh": ">=0.1.1-rc.1 <0.2.0",
+      "dsh": ">=0.1.1-rc.1 <0.3.0",
       "profiles": [
         "web",
         "desktop"
@@ -87,7 +87,9 @@
       "dshReleases": {
         "0.1.0-rc.8": "unknown",
         "0.1.1-rc.1": "compatible",
-        "0.1.1-rc.2": "compatible"
+        "0.1.1-rc.2": "compatible",
+        "0.2.0-rc.1": "compatible",
+        "0.2.0-rc.2": "compatible"
       }
     }
   }

package/src/browser/runtime.ts

@@ -177,7 +177,21 @@ export class BrowserRuntime extends Service {
     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')
+      // Two very different causes used to read identically here — nothing is
+      // registered, or something is registered but cannot run — and only the
+      // second one has a fix the user can apply without reinstalling.
+      const registered = [...providers.values()].map(provider => provider.id)
+      if (registered.length === 0) {
+        throw new BrowserError(
+          'no browser provider is registered — install a browser plugin (e.g. dsh-builtin-browser) and enable it in this profile',
+          'BROWSER_PROVIDER_UNAVAILABLE',
+        )
+      }
+      throw new BrowserError(
+        `browser provider(s) ${registered.join(', ')} are registered but report themselves unavailable — `
+        + 'for dsh-builtin-browser this means no spawnable Electron binary was found; run `npx install-electron` in the active profile or set ELECTRON_PATH',
+        'BROWSER_PROVIDER_UNAVAILABLE',
+      )
     }
     if (usable.length > 1) {
       const ids = usable.map(provider => provider.id).join(', ')