feat: add browser-scoped session client

Bind browser subresource calls to a browser session's base_url and expose raw HTTP through fetch so metro-routed access feels like normal JavaScript networking.

Made-with: Cursor

Author: rgarcia

examples/browser-scoped.ts

@@ -0,0 +1,24 @@
+/**
+ * Browser-scoped client: call metro-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
+ * ts-node with path aliases.
+ */
+import Kernel from '@onkernel/sdk';
+
+async function main() {
+  const kernel = new Kernel();
+
+  const created = await kernel.browsers.create({});
+  const browser = kernel.forBrowser(created);
+
+  await browser.computer.clickMouse({ x: 10, y: 10 });
+
+  const page = await browser.fetch('https://example.com', { method: 'GET' });
+  console.log('status', page.status);
+
+  await kernel.browsers.deleteByID(created.session_id);
+}
+
+void main();

src/client.ts

@@ -67,6 +67,7 @@ import {
   Deployments,
 } from './resources/deployments';
 import { KernelApp } from './core/app-framework';
+import { KernelBrowserSession, type KernelBrowserInput } from './lib/kernel-browser-session';
 import {
   ExtensionDownloadFromChromeStoreParams,
   ExtensionListResponse,
@@ -879,6 +880,15 @@ export class Kernel {
     return new KernelApp(name);
   }
 
+  /**
+   * 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.
+   */
+  public forBrowser(browser: KernelBrowserInput): KernelBrowserSession {
+    return new KernelBrowserSession(this, browser);
+  }
+
   static Kernel = this;
   static DEFAULT_TIMEOUT = 60000; // 1 minute
 

src/index.ts

@@ -5,6 +5,12 @@ export { Kernel as default } from './client';
 export { type Uploadable, toFile } from './core/uploads';
 export { APIPromise } from './core/api-promise';
 export { Kernel, type ClientOptions } from './client';
+export {
+  KernelBrowserSession,
+  type BrowserFetchInit,
+  type KernelBrowserInput,
+} from './lib/kernel-browser-session';
+export { type KernelBrowserLike, type ResolvedBrowserTransport } from './lib/browser-transport';
 export { PagePromise } from './core/pagination';
 export {
   KernelError,

src/lib/browser-transport.ts

@@ -0,0 +1,62 @@
+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}.
+ */
+export type ResolvedBrowserTransport = {
+  sessionId: string;
+  defaultBaseURL?: string | undefined;
+  jwt?: string | undefined;
+};
+
+export type KernelBrowserLike = {
+  session_id: string;
+  base_url?: string | null | undefined;
+  cdp_ws_url?: string | null | undefined;
+  /** When set, overrides jwt parsed from cdp_ws_url */
+  jwt?: string | null | undefined;
+};
+
+export function parseJwtFromCdpWsUrl(cdpWsUrl: string | null | undefined): string | undefined {
+  if (!cdpWsUrl) {
+    return undefined;
+  }
+  try {
+    const u = new URL(cdpWsUrl);
+    const jwt = u.searchParams.get('jwt');
+    return jwt ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function resolveBrowserTransport(browser: KernelBrowserLike): ResolvedBrowserTransport {
+  const sessionId = browser.session_id;
+  const rawBase = browser.base_url?.trim();
+  const defaultBaseURL = rawBase && rawBase.length > 0 ? rawBase : undefined;
+  const jwt =
+    (typeof browser.jwt === 'string' && browser.jwt.length > 0 ? browser.jwt : undefined) ??
+    parseJwtFromCdpWsUrl(browser.cdp_ws_url ?? undefined);
+  return { sessionId, defaultBaseURL, jwt };
+}
+
+export function mergeBrowserScopedRequestOptions(
+  transport: ResolvedBrowserTransport,
+  options?: RequestOptions,
+): RequestOptions | undefined {
+  if (!transport.defaultBaseURL) {
+    return options;
+  }
+  const next: RequestOptions = { ...options, defaultBaseURL: transport.defaultBaseURL };
+  if (transport.jwt) {
+    const prev =
+      options?.query && typeof options.query === 'object' && !Array.isArray(options.query) ?
+        (options.query as Record<string, unknown>)
+      : {};
+    next.query = { ...prev, jwt: transport.jwt };
+  }
+  return next;
+}