pi-browser-harness 0.10.2 → 0.12.0

package/src/cdp/network-buffer.ts

@@ -1,18 +1,5 @@
-/**
- * In-memory aggregator for CDP Network.* events.
- *
- * The CDP event stream is consumed by a single internal loop in session.ts.
- * That loop hands Network.* event params to this module, which joins them into
- * one record per requestId (request → response → finished/failed). Tools then
- * read records via drain(), filtered to what the caller asked for.
- *
- * Bounded by a fixed capacity (default 500): on overflow the oldest record is
- * evicted FIFO. The overflow flag is reported once per drain so tools can warn
- * the LLM that data may be missing.
- *
- * This module is pure (no CDP dependency) so the joining/filtering logic stays
- * trivially testable in isolation.
- */
+import { decodeEvent, type EventParamsOf } from "./events";
+import { createRecordStore } from "./record-store";
 
 export type NetworkRecord = {
   requestId: string;
@@ -22,34 +9,27 @@ export type NetworkRecord = {
   statusText?: string;
   type: string;
   mimeType?: string;
-  /** Wall-clock ms when requestWillBeSent fired, in Date.now() units. */
   requestStartedMs: number;
   durationMs?: number;
   requestBodySize: number;
   responseBodySize?: number;
   failed?: boolean;
   errorText?: string;
-  /** Populated by the tool layer via Network.getResponseBody, never by the aggregator. */
   body?: string | null;
 };
 
 export type NetworkFilter = {
-  /** Substring match by default. Wrap in slashes (`/foo/`) for regex. */
   urlPattern?: string;
   methodFilter?: string[];
   statusFilter?: { min?: number; max?: number };
   resourceTypes?: string[];
-  /** Only requests whose start is at most N ms ago. */
   sinceMs?: number;
-  /** Cap on the returned records. */
   limit?: number;
 };
 
 export type DrainResult = {
   readonly records: NetworkRecord[];
-  /** 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;
 };
 
@@ -67,53 +47,41 @@ const compileUrlMatcher = (pattern: string): ((url: string) => boolean) => {
     try {
       const re = new RegExp(pattern.slice(1, -1));
       return (url) => re.test(url);
-    } catch {
-      // Fall through to substring match if the pattern is not a valid regex.
-    }
+    } catch {}
   }
   return (url) => url.includes(pattern);
 };
 
+type UpdateEvent = "Network.responseReceived" | "Network.loadingFinished" | "Network.loadingFailed";
+
 export const createNetworkBuffer = (capacity = 500): NetworkBuffer => {
-  // Insertion-ordered map keyed by requestId. Map preserves insertion order in JS,
-  // so iteration gives us oldest-first eviction without a separate index.
-  const records = new Map<string, NetworkRecord>();
-  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 records = createRecordStore<string, NetworkRecord>(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,
+  ): void => {
+    const decoded = decodeEvent(method, p);
+    if (!decoded.success) return;
+    const id = decoded.data.requestId;
+    if (!id) return;
+    const r = records.get(id);
+    if (!r) return;
+    apply(r, decoded.data);
   };
 
   return {
     ingestRequestWillBeSent(p) {
-      // CDP boundary cast: Network.requestWillBeSent
-      const params = p as
-        | {
-            requestId?: string;
-            request?: {
-              url?: string;
-              method?: string;
-              postData?: string;
-              headers?: Record<string, string>;
-            };
-            type?: string;
-            timestamp?: number;
-            wallTime?: number;
-          }
-        | undefined;
+      const decoded = decodeEvent("Network.requestWillBeSent", p);
+      const params = decoded.success ? decoded.data : undefined;
       const id = params?.requestId;
-      const url = params?.request?.url;
-      const method = params?.request?.method;
+      const url = params?.request.url;
+      const method = params?.request.method;
       if (!id || !url || !method) return;
-      // Re-fired requestWillBeSent for the same id (e.g. redirect) — refresh in place.
       records.delete(id);
-      evictOldestIfFull();
-      const postData = params.request?.postData;
+      const postData = params.request.postData;
       records.set(id, {
         requestId: id,
         method,
@@ -125,54 +93,28 @@ export const createNetworkBuffer = (capacity = 500): NetworkBuffer => {
     },
 
     ingestResponseReceived(p) {
-      // CDP boundary cast: Network.responseReceived
-      const params = p as
-        | {
-            requestId?: string;
-            response?: {
-              status?: number;
-              statusText?: string;
-              mimeType?: string;
-            };
-            type?: string;
-          }
-        | undefined;
-      const id = params?.requestId;
-      if (!id) return;
-      const r = records.get(id);
-      if (!r) return;
-      if (params?.response?.status !== undefined) r.status = params.response.status;
-      if (params?.response?.statusText !== undefined && params.response.statusText !== "") r.statusText = params.response.statusText;
-      if (params?.response?.mimeType !== undefined) r.mimeType = params.response.mimeType;
-      // type is more accurate on responseReceived (CDP sometimes refines it)
-      if (params?.type !== undefined) r.type = params.type;
+      update("Network.responseReceived", p, (r, params) => {
+        if (params.response?.status !== undefined) r.status = params.response.status;
+        if (params.response?.statusText !== undefined && params.response.statusText !== "") r.statusText = params.response.statusText;
+        if (params.response?.mimeType !== undefined) r.mimeType = params.response.mimeType;
+        // type is more accurate on responseReceived (CDP sometimes refines it)
+        if (params.type !== undefined) r.type = params.type;
+      });
     },
 
     ingestLoadingFinished(p) {
-      // CDP boundary cast: Network.loadingFinished
-      const params = p as
-        | { requestId?: string; encodedDataLength?: number }
-        | undefined;
-      const id = params?.requestId;
-      if (!id) return;
-      const r = records.get(id);
-      if (!r) return;
-      if (params?.encodedDataLength !== undefined) r.responseBodySize = params.encodedDataLength;
-      r.durationMs = Date.now() - r.requestStartedMs;
+      update("Network.loadingFinished", p, (r, params) => {
+        if (params.encodedDataLength !== undefined) r.responseBodySize = params.encodedDataLength;
+        r.durationMs = Date.now() - r.requestStartedMs;
+      });
     },
 
     ingestLoadingFailed(p) {
-      // CDP boundary cast: Network.loadingFailed
-      const params = p as
-        | { requestId?: string; errorText?: string; canceled?: boolean }
-        | undefined;
-      const id = params?.requestId;
-      if (!id) return;
-      const r = records.get(id);
-      if (!r) return;
-      r.failed = true;
-      if (params?.errorText !== undefined) r.errorText = params.errorText;
-      r.durationMs = Date.now() - r.requestStartedMs;
+      update("Network.loadingFailed", p, (r, params) => {
+        r.failed = true;
+        if (params.errorText !== undefined) r.errorText = params.errorText;
+        r.durationMs = Date.now() - r.requestStartedMs;
+      });
     },
 
     drain(filter) {
@@ -191,23 +133,14 @@ export const createNetworkBuffer = (capacity = 500): NetworkBuffer => {
         if (cutoff !== undefined && r.requestStartedMs < cutoff) continue;
         if (minStatus !== undefined && (r.status === undefined || r.status < minStatus)) continue;
         if (maxStatus !== undefined && (r.status === undefined || r.status > maxStatus)) continue;
-        // Clone so callers can mutate (e.g. attach body) without polluting the buffer.
         matched.push({ ...r });
       }
 
-      const total = matched.length;
-      const limit = Math.min(filter.limit ?? 50, 500);
-      const limited = matched.slice(-limit); // most recent N
-
-      const bufferOverflowed = overflowed;
-      overflowed = false;
-
-      return { records: limited, total, bufferOverflowed };
+      return records.page(matched, filter.limit);
     },
 
     clear() {
       records.clear();
-      overflowed = false;
     },
   };
 };

package/src/cdp/ownership.ts

@@ -1,28 +1,11 @@
-/**
- * Tracks which tab targetIds belong to this harness session.
- *
- * The harness attaches to the user's running Chrome, which is also full of
- * the user's own tabs. Without an ownership boundary the agent could attach
- * to (or close) personal tabs by accident. The registry is the single source
- * of truth for "did this session open that tab?".
- *
- * Mutations notify a single change listener so the orchestrator can persist
- * to disk via the existing BrowserState flow without the registry needing to
- * know about the pi storage API.
- */
-
 export type OwnershipRegistry = {
   add(targetId: string): void;
   remove(targetId: string): void;
   has(targetId: string): boolean;
   list(): ReadonlyArray<string>;
-  /** Replace the full set — used on restoreState to re-hydrate from disk. */
   replaceAll(ids: ReadonlyArray<string>): void;
   setHarnessWindow(targetId: string | undefined): void;
   harnessWindow(): string | undefined;
-  /** The real Chrome windowId of the dedicated harness window — the durable
-   *  identity of "the window this session initialized", surviving seed-tab
-   *  closure. Undefined until the window is created (or after teardown). */
   setHarnessWindowId(windowId: number | undefined): void;
   harnessWindowId(): number | undefined;
   onChange(cb: () => void): void;

package/src/cdp/record-store.ts

@@ -0,0 +1,61 @@
+export type DrainPage<T> = {
+  readonly records: T[];
+  readonly total: number;
+  readonly bufferOverflowed: boolean;
+};
+
+export type RecordStore<K, T> = {
+  set(key: K, rec: T): void;
+  get(key: K): T | undefined;
+  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>;
+  clear(): void;
+};
+
+const MAX_LIMIT = 500;
+const DEFAULT_LIMIT = 50;
+
+export const createRecordStore = <K, T>(capacity: number): RecordStore<K, T> => {
+  const records = new Map<K, T>();
+  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;
+    }
+  };
+
+  return {
+    set(key, rec) {
+      evictOldestIfFull();
+      records.set(key, rec);
+    },
+    get(key) {
+      return records.get(key);
+    },
+    delete(key) {
+      records.delete(key);
+    },
+    values() {
+      return records.values();
+    },
+    page(matched, limit) {
+      const bufferOverflowed = overflowed;
+      overflowed = false;
+      return {
+        records: matched.slice(-Math.min(limit ?? DEFAULT_LIMIT, MAX_LIMIT)),
+        total: matched.length,
+        bufferOverflowed,
+      };
+    },
+    clear() {
+      records.clear();
+      overflowed = false;
+    },
+  };
+};