fix: require base_url for browser-scoped routing

Fail fast when browser-scoped clients do not have a session base_url, route subresource calls through the browser session base directly, and clean up browser-vm wording.

Made-with: Cursor

Author: rgarcia

examples/browser-scoped.ts

@@ -1,5 +1,5 @@
 /**
- * Browser-scoped client: call metro-routed browser APIs without repeating the
+ * Browser-scoped client: call browser VM-routed browser APIs without repeating the
  * session id, and run `fetch`-style HTTP through the browser network stack.
  *
  * Run after `yarn build` so `dist/` matches sources, or import from `src/` via

src/client.ts

@@ -881,9 +881,9 @@ export class Kernel {
   }
 
   /**
-   * Returns a browser-scoped client: subresource calls omit the session id and,
-   * when the browser response includes base_url, requests are routed through the
-   * metro HTTP base for that session.
+   * Returns a browser-scoped client: subresource calls omit the session id and
+   * are routed through {@link BrowserCreateResponse.base_url} (browser session
+   * HTTP base URL for the browser VM edge). Requires base_url on the browser object.
    */
   public forBrowser(browser: KernelBrowserInput): KernelBrowserSession {
     return new KernelBrowserSession(this, browser);

src/lib/browser-transport.ts

@@ -1,10 +1,10 @@
 import type { RequestOptions } from '../internal/request-options';
 
 /**
- * Resolved HTTP routing for a browser session. Metro requests use defaultBaseURL
- * plus a per-request jwt query param. A future client-wide browser-id → base_url
- * cache can plug in by supplying an alternate resolver before constructing
- * {@link KernelBrowserSession}.
+ * Resolved HTTP routing for a browser session. When {@link ResolvedBrowserTransport.defaultBaseURL}
+ * is set, requests use that browser session base URL plus a per-request jwt query param.
+ * A future client-wide browser-id → base_url cache can plug in by supplying an alternate
+ * resolver before constructing {@link KernelBrowserSession}.
  */
 export type ResolvedBrowserTransport = {
   sessionId: string;

src/lib/kernel-browser-session.ts

@@ -306,7 +306,7 @@ export interface BrowserPoolAcquireResponse {
   webdriver_ws_url: string;
 
   /**
-   * Metro-API HTTP base URL for this browser session.
+   * HTTP base URL for routing browser subresource requests to this session's browser VM.
    */
   base_url?: string;
 

src/resources/browser-pools.ts

@@ -319,7 +319,7 @@ export interface BrowserCreateResponse {
   webdriver_ws_url: string;
 
   /**
-   * Metro-API HTTP base URL for this browser session.
+   * HTTP base URL for routing browser subresource requests to this session's browser VM.
    */
   base_url?: string;
 
@@ -425,7 +425,7 @@ export interface BrowserRetrieveResponse {
   webdriver_ws_url: string;
 
   /**
-   * Metro-API HTTP base URL for this browser session.
+   * HTTP base URL for routing browser subresource requests to this session's browser VM.
    */
   base_url?: string;
 
@@ -531,7 +531,7 @@ export interface BrowserUpdateResponse {
   webdriver_ws_url: string;
 
   /**
-   * Metro-API HTTP base URL for this browser session.
+   * HTTP base URL for routing browser subresource requests to this session's browser VM.
    */
   base_url?: string;
 
@@ -637,7 +637,7 @@ export interface BrowserListResponse {
   webdriver_ws_url: string;
 
   /**
-   * Metro-API HTTP base URL for this browser session.
+   * HTTP base URL for routing browser subresource requests to this session's browser VM.
    */
   base_url?: string;
 

src/resources/browsers/browsers.ts

@@ -454,7 +454,7 @@ export namespace InvocationListBrowsersResponse {
     webdriver_ws_url: string;
 
     /**
-     * Metro-API HTTP base URL for this browser session.
+     * HTTP base URL for routing browser subresource requests to this session's browser VM.
      */
     base_url?: string;
 

src/resources/invocations.ts

@@ -6,26 +6,26 @@ import {
 
 describe('browser transport', () => {
   test('parseJwtFromCdpWsUrl reads jwt query param', () => {
-    const jwt = parseJwtFromCdpWsUrl('wss://metro.example/browser/cdp?jwt=abc%2B123&x=1');
+    const jwt = parseJwtFromCdpWsUrl('wss://browser-session.test/browser/cdp?jwt=abc%2B123&x=1');
     expect(jwt).toBe('abc+123');
   });
 
   test('resolveBrowserTransport prefers explicit jwt', () => {
     const t = resolveBrowserTransport({
       session_id: 'sess',
-      base_url: 'https://metro/browser/kernel',
+      base_url: 'https://vm.browser-session.test/browser/kernel',
       cdp_ws_url: 'wss://x/cdp?jwt=fromcdp',
       jwt: 'explicit',
     });
     expect(t.sessionId).toBe('sess');
-    expect(t.defaultBaseURL).toBe('https://metro/browser/kernel');
+    expect(t.defaultBaseURL).toBe('https://vm.browser-session.test/browser/kernel');
     expect(t.jwt).toBe('explicit');
   });
 
   test('resolveBrowserTransport falls back to cdp_ws_url jwt', () => {
     const t = resolveBrowserTransport({
       session_id: 'sess',
-      base_url: 'https://metro/browser/kernel',
+      base_url: 'https://vm.browser-session.test/browser/kernel',
       cdp_ws_url: 'wss://x/cdp?jwt=fromcdp',
     });
     expect(t.jwt).toBe('fromcdp');
@@ -40,7 +40,7 @@ describe('browser transport', () => {
     expect(merged?.query).toEqual({ a: '1', jwt: 'j' });
   });
 
-  test('mergeBrowserScopedRequestOptions is noop without metro base', () => {
+  test('mergeBrowserScopedRequestOptions is noop without browser session base URL', () => {
     const opts = { query: { a: '1' } };
     const merged = mergeBrowserScopedRequestOptions({ sessionId: 's' }, opts);
     expect(merged).toBe(opts);

tests/lib/browser-transport.test.ts

@@ -1,27 +1,29 @@
 import Kernel from '@onkernel/sdk';
 import { KernelBrowserSession } from '../../src/lib/kernel-browser-session';
 
-describe('KernelBrowserSession.fetch', () => {
-  test('throws when base_url is missing', async () => {
+describe('KernelBrowserSession', () => {
+  test('throws when base_url is missing', () => {
     const kernel = new Kernel({ apiKey: 'k', baseURL: 'https://api.example/' });
-    const browser = new KernelBrowserSession(kernel, {
-      session_id: 'abc',
-      cdp_ws_url: 'wss://x/browser/cdp?jwt=j',
-    });
-    await expect(browser.fetch('https://example.com')).rejects.toThrow(/base_url/);
+    expect(
+      () =>
+        new KernelBrowserSession(kernel, {
+          session_id: 'abc',
+          cdp_ws_url: 'wss://x/browser/cdp?jwt=j',
+        }),
+    ).toThrow(/base_url/);
   });
 
   test('throws when jwt cannot be resolved', async () => {
     const kernel = new Kernel({ apiKey: 'k', baseURL: 'https://api.example/' });
     const browser = new KernelBrowserSession(kernel, {
       session_id: 'abc',
-      base_url: 'https://metro/browser/kernel',
+      base_url: 'https://vm.browser-session.test/browser/kernel',
       cdp_ws_url: 'wss://x/browser/cdp',
     });
     await expect(browser.fetch('https://example.com')).rejects.toThrow(/jwt/);
   });
 
-  test('issues /curl/raw against metro base with jwt query', async () => {
+  test('issues /curl/raw against browser session base URL with jwt query', async () => {
     const fetchCalls: Array<{ url: string; init: RequestInit | undefined }> = [];
     const kernel = new Kernel({ apiKey: 'k', baseURL: 'https://api.example/' });
     (kernel as any).fetch = async (url: string, init?: RequestInit) => {
@@ -34,7 +36,7 @@ describe('KernelBrowserSession.fetch', () => {
 
     const browser = new KernelBrowserSession(kernel, {
       session_id: 'abc',
-      base_url: 'https://metro/browser/kernel',
+      base_url: 'https://vm.browser-session.test/browser/kernel',
       cdp_ws_url: 'wss://x/browser/cdp?jwt=tok',
     });
 
@@ -45,13 +47,13 @@ describe('KernelBrowserSession.fetch', () => {
     expect(res.status).toBe(200);
     expect(fetchCalls.length).toBe(1);
     const call = fetchCalls[0]!;
-    expect(call.url).toContain('https://metro/browser/kernel/curl/raw?');
+    expect(call.url).toContain('https://vm.browser-session.test/browser/kernel/curl/raw?');
     expect(call.url).toContain('url=https%3A%2F%2Fexample.com%2Fhello');
     expect(call.url).toContain('jwt=tok');
     expect((call.init?.headers as Headers).get('authorization')).toBeNull();
   });
 
-  test('rewrites browser subresource paths through metro base', async () => {
+  test('rewrites browser subresource paths through browser session base URL', async () => {
     const fetchCalls: Array<{ url: string; init: RequestInit | undefined }> = [];
     const kernel = new Kernel({ apiKey: 'k', baseURL: 'https://api.example/' });
     (kernel as any).fetch = async (url: string, init?: RequestInit) => {
@@ -64,15 +66,15 @@ describe('KernelBrowserSession.fetch', () => {
 
     const browser = new KernelBrowserSession(kernel, {
       session_id: 'abc',
-      base_url: 'https://metro/browser/kernel',
+      base_url: 'https://vm.browser-session.test/browser/kernel',
       cdp_ws_url: 'wss://x/browser/cdp?jwt=tok',
     });
 
     await browser.computer.clickMouse({ x: 1, y: 2 });
 
     expect(fetchCalls.length).toBe(1);
     const call = fetchCalls[0]!;
-    expect(call.url).toContain('https://metro/browser/kernel/computer/click_mouse?');
+    expect(call.url).toContain('https://vm.browser-session.test/browser/kernel/computer/click_mouse?');
     expect(call.url).toContain('jwt=tok');
     expect(call.url).not.toContain('/browsers/abc/');
     expect((call.init?.headers as Headers).get('authorization')).toBeNull();