pi-browser-harness 0.11.0 → 0.13.0

package/src/cdp/console-buffer.ts

@@ -1,32 +1,39 @@
+import { Type, type Static } from "typebox";
 import { decodeEvent } from "./events";
-import { createRecordStore } from "./record-store";
+import { createRecordStore, type DrainPage } from "./record-store";
 
 export type ConsoleLevel = "log" | "info" | "warn" | "error" | "debug";
 
-export type ConsoleRecord = {
-  seq: number;
-  timestampMs: number;
-  level: ConsoleLevel;
-  text: string;
-  source: "console-api" | "log-entry";
-  url?: string;
-  lineNumber?: number;
-  stackTrace?: string;
-};
+// The one declaration of a console record: the buffer produces it and browser_console validates replayed
+// details against it, so the two cannot drift.
+export const ConsoleRecordSchema = Type.Object({
+  seq: Type.Number(),
+  timestampMs: Type.Number(),
+  level: Type.Union([
+    Type.Literal("log"),
+    Type.Literal("info"),
+    Type.Literal("warn"),
+    Type.Literal("error"),
+    Type.Literal("debug"),
+  ]),
+  text: Type.String(),
+  source: Type.Union([Type.Literal("console-api"), Type.Literal("log-entry")]),
+  url: Type.Optional(Type.String()),
+  lineNumber: Type.Optional(Type.Number()),
+  stackTrace: Type.Optional(Type.String()),
+});
+
+export type ConsoleRecord = Readonly<Static<typeof ConsoleRecordSchema>>;
 
 export type ConsoleFilter = {
-  levels?: ConsoleLevel[];
-  textPattern?: string;
-  sinceSeq?: number;
-  sinceMs?: number;
-  limit?: number;
+  readonly levels?: ReadonlyArray<ConsoleLevel>;
+  readonly textPattern?: string;
+  readonly sinceSeq?: number;
+  readonly sinceMs?: number;
+  readonly limit?: number;
 };
 
-export type ConsoleDrainResult = {
-  readonly records: ConsoleRecord[];
-  readonly total: number;
-  readonly bufferOverflowed: boolean;
-};
+export type ConsoleDrainResult = DrainPage<ConsoleRecord>;
 
 export type ConsoleBuffer = {
   ingestConsoleApi(p: unknown): void;
@@ -43,7 +50,9 @@ const compileTextMatcher = (pattern: string): ((text: string) => boolean) => {
     try {
       const re = new RegExp(pattern.slice(1, -1));
       return (text) => re.test(text);
-    } catch {}
+    } catch {
+      // Not a valid regex: fall through and match the pattern as a literal substring.
+    }
   }
   return (text) => text.includes(pattern);
 };
@@ -60,7 +69,8 @@ const stringifyRemoteObject = (
     try {
       return JSON.stringify(arg.value);
     } catch {
-      return String(arg.value);
+      // Circular or BigInt payloads cannot be JSON-encoded; fall back to the CDP description.
+      return arg.description ?? arg.type ?? "";
     }
   }
   if (arg.description !== undefined) return arg.description;
