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;
@@ -315,15 +317,18 @@ export class McpContext implements Context {
     return this.#networkCollector.getById(this.getSelectedPage(), reqid);
   }
 
-  async emulate(options: {
-    networkConditions?: string | null;
-    cpuThrottlingRate?: number | null;
-    geolocation?: GeolocationOptions | null;
-    userAgent?: string | null;
-    colorScheme?: 'dark' | 'light' | 'auto' | null;
-    viewport?: Viewport | null;
-  }): Promise<void> {
-    const page = this.getSelectedPage();
+  async emulate(
+    options: {
+      networkConditions?: string | null;
+      cpuThrottlingRate?: number | null;
+      geolocation?: GeolocationOptions | null;
+      userAgent?: string | null;
+      colorScheme?: 'dark' | 'light' | 'auto' | null;
+      viewport?: Viewport | null;
+    },
+    targetPage?: Page,
+  ): Promise<void> {
+    const page = targetPage ?? this.getSelectedPage();
     const currentSettings = this.#emulationSettingsMap.get(page) ?? {};
     const newSettings: EmulationSettings = {...currentSettings};
     let timeoutsNeedUpdate = false;
@@ -500,6 +505,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) {
@@ -534,6 +574,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() {
@@ -729,8 +775,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,
@@ -881,8 +928,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

@@ -54,6 +54,7 @@ export interface ImageContentData {
 export interface SnapshotParams {
   verbose?: boolean;
   filePath?: string;
+  page?: Page;
 }
 
 export interface DevToolsData {
@@ -108,6 +109,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;
@@ -116,14 +118,23 @@ export type Context = Readonly<{
   selectPage(page: Page): void;
   getElementByUid(uid: string): Promise<ElementHandle<Element>>;
   getAXNodeByUid(uid: string): TextSnapshotNode | undefined;
-  emulate(options: {
-    networkConditions?: string | null;
-    cpuThrottlingRate?: number | null;
-    geolocation?: GeolocationOptions | null;
-    userAgent?: string | null;
-    colorScheme?: 'dark' | 'light' | 'auto' | null;
-    viewport?: Viewport | null;
-  }): Promise<void>;
+  emulate(
+    options: {
+      networkConditions?: string | null;
+      cpuThrottlingRate?: number | null;
+      geolocation?: GeolocationOptions | null;
+      userAgent?: string | null;
+      colorScheme?: 'dark' | 'light' | 'auto' | null;
+      viewport?: Viewport | null;
+    },
+    targetPage?: Page,
+  ): Promise<void>;
+  getNetworkConditions(): string | null;
+  getCpuThrottlingRate(): number;
+  getGeolocation(): GeolocationOptions | null;
+  getViewport(): Viewport | null;
+  getUserAgent(): string | null;
+  getColorScheme(): 'dark' | 'light' | null;
   saveTemporaryFile(
     data: Uint8Array<ArrayBufferLike>,
     mimeType: 'image/png' | 'image/jpeg' | 'image/webp',
@@ -136,7 +147,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.
@@ -179,6 +194,18 @@ export function defineTool<
 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()
@@ -104,6 +105,9 @@ export const emulate = defineTool({
       ),
   },
   handler: async (request, _response, context) => {
-    await context.emulate(request.params);
+    const page = context.resolvePageByContext(
+      request.params.isolatedContext,
+    );
+    await context.emulate(request.params, page);
   },
 });