pi-browser-harness 0.10.2 → 0.12.0

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;
     },
   };
 };

package/src/cdp/discovery.ts

@@ -5,17 +5,25 @@ import { request as httpRequest } from "node:http";
 import { type Result, err, ok } from "../util/result";
 import { userDataDirCandidates } from "../profile/paths";
 import { type CdpError, cdpError } from "./errors";
+import { asString, errnoCode, isRecord } from "../util/guards";
 
 const PORT_PROBE_DEADLINE_MS = 30_000;
 const PORT_PROBE_INTERVAL_MS = 1_000;
 
-/**
- * A live CDP endpoint plus, when discovery went through a DevToolsActivePort
- * file, the user-data-dir that file lives in. That directory is the browser's
- * profile registry (`Local State`) — Chromium writes DevToolsActivePort to
- * chrome::DIR_USER_DATA — so it is what profile selection enumerates.
- * Undefined when the endpoint came from BU_CDP_WS or a bare port probe.
- */
+// Hand-rolled on purpose: this file runs inside the daemon, a separate Node process that pi does not
+// supply host-provided packages (typebox) to. Everything the daemon imports must be a runtime
+// dependency or a builtin; test/daemon/entry-imports-test.ts enforces that.
+export const parseVersionResponse = (raw: string): string | null => {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!isRecord(parsed)) return null;
+  return asString(parsed["webSocketDebuggerUrl"]) ?? null;
+};
+
 export type CdpEndpoint = {
   readonly wsUrl: string;
   readonly userDataDir?: string;
@@ -52,17 +60,9 @@ const waitForPort = async (port: number): Promise<Result<void, CdpError>> => {
   ));
 };
 
-// Fast, single-shot TCP check (no retry loop). Used to skip stale
-// DevToolsActivePort files left behind by a browser that has since quit —
-// unlike waitForPort, this returns immediately instead of blocking ~30s.
 const isPortLive = async (port: number): Promise<boolean> => (await probePort(port)).success;
 
-// Ask the live browser for its canonical webSocketDebuggerUrl via
-// http://127.0.0.1:<port>/json/version. This is authoritative: it avoids
-// trusting a path from a stale DevToolsActivePort file that may belong to a
-// different browser which has since exited (e.g. Chrome's stale file pointing
-// at 9222 while Brave actually owns the port now). Returns null if the endpoint
-// is unreachable, non-200, or doesn't expose a WS URL.
+// /json/version is authoritative: a stale DevToolsActivePort file may name a browser that has since exited while another now owns the port.
 const queryLiveWsUrl = (port: number, timeoutMs = 1_500): Promise<string | null> =>
   new Promise<string | null>((resolve) => {
     const req = httpRequest(
@@ -76,13 +76,7 @@ const queryLiveWsUrl = (port: number, timeoutMs = 1_500): Promise<string | null>
         const chunks: Buffer[] = [];
         res.on("data", (c: Buffer) => chunks.push(c));
         res.on("end", () => {
-          try {
-            const json = JSON.parse(Buffer.concat(chunks).toString("utf8")) as Record<string, unknown>;
-            const ws = json["webSocketDebuggerUrl"];
-            resolve(typeof ws === "string" ? ws : null);
-          } catch {
-            resolve(null);
-          }
+          resolve(parseVersionResponse(Buffer.concat(chunks).toString("utf8")));
         });
       },
     );
@@ -91,10 +85,6 @@ const queryLiveWsUrl = (port: number, timeoutMs = 1_500): Promise<string | null>
     req.end();
   });
 
