feat: add isolatedContext routing for parallel agent page resolution

Add optional `isolatedContext` parameter to all page-dependent tools so
parallel agents can resolve pages by context name instead of relying on
the global selected-page pointer.

When an agent creates a page with `new_page(isolatedContext: "my-agent")`,
all subsequent tool calls can pass `isolatedContext: "my-agent"` to
operate on the correct page without race conditions from other agents
calling `select_page` concurrently.

McpContext tracks per-context selected pages and resolvePageByContext()
looks up the right page by context name.  When the parameter is omitted,
tools fall back to getSelectedPage() (fully backward compatible).

Updated tools: take_screenshot, take_snapshot, wait_for, navigate_page,
resize_page, emulate, click_at, fill, fill_form, upload_file, press_key,
evaluate_script, performance_start_trace, performance_stop_trace,
screencast_start.

Author: passtas

src/McpContext.ts

@@ -131,6 +131,8 @@ 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;
@@ -499,6 +501,41 @@ export class McpContext implements Context {
     return page;
   }
 
+  resolvePageByContext(isolatedContext?: string): Page {
+    if (isolatedContext === 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}".`,
+    );
+  }
+
   getPageById(pageId: number): Page {
     const page = this.#pages.find(p => this.#pageIdMap.get(p) === pageId);
     if (!page) {
@@ -533,6 +570,12 @@ 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() {
@@ -728,8 +771,9 @@ export class McpContext implements Context {
   async createTextSnapshot(
     verbose = false,
     devtoolsData: DevToolsData | undefined = undefined,
+    targetPage?: Page,
   ): Promise<void> {
-    const page = this.getSelectedPage();
+    const page = targetPage ?? this.getSelectedPage();
     const rootNode = await page.accessibility.snapshot({
       includeIframes: true,
       interestingOnly: !verbose,
@@ -880,8 +924,12 @@ export class McpContext implements Context {
     return this.#networkCollector.getIdForResource(request);
   }
 
-  waitForTextOnPage(text: string, timeout?: number): Promise<Element> {
-    const page = this.getSelectedPage();
+  waitForTextOnPage(
+    text: string,
+    timeout?: number,
+    targetPage?: Page,
+  ): Promise<Element> {
+    const page = targetPage ?? this.getSelectedPage();
     const frames = page.frames();
 
     let locator = this.#locatorClass.race(

src/McpResponse.ts

@@ -238,6 +238,7 @@ export class McpResponse implements Response {
       await context.createTextSnapshot(
         this.#snapshotParams.verbose,
         this.#devToolsData,
+        this.#snapshotParams.page,
       );
       const textSnapshot = context.getTextSnapshot();
       if (textSnapshot) {

src/tools/ToolDefinition.ts

@@ -53,6 +53,7 @@ export interface ImageContentData {
 export interface SnapshotParams {
   verbose?: boolean;
   filePath?: string;
+  page?: Page;
 }
 
 export interface DevToolsData {
@@ -107,6 +108,7 @@ export type Context = Readonly<{
   recordedTraces(): TraceResult[];
   storeTraceRecording(result: TraceResult): void;
   getSelectedPage(): Page;
+  resolvePageByContext(isolatedContext?: string): Page;
   getDialog(): Dialog | undefined;
   clearDialog(): void;
   getPageById(pageId: number): Page;
@@ -144,7 +146,11 @@ export type Context = Readonly<{
     action: () => Promise<unknown>,
     options?: {timeout?: number},
   ): Promise<void>;
-  waitForTextOnPage(text: string, timeout?: number): Promise<Element>;
+  waitForTextOnPage(
+    text: string,
+    timeout?: number,
+    page?: Page,
+  ): Promise<Element>;
   getDevToolsData(): Promise<DevToolsData>;
   /**
    * Returns a reqid for a cdpRequestId.
@@ -173,6 +179,18 @@ 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 timeoutSchema = {
   timeout: zod
     .number()

src/tools/emulation.ts

@@ -8,7 +8,7 @@
 import {zod, PredefinedNetworkConditions} from '../third_party/index.js';
 
 import {ToolCategory} from './categories.js';
-import {defineTool} from './ToolDefinition.js';
+import {defineTool, isolatedContextSchema} from './ToolDefinition.js';
 
 const throttlingOptions: [string, ...string[]] = [
   'No emulation',
@@ -24,6 +24,7 @@ export const emulate = defineTool({
     readOnlyHint: false,
   },
   schema: {
+    ...isolatedContextSchema,
     networkConditions: zod
       .enum(throttlingOptions)
       .optional()

src/tools/input.ts

@@ -7,11 +7,11 @@
 import {logger} from '../logger.js';
 import type {McpContext, TextSnapshotNode} from '../McpContext.js';
 import {zod} from '../third_party/index.js';
-import type {ElementHandle} from '../third_party/index.js';
+import type {ElementHandle, Page} from '../third_party/index.js';
 import {parseKey} from '../utils/keyboard.js';
 
 import {ToolCategory} from './categories.js';
-import {defineTool} from './ToolDefinition.js';
+import {defineTool, isolatedContextSchema} from './ToolDefinition.js';
 
 const dblClickSchema = zod
   .boolean()
@@ -83,13 +83,16 @@ export const clickAt = defineTool({
     conditions: ['computerVision'],
   },
   schema: {
+    ...isolatedContextSchema,
     x: zod.number().describe('The x coordinate'),
     y: zod.number().describe('The y coordinate'),
     dblClick: dblClickSchema,
     includeSnapshot: includeSnapshotSchema,
   },
   handler: async (request, response, context) => {
-    const page = context.getSelectedPage();
+    const page = context.resolvePageByContext(
+      request.params.isolatedContext,
+    );
     await context.waitForEventsAfterAction(async () => {
       await page.mouse.click(request.params.x, request.params.y, {
         clickCount: request.params.dblClick ? 2 : 1,
@@ -185,6 +188,7 @@ async function fillFormElement(
   uid: string,
   value: string,
   context: McpContext,
+  page?: Page,
 ) {
   const handle = await context.getElementByUid(uid);
   try {
@@ -196,8 +200,9 @@ async function fillFormElement(
     } else {
       // Increase timeout for longer input values.
       const timeoutPerChar = 10; // ms
+      const targetPage = page ?? context.getSelectedPage();
       const fillTimeout =
-        context.getSelectedPage().getDefaultTimeout() +
+        targetPage.getDefaultTimeout() +
         value.length * timeoutPerChar;
       await handle.asLocator().setTimeout(fillTimeout).fill(value);
     }
@@ -216,6 +221,7 @@ export const fill = defineTool({
     readOnlyHint: false,
   },
   schema: {
+    ...isolatedContextSchema,
     uid: zod
       .string()
       .describe(
@@ -225,11 +231,15 @@ export const fill = defineTool({
     includeSnapshot: includeSnapshotSchema,
   },
   handler: async (request, response, context) => {
+    const page = context.resolvePageByContext(
+      request.params.isolatedContext,
+    );
     await context.waitForEventsAfterAction(async () => {
       await fillFormElement(
         request.params.uid,
         request.params.value,
         context as McpContext,
+        page,
       );
     });
     response.appendResponseLine(`Successfully filled out the element`);
@@ -279,6 +289,7 @@ export const fillForm = defineTool({
     readOnlyHint: false,
   },
   schema: {
+    ...isolatedContextSchema,
     elements: zod
       .array(
         zod.object({
@@ -290,12 +301,16 @@ export const fillForm = defineTool({
     includeSnapshot: includeSnapshotSchema,
   },
   handler: async (request, response, context) => {
+    const page = context.resolvePageByContext(
+      request.params.isolatedContext,
+    );
     for (const element of request.params.elements) {
       await context.waitForEventsAfterAction(async () => {
         await fillFormElement(
           element.uid,
           element.value,
           context as McpContext,
+          page,
         );
       });
     }
@@ -314,6 +329,7 @@ export const uploadFile = defineTool({
     readOnlyHint: false,
   },
   schema: {
+    ...isolatedContextSchema,
     uid: zod
       .string()
       .describe(
@@ -335,7 +351,9 @@ export const uploadFile = defineTool({
         // a type=file element. In this case, we want to default to
         // Page.waitForFileChooser() and upload the file this way.
         try {
-          const page = context.getSelectedPage();
+          const page = context.resolvePageByContext(
+            request.params.isolatedContext,
+          );
           const [fileChooser] = await Promise.all([
             page.waitForFileChooser({timeout: 3000}),
             handle.asLocator().click(),
@@ -365,6 +383,7 @@ export const pressKey = defineTool({
     readOnlyHint: false,
   },
   schema: {
+    ...isolatedContextSchema,
     key: zod
       .string()
       .describe(
@@ -373,7 +392,9 @@ export const pressKey = defineTool({
     includeSnapshot: includeSnapshotSchema,
   },
   handler: async (request, response, context) => {
-    const page = context.getSelectedPage();
+    const page = context.resolvePageByContext(
+      request.params.isolatedContext,
+    );
     const tokens = parseKey(request.params.key);
     const [key, ...modifiers] = tokens;
 

src/tools/pages.ts

@@ -9,7 +9,12 @@ import type {Dialog} from '../third_party/index.js';
 import {zod} from '../third_party/index.js';
 
 import {ToolCategory} from './categories.js';
-import {CLOSE_PAGE_ERROR, defineTool, timeoutSchema} from './ToolDefinition.js';
+import {
+  CLOSE_PAGE_ERROR,
+  defineTool,
+  isolatedContextSchema,
+  timeoutSchema,
+} from './ToolDefinition.js';
 
 export const listPages = defineTool({
   name: 'list_pages',
@@ -130,6 +135,7 @@ export const navigatePage = defineTool({
     readOnlyHint: false,
   },
   schema: {
+    ...isolatedContextSchema,
     type: zod
       .enum(['url', 'back', 'forward', 'reload'])
       .optional()
@@ -156,7 +162,9 @@ export const navigatePage = defineTool({
     ...timeoutSchema,
   },
   handler: async (request, response, context) => {
-    const page = context.getSelectedPage();
+    const page = context.resolvePageByContext(
+      request.params.isolatedContext,
+    );
     const options = {
       timeout: request.params.timeout,
     };
@@ -279,11 +287,14 @@ export const resizePage = defineTool({
     readOnlyHint: false,
   },
   schema: {
+    ...isolatedContextSchema,
     width: zod.number().describe('Page width'),
     height: zod.number().describe('Page height'),
   },
   handler: async (request, response, context) => {
-    const page = context.getSelectedPage();
+    const page = context.resolvePageByContext(
+      request.params.isolatedContext,
+    );
 
     try {
       const browser = page.browser();

src/tools/performance.ts

@@ -17,7 +17,7 @@ import {
 
 import {ToolCategory} from './categories.js';
 import type {Context, Response} from './ToolDefinition.js';
-import {defineTool} from './ToolDefinition.js';
+import {defineTool, isolatedContextSchema} from './ToolDefinition.js';
 
 const filePathSchema = zod
   .string()
@@ -34,6 +34,7 @@ export const startTrace = defineTool({
     readOnlyHint: false,
   },
   schema: {
+    ...isolatedContextSchema,
     reload: zod
       .boolean()
       .describe(
@@ -55,7 +56,9 @@ export const startTrace = defineTool({
     }
     context.setIsRunningPerformanceTrace(true);
 
-    const page = context.getSelectedPage();
+    const page = context.resolvePageByContext(
+      request.params.isolatedContext,
+    );
     const pageUrlForTracing = page.url();
 
     if (request.params.reload) {
@@ -121,13 +124,16 @@ export const stopTrace = defineTool({
     readOnlyHint: false,
   },
   schema: {
+    ...isolatedContextSchema,
     filePath: filePathSchema,
   },
   handler: async (request, response, context) => {
     if (!context.isRunningPerformanceTrace()) {
       return;
     }
-    const page = context.getSelectedPage();
+    const page = context.resolvePageByContext(
+      request.params.isolatedContext,
+    );
     await stopTracingAndAppendOutput(
       page,
       response,