@@ -69,6 +79,8 @@ const stringifyRemoteObject = (
 
 const mapConsoleApiLevel = (type: string | undefined): ConsoleLevel => {
   switch (type) {
+    case undefined:
+      return "log";
     case "error":
     case "assert":
       return "error";
@@ -86,6 +98,8 @@ const mapConsoleApiLevel = (type: string | undefined): ConsoleLevel => {
 
 const mapLogEntryLevel = (level: string | undefined): ConsoleLevel => {
   switch (level) {
+    case undefined:
+      return "info";
     case "error":
       return "error";
     case "warning":

package/src/cdp/discovery.ts

@@ -2,23 +2,28 @@ import { readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { connect as netConnect } from "node:net";
 import { request as httpRequest } from "node:http";
-import { Type } from "typebox";
-import { Compile } from "typebox/compile";
-import { parseJson } from "../schemas/parse";
 import { type Result, err, ok } from "../util/result";
 import { userDataDirCandidates } from "../profile/paths";
 import { type CdpError, cdpError } from "./errors";
-import { errnoCode } from "../util/guards";
+import { asString, errnoCode, isRecord } from "../util/guards";
+import { sleep } from "../util/sleep";
 
 const PORT_PROBE_DEADLINE_MS = 30_000;
 const PORT_PROBE_INTERVAL_MS = 1_000;
 
-const VersionResponse = Type.Object(
-  { webSocketDebuggerUrl: Type.Optional(Type.String()) },
-  { additionalProperties: true },
-);
-
-const versionValidator = Compile(VersionResponse);
+// 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;
@@ -36,24 +41,57 @@ const probePort = (port: number): Promise<Result<void, CdpError>> =>
       sock.destroy();
       resolve(r);
     };
-    sock.setTimeout(1000, () => finish(err(cdpError("discovery_failed", "probe timeout"))));
-    sock.once("error", (e) => finish(err(cdpError("discovery_failed", e.message))));
-    sock.once("connect", () => finish(ok(undefined)));
+    sock.setTimeout(1000, () => { finish(err(cdpError("discovery_failed", "probe timeout"))); });
+    sock.once("error", (e) => { finish(err(cdpError("discovery_failed", e.message))); });
+    sock.once("connect", () => { finish(ok(undefined)); });
   });
 
-const waitForPort = async (port: number): Promise<Result<void, CdpError>> => {
-  const end = Date.now() + PORT_PROBE_DEADLINE_MS;
-  let lastMessage = "unknown";
-  while (Date.now() < end) {
-    const probe = await probePort(port);
-    if (probe.success) return probe;
-    lastMessage = probe.error.message;
-    await new Promise((r) => setTimeout(r, PORT_PROBE_INTERVAL_MS));
+export type PortProbe = (port: number) => Promise<Result<void, CdpError>>;
+
+export type PortRaceOptions = {
+  readonly probe?: PortProbe;
+  readonly deadlineMs?: number;
+  readonly intervalMs?: number;
+};
+
+// Polls every candidate port at once under ONE deadline and settles on the first that answers; a stale DevToolsActivePort can no longer hold discovery for its own full deadline before the next candidate is tried.
+export const firstReadyPort = async <C extends { readonly port: number }>(
+  candidates: ReadonlyArray<C>,
+  opts: PortRaceOptions = {},
+): Promise<Result<C, CdpError>> => {
+  const probe = opts.probe ?? probePort;
+  const deadlineMs = opts.deadlineMs ?? PORT_PROBE_DEADLINE_MS;
+  const intervalMs = opts.intervalMs ?? PORT_PROBE_INTERVAL_MS;
+  if (candidates.length === 0) return err(cdpError("discovery_failed", "no DevTools port candidates to probe"));
+
+  // One controller ends every loser the moment a winner appears (or the deadline passes).
+  const stop = new AbortController();
+  const deadline = setTimeout(() => { stop.abort(); }, deadlineMs);
+  const lastMessages = new Map<number, string>();
+
+  const poll = async (c: C): Promise<C> => {
+    while (!stop.signal.aborted) {
+      const r = await probe(c.port);
+      if (r.success) return c;
+      lastMessages.set(c.port, r.error.message);
+      await sleep(intervalMs, stop.signal);
+    }
+    throw new Error(lastMessages.get(c.port) ?? "aborted");
+  };
+
+  try {
+    return ok(await Promise.any(candidates.map(poll)));
+  } catch {
+    const ports = candidates.map((k) => `127.0.0.1:${k.port}`).join(", ");
+    const detail = [...lastMessages.entries()].map(([port, m]) => `${port}: ${m}`).join("; ") || "unknown";
+    return err(cdpError(
+      "discovery_failed",
+      `Chrome's remote-debugging page is open, but DevTools is not live yet on ${ports} — if Chrome opened a profile picker, choose your normal profile first, then tick the checkbox and click Allow if shown (last error: ${detail})`,
+    ));
+  } finally {
+    clearTimeout(deadline);
+    stop.abort();
   }
-  return err(cdpError(
-    "discovery_failed",
-    `Chrome's remote-debugging page is open, but DevTools is not live yet on 127.0.0.1:${port} — if Chrome opened a profile picker, choose your normal profile first, then tick the checkbox and click Allow if shown (last error: ${lastMessage})`,
-  ));
 };
 
 const isPortLive = async (port: number): Promise<boolean> => (await probePort(port)).success;
@@ -72,13 +110,12 @@ const queryLiveWsUrl = (port: number, timeoutMs = 1_500): Promise<string | null>
         const chunks: Buffer[] = [];
         res.on("data", (c: Buffer) => chunks.push(c));
         res.on("end", () => {
-          const parsed = parseJson(Buffer.concat(chunks).toString("utf8"), versionValidator);
-          resolve(parsed.success ? parsed.data.webSocketDebuggerUrl ?? null : null);
+          resolve(parseVersionResponse(Buffer.concat(chunks).toString("utf8")));
         });
       },
     );
     req.on("timeout", () => { req.destroy(); resolve(null); });
-    req.on("error", () => resolve(null));
+    req.on("error", () => { resolve(null); });
     req.end();
   });
 
@@ -123,7 +160,9 @@ export const discoverEndpoint = async (): Promise<Result<CdpEndpoint, CdpError>>
       raw = await readFile(portFile, "utf8");
       try {
         mtimeMs = (await stat(portFile)).mtimeMs;
-      } catch {}
+      } catch {
+        // The file was readable a moment ago; without an mtime it is simply treated as fresh.
+      }
     } catch (e) {
       // EPERM/EACCES is common under sandboxes; remember it and fall back to network probing rather than failing the whole discovery.
       const code = errnoCode(e);
@@ -172,13 +211,9 @@ export const discoverEndpoint = async (): Promise<Result<CdpEndpoint, CdpError>>
   const ordered = liveCandidates.length > 0 ? liveCandidates : unique;
 
   // 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);
-    if (!ready.success) {
-      lastErr = err(ready.error);
-      continue;
-    }
+  const ready = await firstReadyPort(ordered);
+  if (ready.success) {
+    const c = ready.data;
     const liveUrl = await queryLiveWsUrl(c.port);
     return ok({ wsUrl: liveUrl ?? `ws://127.0.0.1:${c.port}${c.path}`, userDataDir: c.userDataDir });
   }
@@ -189,7 +224,7 @@ export const discoverEndpoint = async (): Promise<Result<CdpEndpoint, CdpError>>
     if (liveUrl) return ok({ wsUrl: liveUrl });
   }
 