-// Well-known CDP ports to probe when no DevToolsActivePort file is readable
-// (sandboxed harness, restricted filesystem permissions, or an unusual profile
-// location not on the profileDirs list). The default Chromium remote-debugging
-// port is 9222; users can extend via BU_CDP_PORTS="9222,9333".
 const fallbackPorts = (): ReadonlyArray<number> => {
   const ports = new Set<number>([9222]);
   const fromEnv = process.env["BU_CDP_PORTS"];
@@ -111,21 +101,21 @@ type Candidate = {
   readonly port: number;
   readonly path: string;
   readonly mtimeMs: number;
-  /** The user-data-dir whose DevToolsActivePort produced this candidate. */
   readonly userDataDir: string;
 };
 
-/**
- * Locate a live CDP endpoint, reporting the user-data-dir it belongs to when
- * that is knowable. `discoverWsUrl` is the URL-only view of the same walk.
- */
+// Read here rather than in the client: the daemon owns the only socket to Chrome, so an override the daemon cannot see has no effect.
+export const endpointFromEnv = (env: NodeJS.ProcessEnv = process.env): CdpEndpoint | undefined => {
+  const wsUrl = env["BU_CDP_WS"]?.trim();
+  return wsUrl ? { wsUrl } : undefined;
+};
+
 export const discoverEndpoint = async (): Promise<Result<CdpEndpoint, CdpError>> => {
+  const override = endpointFromEnv();
+  if (override) return ok(override);
+
   const dirs = userDataDirCandidates();
 
-  // Phase 1: collect every readable DevToolsActivePort candidate up front,
-  // rather than committing to the first one found. A single browser writes one
-  // such file, but stale files from quit browsers linger, so we must
-  // disambiguate below instead of trusting discovery order.
   const candidates: Candidate[] = [];
   const readErrors: string[] = [];
   for (const base of dirs) {
@@ -136,15 +126,10 @@ export const discoverEndpoint = async (): Promise<Result<CdpEndpoint, CdpError>>
       raw = await readFile(portFile, "utf8");
       try {
         mtimeMs = (await stat(portFile)).mtimeMs;
-      } catch {
-        // mtime is only a tiebreaker; a stat failure just leaves it at 0.
-      }
+      } catch {}
     } catch (e) {
-      // Node fs errors carry .code; see ErrnoException. ENOENT is normal — the
-      // dir is on our list but the user hasn't installed that browser. EPERM/
-      // EACCES is common under sandboxes; remember it and fall back to network
-      // probing rather than failing the whole discovery.
-      const code = (e as NodeJS.ErrnoException).code;
+      // EPERM/EACCES is common under sandboxes; remember it and fall back to network probing rather than failing the whole discovery.
+      const code = errnoCode(e);
       if (code === "ENOENT" || code === undefined) continue;
       if (code === "EPERM" || code === "EACCES") {
         readErrors.push(`${portFile}: ${code}`);
@@ -157,25 +142,16 @@ export const discoverEndpoint = async (): Promise<Result<CdpEndpoint, CdpError>>
     const port = lines[0]?.trim();
     const path = lines[1]?.trim();
     if (!port || !path) continue;
-    // Guard against a truncated/corrupt port file (e.g. a non-numeric first
-    // line): an out-of-range port makes net.connect throw ERR_SOCKET_BAD_PORT
-    // synchronously, which would escape discoverWsUrl instead of surfacing as
-    // a Result error. Skip such entries.
+    // An out-of-range port makes net.connect throw ERR_SOCKET_BAD_PORT synchronously, escaping discoverWsUrl instead of surfacing as a Result error.
     const portNum = Number(port);
     if (!Number.isInteger(portNum) || portNum <= 0 || portNum >= 65536) continue;
     candidates.push({ port: portNum, path, mtimeMs, userDataDir: base });
   }
 
-  // Phase 2: no readable candidate — probe well-known ports directly. Covers
-  // sandboxed harnesses that can't read profile dirs and non-default install
-  // locations. Requires the browser to have been launched with
-  // --remote-debugging-port so /json/version is served.
   if (candidates.length === 0) {
     for (const port of fallbackPorts()) {
       if (!(await isPortLive(port))) continue;
       const live = await queryLiveWsUrl(port);
-      // No DevToolsActivePort file was involved, so the user-data-dir behind
-      // this endpoint is unknown — profile selection stays unavailable.
       if (live) return ok({ wsUrl: live });
     }
     const permHint = readErrors.length > 0
@@ -187,9 +163,6 @@ export const discoverEndpoint = async (): Promise<Result<CdpEndpoint, CdpError>>
     ));
   }
 
