pi-browser-harness 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to pi-browser-harness will be documented in this file.
 
+## 0.5.0 — 2026-05-07
+
+### Added
+
+- **`browser_console`** — new tool. Reads JS errors and console messages from the active tab via two CDP sources merged into one buffer: `Runtime.consoleAPICalled` (page `console.*` calls and uncaught exceptions) and `Log.entryAdded` (browser-level entries — CSP violations, mixed content, deprecations, network errors). Filters: `levels` (log/info/warn/error/debug), `textPattern` (substring; wrap in slashes for regex), `sinceMs`, `limit` (default 50, cap 500). Each record carries a monotonic `seq`; the response includes `nextCursor` so callers can pass `sinceSeq` to see only what's new since the previous drain — the cursor pattern that makes "what did this action cause?" answerable in one call. Buffer is page-scoped (cleared on tab switch) and bounded at 500 records; `bufferOverflowed` flag reports drops since the last drain. Stack traces (top 3 frames) are preserved for error/warn records. Per-arg cap of 2 KB prevents a single `console.log(hugeBlob)` from blowing the buffer.
+- **`Log` CDP domain enabled** alongside Page/DOM/Runtime/Network/Accessibility on every attach. (`Runtime` was already enabled, so `Runtime.consoleAPICalled` was reachable; this adds the missing domain for browser-level entries.)
+- **`browser_console` ships with a custom `renderResult`** following the established pattern — collapsed: header counts (`3 errors · 2 warnings · 47 logs`) + last 5 rows. Expanded: full list with stack traces inline as code fences. Appends `keyHint("app.tools.expand", ...)` so the binding label adapts to user remaps.
+
+### Internal
+
+- New pure module `src/cdp/console-buffer.ts` mirrors the `network-buffer.ts` pattern (insertion-ordered Map, FIFO eviction at capacity 500, overflow flag reset per drain). Wired into the existing single-consumer event loop in `src/cdp/session.ts`.
+
+### Known follow-ups
+
+- No tests added in this release. Verification is manual against real Chrome.
+
 ## 0.4.0 — 2026-05-06
 
 ### Added

package/README.md

