dsh-builtin-browser 0.1.21 → 0.1.22

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. */
@@ -823,6 +845,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 } : {} });
@@ -933,6 +984,34 @@ class DeferredRemoteView {
     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 +1030,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.22",
   "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",

package/src/browser-electron/host-main.ts

@@ -34,6 +34,7 @@ import { dirname, join } from 'node:path'
  * The spawn token the parent sent via stdin (first line). Must be echoed in
  * our hello. Read from stdin so the token never appears in argv (WMI /
  * Process Explorer / /proc/*).
+ */
 
 // Isolate this host's profile from the DSH app's default Electron userData:
 // several Electron instances sharing Roaming\Electron fight over the GPU
@@ -85,6 +86,14 @@ const TOOLBAR_HEIGHT = 64
 /** One view: the Electron object plus its CDP-backed surface. */
 interface HostView {
   readonly webContentsView: WebContentsView
+  /**
+   * Set when the view's renderer process was replaced by a navigation. The
+   * fresh renderer has no display surface, and Chromium silently drops CDP
+   * synthesized input for a view without one — so the next show/input must
+   * force the visible-again dance even if this view is already the visible
+   * one. Cleared once the surface has been re-established.
+   */
+  needsRepresent: boolean
 }
 
 /** One window: a session's views + its toolbar. */
@@ -176,7 +185,17 @@ button.tool:hover { background: rgba(255,255,255,.12); }
   <div class="strip" id="strip"></div>
   <div id="err"></div>
 <script>
-const bridge = window.bridge
+// The body runs inside an IIFE on purpose. The preload above exposes
+// window.bridge via contextBridge.exposeInMainWorld(), which installs a
+// NON-CONFIGURABLE global property. A top-level const/let named bridge here
+// would hit HasRestrictedGlobalProperty and throw a SyntaxError at PARSE time
+// — an early error, so the whole script is discarded: nothing gets bound, the
+// address bar and nav buttons go silently dead, and the user sees no error.
+// Function scope sidesteps that check (the tb name below stops the collision
+// from returning by habit) and keeps these bindings off the page global.
+// Keep this block free of backticks — it lives inside a TS template literal.
+(() => {
+const tb = window.bridge
 const addr = document.getElementById('addr')
 const strip = document.getElementById('strip')
 const errBox = document.getElementById('err')
@@ -187,7 +206,7 @@ function showErr(text) {
   clearTimeout(showErrT)
   showErrT = setTimeout(() => errBox.classList.remove('show'), 5000)
 }
-function post(action, payload) { bridge.post(action, payload || {}) }
+function post(action, payload) { tb.post(action, payload || {}) }
 document.getElementById('back').onclick = () => post('back')
 document.getElementById('fwd').onclick = () => post('forward')
 document.getElementById('reload').onclick = () => post('reload')
@@ -202,7 +221,7 @@ addr.addEventListener('keydown', e => {
     if (v !== '') { post('navigate', { url: v }); addr.blur() }
   }
 })
-bridge.onTabs(payload => {
+tb.onTabs(payload => {
   const tabs = (payload && payload.tabs) || []
   strip.textContent = ''
   for (const t of tabs) {
@@ -224,7 +243,8 @@ bridge.onTabs(payload => {
   const act = tabs.find(t => t.active)
   if (act && document.activeElement !== addr) addr.value = act.url || ''
 })
-bridge.onError(text => showErr(text))
+tb.onError(text => showErr(text))
+})()
 </script>
 </body>
 </html>
@@ -243,6 +263,48 @@ function ensureToolbarFiles(): void {
   writeFileSync(join(TOOLBAR_DIR, 'toolbar.html'), TOOLBAR_HTML)
 }
 
+/**
+ * Bound an await with a timeout. Used so a wedged renderer surfaces as an
+ * explicit error instead of a command that never settles.
+ */
+function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(`${label} timed out after ${ms}ms`))
+    }, ms)
+    promise.then(
+      (value) => { clearTimeout(timer); resolve(value) },
+      (error) => { clearTimeout(timer); reject(error) },
+    )
+  })
+}
+
+/**
+ * CDP commands are bounded here as well as in the parent: a view whose
+ * renderer stopped responding must produce a clear error, not a hang that
+ * only the tool layer's 10–30s timeout eventually cuts off.
+ */
+const COMMAND_TIMEOUT_MS = 20000
+
+/**
+ * A brand-new WebContentsView has no renderer process until something loads,
+ * and CDP commands (Runtime.evaluate …) sent to a renderer-less view never
+ * settle. That is what made a host restart unrecoverable: the provider
+ * rebuilds the session with a fresh blank view whose very first action is a
+ * location.href read, which hung until the tool timeout.
+ *
+ * Loading about:blank spawns the renderer, so the view answers the moment it
+ * exists; a real navigation replaces it right after. Bounded + best-effort —
+ * the caller still gets its reply if this fails.
+ */
+const RENDERER_PRIME_TIMEOUT_MS = 3000
+
+async function primeRenderer(view: WebContentsView): Promise<void> {
+  try {
+    await withTimeout(view.webContents.loadURL('about:blank'), RENDERER_PRIME_TIMEOUT_MS, 'renderer prime')
+  } catch { /* best effort: the first real navigation creates the renderer */ }
+}
+
 /** Reply to the parent over the RPC socket. */
 function reply(id: number, payload: Record<string, unknown>): void {
   if (rpcSocket === undefined) {
@@ -449,7 +511,16 @@ function updateWindowTitle(win: HostWindow, viewId: string | undefined, label: s
 function showViewInWindow(win: HostWindow, viewId: string, label?: string): void {
   const entry = win.views.get(viewId)
   if (entry === undefined) return
-  if (win.visibleViewId !== viewId) {
+  // A navigation replaced this view's renderer, and the new one has no
+  // display surface yet. Chromium drops CDP synthesized input (Input.*) for a
+  // view without a surface, which silently swallowed the FIRST click/keystroke
+  // after every navigation — and because the view was already the visible one,
+  // the dance below used to be skipped entirely. Force it once.
+  const mustRepresent = entry.needsRepresent
+  if (mustRepresent) {
+    try { entry.webContentsView.setVisible(false) } catch { /* destroyed */ }
+  }
+  if (win.visibleViewId !== viewId || mustRepresent) {
     // Hide every other view in THIS window, then show and RAISE the target
     // (topmost child wins). When the target is already visible, skip the
     // remove/re-add dance — doing it on every operation flickered.
@@ -463,6 +534,7 @@ function showViewInWindow(win: HostWindow, viewId: string, label?: string): void
       win.window.contentView.addChildView(entry.webContentsView)
     } catch { /* window closing */ }
     win.visibleViewId = viewId
+    entry.needsRepresent = false
     syncToolbar(win)
   }
   // Always refresh the title: it reflects the CURRENT page of the visible
@@ -549,11 +621,18 @@ async function handle(op: string, msg: { id: number; viewId?: string; windowId?:
         // New views start hidden: only the shown one may be visible.
         view.setVisible(false)
         win.window.contentView.addChildView(view)
-        win.views.set(viewId, { webContentsView: view })
+        win.views.set(viewId, { webContentsView: view, needsRepresent: false })
         // Keep the window title and the toolbar tab strip live as the page
         // changes (navigations, title updates).
         view.webContents.on('page-title-updated', () => { updateWindowTitle(win, viewId, undefined); syncToolbar(win) })
-        view.webContents.on('did-navigate', () => { updateWindowTitle(win, viewId, undefined); syncToolbar(win) })
+        view.webContents.on('did-navigate', () => {
+          // The renderer process was just replaced: mark the view so the next
+          // show forces a fresh display surface (see showViewInWindow).
+          const current = win.views.get(viewId)
+          if (current !== undefined) current.needsRepresent = true
+          updateWindowTitle(win, viewId, undefined)
+          syncToolbar(win)
+        })
         view.webContents.on('did-navigate-in-page', () => syncToolbar(win))
         wireFocusRouting(win, view, viewId)
         const first = win.views.size === 1
@@ -564,6 +643,10 @@ async function handle(op: string, msg: { id: number; viewId?: string; windowId?:
         layoutWindow(win)
         if (first) updateWindowTitle(win, viewId, undefined)
         syncToolbar(win)
+        // Prime the renderer BEFORE replying: the parent's next command
+        // (a location.href read) would otherwise hang on a view that has no
+        // renderer yet — the root of "host restarted and never recovers".
+        await primeRenderer(view)
         reply(msg.id, { ok: true })
         return
       }
@@ -623,7 +706,11 @@ async function handle(op: string, msg: { id: number; viewId?: string; windowId?:
         if (win === undefined || 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 ?? {})
+        const result = await withTimeout(
+          entry.webContentsView.webContents.debugger.sendCommand(method, msg.params ?? {}),
+          COMMAND_TIMEOUT_MS,
+          `CDP ${method}`,
+        )
         reply(msg.id, { ok: true, result })
         return
       }
@@ -894,6 +981,13 @@ void app.whenReady().then(() => {
     }
   }
   const rl = createInterface({ input: socket })
+  // Handle messages STRICTLY in order. Ops depend on each other completing:
+  // a `command` for a view must not overtake the `createView` that makes it,
+  // and the parent's present-barrier (`showView` then `ping`) is only
+  // meaningful if the child cannot answer the ping mid-show. The previous
+  // fire-and-forget loop let all of them race, which is how a fresh tab's
+  // first click could be dispatched before its view was ever on screen.
+  let queue: Promise<void> = Promise.resolve()
   rl.on('line', line => {
     const text = line.trim()
     if (text === '') return
@@ -904,7 +998,10 @@ void app.whenReady().then(() => {
       return // non-protocol noise
     }
     if (typeof msg.id !== 'number' || typeof msg.op !== 'string') return
-    void handle(msg.op, msg).catch(() => { /* reply already sent inside handle */ })
+    // Bind the narrowed op now: the check above does not survive into the
+    // deferred callback (msg is a mutable binding).
+    const op = msg.op
+    queue = queue.then(() => handle(op, msg)).catch(() => { /* reply already sent inside handle */ })
   })
   socket.on('error', error => {
     process.stderr.write(`[dsh-browser host] socket error: ${String(error)}\n`)