pi-browser-harness 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 All notable changes to pi-browser-harness will be documented in this file.
 
+## 0.4.0 — 2026-05-06
+
+### Added
+
+- **`browser_snapshot`** — new tool. Returns the structured CDP accessibility tree (roles, names, states, hierarchy) for the current page. For every interactive element (button, link, textbox, checkbox, etc.) the outline includes click coordinates as `@(x,y)`, fetched via `DOM.getBoxModel` per node in parallel under a 1.5s aggregate budget. Pass these straight to `browser_click` — no `browser_screenshot` round-trip needed. `format:"json"` returns the slim structure with `box: {x,y,width,height,cx,cy}` per node. Optional `includeScreenshot:true` attaches a JPEG (q=80) when visual confirmation is also wanted.
+- **`browser_network_requests`** — new tool, replacing the deprecated `browser_get_network_log` placeholder. Lists requests captured on the current tab since attach with filters: `urlPattern` (substring; wrap in slashes for regex), `methodFilter`, `statusFilter`, `resourceTypes`, `sinceMs`, `limit` (default 50, cap 500). `includeResponseBodies:true` fetches `Network.getResponseBody` per matched record under a 5s aggregate budget with a 50 KB per-body cap. Buffer is page-scoped (cleared on tab switch) and bounded at 500 records; `bufferOverflowed` flag in the result reports drops since the last drain.
+- **Tab ownership / harness-window isolation.** New `OwnershipRegistry` tracks which page targets this session opened. The harness now creates a dedicated Chrome window on first attach (`newWindow:true`) instead of grabbing the user's foreground tab; subsequent `browser_new_tab` calls open inside that window via `openerId`. `browser_list_tabs` defaults to `scope:"owned"`; pass `scope:"all"` to see the user's other tabs read-only. `browser_switch_tab` and the new **`browser_close_tab`** refuse non-owned tabs with a clear remediation hint. Ownership is persisted across session reloads via `BrowserState`. The session also subscribes `Target.setDiscoverTargets` and reaps `targetDestroyed` events so the registry stays in sync.
+- **`Accessibility` CDP domain enabled** alongside Page/DOM/Runtime/Network on every attach.
+- **`Ctrl+O` (`app.tools.expand`) expand/collapse on tool output.** Three tools now ship custom `renderResult`:
+  - `browser_snapshot` — collapsed: 4-line summary (node count, URL, landmarks/buttons/inputs, screenshot status). Expanded: full indented outline + inline screenshot when `includeScreenshot:true`.
+  - `browser_network_requests` — collapsed: header + first 5 rows. Expanded: full markdown table + per-request body sections when bodies were requested.
+  - `browser_execute_js` — collapsed: size + first 120-char preview. Expanded: pretty-printed JSON if value parses, otherwise raw value, in a code fence.
+  All three append a `keyHint("app.tools.expand", ...)` so the binding label adapts to user remaps.
+
+### Changed
+
+- **Tool prompts pivoted from screenshot-first to snapshot-first.** `browser_screenshot`'s description now explicitly says "NOT a default exploration tool". `browser_snapshot` is documented as the default for understanding pages; `browser_execute_js` as the default for surgical reads. `browser_click` guidance no longer instructs the agent to screenshot for coordinates — it points at `browser_snapshot`'s `@(x,y)` hints. `browser_open_urls` post-step flipped from screenshot to snapshot.
+- **`SKILL.md` rewritten** (~342 lines → ~53 lines). Frontmatter description carries the tool-hierarchy hint (always in context per pi's progressive-disclosure model). Body keeps only what isn't already in tool prompts: the decision tree, the connection rules (real Chrome, no creds, dialog-first), and the `browser_run_script` daemon bindings (the only tool whose API can't be inferred from its prompt). Pattern reference, parallelization details, troubleshooting, and tool enumeration removed as duplication.
+- **CDP `Network.*` events** are now consumed by an in-process aggregator (`src/cdp/network-buffer.ts`) wired into the existing single-consumer event loop in `src/cdp/session.ts`. Pure module, ring-buffered, non-destructive drain.
+
+### Removed
+
+- **`browser_get_network_log`** — was a deprecated placeholder in v0.3 that returned a "use PerformanceObserver" message because the CDP event stream had no public drain API. Replaced by `browser_network_requests`.
+
+### Known follow-ups
+
+- Live network streaming (`browser_network_monitor` real-time during a click) — deferred; reuses the same buffer plumbing once the post-hoc form is proven.
+- No tests added in this release. Verification is manual against real Chrome.
+
+## 0.3.2 — 2026-05-05
+
+### Added
+
+- **Parallel tool execution with automatic mutation serialization.** Observation tools (`browser_screenshot`, `browser_page_info`, `browser_execute_js`, `browser_list_tabs`, `browser_http_get` etc.) can now run in parallel with each other and with mutation tools. Mutation tools (`browser_click`, `browser_type`, `browser_scroll`, `browser_navigate`, `browser_switch_tab`, etc.) are automatically serialized through a shared async mutex so they never race on shared CDP session/page state. LLMs can emit independent operations in the same turn for better latency.
+- **New `src/util/mutex.ts`** — lightweight async mutex (~25 LOC) with FIFO queue. `serialized?: boolean` flag added to `BrowserToolDefinition`; `mutationMutex()` exposed on `BrowserClient`.
+- **Prompt and SKILL.md** updated with parallel-execution guidance and safe-parallel-call examples.
+
+### Fixed
+
+- **Scroll tool deltaY sign convention corrected.** Previously `deltaY` was documented as positive=up (inverted vs W3C wheel events). Now follows the W3C convention: positive=down, negative=up. Default changed from `-300` to `300` (scroll down). Prompt snippets, tool descriptions, and guidelines all updated.
+- **Scroll tool now calls `Page.bringToFront`** before dispatching mouse events, preventing silent-drop when the target page is not the active browser tab. Mouse events now include explicit `button:"none"`, `buttons:0`, `pointerType:"mouse"`.
+- **Screenshot TUI render no longer crashes the host on long file paths.** The `Image` text-fallback render did not respect terminal width, so a long path could overflow and crash the host TUI. Each rendered line is now truncated with `truncateToWidth` to fit the available width.
+
 ## 0.3.1 — 2026-05-02
 
 ### Bug fixes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-browser-harness",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Browser control extension for pi — navigate, click, type, screenshot, and extract data from real Chrome via CDP",
   "keywords": [
     "pi-package",

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

@@ -1,226 +1,53 @@
 ---
 name: pi-browser-harness
-description: Direct browser control via CDP. Use when the user wants to automate, scrape, test, or interact with web pages. Connects to the user's already-running Chrome.
+description: Direct browser control via CDP. Use when the user wants to automate, scrape, test, or interact with web pages. Connects to the user's already-running Chrome. Default to browser_snapshot for understanding pages and browser_execute_js for surgical reads — browser_screenshot is for visual verification only.
 ---
 
 # pi-browser-harness
 
-Direct browser control via CDP. Gives pi agents full control of a real Chrome browser.
-Browser tools coexist with all standard pi tools (read, bash, edit, write, etc.).
+Direct browser control of the user's running Chrome via CDP.
 
-## Setup
+## Tool hierarchy
 
-Run `/browser-setup` to install browser-harness and connect to Chrome. Chrome must be running
-with remote debugging enabled. Start Chrome with:
-
-```
---remote-debugging-port=9222
-```
-
-Check status with `/browser-status`. Restart the daemon with `/browser-reload-daemon`.
-
-## Core Workflow
-
-```
-browser_screenshot() → browser_click(x, y) → browser_screenshot()
-```
-
-1. **Screenshot first** — see what's on screen before any interaction
-2. **Coordinate click** — read the target pixel from the screenshot, click at (x, y)
-3. **Screenshot again** — verify the action worked
-
-Compositor-level clicks (`Input.dispatchMouseEvent`) work through iframes, shadow DOM,
-and cross-origin content. No selectors needed.
-
-## Available Tools
-
-### Navigation
-- `browser_navigate` — navigate to a URL (creates new tab on first call, reuses current tab after)
-- `browser_new_tab` — open a new tab, optionally navigate (use for first navigation)
-- `browser_open_urls` — open multiple URLs in parallel tabs (use after search to open result links)
-- `browser_go_back` / `browser_go_forward` / `browser_reload` — history navigation
-- `browser_page_info` — get URL, title, viewport, scroll position, or dialog info
-- `browser_list_tabs` / `browser_current_tab` / `browser_switch_tab` — tab management
-
-### Interaction
-- `browser_click` — click at viewport CSS-pixel coordinates
-- `browser_type` — type text into focused element
-- `browser_press_key` — press a key (Enter, Tab, Escape, arrows, etc.)
-- `browser_scroll` — scroll the page at coordinates
-
-### Visual
-- `browser_screenshot` — capture PNG screenshot
-
-### Data Extraction
-- `browser_execute_js` — execute JavaScript and return result
-- `browser_http_get` — direct HTTP GET outside browser (10-50x faster for APIs)
-
-### Utility
-- `browser_wait` — wait N seconds
-- `browser_wait_for_load` — wait for document.readyState === 'complete'
-- `browser_handle_dialog` — accept or dismiss JS dialogs (alert/confirm/prompt)
-
-### Extending
-- `browser_run_script` — execute a temporary script file with daemon access
-
-## Pattern Reference
-
-### Navigation
-```
-browser_new_tab("https://example.com") → browser_wait_for_load() → browser_screenshot()
-```
-
-### Form Filling
-```
-browser_screenshot() → find input coordinates
-→ browser_click(x, y) → browser_type("text")
-→ browser_press_key("Tab") → browser_screenshot()
-```
-
-### Data Extraction
-```
-browser_execute_js("document.querySelector('.price').innerText")
-// or for APIs directly:
-browser_http_get("https://api.example.com/data")
-```
-
-### Scrolling
-```
-browser_screenshot() → browser_scroll({ deltaY: -500 }) → browser_screenshot()
 ```
+What do you need to know?
 
-### Research (search engine + browser_open_urls)
-```
-browser_new_tab("https://google.com/search?q=query") → search engine results
-browser_open_urls({urls: ["url1", "url2"]}) → open result pages in parallel tabs
-browser_list_tabs() → see all open tabs with targetIds
-browser_switch_tab({targetId: "..."}) → switch to a specific tab
-browser_wait_for_load() → wait for the page to render
-browser_screenshot() → visually inspect the page
-browser_execute_js("document.querySelector('.content').innerText") → extract text
-```
-
-## Temporary Scripts
-
-When the built-in tools aren't enough, write a temporary script to disk and execute it
-with `browser_run_script`. Scripts run in the harness process with direct access to
-the browser daemon and full Node.js APIs — no dynamic tool registration needed.
-
-```
-  ● agent: needs to scrape 47 paginated search result pages
+  ├─ Page structure / what's clickable / labels?
+  │     → browser_snapshot     (DEFAULT — AX tree with @(x,y) per interactive element)
   │
-  ● write("/tmp/scrape-pages.js", "...script using daemon.cdp() and daemon.evaluateJS()...")
+  ├─ A specific element's value / attribute / coords?
+  │     → browser_execute_js   (e.g. el.innerText, el.getBoundingClientRect())
   │
-  ● browser_run_script("/tmp/scrape-pages.js", { urls: [...] })
+  ├─ Network behavior on the current page?
+  │     → browser_network_requests
   │
-  ✓ script executes and returns results
-```
-
-The script is written to disk, so it's auditable and re-runnable.
-
-**When to use scripts:**
-- You're about to do the same 3+ step sequence more than once
-- You need a capability the built-in tools don't provide (e.g., bulk CSV export, structured extraction, pagination)
-- You discover a domain-specific pattern that should be reusable
-- The alternative is a fragile multi-turn loop of screenshots + clicks
-
-**What NOT to do:**
-- Don't write scripts for one-off actions — use the built-in browser_* tools directly.
-- Don't try to call browser_* tools from within a script — sequence them as separate tool calls.
-
-**Script bindings:**
-- `params` — the arguments passed to browser_run_script
-- `daemon` — browser daemon with these methods:
-  - `daemon.evaluateJs(expression)` — run JS in the current page
-  - `daemon.pageInfo()` — get current page info or dialog
-  - `daemon.listTabs()` — returns `{ success, data: [{ targetId, url, title }] }`
-  - `daemon.switchTab(targetId)` — switch to a tab by full targetId
-  - `daemon.newTab(url?)` — open and switch to a new tab
-  - `daemon.current()` — returns `{ targetId, url?, title? }`
-  - `daemon.session(targetId)` — returns a session object for raw CDP:
-    - `session.call(method, params?)` — CDP command on the page target
-    - `session.callOnTarget(method, params, sessionId)` — CDP on a specific session
-    - `session.callBrowser(method, params?)` — CDP on the browser target
-    - `session.takeDialog()` — get/dismiss pending dialog
-- `require` — Node.js require() (use 'fs', 'path', 'crypto', etc.)
-- `signal` — AbortSignal for cancellation
-- `onUpdate` — progress callback: onUpdate({ content: [{ type: 'text', text: '...' }] })
-- `ctx` — ExtensionContext (ctx.cwd, ctx.signal, etc.)
-- `console`, `fetch`, `JSON`, `Buffer`, `setTimeout`, `clearTimeout`
-
-**Example — a script that extracts structured data:**
-```javascript
-// /tmp/extract-products.js
-const info = await daemon.pageInfo();
-if (info && "dialog" in info) throw new Error("Dialog is blocking: " + info.dialog.message);
-const data = await daemon.evaluateJs(`
-  JSON.stringify(Array.from(document.querySelectorAll('${params.rowSelector}')).map(el => ({
-    title: el.querySelector('${params.titleSelector}')?.textContent?.trim(),
-    price: el.querySelector('${params.priceSelector}')?.textContent?.trim(),
-  })))
-`);
-return { content: [{ type: 'text', text: data }], details: { raw: JSON.parse(data) } };
-```
-
-## What NOT To Do
-
-- **Don't launch your own browser** — you're connected to the user's real Chrome
-- **Don't type credentials** — if you hit an auth wall, stop and ask the user
-- **Don't assume page state** — screenshot to confirm
-- **Don't write pixel coordinates into documentation** — describe how to locate targets (selectors, text, aria-label)
-- **Don't use browser_navigate for first navigation** — use browser_new_tab to explicitly preserve the user's active tab (browser_navigate auto-creates a new tab on first call, but explicit is clearer)
-- **Don't ignore dialogs** — if browser_page_info returns a dialog, handle it first
-
-## Dialogs
-
-JS dialogs (alert, confirm, prompt, beforeunload) freeze the page's JS thread.
-If browser_page_info returns a dialog, handle it with browser_handle_dialog
-before any other browser action.
-
-```
-// Check page_info first — if it shows a dialog:
-browser_handle_dialog({ action: "accept" })       // accept/confirm
-browser_handle_dialog({ action: "dismiss" })       // dismiss/cancel
-browser_handle_dialog({ action: "accept", promptText: "hello" })  // prompt with text
-```
-
-## SPAs (React, Vue, etc.)
-
-`browser_wait_for_load()` only checks `document.readyState === "complete"`.
-Single-page apps often paint content after this. After wait_for_load, use
-`browser_execute_js` to check for specific elements:
-
-```
-browser_execute_js("!!document.querySelector('.loaded-content')")
+  └─ Visual rendering (layout / colors / chart drew correctly)?
+        → browser_screenshot   (LAST RESORT — pixels only)
 ```
 
-## Keyboard Modifiers
+Pass `@(x,y)` from `browser_snapshot` straight to `browser_click`. No screenshot round-trip.
 
-`browser_press_key` supports modifier bitfield:
-- 1 = Alt, 2 = Ctrl, 4 = Meta/Cmd, 8 = Shift
-- Combine: Ctrl+Shift = 2|8 = 10, Cmd+Shift = 4|8 = 12
+## Connection
 
-## Troubleshooting
+You're attached to the user's real Chrome — never launch your own. If auth is required, stop and ask the user. If `browser_page_info` returns a dialog, handle it first with `browser_handle_dialog`.
 
-- **Daemon not starting**: Run `/browser-setup` to re-run the guided setup
-- **"DevToolsActivePort not found"**: Open chrome://inspect/#remote-debugging, tick checkbox, click Allow
-- **Stale session**: Run `/browser-reload-daemon` to restart the daemon
-- **Dialog blocking**: Run browser_page_info to detect it, then browser_handle_dialog
-- **Status check**: Run `/browser-status` to see daemon health and current page
-- **Screenshot maxDim not working**: Install sharp (`npm install sharp`) for auto-resize support
-- **Google navigation fails**: Google's anti-bot detection may reject CDP navigation; use `browser_http_get` to fetch search results instead
+## Temporary scripts
 
-## Architecture
+When a workflow repeats 3+ times or needs Node.js APIs, write a script to disk and run it with `browser_run_script`. Scripts get a `daemon` binding for direct CDP access — much faster than chaining tool calls.
 
-```
-pi agent → pi-browser-harness (TypeScript)
-               │ CDP WebSocket
-               ▼
-            Chrome
+**Bindings inside a script:**
 
-Temporary scripts:
-  write("/tmp/script.js") → browser_run_script("/tmp/script.js")
-      │                              │
-      ▼                              ▼
-  script on disk (auditable)    executed in harness process with daemon access
-```
+- `params` — args passed to `browser_run_script`
+- `daemon`:
+  - `daemon.evaluateJs(expression)` — run JS in the current page
+  - `daemon.pageInfo()` — `{ url, title, ... }` or `{ dialog }`
+  - `daemon.listTabs()` / `daemon.switchTab(targetId)` / `daemon.newTab(url?)` / `daemon.current()`
+  - `daemon.session(targetId)` for raw CDP: `session.call`, `session.callOnTarget`, `session.callBrowser`, `session.takeDialog`
+- `require`, `fetch`, `JSON`, `Buffer`, `console`, `setTimeout`, `clearTimeout`
+- `signal` — AbortSignal
+- `onUpdate({ content: [{ type: 'text', text }] })` — progress callback
+- `ctx` — `ExtensionContext`
+
+**Don't:**
+- Use scripts for one-off actions — call `browser_*` tools directly.
+- Call `browser_*` tools from inside a script — sequence them as separate tool calls outside.

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