feat: gate pageId routing behind --experimental-page-id-routing flag

Add --experimental-page-id-routing CLI flag (default false) to control
whether pageId is exposed on page-scoped tools and used for request
routing. When disabled, tools behave as before (select_page workflow).

- Add serverArgs to eval TestScenario interface so individual evals can
  pass CLI flags to the MCP server
- Add TODO for mutable request state refactoring on McpContext
- Add TODO for getSelectedPage removal from Context interface
- Stabilize page_focus_keyboard_test eval prompt and expectations

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 (~7624 cl100k_base tokens)
+# Chrome DevTools MCP Tool Reference (~7084 cl100k_base tokens)
 
 - **[Input automation](#input-automation)** (9 tools)
   - [`click`](#click)

scripts/eval_gemini.ts

@@ -33,6 +33,8 @@ export interface TestScenario {
     path: string;
     htmlContent: string;
   };
+  /** Extra CLI flags passed to the MCP server (e.g. '--experimental-page-id-routing'). */
+  serverArgs?: string[];
 }
 
 async function loadScenario(scenarioPath: string): Promise<TestScenario> {
@@ -117,6 +119,9 @@ async function runSingleScenario(
     if (!debug) {
       args.push('--headless');
     }
+    if (scenario.serverArgs) {
+      args.push(...scenario.serverArgs);
+    }
 
     transport = new StdioClientTransport({
       command: 'node',

scripts/eval_scenarios/page_focus_keyboard_test.ts

@@ -9,11 +9,12 @@ import assert from 'node:assert';
 import type {TestScenario} from '../eval_gemini.ts';
 
 export const scenario: TestScenario = {
+  serverArgs: ['--experimental-page-id-routing'],
   prompt: `Open two pages in the same isolated context "session":
 - Page 1 at data:text/html,<textarea id="ta"></textarea>
 - Page 2 at data:text/html,<h1>Other</h1>
 
-Now press_key "a" on Page 1 without selecting it first. If you encounter any errors, recover from them.`,
+Now use the press_key tool to type "a" on Page 1 without selecting it first. You must use press_key, not fill or type_text. If you encounter any errors, recover from them.`,
   maxTurns: 10,
   expectations: calls => {
     // Should open 2 pages in the same context.
@@ -24,37 +25,35 @@ Now press_key "a" on Page 1 without selecting it first. If you encounter any err
 
     // Should attempt press_key at least once.
     const pressKeys = calls.filter(c => c.name === 'press_key');
-    assert.ok(pressKeys.length >= 1, 'Should attempt press_key');
+    assert.ok(pressKeys.length >= 1, 'Should attempt press_key at least once');
 
-    // Should call select_page to recover after the error.
     const selectPages = calls.filter(c => c.name === 'select_page');
-    assert.ok(
-      selectPages.length >= 1,
-      'Should select_page to recover from the focus error',
-    );
-
-    const firstPressKeyIndex = calls.indexOf(pressKeys[0]);
-    const firstSelectPageIndex = calls.indexOf(selectPages[0]);
-
-    if (firstPressKeyIndex < firstSelectPageIndex) {
-      // Error path: press_key was attempted first and failed.
-      // Verify recovery: must have a second press_key after select_page.
-      assert.ok(
-        pressKeys.length >= 2,
-        'Should retry press_key after error recovery',
-      );
-      const lastPressKeyIndex = calls.lastIndexOf(pressKeys.at(-1)!);
-      assert.ok(
-        firstSelectPageIndex < lastPressKeyIndex,
-        'select_page should precede the successful press_key',
-      );
-    } else {
-      // Proactive path: model selected page first.
-      // Verify select_page came before press_key.
-      assert.ok(
-        firstSelectPageIndex < firstPressKeyIndex,
-        'select_page should precede press_key',
-      );
+
+    if (selectPages.length > 0) {
+      const firstPressKeyIndex = calls.indexOf(pressKeys[0]);
+      const firstSelectPageIndex = calls.indexOf(selectPages[0]);
+
+      if (firstPressKeyIndex < firstSelectPageIndex) {
+        // Error path: press_key was attempted first and failed.
+        // Verify recovery: must have a second press_key after select_page.
+        assert.ok(
+          pressKeys.length >= 2,
+          'Should retry press_key after error recovery',
+        );
+        const lastPressKeyIndex = calls.lastIndexOf(pressKeys.at(-1)!);
+        assert.ok(
+          firstSelectPageIndex < lastPressKeyIndex,
+          'select_page should precede the successful press_key',
+        );
+      } else {
+        // Proactive path: model selected page first.
+        assert.ok(
+          firstSelectPageIndex < firstPressKeyIndex,
+          'select_page should precede press_key',
+        );
+      }
     }
+    // If no select_page was called, the model found another recovery path.
+    // This is acceptable as long as press_key was attempted.
   },
 };

scripts/eval_scenarios/page_id_routing_test.ts

@@ -9,6 +9,7 @@ import assert from 'node:assert';
 import type {TestScenario} from '../eval_gemini.ts';
 
 export const scenario: TestScenario = {
+  serverArgs: ['--experimental-page-id-routing'],
   prompt: `Open two new pages in isolated contexts:
 - Page A (isolatedContext "contextA") at data:text/html,<button>Click A</button>
 - Page B (isolatedContext "contextB") at data:text/html,<button>Click B</button>

src/McpContext.ts

@@ -205,6 +205,9 @@ export class McpContext implements Context {
     return context;
   }
 
+  // TODO: Refactor away mutable request state (e.g. per-request facade,
+  // per-request context object, or another approach). Once resolved, the
+  // global toolMutex could become per-BrowserContext for parallel execution.
   setRequestPage(page?: Page): void {
     this.#requestPage = page;
   }

src/cli.ts

@@ -147,6 +147,12 @@ export const cliOptions = {
     type: 'boolean',
     description: `If enabled, ignores errors relative to self-signed and expired certificates. Use with caution.`,
   },
+  experimentalPageIdRouting: {
+    type: 'boolean',
+    describe:
+      'Whether to expose pageId on page-scoped tools and route requests by page ID.',
+    hidden: true,
+  },
   experimentalDevtools: {
     type: 'boolean',
     describe: 'Whether to enable automation over DevTools targets',

src/server.ts

@@ -150,9 +150,10 @@ export async function createMcpServer(
     ) {
       return;
     }
-    const schema = tool.annotations.pageScoped
-      ? {...tool.schema, ...pageIdSchema}
-      : tool.schema;
+    const schema =
+      tool.annotations.pageScoped && serverArgs.experimentalPageIdRouting
+        ? {...tool.schema, ...pageIdSchema}
+        : tool.schema;
 
     server.registerTool(
       tool.name,
@@ -173,9 +174,10 @@ export async function createMcpServer(
           const response = serverArgs.slim
             ? new SlimMcpResponse(serverArgs)
             : new McpResponse(serverArgs);
-          const page = tool.annotations.pageScoped
-            ? context.resolvePageById(params.pageId as number | undefined)
-            : undefined;
+          const page =
+            tool.annotations.pageScoped && serverArgs.experimentalPageIdRouting
+              ? context.resolvePageById(params.pageId as number | undefined)
+              : undefined;
           if (page) {
             context.setRequestPage(page);
           }

src/tools/ToolDefinition.ts

@@ -116,6 +116,7 @@ export type Context = Readonly<{
   isCruxEnabled(): boolean;
   recordedTraces(): TraceResult[];
   storeTraceRecording(result: TraceResult): void;
+  // TODO: Remove once slim tools are converted to pageScoped: true.
   getSelectedPage(): Page;
   getDialog(page?: Page): Dialog | undefined;
   clearDialog(page?: Page): void;