dsh-builtin-browser 0.2.0 → 0.3.1

package/lib/tool-browser/index.js

@@ -122,9 +122,20 @@ function parseFillValue(v) {
         return Number(v);
     return v ?? '';
 }
-/** Format a snapshot element list for the model. */
-function formatSnapshot(snapshot) {
-    const lines = snapshot.elements.map(el => `[${el.ref}] ${el.kind}: ${el.label}${el.frame === true ? ' (iframe)' : ''} (${el.x},${el.y})`);
+/**
+ * Format a snapshot element list for the model.
+ *
+ * Coordinates are opt-in. They are only meaningful to a caller that intends to
+ * click a pixel position, which means a vision pass; for the far more common case
+ * of locating an element by role/label and passing a semantic target, they are the
+ * bulkiest and least useful part of every line. Omitting them keeps the listing
+ * readable — which is exactly what a model without image input has to work from.
+ * @param snapshot - the snapshot payload.
+ * @param options - `coords: true` to include each element's viewport position.
+ */
+function formatSnapshot(snapshot, options = {}) {
+    const showCoords = options.coords === true;
+    const lines = snapshot.elements.map(el => `[${el.ref}] ${el.kind}: ${el.label}${el.frame === true ? ' (iframe)' : ''}${showCoords ? ` (${el.x},${el.y})` : ''}`);
     const header = `URL: ${snapshot.url}${snapshot.title !== undefined ? `\nTitle: ${snapshot.title}` : ''}`;
     const body = lines.length > 0 ? lines.join('\n') : '(no interactive elements found)';
     const tail = snapshot.truncated === true ? '\n(snapshot truncated)' : '';
@@ -193,7 +204,10 @@ export function apply(ctx, config = {}) {
                     },
                 },
             },
-            render: (_args, value) => [{ type: 'text', text: formatSnapshot(value) }],
+            // browser_open is an overview of what just loaded, not a locator: it has no
+            // `coords` parameter, so coordinates stay off here (browser_snapshot owns
+            // that switch for callers that actually target pixels).
+            render: (args, value) => [{ type: 'text', text: formatSnapshot(value, { coords: args.coords === true }) }],
         },
         timeoutMs,
         isConcurrencySafe: () => false, // opens tabs / navigates; exclusive within a task
