dsh-builtin-browser 0.1.23 → 0.3.0

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

@@ -0,0 +1,227 @@
+/**
+ * Plugin-owned settings document — the switches the browser settings panel
+ * exposes, stored next to the browsing history so both follow the same rules:
+ * they survive the browser process and DSH restarts.
+ *
+ * Every field is optional on disk and falls back to a default, so a hand-edited
+ * or older file never breaks startup; an unreadable file is treated as "all
+ * defaults" rather than an error.
+ * @module dsh-browser/browser-electron/settings-store
+ */
+
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import type { BrowserChannel } from './system-browser.js'
+
+/** Vision/operation strategy the provider prefers when the model can see. */
+export type VisionStrategy = 'auto' | 'nonVisual'
+
+/** The full settings document, with every field resolved. */
+export interface BrowserSettings {
+  /** Persistent browsing history (visited pages). */
+  readonly history: {
+    readonly enabled: boolean
+    readonly maxEntries: number
+    readonly maxAgeDays: number
+  }
+  /** Login-state retention: cookies and the browser profile. */
+  readonly cookies: {
+    readonly persist: boolean
+  }
+  /** Presentation behaviour. */
+  readonly ui: {
+    /** Auto-expand the side panel once per task, then leave the user alone. */
+    readonly autoExpandOnce: boolean
+    /** Release the browser when its session ends, instead of waiting for a close. */
+    readonly closeWithSession: boolean
+    /** Show the synthetic cursor/click feedback while the agent operates. */
+    readonly virtualCursor: boolean
+  }
+  /** Visual vs non-visual operation strategy. */
+  readonly vision: {
+    readonly strategy: VisionStrategy
+  }
+  /** Which browser binary carries the agent's pages. */
+  readonly browser: {
+    readonly channel: BrowserChannel
+  }
+  /** Whether the agent may read cookies / export login state. */
+  readonly credentials: {
+    readonly allowRead: boolean
+  }
+}
+
+/** Defaults for every switch: the documented out-of-the-box behaviour. */
+export const DEFAULT_SETTINGS: BrowserSettings = {
+  history: { enabled: true, maxEntries: 5_000, maxAgeDays: 90 },
+  cookies: { persist: true },
+  ui: { autoExpandOnce: true, closeWithSession: false, virtualCursor: true },
+  vision: { strategy: 'auto' },
+  // Bundled by default: it needs nothing installed, and on the desktop the carrier
+  // is the sidebar anyway. Choosing a system browser is an explicit opt-in because
+  // it starts a real Chrome/Edge with its own profile.
+  browser: { channel: 'bundled' },
+  credentials: { allowRead: true },
+}
+
+/**
+ * Absolute path of the settings file, beside the browser profile and the
+ * browsing history.
+ * @returns the settings file path.
+ */
+export function settingsPath(): string {
+  const home = process.env.DSH_HOME ?? join(homedir(), '.dsh')
+  return join(home, 'dsh-builtin-browser-host', 'settings.json')
+}
+
+/** Coerce one boolean field, keeping the default when absent or mistyped. */
+function bool(value: unknown, fallback: boolean): boolean {
+  return typeof value === 'boolean' ? value : fallback
+}
+
+/**
+ * Coerce the browser channel, keeping the default when it is not one of the
+ * known choices. A hand-edited typo must not silently select a different browser.
+ * @param value - the raw value from the settings document.
+ * @returns a valid channel.
+ */
+function resolveChannel(value: unknown): BrowserChannel {
+  return value === 'chrome' || value === 'edge' || value === 'auto' || value === 'bundled'
+    ? value
+    : DEFAULT_SETTINGS.browser.channel
+}
+
+/** Coerce one positive-integer field, keeping the default when invalid. */
+function count(value: unknown, fallback: number): number {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback
+}
+
+/** Read one nested section of an unknown document, or an empty object. */
+function section(source: Record<string, unknown>, key: string): Record<string, unknown> {
+  const value = source[key]
+  return typeof value === 'object' && value !== null ? value as Record<string, unknown> : {}
+}
+
+/**
+ * Resolve a raw settings document (already parsed, shape unknown) into the full
+ * document, field by field. Unknown keys are dropped: the file is not a place to
+ * smuggle configuration.
+ * @param raw - the parsed file contents.
+ * @returns the resolved settings.
+ */
+export function resolveSettings(raw: unknown): BrowserSettings {
+  const source = typeof raw === 'object' && raw !== null ? raw as Record<string, unknown> : {}
+  const history = section(source, 'history')
+  const cookies = section(source, 'cookies')
+  const ui = section(source, 'ui')
+  const vision = section(source, 'vision')
+  const credentials = section(source, 'credentials')
+  const browser = section(source, 'browser')
+  return {
+    history: {
+      enabled: bool(history.enabled, DEFAULT_SETTINGS.history.enabled),
+      maxEntries: count(history.maxEntries, DEFAULT_SETTINGS.history.maxEntries),
+      maxAgeDays: count(history.maxAgeDays, DEFAULT_SETTINGS.history.maxAgeDays),
+    },
+    cookies: { persist: bool(cookies.persist, DEFAULT_SETTINGS.cookies.persist) },
+    ui: {
+      autoExpandOnce: bool(ui.autoExpandOnce, DEFAULT_SETTINGS.ui.autoExpandOnce),
+      closeWithSession: bool(ui.closeWithSession, DEFAULT_SETTINGS.ui.closeWithSession),
+      virtualCursor: bool(ui.virtualCursor, DEFAULT_SETTINGS.ui.virtualCursor),
+    },
+    vision: { strategy: vision.strategy === 'nonVisual' ? 'nonVisual' : DEFAULT_SETTINGS.vision.strategy },
+    browser: { channel: resolveChannel(browser.channel) },
+    credentials: { allowRead: bool(credentials.allowRead, DEFAULT_SETTINGS.credentials.allowRead) },
+  }
+}
+
+/**
+ * File-backed settings with an in-memory snapshot. Reads re-stat the file so an
+ * edit from another process (or the settings panel writing through a second
+ * code path) is picked up without a restart; writes are atomic enough for a
+ * single-writer plugin and never throw at the caller.
+ */
+export class SettingsStore {
+  private cached: BrowserSettings | undefined
+  /** Last observed mtime, used to invalidate the cache on external edits. */
+  private cachedMtimeMs = -1
+
+  /**
+   * @param file - settings file path (defaults beside the browser profile).
+   */
+  constructor(private readonly file: string = settingsPath()) {}
+
+  /** Path this store reads and writes. */
+  path(): string {
+    return this.file
+  }
+
+  /**
+   * Current settings, re-read when the file changed on disk.
+   * @returns the resolved settings document.
+   */
+  get(): BrowserSettings {
+    let mtimeMs = -1
+    let text: string | undefined
+    try {
+      if (existsSync(this.file)) {
+        mtimeMs = statSync(this.file).mtimeMs
+        text = readFileSync(this.file, 'utf8')
+      }
+    } catch {
+      // Unreadable file: fall through to defaults below.
+      mtimeMs = -1
+      text = undefined
+    }
+    if (this.cached !== undefined && mtimeMs === this.cachedMtimeMs) return this.cached
+    try {
+      // A leading BOM is what ordinary Windows editors (Notepad, PowerShell's
+      // `Set-Content -Encoding utf8`) leave behind, and `JSON.parse` rejects it.
+      // Without this strip, hand-editing the settings file silently discarded every
+      // value in it: the document looked correct, and the plugin quietly ran on
+      // defaults — including switches the user had just turned off.
+      const body = text?.replace(/^\uFEFF/, '')
+      this.cached = body === undefined ? DEFAULT_SETTINGS : resolveSettings(JSON.parse(body))
+    } catch {
+      // Malformed JSON: behave as defaults rather than fail startup.
+      this.cached = DEFAULT_SETTINGS
+    }
+    this.cachedMtimeMs = mtimeMs
+    return this.cached
+  }
+
+  /**
+   * Merge a partial patch into the stored document and persist it.
+   * @param patch - the fields to change (unknown keys are ignored).
+   * @returns the settings after the merge.
+   */
+  update(patch: unknown): BrowserSettings {
+    const current = this.get()
+    const merged = resolveSettings(deepMerge(current as unknown as Record<string, unknown>, patch))
+    try {
+      mkdirSync(dirname(this.file), { recursive: true })
+      writeFileSync(this.file, `${JSON.stringify(merged, null, 2)}\n`)
+    } catch {
+      // Keep the merged value in memory even when the write fails.
+    }
+    this.cached = merged
+    this.cachedMtimeMs = Date.now()
+    return merged
+  }
+}
+
+/** One-level-deep merge over the settings sections (patch wins). */
+function deepMerge(base: Record<string, unknown>, patch: unknown): Record<string, unknown> {
+  if (typeof patch !== 'object' || patch === null) return base
+  const result: Record<string, unknown> = { ...base }
+  for (const [key, value] of Object.entries(patch as Record<string, unknown>)) {
+    const existing = result[key]
+    if (typeof value === 'object' && value !== null && typeof existing === 'object' && existing !== null) {
+      result[key] = { ...existing as Record<string, unknown>, ...value as Record<string, unknown> }
+    } else {
+      result[key] = value
+    }
+  }
+  return result
+}

