feat: add browser routing cache

[rgarcia]

Summary

• keep browser routing centered on a shared browser_route_cache plus direct-to-VM request rewriting
• remove the public cache-priming helper so cached routes are always normalized before use and JWTs remain required for direct VM requests
• rename the browser routing allowlist field to subresources so configuration reads more naturally
• rename the example and focused test file to browser-routing terminology while keeping the custom raw HTTP helpers cache-backed

Test plan

• .venv/bin/pytest tests/test_browser_routing.py -o addopts=

---

Note

Medium Risk
Introduces request URL rewriting and automatic Authorization stripping for allowlisted browser subresources, which could misroute calls or change auth behavior if the cache/config is incorrect. Adds new raw HTTP request/stream helpers that rely on cached JWTs and parameter sanitization.

Overview
Adds cache-backed direct-to-VM browser routing: Kernel/AsyncKernel now accept browser_routing and maintain a shared browser_route_cache, rewriting matching /browsers/{session}/{subresource}/... calls to the browser VM base URL and injecting jwt while removing Authorization on direct-to-VM requests.

Extends browsers with request()/stream() (sync + async) for raw HTTP via /curl/raw, sanitizing user query params so url/jwt cannot be overridden, and auto-populates the route cache from browsers.create/retrieve/update/list. Includes a new examples/browser_routing.py and focused tests covering routing allowlists, auth stripping, /curl/raw behavior, and cache requirements.

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

[cursor]

Cache stores route under unnormalized session ID key

Low Severity

BrowserRouteCache.set() uses the original route.session_id as the dictionary key but stores a BrowserRoute whose session_id is route.session_id.strip(). If the incoming session ID has any whitespace, subsequent cache.get() calls with the stripped ID won't find the entry, and cache.delete() with the stripped ID also won't remove it. The key and the stored value's session_id are inconsistent.

 

^{Reviewed by Cursor Bugbot for commit 3ce80e7. Configure here.}