dsh-builtin-browser 0.4.1 → 0.4.5

package/scripts/verify-host-compat.mjs

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+/**
+ * Host-compatibility probe: does THIS build of the plugin run on the DSH in front of it?
+ *
+ * A version range in package.json is a claim, not evidence. This assembles a host out of the
+ * real DSH packages installed in a profile, loads the plugin's compiled output, registers its
+ * tools through the host's own `defineTool`, and calls two of them over the plugin's provider
+ * seam. It is the check that answers "did DSH 0.2.x break us?" without booting a browser.
+ *
+ * Usage:
+ *   node scripts/verify-host-compat.mjs                 # probe the profile named by DSH_PROFILE
+ *   DSH_PROFILE=desktop node scripts/verify-host-compat.mjs
+ *   DSH_HOME=/path/to/.dsh node scripts/verify-host-compat.mjs
+ *
+ * Resolution: the profile's own package.json is the module root, so `@deepseek-ai/*` resolves
+ * exactly as it does at runtime (links included). With no usable profile the probe reports
+ * that it could not run and exits 0 — an unprobeable host is not a compatibility failure, and
+ * making CI red for it would be reporting the wrong thing.
+ *
+ * What it does NOT cover: the browser actually launching (no Electron here), and the client
+ * panel rendering in a real session.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+const REPO = new URL('..', import.meta.url)
+const failures = []
+
+const ok = (label, condition, detail = '') => {
+  console.log(`  ${condition ? 'OK  ' : 'FAIL'}  ${label}${detail === '' ? '' : `  — ${detail}`}`)
+  if (!condition) failures.push(label)
+}
+
+/** The profile whose node_modules resolve the host packages, or undefined. */
+function findProfileRoot() {
+  const home = process.env.DSH_HOME ?? join(process.env.USERPROFILE ?? process.env.HOME ?? '', '.dsh')
+  const profiles = join(home, 'profiles')
+  if (!existsSync(profiles)) return undefined
+  const named = process.env.DSH_PROFILE
+  const candidates = named !== undefined && named !== ''
+    ? [named]
+    : readdirSync(profiles).filter(entry => existsSync(join(profiles, entry, 'package.json')))
+  for (const candidate of candidates) {
+    const manifest = join(profiles, candidate, 'package.json')
+    if (existsSync(manifest)) return { name: candidate, manifest }
+  }
+  return undefined
+}
+
+const profile = findProfileRoot()
+if (profile === undefined) {
+  console.log('No DSH profile found (looked under $DSH_HOME/profiles).')
+  console.log('Set DSH_HOME or DSH_PROFILE to point at one; nothing to verify.')
+  process.exit(0)
+}
+
+const require = createRequire(profile.manifest)
+const load = async (spec) => import(pathToFileURL(require.resolve(spec)).href)
+
+console.log(`Host: profile "${profile.name}" at ${profile.manifest}`)
+let hostVersion = 'unknown'
+try {
+  hostVersion = JSON.parse(readFileSync(require.resolve('@deepseek-ai/dsh-system-prompt/package.json'), 'utf8')).version
+} catch { /* reported as unknown; the probe below is what matters */ }
+console.log(`      @deepseek-ai/dsh-system-prompt = ${hostVersion}`)
+console.log('')
+
+console.log('=== 1. the host API surface this plugin imports ===')
+let cordis
+let dshTools
+let dshLlm
+let schemastery
+try {
+  cordis = await load('@deepseek-ai/cordis')
+  dshTools = await load('@deepseek-ai/dsh-tools')
+  dshLlm = await load('@deepseek-ai/dsh-llm')
+  schemastery = await load('@deepseek-ai/schemastery')
+} catch (error) {
+  console.log(`  FAIL  a host package could not be resolved: ${String(error && error.message)}`)
+  process.exit(1)
+}
+const z = schemastery.default ?? schemastery
+
+ok('@deepseek-ai/cordis exports Context', typeof cordis.Context === 'function')
+ok('@deepseek-ai/cordis exports Service', typeof cordis.Service === 'function')
+ok('@deepseek-ai/dsh-tools exports defineTool', typeof dshTools.defineTool === 'function')
+ok('@deepseek-ai/dsh-llm exports HarnessError', typeof dshLlm.HarnessError === 'function')
+ok('@deepseek-ai/schemastery default is the schema builder', typeof z?.string === 'function')
+
+console.log('')
+console.log('=== 2. the plugin loads against a real cordis context ===')
+const root = new cordis.Context()
+
+// Stub services. DSH's own tools/systemPrompt implementations are not what is under test and
+// standing them up would mean booting a profile; only their SHAPE matters here, and it is
+// taken from the real ones: `ctx.tools.register(definition)`, `ctx.systemPrompt.section(spec)`.
+const registered = new Map()
+class StubTools extends cordis.Service {
+  constructor(ctx) { super(ctx, 'tools') }
+  register(definition) { registered.set(definition.name, definition); return () => {} }
+}
+class StubSystemPrompt extends cordis.Service {
+  constructor(ctx) { super(ctx, 'systemPrompt'); this.sections = [] }
+  section(spec) { this.sections.push(spec); return () => {} }
+}
+new StubTools(root)
+const prompts = new StubSystemPrompt(root)
+
+try {
+  const runtimeModule = await import(new URL('lib/browser/runtime.js', REPO).href)
+  ok('the plugin ships a browser seam service', typeof runtimeModule.default === 'function')
+  new runtimeModule.default(root)
+  ok('the seam registered itself as ctx.browser', root.get('browser') !== undefined)
+
+  const layer = await import(new URL('lib/tool-browser/index.js', REPO).href)
+  ok('the tool layer exports an apply()', typeof layer.apply === 'function')
+  layer.apply(root, {})
+  ok('tools registered through the host\'s own defineTool', registered.size > 30, `${registered.size} tools`)
+  ok('the system prompt section was declared', prompts.sections.length === 1)
+} catch (error) {
+  ok('the plugin loads and registers', false, String(error && error.stack).split('\n').slice(0, 2).join(' | '))
+}
+
+console.log('')
+console.log('=== 3. the definitions the host will consume ===')
+// `defineTool` already accepted every spec the plugin handed it — it throws on a shape it
+// cannot compile, and the tools came back — so what is left is the stored definition: a JSON
+// Schema the host can show a model, plus the output contract.
+const SCALAR_TYPES = new Set(['string', 'number', 'integer', 'boolean', 'array', 'object', 'null'])
+const schemaFailures = []
+for (const [name, definition] of registered) {
+  if (typeof definition.execute !== 'function') schemaFailures.push(`${name}: no execute`)
+  if (definition.output?.schema === undefined) schemaFailures.push(`${name}: no output.schema`)
+  if (typeof definition.output?.render !== 'function') schemaFailures.push(`${name}: no output.render`)
+  if (typeof definition.description !== 'string' || definition.description === '') schemaFailures.push(`${name}: no description`)
+  const parameters = definition.parameters
+  if (typeof parameters !== 'object' || parameters === null) {
+    schemaFailures.push(`${name}: parameters is not a schema object`)
+    continue
+  }
+  if (parameters.type !== 'object') schemaFailures.push(`${name}: parameters.type is ${String(parameters.type)}`)
+  for (const [field, spec] of Object.entries(parameters.properties ?? {})) {
+    if (typeof spec?.type !== 'string' || !SCALAR_TYPES.has(spec.type)) schemaFailures.push(`${name}.${field}: type ${String(spec?.type)}`)
+  }
+}
+ok('every tool definition carries a usable schema', schemaFailures.length === 0, schemaFailures.slice(0, 4).join(' | '))
+
+console.log('')
+console.log('=== 4. a tool runs, over the plugin\'s own provider seam ===')
+const fakeSession = 'browser:00000000-0000-4000-8000-000000000001'
+try {
+  root.get('browser').registerBrowserProvider({
+    id: 'verify-host-compat',
+    available: () => true,
+    open: async () => fakeSession,
+    listTabs: async () => [{ id: 'tab:1', title: 'verify', url: 'about:blank', active: true }],
+    a11y: async () => ({
+      url: 'about:blank',
+      count: 1,
+      truncated: false,
+      nodes: [{ ref: 1, role: 'button', name: 'Probe', states: ['enabled'], depth: 0, tag: 'button', selector: '#probe', x: 1, y: 2 }],
+    }),
+  })
+} catch (error) {
+  ok('a provider can register on the seam', false, String(error && error.message))
+}
+
+const exec = { agent: { id: 'verify-host-compat' } }
+try {
+  const value = await registered.get('browser_session').execute({}, exec)
+  ok('browser_session ran', value !== undefined, JSON.stringify(value).slice(0, 100))
+} catch (error) {
+  ok('browser_session ran', false, String(error && error.message))
+}
+
+try {
+  const tool = registered.get('browser_a11y')
+  const value = await tool.execute({}, exec)
+  const text = JSON.stringify(tool.output.render({}, value))
+  ok('browser_a11y ran and rendered', value?.nodes?.length === 1, '')
+  ok('its renderer emits the element selector', text.includes('#probe'), text.slice(0, 120))
+} catch (error) {
+  ok('browser_a11y ran', false, String(error && error.message))
+}
+
+console.log('')
+if (failures.length === 0) {
+  console.log(`VERDICT: this build runs on the host above (${hostVersion}).`)
+} else {
+  console.log(`VERDICT: ${failures.length} failure(s) — this build does NOT match the host above:`)
+  for (const failure of failures) console.log(`  - ${failure}`)
+  process.exitCode = 1
+}

