dsh-builtin-browser 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-builtin-browser",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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",
@@ -35,6 +35,7 @@
     "lib",
     "src",
     "docs",
+    "desktop-bridge",
     "client.js",
     "cordis.patch.yml",
     "README.md",

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

@@ -0,0 +1,145 @@
+/**
+ * Transport for the desktop shell's browser bridge: one long-lived connection to a
+ * loopback TCP service.
+ *
+ * WHY THIS IS ITS OWN MODULE
+ * The bridge used to be reached with a fresh connection per request, which measured
+ * at ~25ms per call (TCP handshake + token exchange) against ~0.2ms when the socket
+ * is reused. A single browser action issues several CDP commands, so that cost was
+ * multiplied on every tool call — the difference between a snappy agent and a
+ * visibly sluggish one. Reuse is therefore a property of the transport, and keeping
+ * it here means the view host above does not have to think about sockets at all.
+ *
+ * PROTOCOL
+ * The first line on a connection carries the token; the service marks the socket
+ * authenticated and ignores that line as a command. Requests and answers are then
+ * newline-delimited JSON, one answer per request, in order.
+ *
+ * @module dsh-browser/browser-electron/bridge-connection
+ */
+
+import { connect, type Socket } from 'node:net'
+
+/** Where the shell publishes its bridge endpoint. */
+export interface BridgeEndpoint {
+  readonly port: number
+  readonly token: string
+  readonly pid: number
+  readonly updatedAt?: string
+}
+
+/** One queued request, waiting for its answer. */
+interface PendingCall {
+  readonly resolve: (answer: Record<string, unknown>) => void
+  readonly reject: (error: Error) => void
+}
+
+/**
+ * A reusable connection to the bridge.
+ *
+ * Requests are serialised by construction: one socket, one in-flight request at a
+ * time, answered in order. A broken socket is discarded so the next call dials
+ * again — a dead connection must never become a dead plugin.
+ */
+export class BridgeConnection {
+  private socket: Socket | undefined
+  private buffer = ''
+  private readonly queue: PendingCall[] = []
+
+  /**
+   * @param endpoint - the shell's published bridge endpoint.
+   */
+  constructor(private readonly endpoint: BridgeEndpoint) {}
+
+  /**
+   * Send one request, reusing the socket if it is still healthy.
+   * @param request - the request body (the token is added here).
+   * @param timeoutMs - how long to wait for the answer before dropping the socket.
+   * @returns the bridge's answer.
+   */
+  async call(request: Record<string, unknown>, timeoutMs = 20_000): Promise<Record<string, unknown>> {
+    const socket = this.ensureSocket()
+    return await new Promise<Record<string, unknown>>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        const index = this.queue.findIndex(entry => entry.resolve === resolve)
+        if (index !== -1) this.queue.splice(index, 1)
+        const error = new Error(`dsh-builtin-browser: bridge timed out after ${timeoutMs}ms`)
+        this.reset(error)
+        reject(error)
+      }, timeoutMs)
+      this.queue.push({
+        resolve: answer => { clearTimeout(timer); resolve(answer) },
+        reject: error => { clearTimeout(timer); reject(error) },
+      })
+      try {
+        socket.write(JSON.stringify({ token: this.endpoint.token, ...request }) + '\n')
+      } catch (error) {
+        clearTimeout(timer)
+        this.queue.pop()
+        const failure = error instanceof Error ? error : new Error(String(error))
+        this.reset(failure)
+        reject(failure)
+      }
+    })
+  }
+
+  /** Close the socket and fail anything still waiting on it. */
+  close(): void {
+    this.reset(new Error('dsh-builtin-browser: bridge closed'))
+  }
+
+  /** The live socket, connecting and authenticating it on first use. */
+  private ensureSocket(): Socket {
+    if (this.socket !== undefined) return this.socket
+    const socket = connect({ host: '127.0.0.1', port: this.endpoint.port })
+    socket.setEncoding('utf8')
+    socket.on('data', chunk => this.onData(String(chunk)))
+    socket.on('error', error => this.reset(error))
+    socket.on('close', () => this.reset(new Error('dsh-builtin-browser: bridge connection closed')))
+    this.buffer = ''
+    this.socket = socket
+    socket.write(JSON.stringify({ token: this.endpoint.token }) + '\n')
+    return socket
+  }
+
+  /** Resolve queued requests in order as answers arrive. */
+  private onData(chunk: string): void {
+    this.buffer += chunk
+    let newline = this.buffer.indexOf('\n')
+    while (newline !== -1) {
+      const line = this.buffer.slice(0, newline).trim()
+      this.buffer = this.buffer.slice(newline + 1)
+      newline = this.buffer.indexOf('\n')
+      if (line === '') continue
+      const entry = this.queue.shift()
+      if (entry === undefined) continue
+      try {
+        const answer = JSON.parse(line) as Record<string, unknown>
+        // A rejected token means the shell restarted with a new one, so this socket
+        // can never succeed again: answer (the caller needs the error) and drop it,
+        // so the next call dials afresh instead of retrying a doomed credential.
+        if (answer.ok === false && answer.error === 'bad token') {
+          entry.resolve(answer)
+          this.reset(new Error('dsh-builtin-browser: the bridge rejected our token'))
+          continue
+        }
+        entry.resolve(answer)
+      } catch (error) {
+        entry.reject(new Error(`dsh-builtin-browser: malformed bridge answer (${String(error)})`))
+      }
+    }
+  }
+
+  /** Tear the socket down, failing pending work. */
+  private reset(error: Error): void {
+    if (this.socket !== undefined) {
+      const socket = this.socket
+      this.socket = undefined
+      socket.removeAllListeners()
+      socket.destroy()
+    }
+    this.buffer = ''
+    const pending = this.queue.splice(0, this.queue.length)
+    for (const entry of pending) entry.reject(error)
+  }
+}

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