@@ -2,7 +2,29 @@
 
 ![pi-browser-harness](https://raw.githubusercontent.com/amankumarsingh77/pi-browser-harness/main/assets/hero.png)
 
-Full browser control for pi agents. Navigate, click, type, screenshot, and extract data from your real Chrome — all driven through natural language via CDP.
+Full browser control for pi agents in **your real Chrome** — your sessions, your cookies, your tabs. Drives navigation, structured page reads, network capture, clicks, typing, screenshots, and arbitrary scripts via CDP.
+
+---
+
+## Why pi-browser-harness?
+
+| Capability | pi-browser-harness | Playwright MCP | Stagehand | Puppeteer MCP |
+|---|:---:|:---:|:---:|:---:|
+| **Drives your real Chrome** (logged-in sessions preserved) | ✅ | ❌ launches its own browser | ❌ | ❌ |
+| **Coordinate clicks** that work through iframes, shadow DOM, cross-origin | ✅ | ❌ selector-based | ❌ selector-based | ❌ selector-based |
+| **Inline TUI screenshot rendering** (Kitty/iTerm2/Ghostty/WezTerm) | ✅ | ❌ | ❌ | ❌ |
+| **Accessibility-tree snapshot with click coords `@(x,y)` per element** | ✅ | ✅ tree only, no coords | partial | ❌ |
+| **Network request capture** with filters + body capture | ✅ | ✅ post-hoc list | ❌ | ❌ |
+| **Parallel tool execution** with automatic mutation serialization | ✅ | ❌ | ❌ | ❌ |
+| **Temporary scripts** with daemon + full Node.js | ✅ | ❌ | ❌ | ❌ |
+| **Direct HTTP GET** outside the browser (10–50× faster for APIs) | ✅ | ❌ | ❌ | ❌ |
+| **Tab ownership isolation** — never touches the user's other tabs | ✅ | N/A | N/A | N/A |
+| **Pi-native** — no MCP/JSON-RPC overhead, no extra LLM API keys | ✅ | ❌ MCP roundtrip | ❌ external LLM | ❌ MCP roundtrip |
+| **TypeScript strict mode**, zero `any`, all CDP casts documented | ✅ | unknown | unknown | unknown |
+| Ctrl+O expand/collapse on tool output | ✅ | ❌ | ❌ | ❌ |
+| Compositor-level dispatch (works on every site, no flakey waits) | ✅ | ❌ | ❌ | ❌ |
+
+If you live in pi and you want an agent driving the same Chrome you're already signed into, this is the only one that fits.
 
 ---
 
@@ -29,84 +51,144 @@ pi install npm:pi-browser-harness
 
 ---
 
+## Tool hierarchy — read this first
+
+```
+What do you need to know?
+
+  ├─ Page structure / what's clickable / labels?
+  │     → browser_snapshot     (DEFAULT — AX tree with @(x,y) per interactive element)
+  │
+  ├─ A specific element's value / attribute / coords?
+  │     → browser_execute_js   (e.g. el.innerText, el.getBoundingClientRect())
+  │
+  ├─ Network behavior on the current page?
+  │     → browser_network_requests
+  │
+  └─ Visual rendering (layout / colors / chart drew correctly)?
+        → browser_screenshot   (LAST RESORT — pixels only)
+```
+
+Pass `@(x,y)` from `browser_snapshot` straight to `browser_click`. **No screenshot round-trip needed** to find click targets — the snapshot already has them.
+
+---
+
 ## Tools
 
+### Page inspection (use these by default)
+
 | Tool | Purpose |
 |------|---------|
-| `browser_screenshot` | Capture a PNG screenshot of the current page |
-| `browser_click` | Click at viewport coordinates |
-| `browser_type` | Type text into the focused element |
-| `browser_press_key` | Press a key (Enter, Tab, Escape, arrows, etc.) with optional modifiers |
-| `browser_scroll` | Scroll the page by delta pixels |
-| `browser_navigate` | Navigate to a URL |
-| `browser_new_tab` | Open a new tab, optionally navigate |
+| `browser_snapshot` | **Default for page inspection.** Returns the CDP accessibility tree with click coords `@(x,y)` for every interactive element. Optional `includeScreenshot:true`. |
+| `browser_execute_js` | Surgical DOM reads — element text, attributes, `getBoundingClientRect()`. Cheapest, most precise. |
+| `browser_network_requests` | List recent network requests on the current tab. Filter by url/method/status/type/recency; optional response-body capture. |
+| `browser_page_info` | URL, title, viewport, scroll position, or pending dialog. |
+| `browser_http_get` | Direct HTTP GET outside the browser — 10-50× faster for APIs. |
+
+### Visual (last resort)
+
+| Tool | Purpose |
+|------|---------|
+| `browser_screenshot` | Capture PNG/JPEG. Use only when you need to verify visual rendering. |
+
+### Navigation
+
+| Tool | Purpose |
+|------|---------|
+| `browser_navigate` / `browser_new_tab` | Navigate or open a tab |
 | `browser_open_urls` | Open multiple URLs in parallel tabs |
 | `browser_go_back` / `browser_go_forward` / `browser_reload` | History navigation |
-| `browser_page_info` | Get URL, title, viewport, scroll position, or dialog state |
-| `browser_list_tabs` / `browser_current_tab` / `browser_switch_tab` | Tab discovery and switching |
-| `browser_execute_js` | Run JavaScript in the page and return the result |
-| `browser_http_get` | Direct HTTP GET outside the browser — much faster for APIs |
+| `browser_list_tabs` / `browser_current_tab` / `browser_switch_tab` / `browser_close_tab` | Tab management (only tabs this session opened) |
+
+### Interaction
+
+| Tool | Purpose |
+|------|---------|
+| `browser_click` | Click at viewport coordinates (use `@(x,y)` from `browser_snapshot`) |
+| `browser_type` | Type text into the focused element |
+| `browser_press_key` | Press a key with optional modifiers |
+| `browser_scroll` | Scroll the page by delta pixels |
+
+### Utility
+
+| Tool | Purpose |
+|------|---------|
 | `browser_wait` / `browser_wait_for_load` | Sleep, or wait for `readyState === 'complete'` |
 | `browser_handle_dialog` | Accept or dismiss `alert` / `confirm` / `prompt` |
 | `browser_run_script` | Execute a temporary script with daemon and Node.js access |
 
----
+Three tools (`browser_snapshot`, `browser_network_requests`, `browser_execute_js`) ship custom TUI rendering with **Ctrl+O** (`app.tools.expand`) to toggle between compact and full output.
 
-## Core Patterns
+---
 
-The golden rule: **screenshot → act → screenshot → verify.** Never assume — always look.
+## Core patterns
 
-### Navigation
+### Page inspection
 
 ```
-browser_new_tab({ url: "https://example.com" })
-browser_wait_for_load()
-browser_screenshot()
+browser_snapshot()
+# → AX outline with @(x,y) per button/link/input
 ```
 
-### Form filling
+### Form filling (no screenshots)
 
 ```
-browser_screenshot()                   # see the form
-browser_click({ x: 400, y: 200 })      # click the search input
-browser_type({ text: "query" })        # type
-browser_press_key({ key: "Enter" })    # submit
+browser_snapshot()                    # find input @(x,y) and labels
+browser_click({ x, y })               # click using snapshot's @(x,y)
+browser_type({ text: "query" })
+browser_press_key({ key: "Enter" })
 browser_wait_for_load()
-browser_screenshot()                   # verify
+browser_snapshot()                    # verify next state
 ```
 
 ### Data extraction
 
-```
+```js
+// One value
 browser_execute_js({ expression: "document.querySelector('.price').innerText" })
 
+// Direct API call outside the browser
 browser_http_get({ url: "https://api.github.com/repos/amankumarsingh77/pi-browser-harness" })
 
 // Structured arrays
-browser_execute_js({ expression: `Array.from(document.querySelectorAll('.result')).map(el => ({
-  title: el.querySelector('h3')?.textContent,
-  link:  el.querySelector('a')?.href,
-}))` })
+browser_execute_js({ expression: `JSON.stringify(
+  Array.from(document.querySelectorAll('.result')).map(el => ({
+    title: el.querySelector('h3')?.textContent,
+    link:  el.querySelector('a')?.href,
+  }))
+)` })
+```
+
+### Network debugging
+
+```
+browser_navigate({ url: "https://app.example.com/feed" })
+browser_wait_for_load()
+browser_network_requests({
+  urlPattern: "/api/",
+  statusFilter: { min: 400 },
+  includeResponseBodies: true
+})
 ```
 
 ### Research workflow
 
 ```
 browser_navigate({ url: "https://google.com/search?q=..." })
-// read search results
 browser_open_urls({ urls: ["url1", "url2", "url3"] })
 browser_list_tabs()
 browser_switch_tab({ targetId: "..." })
-browser_screenshot()
+browser_wait_for_load()
+browser_snapshot()
 browser_execute_js({ expression: "document.querySelector('.content').innerText" })
 ```
 
-### Scrolling
+### Visual verification (only when pixels matter)
 
 ```
-browser_screenshot()
-browser_scroll({ deltaY: -500 })
-browser_screenshot()
+browser_click({ x, y })         # got coords from browser_snapshot
+browser_snapshot()              # confirm the form transitioned
+browser_screenshot()            # ONLY if you need to verify a chart/modal/CSS rendered correctly
 ```
 
 ### Keyboard modifiers
@@ -118,55 +200,65 @@ browser_screenshot()
 | Meta / Cmd | 4 |
 | Shift | 8 |
 
-Combine with bitwise OR:
 ```
 browser_press_key({ key: "c", modifiers: 2 })    // Ctrl+C
 browser_press_key({ key: "v", modifiers: 4 })    // Cmd+V
 browser_press_key({ key: "T", modifiers: 10 })   // Ctrl+Shift+T
 ```
 
-### SPAs (React, Vue, etc.)
+### Dialogs
 
-`browser_wait_for_load` only checks `readyState`. Poll for elements after:
+JS dialogs freeze the page. Check `browser_page_info` first — if it reports a dialog, handle it before anything else:
 
 ```
-browser_execute_js({ expression: "!!document.querySelector('.loaded-content')" })
+browser_handle_dialog({ action: "accept" })       // confirm
+browser_handle_dialog({ action: "dismiss" })       // cancel
+browser_handle_dialog({ action: "accept", promptText: "hello" })  // prompt
 ```
 
-### Dialogs
+---
+
+## Parallel execution
 
-JS dialogs (`alert` / `confirm` / `prompt`) freeze the page. Check `browser_page_info` first — if it reports a dialog, handle it before anything else:
+Observation tools run in parallel by default. Mutation tools (`click`, `type`, `scroll`, `navigate`, `switch_tab`, …) are automatically serialized through a shared mutex — emit them in the same turn and the harness FIFO-queues them.
 
 ```
-browser_handle_dialog({ action: "accept" })       // confirm
-browser_handle_dialog({ action: "dismiss" })       // cancel
-browser_handle_dialog({ action: "accept", promptText: "hello" })  // prompt
+# All three run concurrently
+browser_snapshot()
+browser_network_requests({ sinceMs: 5000 })
+browser_http_get({ url: "..." })
 ```
 
 ---
 
-## Temporary Scripts
+## Tab ownership
 
-When built-in tools aren't enough, write a script to disk and run it:
+The harness never touches tabs you didn't open through it. On first attach it spawns a dedicated Chrome window; subsequent `browser_new_tab` calls open inside that window. `browser_list_tabs` defaults to `scope:"owned"` (pass `scope:"all"` to see read-only listings of your other tabs); `browser_switch_tab` and `browser_close_tab` refuse non-owned tabs.
+
+---
+
+## Temporary scripts
+
+When the built-in tools aren't enough, write a script to disk and run it. Scripts get a `daemon` binding for direct CDP access — much faster than chaining tool calls.
 
 ```js
-// 1. Write the script
 write("/tmp/scrape-pages.js", `
   const results = [];
   for (const url of params.urls) {
-    await daemon.cdp("Page.navigate", { url });
+    await daemon.session().call("Page.navigate", { url });
     await new Promise(r => setTimeout(r, 2000));
-    const title = await daemon.evaluateJS("document.title");
+    const title = await daemon.evaluateJs("document.title");
     results.push({ url, title });
   }
   return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
 `)
 
-// 2. Execute it
 browser_run_script({ path: "/tmp/scrape-pages.js", params: { urls: [...] } })
 ```
 
-**Script bindings:** `params`, `daemon`, `require`, `signal`, `onUpdate`, `ctx`, `console`, `fetch`, `JSON`, `Buffer`, `setTimeout`, `clearTimeout`.
+**Bindings:** `params`, `daemon`, `require`, `signal`, `onUpdate`, `ctx`, `console`, `fetch`, `JSON`, `Buffer`, `setTimeout`, `clearTimeout`.
+
+`daemon` exposes: `evaluateJs`, `pageInfo`, `listTabs`, `switchTab`, `newTab`, `current`, and `session(targetId?)` for raw CDP via `session.call` / `session.callOnTarget` / `session.callBrowser` / `session.takeDialog`.
 
 Scripts are written to disk — auditable and re-runnable.
 
@@ -186,8 +278,9 @@ Scripts are written to disk — auditable and re-runnable.
 
 - 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
-- Don't assume a page action worked — screenshot to verify
-- Don't write pixel coordinates into documentation — describe selectors and text instead
+- Don't screenshot to understand the page — `browser_snapshot` is the default
+- Don't screenshot to find click coordinates — `browser_snapshot`'s `@(x,y)` is exact
+- Don't screenshot to read a value — `browser_execute_js` is one round-trip
 - Don't ignore dialogs — check `browser_page_info` first
 
 ---
@@ -211,9 +304,10 @@ Temporary scripts run inside the harness process with full daemon and Node.js ac
 |---------|-----|
 | `DevToolsActivePort not found` | Open `chrome://inspect/#remote-debugging`, tick the checkbox, click Allow |
 | Connection fails after Chrome restart | Run `/browser-reload-daemon` |
-| Page seems loaded but content is missing | SPA — poll with `browser_execute_js` for the element you need |
-| A JS dialog is blocking actions | `browser_page_info` will report it — use `browser_handle_dialog` |
+| Page seems loaded but content is missing | SPA — call `browser_snapshot` again, or `browser_execute_js` for a specific element |
+| JS dialog is blocking actions | `browser_page_info` will report it — use `browser_handle_dialog` |
 | Daemon not starting | Run `/browser-setup` to re-run guided setup |
+| Snapshot didn't return `@(x,y)` for a target | Element wasn't recognized as interactive. Fall back to `browser_execute_js` with `getBoundingClientRect()` |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-browser-harness",
-  "version": "0.4.0",
+  "version": "0.5.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

@@ -21,6 +21,9 @@ What do you need to know?
   ├─ Network behavior on the current page?
   │     → browser_network_requests
   │
+  ├─ JS errors / why did nothing happen after an action?
+  │     → browser_console     (DIAGNOSTIC — only when something looks broken)
+  │
   └─ Visual rendering (layout / colors / chart drew correctly)?
         → browser_screenshot   (LAST RESORT — pixels only)
 ```
@@ -31,6 +34,10 @@ Pass `@(x,y)` from `browser_snapshot` straight to `browser_click`. No screenshot
 
 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`.
 
+## Diagnosing a "nothing happened" moment
+
+When an action runs but the page didn't change, capture `browser_console`'s `nextCursor` *before* the action, take the action, then call `browser_console({ sinceSeq: <cursor> })` after — this isolates what your action caused from what was already there. Pair with `browser_network_requests({ sinceMs: 5000 })` to see if an API call fired and failed. The console buffer is page-scoped: it clears on tab switch, capacity 500.
+
 ## Temporary scripts
 
 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.

package/src/cdp/console-buffer.ts

@@ -0,0 +1,263 @@
+/**
+ * In-memory aggregator for CDP Runtime.consoleAPICalled and Log.entryAdded events.
+ *
+ * Mirrors network-buffer.ts: the single CDP event loop in session.ts hands raw
+ * params to ingestConsoleApi / ingestLogEntry; tools later read records via drain().
+ *
+ * Bounded by capacity (default 500). On overflow the oldest record is evicted FIFO,
+ * and the overflow flag is reported once per drain so tools can warn the LLM that
+ * data may be missing.
+ *
+ * Each record carries a monotonic `seq`. Tools expose the last drained seq as
+ * `nextCursor`; callers pass it back as `sinceSeq` to read only what's new since
+ * the previous drain. This is the cursor pattern that makes "what did this action
+ * cause?" answerable in one tool call.
+ *
+ * Pure module (no CDP dependency) — joining/filtering logic stays trivially testable.
+ */
+
+export type ConsoleLevel = "log" | "info" | "warn" | "error" | "debug";
+
+export type ConsoleRecord = {
+  seq: number;
+  /** Wall-clock ms when the event was ingested, in Date.now() units. */
+  timestampMs: number;
+  level: ConsoleLevel;
+  /** Joined args (console-api) or the entry text (log-entry). Per-arg truncated. */
+  text: string;
+  source: "console-api" | "log-entry";
+  url?: string;
+  lineNumber?: number;
+  /** Top frames only, joined with newlines. Populated for error/warn when CDP provides one. */
+  stackTrace?: string;
+};
+
+export type ConsoleFilter = {
+  levels?: ConsoleLevel[];
+  /** Substring match by default. Wrap in slashes (`/foo/`) for regex. */
+  textPattern?: string;
+  /** Only records with seq strictly greater than this. */
+  sinceSeq?: number;
+  /** Only records with timestamp at most N ms ago. */
+  sinceMs?: number;
+  /** Cap on returned records (default 50, max 500). */
+  limit?: number;
+};
+
+export type ConsoleDrainResult = {
+  readonly records: ConsoleRecord[];
+  /** 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 ConsoleBuffer = {
+  ingestConsoleApi(p: unknown): void;
+  ingestLogEntry(p: unknown): void;
+  drain(filter: ConsoleFilter): ConsoleDrainResult;
+  clear(): void;
+};
+
+/** Per-arg cap to stop a single console.log(hugeBlob) from blowing the buffer. */
+const PER_ARG_CAP = 2000;
+/** Max stack frames preserved per record. */
+const MAX_STACK_FRAMES = 3;
+
+const compileTextMatcher = (pattern: string): ((text: string) => boolean) => {
+  if (pattern.length >= 2 && pattern.startsWith("/") && pattern.endsWith("/")) {
+    try {
+      const re = new RegExp(pattern.slice(1, -1));
+      return (text) => re.test(text);
+    } catch {
+      // Fall through to substring match if the pattern is not a valid regex.
+    }
+  }
+  return (text) => text.includes(pattern);
+};
+
+const truncateArg = (s: string): string =>
+  s.length > PER_ARG_CAP ? s.slice(0, PER_ARG_CAP) + "…" : s;
+
+/** Best-effort stringification of one Runtime.RemoteObject. */
+const stringifyRemoteObject = (
+  arg: { type?: string; subtype?: string; value?: unknown; description?: string; unserializableValue?: string },
+): string => {
+  if (arg.unserializableValue !== undefined) return arg.unserializableValue;
+  if (arg.value !== undefined) {
+    if (typeof arg.value === "string") return arg.value;
+    try {
+      return JSON.stringify(arg.value);
+    } catch {
+      return String(arg.value);
+    }
+  }
+  if (arg.description !== undefined) return arg.description;
+  return arg.type ?? "";
+};
+
+/** Map CDP console-API method names to our normalized levels. */
+const mapConsoleApiLevel = (type: string | undefined): ConsoleLevel => {
+  switch (type) {
+    case "error":
+    case "assert":
+      return "error";
+    case "warning":
+      return "warn";
+    case "debug":
+    case "trace":
+      return "debug";
+    case "info":
+      return "info";
+    default:
+      return "log";
+  }
+};
+
+/** Map Log.LogEntry.level values ("verbose","info","warning","error") to our levels. */
+const mapLogEntryLevel = (level: string | undefined): ConsoleLevel => {
+  switch (level) {
+    case "error":
+      return "error";
+    case "warning":
+      return "warn";
+    case "verbose":
+      return "debug";
+    default:
+      return "info";
+  }
+};
+
+const formatStackTrace = (
+  st: { callFrames?: ReadonlyArray<{ url?: string; lineNumber?: number; functionName?: string }> } | undefined,
+): string | undefined => {
+  const frames = st?.callFrames;
+  if (!frames || frames.length === 0) return undefined;
+  const top = frames.slice(0, MAX_STACK_FRAMES);
+  const rendered = top.map((f) => {
+    const fn = f.functionName !== undefined && f.functionName !== "" ? f.functionName : "<anonymous>";
+    const loc = f.url !== undefined && f.url !== "" ? `${f.url}:${(f.lineNumber ?? 0) + 1}` : "<unknown>";
+    return `  at ${fn} (${loc})`;
+  });
+  return rendered.join("\n");
+};
+
+export const createConsoleBuffer = (capacity = 500): ConsoleBuffer => {
+  // Insertion-ordered map keyed by seq. Map preserves insertion order in JS,
+  // so iteration gives us oldest-first eviction without a separate index.
+  const records = new Map<number, ConsoleRecord>();
+  let nextSeq = 1;
+  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 insert = (rec: ConsoleRecord): void => {
+    evictOldestIfFull();
+    records.set(rec.seq, rec);
+  };
+
+  return {
+    ingestConsoleApi(p) {
+      // CDP boundary cast: Runtime.consoleAPICalled
+      const params = p as
+        | {
+            type?: string;
+            args?: ReadonlyArray<{
+              type?: string;
+              subtype?: string;
+              value?: unknown;
+              description?: string;
+              unserializableValue?: string;
+            }>;
+            stackTrace?: { callFrames?: ReadonlyArray<{ url?: string; lineNumber?: number; functionName?: string }> };
+          }
+        | undefined;
+      if (!params) return;
+      const level = mapConsoleApiLevel(params.type);
+      const argTexts = (params.args ?? []).map((a) => truncateArg(stringifyRemoteObject(a)));
+      const text = argTexts.join(" ");
+      const stack = level === "error" || level === "warn" ? formatStackTrace(params.stackTrace) : undefined;
+      const top = params.stackTrace?.callFrames?.[0];
+      const rec: ConsoleRecord = {
+        seq: nextSeq++,
+        timestampMs: Date.now(),
+        level,
+        text,
+        source: "console-api",
+        ...(top?.url !== undefined && top.url !== "" ? { url: top.url } : {}),
+        ...(top?.lineNumber !== undefined ? { lineNumber: top.lineNumber + 1 } : {}),
+        ...(stack !== undefined ? { stackTrace: stack } : {}),
+      };
+      insert(rec);
+    },
+
+    ingestLogEntry(p) {
+      // CDP boundary cast: Log.entryAdded
+      const params = p as
+        | {
+            entry?: {
+              level?: string;
+              text?: string;
+              url?: string;
+              lineNumber?: number;
+              stackTrace?: { callFrames?: ReadonlyArray<{ url?: string; lineNumber?: number; functionName?: string }> };
+            };
+          }
+        | undefined;
+      const entry = params?.entry;
+      if (!entry) return;
+      const level = mapLogEntryLevel(entry.level);
+      const text = truncateArg(entry.text ?? "");
+      const stack = level === "error" || level === "warn" ? formatStackTrace(entry.stackTrace) : undefined;
+      const rec: ConsoleRecord = {
+        seq: nextSeq++,
+        timestampMs: Date.now(),
+        level,
+        text,
+        source: "log-entry",
+        ...(entry.url !== undefined && entry.url !== "" ? { url: entry.url } : {}),
+        ...(entry.lineNumber !== undefined ? { lineNumber: entry.lineNumber + 1 } : {}),
+        ...(stack !== undefined ? { stackTrace: stack } : {}),
+      };
+      insert(rec);
+    },
+
+    drain(filter) {
+      const matchText = filter.textPattern !== undefined ? compileTextMatcher(filter.textPattern) : undefined;
+      const levels = filter.levels && filter.levels.length > 0 ? new Set(filter.levels) : undefined;
+      const cutoff = filter.sinceMs !== undefined ? Date.now() - filter.sinceMs : undefined;
+      const sinceSeq = filter.sinceSeq;
+
+      const matched: ConsoleRecord[] = [];
+      for (const r of records.values()) {
+        if (sinceSeq !== undefined && r.seq <= sinceSeq) continue;
+        if (levels && !levels.has(r.level)) continue;
+        if (cutoff !== undefined && r.timestampMs < cutoff) continue;
+        if (matchText && !matchText(r.text)) continue;
+        matched.push({ ...r });
+      }
+
+      const total = matched.length;
+      const limit = Math.min(filter.limit ?? 50, 500);
+      const limited = matched.slice(-limit);
+
+      const bufferOverflowed = overflowed;
+      overflowed = false;
+
+      return { records: limited, total, bufferOverflowed };
+    },
+
+    clear() {
+      records.clear();
+      nextSeq = 1;
+      overflowed = false;
+    },
+  };
+};

package/src/cdp/session.ts

@@ -4,6 +4,20 @@ import type { DialogInfo } 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>>;
@@ -15,6 +29,7 @@ export type CdpSession = {
   takeDialog(): DialogInfo | null;
   drainPageInfoInvalidations(): boolean;
   drainNetworkBuffer(filter: NetworkFilter): DrainResult;
+  drainConsoleBuffer(filter: ConsoleFilter): ConsoleDrainResult;
 };
 
 export const createCdpSession = (
@@ -23,17 +38,33 @@ export const createCdpSession = (
 ): CdpSession => {
   let sessionId: string | null = null;
   let targetId: string | null = null;
-  let dialog: DialogInfo | null = null;
-  let pageInfoDirty = false;
-  const networkBuffer = createNetworkBuffer();
+
+  // 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 } : {}),
@@ -45,16 +76,40 @@ export const createCdpSession = (
       // 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);
+        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);
       }
-      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);
     }
   };
 
