Add browser telemetry reads and debugging guidance

[yummybomb]

summary

• add get_browser_telemetry 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; current capture state is appended to the note
• 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
Expands a high-traffic MCP tool with new query semantics and SDK telemetry calls; behavior is read-only for telemetry but affects agent debugging workflows and token-sized responses.

Overview
Adds manage_browsers action get_telemetry so agents can read archived browser telemetry for active or deleted sessions. Queries support category filters, since/until, asc/desc, and opaque next_offset paging; since with order=desc is rejected with a clear error. Default unfiltered ascending reads use the Unix epoch instead of the API’s five-minute since default so the first page starts at session creation. Responses compact event payloads (always drop body, headers, post_data, png; cap other fields at 8 KiB) and return compact JSON with note hints on empty pages (including whether capture is currently disabled).

Introduces shared src/lib/mcp/telemetry.ts (telemetryEventCategories, TELEMETRY_EVENT_CATALOG) reused in tool schemas and the debug-browser-session prompt, which is reworked to be telemetry-first (opt-in capture vs archive, paging heuristics). README documents telemetry on manage_browsers; create/update telemetry param descriptions clarify the default lightweight bundle vs debug categories.

^{Reviewed by Cursor Bugbot for commit 94477c7. 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 3:28pm

[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.}

Want fixes drafted automatically? Bugbot Autofix can create code changes for findings. A team admin can enable Autofix in the Cursor dashboard.

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