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
Changes request preparation to rewrite certain /browsers/{id}/... calls to a browser VM base URL and strips Authorization headers on those requests, which could affect routing/auth behavior if misconfigured. Adds new raw HTTP APIs (browsers.request/browsers.stream) that depend on cached routes and env-based allowlisting.

Overview
Introduces direct-to-VM browser subresource routing driven by KERNEL_BROWSER_ROUTING_SUBRESOURCES (defaults to routing curl, empty string disables), backed by a new public browser_route_cache stored on Kernel/AsyncKernel.

The client now rewrites matching /browsers/{session_id}/{subresource}/... request URLs to the cached browser VM base_url and injects a jwt query param, while removing Authorization for direct-to-VM requests.

Adds new browsers.request() and browsers.stream() (sync/async) APIs that proxy raw HTTP via the browser VM’s /curl/raw, sanitizing user params so url/jwt cannot be overridden, plus an example and targeted tests covering allowlisting, auth stripping, and param sanitization.

^{Reviewed by Cursor Bugbot for commit f4c247b. 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.}