feat: add browser-scoped session client

[rgarcia]

Summary

• add kernel.forBrowser(...) to create a browser-scoped client from a browser session response
• route browser subresource methods through the session base_url so callers stop repeating the browser id
• expose raw HTTP through browser.fetch(...) while keeping the internal /curl/raw transport path hidden
• add focused tests for metro routing, JWT propagation, and browser-scoped fetch behavior

Test plan

• ./node_modules/.bin/tsc --noEmit
• ./node_modules/.bin/jest tests/lib/browser-transport.test.ts tests/lib/kernel-browser-session.test.ts

Made with Cursor

---

Note

Medium Risk
Introduces a new request-routing mode that rewrites browser subresource paths and changes auth behavior (drops Authorization and relies on jwt query params), which could affect how browser-session requests are authenticated and routed.

Overview
Adds a browser-scoped session client via kernel.forBrowser(...), returning KernelBrowserSession that lets callers invoke browser subresources without repeating session_id and routes those calls through the browser session base_url.

Introduces browser.fetch(...) to proxy HTTP through the browser VM network stack by calling internal POST /curl/raw, and adds transport helpers to resolve base_url and jwt (from cdp_ws_url or explicit) and inject jwt into query params.

Adds a codegen script (scripts/generate-browser-session.ts) and committed generated bindings for browser subresources, wires generation into build/lint, exports the new APIs from src/index.ts, and adds tests plus an example demonstrating the new browser-scoped usage.

^{Reviewed by Cursor Bugbot for commit c5731cb. 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 2 potential issues.

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

^{Reviewed by Cursor Bugbot for commit 7486cd4. Configure here.}

[cursor]

Path prefix matching ignores SDK URL encoding

Low Severity

The prepareOptions override builds the prefix with raw string interpolation (`/browsers/${transport.sessionId}/`), but the SDK's path tagged template in resource methods (e.g., path`/browsers/${id}/...`) runs path parameters through encodeURIPath. If a session_id ever contains characters outside the URI-safe set, the encoded path won't match the raw prefix, so the path won't be rewritten and requests will hit the wrong endpoint.

 

^{Reviewed by Cursor Bugbot for commit 7486cd4. Configure here.}