@@ -72,7 +127,8 @@ export const createCdpSession = (
   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();
@@ -82,7 +138,7 @@ export const createCdpSession = (
   // 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", "Accessibility"]) {
+    for (const d of ["Page", "DOM", "Runtime", "Network", "Accessibility", "Log"]) {
       await transport.request(`${d}.enable`, {}, { sessionId: sid });
     }
   };
@@ -111,6 +167,15 @@ export const createCdpSession = (
         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
@@ -139,6 +204,15 @@ export const createCdpSession = (
       sessionId = a.sessionId;
       targetId = pickTargetId;
       await enableDomains(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) {
@@ -147,13 +221,29 @@ export const createCdpSession = (
       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;
-      // 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);
     },
     current() {
@@ -169,17 +259,28 @@ export const createCdpSession = (
       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) {
-      return networkBuffer.drain(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/client.ts

@@ -98,7 +98,7 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
   const session = createCdpSession(transport, ownership);
   const mutationMutex = createMutex();
   let lastHealth = 0;
-  let pageCache: { readonly info: PageInfo; readonly at: number } | null = null;
+  let pageCaches = new Map<string, { readonly info: PageInfo; readonly at: number }>();
   let remote: BrowserClientOptions["remote"] | null = opts.remote ?? null;
 
   const start = async (): Promise<Result<void, CdpError>> => {
@@ -125,13 +125,13 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
       return attached;
     }
     lastHealth = Date.now();
-    pageCache = null;
+    pageCaches.clear();
     return ok(undefined);
   };
 
   const stop = async (): Promise<void> => {
     await transport.close();
-    pageCache = null;
+    pageCaches.clear();
     lastHealth = 0;
   };
 
@@ -155,7 +155,7 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
     if (!jsProbe.success && jsProbe.error.kind === "session_not_found") {
       const reattached = await session.attachFirstPage();
       if (reattached.success) {
-        pageCache = null;
+        pageCaches.clear();
         return ok(undefined);
       }
       await stop();
@@ -185,7 +185,9 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
 
   const readPageInfo = async (): Promise<Result<PageInfo, CdpError>> => {
     const dirty = session.drainPageInfoInvalidations();
-    if (pageCache && !dirty && Date.now() - pageCache.at < PAGE_INFO_TTL_MS) return ok(pageCache.info);
+    const currentTid = session.current()?.targetId;
+    const cached = currentTid ? pageCaches.get(currentTid) : undefined;
+    if (cached && !dirty && Date.now() - cached.at < PAGE_INFO_TTL_MS) return ok(cached.info);
     const expr = safeJs`JSON.stringify({url:location.href,title:document.title,w:innerWidth,h:innerHeight,sx:scrollX,sy:scrollY,pw:document.documentElement.scrollWidth,ph:document.documentElement.scrollHeight})`;
     const raw = await evaluateJs(expr);
     if (!raw.success) return raw;
@@ -198,7 +200,7 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
     }
     const info = parsePageInfoPayload(parsedRaw);
     if (!info.success) return info;
-    pageCache = { info: info.data, at: Date.now() };
+    if (currentTid) pageCaches.set(currentTid, { info: info.data, at: Date.now() });
     return ok(info.data);
   };
 
@@ -228,13 +230,17 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
     if (survivors.length !== owned.length) ownership.replaceAll(survivors);
     const hw = ownership.harnessWindow();
     if (hw && !live.has(hw)) ownership.setHarnessWindow(undefined);
+    // Prune per-tab page caches for tabs that no longer exist
+    for (const tid of pageCaches.keys()) {
+      if (!live.has(tid)) pageCaches.delete(tid);
+    }
     return ok(tabs);
   };
 
   const switchTab = async (targetId: string): Promise<Result<void, CdpError>> => {
     const r = await session.switchTo(targetId);
     if (!r.success) return r;
-    pageCache = null;
+    // pageCache per-tab: no longer cleared — each tab retains its cache
     // Best-effort: mark the tab title with a green circle so the user can
     // see which tab the agent attached to. CSP or detached frames may
     // block the eval; we don't surface that as a switchTab failure.
@@ -274,7 +280,6 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
     if (url && url !== "about:blank") {
       const nav = await session.call("Page.navigate", { url });
       if (!nav.success) return nav;
-      pageCache = null;
     }
     return ok(c.targetId);
   };

package/src/domains/console.ts

@@ -0,0 +1,173 @@
+import { Type } from "typebox";
+import { Markdown, Text } from "@mariozechner/pi-tui";
+import { getMarkdownTheme, keyHint } from "@mariozechner/pi-coding-agent";
+import { type Result, ok } from "../util/result";
+import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
+import { applyTruncation } from "../util/truncate";
+import type { ConsoleRecord, ConsoleLevel } from "../cdp/console-buffer";
+
+const ConsoleArgs = Type.Object({
+  levels: Type.Optional(
+    Type.Array(
+      Type.Union(
+        [
+          Type.Literal("log"),
+          Type.Literal("info"),
+          Type.Literal("warn"),
+          Type.Literal("error"),
+          Type.Literal("debug"),
+        ],
+      ),
+      { description: 'Filter to these levels only, e.g. ["error","warn"]. Default: all levels.' },
+    ),
+  ),
+  textPattern: Type.Optional(
+    Type.String({ description: "Substring match by default. Wrap in slashes (e.g. /TypeError/) for regex." }),
+  ),
+  sinceSeq: Type.Optional(
+    Type.Integer({ minimum: 0, description: "Only records with seq strictly greater than this. Use the previous call's nextCursor to see only what's new." }),
+  ),
+  sinceMs: Type.Optional(
+    Type.Integer({ minimum: 0, description: "Only records from the last N ms." }),
+  ),
+  limit: Type.Optional(
+    Type.Integer({ default: 50, minimum: 1, maximum: 500, description: "Max records to return." }),
+  ),
+});
+
+const levelTag = (lvl: ConsoleLevel): string => {
+  switch (lvl) {
+    case "error": return "[error]";
+    case "warn":  return "[warn] ";
+    case "info":  return "[info] ";
+    case "debug": return "[debug]";
+    default:      return "[log]  ";
+  }
+};
+
+const formatLocation = (r: ConsoleRecord): string => {
+  if (r.url === undefined || r.url === "") return "";
+  const short = r.url.length > 60 ? "…" + r.url.slice(-59) : r.url;
+  return r.lineNumber !== undefined ? `${short}:${r.lineNumber}` : short;
+};
+
+const renderConsoleMarkdown = (
+  records: ReadonlyArray<ConsoleRecord>,
+  opts: { total: number; bufferOverflowed: boolean; expanded: boolean; nextCursor: number | undefined },
+): string => {
+  if (records.length === 0) {
+    if (opts.bufferOverflowed) return "_No matching console records. (Buffer overflowed since last drain — some events were dropped.)_";
+    return "_No matching console records captured yet._";
+  }
+
+  const counts = records.reduce<Record<ConsoleLevel, number>>(
+    (acc, r) => { acc[r.level]++; return acc; },
+    { log: 0, info: 0, warn: 0, error: 0, debug: 0 },
+  );
+
+  const summaryParts: string[] = [];
+  if (counts.error > 0) summaryParts.push(`${counts.error} error${counts.error === 1 ? "" : "s"}`);
+  if (counts.warn  > 0) summaryParts.push(`${counts.warn} warning${counts.warn === 1 ? "" : "s"}`);
+  if (counts.info  > 0) summaryParts.push(`${counts.info} info`);
+  if (counts.log   > 0) summaryParts.push(`${counts.log} log${counts.log === 1 ? "" : "s"}`);
+  if (counts.debug > 0) summaryParts.push(`${counts.debug} debug`);
+
+  const headerLines: string[] = [`**${summaryParts.join(" · ")}**`];
+  if (opts.bufferOverflowed) headerLines.push("⚠ buffer overflowed since last drain — older entries dropped");
+  if (opts.total > records.length) headerLines.push(`(${records.length} of ${opts.total} matches shown — increase \`limit\` for more)`);
+
+  const renderRow = (r: ConsoleRecord, compact: boolean): string => {
+    const tag = levelTag(r.level);
+    const loc = formatLocation(r);
+    const maxText = compact ? 80 : 200;
+    const text = r.text.length > maxText ? r.text.slice(0, maxText - 1) + "…" : r.text;
+    const locSuffix = loc !== "" ? `  _at ${loc}_` : "";
+    const main = `\`${tag}\` ${text}${locSuffix}`;
+    if (!compact && r.stackTrace !== undefined) return `${main}\n\`\`\`\n${r.stackTrace}\n\`\`\``;
+    return main;
+  };
+
+  const visible = !opts.expanded && records.length > 5 ? records.slice(-5) : records;
+  const rows = visible.map((r) => renderRow(r, !opts.expanded)).join(opts.expanded ? "\n\n" : "\n");
+
+  const more = !opts.expanded && records.length > 5 ? `\n  … ${records.length - 5} earlier (expand to see all)` : "";
+  const cursor = opts.nextCursor !== undefined ? `\n\n_nextCursor=${opts.nextCursor}_` : "";
+
+  return `${headerLines.join("\n")}\n\n${rows}${more}${cursor}`;
+};
+
+type ConsoleDetails = {
+  total: number;
+  returned: number;
+  bufferOverflowed: boolean;
+  truncated: boolean;
+  fullOutputPath?: string;
+  records: ReadonlyArray<ConsoleRecord>;
+  nextCursor?: number;
+};
+
+export const consoleTool = defineBrowserTool({
+  name: "browser_console",
+  label: "Browser Console",
+  description:
+    "Read JS errors and console messages from the active tab. Diagnostic — use when an action looks broken or silent.",
+  promptSnippet: "Read JS errors / console output on the current tab",
+  promptGuidelines: [
+    "Use after a click, submit, or navigate produced no visible change — errors often explain it.",
+    "Pass `sinceSeq` from the previous call's `nextCursor` to see only new messages after an action.",
+    "Buffer is reset on tab switch (capacity 500 records). bufferOverflowed:true means older entries were dropped.",
+    "Don't use as a default observation tool — prefer browser_snapshot for page structure.",
+  ],
+  parameters: ConsoleArgs,
+
+  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const session = client.session();
+    const drained = session.drainConsoleBuffer({
+      ...(args.levels !== undefined ? { levels: args.levels } : {}),
+      ...(args.textPattern !== undefined ? { textPattern: args.textPattern } : {}),
+      ...(args.sinceSeq !== undefined ? { sinceSeq: args.sinceSeq } : {}),
+      ...(args.sinceMs !== undefined ? { sinceMs: args.sinceMs } : {}),
+      limit: args.limit ?? 50,
+    });
+
+    const last = drained.records.at(-1);
+    const nextCursor = last?.seq;
+
+    const text = renderConsoleMarkdown(drained.records, {
+      total: drained.total,
+      bufferOverflowed: drained.bufferOverflowed,
+      expanded: true, // full text always returned to the LLM; renderResult handles compact view for humans
+      nextCursor,
+    });
+    const trunc = await applyTruncation(text, "console");
+
+    const details: ConsoleDetails = {
+      total: drained.total,
+      returned: drained.records.length,
+      bufferOverflowed: drained.bufferOverflowed,
+      truncated: trunc.wasTruncated,
+      records: drained.records,
+      ...(nextCursor !== undefined ? { nextCursor } : {}),
+    };
+    if (trunc.fullOutputPath !== undefined) details.fullOutputPath = trunc.fullOutputPath;
+
+    return ok({ text: trunc.text, details });
+  },
+
+  renderResult(result, expanded, theme) {
+    const details = result.details as ConsoleDetails | undefined;
+    if (!details) return new Text(theme.fg("error", "console: no details"), 0, 0);
+
+    const md = renderConsoleMarkdown(details.records, {
+      total: details.total,
+      bufferOverflowed: details.bufferOverflowed,
+      expanded,
+      nextCursor: details.nextCursor,
+    });
+    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());
+  },
+});

package/src/prompt.ts

@@ -36,6 +36,7 @@ to interact with pages visually, and other tools alongside them.
 | browser_switch_tab | Switch to a different tab by targetId |
 | browser_execute_js | Execute JavaScript and return the result |
 | browser_http_get | Direct HTTP GET (outside browser, for APIs) |
+| browser_console | Read JS errors / console output on the current tab (diagnostic — use when an action looks broken; pass sinceSeq from the previous nextCursor to see only new messages) |
 | browser_wait | Wait N seconds |
 | browser_wait_for_load | Wait for document.readyState === 'complete' (returns a typed timeout error if the page doesn't reach readyState=complete in N seconds, default 15) |
 | browser_handle_dialog | Accept or dismiss a JS dialog |
@@ -73,6 +74,8 @@ browser_screenshot() + browser_page_info() + browser_execute_js("document.title"
 browser_http_get("https://api.example.com/data") + browser_click(x, y)
 \`\`\`
 
+**Multi-agent note**: When multiple subagents use the browser, tab switching by one agent changes the active tab for all agents. Per-tab data (console buffers, network traces, dialogs, page info cache) is isolated — switching tabs does not destroy another agent's collected data. Call \`browser_current_tab\` before mutation tools to confirm you're on the expected tab. If \`browser_page_info\` returns a dialog, handle it with \`browser_handle_dialog\` promptly — dialogs block page interaction and are not queued across agents.
+
 ### Common Patterns
 
 **Navigation:**

package/src/registry.ts

@@ -14,6 +14,7 @@ import { uploadFileTool, downloadTool, printToPdfTool } from "./domains/files";
 import { viewportResizeTool } from "./domains/viewport";
 import { dragAndDropTool } from "./domains/drag";
 import { httpGetTool, networkRequestsTool } from "./domains/network";
+import { consoleTool } from "./domains/console";
 import { snapshotTool } from "./domains/snapshot";
 import { executeJsTool, runScriptTool } from "./domains/js";
 
@@ -48,6 +49,7 @@ const TOOLS: ReadonlyArray<AnyBrowserToolDefinition> = [
   { ...dragAndDropTool, serialized: true },
   httpGetTool,
   networkRequestsTool,
+  consoleTool,
   snapshotTool,
   executeJsTool,
   runScriptTool,