package/src/browser/types.ts

@@ -266,6 +266,14 @@ export interface BrowserWaitResult {
 export interface BrowserScreenshotResult {
   /** Base64 data URL of the capture (PNG or JPEG per the request). */
   readonly dataUrl: string
+  /** Pixel size of the image in `dataUrl`, when the capture was measured and scaled.
+   *
+   * Present when the request carried `maxWidth`/`maxHeight` and the layout metrics were
+   * readable: the scaling happens inside CDP through a clip, and without this the only way to
+   * learn what came back was to decode the data URL. Undefined means "not measured", which is
+   * also what an unscaled capture reports. */
+  readonly width?: number
+  readonly height?: number
   /** File path the capture was also saved to, when the request asked for it. */
   readonly path?: string
 }
@@ -388,14 +396,29 @@ export interface BrowserA11yNode {
   readonly role: string
   /** Accessible name (aria-label, label text, placeholder, own text, …). */
   readonly name: string
-  /** Current value of input-like nodes (null when not applicable). */
-  readonly value: string | null
+  /**
+   * Current value of input-like nodes; absent when the node has none.
+   *
+   * The provider produces `null` for "not applicable" and the tool layer drops it, so absence
+   * and null mean the same thing here — which is what the output schema declares (`string`,
+   * not nullable). Saying `string | null` described the provider's internal shape rather than
+   * the contract, and the two disagreed at every call.
+   */
+  readonly value?: string
   /** ARIA/DOM states: enabled/disabled/checked/unchecked/expanded/… */
   readonly states: readonly string[]
   /** DOM depth (within its document), for reconstructing the tree. */
   readonly depth: number
   /** Element tag name (lowercase). */
   readonly tag: string
+  /**
+   * A CSS selector for this node, when one can be derived from its id or name.
+   *
+   * Empty for the many elements that have neither. Present because a role and a name are not
+   * always enough to target a node: `{by: 'text'}` matches an accessible name only loosely,
+   * and this is what lets a caller point at the exact element it was shown.
+   */
+  readonly selector: string
   /** Viewport-relative center, for coordinate fallbacks. */
   readonly x: number
   readonly y: number
@@ -499,7 +522,15 @@ export interface BrowserProvider {
   /**
    * Open a new session. The provider mints the session id and prepares its
    * backing surface (a view, a headless page, and so on). Sessions are isolated from
-   * each other; a session must not be visible to any other session's caller.
+   * each other in what they OWN — tabs, the active tab, history, the view — so one
+   * session must not be visible to any other session's caller.
+   *
+   * That isolation stops at the browser's own state, and is not meant to go further:
+   * cookies, logins and site storage are deliberately shared by every session, because
+   * every session drives the same browser and "sign in once, use it everywhere" is the
+   * point of using a real one. Reads that hand that state to a caller (see
+   * `flushAuth`) are scoped to the page in question, which is least exposure rather
+   * than a claim that the jar is per-session.
    * @param label - optional human-readable label (e.g. the calling DSH task
    * id) the provider may surface on the visible surface (window title) so a
    * human can tell which task's page is currently shown.

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

@@ -1,3 +1,4 @@
+import { readFileSync } from 'node:fs'
 /**
  * Transport for the desktop shell's browser bridge: one long-lived connection to a
  * loopback TCP service.
@@ -34,50 +35,149 @@ interface PendingCall {
   readonly reject: (error: Error) => void
 }
 
+/**
+ * Safety cap on one un-answered reply line. CDP answers from the sidebar (a screenshot's
+ * base64 is the big one) cross this socket, so the cap is generous; what it exists for is a
+ * peer that never sends a newline — `this.buffer += chunk` grew without bound, unlike the
+ * same buffer in remote-host.ts, which caps at 512 MiB.
+ */
+const MAX_BUFFER_BYTES = 128 * 1024 * 1024
+
+/**
+ * Field this client adds to every request so the shell can echo it back and never relies on
+ * byte order to pair an answer with its request. Loosely named, and additive on purpose: a
+ * bridge that does not know it simply ignores it (the current shipped shell does), and the
+ * client then falls back to arrival order, which is what the protocol guaranteed before.
+ */
+const REQUEST_ID_FIELD = 'bridgeRequestId'
+
 /**
  * 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.
+ * Requests may be in flight CONCURRENTLY, so answers are correlated by id rather than by
+ * position: `call()` stamps a unique {@link REQUEST_ID_FIELD} on the request and `onData()`
+ * resolves the entry that carries the echoed id. A bridge that does not echo it is still
+ * supported — its answer is handed to the oldest outstanding request, which is the
+ * arrival-order rule the protocol states. Once such an answer has been seen, the connection
+ * stops keeping two requests in flight (a second one re-dials), so position can never be the
+ * only thing distinguishing two callers' answers. An answer that matches nothing is never
+ * handed to whichever request happens to be first: the socket is dropped instead.
+ *
+ * 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[] = []
+  /** Outstanding requests by id. */
+  private readonly pending = new Map<number, PendingCall>()
+  /** Ids of the requests sent on the current socket, oldest first. */
+  private readonly queue: number[] = []
+  private nextId = 1
+  /** True once any reply arrived without an id: this bridge does not echo request ids. */
+  private idLessBridge = false
+  /** True once this connection may only have one request in flight at a time. */
+  private serialisable = false
 
   /**
    * @param endpoint - the shell's published bridge endpoint.
+   * @param endpointPath - where that endpoint is republished, so a moved port can be followed.
    */
-  constructor(private readonly endpoint: BridgeEndpoint) {}
+  constructor(private endpoint: BridgeEndpoint, private readonly endpointPath?: string) {}
+
+  /**
+   * Re-read the published endpoint, and adopt it if the shell has moved.
+   *
+   * The bridge binds an ephemeral port and picks a NEW one whenever its server is recreated. The
+   * endpoint file is rewritten every fifteen seconds, but a host that adopted the old one keeps
+   * dialling a dead port forever: measured here as `connect ECONNREFUSED 127.0.0.1:52276` while
+   * the live bridge sat on 52411. Discarding the socket is not enough — the comment below says a
+   * dead connection must never become a dead plugin, and a stale PORT makes exactly that happen.
+   *
+   * Cheap and safe: one small file read per call, no socket work.
+   *
+   * @returns true when a different endpoint was adopted.
+   */
+  private refreshEndpoint(): boolean {
+    if (this.endpointPath === undefined) return false
+    try {
+      const raw = JSON.parse(readFileSync(this.endpointPath, 'utf8')) as Partial<BridgeEndpoint>
+      if (typeof raw.port !== 'number' || typeof raw.token !== 'string') return false
+      if (raw.port === this.endpoint.port && raw.token === this.endpoint.token) return false
+      this.endpoint = {
+        port: raw.port,
+        token: raw.token,
+        pid: typeof raw.pid === 'number' ? raw.pid : this.endpoint.pid,
+      }
+      // The old socket belongs to the old port.
+      this.reset(new Error('dsh-builtin-browser: the bridge moved; reconnecting to the new port'))
+      return true
+    } catch {
+      return false
+    }
+  }
 
   /**
    * Send one request, reusing the socket if it is still healthy.
-   * @param request - the request body (the token is added here).
+   *
+   * Requests may overlap: the request is written as soon as it is queued, so two concurrent
+   * callers have two requests in flight. Each carries a unique {@link REQUEST_ID_FIELD}, and
+   * `onData()` resolves the entry that carries the echoed id — which is what makes
+   * correlation independent of arrival order. A bridge that does not echo the field (the
+   * shipped shell today) still works by arrival order; see {@link onData}.
+   * @param request - the request body (the token and the request id are 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()
+    // One re-dial, and only for the case this exists for: a socket that has already carried
+    // an id-less answer cannot have a second request in flight, because two outstanding
+    // requests would be matched by position — the swap this correlation prevents. It is a
+    // straight-line re-dial rather than a retry loop: an earlier revision re-entered call()
+    // from inside its own promise executor, which left an orphaned pending entry behind and,
+    // when the condition could not clear, spun until the process ran out of heap.
+    // Follow the shell if its bridge moved to a new port (see refreshEndpoint).
+    this.refreshEndpoint()
+    let socket = this.ensureSocket()
+    if (this.serialisable && this.queue.length > 0) {
+      this.reset(new Error('dsh-builtin-browser: bridge connection reopened so replies stay attributable'))
+      socket = this.ensureSocket()
+    }
+    const id = this.nextId++
     return await new Promise<Record<string, unknown>>((resolve, reject) => {
+      this.pending.set(id, {
+        resolve: answer => { clearTimeout(timer); resolve(answer) },
+        reject: error => { clearTimeout(timer); reject(error) },
+      })
+      this.queue.push(id)
       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)
+        // An unanswered request desynchronises the stream for an id-less bridge, and leaves one
+        // outstanding for one that echoes ids — either way the next call should start on a
+        // fresh socket. Only when THIS request's socket is still the live one: tearing down the
+        // REPLACEMENT because an abandoned request timed out would break whatever is using it.
+        //
+        // This test used to read `this.pending.has(id) && this.socket === socket`, with
+        // `forget(id)` on the line above it — and forget() is what removes the entry that `has`
+        // was looking for, so the condition was false every single time and the rebuild never
+        // ran. A timed-out call therefore left the desynchronised socket in place, and every
+        // later call inherited exactly the ambiguity this reset exists to clear. Deciding
+        // before forgetting is the whole fix; the `else` still drops the stale entry.
+        if (this.socket === socket) this.reset(error)
+        else this.forget(id)
+        // reset() already rejected this entry through its wrapper when it ran, so this is
+        // either the only rejection or a no-op that guarantees the caller settles.
         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')
+        // The id is added LAST so a request body can never shadow it, and the token is
+        // added here rather than by the caller.
+        socket.write(JSON.stringify({ token: this.endpoint.token, ...request, [REQUEST_ID_FIELD]: id }) + '\n')
       } catch (error) {
         clearTimeout(timer)
-        this.queue.pop()
+        this.forget(id)
         const failure = error instanceof Error ? error : new Error(String(error))
-        this.reset(failure)
+        if (this.socket === socket) this.reset(failure)
         reject(failure)
       }
     })
@@ -94,25 +194,60 @@ export class BridgeConnection {
     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')))
+    // Both handlers pass the socket they belong to, so a late event from a socket that was
+    // already replaced cannot tear down its successor: 'close' still fires for a socket that
+    // was removed mid-recycle, and acting on it there would kill a perfectly good connection.
+    socket.on('error', error => this.socketFailed(socket, error))
+    socket.on('close', () => this.socketFailed(socket, 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. */
+  /** Tear the connection down for an event raised by `source`, unless it is already gone. */
+  private socketFailed(source: Socket, error: Error): void {
+    if (this.socket !== source) return
+    this.reset(error)
+  }
+
+  /** Resolve queued requests by id, or in order when the bridge does not echo one. */
   private onData(chunk: string): void {
     this.buffer += chunk
+    // A peer that never sends a newline must not grow this buffer without bound. Failing
+    // the connection is the honest outcome: the caller gets an error naming the cap, while
+    // the next call dials a fresh socket.
+    if (this.buffer.length > MAX_BUFFER_BYTES) {
+      this.buffer = ''
+      this.reset(new Error(`dsh-builtin-browser: bridge reply exceeded ${String(MAX_BUFFER_BYTES)} bytes`))
+      return
+    }
     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()
+      const echoed = echoOf(line)
+      const id = echoed ?? this.queue[0]
+      if (id === undefined) {
+        // Nothing is waiting for this answer: the peer is answering something this socket
+        // never asked (or answered twice). Drop the socket rather than trust the stream.
+        this.reset(new Error('dsh-builtin-browser: bridge answered with no request outstanding'))
+        return
+      }
+      const index = this.queue.indexOf(id)
+      if (index !== -1) this.queue.splice(index, 1)
+      const entry = this.pending.get(id)
       if (entry === undefined) continue
+      this.pending.delete(id)
+      // Id-less bridges pair by order, so a reply for the WRONG request cannot be told apart
+      // from the right one. Remember that this bridge does not echo ids, and serialise every
+      // later call so the ambiguity cannot arise again.
+      if (echoed === undefined) {
+        this.idLessBridge = true
+        this.serialisable = true
+      }
       try {
         const answer = JSON.parse(line) as Record<string, unknown>
         // A rejected token means the shell restarted with a new one, so this socket
@@ -130,6 +265,13 @@ export class BridgeConnection {
     }
   }
 
+  /** Forget one request (its answer can no longer be matched). */
+  private forget(id: number): void {
+    this.pending.delete(id)
+    const index = this.queue.indexOf(id)
+    if (index !== -1) this.queue.splice(index, 1)
+  }
+
   /** Tear the socket down, failing pending work. */
   private reset(error: Error): void {
     if (this.socket !== undefined) {
@@ -139,7 +281,22 @@ export class BridgeConnection {
       socket.destroy()
     }
     this.buffer = ''
-    const pending = this.queue.splice(0, this.queue.length)
+    this.queue.length = 0
+    const pending = [...this.pending.values()]
+    this.pending.clear()
     for (const entry of pending) entry.reject(error)
   }
 }
+
+/** The request id a raw answer line echoes back, when it carries one. */
+function echoOf(line: string): number | undefined {
+  try {
+    const answer = JSON.parse(line) as Record<string, unknown>
+    const value = answer[REQUEST_ID_FIELD]
+    return typeof value === 'number' && Number.isSafeInteger(value) ? value : undefined
+  } catch {
+    // A malformed line cannot be matched by id; the caller consumes it in order and
+    // reports the parse failure itself.
+    return undefined
+  }
+}