package/src/browser-electron/system-browser.ts

@@ -0,0 +1,318 @@
+/**
+ * Drive the browser the user already has (Chrome / Edge / any Chromium) instead of
+ * the Electron we ship — the same approach Codex Browser Use takes.
+ *
+ * WHY
+ * The bundled Electron is a private copy with its own profile, so it can never see
+ * the logins the user already has in Chrome, and on a managed machine the user may
+ * simply prefer their own browser. Launching their browser with a *separate*
+ * `--user-data-dir` gives us a real Chromium we can drive over CDP without touching
+ * their everyday profile, bookmarks or windows: nothing of theirs is opened, locked
+ * or modified, and closing us never closes them.
+ *
+ * HOW
+ * Chromium exposes CDP on `--remote-debugging-port=0`, and writes the port it chose
+ * into `<profile>/DevToolsActivePort`. That file is the discovery mechanism — no
+ * port guessing, no collisions. From there everything is CDP over one WebSocket:
+ * `Target.createTarget` makes a page, `Target.attachToTarget` (flattened) gives a
+ * session for it, and the plugin's commands ride that session. Node 22 ships a global
+ * `WebSocket`, so this needs no dependency at all.
+ *
+ * WHAT IT IMPLEMENTS
+ * The same `ElectronBrowserViewHost` seam as the self-hosted and sidebar hosts, so
+ * the provider, the tools, history, the cursor and teardown rules are unchanged —
+ * only the carrier differs.
+ * @module dsh-browser/browser-electron/system-browser
+ */
+
+import { readFileSync, rmSync } from 'node:fs'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { spawn, type ChildProcess } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
+import type { ElectronBrowserViewHost, ElectronViewHandle } from './provider.js'
+
+/** Which browser the user asked for. */
+export type BrowserChannel = 'bundled' | 'chrome' | 'edge' | 'auto'
+
+/** A resolved browser installation. */
+export interface DetectedBrowser {
+  /** Which product this is. */
+  readonly kind: 'chrome' | 'edge' | 'brave'
+  /** Absolute path to the executable. */
+  readonly path: string
+}
+
+/**
+ * Where each Chromium product installs on Windows, plus the registry paths that
+ * survive a non-default install location. Only paths that exist are returned, so a
+ * caller can tell "not installed" from "installed elsewhere".
+ */
+const WINDOWS_LOCATIONS: Record<DetectedBrowser['kind'], string[]> = {
+  chrome: [
+    String.raw`C:\Program Files\Google\Chrome\Application\chrome.exe`,
+    String.raw`C:\Program Files (x86)\Google\Chrome\Application\chrome.exe`,
+  ],
+  edge: [
+    String.raw`C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe`,
+    String.raw`C:\Program Files\Microsoft\Edge\Application\msedge.exe`,
+  ],
+  brave: [
+    String.raw`C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe`,
+    String.raw`C:\Program Files (x86)\BraveSoftware\Brave-Browser\Application\brave.exe`,
+  ],
+}
+
+/**
+ * Find an installed Chromium browser.
+ *
+ * `auto` prefers Chrome, then Edge, then Brave — the order reflects how likely each
+ * is to be the browser a user actually chose rather than one Windows shipped.
+ * @param channel - the configured choice; `bundled` never resolves to a system browser.
+ * @param env - environment lookup, injected so tests need no real machine.
+ * @returns the detected browser, or undefined when the choice is unavailable.
+ */
+export function detectBrowser(channel: BrowserChannel, env: NodeJS.ProcessEnv = process.env): DetectedBrowser | undefined {
+  if (channel === 'bundled') return undefined
+  const order: DetectedBrowser['kind'][] = channel === 'auto' ? ['chrome', 'edge', 'brave'] : [channel as DetectedBrowser['kind']]
+  for (const kind of order) {
+    const fromEnv = (kind === 'chrome' ? env.DSH_BROWSER_CHROME_PATH : kind === 'edge' ? env.DSH_BROWSER_EDGE_PATH : undefined)
+    if (fromEnv !== undefined && fromEnv !== '' && existsSync(fromEnv)) return { kind, path: fromEnv }
+    for (const candidate of WINDOWS_LOCATIONS[kind] ?? []) {
+      if (existsSync(candidate)) return { kind, path: candidate }
+    }
+  }
+  return undefined
+}
+
+/** One CDP connection to a browser-level WebSocket, with flattened sessions. */
+class CdpClient {
+  private nextId = 1
+  private readonly pending = new Map<number, { resolve: (value: unknown) => void; reject: (error: Error) => void }>()
+  private readonly ready: Promise<void>
+
+  /**
+   * @param url - the browser's `webSocketDebuggerUrl`.
+   */
+  constructor(private readonly url: string) {
+    // Node 22 provides WebSocket globally; no dependency is added for this.
+    const socket = new WebSocket(url)
+    this.socket = socket
+    this.ready = new Promise<void>((resolve, reject) => {
+      socket.addEventListener('open', () => resolve())
+      socket.addEventListener('error', () => reject(new Error('dsh-builtin-browser: could not reach the browser over CDP')))
+    })
+    socket.addEventListener('message', event => this.onMessage(String((event as MessageEvent).data)))
+    socket.addEventListener('close', () => this.fail(new Error('dsh-builtin-browser: the browser closed the CDP connection')))
+  }
+
+  private readonly socket: WebSocket
+
+  /** Resolve once the socket is open. */
+  async whenReady(): Promise<void> {
+    await this.ready
+  }
+
+  /**
+   * Send one CDP command, optionally on an attached session.
+   * @param method - the CDP method.
+   * @param params - its parameters.
+   * @param sessionId - the flattened session to target, when this is a page command.
+   * @returns the CDP result.
+   */
+  async send(method: string, params?: Record<string, unknown>, sessionId?: string): Promise<unknown> {
+    await this.ready
+    const id = this.nextId++
+    const message = { id, method, ...params !== undefined ? { params } : {}, ...sessionId !== undefined ? { sessionId } : {} }
+    return await new Promise<unknown>((resolve, reject) => {
+      this.pending.set(id, { resolve, reject })
+      this.socket.send(JSON.stringify(message))
+      setTimeout(() => {
+        if (this.pending.delete(id)) reject(new Error(`dsh-builtin-browser: ${method} timed out`))
+      }, 30_000).unref?.()
+    })
+  }
+
+  /** Close the socket. */
+  close(): void {
+    try { this.socket.close() } catch { /* already closed */ }
+  }
+
+  /** Route one CDP message to its waiter. */
+  private onMessage(raw: string): void {
+    let message: { id?: number; result?: unknown; error?: { message?: string } }
+    try { message = JSON.parse(raw) } catch { return }
+    if (message.id === undefined) return
+    const entry = this.pending.get(message.id)
+    if (entry === undefined) return
+    this.pending.delete(message.id)
+    if (message.error !== undefined) entry.reject(new Error(`dsh-builtin-browser: CDP error: ${message.error.message ?? 'unknown'}`))
+    else entry.resolve(message.result)
+  }
+
+  /** Fail everything in flight. */
+  private fail(error: Error): void {
+    const pending = [...this.pending.values()]
+    this.pending.clear()
+    for (const entry of pending) entry.reject(error)
+  }
+}
+
+/** A system browser driven over CDP, presented as a browser view host. */
+export class SystemBrowserViewHost implements ElectronBrowserViewHost {
+  private readonly views = new Map<string, string>()
+  private disposed = false
+
+  /**
+   * @param child - the launched browser process.
+   * @param client - the CDP connection to it.
+   * @param kind - which product this is (for diagnostics).
+   * @param ephemeralDir - a throwaway profile to remove on release, when the user
+   *   has turned persistence off and no login state should outlive the session.
+   */
+  private constructor(
+    private readonly child: ChildProcess,
+    private readonly client: CdpClient,
+    readonly kind: DetectedBrowser['kind'],
+    private readonly ephemeralDir?: string,
+  ) {}
+
+  /**
+   * @param browser - the detected installation to launch.
+   * @param profileDir - a plugin-owned directory; the user's own profile is never touched.
+   * @param extraArgs - additional Chromium switches.
+   * @param ephemeralDir - a directory to delete when the browser is released, used
+   *   when persistence is switched off so no login state outlives the session.
+   * @returns the host, or undefined when the browser refuses to come up.
+   */
+  static async launch(browser: DetectedBrowser, profileDir: string, extraArgs: readonly string[] = [], ephemeralDir?: string): Promise<SystemBrowserViewHost | undefined> {
+    const args = [
+      '--remote-debugging-port=0',
+      `--user-data-dir=${profileDir}`,
+      // Behave like a fresh, unattended browser: no first-run UI, no default-browser
+      // prompt, no restore bubble, and no "Chrome is being controlled" infobar.
+      '--no-first-run',
+      '--no-default-browser-check',
+      '--disable-features=Translate,MediaRouter',
+      '--disable-session-crashed-bubble',
+      '--hide-crash-restore-bubble',
+      ...extraArgs,
+      'about:blank',
+    ]
+    const child = spawn(browser.path, args, { stdio: ['ignore', 'ignore', 'ignore'], windowsHide: false })
+    const portFile = join(profileDir, 'DevToolsActivePort')
+    const deadline = Date.now() + 30_000
+    for (;;) {
+      if (Date.now() > deadline) { child.kill(); return undefined }
+      if (child.exitCode !== null) return undefined
+      if (existsSync(portFile)) {
+        try {
+          const port = readFileSync(portFile, 'utf8').split('\n')[0]?.trim() ?? ''
+          if (port !== '') {
+            const version = await (await fetch(`http://127.0.0.1:${port}/json/version`)).json() as { webSocketDebuggerUrl?: string }
+            if (typeof version.webSocketDebuggerUrl === 'string') {
+              const client = new CdpClient(version.webSocketDebuggerUrl)
+              await client.whenReady()
+              return new SystemBrowserViewHost(child, client, browser.kind, ephemeralDir)
+            }
+          }
+        } catch {
+          // The file can exist a moment before the port answers; poll again.
+        }
+      }
+      await new Promise(resolve => setTimeout(resolve, 250))
+    }
+  }
+
+  /** Whether this host can back views: the CDP connection is live. */
+  available(): boolean {
+    return !this.disposed
+  }
+
+  createView(): ElectronViewHandle {
+    const viewId = randomUUID()
+    return {
+      id: viewId,
+      sendCommand: async (method: string, params?: Record<string, unknown>) => {
+        const session = this.views.get(viewId) ?? await this.ensureSession(viewId)
+        const result = await this.client.send(method, params, session)
+        return (result ?? {}) as Record<string, unknown>
+      },
+    }
+  }
+
+  destroyView(handle: ElectronViewHandle): void {
+    const session = this.views.get(handle.id)
+    this.views.delete(handle.id)
+    if (session === undefined) return
+    // A session id is not a target id: closing the page needs the target the session
+    // was attached to, which is why they are tracked separately.
+    const targetId = this.sessions.get(session)
+    this.sessions.delete(session)
+    if (targetId !== undefined) {
+      // Best-effort: a page that is already gone is not an error.
+      void this.client.send('Target.closeTarget', { targetId }).catch(() => undefined)
+    }
+  }
+
+  /** Nothing to show: the browser owns its own windows. */
+  showView(): void {}
+
+  /** Same as {@link showView}. */
+  async presentView(): Promise<void> {}
+
+  /** The browser owns window grouping. */
+  groupView(): void {}
+
+  /**
+   * Bring the browser's window forward.
+   *
+   * The browser is a separate application, so there is no view to raise; focusing
+   * the process is the closest honest equivalent, and failing to do so (a minimized
+   * window, a locked session) is never worth an error.
+   */
+  async focus(): Promise<void> {
+    try { this.child.kill('SIGCONT') } catch { /* not supported on Windows; harmless */ }
+  }
+
+  /** The browser reports its own window lifecycle. */
+  onUserAction(): void {}
+
+  /** The browser reports its own window lifecycle. */
+  onViewClosed(): void {}
+
+  /** Close the browser we launched. The user's own windows are a different process. */
+  dispose(): void {
+    if (this.disposed) return
+    this.disposed = true
+    this.views.clear()
+    this.sessions.clear()
+    this.client.close()
+    try { this.child.kill() } catch { /* already gone */ }
+    const ephemeral = this.ephemeralDir
+    if (ephemeral !== undefined) {
+      // The browser flushes its profile while shutting down, so deleting later avoids
+      // racing it. Leftovers are only a stray temp directory, never a live credential.
+      setTimeout(() => { try { rmSync(ephemeral, { recursive: true, force: true }) } catch { /* best effort */ } }, 3_000).unref?.()
+    }
+  }
+
+  /** The flattened session for a view, creating its page on first use. */
+  private async ensureSession(viewId: string): Promise<string> {
+    const existing = this.views.get(viewId)
+    if (existing !== undefined) return existing
+    const created = await this.client.send('Target.createTarget', { url: 'about:blank' }) as { targetId?: string }
+    const targetId = created?.targetId
+    if (typeof targetId !== 'string') throw new Error('dsh-builtin-browser: the browser did not create a page')
+    const attached = await this.client.send('Target.attachToTarget', { targetId, flatten: true }) as { sessionId?: string }
+    const sessionId = attached?.sessionId
+    if (typeof sessionId !== 'string') throw new Error('dsh-builtin-browser: the browser did not attach to the new page')
+    // The session id is what page commands ride; the target id is what closes it.
+    this.sessions.set(sessionId, targetId)
+    this.views.set(viewId, sessionId)
+    return sessionId
+  }
+
+  /** sessionId -> targetId, so a destroyed view can close the right page. */
+  private readonly sessions = new Map<string, string>()
+}