dsh-builtin-browser 0.4.6 → 0.4.8

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-builtin-browser",
-  "version": "0.4.6",
-  "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",
+  "version": "0.4.8",
+  "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 (dsh_browser_auth), CAPTCHA detection, batch form fill (dsh_browser_fill), authenticated download, history/replay, action restriction",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/scripts/verify-host-compat.mjs

@@ -169,20 +169,20 @@ try {
 
 const exec = { agent: { id: 'verify-host-compat' } }
 try {
-  const value = await registered.get('browser_session').execute({}, exec)
-  ok('browser_session ran', value !== undefined, JSON.stringify(value).slice(0, 100))
+  const value = await registered.get('dsh_browser_session').execute({}, exec)
+  ok('dsh_browser_session ran', value !== undefined, JSON.stringify(value).slice(0, 100))
 } catch (error) {
-  ok('browser_session ran', false, String(error && error.message))
+  ok('dsh_browser_session ran', false, String(error && error.message))
 }
 
 try {
-  const tool = registered.get('browser_a11y')
+  const tool = registered.get('dsh_browser_a11y')
   const value = await tool.execute({}, exec)
   const text = JSON.stringify(tool.output.render({}, value))
-  ok('browser_a11y ran and rendered', value?.nodes?.length === 1, '')
+  ok('dsh_browser_a11y ran and rendered', value?.nodes?.length === 1, '')
   ok('its renderer emits the element selector', text.includes('#probe'), text.slice(0, 120))
 } catch (error) {
-  ok('browser_a11y ran', false, String(error && error.message))
+  ok('dsh_browser_a11y ran', false, String(error && error.message))
 }
 
 console.log('')

package/src/browser/types.ts

@@ -65,7 +65,7 @@ export interface BrowserScrollRequest {
 
 /** Press one named key (Enter, Tab, arrows, …). */
 export interface BrowserKeyRequest {
-  /** Key name from the supported set (see the browser_key tool). */
+  /** Key name from the supported set (see the dsh_browser_key tool). */
   readonly key: string
 }
 
@@ -361,7 +361,7 @@ export interface BrowserSnapshotElement {
   /**
    * True when the element lives inside an (same-origin) iframe: coordinates
    * are still top-document, but DOM selectors are frame-scoped — reach the
-   * element via `iframe.contentDocument` in browser_execute.
+   * element via `iframe.contentDocument` in dsh_browser_execute.
    */
   readonly frame?: boolean
 }

package/src/browser-electron/bridge-connection.ts

@@ -51,6 +51,16 @@ const MAX_BUFFER_BYTES = 128 * 1024 * 1024
  */
 const REQUEST_ID_FIELD = 'bridgeRequestId'
 
+/**
+ * How long the published endpoint may go un-refreshed before its shell is presumed gone.
+ *
+ * A live shell rewrites the file every fifteen seconds (its keep-alive), so four missed refreshes
+ * is not a slow shell — it is a shell that exited and left its last write behind. The distinction
+ * matters because the file is the ONLY thing that says where the bridge is: a tombstone names a
+ * port nobody owns, and a client that trusts it dials that port for the rest of its life.
+ */
+const ENDPOINT_TTL_MS = 60_000
+
 /**
  * A reusable connection to the bridge.
  *
@@ -78,12 +88,19 @@ export class BridgeConnection {
   private idLessBridge = false
   /** True once this connection may only have one request in flight at a time. */
   private serialisable = false
+  /** True once the shell behind this connection has been reported gone. */
+  private lostNotified = false
 
   /**
    * @param endpoint - the shell's published bridge endpoint.
    * @param endpointPath - where that endpoint is republished, so a moved port can be followed.
+   * @param onLost - called once when this connection concludes the shell behind it is gone.
    */
-  constructor(private endpoint: BridgeEndpoint, private readonly endpointPath?: string) {}
+  constructor(
+    private endpoint: BridgeEndpoint,
+    private readonly endpointPath?: string,
+    private readonly onLost?: () => void,
+  ) {}
 
   /**
    * Re-read the published endpoint, and adopt it if the shell has moved.
@@ -103,6 +120,13 @@ export class BridgeConnection {
     try {
       const raw = JSON.parse(readFileSync(this.endpointPath, 'utf8')) as Partial<BridgeEndpoint>
       if (typeof raw.port !== 'number' || typeof raw.token !== 'string') return false
+      // A shell that exited stops refreshing the file, and what it left names a port nobody owns.
+      // Trusting it is how a host ends up dialling a dead port for the rest of the process's life
+      // — reported as "the browser stopped working and only restarting DSH brought it back".
+      if (endpointExpired(raw.updatedAt)) {
+        this.notifyLost()
+        return false
+      }
       if (raw.port === this.endpoint.port && raw.token === this.endpoint.token) return false
       this.endpoint = {
         port: raw.port,
@@ -117,6 +141,17 @@ export class BridgeConnection {
     }
   }
 
+  /** Report once that the shell is gone, so the surface can fall back instead of dialling it. */
+  private notifyLost(): void {
+    if (this.lostNotified) return
+    this.lostNotified = true
+    try {
+      this.onLost?.()
+    } catch {
+      // A listener must never break the transport: the caller's error is the one that matters.
+    }
+  }
+
   /**
    * Send one request, reusing the socket if it is still healthy.
    *
@@ -138,6 +173,16 @@ export class BridgeConnection {
     // when the condition could not clear, spun until the process ran out of heap.
     // Follow the shell if its bridge moved to a new port (see refreshEndpoint).
     this.refreshEndpoint()
+    // The shell behind this connection is gone, and the endpoint file says so. Refusing here is
+    // what turns a permanent ECONNREFUSED into one named error the surface can act on — by
+    // falling back to the browser it hosts itself, instead of dialling a dead port until DSH is
+    // restarted.
+    if (this.lostNotified) {
+      throw new Error(
+        'dsh-builtin-browser: the desktop shell that backed this browser has exited '
+        + '(its published endpoint stopped being refreshed)',
+      )
+    }
     let socket = this.ensureSocket()
     if (this.serialisable && this.queue.length > 0) {
       this.reset(new Error('dsh-builtin-browser: bridge connection reopened so replies stay attributable'))
@@ -288,8 +333,21 @@ export class BridgeConnection {
   }
 }
 
-/** The request id a raw answer line echoes back, when it carries one. */
-function echoOf(line: string): number | undefined {
+/**
+ * Whether a published endpoint has gone un-refreshed long enough to be a tombstone.
+ *
+ * A missing or unparseable stamp is NOT expired: an older bridge that never wrote one must keep
+ * working, and guessing "stale" from absence would break every shell that predates the field.
+ * @param updatedAt - the file's own refresh stamp, when it carries one.
+ */
+function endpointExpired(updatedAt: unknown): boolean {
+  if (typeof updatedAt !== 'string') return false
+  const at = Date.parse(updatedAt)
+  if (!Number.isFinite(at)) return false
+  return Date.now() - at > ENDPOINT_TTL_MS
+}
+
+/** The request id a raw answer line echoes back, when it carries one. */function echoOf(line: string): number | undefined {
   try {
     const answer = JSON.parse(line) as Record<string, unknown>
     const value = answer[REQUEST_ID_FIELD]

package/src/browser-electron/desktop-bridge-host.ts

@@ -118,13 +118,34 @@ export class DesktopBridgeViewHost implements ElectronBrowserViewHost {
    * the desktop sidebar is the carrier — by design, not by omission.
    */
   private userActionHandler: ((action: BrowserUserAction) => void) | undefined
+  /** Told when the shell behind this bridge exits; see `onLost`. */
+  private lostListener: (() => void) | undefined
 
   /**
    * @param endpoint - the shell's published bridge endpoint.
    */
   private constructor(endpoint: BridgeEndpoint, sessionId?: string) {
     this.owner = sessionId !== undefined && sessionId !== String.fromCharCode(39,39) ? sessionId : randomUUID()
-    this.connection = new BridgeConnection(endpoint, bridgeEndpointPath())
+    this.connection = new BridgeConnection(endpoint, bridgeEndpointPath(), () => this.reportLost())
+  }
+
+  /**
+   * Called by the transport once the shell behind it is gone.
+   *
+   * Forwarded rather than acted on here: only the entry point owns the swap back to the self-hosted
+   * browser, and a host that tried to replace itself would be reaching outside its own contract.
+   */
+  private reportLost(): void {
+    try {
+      this.lostListener?.()
+    } catch {
+      // The listener's failure is not the transport's problem.
+    }
+  }
+
+  /** Register the "this carrier is gone" listener (see the interface's `onLost`). */
+  onLost(listener: () => void): void {
+    this.lostListener = listener
   }
 
   /**

package/src/browser-electron/entry.ts

@@ -5,7 +5,7 @@
  * `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
+ * installing the plugin is enough for `dsh_browser_*` tools to work on any
  * surface.
  * @module dsh-browser/browser-electron
  */
@@ -48,7 +48,7 @@ export interface Config {
   /** Allow navigation only to HTTP(S) URLs. Default true. */
   readonly httpOnly?: boolean
   /**
-   * Directory `browser_download` save paths must resolve inside (prevents a
+   * Directory `dsh_browser_download` save paths must resolve inside (prevents a
    * prompt-injected agent from writing arbitrary machine paths). Default:
    * the user's Downloads folder; override to confine downloads elsewhere.
    */
@@ -112,9 +112,10 @@ export function apply(ctx: Context & { browser: BrowserRuntime }, config: Config
   const sessionId = readSessionId(ctx)
 
   // One settings document per plugin instance: the settings panel writes it, the
-  // provider reads it live, and both ends agree on the same file.
-  const settings = new SettingsStore()
-  installSettingsRoute(ctx, settings)
+  // provider reads it live, and both ends agree on the same file. The logger is passed so a
+  // discarded value (a mistyped channel, most of all) is reported instead of being silently
+  // replaced by the default — "my setting did nothing" and "I misspelled it" must not look alike.
+  const settings = new SettingsStore(undefined, message => ctx.logger?.warn?.(message))
 
   const providerConfig = {
     httpOnly: config.httpOnly,
@@ -129,6 +130,17 @@ export function apply(ctx: Context & { browser: BrowserRuntime }, config: Config
   if (config.viewHost !== undefined) {
     const external = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(config.viewHost as ElectronBrowserViewHost, providerConfig))
     ctx.effect(() => () => { external() })
+    // The composition supplied the carrier, so `browser.channel` is not ours to honour on this
+    // surface. Saying so is the difference between a setting that cannot apply and a setting that
+    // appears not to have worked — the second is what sends people looking for a bug elsewhere.
+    const asked = settings.get().browser.channel
+    if (asked !== 'sidebar' && asked !== 'bundled') {
+      ctx.logger?.warn?.(
+        `dsh-builtin-browser: browser.channel is "${asked}", but this surface's carrier was `
+        + 'supplied by its composition (the desktop shell), which outranks the setting. Set it to '
+        + '"sidebar" to record the intent, or run on a surface that picks its own carrier.',
+      )
+    }
     return
   }
 
@@ -140,25 +152,69 @@ export function apply(ctx: Context & { browser: BrowserRuntime }, config: Config
   const selfHosted = new RemoteElectronViewHost(defaultHostMainPath())
   let unregister = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(selfHosted, providerConfig))
   let upgraded = false
+  /** The carrier an `adopt` installed, so a later choice can release it. */
+  let adoptedCarrier: ElectronBrowserViewHost | undefined
 
   ctx.effect(() => () => {
     unregister()
     selfHosted.dispose()
   })
 
+  /**
+   * Put the self-hosted browser back after an adopted carrier reports that it is gone.
+   *
+   * This is the half the startup retries never covered: a bridge that was alive at apply time and
+   * exited later left every subsequent call dialling a port nobody owns, because the swap happened
+   * once and only in one direction. Reaching here means the shell is gone, so the choice made at
+   * startup is no longer a choice — the alternative to falling back is a browser surface that does
+   * nothing until DSH is restarted.
+   * @param adopted - the carrier that reported the loss, disposed once its replacement is in place.
+   */
+  const restoreSelfHosted = (adopted: ElectronBrowserViewHost): void => {
+    try {
+      const restored = new RemoteElectronViewHost(defaultHostMainPath())
+      unregister()
+      unregister = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(restored, providerConfig))
+      ctx.logger?.warn?.(
+        'dsh-builtin-browser: the desktop shell backed the sidebar browser and has exited, so the '
+        + 'browser this plugin hosts itself takes over. Pages from the sidebar are gone with it; '
+        + 'open the page again.',
+      )
+    } catch (error) {
+      // Nothing better is available: the adopted carrier is gone and a provider that throws is
+      // worse than one that explains.
+      ctx.logger?.warn?.(`dsh-builtin-browser: could not fall back to the self-hosted browser: ${String(error)}`)
+    } finally {
+      adopted.dispose?.()
+    }
+  }
+
   /**
    * Swap the provider to another carrier, releasing the previous one.
    * @param host - the carrier to adopt.
    * @param note - a one-line description for the log.
    */
   const adopt = (host: ElectronBrowserViewHost, note: string): void => {
-    if (upgraded) { host.dispose?.(); return }
+    // This guard used to make the FIRST choice final, disposing anything that arrived later. That
+    // is right against two carriers racing in, and exactly wrong for a user changing the setting:
+    // `chooseCarrier` runs again on purpose, and a refusal here is indistinguishable from the
+    // write having done nothing. The previous carrier is now released by the replacement instead.
     upgraded = true
     try {
       unregister()
       unregister = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(host, providerConfig))
       selfHosted.dispose()
       ctx.logger?.info?.(`dsh-builtin-browser: ${note}`)
+      // A borrowed carrier can lose the process behind it, and this is the only notification that
+      // will ever arrive. Registering AFTER the swap succeeded means a listener can never fire
+      // against a provider that was never installed.
+      host.onLost?.(() => { restoreSelfHosted(host) })
+      const previous = adoptedCarrier
+      adoptedCarrier = host
+      // Released AFTER the replacement is installed, so the surface is never without a provider.
+      if (previous !== undefined && previous !== host) {
+        try { previous.dispose?.() } catch { /* the replacement is already serving */ }
+      }
     } catch (error) {
       // Never leave the surface without a provider. The half-built host is disposed FIRST: an
       // adopt that got as far as constructing it may already hold a socket, a listener or a child
@@ -184,6 +240,16 @@ export function apply(ctx: Context & { browser: BrowserRuntime }, config: Config
     }
   }
 
+  /**
+   * Choose and install the carrier that `browser.channel` names RIGHT NOW.
+   *
+   * A function rather than straight-line code because the setting is read live everywhere else:
+   * the settings route writes the file and the provider picks the change up on its next call, so a
+   * channel that could only be honoured at apply time was the one setting whose write silently did
+   * nothing. Re-entrant by design — changing the channel means replacing the carrier, which is
+   * exactly what a second call does.
+   */
+  const chooseCarrier = (): void => {
   // A browser the user explicitly asked for outranks every automatic choice: the
   // whole point of the setting is that they know which browser they want. It is
   // launched with a plugin-owned profile, so their own windows are untouched.
@@ -281,6 +347,14 @@ export function apply(ctx: Context & { browser: BrowserRuntime }, config: Config
       )
     }
   })()
+  }
+
+  chooseCarrier()
+
+  // Wired AFTER the chooser exists, because the handler re-runs it: a settings write that changes
+  // `browser.channel` is a request to switch carriers, and answering `ok` without switching is the
+  // one thing a caller cannot tell apart from a write that worked.
+  installSettingsRoute(ctx, settings, () => { chooseCarrier() })
 }
 
 /** Route the settings panel reads and writes. */
@@ -353,7 +427,11 @@ interface WebServerHost {
  * @param ctx - the plugin context.
  * @param settings - the settings document to expose.
  */
-function installSettingsRoute(ctx: Context, settings: SettingsStore): void {
+function installSettingsRoute(
+  ctx: Context,
+  settings: SettingsStore,
+  onChannelChange?: () => void,
+): void {
   const inject = (ctx as unknown as {
     inject?: (deps: readonly string[], callback: (host: WebServerHost) => void) => void
   }).inject
@@ -363,7 +441,7 @@ function installSettingsRoute(ctx: Context, settings: SettingsStore): void {
       host.effect(() => host.webServer.register({
         kind: 'exact',
         path: SETTINGS_ROUTE,
-        handler: (request, response) => handleSettingsRequest(request, response, settings),
+        handler: (request, response) => handleSettingsRequest(request, response, settings, onChannelChange),
       }, 'dsh-builtin-browser: settings'))
     })
   } catch {
@@ -377,11 +455,13 @@ function installSettingsRoute(ctx: Context, settings: SettingsStore): void {
  * @param request - the incoming request.
  * @param response - the response to write.
  * @param settings - the settings document.
+ * @param onChannelChange - re-runs the carrier choice when this write changed `browser.channel`.
  */
 async function handleSettingsRequest(
   request: IncomingMessage,
   response: ServerResponse,
   settings: SettingsStore,
+  onChannelChange?: () => void,
 ): Promise<void> {
   const json = (status: number, body: unknown): void => {
     response.writeHead(status, {
@@ -407,7 +487,19 @@ async function handleSettingsRequest(
   try {
     const body = await readBody(request)
     const patch: unknown = body.trim() === '' ? {} : JSON.parse(body)
-    json(200, { ok: true, settings: settings.update(patch) })
+    const before = settings.get().browser.channel
+    const updated = settings.update(patch)
+    // A changed `browser.channel` is a request to switch carriers, not just a value to store. The
+    // choice is re-run here so the write takes effect now — and the response says so, because a
+    // caller that cannot tell "applied" from "stored for later" has no way to know what it got,
+    // which is exactly how a write that did nothing read as a success.
+    const channelChanged = updated.browser.channel !== before
+    if (channelChanged) onChannelChange?.()
+    json(200, {
+      ok: true,
+      settings: updated,
+      ...channelChanged ? { carrierRechosen: true } : {},
+    })
   } catch (error) {
     json(400, { ok: false, error: `invalid settings patch: ${String(error)}` })
   }

package/src/browser-electron/history-store.ts

@@ -1,6 +1,6 @@
 /**
  * Persistent browsing history: which pages the shared browser actually visited,
- * kept independently from any session's operation log (`browser_history`) and
+ * kept independently from any session's operation log (`dsh_browser_history`) and
  * from the browser process's lifetime.
  *
  * It lives beside the browser profile (`$DSH_HOME/dsh-builtin-browser-host/

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

@@ -41,7 +41,7 @@ import { dirname, join } from 'node:path'
 // several Electron instances sharing Roaming\Electron fight over the GPU
 // cache/session locks, which can leave the window without a display surface
 // (capturePage then fails). A dedicated userData also persists cookies across
-// host restarts (on top of browser_auth). Must run before app is ready.
+// host restarts (on top of dsh_browser_auth). Must run before app is ready.
 try {
   const base = process.env.DSH_HOME ?? app.getPath('appData')
   app.setPath('userData', join(base, 'dsh-builtin-browser-host'))
@@ -769,7 +769,7 @@ async function handle(op: string, msg: { id: number; viewId?: string; windowId?:
         const entry = win?.views.get(viewId)
         if (win === undefined || entry === undefined) throw new Error(`focus: unknown view ${viewId}`)
         // Keys go to the view that holds web focus. A view that was never
-        // clicked holds none, so the FIRST browser_key of a session was dropped
+        // clicked holds none, so the FIRST dsh_browser_key of a session was dropped
         // by the renderer while CDP still answered the dispatch with success —
         // and `document.hasFocus()` inside the page even read true.
         const contents = entry.webContentsView.webContents
@@ -881,7 +881,7 @@ async function handle(op: string, msg: { id: number; viewId?: string; windowId?:
           throw new Error('capture produced no image (view not painted)')
         }
         // The measured size travels with the image. Without it the native path — which is the
-        // default self-hosted one — could never answer `browser_screenshot`'s width/height,
+        // default self-hosted one — could never answer `dsh_browser_screenshot`'s width/height,
         // because the seam's only channel was {base64, mime} and the provider had nothing to
         // forward. The caller's `maxWidth`/`maxHeight` are applied here, so this is the only
         // place that knows what came back.