feat: add pageId routing for parallel multi-agent workflows

[passtas]

Summary

Adds optional pageId routing to page-scoped tools, gated behind --experimental-page-id-routing. When enabled, multi-agent callers can target a specific page without relying on global selection state. Fully backward-compatible: without the flag, behavior is unchanged.

Key changes

• pageScoped annotation: tools declare pageScoped: true; the server merges pageId into their schema at registration time (when the flag is on)
• McpPage wrapper: consolidates per-page state (numeric id, isolated context name, focus tracking) into a single class
• Request-scoped page routing: resolvePageById() resolves the target page, setRequestPage() threads it through the handler so tools like getSelectedPage() see the right page
• assertPageIsFocused: keyboard/input tools validate that the target page holds browser focus, returning an actionable error ("call select_page first") instead of silently dispatching to the wrong page
• --experimental-page-id-routing CLI flag (hidden): gates schema injection and request-scoped routing so the feature can be tested before graduating
• Eval scenarios: page_id_routing_test and page_focus_keyboard_test with serverArgs support in the eval harness

Addresses #1019

[OrKoN]

I think the PR does not extend the focused page emulation and the dialog handling for all pages. Without it, tools might hang and not work as expected on background tabs.

[passtas]

@OrKoN, I prototyped fixes for both and wanted to validate the approach before going further (see 8edf6e8).

Dialog: Replaced the singleton #dialog with #pageDialogs = new Map<Page, Dialog>(). Handlers are attached per-page via a #setupPage() method called when pages are first discovered. getDialog and clearDialog take an optional page param, defaulting to selected page for backward compat.

handle_dialog now resolves page via pageIdSchema.

Focus: Added #focusedPagePerContext = new Map<BrowserContext, Page>(). The issue is that with parallel agents interleaving selectPage() calls, #selectedPage bounces between contexts so the wrong page gets defocused (or none does). Now selectPage() looks up the last focused page per-context, so it always defocuses the correct same-context page. Entries are cleaned up in closePage().

Both follow the same pattern: singleton field becomes a Map keyed by Page or BrowserContext, existing API stays backward-compatible via optional params, cleanup on page close.

Before I extend this further, wanted your take on introducing these Maps. The next candidate would be #textSnapshot which has the same singleton problem (one agent's uid references go stale when another agent snapshots a different page). That's a bigger change though, so I'd rather confirm you're good with the direction on these simpler cases first.

[OrKoN]

I will need to think about it more but I think there could be the following opportunities:

1. instead of adding pageId schema in each tool definition file, we could have an annotation saying that a tool is page-scoped and then add the schema centrally. We can also avoid looking up the right page in the tool logic by passing request.page centrally.

2. I think we might be at the point where we have outgrown McpContext. Instead we would need to introduce an McpPage wrapper over Puppeteer's page to hold page related data instead of adding maps and simplify the McpContext interface by moving some actions to McpPage and removing the need for so many maps.

3. tools that already accept a uid or any other id should not need a page id, instead we need to make sure that IDs are unique across all pages.

[OrKoN]

Another thing to keep in mind is that although performance tracing tools are scoped to a page it is not possible to start more than one tracing in the entire browser at the same time (even if pages are different).

[OrKoN]

I think there is a merge conflict caused by a8bf3e5 To solve changes from main.ts should be moved to server.ts

[passtas]

I think there is a merge conflict caused by a8bf3e5 To solve changes from main.ts should be moved to server.ts

Yeah, was just solving that :)

Just FYI: there was one flaky test failure "should should detect open DevTools pages" only on Windows with Node 20. https://github.com/ChromeDevTools/chrome-devtools-mcp/actions/runs/22402585807/job/64955339393?pr=1022

Can you please rerun tests to see if it was flakiness or I actually broke it somehow?

[passtas]

I think there is a merge conflict caused by a8bf3e5 To solve changes from main.ts should be moved to server.ts

Yeah, was just solving that :)

Just FYI: there was one flaky test failure "should should detect open DevTools pages" only on Windows with Node 20. https://github.com/ChromeDevTools/chrome-devtools-mcp/actions/runs/22402585807/job/64955339393?pr=1022

Can you please rerun tests to see if it was flakiness or I actually broke it somehow?

This time it failed on Windows Node 23 :), certainly flaky.

@OrKoN, how would you like to proceed here?

[OrKoN]

LGTM thanks!

[pirate]

related: @OrKoN @passtas you may be interested in my chromium CDP feature request to make foreground page tracking easier / avoid needing to maintain internal state in CDP clients to track it: https://issues.chromium.org/issues/497896141

Also in case it helps: At browser-use we made page IDs simply the last 4 characters of targetIds, which helped keep them stable / avoid needing in-memory mappings.