@@ -219,8 +233,10 @@ export function apply(ctx, config = {}) {
     }));
     ctx.tools.register(defineTool({
         name: 'browser_snapshot',
-        description: 'Return an AI-friendly snapshot of the current shared-browser page: numbered interactive elements (inputs, buttons, links) the model can cite. Use this to understand an interactive page before driving it.',
-        parameters: {},
+        description: 'Return an AI-friendly snapshot of the current shared-browser page: numbered interactive elements (inputs, buttons, links) the model can cite. This is the primary way to understand a page, and it needs no image input — every listed element can afterwards be addressed by a semantic target (browser_click, browser_type, browser_check, …) rather than by coordinates.',
+        parameters: {
+            coords: { type: 'boolean', description: 'Also print each element\'s viewport coordinates. Off by default; only useful when a vision pass is going to click a pixel position.' },
+        },
         output: {
             schema: {
                 type: 'object',
@@ -256,7 +272,7 @@ export function apply(ctx, config = {}) {
                     },
                 },
             },
-            render: (_args, value) => [{ type: 'text', text: formatSnapshot(value) }],
+            render: (args, value) => [{ type: 'text', text: formatSnapshot(value, { coords: args.coords === true }) }],
         },
         timeoutMs,
         isConcurrencySafe: () => true,
@@ -281,6 +297,7 @@ export function apply(ctx, config = {}) {
         parameters: {
             includeHidden: { type: 'boolean', description: 'Include hidden elements (default false).' },
             maxNodes: { type: 'number', description: 'Maximum nodes (default 500, range 10-5000).' },
+            coords: { type: 'boolean', description: 'Include each element\'s viewport coordinates. Off by default: a semantic target needs no coordinates, and they are pure noise unless a vision pass is going to click a pixel position.' },
         },
         output: {
             schema: {
@@ -313,14 +330,24 @@ export function apply(ctx, config = {}) {
                     },
                 },
             },
-            render: (_args, value) => {
+            render: (args, value) => {
                 const nodes = value.nodes;
+                // Built for reading, not for imaging: containment is shown as indentation
+                // (the depth was already collected and simply thrown away), an empty state
+                // list adds nothing, and coordinates appear only when asked for — a model
+                // working from the DOM never needs them, and they are the bulkiest part of
+                // every line.
+                const showCoords = args.coords === true;
                 const lines = nodes.map(n => {
                     const valuePart = n.value !== undefined && n.value !== null ? ` value="${String(n.value).slice(0, 60)}"` : '';
-                    return `[${n.ref}] ${n.role} "${n.name}"${valuePart} (${n.x},${n.y}) states=[${n.states.join(',')}]${n.frame === true ? ' (iframe)' : ''}`;
+                    const indent = '  '.repeat(Math.max(0, Math.min(8, Number(n.depth) || 0)));
+                    const coordsPart = showCoords ? ` (${n.x},${n.y})` : '';
+                    const statePart = Array.isArray(n.states) && n.states.length > 0 ? ` states=[${n.states.join(',')}]` : '';
+                    return `${indent}[${n.ref}] ${n.role} "${n.name}"${valuePart}${coordsPart}${statePart}${n.frame === true ? ' (iframe)' : ''}`;
                 });
                 const header = `URL: ${value.url}${value.title !== undefined ? `\nTitle: ${value.title}` : ''}`;
-                return [{ type: 'text', text: `${header}\n\n${lines.length > 0 ? lines.join('\n') : '(no accessible interactive nodes)'}${value.truncated === true ? '\n(truncated)' : ''}` }];
+                const hint = showCoords ? '' : '\n(coordinates omitted — pass coords: true to include them, or click by semantic target)';
+                return [{ type: 'text', text: `${header}\n\n${lines.length > 0 ? lines.join('\n') : '(no accessible interactive nodes)'}${value.truncated === true ? '\n(truncated)' : ''}${hint}` }];
             },
         },
         timeoutMs,
@@ -553,7 +580,7 @@ export function apply(ctx, config = {}) {
     }));
     ctx.tools.register(defineTool({
         name: 'browser_click',
-        description: 'Click in the shared browser. Two ways: (1) semantic target — pass target {by: css|text|xpath, value, index?} and the element is located, scrolled into view and clicked at its center; (2) viewport coordinates (x/y) — use with browser_screenshot when a vision model locates an element on the screenshot (covers icons, image buttons, and canvas that DOM locators cannot target). Provide exactly one of target or x/y.',
+        description: 'Click in the shared browser. Prefer the semantic target: pass target {by: css|text|xpath, value, index?} and the element is located from the DOM, scrolled into view and clicked at its centre — this needs no image input and is the only form that works without vision. The alternative is viewport coordinates (x/y), which are meaningful only after a vision model has located the element on a browser_screenshot; coordinate clicks are refused outright under the non-visual strategy. Provide exactly one of target or x/y.',
         parameters: {
             target: {
                 type: 'object',
@@ -565,8 +592,8 @@ export function apply(ctx, config = {}) {
                 },
                 description: 'Locate the element semantically and click it (css/text/xpath).',
             },
-            x: { type: 'number', description: 'Viewport x coordinate (CSS px), e.g. from a vision model reading the screenshot.' },
-            y: { type: 'number', description: 'Viewport y coordinate (CSS px).' },
+            x: { type: 'number', description: 'Viewport x coordinate (CSS px), taken from a browser_screenshot read by a vision model. Prefer a semantic target — it works without image input.' },
+            y: { type: 'number', description: 'Viewport y coordinate (CSS px), taken from the same screenshot as x.' },
         },
         output: {
             schema: { type: 'object', additionalProperties: false, properties: { clicked: { type: 'boolean', required: true } } },
@@ -1044,7 +1071,7 @@ export function apply(ctx, config = {}) {
     }));
     ctx.tools.register(defineTool({
         name: 'browser_screenshot',
-        description: 'Capture the current shared-browser page as a screenshot (PNG default, JPEG optional). Use for visual confirmation of layout, charts, designs, or CAPTCHAs, or to feed a vision tool (read_image) that locates elements visually. Supports full-page capture, save-to-file, JPEG encoding, and downscaling (maxWidth/maxHeight) to cut vision-tool token cost. JPEG is only available on the self-hosted native path; the desktop-shell path returns PNG.',
+        description: 'Capture the current shared-browser page as a screenshot (PNG default, JPEG optional). This is for models that can read images: layout checks, charts, designs, CAPTCHAs, or locating an element by eye before clicking its coordinates. A model without image input gains nothing from it — browser_snapshot, browser_a11y and browser_content carry the same page as text, and browser_scrape extracts structured data. Supports full-page capture, save-to-file, JPEG encoding, and downscaling (maxWidth/maxHeight) to cut vision-tool token cost. JPEG is only available on the self-hosted native path; the desktop-shell path returns PNG.',
         parameters: {
             fullPage: { type: 'boolean', description: 'Capture the full scrollable page instead of the viewport (default false).' },
             savePath: { type: 'string', description: 'Absolute file path to also save the image to (e.g. for read_image vision location). Must resolve inside the configured downloadDir (default: the system Downloads folder, localized names such as ~/下载 included); an existing file is never overwritten.' },
@@ -1296,6 +1323,8 @@ export function apply(ctx, config = {}) {
         parameters: {
             limit: { type: 'number', description: 'Maximum entries to return (default 30, capped at 200).' },
             domain: { type: 'string', description: 'Only visits whose hostname contains this text (case-insensitive).' },
+            query: { type: 'string', description: 'Only visits whose URL or title contains this text (case-insensitive).' },
+            session: { type: 'string', description: 'Only visits recorded by this task/session label — use it to separate your own pages from another session\'s or the human\'s.' },
         },
         output: {
             schema: {
@@ -1343,7 +1372,14 @@ export function apply(ctx, config = {}) {
             const rawLimit = typeof args.limit === 'number' && Number.isFinite(args.limit) ? args.limit : 30;
             const limit = Math.max(1, Math.min(200, Math.floor(rawLimit)));
             const domain = typeof args.domain === 'string' && args.domain.trim() !== '' ? args.domain.trim() : undefined;
-            const entries = browser.visited({ limit, ...domain !== undefined ? { domain } : {} });
+            const query = typeof args.query === 'string' && args.query.trim() !== '' ? args.query.trim() : undefined;
+            const session = typeof args.session === 'string' && args.session.trim() !== '' ? args.session.trim() : undefined;
+            const entries = browser.visited({
+                limit,
+                ...domain !== undefined ? { domain } : {},
+                ...query !== undefined ? { query } : {},
+                ...session !== undefined ? { session } : {},
+            });
             return {
                 count: entries.length,
                 entries: entries.map(entry => ({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-builtin-browser",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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
+  }
+}