refactor: replace isolatedContext routing with pageId routing

Replace the isolatedContext-based page resolution with the more general
pageId parameter. The isolatedContext approach only worked when agents
used different browser contexts. pageId works for any multi-page
scenario, uses an already-existing concept (page IDs), and does not
depend on isolated contexts.

- Rename isolatedContextSchema to pageIdSchema (string to number)
- Replace resolvePageByContext() with resolvePageById() in McpContext
- Remove per-context page tracking (#contextSelectedPage map)
- Update all tool files to use pageId routing
- Keep isolatedContext on new_page (browser context isolation, not routing)
- Update tests to use pageId-based assertions

Author: passtas

docs/tool-reference.md

@@ -1,6 +1,6 @@
 <!-- AUTO GENERATED DO NOT EDIT - run 'npm run docs' to update-->
 
-# Chrome DevTools MCP Tool Reference (~6885 cl100k_base tokens)
+# Chrome DevTools MCP Tool Reference (~7236 cl100k_base tokens)
 
 - **[Input automation](#input-automation)** (8 tools)
   - [`click`](#click)
@@ -71,6 +71,7 @@
 - **uid** (string) **(required)**: The uid of an element on the page from the page content snapshot
 - **value** (string) **(required)**: The value to [`fill`](#fill) in
 - **includeSnapshot** (boolean) _(optional)_: Whether to include a snapshot in the response. Default is false.
+- **pageId** (number) _(optional)_: Targets a specific page by ID.
 
 ---
 
@@ -82,6 +83,7 @@
 
 - **elements** (array) **(required)**: Elements from snapshot to [`fill`](#fill) out.
 - **includeSnapshot** (boolean) _(optional)_: Whether to include a snapshot in the response. Default is false.
+- **pageId** (number) _(optional)_: Targets a specific page by ID.
 
 ---
 
@@ -115,6 +117,7 @@
 
 - **key** (string) **(required)**: A key or a combination (e.g., "Enter", "Control+A", "Control++", "Control+Shift+R"). Modifiers: Control, Shift, Alt, Meta
 - **includeSnapshot** (boolean) _(optional)_: Whether to include a snapshot in the response. Default is false.
+- **pageId** (number) _(optional)_: Targets a specific page by ID.
 
 ---
 
@@ -127,6 +130,7 @@
 - **filePath** (string) **(required)**: The local path of the file to upload
 - **uid** (string) **(required)**: The uid of the file input element or an element that will open file chooser on the page from the page content snapshot
 - **includeSnapshot** (boolean) _(optional)_: Whether to include a snapshot in the response. Default is false.
+- **pageId** (number) _(optional)_: Targets a specific page by ID.
 
 ---
 
@@ -159,6 +163,7 @@
 - **handleBeforeUnload** (enum: "accept", "decline") _(optional)_: Whether to auto accept or beforeunload dialogs triggered by this navigation. Default is accept.
 - **ignoreCache** (boolean) _(optional)_: Whether to ignore cache on reload.
 - **initScript** (string) _(optional)_: A JavaScript script to be executed on each new document before any other scripts for the next navigation.
+- **pageId** (number) _(optional)_: Targets a specific page by ID.
 - **timeout** (integer) _(optional)_: Maximum wait time in milliseconds. If set to 0, the default timeout will be used.
 - **type** (enum: "url", "back", "forward", "reload") _(optional)_: Navigate the page by URL, back or forward in history, or reload.
 - **url** (string) _(optional)_: Target URL (only type=url)
@@ -196,6 +201,7 @@
 **Parameters:**
 
 - **text** (string) **(required)**: Text to appear on the page
+- **pageId** (number) _(optional)_: Targets a specific page by ID.
 - **timeout** (integer) _(optional)_: Maximum wait time in milliseconds. If set to 0, the default timeout will be used.
 
 ---
@@ -212,6 +218,7 @@
 - **cpuThrottlingRate** (number) _(optional)_: Represents the CPU slowdown factor. Set the rate to 1 to disable throttling. If omitted, throttling remains unchanged.
 - **geolocation** (unknown) _(optional)_: Geolocation to [`emulate`](#emulate). Set to null to clear the geolocation override.
 - **networkConditions** (enum: "No emulation", "Offline", "Slow 3G", "Fast 3G", "Slow 4G", "Fast 4G") _(optional)_: Throttle network. Set to "No emulation" to disable. If omitted, conditions remain unchanged.
+- **pageId** (number) _(optional)_: Targets a specific page by ID.
 - **userAgent** (unknown) _(optional)_: User agent to [`emulate`](#emulate). Set to null to clear the user agent override.
 - **viewport** (unknown) _(optional)_: Viewport to [`emulate`](#emulate). Set to null to reset to the default viewport.
 
@@ -225,6 +232,7 @@
 
 - **height** (number) **(required)**: Page height
 - **width** (number) **(required)**: Page width
+- **pageId** (number) _(optional)_: Targets a specific page by ID.
 
 ---
 
@@ -250,6 +258,7 @@
 - **autoStop** (boolean) **(required)**: Determines if the trace recording should be automatically stopped.
 - **reload** (boolean) **(required)**: Determines if, once tracing has started, the current selected page should be automatically reloaded. Navigate the page to the right URL using the [`navigate_page`](#navigate_page) tool BEFORE starting the trace if reload or autoStop is set to true.
 - **filePath** (string) _(optional)_: The absolute file path, or a file path relative to the current working directory, to save the raw trace data. For example, trace.json.gz (compressed) or trace.json (uncompressed).
+- **pageId** (number) _(optional)_: Targets a specific page by ID.
 
 ---
 
@@ -260,6 +269,7 @@
 **Parameters:**
 
 - **filePath** (string) _(optional)_: The absolute file path, or a file path relative to the current working directory, to save the raw trace data. For example, trace.json.gz (compressed) or trace.json (uncompressed).
+- **pageId** (number) _(optional)_: Targets a specific page by ID.
 
 ---
 
@@ -320,6 +330,7 @@ so returned values have to be JSON-serializable.
 }`
 
 - **args** (array) _(optional)_: An optional list of arguments to pass to the function.
+- **pageId** (number) _(optional)_: Targets a specific page by ID.
 
 ---
 
@@ -355,6 +366,7 @@ so returned values have to be JSON-serializable.
 - **filePath** (string) _(optional)_: The absolute path, or a path relative to the current working directory, to save the screenshot to instead of attaching it to the response.
 - **format** (enum: "png", "jpeg", "webp") _(optional)_: Type of format to save the screenshot as. Default is "png"
 - **fullPage** (boolean) _(optional)_: If set to true takes a screenshot of the full page instead of the currently visible viewport. Incompatible with uid.
+- **pageId** (number) _(optional)_: Targets a specific page by ID.
 - **quality** (number) _(optional)_: Compression quality for JPEG and WebP formats (0-100). Higher values mean better quality but larger file sizes. Ignored for PNG format.
 - **uid** (string) _(optional)_: The uid of an element on the page from the page content snapshot. If omitted takes a pages screenshot.
 
@@ -369,6 +381,7 @@ in the DevTools Elements panel (if any).
 **Parameters:**
 
 - **filePath** (string) _(optional)_: The absolute path, or a path relative to the current working directory, to save the snapshot to instead of attaching it to the response.
+- **pageId** (number) _(optional)_: Targets a specific page by ID.
 - **verbose** (boolean) _(optional)_: Whether to include all possible information available in the full a11y tree. Default is false.
 
 ---

scripts/eval_scenarios/page_id_routing_test.ts

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import assert from 'node:assert';
+
+import type {TestScenario} from '../eval_gemini.ts';
+
+export const scenario: TestScenario = {
+  prompt: `Open three new pages in isolated contexts:
+- Page A at data:text/html,<h1>Page A</h1>
+- Page B at data:text/html,<h1>Page B</h1>
+- Page C at data:text/html,<h1>Page C</h1>
+Then take screenshots of all three pages in parallel.`,
+  maxTurns: 8,
+  expectations: calls => {
+    // Exactly 3 screenshot calls.
+    const screenshots = calls.filter(c => c.name === 'take_screenshot');
+    assert.strictEqual(screenshots.length, 3, 'Should take 3 screenshots');
+
+    // Each screenshot must carry a numeric pageId.
+    for (const ss of screenshots) {
+      assert.strictEqual(
+        typeof ss.args.pageId,
+        'number',
+        'Screenshot should use pageId',
+      );
+    }
+
+    // All pageIds should be distinct (one per page).
+    const pageIds = new Set(screenshots.map(s => s.args.pageId));
+    assert.strictEqual(
+      pageIds.size,
+      3,
+      'Each screenshot should target a different page',
+    );
+  },
+};

src/McpContext.ts

@@ -131,8 +131,6 @@ export class McpContext implements Context {
   #pages: Page[] = [];
   #pageToDevToolsPage = new Map<Page, Page>();
   #selectedPage?: Page;
-  // Per-context selected page tracking for parallel agent support.
-  #contextSelectedPage = new Map<string, Page>();
   #textSnapshot: TextSnapshot | null = null;
   #networkCollector: NetworkCollector;
   #consoleCollector: ConsoleCollector;
@@ -505,39 +503,11 @@ export class McpContext implements Context {
     return page;
   }
 
-  resolvePageByContext(isolatedContext?: string): Page {
-    if (isolatedContext === undefined) {
+  resolvePageById(pageId?: number): Page {
+    if (pageId === undefined) {
       return this.getSelectedPage();
     }
-
-    // Try the per-context selected page first.
-    const tracked = this.#contextSelectedPage.get(isolatedContext);
-    if (tracked && !tracked.isClosed()) {
-      return tracked;
-    }
-
-    // Fall back: find any non-closed page in the context.
-    const ctx = this.#isolatedContexts.get(isolatedContext);
-    if (!ctx) {
-      throw new Error(
-        `No isolated context named "${isolatedContext}" exists. ` +
-          `Create one first with new_page(isolatedContext: "${isolatedContext}").`,
-      );
-    }
-
-    for (const page of this.#pages) {
-      if (
-        !page.isClosed() &&
-        this.#pageToIsolatedContextName.get(page) === isolatedContext
-      ) {
-        this.#contextSelectedPage.set(isolatedContext, page);
-        return page;
-      }
-    }
-
-    throw new Error(
-      `No open page found in isolated context "${isolatedContext}".`,
-    );
+    return this.getPageById(pageId);
   }
 
   getPageById(pageId: number): Page {
@@ -574,12 +544,6 @@ export class McpContext implements Context {
     void newPage.emulateFocusedPage(true).catch(error => {
       this.logger('Error turning on focused page emulation', error);
     });
-
-    // Track per-context selected page for parallel agent routing.
-    const contextName = this.#pageToIsolatedContextName.get(newPage);
-    if (contextName) {
-      this.#contextSelectedPage.set(contextName, newPage);
-    }
   }
 
   #updateSelectedPageTimeouts() {

src/tools/ToolDefinition.ts

@@ -108,7 +108,7 @@ export type Context = Readonly<{
   recordedTraces(): TraceResult[];
   storeTraceRecording(result: TraceResult): void;
   getSelectedPage(): Page;
-  resolvePageByContext(isolatedContext?: string): Page;
+  resolvePageById(pageId?: number): Page;
   getDialog(): Dialog | undefined;
   clearDialog(): void;
   getPageById(pageId: number): Page;
@@ -182,16 +182,8 @@ export function defineTool<Schema extends zod.ZodRawShape>(
 export const CLOSE_PAGE_ERROR =
   'The last open page cannot be closed. It is fine to keep it open.';
 
-export const isolatedContextSchema = {
-  isolatedContext: zod
-    .string()
-    .optional()
-    .describe(
-      'The name of the isolated browser context to resolve the page from. ' +
-        'When provided, the tool operates on the page belonging to this context ' +
-        'instead of the globally selected page. ' +
-        'Use this to avoid race conditions when multiple agents work in parallel.',
-    ),
+export const pageIdSchema = {
+  pageId: zod.number().optional().describe('Targets a specific page by ID.'),
 };
 
 export const timeoutSchema = {

src/tools/emulation.ts

@@ -8,7 +8,7 @@
 import {zod, PredefinedNetworkConditions} from '../third_party/index.js';
 
 import {ToolCategory} from './categories.js';
-import {defineTool, isolatedContextSchema} from './ToolDefinition.js';
+import {defineTool, pageIdSchema} from './ToolDefinition.js';
 
 const throttlingOptions: [string, ...string[]] = [
   'No emulation',
@@ -24,7 +24,7 @@ export const emulate = defineTool({
     readOnlyHint: false,
   },
   schema: {
-    ...isolatedContextSchema,
+    ...pageIdSchema,
     networkConditions: zod
       .enum(throttlingOptions)
       .optional()
@@ -105,9 +105,7 @@ export const emulate = defineTool({
       ),
   },
   handler: async (request, _response, context) => {
-    const page = context.resolvePageByContext(
-      request.params.isolatedContext,
-    );
+    const page = context.resolvePageById(request.params.pageId);
     await context.emulate(request.params, page);
   },
 });