pi-browser-harness 0.3.2 → 0.5.0

package/src/cdp/network-buffer.ts

@@ -0,0 +1,213 @@
+/**
+ * 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.
+ */
+
+export type NetworkRecord = {
+  requestId: string;
+  method: string;
+  url: string;
+  status?: number;
+  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;
+};
+
+export type NetworkBuffer = {
+  ingestRequestWillBeSent(p: unknown): void;
+  ingestResponseReceived(p: unknown): void;
+  ingestLoadingFinished(p: unknown): void;
+  ingestLoadingFailed(p: unknown): void;
+  drain(filter: NetworkFilter): DrainResult;
+  clear(): void;
+};
+
+const compileUrlMatcher = (pattern: string): ((url: string) => boolean) => {
+  if (pattern.length >= 2 && pattern.startsWith("/") && pattern.endsWith("/")) {
+    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.
+    }
+  }
+  return (url) => url.includes(pattern);
+};
+
+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;
+    }
+  };
+
+  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 id = params?.requestId;
+      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;
+      records.set(id, {
+        requestId: id,
+        method,
+        url,
+        type: params.type ?? "Other",
+        requestStartedMs: Date.now(),
+        requestBodySize: postData ? Buffer.byteLength(postData, "utf8") : 0,
+      });
+    },
+
+    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;
+    },
+
+    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;
+    },
+
+    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;
+    },
+
+    drain(filter) {
+      const matchUrl = filter.urlPattern !== undefined ? compileUrlMatcher(filter.urlPattern) : undefined;
+      const methods = filter.methodFilter ? new Set(filter.methodFilter.map((m) => m.toUpperCase())) : undefined;
+      const types = filter.resourceTypes ? new Set(filter.resourceTypes.map((t) => t.toLowerCase())) : undefined;
+      const minStatus = filter.statusFilter?.min;
+      const maxStatus = filter.statusFilter?.max;
+      const cutoff = filter.sinceMs !== undefined ? Date.now() - filter.sinceMs : undefined;
+
+      const matched: NetworkRecord[] = [];
+      for (const r of records.values()) {
+        if (matchUrl && !matchUrl(r.url)) continue;
+        if (methods && !methods.has(r.method.toUpperCase())) continue;
+        if (types && !types.has(r.type.toLowerCase())) continue;
+        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 };
+    },
+
+    clear() {
+      records.clear();
+      overflowed = false;
+    },
+  };
+};

package/src/cdp/ownership.ts

