Add browser telemetry reads and debugging guidance

[yummybomb]

summary

• add a get_telemetry action to manage_browsers for archived browser telemetry: works for active and deleted sessions, including events captured before telemetry was disabled
• support category filters, time windows (since/until), ascending/descending reads, and opaque offset pagination; since + order=desc is rejected up front with a clear error
• default unfiltered ascending reads to the Unix epoch instead of the API's five-minute default, so the initial page starts at the beginning of the session (the archive cannot predate the session, so no extra browser lookup is needed)
• compact event payloads: always drop body, headers, post_data, and screenshot png, plus any data field over 8 KiB; report every removal in omitted_fields and keep seq, raw ts (µs), readable time, source, and truncated
• signal empty results through short notes instead of a status field (which collided with the list status param): empty filtered pages with more data tell the caller to continue; terminal empty reads say whether anything is archived (an explicit since at or before session creation counts as a full-session read); current capture state is appended to the note
• steer agents away from paging a long archive oldest-first: unfiltered ascending pages with more data carry a note pointing at order=desc, and the order description says when desc is the better read
• expand manage_browsers telemetry category descriptions (default bundle gotcha, per-category definitions)
• rework the debug-browser-session prompt: telemetry-first heuristics instead of a fixed script, the opt-in/archive-vs-config gotcha, and the shared event catalog (defined once in src/lib/mcp/telemetry.ts, reused verbatim)

The required SDK update and pagination migrations landed in #122; this branch is rebased onto main.

live verification (production)

Exercised the actual tool handlers end-to-end against production: created a browser with console/network/page telemetry via manage_browsers, drove a navigation, an intentional console error, and a failing page load, then verified: full-session default reads, omitted_fields compaction, a category filter isolating the planted console_error (51.8KB → 1KB), order=desc, filter misses, since+desc rejection, current-disabled hints, never-enabled sessions, and post-deletion reads.

verification

• bun install --frozen-lockfile
• bunx tsc --noEmit
• Prettier check on changed source files
• desc/empty-archive and deleted-session note behavior verified against the API implementation in kernel/kernel (packages/api/cmd/api/api/telemetry.go, browsers.go)

The repository does not have an automated test suite.

---

Note

Medium Risk
New read path on manage_browsers and richer telemetry create/update docs affect agent debugging workflows; behavior is read-only for telemetry but touches session diagnosis flows many agents rely on.

Overview
Adds get_telemetry to manage_browsers so agents can read archived browser telemetry for active or deleted sessions, with category filters, since/until, asc/desc ordering, and opaque next_offset pagination. Unfiltered ascending reads default to the full session (epoch since instead of the API’s five-minute window); since + order=desc is rejected with a clear error. Responses compact event payloads (drop heavy fields, cap field size, surface omitted_fields) and use note text for empty results and to steer away from paging long archives oldest-first.

Introduces shared src/lib/mcp/telemetry.ts (category list + event catalog) reused in tool schemas and the debug-browser-session prompt, which is reworked to be telemetry-first (opt-in capture vs archive, enable debug categories via update). README and create/update telemetry param descriptions clarify defaults and debug categories.

^{Reviewed by Cursor Bugbot for commit 260708e. Bugbot is set up for automated code reviews on this repo. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
mcp	Ready	Preview, Comment	Jul 16, 2026 6:20pm

[Sayan-]

I know this is wip but fly by initial reactions from opus

Overall looking good + nothing blocking.

One field escapes the compaction. It strips body/headers/post_data (great for network events) but misses the screenshot event's png — a full base64 image the schema flags as "high volume." Screenshots are off by default so most reads are fine, but when they're on, an unfiltered read dumps full images into context, which is what compaction is meant to prevent. Quick fix: add png. Sturdier fix: drop by size (trim any oversized field, note it in omitted_fields) so new bulky fields don't slip through later.

Worth a think: the empty-result logic is doing a lot. Three statuses (ok/no_events/telemetry_currently_disabled) plus tailored prose per branch is the most involved part and looks like it took the most churn to settle. Fair to ask whether it can relax to a simple status + short note before more wording passes.

Worth a think: standalone tool vs. an action on manage_browsers. README's house style is one manage_* per feature; telemetry arguably belongs to browsers. Precedent for standalone exists (browser_curl), so not wrong — just cheap to settle now, annoying to move later.

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit f4cc8d3. Configure here.}

[yummybomb]

I know this is wip but fly by initial reactions from opus

Overall looking good + nothing blocking.

One field escapes the compaction. It strips body/headers/post_data (great for network events) but misses the screenshot event's png — a full base64 image the schema flags as "high volume." Screenshots are off by default so most reads are fine, but when they're on, an unfiltered read dumps full images into context, which is what compaction is meant to prevent. Quick fix: add png. Sturdier fix: drop by size (trim any oversized field, note it in omitted_fields) so new bulky fields don't slip through later.

Worth a think: the empty-result logic is doing a lot. Three statuses (ok/no_events/telemetry_currently_disabled) plus tailored prose per branch is the most involved part and looks like it took the most churn to settle. Fair to ask whether it can relax to a simple status + short note before more wording passes.

Worth a think: standalone tool vs. an action on manage_browsers. README's house style is one manage_* per feature; telemetry arguably belongs to browsers. Precedent for standalone exists (browser_curl), so not wrong — just cheap to settle now, annoying to move later.

Addressed all three.

• Added screenshots to be compacted.
• Added note strings for simplicity
• Standalone get_browser_telemetry tool → manage_browsers action to follow the README's house style