feat: add browser routing cache

[rgarcia]

Summary

• remove the public browserRouting client constructor config and move rollout control to KERNEL_BROWSER_ROUTING_SUBRESOURCES
• default direct-to-VM request interception to curl when the env var is unset, and treat an explicit empty string as disabling browser subresource routing
• keep BrowserRouteCache public for debugging while making the routing fetch wrapper fully internal to the client constructor and withOptions()
• keep browsers.fetch() cache-backed so raw HTTP continues to go directly to the browser VM’s /curl/raw path with no control-plane fallback

Rollout behavior

• env var unset: route only curl subresources directly to the browser VM
• env var set to "": disable browser subresource routing entirely
• env var set to a comma-separated list: route exactly those subresources directly to the browser VM
• browsers.fetch() still always goes direct to the browser VM because it resolves through the shared browser route cache and /curl/raw

Test plan

• ./node_modules/.bin/jest tests/lib/browser-routing.test.ts
• ./node_modules/.bin/eslint src/client.ts src/lib/browser-routing.ts src/index.ts tests/lib/browser-routing.test.ts examples/browser-routing.ts
• ./node_modules/.bin/tsc -p tsconfig.json --noEmit
• KERNEL_API_KEY=... KERNEL_BASE_URL=https://api.onkernel.com ./node_modules/.bin/ts-node examples/browser-routing.ts

---

Note

Medium Risk
Wraps the client’s fetch to transparently reroute some /browsers/{session}/{subresource} calls directly to the browser VM based on cached route data, which could affect request routing/headers and break integrations if misconfigured.

Overview
Adds a shared BrowserRouteCache that is auto-populated by sniffing JSON API responses for browser session_id/base_url and a JWT (from jwt or cdp_ws_url). The Kernel client now wraps its underlying fetch to intercept allowlisted /browsers/{sessionId}/{subresource} requests and send them directly to the browser VM base_url, stripping authorization and injecting jwt as a query param.

Rollout is controlled by KERNEL_BROWSER_ROUTING_SUBRESOURCES (unset defaults to routing curl; empty string disables routing; comma-list routes those subresources). Adds browsers.fetch() implemented via new browserFetch() to always issue raw HTTP through the VM’s /curl/raw endpoint using the cache, expands HTTPMethod to include head/options, exports the new types, and includes an example and Jest coverage for routing/cache/withOptions() behavior.

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

[firetiger-agent]

Firetiger deploy monitoring skipped

This PR didn't match the auto-monitor filter configured on your GitHub connection:

Any PR that changes the kernel API. Monitor changes to API endpoints (packages/api/cmd/api/) and Temporal workflows (packages/api/lib/temporal) in the kernel repo

Reason: PR modifies client library code (browser session client) rather than API endpoints or Temporal workflows in packages/api/

To monitor this PR anyway, reply with @firetiger monitor this.

[cursor]

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

^{Bugbot Autofix is ON. A cloud agent has been kicked off to fix the reported issue. You can view the agent here.}

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

[cursor]

Every JSON response cloned and parsed unnecessarily

Medium Severity

sniffAndPopulateCache is await-ed on every single fetch response — including non-browser endpoints like deployments, invocations, credentials, etc. For every JSON response, the body is cloned and fully parsed before the response is returned to the caller. This blocks the caller until the entire response body has been received and parsed as JSON, adding latency proportional to response size on every API call. Only responses to browser-related paths (matching the /browsers/ pattern) can ever contain cacheable route data, so the work is wasted for all other endpoints.

Additional Locations (1)

• src/lib/browser-routing.ts#L96-L108

 

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