dsh-builtin-browser 0.4.6 → 0.4.7

package/src/browser-electron/provider.ts

@@ -217,6 +217,17 @@ export interface ElectronBrowserViewHost {
    *   which is only correct from a teardown that is itself global.
    */
   releasePage?(owner?: string): Promise<void>
+  /**
+   * Report that this carrier can no longer serve anything, so its owner may replace it.
+   *
+   * A carrier that borrows an outside process can lose it: the desktop shell exits, and every call
+   * after that would dial a port nobody owns. Without this signal the swap happens only at
+   * startup, so the choice made then is final for the process's life — which is what a user
+   * experiences as "the browser stopped working until I restart DSH". Optional: a carrier that
+   * owns its own lifetime has nothing to report.
+   * @param listener - called once, when the carrier concludes it is gone.
+   */
+  onLost?(listener: () => void): void
   /**
    * Fold the carrier's presentation away while keeping the page alive.
    *
@@ -312,10 +323,21 @@ export interface ElectronViewHandle {
   capture?(opts?: ScreenshotOptions): Promise<{ base64: string; mime: string; width?: number; height?: number }>
 }
 
-/** One tab inside a session: its view plus a stable id. */
+/**
+ * One tab inside a session: its view, a stable id, and the last URL this provider accepted.
+ *
+ * `url` does two jobs. It separates "never navigated" from "navigated, but the URL could not be
+ * read" — the two used to collapse into the same empty string — and it lets `listTabs` skip
+ * probing a tab it already knows is blank, where a probe is a round trip on an uncommitted view
+ * that can only answer nothing.
+ *
+ * `handle` is deliberately NOT readonly: a view that has wedged is replaced in place, and the tab
+ * keeps its public id across that replacement (see `replaceTabWithBlank`).
+ */
 interface Tab {
   readonly id: string
-  readonly handle: ElectronViewHandle
+  handle: ElectronViewHandle
+  url: string
 }
 
 /** One live browser session: an ordered list of tabs, one active. */
@@ -717,7 +739,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
     // session), carrying the label for the window title. Hosts without
     // groupView keep the shared-window behavior.
     this.host.groupView?.(handle, id, label)
-    this.sessions.set(id, { id, label, tabs: [{ id: `tab:${randomUUID()}`, handle }], activeIndex: 0, history: [], nextSeq: 1 })
+    this.sessions.set(id, { id, label, tabs: [{ id: `tab:${randomUUID()}`, handle, url: '' }], activeIndex: 0, history: [], nextSeq: 1 })
     return Promise.resolve(id)
   }
 
