dsh-builtin-browser 0.1.21 → 0.1.23

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

@@ -26,6 +26,7 @@
  */
 
 import { execFileSync, spawn, type ChildProcessByStdio } 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'
@@ -38,6 +39,9 @@ import type { ExportedCookie } from '../browser/types.js'
 /** 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
 
@@ -355,23 +359,32 @@ function compareVersions(a: string, b: string): number {
   return 0
 }
 
-/** From an electron package entry file, find the dist executable beside it. */
-function electronExeBeside(entry: string): string | undefined {
-  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: string, platform: NodeJS.Platform = process.platform): string[] {
+  // 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)) return candidate
+}
+
+/** From an electron package entry file, find the dist executable beside it. */
+function electronExeBeside(entry: string, platform: NodeJS.Platform = process.platform): string | undefined {
+  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: string): string | undefined {
-  for (const candidate of [join(pkgRoot, 'dist', 'electron.exe'), join(pkgRoot, 'dist', 'electron')]) {
+function electronDistExe(pkgRoot: string, platform: NodeJS.Platform = process.platform): string | undefined {
+  for (const candidate of electronDistCandidates(pkgRoot, platform)) {
     if (existsSync(candidate)) return candidate
   }
   return undefined
@@ -452,8 +465,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
@@ -464,11 +482,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}`))
     })
   }
 
@@ -633,6 +657,11 @@ class RemoteView implements ElectronViewHandle {
     })
   }
 
+  /** Give this view web focus in the child, so keyboard input reaches the page. */
+  focus(): Promise<void> {
+    return this.client.call<void>('focus', { viewId: this.id })
+  }
+
   /** Ask the child to download a URL to a local file (keeps cookies/login). */
   async download(url: string, savePath: string): Promise<void> {
     // The child writes the file itself (temp + rename); only a small
@@ -657,6 +686,15 @@ class RemoteView implements ElectronViewHandle {
   }
 }
 
+/**
+ * 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
@@ -669,8 +707,11 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
   private readonly views = new Map<string, ElectronViewHandle>()
   private readyPromise: Promise<void> | undefined
   private 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()`). */
   private electronAvailable: boolean | undefined
+  /** Earliest time the next probe may run after a negative one. */
+  private nextProbeAt = 0
   /** Window groups (windowId per view), re-sent on every materialization so
    *  a restarted child still places views in the right windows. */
   private readonly groups = new Map<string, { windowId: string; label?: string }>()
@@ -682,27 +723,37 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
     /** Test seam: the executable to spawn instead of the resolved Electron
      *  binary. Absent -> resolveElectronPath() (production behavior). */
     private readonly spawnExecutable?: string,
+    /** Test seam: the binary probe behind `available()`. Absent ->
+     *  resolveElectronPath(). */
+    private readonly probe: () => void = resolveElectronPath,
   ) {}
 
   /**
    * 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 {
-    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
   }
@@ -860,6 +911,39 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
       .catch(() => { /* host unavailable */ })
   }
 
+  /**
+   * (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: ElectronViewHandle, label?: string): Promise<void> {
+    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: ElectronViewHandle, windowId: string, label?: string): void {
     this.groups.set(handle.id, { windowId, ...label !== undefined ? { label } : {} })
@@ -970,6 +1054,10 @@ class DeferredRemoteView implements ElectronViewHandle {
     return this.withRecovery(view => view.capture(opts))
   }
 
+  async focus(): Promise<void> {
+    return this.withRecovery(view => view.focus())
+  }
+
   async flushAuth(): Promise<ExportedCookie[]> {
     return this.withRecovery(view => view.flushAuth())
   }
@@ -977,6 +1065,33 @@ class DeferredRemoteView implements ElectronViewHandle {
   async restoreAuth(cookies: ExportedCookie[]): Promise<number> {
     return this.withRecovery(view => view.restoreAuth(cookies))
   }
+
+  /** Materialize this view in the child (no-op when already there). */
+  async ensureMaterialized(): Promise<void> {
+    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: string): void {
+  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. */
@@ -1001,6 +1116,9 @@ export function defaultHostMainPath(): string {
  * steps; `resolveElectronPath` is the full resolution order.
  */
 export const internals = {
+  electronDistCandidates,
+  electronDistExe,
+  electronExeBeside,
   isBareElectron,
   resolveElectronPath,
   resolveElectronPathImpl,

package/src/tool-browser/index.ts

@@ -1087,7 +1087,7 @@ export function apply(ctx: Context, config: Config = {}): void {
     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).' },
@@ -1354,7 +1354,7 @@ export function apply(ctx: Context, config: Config = {}): void {
     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 } } },