pi-browser-harness 0.3.2 → 0.4.0

package/src/cdp/session.ts

@@ -1,8 +1,9 @@
-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";
 
 export type CdpSession = {
   attachFirstPage(): Promise<Result<{ readonly targetId: string; readonly sessionId: string }, CdpError>>;
@@ -13,13 +14,18 @@ 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;
 };
 
-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;
+  const networkBuffer = createNetworkBuffer();
 
   let activeConsumer: Promise<void> = Promise.resolve();
 
@@ -41,6 +47,14 @@ export const createCdpSession = (transport: CdpTransport): CdpSession => {
       if (ev.method === "Page.frameNavigated" || ev.method === "Page.loadEventFired") {
         pageInfoDirty = true;
       }
+      if (ev.method === "Target.targetDestroyed" && ownership) {
+        const params = ev.params as { targetId?: string } | undefined;
+        if (params?.targetId) ownership.remove(params.targetId);
+      }
+      if (ev.method === "Network.requestWillBeSent") networkBuffer.ingestRequestWillBeSent(ev.params);
+      else if (ev.method === "Network.responseReceived") networkBuffer.ingestResponseReceived(ev.params);
+      else if (ev.method === "Network.loadingFinished") networkBuffer.ingestLoadingFinished(ev.params);
+      else if (ev.method === "Network.loadingFailed") networkBuffer.ingestLoadingFailed(ev.params);
     }
   };
 
@@ -68,7 +82,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"]) {
       await transport.request(`${d}.enable`, {}, { sessionId: sid });
     }
   };