@@ -0,0 +1,72 @@
+/**
+ * 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;
+  onChange(cb: () => void): void;
+};
+
+export const createOwnershipRegistry = (
+  initial?: { readonly ownedTargetIds?: ReadonlyArray<string>; readonly harnessWindowTargetId?: string },
+): OwnershipRegistry => {
+  const owned = new Set<string>(initial?.ownedTargetIds ?? []);
+  let harnessWindow: string | undefined = initial?.harnessWindowTargetId;
+  let listener: (() => void) | null = null;
+
+  const notify = (): void => {
+    if (listener) listener();
+  };
+
+  return {
+    add(targetId) {
+      if (owned.has(targetId)) return;
+      owned.add(targetId);
+      notify();
+    },
+    remove(targetId) {
+      if (!owned.has(targetId) && harnessWindow !== targetId) return;
+      owned.delete(targetId);
+      if (harnessWindow === targetId) harnessWindow = undefined;
+      notify();
+    },
+    has(targetId) {
+      return owned.has(targetId);
+    },
+    list() {
+      return [...owned];
+    },
+    replaceAll(ids) {
+      owned.clear();
+      for (const id of ids) owned.add(id);
+      notify();
+    },
+    setHarnessWindow(targetId) {
+      if (harnessWindow === targetId) return;
+      harnessWindow = targetId;
+      notify();
+    },
+    harnessWindow() {
+      return harnessWindow;
+    },
+    onChange(cb) {
+      listener = cb;
+    },
+  };
+};

package/src/cdp/session.ts

@@ -1,8 +1,23 @@
-import { type Result, err, ok } from "../util/result";
-import { type CdpError, cdpError } from "./errors";
+import { type Result, ok } from "../util/result";
+import type { CdpError } from "./errors";
 import type { DialogInfo } from "./types";
-import { isInternalUrl } from "./types";
+import type { OwnershipRegistry } from "./ownership";
 import type { CdpTransport } from "./transport";
+import { createNetworkBuffer, type DrainResult, type NetworkFilter } from "./network-buffer";
+import { createConsoleBuffer, type ConsoleDrainResult, type ConsoleFilter } from "./console-buffer";
+
+// Per-tab state. One TabSession exists per known targetId.
+// Dialog, page-info dirty flag, and CDP buffers are per-tab — switching
+// tabs preserves the previous tab's data in its TabSession instead of
+// clearing it.
+type TabSession = {
+  sessionId: string;
+  targetId: string;
+  dialog: DialogInfo | null;
+  pageInfoDirty: boolean;
+  networkBuffer: ReturnType<typeof createNetworkBuffer>;
+  consoleBuffer: ReturnType<typeof createConsoleBuffer>;
+};
 
 export type CdpSession = {
   attachFirstPage(): Promise<Result<{ readonly targetId: string; readonly sessionId: string }, CdpError>>;
@@ -13,21 +28,43 @@ export type CdpSession = {
   callBrowser(method: string, params?: Record<string, unknown>, opts?: { timeoutMs?: number }): Promise<Result<unknown, CdpError>>;
   takeDialog(): DialogInfo | null;
   drainPageInfoInvalidations(): boolean;
+  drainNetworkBuffer(filter: NetworkFilter): DrainResult;
+  drainConsoleBuffer(filter: ConsoleFilter): ConsoleDrainResult;
 };
 
-export const createCdpSession = (transport: CdpTransport): CdpSession => {
+export const createCdpSession = (
+  transport: CdpTransport,
+  ownership?: OwnershipRegistry,
+): CdpSession => {
   let sessionId: string | null = null;
   let targetId: string | null = null;
-  let dialog: DialogInfo | null = null;
-  let pageInfoDirty = false;
+
+  // Per-tab tracking: maps targetId → TabSession and sessionId → targetId for
+  // event routing. Lazy: a TabSession is created on the first visit to a tab.
+  const tabs = new Map<string, TabSession>();
+  const sessionIdToTargetId = new Map<string, string>();
 
   let activeConsumer: Promise<void> = Promise.resolve();
 
+  // Event → TabSession resolver. Uses sessionId from CDP events to find the
+  // correct TabSession, falling back to the current targetId when no sessionId.
+  const resolveTab = (evSessionId?: string): TabSession | undefined => {
+    const tid = evSessionId ? sessionIdToTargetId.get(evSessionId) : targetId;
+    return tid ? tabs.get(tid) : undefined;
+  };
+
   const consumeEvents = async (): Promise<void> => {
     for await (const ev of transport.events()) {
+      // Filter: skip events from sessions we're not currently tracking.
+      // Target.targetDestroyed is browser-level (no sessionId) — always process.
+      if (ev.method !== "Target.targetDestroyed") {
+        if (ev.sessionId && ev.sessionId !== sessionId) continue;
+      }
       if (ev.method === "Page.javascriptDialogOpening") {
+        const tab = targetId ? tabs.get(targetId) : undefined;
+        if (!tab) continue;
         const params = ev.params as Partial<DialogInfo> | undefined;
-        dialog = {
+        tab.dialog = {
           type: (params?.type as DialogInfo["type"]) ?? "alert",
           message: params?.message ?? "",
           ...(params?.defaultPrompt !== undefined ? { defaultPrompt: params.defaultPrompt } : {}),
@@ -39,7 +76,39 @@ export const createCdpSession = (transport: CdpTransport): CdpSession => {
       // This prevents fast dismiss flows from dropping a dialog the agent
       // was about to read. (Fix for spec §7 predictability bug #2.)
       if (ev.method === "Page.frameNavigated" || ev.method === "Page.loadEventFired") {
-        pageInfoDirty = true;
+        const tab = targetId ? tabs.get(targetId) : undefined;
+        if (tab) tab.pageInfoDirty = true;
+      }
+      if (ev.method === "Target.targetDestroyed" && ownership) {
+        const params = ev.params as { targetId?: string } | undefined;
+        if (params?.targetId) {
+          ownership.remove(params.targetId);
+          // Prune per-tab state for the destroyed target
+          const tab = tabs.get(params.targetId);
+          if (tab) {
+            sessionIdToTargetId.delete(tab.sessionId);
+            tabs.delete(params.targetId);
+          }
+        }
+      }
+      if (ev.method === "Network.requestWillBeSent") {
+        const tab = resolveTab(ev.sessionId);
+        if (tab) tab.networkBuffer.ingestRequestWillBeSent(ev.params);
+      } else if (ev.method === "Network.responseReceived") {
+        const tab = resolveTab(ev.sessionId);
+        if (tab) tab.networkBuffer.ingestResponseReceived(ev.params);
+      } else if (ev.method === "Network.loadingFinished") {
+        const tab = resolveTab(ev.sessionId);
+        if (tab) tab.networkBuffer.ingestLoadingFinished(ev.params);
+      } else if (ev.method === "Network.loadingFailed") {
+        const tab = resolveTab(ev.sessionId);
+        if (tab) tab.networkBuffer.ingestLoadingFailed(ev.params);
+      } else if (ev.method === "Runtime.consoleAPICalled") {
+        const tab = resolveTab(ev.sessionId);
+        if (tab) tab.consoleBuffer.ingestConsoleApi(ev.params);
+      } else if (ev.method === "Log.entryAdded") {
+        const tab = resolveTab(ev.sessionId);
+        if (tab) tab.consoleBuffer.ingestLogEntry(ev.params);
       }
     }
   };
@@ -58,7 +127,8 @@ export const createCdpSession = (transport: CdpTransport): CdpSession => {
   transport.onClose(() => {
     sessionId = null;
     targetId = null;
-    pageInfoDirty = false;
+    tabs.clear();
+    sessionIdToTargetId.clear();
     // Do NOT clear `dialog` here — same rationale as inside consumeEvents:
     // the agent may have a pending takeDialog() call that should still see it.
     restartConsumer();
@@ -68,7 +138,7 @@ export const createCdpSession = (transport: CdpTransport): CdpSession => {
   // Switching to Promise.all over a single WS pipelines the round-trips and
   // saves ~3× on tab-switch latency. Defer until session.ts has tests.
   const enableDomains = async (sid: string): Promise<void> => {
-    for (const d of ["Page", "DOM", "Runtime", "Network"]) {
+    for (const d of ["Page", "DOM", "Runtime", "Network", "Accessibility", "Log"]) {
       await transport.request(`${d}.enable`, {}, { sessionId: sid });
     }
   };
@@ -81,25 +151,69 @@ export const createCdpSession = (transport: CdpTransport): CdpSession => {
   // as a clear Error in normal use.
   return {
     async attachFirstPage() {
+      // Subscribe to Target.* events so we can react to targetDestroyed.
+      // Best-effort: failing to enable discovery is not fatal for attach.
+      await transport.request("Target.setDiscoverTargets", { discover: true }, { sessionId: null });
+
       const targets = await transport.request("Target.getTargets", {}, { sessionId: null });
       if (!targets.success) return targets;
       const data = targets.data as { targetInfos: ReadonlyArray<{ targetId: string; type: string; url: string }> };
-      let pages = data.targetInfos.filter((t) => t.type === "page" && !isInternalUrl(t.url));
-      if (pages.length === 0) {
-        const created = await transport.request("Target.createTarget", { url: "about:blank" }, { sessionId: null });
+      const allPages = data.targetInfos.filter((t) => t.type === "page");
+      // Reconcile the persisted ownership set against live targets — drop dead IDs.
+      if (ownership) {
+        const live = new Set(allPages.map((p) => p.targetId));
+        const survivors = ownership.list().filter((id) => live.has(id));
+        if (survivors.length !== ownership.list().length) ownership.replaceAll(survivors);
+        const hw = ownership.harnessWindow();
+        if (hw && !live.has(hw)) ownership.setHarnessWindow(undefined);
+      }
+      // Prune per-tab state for pages that no longer exist
+      const liveTargetIds = new Set(allPages.map((p) => p.targetId));
+      for (const tid of tabs.keys()) {
+        if (!liveTargetIds.has(tid)) {
+          const tab = tabs.get(tid);
+          if (tab) sessionIdToTargetId.delete(tab.sessionId);
+          tabs.delete(tid);
+        }
+      }
+
+      // Prefer attaching to a tab this session already owns. Falls back to
+      // creating a fresh harness-owned tab in a dedicated window — never
+      // grabs the user's foreground tab.
+      let pickTargetId: string | undefined;
+      if (ownership) {
+        const ownedLive = ownership.list().filter((id) => allPages.some((p) => p.targetId === id));
+        pickTargetId = ownedLive[0];
+      }
+      if (!pickTargetId) {
+        const createParams: Record<string, unknown> = { url: "about:blank" };
+        if (ownership) createParams["newWindow"] = true;
+        const created = await transport.request("Target.createTarget", createParams, { sessionId: null });
         if (!created.success) return created;
         const c = created.data as { targetId: string };
-        pages = [{ targetId: c.targetId, type: "page", url: "about:blank" }];
+        pickTargetId = c.targetId;
+        if (ownership) {
+          ownership.setHarnessWindow(c.targetId);
+          ownership.add(c.targetId);
+        }
       }
-      const first = pages[0];
-      if (!first) return err(cdpError("invalid_response", "no page targets after creation"));
-      const attached = await transport.request("Target.attachToTarget", { targetId: first.targetId, flatten: true }, { sessionId: null });
+
+      const attached = await transport.request("Target.attachToTarget", { targetId: pickTargetId, flatten: true }, { sessionId: null });
       if (!attached.success) return attached;
       const a = attached.data as { sessionId: string };
       sessionId = a.sessionId;
-      targetId = first.targetId;
+      targetId = pickTargetId;
       await enableDomains(a.sessionId);
-      return ok({ targetId: first.targetId, sessionId: a.sessionId });
+      tabs.set(pickTargetId, {
+        sessionId: a.sessionId,
+        targetId: pickTargetId,
+        dialog: null,
+        pageInfoDirty: false,
+        networkBuffer: createNetworkBuffer(),
+        consoleBuffer: createConsoleBuffer(),
+      });
+      sessionIdToTargetId.set(a.sessionId, pickTargetId);
+      return ok({ targetId: pickTargetId, sessionId: a.sessionId });
     },
     async switchTo(tid) {
       const activated = await transport.request("Target.activateTarget", { targetId: tid }, { sessionId: null });
@@ -107,10 +221,29 @@ export const createCdpSession = (transport: CdpTransport): CdpSession => {
       const attached = await transport.request("Target.attachToTarget", { targetId: tid, flatten: true }, { sessionId: null });
       if (!attached.success) return attached;
       const a = attached.data as { sessionId: string };
-      sessionId = a.sessionId;
+      // Reuse existing TabSession or create one on first visit
+      const existing = tabs.get(tid);
+      const tab: TabSession = existing ?? {
+        sessionId: a.sessionId,
+        targetId: tid,
+        dialog: null,
+        pageInfoDirty: true,
+        networkBuffer: createNetworkBuffer(),
+        consoleBuffer: createConsoleBuffer(),
+      };
+      if (existing) {
+        // Each Target.attachToTarget produces a new sessionId — update it.
+        sessionIdToTargetId.delete(existing.sessionId);
+        existing.sessionId = a.sessionId;
+        sessionIdToTargetId.set(a.sessionId, tid);
+      } else {
+        tabs.set(tid, tab);
+        await enableDomains(a.sessionId);
+        sessionIdToTargetId.set(a.sessionId, tid);
+      }
+      // Update global pointers to point at the new active tab
+      sessionId = tab.sessionId;
       targetId = tid;
-      pageInfoDirty = true;
-      await enableDomains(a.sessionId);
       return ok(undefined);
     },
     current() {
@@ -126,14 +259,28 @@ export const createCdpSession = (transport: CdpTransport): CdpSession => {
       return transport.request(method, params, { sessionId: null, ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}) });
     },
     takeDialog() {
-      const d = dialog;
-      dialog = null;
+      const tab = targetId ? tabs.get(targetId) : undefined;
+      if (!tab) return null;
+      const d = tab.dialog;
+      tab.dialog = null;
       return d;
     },
     drainPageInfoInvalidations() {
-      const dirty = pageInfoDirty;
-      pageInfoDirty = false;
+      const tab = targetId ? tabs.get(targetId) : undefined;
+      if (!tab) return false;
+      const dirty = tab.pageInfoDirty;
+      tab.pageInfoDirty = false;
       return dirty;
     },
+    drainNetworkBuffer(filter) {
+      const tab = targetId ? tabs.get(targetId) : undefined;
+      if (!tab) return { records: [], total: 0, bufferOverflowed: false };
+      return tab.networkBuffer.drain(filter);
+    },
+    drainConsoleBuffer(filter) {
+      const tab = targetId ? tabs.get(targetId) : undefined;
+      if (!tab) return { records: [], total: 0, bufferOverflowed: false };
+      return tab.consoleBuffer.drain(filter);
+    },
   };
 };

package/src/cdp/types.ts

@@ -23,6 +23,7 @@ export type TabInfo = {
   readonly targetId: string;
   readonly title: string;
   readonly url: string;
+  readonly owned?: boolean;
 };
 
 export type PageInfo = {