feat: route browser telemetry directly to the VM by default

[rgarcia]

What

• Telemetry method path: client.browsers.telemetry.stream() now calls GET /browsers/{id}/telemetry/stream (was /browsers/{id}/telemetry). This mirrors the browser VM, where the SSE stream lives at {base_url}/telemetry/stream while {base_url}/telemetry is a different (non-streaming, JSON config) endpoint. With the new path, the direct-routing rewrite correctly yields {base_url}/telemetry/stream.
• Default routing: added "telemetry" to the default KERNEL_BROWSER_ROUTING_SUBRESOURCES list (['curl'] -> ['curl', 'telemetry']), so telemetry streams route directly to the VM with no env var required.
• Updated api.md and the routing unit tests (default list assertion + a new test proving a telemetry call rewrites to {base_url}/telemetry/stream with the Authorization header stripped).

Depends on

The control-plane PR renaming the public endpoint /browsers/{id}/telemetry -> /browsers/{id}/telemetry/stream. That is not yet deployed to prod, so until it ships, telemetry.stream() only works via direct routing (a non-routed call to the new path 404s in prod). This also independently proves routing is doing the work.

Live smoke evidence (prod)

Ran examples/smoke-browser-telemetry.ts against https://api.onkernel.com with an instrumented custom fetch:

• Telemetry stream outbound URL: https://proxy.yul-funny-austin.onkernel.com:8443/browser/kernel/telemetry/stream?jwt=...
• Host matches the session base_url (proxy host, :8443), not api.onkernel.com
• Path ends with /telemetry/stream; jwt query param present; Authorization header stripped
• 1 telemetry event received (type=api_call) within ~1s of generating activity via browsers.curl
• Browser deleted in finally

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes default fetch routing for telemetry SSE (auth stripped, VM URL rewrite); depends on control-plane /telemetry/stream being deployed for non-routed calls.

Overview
Browser telemetry SSE now uses the same direct-to-VM routing as curl by default: telemetry is included in DEFAULT_BROWSER_ROUTING_SUBRESOURCES, so browsers.telemetry.stream() is rewritten to {session base_url}/telemetry/stream with a jwt query param and without forwarding Authorization.

Tests assert the expanded default subresource list and that a telemetry stream request hits the VM path. A new examples/browser-telemetry.ts sample creates a browser with telemetry on, streams a few events after curl activity, then deletes the session.

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

[firetiger-agent]

Created a monitoring plan for this PR.

What this PR does: Fixes the browser telemetry stream endpoint URL in the SDK (/telemetry → /telemetry/stream) and enables VM-direct routing for telemetry calls by default, so the stream connects directly to the browser VM rather than going through the API gateway.

Intended effect:

• Telemetry stream path: baseline 8 hits/24h on old path (/telemetry), 0 on new path; confirmed if new path (/telemetry/stream) returns 200/streaming with no 404s
• Browser API 5xx rate: baseline 0–9 5xx/hr on browser paths (0.002–0.018%); confirmed stable if it remains below 0.05% post-deploy
• VM-direct routing: confirmed if outbound telemetry stream requests go to the VM base URL with jwt param and no Authorization header (verified by smoke test log SMOKE_RESULT eventsObserved=N)

Risks:

• 404 on new path — if the API server doesn't serve GET /browsers/{id}/telemetry/stream, SDK callers get 404; alert if any 404 appears on %telemetry/stream% in API logs
• Old-path breakage — callers on older SDK versions hitting the old /browsers/{id}/telemetry path may see changed behavior; alert if old path returns 404 post-deploy
• VM routing auth mismatch — if JWT not appended or auth header not stripped, VM rejects the connection; no railway-log signal (VM-direct), but observable as empty/closed streams client-side; alert on any user-reported telemetry stream failures
• Route cache miss fallback — if session route isn't cached, request falls back to the API; alert if /telemetry/stream appears in API logs with non-200 status codes

Status updates will be posted automatically on this PR as monitoring progresses.

View monitor