@@ -0,0 +1,305 @@
+/**
+ * Desktop-sidebar browser host: drive the page the desktop shell shows in its
+ * sidebar, instead of spawning a second, parallel Electron window.
+ *
+ * WHY
+ * The plugin runs inside the desktop's Node-mode host, where there is no Electron
+ * API — which is why it self-hosts a whole browser today. The shell, however, can
+ * own views, and its sidebar already displays real web pages. This host borrows
+ * that page over the shell's bridge (see apps/desktop/bridge/plugin-browser-bridge.js),
+ * so the agent and the human end up on ONE page instead of two.
+ *
+ * CONTRACT
+ * It implements the same `ElectronBrowserViewHost` seam the self-hosted host does,
+ * so the provider, the tools, browsing history, the synthetic cursor and the
+ * teardown rules are all unchanged: only the carrier differs. Everything is
+ * lazily materialized — a fresh shell has no sidebar guest until something asks
+ * for a page, and the bridge creates one on demand.
+ *
+ * FALLBACK
+ * `discover()` returns undefined whenever the shell offers no usable bridge
+ * (older desktop build, plain `dsh web`, bridge not started), and the entry point
+ * then keeps the self-hosted Electron it has always used.
+ * @module dsh-browser/browser-electron/desktop-bridge-host
+ */
+
+import { BridgeConnection, type BridgeEndpoint } from './bridge-connection.js'
+import { readFileSync } from 'node:fs'
+import { connect, type Socket } from 'node:net'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { randomUUID } from 'node:crypto'
+import type { ElectronBrowserViewHost, ElectronViewHandle } from './provider.js'
+import type { BrowserUserAction } from './provider.js'
+
+
+/** Absolute path of the endpoint file the shell writes. */
+export function bridgeEndpointPath(): string {
+  const home = process.env.DSH_HOME ?? join(homedir(), '.dsh')
+  return join(home, 'dsh-builtin-browser-bridge.json')
+}
+
+/**
+ * Whether a command failed because the page is no longer there (as opposed to
+ * failing on its own merits). Only these are worth retrying on a fresh guest.
+ * @param error - the failure to classify.
+ */
+function isGuestGone(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error)
+  return /guest \d+ is not available|sidebar unavailable|did not create a browser guest/i.test(message)
+}
+
+/**
+ * The desktop sidebar, presented as a browser view host.
+ *
+ * One sidebar exists per shell window, so every view this host hands out refers
+ * to the same guest: the provider keeps its tab bookkeeping, and the tabs simply
+ * share the visible page. That is the intended behaviour for this carrier — the
+ * point is a single page both parties can see.
+ */
+export class DesktopBridgeViewHost implements ElectronBrowserViewHost {
+  private readonly connection: BridgeConnection
+  private readonly views = new Map<string, number>()
+  /**
+   * Guests whose view is gone but whose page may still be open in the sidebar.
+   *
+   * The provider destroys its view handles before it asks for a release, so the
+   * mapping is dropped by then — keeping the guest ids here is what lets us close
+   * only our own tabs when several sessions are running (requirements §4: each
+   * session gets its own page).
+   */
+  private readonly orphaned = new Set<number>()
+  private userActionHandler: ((action: BrowserUserAction) => void) | undefined
+
+  /**
+   * @param endpoint - the shell's published bridge endpoint.
+   */
+  private constructor(private readonly endpoint: BridgeEndpoint) {
+    this.connection = new BridgeConnection(endpoint)
+  }
+
+  /**
+   * Find a usable desktop bridge, if this surface has one.
+   *
+   * A stale endpoint (a shell that already exited, leaving its file behind) is
+   * rejected here rather than surfacing later as a mysterious ECONNREFUSED: the
+   * caller falls back to self-hosting, which always works.
+   * @returns the host, or undefined when no bridge is available.
+   */
+  static async discover(): Promise<DesktopBridgeViewHost | undefined> {
+    let endpoint: BridgeEndpoint
+    try {
+      const raw = JSON.parse(readFileSync(bridgeEndpointPath(), 'utf8')) as Partial<BridgeEndpoint>
+      if (typeof raw.port !== 'number' || typeof raw.token !== 'string' || typeof raw.pid !== 'number') return undefined
+      endpoint = { port: raw.port, token: raw.token, pid: raw.pid, ...raw.updatedAt !== undefined ? { updatedAt: raw.updatedAt } : {} }
+    } catch {
+      return undefined
+    }
+    try {
+      // A throwaway connection for discovery: the adopted host opens its own, and a
+      // rejected endpoint must not leave a socket behind.
+      const probe = new BridgeConnection(endpoint)
+      try {
+        const answer = await probe.call({ op: 'list' }, 5_000)
+        return answer.ok === true ? new DesktopBridgeViewHost(endpoint) : undefined
+      } finally {
+        probe.close()
+      }
+    } catch {
+      // Dead endpoint or an older bridge: self-hosting remains the answer.
+      return undefined
+    }
+  }
+
+  /** Whether this host can back views: the bridge already answered `list`. */
+  available(): boolean {
+    return true
+  }
+
+  /**
+   * The guest id backing a view, materialized on first use.
+   *
+   * The sidebar browser is itself a multi-tab surface, so each view gets its own
+   * tab's guest: the provider's tab bookkeeping then maps onto real tabs the human
+   * can see and switch between. Two rules keep that honest:
+   *   - a cached guest is used as-is: probing it first cost a round-trip on every
+   *     command, so liveness is established by the command failing instead;
+   *   - a fresh view takes an unclaimed guest, growing the tab strip only when
+   *     every existing guest is already spoken for.
+   * @param viewId - the view whose guest is wanted.
+   * @param url - address to use when a sidebar browser has to be opened first.
+   */
+  private async guestFor(viewId: string, url?: string): Promise<number> {
+    const existing = this.views.get(viewId)
+    // No liveness check here: verifying the cached guest cost a round-trip on every
+    // command. A guest that has gone away is detected by the command itself failing,
+    // and `createView`'s sendCommand then discards the cache and calls back in here.
+    if (existing !== undefined) return existing
+
+    // The browser tab must exist before its strip can be extended: `ensureSidebar`
+    // opens the sidebar (and, on a fresh shell, materializes the first guest).
+    const sidebar = await this.connection.call({
+      op: 'ensureSidebar',
+      ...url !== undefined ? { url } : {},
+    })
+    if (sidebar.ok !== true) throw new Error(`dsh-builtin-browser: sidebar unavailable (${String(sidebar.error)})`)
+
+    const wanted = this.views.size + 1
+    let ids = await this.guestIds(Math.max(1, wanted))
+    const taken = new Set(this.views.values())
+    let free = ids.find(id => !taken.has(id))
+    if (free === undefined) {
+      // Every tab is already driving something: the strip has to grow.
+      ids = await this.guestIds(ids.length + 1)
+      free = ids.find(id => !taken.has(id))
+    }
+    if (free === undefined) throw new Error('dsh-builtin-browser: the sidebar reported no free browser tab')
+    this.views.set(viewId, free)
+    return free
+  }
+
+  /**
+   * Ask for at least `count` sidebar tabs and return their guest ids.
+   * @param count - minimum number of tabs.
+   */
+  private async guestIds(count: number): Promise<number[]> {
+    const answer = await this.connection.call({ op: 'ensureTabs', count })
+    if (answer.ok !== true) throw new Error(`dsh-builtin-browser: could not open a sidebar tab (${String(answer.error)})`)
+    const ids = Array.isArray(answer.ids) ? answer.ids.map(Number).filter(Number.isFinite) : []
+    if (ids.length === 0) throw new Error('dsh-builtin-browser: the sidebar reported no browser tabs')
+    return ids
+  }
+
+  createView(): ElectronViewHandle {
+    const viewId = randomUUID()
+    const navigateUrl = (method: string, params?: Record<string, unknown>): string | undefined =>
+      method === 'Page.navigate' ? String((params as { url?: unknown })?.url ?? '') : undefined
+    const run = async (guest: number, method: string, params?: Record<string, unknown>): Promise<Record<string, unknown>> => {
+      const answer = await this.connection.call({ op: 'cdp', id: guest, method, params })
+      if (answer.ok !== true) throw new Error(`dsh-builtin-browser: sidebar command failed: ${String(answer.error)}`)
+      // The bridge forwards whatever CDP answered; the seam expects an object.
+      return (answer.result ?? {}) as Record<string, unknown>
+    }
+    return {
+      id: viewId,
+      sendCommand: async (method: string, params?: Record<string, unknown>) => {
+        // No liveness probe up front. Checking first cost a whole round-trip on
+        // every command; instead the command runs and its failure is what triggers
+        // recovery. Only a genuinely missing guest is retried, so a real error (a
+        // bad selector, a timeout) still surfaces unchanged.
+        const url = navigateUrl(method, params)
+        let guest = await this.guestFor(viewId, url)
+        try {
+          return await run(guest, method, params)
+        } catch (error) {
+          if (!isGuestGone(error)) throw error
+          // The human closed the tab: the page is gone, so take a fresh one and
+          // replay the command once. This is the "closing the interface ends the
+          // session" rule, now paid for only when it actually happens.
+          this.views.delete(viewId)
+          guest = await this.guestFor(viewId, url)
+          return await run(guest, method, params)
+        }
+      },
+    }
+  }
+
+  destroyView(handle: ElectronViewHandle): void {
+    const guest = this.views.get(handle.id)
+    if (guest !== undefined) {
+      // Remember it: the page outlives our handle, and a later release must be able
+      // to name exactly the tabs this plugin opened.
+      this.orphaned.add(guest)
+      this.views.delete(handle.id)
+    }
+  }
+
+  /**
+   * Nothing to show: the sidebar is already on screen, and showing it again is
+   * the shell's business (it owns the tab strip and the visibility toggle).
+   */
+  showView(): void {}
+
+  /** Same as {@link showView}: the page is already presented by the shell. */
+  async presentView(): Promise<void> {}
+
+  /**
+   * The shell owns window grouping, and one sidebar serves every view, so there
+   * is nothing to record here. (It must not write a placeholder guest id either:
+   * a view whose guest is not yet materialized has to stay absent from the map,
+   * or the first real command would be sent to the placeholder.)
+   */
+  groupView(): void {}
+
+  /** Focus is the shell's to manage, and there is no separate window to raise. */
+  async focus(): Promise<void> {}
+
+  onUserAction(handler: (action: BrowserUserAction) => void): void {
+    this.userActionHandler = handler
+  }
+
+  /** The shell reports its own window lifecycle; nothing to subscribe to here. */
+  onViewClosed(): void {}
+
+  /**
+   * Release the sidebar's browser pages (requirements §3, `ui.closeWithSession`).
+   *
+   * Destroying our own view handles is not enough on this carrier: the sidebar
+   * belongs to the shell and would happily keep the page (and its renderer) alive.
+   * Closing the tabs is what actually ends the page — and only the page: cookies
+   * live in the partition, history on disk, so both survive.
+   * @returns a promise that settles once the shell has been asked.
+   */
+  async releasePage(): Promise<void> {
+    // Only our own tabs: the ids come from the views we handed out (and their
+    // orphans), never from "every webview currently visible". With two sessions
+    // live, releasing one must leave the other's page alone.
+    const mine = [...this.views.values(), ...this.orphaned]
+    this.views.clear()
+    this.orphaned.clear()
+    // Nothing of ours is open: release nothing. Falling through to an unfiltered
+    // release here would close tabs a human opened, or another session's page.
+    if (mine.length === 0) return
+    let titles: string[]
+    try {
+      const answer = await this.connection.call({ op: 'list' }, 5_000)
+      const sidebar = Array.isArray(answer.sidebar) ? answer.sidebar as Array<{ id?: unknown; title?: unknown }> : []
+      titles = sidebar
+        .filter(guest => mine.includes(Number(guest.id)))
+        .map(guest => String(guest.title ?? ''))
+        .filter(title => title !== '')
+    } catch {
+      // Could not read the titles back; releasing nothing is safer than closing
+      // tabs that belong to somebody else.
+      return
+    }
+    if (titles.length === 0) return
+    try {
+      await this.connection.call({ op: 'closeSidebarBrowser', titles }, 10_000)
+    } catch {
+      // Best effort: the setting expresses a preference, and a shell that cannot
+      // be reached is no reason to fail the session teardown that called us.
+    }
+  }
+
+  /**
+   * Fold the sidebar away without ending the page (`ui.autoExpandOnce` is off, or
+   * the caller wants the screen back while work continues).
+   * @returns a promise that settles once the shell has been asked.
+   */
+  async collapse(): Promise<void> {
+    try {
+      await this.connection.call({ op: 'collapseSidebar' }, 10_000)
+    } catch {
+      // Presentation only; failing to fold is never worth an error.
+    }
+  }
+
+  /** No child process of our own to stop; close the shared connection instead. */
+  dispose(): void {
+    this.connection.close()
+    this.views.clear()
+    this.orphaned.clear()
+    this.userActionHandler = undefined
+  }
+}