@@ -81,25 +95,51 @@ 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);
+      }
+
+      // 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 });
+      return ok({ targetId: pickTargetId, sessionId: a.sessionId });
     },
     async switchTo(tid) {
       const activated = await transport.request("Target.activateTarget", { targetId: tid }, { sessionId: null });
@@ -110,6 +150,9 @@ export const createCdpSession = (transport: CdpTransport): CdpSession => {
       sessionId = a.sessionId;
       targetId = tid;
       pageInfoDirty = true;
+      // Buffer is page-scoped: on switch, the network history of the previous
+      // tab is no longer relevant to what the agent is now looking at.
+      networkBuffer.clear();
       await enableDomains(a.sessionId);
       return ok(undefined);
     },
@@ -135,5 +178,8 @@ export const createCdpSession = (transport: CdpTransport): CdpSession => {
       pageInfoDirty = false;
       return dirty;
     },
+    drainNetworkBuffer(filter) {
+      return networkBuffer.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 = {

package/src/client.ts

@@ -6,11 +6,20 @@ import { type CdpError, cdpError } from "./cdp/errors";
 import type { CdpTransport } from "./cdp/transport";
 import { createCdpTransport } from "./cdp/transport";
 import { type CdpSession, createCdpSession } from "./cdp/session";
+import { type OwnershipRegistry, createOwnershipRegistry } from "./cdp/ownership";
 import type { DaemonStatus, DialogInfo, PageInfo, TabInfo } from "./cdp/types";
 
 export type BrowserClientOptions = {
   readonly namespace: string;
   readonly remote?: { readonly cdpUrl: string; readonly browserId: string };
+  readonly initialOwnership?: {
+    readonly ownedTargetIds?: ReadonlyArray<string>;
+    readonly harnessWindowTargetId?: string;
+  };
+  readonly onOwnershipChange?: (snapshot: {
+    readonly ownedTargetIds: ReadonlyArray<string>;
+    readonly harnessWindowTargetId: string | undefined;
+  }) => void;
 };
 
 export type BrowserClient = {
@@ -25,6 +34,9 @@ export type BrowserClient = {
   listTabs(includeInternal?: boolean): Promise<Result<ReadonlyArray<TabInfo>, CdpError>>;
   switchTab(targetId: string): Promise<Result<void, CdpError>>;
   newTab(url?: string): Promise<Result<string, CdpError>>;
+  closeTab(targetId: string): Promise<Result<void, CdpError>>;
+  owns(targetId: string): boolean;
+  ownership(): OwnershipRegistry;
   current(): { readonly sessionId: string; readonly targetId: string } | null;
   session(): CdpSession;
   transport(): CdpTransport;
@@ -66,7 +78,24 @@ const parsePageInfoPayload = (v: unknown): Result<PageInfo, CdpError> => {
 
 export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient => {
   const transport = createCdpTransport();
-  const session = createCdpSession(transport);
+  const ownershipInit: { ownedTargetIds?: ReadonlyArray<string>; harnessWindowTargetId?: string } = {};
+  if (opts.initialOwnership?.ownedTargetIds !== undefined) {
+    ownershipInit.ownedTargetIds = opts.initialOwnership.ownedTargetIds;
+  }
+  if (opts.initialOwnership?.harnessWindowTargetId !== undefined) {
+    ownershipInit.harnessWindowTargetId = opts.initialOwnership.harnessWindowTargetId;
+  }
+  const ownership = createOwnershipRegistry(ownershipInit);
+  if (opts.onOwnershipChange) {
+    const cb = opts.onOwnershipChange;
+    ownership.onChange(() => {
+      cb({
+        ownedTargetIds: ownership.list(),
+        harnessWindowTargetId: ownership.harnessWindow(),
+      });
+    });
+  }
+  const session = createCdpSession(transport, ownership);
   const mutationMutex = createMutex();
   let lastHealth = 0;
   let pageCache: { readonly info: PageInfo; readonly at: number } | null = null;
@@ -186,7 +215,19 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
     const tabs = data.targetInfos
       .filter((t) => t.type === "page")
       .filter((t) => includeInternal || !t.url.startsWith("chrome://"))
-      .map((t): TabInfo => ({ targetId: t.targetId, title: t.title, url: t.url }));
+      .map((t): TabInfo => ({
+        targetId: t.targetId,
+        title: t.title,
+        url: t.url,
+        owned: ownership.has(t.targetId),
+      }));
+    // Reconcile any persisted owned ids that no longer exist as live page targets.
+    const live = new Set(tabs.map((t) => t.targetId));
+    const owned = ownership.list();
+    const survivors = owned.filter((id) => live.has(id));
+    if (survivors.length !== owned.length) ownership.replaceAll(survivors);
+    const hw = ownership.harnessWindow();
+    if (hw && !live.has(hw)) ownership.setHarnessWindow(undefined);
     return ok(tabs);
   };
 
@@ -204,9 +245,30 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
   };
 
   const newTab = async (url?: string): Promise<Result<string, CdpError>> => {
-    const created = await session.callBrowser("Target.createTarget", { url: "about:blank" });
+    // Verify the recorded harness window still exists. Querying the live
+    // target list also gives listTabs's reconciliation a chance to run.
+    const tabsResult = await listTabs(true);
+    if (!tabsResult.success) return tabsResult;
+    const live = new Set(tabsResult.data.map((t) => t.targetId));
+    const hw = ownership.harnessWindow();
+
+    const params: Record<string, unknown> = { url: "about:blank" };
+    if (hw && live.has(hw)) {
+      // Open as a child of the harness window's seed tab — Chrome places
+      // it in the same window, giving us visual grouping for free.
+      params["openerId"] = hw;
+    } else {
+      // Either fresh session or the harness window was closed by the user.
+      // Spawn a new dedicated window.
+      params["newWindow"] = true;
+    }
+    const created = await session.callBrowser("Target.createTarget", params);
     if (!created.success) return created;
     const c = created.data as { targetId: string };
+
+    if (params["newWindow"]) ownership.setHarnessWindow(c.targetId);
+    ownership.add(c.targetId);
+
     const switched = await switchTab(c.targetId);
     if (!switched.success) return switched;
     if (url && url !== "about:blank") {
@@ -217,6 +279,13 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
     return ok(c.targetId);
   };
 
+  const closeTab = async (targetId: string): Promise<Result<void, CdpError>> => {
+    const r = await session.callBrowser("Target.closeTarget", { targetId });
+    if (!r.success) return r;
+    ownership.remove(targetId);
+    return ok(undefined);
+  };
+
   const status = (): DaemonStatus => ({
     alive: transport.state() === "open" && session.current() !== null,
     sessionId: session.current()?.sessionId ?? null,
@@ -229,7 +298,9 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
     ensureAlive, status, start, stop,
     evaluateJs, pageInfo,
     takeDialog: () => session.takeDialog(),
-    listTabs, switchTab, newTab,
+    listTabs, switchTab, newTab, closeTab,
+    owns: (id: string) => ownership.has(id),
+    ownership: () => ownership,
     current: () => session.current(),
     session: () => session,
     transport: () => transport,

package/src/domains/click.ts

@@ -41,14 +41,15 @@ export const clickTool = defineBrowserTool({
   name: "browser_click",
   label: "Browser Click",
   description:
-    "Click at viewport CSS-pixel coordinates. Compositor-level click works through iframes, shadow DOM, and cross-origin content. Use browser_screenshot first to find coordinates.",
+    "Click at viewport CSS-pixel coordinates. Compositor-level click works through iframes, shadow DOM, and cross-origin content. Get coordinates from browser_snapshot's @(x,y) hints — do not screenshot to find click targets.",
   promptSnippet: "Click at pixel coordinates (x, y) on the page",
   promptGuidelines: [
-    "Use browser_click for all clicks. Coordinates are viewport CSS pixels (not device pixels).",
-    "Capture a browser_screenshot BEFORE clicking to find the right coordinates.",
-    "Capture another browser_screenshot AFTER clicking to verify the action worked.",
+    "Get (x, y) from browser_snapshot — the outline shows '@(x,y)' for every interactive element. NO screenshot needed.",
+    "If the target isn't an interactive role in the snapshot, fall back to browser_execute_js with `el.getBoundingClientRect()` — still NO screenshot.",
+    "Coordinates are viewport CSS pixels (not device pixels).",
+    "After clicking, verify with browser_snapshot (or browser_execute_js for a specific value). Only screenshot if you need to confirm visual rendering.",
     "Compositor-level clicks pass through iframes, shadow DOM, and cross-origin content — no selector needed.",
-    "If a click doesn't register, try setting BH_DEBUG_CLICKS=1 to get annotated screenshots showing exact click positions.",
+    "If a click doesn't register, set BH_DEBUG_CLICKS=1 to get annotated screenshots showing exact click positions (debug only).",
     "For React/Vue components that don't respond to clicks, try browser_dispatch_key to send DOM-level events.",
   ],
   parameters: ClickArgs,

package/src/domains/js.ts

@@ -3,10 +3,20 @@ import { resolve, isAbsolute } from "node:path";
 import { tmpdir } from "node:os";
 import { createRequire } from "node:module";
 import { Type } from "typebox";
+import { Markdown, Text } from "@mariozechner/pi-tui";
+import { getMarkdownTheme, keyHint } from "@mariozechner/pi-coding-agent";
 import { type Result, err, ok } from "../util/result";
 import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
 import { applyTruncation } from "../util/truncate";
 
+const COMPACT_PREVIEW_BYTES = 120;
+
+const formatBytes = (n: number): string => {
+  if (n >= 1_048_576) return `${(n / 1_048_576).toFixed(1)} MB`;
+  if (n >= 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${n} B`;
+};
+
 // AsyncFunction constructor — the documented Node.js mechanism for compiling
 // arbitrary user-supplied source. Equivalent to `new Function` but produces an
 // async function we can `await`. The full RCE risk is contained at the source
@@ -29,11 +39,15 @@ export const executeJsTool = defineBrowserTool({
   name: "browser_execute_js",
   label: "Browser Execute JS",
   description:
-    "Run JavaScript in the page (or a specific iframe target). `return X` gets auto-wrapped in an IIFE for convenience. Always use safeJs / JSON.stringify when interpolating untrusted strings into source.",
-  promptSnippet: "Execute JS in the page (or iframe)",
+    "Surgical reads from the DOM. The cheapest, most precise way to extract a specific element's text, attribute, value, or geometry. Prefer over browser_screenshot for ANY data extraction or coordinate lookup. `return X` is auto-wrapped in an IIFE. Always use safeJs / JSON.stringify when interpolating untrusted strings.",
+  promptSnippet: "Execute JS in the page — surgical DOM reads (preferred over screenshot)",
   promptGuidelines: [
+    "DEFAULT for extracting a specific value: `document.querySelector('.price').innerText`, `input.value`, `el.getAttribute('aria-label')`, etc.",
+    "For click coordinates not already in browser_snapshot: `JSON.stringify(document.querySelector('SELECTOR').getBoundingClientRect())` — beats a screenshot every time.",
+    "For 'is this element visible / enabled / checked / focused', a one-liner here beats a screenshot every time.",
+    "DO NOT call browser_screenshot to read a value or check element state. Use this tool.",
     "`return foo` is auto-wrapped in an IIFE — both `foo` and `(() => foo)()` work.",
-    "For iframes, get a targetId via browser_execute_js with `Object.values(document.querySelectorAll('iframe'))` then call browser_execute_js with targetId.",
+    "For iframes, first run `Object.values(document.querySelectorAll('iframe'))` to find the iframe, then pass its targetId.",
     "Result must be JSON-serializable (Runtime.evaluate returnByValue=true).",
   ],
   parameters: ExecuteJsArgs,
@@ -42,13 +56,58 @@ export const executeJsTool = defineBrowserTool({
     if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
     const valueStr = r.data === undefined ? "undefined" : JSON.stringify(r.data);
     const truncated = await applyTruncation(valueStr, "js");
+    // If the value is JSON, pretty-print for the expanded TUI view. Falls back
+    // to the raw string if parse fails (e.g. value is "undefined" sentinel).
+    let pretty: string | undefined;
+    try {
+      const parsed = JSON.parse(valueStr);
+      pretty = JSON.stringify(parsed, null, 2);
+    } catch {
+      pretty = undefined;
+    }
     return ok({
       text: truncated.text,
-      details: truncated.fullOutputPath !== undefined
-        ? { valueLength: valueStr.length, fullOutputPath: truncated.fullOutputPath }
-        : { valueLength: valueStr.length },
+      details: {
+        valueLength: valueStr.length,
+        // Full value for the expanded renderer. Capped at 200 KB so a giant
+        // dump doesn't bloat the conversation transcript on disk.
+        full: valueStr.length > 200_000 ? valueStr.slice(0, 200_000) : valueStr,
+        ...(pretty !== undefined ? { pretty: pretty.length > 200_000 ? pretty.slice(0, 200_000) : pretty } : {}),
+        ...(truncated.fullOutputPath !== undefined ? { fullOutputPath: truncated.fullOutputPath } : {}),
+      },
     });
   },
+
+  renderResult(result, expanded, theme) {
+    const details = result.details as
+      | { valueLength?: number; full?: string; pretty?: string; fullOutputPath?: string }
+      | undefined;
+    if (!details) return new Text(theme.fg("error", "execute_js: no details"), 0, 0);
+
+    const len = details.valueLength ?? 0;
+    const full = details.full ?? "";
+    const isJson = details.pretty !== undefined;
+
+    if (!expanded) {
+      const preview = full.length > COMPACT_PREVIEW_BYTES ? full.slice(0, COMPACT_PREVIEW_BYTES) + "…" : full;
+      const md = [
+        `**${formatBytes(len)}** ${isJson ? "JSON" : "value"}`,
+        "```",
+        preview,
+        "```",
+        keyHint("app.tools.expand", "to expand"),
+      ].join("\n");
+      return new Markdown(md, 0, 0, getMarkdownTheme());
+    }
+
+    const body = details.pretty ?? full;
+    const fence = isJson ? "```json" : "```";
+    const tail = details.fullOutputPath
+      ? `\n\nFull value at \`${details.fullOutputPath}\` · ${keyHint("app.tools.expand", "to collapse")}`
+      : `\n\n${keyHint("app.tools.expand", "to collapse")}`;
+    const md = [`**${formatBytes(len)}** ${isJson ? "JSON" : "value"}`, fence, body, "```", tail].join("\n");
+    return new Markdown(md, 0, 0, getMarkdownTheme());
+  },
 });
 
 const RunScriptArgs = Type.Object({

package/src/domains/navigate.ts

@@ -75,7 +75,7 @@ export const openUrlsTool = defineBrowserTool({
   promptSnippet: "Open multiple URLs in new tabs (parallel)",
   promptGuidelines: [
     "Use after web_search to open citations in parallel.",
-    "After opening, use browser_list_tabs / browser_switch_tab / browser_screenshot to interact.",
+    "After opening, use browser_list_tabs / browser_switch_tab to navigate, then browser_snapshot to inspect each tab.",
     "Use browser_wait_for_load on a tab before extracting data from SPAs.",
   ],
   parameters: OpenUrlsArgs,

package/src/domains/network.ts

@@ -1,7 +1,10 @@
 import { Type } from "typebox";
+import { Markdown, Text } from "@mariozechner/pi-tui";
+import { getMarkdownTheme, keyHint } from "@mariozechner/pi-coding-agent";
 import { type Result, err, ok } from "../util/result";
 import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
 import { applyTruncation } from "../util/truncate";
+import type { NetworkRecord } from "../cdp/network-buffer";
 
 const HttpGetArgs = Type.Object({
   url: Type.String({ description: "URL to GET" }),
@@ -49,32 +52,200 @@ export const httpGetTool = defineBrowserTool({
   },
 });
 
-const NetLogArgs = Type.Object({
-  eventTypes: Type.Optional(
-    Type.Array(Type.String(), { description: "CDP event names to filter (e.g., ['Network.requestWillBeSent'])" }),
+const NetworkRequestsArgs = Type.Object({
+  urlPattern: Type.Optional(
+    Type.String({ description: "Substring match by default. Wrap in slashes (e.g. /api\\\\.example/) for regex." }),
+  ),
+  methodFilter: Type.Optional(
+    Type.Array(Type.String(), { description: 'HTTP methods to include, e.g. ["GET","POST"].' }),
+  ),
+  statusFilter: Type.Optional(
+    Type.Object(
+      {
+        min: Type.Optional(Type.Integer({ minimum: 100, maximum: 599 })),
+        max: Type.Optional(Type.Integer({ minimum: 100, maximum: 599 })),
+      },
+      { description: "Inclusive HTTP status range." },
+    ),
+  ),
+  resourceTypes: Type.Optional(
+    Type.Array(Type.String(), { description: 'CDP resource types: "Document","Stylesheet","Image","Media","Font","Script","TextTrack","XHR","Fetch","EventSource","WebSocket","Manifest","SignedExchange","Ping","CSPViolationReport","Preflight","Other".' }),
+  ),
+  sinceMs: Type.Optional(
+    Type.Integer({ minimum: 0, description: "Only requests started in the last N ms." }),
+  ),
+  limit: Type.Optional(
+    Type.Integer({ default: 50, minimum: 1, maximum: 500, description: "Max records to return." }),
+  ),
+  includeResponseBodies: Type.Optional(
+    Type.Boolean({ default: false, description: "Fetch response bodies via Network.getResponseBody. Costs one CDP call per matched request." }),
   ),
-  limit: Type.Optional(Type.Integer({ default: 50, minimum: 1, maximum: 500 })),
 });
 
-export const getNetworkLogTool = defineBrowserTool({
-  name: "browser_get_network_log",
-  label: "Browser Get Network Log",
+const BODY_BUDGET_MS = 5_000;
+const PER_BODY_CAP = 50_000;
+
+const renderNetworkMarkdown = (
+  records: ReadonlyArray<NetworkRecord>,
+  opts: { includeBodies: boolean; total: number; bufferOverflowed: boolean; expanded: boolean },
+): string => {
+  if (records.length === 0) {
+    if (opts.bufferOverflowed) return "_No matching requests. (Buffer overflowed since last drain — some events were dropped.)_";
+    return "_No matching requests captured yet._";
+  }
+
+  const failed = records.filter((r) => r.failed || (r.status !== undefined && r.status >= 500)).length;
+  const totalBytes = records.reduce((s, r) => s + (r.responseBodySize ?? 0), 0);
+  const formatBytes = (n: number): string => {
+    if (n >= 1_048_576) return `${(n / 1_048_576).toFixed(1)} MB`;
+    if (n >= 1024) return `${(n / 1024).toFixed(1)} KB`;
+    return `${n} B`;
+  };
+  const showWindow = (() => {
+    const finished = records.filter((r) => r.durationMs !== undefined);
+    if (finished.length === 0) return "";
+    const span = Math.max(...records.map((r) => r.requestStartedMs)) - Math.min(...records.map((r) => r.requestStartedMs));
+    return ` · ${(span / 1000).toFixed(1)}s window`;
+  })();
+
+  const headerLines: string[] = [
+    `**${records.length} requests** · ${failed} failed · ${formatBytes(totalBytes)}${showWindow}`,
+  ];
+  if (opts.bufferOverflowed) headerLines.push("⚠ buffer overflowed since last drain — older events dropped");
+  if (opts.total > records.length) headerLines.push(`(${records.length} of ${opts.total} matches shown — increase \`limit\` for more)`);
+
+  const compactRows = (records.length > 5 && !opts.expanded ? records.slice(0, 5) : records).map((r) => {
+    const status = r.failed ? "ERR" : r.status !== undefined ? String(r.status) : "—";
+    const warn = r.failed || (r.status !== undefined && r.status >= 500) ? " ⚠" : "";
+    const ms = r.durationMs !== undefined ? `${r.durationMs} ms` : "—";
+    const url = r.url.length > 60 ? r.url.slice(0, 57) + "…" : r.url;
+    return `\`${r.method.padEnd(4)} ${status.padStart(3)}\`  ${url}  _${ms}_${warn}`;
+  });
+
+  const rows = compactRows.join("\n");
+
+  if (!opts.expanded) {
+    const more = records.length > 5 ? `\n  … ${records.length - 5} more` : "";
+    return `${headerLines.join("\n")}\n\n${rows}${more}`;
+  }
+
+  // Expanded: full table + optional body sections.
+  const tableHeader = `| # | Method | Status | URL | Type | ms |\n|---|---|---|---|---|---|`;
+  const tableRows = records
+    .map((r, i) => {
+      const status = r.failed ? "ERR" : r.status !== undefined ? String(r.status) : "—";
+      const ms = r.durationMs !== undefined ? String(r.durationMs) : "—";
+      const url = r.url.length > 80 ? r.url.slice(0, 77) + "…" : r.url;
+      return `| ${i + 1} | ${r.method} | ${status} | \`${url}\` | ${r.type} | ${ms} |`;
+    })
+    .join("\n");
+
+  let bodySections = "";
+  if (opts.includeBodies) {
+    const sections: string[] = [];
+    records.forEach((r, i) => {
+      if (r.body === undefined) return;
+      const sizes = `${r.requestBodySize} B → ${r.responseBodySize ?? 0} B`;
+      const status = r.failed ? "failed" : r.status ?? "?";
+      const header = `── #${i + 1} ${r.method} ${r.url} (${status}, ${r.durationMs ?? "?"} ms, ${r.type}, ${sizes}) ──`;
+      const bodyText = r.body === null ? "_(body unavailable — already GC'd by Chrome)_" : "```\n" + r.body + "\n```";
+      sections.push(`${header}\n\n${bodyText}`);
+    });
+    if (sections.length > 0) bodySections = "\n\n" + sections.join("\n\n");
+  }
+
+  return [headerLines.join("\n"), "", tableHeader, tableRows, bodySections].filter((s) => s !== "").join("\n");
+};
+
+type NetworkDetails = {
+  total: number;
+  returned: number;
+  bufferOverflowed: boolean;
+  truncated: boolean;
+  fullOutputPath?: string;
+  requests: ReadonlyArray<NetworkRecord>;
+  includeBodies: boolean;
+};
+
+export const networkRequestsTool = defineBrowserTool({
+  name: "browser_network_requests",
+  label: "Browser Network Requests",
   description:
-    "Read buffered Network.* CDP events. NOTE: in v0.3 the event stream is consumed internally by the session manager; this tool is a placeholder. Use browser_execute_js with PerformanceObserver as a workaround.",
-  promptSnippet: "Get buffered network events (DEPRECATED in v0.3 — use browser_execute_js with PerformanceObserver instead)",
+    "List recent network requests captured on the current tab since attach. Filter by URL pattern, method, status, resource type, or recency. Optionally include response bodies.",
+  promptSnippet: "Inspect recent network requests on the current page",
   promptGuidelines: [
-    "v0.3 routes CDP events through an internal AsyncIterable; a synchronous drain API isn't exposed yet.",
-    "For now, use browser_execute_js with PerformanceObserver, performance.getEntries(), or fetch interceptors.",
+    "Buffer is reset on tab switch — only requests on the current tab since attach are visible.",
+    'urlPattern is a substring; wrap in slashes for regex (e.g. "/\\\\.json$/").',
+    "includeResponseBodies:true costs an extra CDP call per matched request — use only when you need payloads.",
+    "If bufferOverflowed:true in the result, older events were dropped (capacity 500 records/tab).",
   ],
-  parameters: NetLogArgs,
-  async handler(args): Promise<Result<ToolOk, ToolErr>> {
-    return ok({
-      text: "browser_get_network_log: in v0.3 the CDP event stream is consumed by the session; use browser_execute_js with PerformanceObserver or performance.getEntries() to inspect network activity.",
-      details: {
-        deprecated: true,
-        eventTypes: args.eventTypes ?? null,
-        limit: args.limit ?? null,
-      },
+  parameters: NetworkRequestsArgs,
+
+  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const session = client.session();
+    const drained = session.drainNetworkBuffer({
+      ...(args.urlPattern !== undefined ? { urlPattern: args.urlPattern } : {}),
+      ...(args.methodFilter !== undefined ? { methodFilter: args.methodFilter } : {}),
+      ...(args.statusFilter !== undefined ? { statusFilter: args.statusFilter } : {}),
+      ...(args.resourceTypes !== undefined ? { resourceTypes: args.resourceTypes } : {}),
+      ...(args.sinceMs !== undefined ? { sinceMs: args.sinceMs } : {}),
+      limit: args.limit ?? 50,
     });
+
+    if (args.includeResponseBodies) {
+      const ac = new AbortController();
+      const timer = setTimeout(() => ac.abort(), BODY_BUDGET_MS);
+      const fills = drained.records.map(async (r) => {
+        if (ac.signal.aborted) return;
+        const bodyRes = await session.call("Network.getResponseBody", { requestId: r.requestId });
+        if (!bodyRes.success) {
+          r.body = null;
+          return;
+        }
+        const b = bodyRes.data as { body: string; base64Encoded?: boolean };
+        let body = b.base64Encoded ? Buffer.from(b.body, "base64").toString("utf8") : b.body;
+        if (body.length > PER_BODY_CAP) body = body.slice(0, PER_BODY_CAP) + "…";
+        r.body = body;
+      });
+      await Promise.allSettled(fills);
+      clearTimeout(timer);
+    }
+
+    const text = renderNetworkMarkdown(drained.records, {
+      includeBodies: args.includeResponseBodies ?? false,
+      total: drained.total,
+      bufferOverflowed: drained.bufferOverflowed,
+      expanded: true, // full text always returned to the LLM; renderResult handles compact view for humans
+    });
+    const trunc = await applyTruncation(text, "network");
+
+    const details: NetworkDetails = {
+      total: drained.total,
+      returned: drained.records.length,
+      bufferOverflowed: drained.bufferOverflowed,
+      truncated: trunc.wasTruncated,
+      requests: drained.records,
+      includeBodies: args.includeResponseBodies ?? false,
+    };
+    if (trunc.fullOutputPath !== undefined) details.fullOutputPath = trunc.fullOutputPath;
+
+    return ok({ text: trunc.text, details });
+  },
+
+  renderResult(result, expanded, theme) {
+    const details = result.details as NetworkDetails | undefined;
+    if (!details) return new Text(theme.fg("error", "network: no details"), 0, 0);
+
+    const md = renderNetworkMarkdown(details.requests, {
+      includeBodies: details.includeBodies && expanded,
+      total: details.total,
+      bufferOverflowed: details.bufferOverflowed,
+      expanded,
+    });
+    const tail = expanded
+      ? `\n\n${keyHint("app.tools.expand", "to collapse")}${details.fullOutputPath ? ` · full payload at \`${details.fullOutputPath}\`` : ""}`
+      : `\n\n${keyHint("app.tools.expand", "to expand")}`;
+
+    return new Markdown(md + tail, 0, 0, getMarkdownTheme());
   },
 });