-  // Phase 3: disambiguate candidates sharing a port (one browser running, and
-  // another's file left behind on the default 9222): keep the most-recently-
-  // written file — that's the currently-running browser.
   const byPort = new Map<number, Candidate>();
   for (const c of candidates) {
     const prev = byPort.get(c.port);
@@ -197,16 +170,11 @@ export const discoverEndpoint = async (): Promise<Result<CdpEndpoint, CdpError>>
   }
   const unique = Array.from(byPort.values());
 
-  // Prefer candidates whose port is actually accepting connections; this skips
-  // stale files whose browser has quit (avoiding a ~30s waitForPort block).
   const liveChecks = await Promise.all(unique.map((c) => isPortLive(c.port)));
   const liveCandidates = unique.filter((_, i) => liveChecks[i]);
   const ordered = liveCandidates.length > 0 ? liveCandidates : unique;
 
-  // Phase 4: for each candidate, prefer the browser's own canonical WS URL from
-  // /json/version. Some browsers disable that HTTP endpoint when remote
-  // debugging is toggled only via chrome://inspect (rather than a launch flag),
-  // so fall back to the WS path written in DevToolsActivePort.
+  // Some browsers disable the /json/version endpoint when remote debugging is toggled via chrome://inspect rather than a launch flag, hence the DevToolsActivePort fallback.
   let lastErr: Result<CdpEndpoint, CdpError> | null = null;
   for (const c of ordered) {
     const ready = await waitForPort(c.port);
@@ -218,10 +186,6 @@ export const discoverEndpoint = async (): Promise<Result<CdpEndpoint, CdpError>>
     return ok({ wsUrl: liveUrl ?? `ws://127.0.0.1:${c.port}${c.path}`, userDataDir: c.userDataDir });
   }
 
-  // Every discovered candidate was stale/unreachable. Before giving up, try the
-  // well-known fallback ports — a user with a leftover DevToolsActivePort file
-  // may still have a live browser reachable via 9222 / BU_CDP_PORTS. (Skip ports
-  // already covered by a candidate above so we don't re-probe them.)
   for (const port of fallbackPorts()) {
     if (byPort.has(port) || !(await isPortLive(port))) continue;
     const liveUrl = await queryLiveWsUrl(port);
@@ -231,10 +195,6 @@ export const discoverEndpoint = async (): Promise<Result<CdpEndpoint, CdpError>>
   return lastErr ?? err(cdpError("discovery_failed", "no live DevTools endpoint among discovered candidates"));
 };
 
