dsh-builtin-browser 0.1.23 → 0.3.0

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

@@ -11,11 +11,18 @@
  */
 
 import type { Context } from '@deepseek-ai/cordis'
+import type { IncomingMessage, ServerResponse } from 'node:http'
 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 {
   ELECTRON_BROWSER_PROVIDER_ID,
@@ -59,23 +66,222 @@ 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())
-  // 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, {
+  // 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)
+
+  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()
+  })
+
+  /**
+   * 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. */
+const SETTINGS_ROUTE = '/dsh-builtin-browser/settings'
+
+/** The host web-server surface this plugin uses, described structurally. */
+interface WebServerHost {
+  readonly webServer: {
+    register(
+      spec: {
+        readonly kind: 'exact'
+        readonly path: string
+        readonly handler: (request: IncomingMessage, response: ServerResponse) => void | Promise<void>
+      },
+      label?: string,
+    ): () => void
+  }
+  effect(callback: () => (() => void) | void): void
+}
+
+/**
+ * Expose the settings document over the host's web server, which is how the
+ * settings panel reads and writes it. A host without that service (headless /
+ * CLI surfaces) simply skips this: the panel is then unreachable and the file
+ * stays hand-editable — never a plugin-startup failure.
+ * @param ctx - the plugin context.
+ * @param settings - the settings document to expose.
+ */
+function installSettingsRoute(ctx: Context, settings: SettingsStore): void {
+  const inject = (ctx as unknown as {
+    inject?: (deps: readonly string[], callback: (host: WebServerHost) => void) => void
+  }).inject
+  if (typeof inject !== 'function') return
+  try {
+    inject(['webServer'], (host) => {
+      host.effect(() => host.webServer.register({
+        kind: 'exact',
+        path: SETTINGS_ROUTE,
+        handler: (request, response) => handleSettingsRequest(request, response, settings),
+      }, 'dsh-builtin-browser: settings'))
+    })
+  } catch {
+    // No web server on this surface: the settings file remains the interface.
+  }
+}
+
+/**
+ * Same-origin guard. Settings are machine-local configuration, so a page loaded
+ * elsewhere must not be able to read or rewrite them.
+ * @param request - the incoming request.
+ * @returns whether the request may touch the settings document.
+ */
+function sameOrigin(request: IncomingMessage): boolean {
+  const site = String(request.headers['sec-fetch-site'] ?? '').toLowerCase()
+  if (site === 'cross-site') return false
+  const origin = String(request.headers.origin ?? '').trim()
+  if (origin === 'null') return false
+  if (origin === '') return true
+  try {
+    return new URL(origin).host.toLowerCase() === String(request.headers.host ?? '').trim().toLowerCase()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * One settings round-trip: `GET` reads the document, `PUT`/`POST` merges a
+ * partial patch into it.
+ * @param request - the incoming request.
+ * @param response - the response to write.
+ * @param settings - the settings document.
+ */
+async function handleSettingsRequest(
+  request: IncomingMessage,
+  response: ServerResponse,
+  settings: SettingsStore,
+): Promise<void> {
+  const json = (status: number, body: unknown): void => {
+    response.writeHead(status, {
+      'content-type': 'application/json; charset=utf-8',
+      'cache-control': 'no-store',
+    })
+    response.end(JSON.stringify(body))
+  }
+  if (!sameOrigin(request)) {
+    json(403, { ok: false, error: 'cross-origin request refused' })
+    return
+  }
+  const method = request.method ?? 'GET'
+  if (method === 'GET') {
+    json(200, { ok: true, settings: settings.get(), path: settings.path() })
+    return
+  }
+  if (method !== 'PUT' && method !== 'POST') {
+    response.writeHead(405, { allow: 'GET, PUT' })
+    response.end()
+    return
+  }
+  try {
+    const body = await readBody(request)
+    const patch: unknown = body.trim() === '' ? {} : JSON.parse(body)
+    json(200, { ok: true, settings: settings.update(patch) })
+  } catch (error) {
+    json(400, { ok: false, error: `invalid settings patch: ${String(error)}` })
+  }
+}
+
+/**
+ * Read a request body with a hard cap (the settings patch is tiny, and an
+ * unbounded read would let any same-origin caller exhaust memory).
+ * @param request - the incoming request.
+ * @param limit - maximum accepted characters.
+ * @returns the body text.
+ */
+function readBody(request: IncomingMessage, limit = 64 * 1024): Promise<string> {
+  return new Promise<string>((resolve, reject) => {
+    let text = ''
+    request.setEncoding('utf8')
+    request.on('data', chunk => {
+      text += String(chunk)
+      if (text.length > limit) {
+        request.destroy()
+        reject(new Error('settings patch too large'))
+      }
+    })
+    request.on('end', () => resolve(text))
+    request.on('error', reject)
   })
 }