@@ -737,9 +759,15 @@ export class ElectronBrowserProvider implements BrowserProvider {
     for (let i = 0; i < s.tabs.length; i++) {
       const tab = s.tabs[i]
       if (tab === undefined) continue // defensive: array can shift under concurrency
+      // A tab we know has never navigated is NOT probed: its view has committed no document, so
+      // the round trip can only answer nothing — and it is the round trip that costs. A tab that
+      // HAS navigated is re-read, because the page may have moved itself since; a read that fails
+      // keeps the last accepted URL rather than reporting the tab as blank.
+      const liveUrl = tab.url === '' ? '' : await this.currentUrl(tab.handle).catch(() => tab.url)
+      if (liveUrl !== '') tab.url = liveUrl
       result.push({
         id: tab.id,
-        url: await this.currentUrl(tab.handle).catch(() => ''),
+        url: liveUrl,
         active: i === s.activeIndex,
       })
     }
@@ -825,7 +853,8 @@ export class ElectronBrowserProvider implements BrowserProvider {
   /** Navigate the active tab's view to a URL, honoring HTTP(S)-only admission. */
   async navigate(session: BrowserSessionId, request: { readonly url: string }, signal?: AbortSignal): Promise<void> {
     const s = this.session(session)
-    const { handle } = this.activeTab(s)
+    const tab = this.activeTab(s)
+    const { handle } = tab
     const url = request.url
     try {
       if (this.httpOnly) {
@@ -870,6 +899,11 @@ export class ElectronBrowserProvider implements BrowserProvider {
       // the visit written to the persistent history for a navigation nobody awaits any more.
       signal?.throwIfAborted()
       this.record(s, 'navigate', { url }, true)
+      // The tab now holds a committed document, which is what the blank short-circuit in
+      // `snapshot`/`a11y` keys on. Recorded here rather than after the settle below: the
+      // navigation HAS committed, and a tab wrongly treated as blank would return empty results
+      // for a page that is really there.
+      tab.url = url
       await this.settleDocument(handle, before, signal)
       this.recordVisit(s, handle)
       this.showActive(s)
@@ -1205,6 +1239,10 @@ export class ElectronBrowserProvider implements BrowserProvider {
     const s = this.session(session)
     const tab = this.activeTab(s)
     signal?.throwIfAborted()
+    // A tab that has never navigated is a blank, uncommitted view. The collector cannot answer in
+    // it — there is no document to commit — so the call would sit out its whole budget before
+    // saying anything. Answering the empty page immediately is both faster and more truthful.
+    if (tab.url === '') return { url: '', elements: [], truncated: false }
     const script = `(() => {
       const cap = ${String(this.snapshotMaxElements)}
       const url = location.href
@@ -1277,13 +1315,31 @@ export class ElectronBrowserProvider implements BrowserProvider {
     // Same hang guard as execute: a renderer that has not committed after
     // navigate would otherwise block snapshot forever.
     const timeoutMs = 30_000
-    const result = await withTimeout(
-      handleSendEvaluate(tab.handle, script),
-      timeoutMs,
-      signal,
-      `browser: snapshot timed out after ${timeoutMs}ms`,
-      () => terminatePage(tab.handle),
-    )
+    let result: { ok: true; value: unknown } | { ok: false; exception: string }
+    try {
+      result = await withTimeout(
+        handleSendEvaluate(tab.handle, script),
+        timeoutMs,
+        signal,
+        `browser: snapshot timed out after ${timeoutMs}ms`,
+        () => terminatePage(tab.handle),
+      ) as { ok: true; value: unknown } | { ok: false; exception: string }
+    } catch (error) {
+      // A timeout leaves the wedged view in the session, so every later read would pay the same
+      // 30 seconds again — and `terminatePage` only interrupts the running script, it does not
+      // make the view readable. Replacing it is what turns a permanent loss into one bad call:
+      // the tab keeps the id the caller holds, and the next browser_open with the real URL
+      // repopulates it.
+      if (error instanceof Error && error.name === 'TimeoutError') {
+        this.replaceTabWithBlank(s, tab)
+        throw new BrowserError(
+          'browser: snapshot timed out; the stuck tab was reset to blank. Call browser_open with the real target URL before reading it again.',
+          'BROWSER_SNAPSHOT_TIMEOUT',
+          { cause: error },
+        )
+      }
+      throw error
+    }
     if (!result.ok) throw new BrowserError(`browser: snapshot evaluation failed: ${result.exception}`, 'BROWSER_SNAPSHOT_FAILED')
     const value = result.value as BrowserSnapshotResult
     return value
@@ -1301,6 +1357,9 @@ export class ElectronBrowserProvider implements BrowserProvider {
     const s = this.session(session)
     const tab = this.activeTab(s)
     signal?.throwIfAborted()
+    // Same short-circuit as `snapshot`: a tab that never navigated has no committed document, so
+    // the tree cannot be read and the call would spend its whole budget discovering that.
+    if (tab.url === '') return { url: '', title: undefined, count: 0, nodes: [], truncated: false }
     const includeHidden = request.includeHidden === true
     // 150 rather than 500. The cap fills on any real page, and 500 nodes measured 38,953
       // characters — 10k-13k tokens for a single call. A caller that needs more asks for it.
@@ -1462,13 +1521,28 @@ export class ElectronBrowserProvider implements BrowserProvider {
       return { url: location.href, title: document.title || undefined, count: out.length, nodes: out, truncated: out.length >= maxNodes }
     })()`
     const timeoutMs = 30_000
-    const result = await withTimeout(
-      handleSendEvaluate(tab.handle, script),
-      timeoutMs,
-      signal,
-      `browser: a11y timed out after ${timeoutMs}ms`,
-      () => terminatePage(tab.handle),
-    )
+    let result: { ok: true; value: unknown } | { ok: false; exception: string }
+    try {
+      result = await withTimeout(
+        handleSendEvaluate(tab.handle, script),
+        timeoutMs,
+        signal,
+        `browser: a11y timed out after ${timeoutMs}ms`,
+        () => terminatePage(tab.handle),
+      ) as { ok: true; value: unknown } | { ok: false; exception: string }
+    } catch (error) {
+      // As in `snapshot`: a timeout means the view is wedged, and leaving it in the session would
+      // charge every later read the same 30 seconds. Replaced in place, so the tab id survives.
+      if (error instanceof Error && error.name === 'TimeoutError') {
+        this.replaceTabWithBlank(s, tab)
+        throw new BrowserError(
+          'browser: a11y timed out; the stuck tab was reset to blank. Call browser_open with the real target URL before reading it again.',
+          'BROWSER_A11Y_TIMEOUT',
+          { cause: error },
+        )
+      }
+      throw error
+    }
     if (!result.ok) throw new BrowserError(`browser: a11y evaluation failed: ${result.exception}`, 'BROWSER_A11Y_FAILED')
     const value = result.value as BrowserA11yResult
     this.record(s, 'a11y', { includeHidden, maxNodes }, true, { result: `${value.count} nodes` })
@@ -3116,11 +3190,41 @@ export class ElectronBrowserProvider implements BrowserProvider {
     const handle = this.host.createView(s.label)
     // Same window as the session's other tabs.
     this.host.groupView?.(handle, s.id, s.label)
-    s.tabs.push({ id: `tab:${randomUUID()}`, handle })
+    s.tabs.push({ id: `tab:${randomUUID()}`, handle, url: '' })
     s.activeIndex = s.tabs.length - 1
     this.showActive(s)
   }
 
+  /**
+   * Swap a wedged view for a fresh blank one, keeping the tab's public id.
+   *
+   * A view whose renderer never commits cannot be read again: every evaluate into it runs out its
+   * whole budget. Replacing it is what turns that from permanent into one bad call — the tab id
+   * callers hold stays valid, and the next `browser_open` with the real URL re-populates it.
+   *
+   * The old view is destroyed AFTER the new one is in place, so a failure here cannot leave the
+   * session holding a handle that is already gone.
+   * @param s - the session owning the tab.
+   * @param tab - the tab to reset.
+   */
+  private replaceTabWithBlank(s: Session, tab: Tab): void {
+    const index = s.tabs.indexOf(tab)
+    if (index < 0) return
+    let handle: ElectronViewHandle
+    try {
+      handle = this.host.createView(s.label)
+      this.host.groupView?.(handle, s.id, s.label)
+    } catch {
+      // Creating the replacement failed: leaving the wedged tab in place is worse than nothing
+      // only for the caller, who is about to be told the tab timed out either way.
+      return
+    }
+    const wedged = tab.handle
+    s.tabs[index] = { id: tab.id, handle, url: '' }
+    if (index === s.activeIndex) this.showActive(s)
+    this.host.destroyView(wedged)
+  }
+
   /** Find a session's tab by its backing view id (toolbar actions carry view ids). */
   private tabByViewId(s: Session, viewId: string): Tab | undefined {
     return s.tabs.find(tab => tab.handle.id === viewId)

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

@@ -129,16 +129,35 @@ const SETTINGS_WHEN_UNREADABLE: BrowserSettings = {
   actions: { allowExecute: false, allowDownload: false, allowCredentialWrite: false },
 }
 
+/**
+ * The channels a settings document may name.
+ *
+ * Exported so the log line and the error message can quote the same set the parser accepts: a
+ * message that lists a value the code rejects (or omits one it takes) is worse than no message.
+ */
+export const BROWSER_CHANNELS = ['chrome', 'edge', 'auto', 'bundled', 'sidebar'] as const
+
 /**
  * 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.
+ *
+ * Coercing is right; coercing QUIETLY is not. A typo and "the setting did nothing" look exactly
+ * the same to whoever typed it, which is why every discarded value is reported.
  * @param value - the raw value from the settings document.
+ * @param warn - where to report a discarded value, when the caller has somewhere to put it.
  * @returns a valid channel.
  */
-function resolveChannel(value: unknown): BrowserChannel {
-  return value === 'chrome' || value === 'edge' || value === 'auto' || value === 'bundled' || value === 'sidebar'
-    ? value
-    : DEFAULT_SETTINGS.browser.channel
+function resolveChannel(value: unknown, warn?: (message: string) => void): BrowserChannel {
+  // Absent is the ordinary case, not a mistake: a document that never mentioned the channel gets
+  // the default without a word.
+  if (value === undefined) return DEFAULT_SETTINGS.browser.channel
+  if ((BROWSER_CHANNELS as readonly unknown[]).includes(value)) return value as BrowserChannel
+  warn?.(
+    `dsh-builtin-browser: browser.channel ${JSON.stringify(value)} is not a known channel, so the `
+    + `default "${DEFAULT_SETTINGS.browser.channel}" was used instead. Expected one of: `
+    + `${BROWSER_CHANNELS.join(', ')}.`,
+  )
+  return DEFAULT_SETTINGS.browser.channel
 }
 
 /** Coerce one positive-integer field, keeping the default when invalid. */
@@ -181,7 +200,7 @@ function section(source: Record<string, unknown>, key: string): Record<string, u
  * @param raw - the parsed file contents.
  * @returns the resolved settings.
  */
-export function resolveSettings(raw: unknown): BrowserSettings {
+export function resolveSettings(raw: unknown, warn?: (message: string) => void): BrowserSettings {
   const source = typeof raw === 'object' && raw !== null ? raw as Record<string, unknown> : {}
   const history = section(source, 'history')
   const cookies = section(source, 'cookies')
@@ -208,7 +227,7 @@ export function resolveSettings(raw: unknown): BrowserSettings {
       virtualCursor: bool(ui?.virtualCursor, DEFAULT_SETTINGS.ui.virtualCursor),
     },
     vision: { strategy: vision?.strategy === 'nonVisual' ? 'nonVisual' : DEFAULT_SETTINGS.vision.strategy },
-    browser: { channel: resolveChannel(browser?.channel) },
+    browser: { channel: resolveChannel(browser?.channel, warn) },
     credentials: {
       // `gate` returns false for anything present-and-not-a-boolean, so an unreadable section
       // is refused here for free: the section itself is the "present but wrong" value.
@@ -244,7 +263,7 @@ export class SettingsStore {
   /**
    * @param file - settings file path (defaults beside the browser profile).
    */
-  constructor(private readonly file: string = settingsPath()) {}
+  constructor(private readonly file: string = settingsPath(), private readonly log?: (message: string) => void) {}
 
   /** Path this store reads and writes. */
   path(): string {
@@ -291,7 +310,7 @@ export class SettingsStore {
       // 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))
+      this.cached = body === undefined ? DEFAULT_SETTINGS : resolveSettings(JSON.parse(body), m => this.log?.(m))
     } catch {
       // A document that EXISTS but cannot be parsed is not the same as no document at all: the
       // first is a corrupted or half-written file whose contents were the operator's decisions,
@@ -311,7 +330,7 @@ export class SettingsStore {
    */
   update(patch: unknown): BrowserSettings {
     const current = this.get()
-    const merged = resolveSettings(deepMerge(current as unknown as Record<string, unknown>, patch))
+    const merged = resolveSettings(deepMerge(current as unknown as Record<string, unknown>, patch), m => this.log?.(m))
     try {
       mkdirSync(dirname(this.file), { recursive: true })
       writeFileAtomic(this.file, `${JSON.stringify(merged, null, 2)}\n`)

package/src/tool-browser/index.ts

@@ -146,6 +146,38 @@ function agentOf(exec: unknown): ExecAgent | undefined {
   return (exec as { agent?: ExecAgent } | undefined)?.agent
 }
 
+/**
+ * Refuse the bare DSH web root, which answers 401 and looks like a real page.
+ *
+ * The address comes from `DSH_WEB_URL`, which the harness exports to its children — NOT from a
+ * hardcoded port. This machine's GUI has run on 3080 and on 19387, so a number would stop matching
+ * exactly when the guard is needed, and the trap is not a port anyway: it is the SHAPE. A loopback
+ * address at its root with no token renders as an unauthenticated 401 page, which an agent reads
+ * as the site it meant to open.
+ * @param rawUrl - the address a caller asked to open.
+ */
+function assertNotBareDshWebUrl(rawUrl: string): void {
+  const advertised = process.env.DSH_WEB_URL
+  if (typeof advertised !== 'string' || advertised === '') return
+  let target: URL
+  let dsh: URL
+  try {
+    target = new URL(rawUrl)
+    dsh = new URL(advertised)
+  } catch {
+    return // not a URL this guard can judge; the provider's own admission is the next gate
+  }
+  if (target.origin !== dsh.origin) return
+  if (target.pathname !== '/') return
+  // The authenticated URL printed by `dsh web` carries a token; the bare root does not.
+  if (target.searchParams.has('token')) return
+  throw new Error(
+    'browser_open: refusing the bare DSH web root (' + dsh.origin + '/) because it carries no '
+    + 'authentication token, so it answers with a 401 page that reads like a real site. Open the '
+    + 'target site instead; to open DSH itself, use the authenticated URL printed by `dsh web`.',
+  )
+}
+
 /**
  * Read a target's `index`, refusing the values that cannot mean anything.
  *
@@ -319,7 +351,7 @@ export function apply(ctx: Context, config: Config = {}): void {
 
   ctx.tools.register(defineTool({
     name: 'browser_open',
-    description: 'Open a URL in the shared browser window. Opens this task\'s browser session on first use; optionally opens in a new tab. Returns the resulting page snapshot.',
+    description: 'Open a URL in the shared browser window. Opens this task\'s browser session on first use; optionally opens in a new tab. Returns the resulting page snapshot. A fresh session starts on a blank, uncommitted tab: call this with the REAL target URL before reading, because reading that tab returns an empty page instead of waiting. Never treat the bare DSH host (e.g. http://127.0.0.1:3080/) as the target website — it requires the authenticated URL printed by `dsh web`, and the bare root is refused outright.',
     parameters: {
       url: { type: 'string', required: true, description: 'The URL to open (HTTP/HTTPS).' },
       newTab: { type: 'boolean', description: 'Open in a new tab instead of the active one.' },
@@ -358,6 +390,7 @@ export function apply(ctx: Context, config: Config = {}): void {
     isConcurrencySafe: () => false, // opens tabs / navigates; exclusive within a task
     async execute(args, exec) {
       assertAllowed(state, 'browser_open', taskKey(exec))
+      assertNotBareDshWebUrl(args.url)
       const browser = ctx.get('browser')
       if (browser === undefined) throw new Error('tool-browser: browser service unavailable')
       const session = await ensureSession(browser, state, taskKey(exec), agentOf(exec))