-/**
- * URL-only view of {@link discoverEndpoint}, kept as the stable entry point for
- * callers that don't care which user-data-dir answered.
- */
 export const discoverWsUrl = async (): Promise<Result<string, CdpError>> => {
   const endpoint = await discoverEndpoint();
   return endpoint.success ? ok(endpoint.data.wsUrl) : endpoint;

package/src/cdp/errors.ts

@@ -12,6 +12,10 @@ export type CdpError = {
   readonly method?: string;
 };
 
+// Chrome reports a dead session as a generic protocol error, so the message text is the only signal that a reattach — not a retry — is what will fix it.
+export const classifyRemoteError = (message: string): CdpErrorKind =>
+  message.includes("Session with given id not found") ? "session_not_found" : "remote_error";
+
 export const cdpError = (
   kind: CdpErrorKind,
   message: string,

package/src/cdp/events.ts

@@ -0,0 +1,170 @@
+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 ev = <P extends TSchema>(params: P) => ({ params, validate: Compile(params) });
+
+const open = { additionalProperties: true } as const;
+
+const Anything = Type.Object({}, open);
+
+const StackTrace = Type.Object(
+  {
+    callFrames: Type.Optional(
+      Type.Array(
+        Type.Object(
+          {
+            url: Type.Optional(Type.String()),
+            lineNumber: Type.Optional(Type.Number()),
+            functionName: Type.Optional(Type.String()),
+          },
+          open,
+        ),
+      ),
+    ),
+  },
+  open,
+);
+
+const ConsoleArg = Type.Object(
+  {
+    type: Type.Optional(Type.String()),
+    value: Type.Optional(Type.Unknown()),
+    description: Type.Optional(Type.String()),
+    unserializableValue: Type.Optional(Type.String()),
+  },
+  open,
+);
+
+export const EVENTS = {
+  "Inspector.detached": ev(Anything),
+
+  "Page.javascriptDialogOpening": ev(
+    Type.Object(
+      {
+        type: Type.String(),
+        message: Type.String(),
+        defaultPrompt: Type.Optional(Type.String()),
+      },
+      open,
+    ),
+  ),
+  "Page.loadEventFired": ev(Anything),
+  "Page.frameNavigated": ev(Anything),
+
+  "Runtime.consoleAPICalled": ev(
+    Type.Object(
+      {
+        type: Type.Optional(Type.String()),
+        args: Type.Optional(Type.Array(ConsoleArg)),
+        stackTrace: Type.Optional(StackTrace),
+      },
+      open,
+    ),
+  ),
+
+  "Log.entryAdded": ev(
+    Type.Object(
+      {
+        entry: Type.Object(
+          {
+            level: Type.Optional(Type.String()),
+            text: Type.Optional(Type.String()),
+            url: Type.Optional(Type.String()),
+            lineNumber: Type.Optional(Type.Number()),
+            stackTrace: Type.Optional(StackTrace),
+          },
+          open,
+        ),
+      },
+      open,
+    ),
+  ),
+
+  "Network.requestWillBeSent": ev(
+    Type.Object(
+      {
+        requestId: Type.String(),
+        request: Type.Object(
+          {
+            url: Type.String(),
+            method: Type.String(),
+            postData: Type.Optional(Type.String()),
+          },
+          open,
+        ),
+        type: Type.Optional(Type.String()),
+      },
+      open,
+    ),
+  ),
+  "Network.responseReceived": ev(
+    Type.Object(
+      {
+        requestId: Type.String(),
+        response: Type.Optional(
+          Type.Object(
+            {
+              status: Type.Optional(Type.Number()),
+              statusText: Type.Optional(Type.String()),
+              mimeType: Type.Optional(Type.String()),
+            },
+            open,
+          ),
+        ),
+        type: Type.Optional(Type.String()),
+      },
+      open,
+    ),
+  ),
+  "Network.loadingFinished": ev(
+    Type.Object(
+      { requestId: Type.String(), encodedDataLength: Type.Optional(Type.Number()) },
+      open,
+    ),
+  ),
+  "Network.loadingFailed": ev(
+    Type.Object(
+      { requestId: Type.String(), errorText: Type.Optional(Type.String()) },
+      open,
+    ),
+  ),
+
+  "Target.targetCreated": ev(
+    Type.Object(
+      {
+        targetInfo: Type.Object(
+          {
+            targetId: Type.String(),
+            type: Type.String(),
+            openerId: Type.Optional(Type.String()),
+          },
+          open,
+        ),
+      },
+      open,
+    ),
+  ),
+  "Target.targetDestroyed": ev(Type.Object({ targetId: Type.String() }, open)),
+};
+
+export type CdpEventName = keyof typeof EVENTS;
+export type EventParamsOf<E extends CdpEventName> = Static<(typeof EVENTS)[E]["params"]>;
+
+export const isKnownEvent = (name: string): name is CdpEventName => Object.hasOwn(EVENTS, name);
+
+export const decodeEvent = <E extends CdpEventName>(
+  name: E,
+  raw: unknown,
+): Result<EventParamsOf<E>, CdpError> => {
+  const spec = EVENTS[name];
+  if (spec === undefined) {
+    return err(cdpError("invalid_response", "unknown CDP event", name));
+  }
+  if (!spec.validate.Check(raw)) {
+    const why = spec.validate.Errors(raw).map((e) => e.message).join("; ");
+    return err(cdpError("invalid_response", why, name));
+  }
+  return ok(raw as EventParamsOf<E>);
+};