package/src/browser-electron/entry.ts

@@ -16,7 +16,12 @@ import z from '@deepseek-ai/schemastery'
 import type { BrowserRuntime } from '../browser/runtime.js'
 import { ElectronBrowserProvider } from './provider.js'
 import type { ElectronBrowserViewHost } from './provider.js'
+import { randomUUID } from 'node:crypto'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
 import { defaultHostMainPath, RemoteElectronViewHost } from './remote-host.js'
+import { DesktopBridgeViewHost } from './desktop-bridge-host.js'
+import { detectBrowser, SystemBrowserViewHost } from './system-browser.js'
 import { SettingsStore } from './settings-store.js'
 
 export {
@@ -61,30 +66,96 @@ export const Config: z<Config> = z.object({
 
 /** Register the Electron browser provider with `ctx.browser`. */
 export function apply(ctx: Context & { browser: BrowserRuntime }, config: Config): void {
-  // External host (desktop shell) wins; otherwise self-host. The self-hosted
-  // child is disposed with the fiber, mirroring the shell's lifetime.
-  const host: ElectronBrowserViewHost = config.viewHost ?? new RemoteElectronViewHost(defaultHostMainPath())
   // 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()
-  // Own the disposer on THIS plugin's fiber: registerBrowserProvider's effect
-  // is bound to the seam's own fiber (the browser row), so a reload of this
-  // row would otherwise collide with the still-registered provider
-  // (BROWSER_DUPLICATE_PROVIDER) or leave a stale provider behind.
-  const unregister = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(host, {
+  installSettingsRoute(ctx, settings)
+
+  const providerConfig = {
     httpOnly: config.httpOnly,
     downloadDir: config.downloadDir,
     snapshotMaxElements: config.snapshotMaxElements,
     contentMaxChars: config.contentMaxChars,
     settings: () => settings.get(),
-  }))
+  }
+
+  // A host supplied by the composition (the desktop shell's own seam) wins and is
+  // synchronous, so registration stays synchronous on that path.
+  if (config.viewHost !== undefined) {
+    const external = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(config.viewHost as ElectronBrowserViewHost, providerConfig))
+    ctx.effect(() => () => { external() })
+    return
+  }
+
+  // Otherwise start self-hosted — a working browser from the first call, on every
+  // surface — and upgrade to the desktop sidebar if this machine has one. The
+  // upgrade is deliberately a swap of the whole provider: the two carriers own
+  // different lifetimes (a spawned child vs. the shell's view), and pretending
+  // otherwise would leave a stray window behind.
+  const selfHosted = new RemoteElectronViewHost(defaultHostMainPath())
+  let unregister = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(selfHosted, providerConfig))
+  let upgraded = false
+
   ctx.effect(() => () => {
     unregister()
-    if (config.viewHost === undefined && host instanceof RemoteElectronViewHost) {
-      host.dispose()
-    }
+    selfHosted.dispose()
   })
-  installSettingsRoute(ctx, settings)
+
+  /**
+   * 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 }
+    upgraded = true
+    try {
+      unregister()
+      unregister = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(host, providerConfig))
+      selfHosted.dispose()
+      ctx.logger?.info?.(`dsh-builtin-browser: ${note}`)
+    } catch (error) {
+      // Never leave the surface without a provider.
+      unregister = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(
+        new RemoteElectronViewHost(defaultHostMainPath()), providerConfig))
+      ctx.logger?.warn?.(`dsh-builtin-browser: could not adopt ${note} (${String(error)})`)
+    }
+  }
+
+  // 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.
+  void (async () => {
+    const channel = settings.get().browser.channel
+    if (channel === 'bundled') return
+    const detected = detectBrowser(channel)
+    if (detected === undefined) {
+      ctx.logger?.warn?.(`dsh-builtin-browser: ${channel} was requested but no installation was found; using the bundled browser`)
+      return
+    }
+    const home = process.env.DSH_HOME ?? homedir()
+    // Login state lives in the browser profile, so the cookies setting decides where
+    // that profile goes: a stable directory keeps the user signed in across restarts
+    // (the point of using their own browser), while turning persistence off gets a
+    // throwaway directory that is removed when the browser is released.
+    const persist = settings.get().cookies.persist
+    const profileDir = persist
+      ? join(home, 'dsh-builtin-browser-host', `${detected.kind}-profile`)
+      : join(home, 'dsh-builtin-browser-host', `${detected.kind}-profile-ephemeral-${randomUUID()}`)
+    const host = await SystemBrowserViewHost.launch(detected, profileDir, [], persist ? undefined : profileDir)
+    if (host === undefined) {
+      ctx.logger?.warn?.(`dsh-builtin-browser: ${detected.kind} did not start; using the bundled browser`)
+      return
+    }
+    adopt(host, `driving the installed ${detected.kind} (${detected.path}${persist ? '' : ', ephemeral profile'})`)
+  })().catch(() => { /* the bundled browser stays in place */ })
+
+  void DesktopBridgeViewHost.discover().then(sidebar => {
+    // No bridge (plain `dsh web`, an older desktop build, or a shell that already
+    // exited): keep self-hosting, which is what every surface has always done.
+    if (sidebar === undefined) return
+    adopt(sidebar, 'driving the desktop sidebar browser')
+  }).catch(() => { /* discovery never throws; keep self-hosting */ })
 }
 
 /** Route the settings panel reads and writes. */

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

