feat: add browser routing cache

[rgarcia]

Summary

• remove the public browser_routing= client constructor config and move rollout control to KERNEL_BROWSER_ROUTING_SUBRESOURCES
• default direct-to-VM request rewriting to curl when the env var is unset, and treat an explicit empty string as disabling browser subresource routing
• keep browser_route_cache public for inspection/debugging while deriving routing behavior internally from the environment on Kernel / AsyncKernel
• keep browsers.request() and browsers.stream() cache-backed so raw HTTP continues to go directly to the browser VM’s /curl/raw path with protected url / jwt params

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.request() / browsers.stream() still always go direct to the browser VM because they resolve through the cached browser route and /curl/raw

Test plan

• .venv/bin/pytest tests/test_browser_routing.py tests/test_client.py -o addopts=
• .venv/bin/ruff check src/kernel/_client.py src/kernel/lib/browser_routing/routing.py src/kernel/resources/browsers/browsers.py src/kernel/__init__.py tests/test_browser_routing.py examples/browser_routing.py
• PYTHONPATH=src KERNEL_API_KEY=... KERNEL_BASE_URL=https://api.onkernel.com .venv/bin/python examples/browser_routing.py

---

Note

Medium Risk
Medium risk because it changes core HTTP request/response processing in Kernel/AsyncKernel, including URL rewriting and stripping Authorization headers based on cached routes, which could impact request routing or auth if misapplied.

Overview
Adds a browser route cache to Kernel/AsyncKernel and hooks it into the client lifecycle: responses from browser metadata endpoints populate the cache, successful browser deletes/pool releases evict it, and outgoing requests can be rewritten to hit the browser VM directly.

Introduces env-controlled direct routing via KERNEL_BROWSER_ROUTING_SUBRESOURCES (defaulting to curl, empty string disables) and ensures routed requests inject jwt while removing API Authorization headers.

Adds browsers.request()/browsers.stream() (sync + async) to perform raw HTTP via the browser VM’s /curl/raw endpoint with reserved query keys (url, jwt) protected, plus an example script and comprehensive tests for cache warming/eviction and allowlisted routing behavior.

^{Reviewed by Cursor Bugbot for commit 5328730. 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 adds browser-scoped session client functionality but does not appear to modify API endpoints (packages/api/cmd/api/) or Temporal workflows (packages/api/lib/temporal) as specified in the filter.

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 3ce80e7. Configure here.}

[Sayan-]

great stuff - thanks for iterating on the shape!

[Sayan-]

great stuff - thanks for iterating on the shape!