pi-browser-harness 0.10.1 → 0.11.0

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 All notable changes to pi-browser-harness will be documented in this file.
 
+## 0.11.0 — 2026-08-02
+
+### Fixed
+
+- **`--browser-debug-clicks` now does something.** The flag was registered and documented but never read; the only working switch was the undocumented `BH_DEBUG_CLICKS` environment variable. Both now drive the same setting.
+- **`BU_CDP_WS` now actually attaches to a remote browser.** The client read the variable and passed the URL to `transport.connect()`, but the daemon transport discards that argument and always dials the daemon socket — and the daemon's own discovery never looked at the variable, so setting it changed nothing. The override moved into `discoverEndpoint`, which both processes go through. It is read when the daemon starts, so a running daemon must be stopped first.
+- **A disconnected client's pending requests no longer fire at a dead socket.** `removeClient` cleared the daemon's id multiplexer but not its callback map, so a gone client's command timeouts stayed armed and later tried to answer it.
+
+### Changed
+
+- **One route from a tool to the browser.** Four coexisted; `src/domains/cdp-call.ts` is now the only one, and two boundary-scanner rules scoped to `src/domains/` keep it that way. A CDP timeout now surfaces as `kind: "timeout"` instead of `cdp_error` at the sites that previously flattened it.
+- **Shared logic moved out of tool files** into `ax-tree.ts`, `element-call.ts`, and `screenshot-capture.ts`, so importing one tool no longer pulls in another tool's module. `cdp/attach.ts` and `cdp/window.ts` became `session.attach()` and `session.windowId()`; `cdp/daemon-transport.ts` became `daemon/transport.ts`; the request-timeout half of `cdp/event-queue.ts` became `cdp/pending-requests.ts`.
+- **The daemon's request bookkeeping is one map instead of two**, and a request that arrives while Chrome is down awaits a single connect signal rather than spinning its own 250 ms poll loop.
+
+### Removed
+
+- **The second CDP transport.** `createCdpTransport` was a full WebSocket-to-Chrome implementation reachable only through a fallback in `client.ts` that production never took. `cdp/transport.ts` now holds just the `CdpTransport` interface, and a client must be given a transport.
+- **Dead exports and a fake config knob:** `isInternalUrl`, `SPECIAL_KEYS`, `andThen`, `mapErr`, `BrowserState.remoteBrowserId`, `IpcServer.disconnectClient`, `IpcServer.clients()`, and `DAEMON_STALE_SOCKET_CLEANUP` (a hardcoded `true` with a branch around it).
+
+- **The `deep-research` skill, the `/deep-research` command, and the `web-search-researcher` subagent.** The harness ships browser tools; orchestrating multi-agent research on top of them belongs to the agent, not to this extension. `browser_web_search` and `browser_read_page` are unaffected — search then read still works, it is just no longer wrapped in a fan-out workflow.
+
+## 0.10.3 — 2026-07-26
+
+### Fixed
+
+- **Profile binding after an in-place browser upgrade.** Linux appends `" (deleted)"` to `/proc/<pid>/exe` once the running binary is unlinked — which is exactly what a `google-chrome` package update does while the browser stays open. `detectRunningBrowser` returned that literal string as the executable path, so every profile launch tried to spawn `/opt/google/chrome/chrome (deleted)` and failed with `ENOENT`. Executable paths are now validated against disk, with the marker stripped (and argv[0] used) when the linked binary is gone.
+- **A failed browser launch no longer reports as a sentinel timeout.** `spawn()` signals a missing or non-executable binary asynchronously via an `error` event rather than by throwing, and that event was discarded — so `openProfileWindow` returned success, no window ever opened, and the caller blamed the browser 15 seconds later with `couldn't open a window in "<profile>" automatically`. The launch now waits for `spawn`/`error` and returns the real cause, and removes its handshake page on the failure path.
+
+## 0.10.2 — 2026-07-26
+
+### Fixed
+
+- **Page info no longer fails on a missing `documentElement`.** The page-info probe read `document.documentElement.scrollWidth`/`scrollHeight` directly, which throws when `documentElement` is absent — leaving every caller with an evaluation error instead of a page snapshot. The probe now falls back to zeroed scroll dimensions and returns a usable `PageInfo`.
+
 ## 0.10.1 — 2026-07-26
 
 ### Fixed