@@ -89,15 +89,24 @@ export class HistoryStore {
   /**
    * Read visits, newest first. Unparseable lines are skipped; entries older
    * than the age limit are filtered out but left on disk until the next prune.
-   * @param options - optional result cap and domain filter.
+   * @param options - optional result cap plus three filters: `domain` (hostname),
+   *   `query` (substring of the URL or title) and `session` (the task that visited
+   *   it). Filters compose, so "the pages THIS task opened on that host" is one call.
    * @returns the matching visits, newest first.
    */
-  list(options: { readonly limit?: number; readonly domain?: string } = {}): VisitedPage[] {
+  list(options: { readonly limit?: number; readonly domain?: string; readonly query?: string; readonly session?: string } = {}): VisitedPage[] {
     const all = this.readAll()
     const cutoff = Date.now() - this.maxAgeMs
     const domain = options.domain?.toLowerCase()
+    const query = options.query?.toLowerCase()
+    const session = options.session
     const matches = all.filter(page => {
       if (page.at < cutoff) return false
+      if (session !== undefined && page.session !== session) return false
+      if (query !== undefined) {
+        const haystack = `${page.url}\n${page.title ?? ''}`.toLowerCase()
+        if (!haystack.includes(query)) return false
+      }
       if (domain === undefined) return true
       try {
         return new URL(page.url).hostname.toLowerCase().includes(domain)