-  return lastErr ?? err(cdpError("discovery_failed", "no live DevTools endpoint among discovered candidates"));
+  return err(ready.error);
 };
 
 export const discoverWsUrl = async (): Promise<Result<string, CdpError>> => {

package/src/cdp/events.ts

@@ -39,6 +39,11 @@ const ConsoleArg = Type.Object(
 
 export const EVENTS = {
   "Inspector.detached": ev(Anything),
+  // Browser-level notice that a session ended; carries the session id in params rather than on the envelope.
+  "Target.detachedFromTarget": ev(
+    Type.Object({ sessionId: Type.String(), targetId: Type.Optional(Type.String()) }, open),
+  ),
+  "Page.javascriptDialogClosed": ev(Anything),
 
   "Page.javascriptDialogOpening": ev(
     Type.Object(
@@ -158,13 +163,13 @@ export const decodeEvent = <E extends CdpEventName>(
   name: E,
   raw: unknown,
 ): Result<EventParamsOf<E>, CdpError> => {
+  // `name` is a key of EVENTS, so the lookup cannot miss.
   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));
   }
+  // Guarded assertion: same generic-key correlation limit as decodeResult in cdp/commands.ts.
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- sanctioned decoder, see scripts/boundary-allowlist.ts
   return ok(raw as EventParamsOf<E>);
 };

package/src/cdp/network-buffer.ts

@@ -1,37 +1,40 @@
+import { Type, type Static } from "typebox";
 import { decodeEvent, type EventParamsOf } from "./events";
-import { createRecordStore } from "./record-store";
-
-export type NetworkRecord = {
-  requestId: string;
-  method: string;
-  url: string;
-  status?: number;
-  statusText?: string;
-  type: string;
-  mimeType?: string;
-  requestStartedMs: number;
-  durationMs?: number;
-  requestBodySize: number;
-  responseBodySize?: number;
-  failed?: boolean;
-  errorText?: string;
-  body?: string | null;
-};
+import { createRecordStore, type DrainPage } from "./record-store";
+
+// Only the buffer itself may update a record in place as follow-up events arrive; everything it hands out is readonly.
+// The one declaration of a network record: the buffer produces it and browser_network_requests validates
+// replayed details against it, so the two cannot drift.
+export const NetworkRecordSchema = Type.Object({
+  requestId: Type.String(),
+  method: Type.String(),
+  url: Type.String(),
+  status: Type.Optional(Type.Number()),
+  statusText: Type.Optional(Type.String()),
+  type: Type.String(),
+  mimeType: Type.Optional(Type.String()),
+  requestStartedMs: Type.Number(),
+  durationMs: Type.Optional(Type.Number()),
+  requestBodySize: Type.Number(),
+  responseBodySize: Type.Optional(Type.Number()),
+  failed: Type.Optional(Type.Boolean()),
+  errorText: Type.Optional(Type.String()),
+  body: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+});
+
+type MutableNetworkRecord = Static<typeof NetworkRecordSchema>;
+export type NetworkRecord = Readonly<MutableNetworkRecord>;
 
 export type NetworkFilter = {
-  urlPattern?: string;
-  methodFilter?: string[];
-  statusFilter?: { min?: number; max?: number };
-  resourceTypes?: string[];
-  sinceMs?: number;
-  limit?: number;
+  readonly urlPattern?: string;
+  readonly methodFilter?: ReadonlyArray<string>;
+  readonly statusFilter?: { readonly min?: number; readonly max?: number };
+  readonly resourceTypes?: ReadonlyArray<string>;
+  readonly sinceMs?: number;
+  readonly limit?: number;
 };
 
-export type DrainResult = {
-  readonly records: NetworkRecord[];
-  readonly total: number;
-  readonly bufferOverflowed: boolean;
-};
+export type DrainResult = DrainPage<NetworkRecord>;
 
 export type NetworkBuffer = {
   ingestRequestWillBeSent(p: unknown): void;
@@ -47,7 +50,9 @@ const compileUrlMatcher = (pattern: string): ((url: string) => boolean) => {
     try {
       const re = new RegExp(pattern.slice(1, -1));
       return (url) => re.test(url);
-    } catch {}
+    } catch {
+      // Not a valid regex: fall through and match the pattern as a literal substring.
+    }
   }
   return (url) => url.includes(pattern);
 };
@@ -55,13 +60,13 @@ const compileUrlMatcher = (pattern: string): ((url: string) => boolean) => {
 type UpdateEvent = "Network.responseReceived" | "Network.loadingFinished" | "Network.loadingFailed";
 
 export const createNetworkBuffer = (capacity = 500): NetworkBuffer => {
-  const records = createRecordStore<string, NetworkRecord>(capacity);
+  const records = createRecordStore<string, MutableNetworkRecord>(capacity);
 
   // All three follow-up events say the same thing first: decode, find the request they belong to, give up quietly if it is gone.
   const update = <E extends UpdateEvent>(
     method: E,
     p: unknown,
-    apply: (r: NetworkRecord, params: EventParamsOf<E>) => void,
+    apply: (r: MutableNetworkRecord, params: EventParamsOf<E>) => void,
   ): void => {
     const decoded = decodeEvent(method, p);
     if (!decoded.success) return;
@@ -80,6 +85,7 @@ export const createNetworkBuffer = (capacity = 500): NetworkBuffer => {
       const url = params?.request.url;
       const method = params?.request.method;
       if (!id || !url || !method) return;
+      // Delete before set: the store evicts by insertion order, so a request id that is re-sent (redirects reuse it) must move to the newest slot rather than keep its old age.
       records.delete(id);
       const postData = params.request.postData;
       records.set(id, {

package/src/cdp/ownership.ts

@@ -8,7 +8,8 @@ export type OwnershipRegistry = {
   harnessWindow(): string | undefined;
   setHarnessWindowId(windowId: number | undefined): void;
   harnessWindowId(): number | undefined;
-  onChange(cb: () => void): void;
+  // Subscribe; the returned function unsubscribes. Several subscribers may be registered at once.
+  onChange(cb: () => void): () => void;
 };
 
 export const createOwnershipRegistry = (
@@ -21,10 +22,11 @@ export const createOwnershipRegistry = (
   const owned = new Set<string>(initial?.ownedTargetIds ?? []);
   let harnessWindow: string | undefined = initial?.harnessWindowTargetId;
   let harnessWindowId: number | undefined = initial?.harnessWindowId;
-  let listener: (() => void) | null = null;
+  const listeners = new Set<() => void>();
 
   const notify = (): void => {
-    if (listener) listener();
+    // Snapshot so a listener that unsubscribes (or subscribes) mid-notify does not disturb the iteration.
+    for (const cb of [...listeners]) cb();
   };
 
   return {
@@ -67,7 +69,23 @@ export const createOwnershipRegistry = (
       return harnessWindowId;
     },
     onChange(cb) {
-      listener = cb;
+      listeners.add(cb);
+      return () => {
+        listeners.delete(cb);
+      };
     },
   };
 };
+
+// Drops owned targets (and the harness window) that no longer exist in the browser. Returns the owned ids that survived.
+export const reconcileOwnership = (
+  ownership: OwnershipRegistry,
+  liveTargetIds: ReadonlySet<string>,
+): ReadonlyArray<string> => {
+  const owned = ownership.list();
+  const survivors = owned.filter((id) => liveTargetIds.has(id));
+  if (survivors.length !== owned.length) ownership.replaceAll(survivors);
+  const hw = ownership.harnessWindow();
+  if (hw !== undefined && !liveTargetIds.has(hw)) ownership.setHarnessWindow(undefined);
+  return survivors;
+};

package/src/cdp/record-store.ts

@@ -1,5 +1,5 @@
 export type DrainPage<T> = {
-  readonly records: T[];
+  readonly records: ReadonlyArray<T>;
   readonly total: number;
   readonly bufferOverflowed: boolean;
 };
@@ -10,7 +10,7 @@ export type RecordStore<K, T> = {
   delete(key: K): void;
   values(): IterableIterator<T>;
   // Takes the overflow flag as it pages, so each drain reports only the loss since the previous one.
-  page(matched: T[], limit: number | undefined): DrainPage<T>;
+  page(matched: ReadonlyArray<T>, limit: number | undefined): DrainPage<T>;
   clear(): void;
 };