package/README.md

@@ -6,7 +6,7 @@
 
 Your profile, your logins, your cookies. The agent reads pages as an accessibility tree with stable
 element handles, fills forms that React won't revert, captures network traffic and console errors,
-searches the web, and drops to raw CDP when the tools run out. 38 tools over a single CDP connection —
+searches the web, and drops to raw CDP when the tools run out. 40 tools over a single CDP connection —
 no MCP hop, no second browser, no extra API keys.
 
 ---
@@ -50,9 +50,9 @@ The first time you connect, you'll be asked which browser profile the agent shou
 
 ```
 Select the browser profile the agent should use
-    vertexcover.io (aman@vertexcover.io)
-  ✓ Aman (personal@gmail.com)
-    Harness (harness@gmail.com)
+    Work (work@example.com)
+  ✓ Personal (personal@example.com)
+    Testing (test@example.com)
     — Clear selection (use whichever window is focused) —
 ```
 
@@ -238,11 +238,7 @@ browser_web_search({ query: "chrome devtools protocol overview", limit: 5 })
 browser_read_page({ url: "<the best result's url>" })
 ```
 
-For a question that needs several sources synthesized into a **cited report**, use
-`/deep-research <question>`. It decomposes the question, fans out one isolated
-`web-search-researcher` subagent per sub-question, loops for coverage under a hard ceiling, and
-writes a Markdown report where every claim carries a source link. The skill also auto-triggers on
-research-shaped requests without the command.
+Both tools open their own isolated tab, so neither disturbs the tab you are working in.
 
 ### Keyboard modifiers
 
@@ -310,14 +306,14 @@ re-runnable.
 | `/browser-setup` | Connect pi to your browser. Run once; idempotent. |
 | `/browser-profile` | Pick which browser profile the agent works in. Remembered across sessions. |
 | `/browser-status` | Connection state, selected profile, and current page. |
-| `/deep-research <question>` | Multi-source web research → cited Markdown report. |
 | `/browser-reload-daemon` | Force a client restart. Rarely needed — the transport reconnects on its own. |
 
 | Flag / variable | Effect |
 |---|---|
 | `--browser-namespace <name>` | Override the session namespace (default: auto-generated). |
-| `--browser-debug-clicks` | Save annotated click screenshots for debugging. |
-| `BU_CDP_WS` | Attach to a remote browser by WebSocket URL instead of discovering a local one. |
+| `--browser-debug-clicks` | Save annotated click screenshots for debugging. Equivalent to `BH_DEBUG_CLICKS=1`. |
+| `BU_CDP_WS` | Attach to a remote browser by WebSocket URL instead of discovering a local one. The daemon reads this when it starts, so stop a running daemon first. |
+| `BH_DEBUG_CLICKS` | Same as `--browser-debug-clicks`. |
 | `BU_CDP_PORTS` | Extra ports to probe during CDP discovery, beyond 9222. |
 | `BH_SCRIPT_DIR` | Additional directory `browser_run_script` will accept paths from. |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-browser-harness",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "Browser control extension for pi — navigate, click, type, screenshot, and extract data from real Chrome via CDP",
   "keywords": [
     "pi-package",
@@ -57,7 +57,10 @@
     "typescript": "^5.0.0"
   },
   "scripts": {
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json",
+    "test": "node --conditions=import --import tsx --test \"test/{profile,domains,cdp,daemon,util}/**/*-test.ts\"",
+    "boundaries": "tsx scripts/check-boundaries.ts",
+    "check": "npm run typecheck && npm run boundaries && npm test",
     "prepublishOnly": "tsc --noEmit"
   },
   "publishConfig": {

package/skills/pi-browser-harness/SKILL.md

@@ -36,7 +36,7 @@ What do you need to know?
 
 Pass `@(x,y)` from `browser_snapshot` straight to `browser_click`. No screenshot round-trip.
 
-`browser_web_search` and `browser_read_page` each run in their own isolated tab and never touch the user's current tab. For a multi-source question that needs a synthesized, cited report, use the **deep-research** skill (or `/deep-research <question>`): it fans out isolated `web-search-researcher` subagents over both tools and writes a source-cited Markdown report.
+`browser_web_search` and `browser_read_page` each run in their own isolated tab and never touch the user's current tab. Pair them for a research question: search for candidate URLs, then read the promising ones.
 
 ## Connection Setup
 

package/src/cdp/commands.ts

@@ -0,0 +1,256 @@
+import { Type, type Static, type TSchema } from "typebox";
+import { Compile } from "typebox/compile";
+import { type Result, err, ok } from "../util/result";
+import { type CdpError, cdpError } from "./errors";
+
+const cmd = <P extends TSchema, R extends TSchema>(params: P, result: R) => ({
+  params,
+  result,
+  validate: Compile(result),
+});
+
+const Empty = Type.Object({});
+
+const TargetInfo = Type.Object(
+  {
+    targetId: Type.String(),
+    type: Type.String(),
+    title: Type.String(),
+    url: Type.String(),
+    attached: Type.Optional(Type.Boolean()),
+    openerId: Type.Optional(Type.String()),
+    browserContextId: Type.Optional(Type.String()),
+  },
+  { additionalProperties: true },
+);
+
+const RemoteObject = Type.Object(
+  {
+    type: Type.String(),
+    subtype: Type.Optional(Type.String()),
+    className: Type.Optional(Type.String()),
+    value: Type.Optional(Type.Unknown()),
+    description: Type.Optional(Type.String()),
+    objectId: Type.Optional(Type.String()),
+  },
+  { additionalProperties: true },
+);
+
+const CallArgument = Type.Object(
+  {
+    value: Type.Optional(Type.Unknown()),
+    objectId: Type.Optional(Type.String()),
+    unserializableValue: Type.Optional(Type.String()),
+  },
+  { additionalProperties: true },
+);
+
+const ExceptionDetails = Type.Object(
+  { text: Type.String(), exception: Type.Optional(RemoteObject) },
+  { additionalProperties: true },
+);
+
+const AxValue = Type.Object({ value: Type.Optional(Type.Unknown()) }, { additionalProperties: true });
+
+const AxNode = Type.Object(
+  {
+    nodeId: Type.String(),
+    parentId: Type.Optional(Type.String()),
+    childIds: Type.Optional(Type.Array(Type.String())),
+    ignored: Type.Optional(Type.Boolean()),
+    role: Type.Optional(AxValue),
+    name: Type.Optional(AxValue),
+    value: Type.Optional(AxValue),
+    description: Type.Optional(AxValue),
+    properties: Type.Optional(
+      Type.Array(
+        Type.Object(
+          { name: Type.Optional(Type.String()), value: Type.Optional(AxValue) },
+          { additionalProperties: true },
+        ),
+      ),
+    ),
+    backendDOMNodeId: Type.Optional(Type.Number()),
+  },
+  { additionalProperties: true },
+);
+
+export type AxNodeResult = Static<typeof AxNode>;
+
+export const COMMANDS = {
+  "Target.attachToTarget": cmd(
+    Type.Object({ targetId: Type.String(), flatten: Type.Optional(Type.Boolean()) }),
+    Type.Object({ sessionId: Type.String() }),
+  ),
+  "Target.detachFromTarget": cmd(
+    Type.Object({ sessionId: Type.Optional(Type.String()) }),
+    Empty,
+  ),
+  "Target.createTarget": cmd(
+    Type.Object({
+      url: Type.String(),
+      newWindow: Type.Optional(Type.Boolean()),
+      background: Type.Optional(Type.Boolean()),
+      windowId: Type.Optional(Type.Number()),
+      openerId: Type.Optional(Type.String()),
+    }),
+    Type.Object({ targetId: Type.String() }),
+  ),
+  "Target.closeTarget": cmd(
+    Type.Object({ targetId: Type.String() }),
+    Type.Object({ success: Type.Optional(Type.Boolean()) }),
+  ),
+  "Target.activateTarget": cmd(Type.Object({ targetId: Type.String() }), Empty),
+  "Target.getTargetInfo": cmd(
+    Type.Object({ targetId: Type.Optional(Type.String()) }),
+    Type.Object({ targetInfo: TargetInfo }),
+  ),
+  "Target.getTargets": cmd(
+    Type.Object({}),
+    Type.Object({ targetInfos: Type.Array(TargetInfo) }),
+  ),
+  "Target.setDiscoverTargets": cmd(Type.Object({ discover: Type.Boolean() }), Empty),
+
+  "Browser.getWindowForTarget": cmd(
+    Type.Object({ targetId: Type.Optional(Type.String()) }),
+    Type.Object({ windowId: Type.Number(), bounds: Type.Optional(Type.Unknown()) }),
+  ),
+  "Browser.setDownloadBehavior": cmd(
+    Type.Object({
+      behavior: Type.String(),
+      downloadPath: Type.Optional(Type.String()),
+      eventsEnabled: Type.Optional(Type.Boolean()),
+    }),
+    Empty,
+  ),
+
+  "Page.enable": cmd(Type.Object({}), Empty),
+  "Page.bringToFront": cmd(Type.Object({}), Empty),
+  "Page.navigate": cmd(
+    Type.Object({ url: Type.String(), referrer: Type.Optional(Type.String()) }),
+    Type.Object({
+      frameId: Type.String(),
+      loaderId: Type.Optional(Type.String()),
+      errorText: Type.Optional(Type.String()),
+    }),
+  ),
+  "Page.reload": cmd(Type.Object({ ignoreCache: Type.Optional(Type.Boolean()) }), Empty),
+  "Page.getNavigationHistory": cmd(
+    Type.Object({}),
+    Type.Object({
+      currentIndex: Type.Number(),
+      entries: Type.Array(
+        Type.Object({ id: Type.Number(), url: Type.String(), title: Type.String() }),
+      ),
+    }),
+  ),
+  "Page.navigateToHistoryEntry": cmd(Type.Object({ entryId: Type.Number() }), Empty),
+  "Page.captureScreenshot": cmd(
+    Type.Object({
+      format: Type.Optional(Type.String()),
+      quality: Type.Optional(Type.Number()),
+      clip: Type.Optional(Type.Unknown()),
+      captureBeyondViewport: Type.Optional(Type.Boolean()),
+    }),
+    Type.Object({ data: Type.String() }),
+  ),
+  "Page.printToPDF": cmd(Type.Object({}, { additionalProperties: true }), Type.Object({ data: Type.String() })),
+  "Page.handleJavaScriptDialog": cmd(
+    Type.Object({ accept: Type.Boolean(), promptText: Type.Optional(Type.String()) }),
+    Empty,
+  ),
+
+  "Runtime.evaluate": cmd(
+    Type.Object(
+      {
+        expression: Type.String(),
+        returnByValue: Type.Optional(Type.Boolean()),
+        awaitPromise: Type.Optional(Type.Boolean()),
+        userGesture: Type.Optional(Type.Boolean()),
+      },
+      { additionalProperties: true },
+    ),
+    Type.Object({ result: RemoteObject, exceptionDetails: Type.Optional(ExceptionDetails) }),
+  ),
+  "Runtime.callFunctionOn": cmd(
+    Type.Object(
+      {
+        functionDeclaration: Type.String(),
+        objectId: Type.Optional(Type.String()),
+        arguments: Type.Optional(Type.Array(CallArgument)),
+        returnByValue: Type.Optional(Type.Boolean()),
+        awaitPromise: Type.Optional(Type.Boolean()),
+        userGesture: Type.Optional(Type.Boolean()),
+      },
+      { additionalProperties: true },
+    ),
+    Type.Object({ result: RemoteObject, exceptionDetails: Type.Optional(ExceptionDetails) }),
+  ),
+  "Runtime.releaseObject": cmd(Type.Object({ objectId: Type.String() }), Empty),
+
+  "DOM.getDocument": cmd(
+    Type.Object({ depth: Type.Optional(Type.Number()), pierce: Type.Optional(Type.Boolean()) }),
+    Type.Object({ root: Type.Object({ nodeId: Type.Number() }, { additionalProperties: true }) }),
+  ),
+  "DOM.querySelector": cmd(
+    Type.Object({ nodeId: Type.Number(), selector: Type.String() }),
+    Type.Object({ nodeId: Type.Number() }),
+  ),
+  "DOM.getBoxModel": cmd(
+    Type.Object({ nodeId: Type.Optional(Type.Number()), backendNodeId: Type.Optional(Type.Number()) }),
+    Type.Object({
+      model: Type.Object(
+        { content: Type.Array(Type.Number()), width: Type.Number(), height: Type.Number() },
+        { additionalProperties: true },
+      ),
+    }),
+  ),
+  "DOM.resolveNode": cmd(
+    Type.Object({ nodeId: Type.Optional(Type.Number()), backendNodeId: Type.Optional(Type.Number()) }),
+    Type.Object({ object: RemoteObject }),
+  ),
+  "DOM.setFileInputFiles": cmd(
+    Type.Object({
+      files: Type.Array(Type.String()),
+      nodeId: Type.Optional(Type.Number()),
+      backendNodeId: Type.Optional(Type.Number()),
+      objectId: Type.Optional(Type.String()),
+    }),
+    Empty,
+  ),
+
+  "Input.dispatchMouseEvent": cmd(Type.Object({}, { additionalProperties: true }), Empty),
+  "Input.dispatchKeyEvent": cmd(Type.Object({}, { additionalProperties: true }), Empty),
+  "Input.dispatchDragEvent": cmd(Type.Object({}, { additionalProperties: true }), Empty),
+  "Input.insertText": cmd(Type.Object({ text: Type.String() }), Empty),
+
+  "Network.getResponseBody": cmd(
+    Type.Object({ requestId: Type.String() }),
+    Type.Object({ body: Type.String(), base64Encoded: Type.Optional(Type.Boolean()) }),
+  ),
+  "Emulation.setDeviceMetricsOverride": cmd(Type.Object({}, { additionalProperties: true }), Empty),
+  "Accessibility.getFullAXTree": cmd(
+    Type.Object({ depth: Type.Optional(Type.Number()) }, { additionalProperties: true }),
+    Type.Object({ nodes: Type.Array(AxNode) }),
+  ),
+};
+
+export type CdpMethod = keyof typeof COMMANDS;
+export type ParamsOf<M extends CdpMethod> = Static<(typeof COMMANDS)[M]["params"]>;
+export type ResultOf<M extends CdpMethod> = Static<(typeof COMMANDS)[M]["result"]>;
+
+export const decodeResult = <M extends CdpMethod>(
+  method: M,
+  raw: unknown,
+): Result<ResultOf<M>, CdpError> => {
+  const spec = COMMANDS[method];
+  if (spec === undefined) {
+    return err(cdpError("invalid_response", `unknown CDP method`, method));
+  }
+  if (!spec.validate.Check(raw)) {
+    const why = spec.validate.Errors(raw).map((e) => e.message).join("; ");
+    return err(cdpError("invalid_response", why, method));
+  }
+  // Guarded assertion: the check above proves `raw` matches COMMANDS[method].result, which TS cannot correlate from a generic key.
+  return ok(raw as ResultOf<M>);
+};

package/src/cdp/console-buffer.ts

@@ -1,54 +1,30 @@
-/**
- * In-memory aggregator for CDP Runtime.consoleAPICalled and Log.entryAdded events.
- *
- * Mirrors network-buffer.ts: the single CDP event loop in session.ts hands raw
- * params to ingestConsoleApi / ingestLogEntry; tools later read records via drain().
- *
- * Bounded by capacity (default 500). On overflow the oldest record is evicted FIFO,
- * and the overflow flag is reported once per drain so tools can warn the LLM that
- * data may be missing.
- *
- * Each record carries a monotonic `seq`. Tools expose the last drained seq as
- * `nextCursor`; callers pass it back as `sinceSeq` to read only what's new since
- * the previous drain. This is the cursor pattern that makes "what did this action
- * cause?" answerable in one tool call.
- *
- * Pure module (no CDP dependency) — joining/filtering logic stays trivially testable.
- */
+import { decodeEvent } from "./events";
+import { createRecordStore } from "./record-store";
 
 export type ConsoleLevel = "log" | "info" | "warn" | "error" | "debug";
 
 export type ConsoleRecord = {
   seq: number;
-  /** Wall-clock ms when the event was ingested, in Date.now() units. */
   timestampMs: number;
   level: ConsoleLevel;
-  /** Joined args (console-api) or the entry text (log-entry). Per-arg truncated. */
   text: string;
   source: "console-api" | "log-entry";
   url?: string;
   lineNumber?: number;
-  /** Top frames only, joined with newlines. Populated for error/warn when CDP provides one. */
   stackTrace?: string;
 };
 
 export type ConsoleFilter = {
   levels?: ConsoleLevel[];
-  /** Substring match by default. Wrap in slashes (`/foo/`) for regex. */
   textPattern?: string;
-  /** Only records with seq strictly greater than this. */
   sinceSeq?: number;
-  /** Only records with timestamp at most N ms ago. */
   sinceMs?: number;
-  /** Cap on returned records (default 50, max 500). */
   limit?: number;
 };
 
 export type ConsoleDrainResult = {
   readonly records: ConsoleRecord[];
-  /** Total matches before `limit` was applied. */
   readonly total: number;
-  /** True if the ring buffer evicted at least one record since the last drain. */
   readonly bufferOverflowed: boolean;
 };
 
@@ -59,9 +35,7 @@ export type ConsoleBuffer = {
   clear(): void;
 };
 
-/** Per-arg cap to stop a single console.log(hugeBlob) from blowing the buffer. */
 const PER_ARG_CAP = 2000;
-/** Max stack frames preserved per record. */
 const MAX_STACK_FRAMES = 3;
 
 const compileTextMatcher = (pattern: string): ((text: string) => boolean) => {
@@ -69,9 +43,7 @@ const compileTextMatcher = (pattern: string): ((text: string) => boolean) => {
     try {
       const re = new RegExp(pattern.slice(1, -1));
       return (text) => re.test(text);
-    } catch {
-      // Fall through to substring match if the pattern is not a valid regex.
-    }
+    } catch {}
   }
   return (text) => text.includes(pattern);
 };
@@ -79,7 +51,6 @@ const compileTextMatcher = (pattern: string): ((text: string) => boolean) => {
 const truncateArg = (s: string): string =>
   s.length > PER_ARG_CAP ? s.slice(0, PER_ARG_CAP) + "…" : s;
 
-/** Best-effort stringification of one Runtime.RemoteObject. */
 const stringifyRemoteObject = (
   arg: { type?: string; subtype?: string; value?: unknown; description?: string; unserializableValue?: string },
 ): string => {
@@ -96,7 +67,6 @@ const stringifyRemoteObject = (
   return arg.type ?? "";
 };
 
-/** Map CDP console-API method names to our normalized levels. */
 const mapConsoleApiLevel = (type: string | undefined): ConsoleLevel => {
   switch (type) {
     case "error":
@@ -114,7 +84,6 @@ const mapConsoleApiLevel = (type: string | undefined): ConsoleLevel => {
   }
 };
 
-/** Map Log.LogEntry.level values ("verbose","info","warning","error") to our levels. */
 const mapLogEntryLevel = (level: string | undefined): ConsoleLevel => {
   switch (level) {
     case "error":
@@ -143,43 +112,18 @@ const formatStackTrace = (
 };
 
 export const createConsoleBuffer = (capacity = 500): ConsoleBuffer => {
-  // Insertion-ordered map keyed by seq. Map preserves insertion order in JS,
-  // so iteration gives us oldest-first eviction without a separate index.
-  const records = new Map<number, ConsoleRecord>();
+  const records = createRecordStore<number, ConsoleRecord>(capacity);
   let nextSeq = 1;
-  let overflowed = false;
-
-  const evictOldestIfFull = (): void => {
-    while (records.size >= capacity) {
-      const oldest = records.keys().next();
-      if (oldest.done) return;
-      records.delete(oldest.value);
-      overflowed = true;
-    }
-  };
 
   const insert = (rec: ConsoleRecord): void => {
-    evictOldestIfFull();
     records.set(rec.seq, rec);
   };
 
   return {
     ingestConsoleApi(p) {
-      // CDP boundary cast: Runtime.consoleAPICalled
-      const params = p as
-        | {
-            type?: string;
-            args?: ReadonlyArray<{
-              type?: string;
-              subtype?: string;
-              value?: unknown;
-              description?: string;
-              unserializableValue?: string;
-            }>;
-            stackTrace?: { callFrames?: ReadonlyArray<{ url?: string; lineNumber?: number; functionName?: string }> };
-          }
-        | undefined;
-      if (!params) return;
+      const decoded = decodeEvent("Runtime.consoleAPICalled", p);
+      if (!decoded.success) return;
+      const params = decoded.data;
       const level = mapConsoleApiLevel(params.type);
       const argTexts = (params.args ?? []).map((a) => truncateArg(stringifyRemoteObject(a)));
       const text = argTexts.join(" ");
@@ -199,19 +143,8 @@ export const createConsoleBuffer = (capacity = 500): ConsoleBuffer => {
     },
 
     ingestLogEntry(p) {
-      // CDP boundary cast: Log.entryAdded
-      const params = p as
-        | {
-            entry?: {
-              level?: string;
-              text?: string;
-              url?: string;
-              lineNumber?: number;
-              stackTrace?: { callFrames?: ReadonlyArray<{ url?: string; lineNumber?: number; functionName?: string }> };
-            };
-          }
-        | undefined;
-      const entry = params?.entry;
+      const decoded = decodeEvent("Log.entryAdded", p);
+      const entry = decoded.success ? decoded.data.entry : undefined;
       if (!entry) return;
       const level = mapLogEntryLevel(entry.level);
       const text = truncateArg(entry.text ?? "");
@@ -244,20 +177,12 @@ export const createConsoleBuffer = (capacity = 500): ConsoleBuffer => {
         matched.push({ ...r });
       }
 
-      const total = matched.length;
-      const limit = Math.min(filter.limit ?? 50, 500);
-      const limited = matched.slice(-limit);
-
-      const bufferOverflowed = overflowed;
-      overflowed = false;
-
-      return { records: limited, total, bufferOverflowed };
+      return records.page(matched, filter.limit);
     },
 
     clear() {
       records.clear();
       nextSeq = 1;
-      overflowed = false;
     },
   };
 };