fix: handle browser pool route cache updates

Warm the browser route cache from browser pool acquire responses and evict released sessions after successful pool releases.
Keep this behavior in the routing middleware so generated resource methods stay untouched.

Made-with: Cursor

Author: rgarcia

src/lib/browser-routing.ts

@@ -30,7 +30,9 @@ export class BrowserRouteCache {
 const BROWSER_ROUTING_SUBRESOURCES_ENV = 'KERNEL_BROWSER_ROUTING_SUBRESOURCES';
 const DEFAULT_BROWSER_ROUTING_SUBRESOURCES = ['curl'];
 const BROWSER_ROUTE_CACHEABLE_PATH = /^\/(?:v\d+\/)?browsers(?:\/[^/]+)?\/?$/;
+const BROWSER_POOL_ACQUIRE_PATH = /^\/(?:v\d+\/)?browser_pools\/[^/]+\/acquire\/?$/;
 const BROWSER_DELETE_BY_ID_PATH = /^\/(?:v\d+\/)?browsers\/([^/]+)\/?$/;
+const BROWSER_POOL_RELEASE_PATH = /^\/(?:v\d+\/)?browser_pools\/[^/]+\/release\/?$/;
 
 export function browserRoutingSubresourcesFromEnv(): string[] {
   const raw = readBrowserRoutingSubresourcesEnv();
@@ -70,23 +72,26 @@ export function createRoutingFetch(
     if (shouldSniff) {
       await sniffAndPopulateCache(response, cache);
     }
-    maybeEvictDeletedBrowserRoute(request, response, apiOrigin, cache);
+    await maybeEvictBrowserRoute(request, response, apiOrigin, cache);
     return response;
   };
 }
 
 function shouldSniffAndPopulateCache(request: Request, apiOrigin: string): boolean {
   const url = new URL(request.url);
-  return url.origin === apiOrigin && BROWSER_ROUTE_CACHEABLE_PATH.test(url.pathname);
+  return (
+    url.origin === apiOrigin &&
+    (BROWSER_ROUTE_CACHEABLE_PATH.test(url.pathname) || BROWSER_POOL_ACQUIRE_PATH.test(url.pathname))
+  );
 }
 
-function maybeEvictDeletedBrowserRoute(
+async function maybeEvictBrowserRoute(
   request: Request,
   response: Response,
   apiOrigin: string,
   cache: BrowserRouteCache,
-): void {
-  if (!response.ok || request.method.toUpperCase() !== 'DELETE') {
+): Promise<void> {
+  if (!response.ok) {
     return;
   }
 
@@ -95,17 +100,44 @@ function maybeEvictDeletedBrowserRoute(
     return;
   }
 
-  const match = url.pathname.match(BROWSER_DELETE_BY_ID_PATH);
+  const sessionId =
+    deletedSessionIdFromPath(request, url.pathname) ??
+    (await releasedSessionIdFromRequest(request, url.pathname));
+  if (sessionId) {
+    cache.delete(sessionId);
+  }
+}
+
+function deletedSessionIdFromPath(request: Request, pathname: string): string | undefined {
+  if (request.method.toUpperCase() !== 'DELETE') {
+    return undefined;
+  }
+
+  const match = pathname.match(BROWSER_DELETE_BY_ID_PATH);
   if (!match) {
-    return;
+    return undefined;
   }
 
   const sessionId = decodeURIComponent(match[1] ?? '');
-  if (!sessionId) {
-    return;
+  return sessionId || undefined;
+}
+
+async function releasedSessionIdFromRequest(request: Request, pathname: string): Promise<string | undefined> {
+  if (request.method.toUpperCase() !== 'POST' || !BROWSER_POOL_RELEASE_PATH.test(pathname)) {
+    return undefined;
   }
 
-  cache.delete(sessionId);
+  try {
+    const body = await request.clone().json();
+    if (!body || typeof body !== 'object') {
+      return undefined;
+    }
+
+    const sessionId = (body as Record<string, unknown>)['session_id'];
+    return typeof sessionId === 'string' && sessionId.trim() ? sessionId.trim() : undefined;
+  } catch {
+    return undefined;
+  }
 }
 
 function browserRouteFromValue(value: unknown): BrowserRoute | undefined {

tests/lib/browser-routing.test.ts

@@ -233,6 +233,41 @@ describe('browser routing', () => {
     await expect(kernel.browsers.fetch('sess-1', 'https://example.com/again')).rejects.toThrow(/route cache/);
   });
 
+  test('warms cache from browser pool acquire responses', async () => {
+    await withBrowserRoutingEnv('process', async () => {
+      const calls: string[] = [];
+      const kernel = new Kernel({
+        apiKey: 'k',
+        baseURL: 'https://api.example/',
+        fetch: async (input) => {
+          const url = normalizeURL(input);
+          calls.push(url);
+          if (url === 'https://api.example/browser_pools/pool-1/acquire') {
+            return Response.json({
+              session_id: 'sess-1',
+              base_url: 'http://browser-session.test/browser/kernel',
+              cdp_ws_url: 'wss://browser-session.test/browser/cdp?jwt=token-abc',
+            });
+          }
+          return Response.json({ exit_code: 0, stdout_b64: '', stderr_b64: '' });
+        },
+      });
+
+      await kernel.browserPools.acquire('pool-1', {});
+      await kernel.browsers.process.exec('sess-1', { command: 'echo' });
+
+      expect(kernel.browserRouteCache.get('sess-1')).toMatchObject({
+        sessionId: 'sess-1',
+        baseURL: 'http://browser-session.test/browser/kernel',
+        jwt: 'token-abc',
+      });
+      expect(calls).toEqual([
+        'https://api.example/browser_pools/pool-1/acquire',
+        'http://browser-session.test/browser/kernel/process/exec?jwt=token-abc',
+      ]);
+    });
+  });
+
   test('evicts cached route after successful browser delete by id', async () => {
     const calls: string[] = [];
     const kernel = new Kernel({
@@ -257,6 +292,30 @@ describe('browser routing', () => {
     expect(kernel.browserRouteCache.get('sess-1')).toBeUndefined();
   });
 
+  test('evicts cached route after successful browser pool release', async () => {
+    const calls: string[] = [];
+    const kernel = new Kernel({
+      apiKey: 'k',
+      baseURL: 'https://api.example/',
+      fetch: async (input) => {
+        const url = normalizeURL(input);
+        calls.push(url);
+        return new Response(null, { status: 204 });
+      },
+    });
+
+    kernel.browserRouteCache.set({
+      sessionId: 'sess-1',
+      baseURL: 'http://browser-session.test/browser/kernel',
+      jwt: 'token-abc',
+    });
+
+    await kernel.browserPools.release('pool-1', { session_id: 'sess-1' });
+
+    expect(calls).toEqual(['https://api.example/browser_pools/pool-1/release']);
+    expect(kernel.browserRouteCache.get('sess-1')).toBeUndefined();
+  });
+
   test('keeps cached route when browser delete by id fails', async () => {
     const kernel = new Kernel({
       apiKey: 'k',
@@ -279,6 +338,28 @@ describe('browser routing', () => {
     });
   });
 
+  test('keeps cached route when browser pool release fails', async () => {
+    const kernel = new Kernel({
+      apiKey: 'k',
+      baseURL: 'https://api.example/',
+      maxRetries: 0,
+      fetch: async () => new Response('boom', { status: 500, headers: { 'content-type': 'text/plain' } }),
+    });
+
+    kernel.browserRouteCache.set({
+      sessionId: 'sess-1',
+      baseURL: 'http://browser-session.test/browser/kernel',
+      jwt: 'token-abc',
+    });
+
+    await expect(kernel.browserPools.release('pool-1', { session_id: 'sess-1' })).rejects.toThrow();
+    expect(kernel.browserRouteCache.get('sess-1')).toMatchObject({
+      sessionId: 'sess-1',
+      baseURL: 'http://browser-session.test/browser/kernel',
+      jwt: 'token-abc',
+    });
+  });
+
   test('browser.fetch rejects methods outside the SDK HTTPMethod union', async () => {
     const kernel = new Kernel({
       apiKey: 'k',