feat: add storage-isolated browser contexts

[RobertWsp]

Summary

Adds storage-isolated browser contexts via an optional isolatedContext parameter on the new_page tool, following the simplified design proposed by @OrKoN in #926.

Pages created with the same isolatedContext name share cookies, localStorage, and storage. Pages in different isolated contexts (or the default context) are fully isolated — ideal for testing multi-user real-time features like chat, notifications, or collaborative editing.

Changes

new_page tool

• New optional isolatedContext: string parameter
• If specified, creates/reuses a named BrowserContext and opens a page in it
• If omitted, uses the default browser context (existing behavior unchanged)

McpContext

• #isolatedContexts Map: LLM-provided names → Puppeteer BrowserContext instances
• #pageToIsolatedContextName WeakMap: GC-safe page → context name reverse lookup
• Auto-discovery: externally created browser contexts get isolated-context-1, isolated-context-2, etc.
• getIsolatedContextName(page): returns the isolated context name for a page (used by response formatting)
• page.browserContext() used for context membership detection (no custom target event forwarding needed)
• No context cleanup in dispose() or closePage() — either the entire browser is closed or we disconnect without destroying state

McpResponse

• Page list includes isolatedContext=${name} labels (both text and structured JSON output)

ToolDefinition

• Context interface extended with getIsolatedContextName(page) method

What's NOT included (by design)

• No TargetEventEmitter: Puppeteer forwards target events from BrowserContext → Browser internally
• No context cleanup: Browser contexts are not closed on dispose() or page close, per maintainer guidance
• No about:blank cleanup: Default context and isolated contexts coexist side-by-side

Example

> new_page url="https://app.example.com/chat" isolatedContext="userA"
> new_page url="https://app.example.com/chat" isolatedContext="userB"
> list_pages

Page 1: [app.example.com/chat] isolatedContext=userA
Page 2: [app.example.com/chat] isolatedContext=userB [selected]

Pages in different isolated contexts have fully independent cookies, localStorage, IndexedDB, and WebSocket connections.

Tests

• 6 new tests covering isolatedContext feature in tests/tools/pages.test.ts
• All existing tests pass (333+)
• Zero type errors, lint clean

Closes #926

[OrKoN]

Thanks for the PR but I think we can implement it without new tools, see #926 (comment)

[RobertWsp]

Thanks for the feedback, @OrKoN — you're right, the simpler design is much better.

I've reworked the PR to follow your suggestion from #926 exactly:

• Removed create_session, list_sessions, close_session tools entirely (deleted SessionManager.ts and session.ts)
• Added optional browserContext: string parameter to the new_page tool
• McpContext maintains a Map<string, BrowserContext> mapping LLM-provided names → Puppeteer BrowserContexts
• Auto-naming: unknown contexts discovered via browser.browserContexts() get assigned browser-context-1, browser-context-2, etc.
• Page list snapshots include pages from all mapped browser contexts, with browserContext=${name} in each row (both text and structured JSON)
• Cleanup: closing the last page in a browser context automatically closes that context; dispose() cleans up all contexts

Additional details:

• TargetEventEmitter abstraction so PageCollector/UniverseManager work with both Browser and BrowserContext
• WeakMap<Page, string> for page → context name lookup (GC-safe)
• On first browserContext creation, leftover about:blank pages from the default context are cleaned up

All 333 existing tests pass, zero type errors. I've also updated the PR description to reflect the new design.

Ready for another look when you have time.

[OrKoN]

Thanks, I think the PR needs some polishing (left comments)

[RobertWsp]

Thanks for the thorough review @OrKoN! All 6 items addressed in the new force-pushed commit (f84a246). The diff is now just 5 files, +141/-22 lines — much cleaner.

Here's what changed:

1. browserContext → isolatedContext ✅ — Renamed everywhere (param, fields, methods, docs)

2. DevtoolsUtils.ts ✅ — Reverted, no longer touched

3. main.ts ✅ — Reverted, no longer touched

4. createPagesSnapshot() refactored ✅ — Created a private #getAllPages() helper that calls browser.pages() once and uses page.browserContext() for reverse-lookup instead of iterating the contexts Map. Both createPagesSnapshot() and detectOpenDevToolsWindows() use this helper.

5. package-lock.json ✅ — Reverted, no longer touched

6. PageCollector.ts / TargetEventEmitter ✅ — Removed entirely. PageCollector, NetworkCollector, ConsoleCollector, and UniverseManager all receive Browser directly as before — target events are already forwarded from all browser contexts.

The commit is squashed into a single clean commit on top of main. All 446 tests pass.

[OrKoN]

I think tests were lost?

[RobertWsp]

Removed all BrowserContext.close() calls — both from dispose() and from closePage() (which was closing empty contexts when their last page was closed). Isolated contexts now persist until the browser itself is closed or the client disconnects.

The previous tests were for the TargetEventEmitter abstraction which was removed, so they weren't applicable. Added 6 new tests specifically for the isolatedContext feature covering:

• Creating a page in an isolated context
• Reusing the same context for the same name
• Separate contexts for different names
• isolatedContext label in page listing output
• Backward compatibility (default context returns undefined)
• Closing an isolated page without errors

[OrKoN]

Thanks! I think this mostly looks good, I will double check on Monday and I think we would be able to merge it then. cc @natorion @matthiasrohmer

[RobertWsp]

Done. Removed the entire isFirstIsolatedContext block — default context and isolated contexts now coexist without interference.

[passtas]

Hey @RobertWsp and @OrKoN , thanks for this PR - the isolatedContext feature is exactly what we needed. I've been using it to test cache behavior across different user roles (logged-in vs guest, different account types) by running parallel agents that each get their own isolated session to crawl the site in parallel. Works great for catching stale-cache bugs where one user sees another's cached data.

Ran into a race condition with the shared selectedPage state though.

The problem: isolatedContext correctly isolates cookies/storage, but all tools that operate on a page (take_screenshot, take_snapshot, navigate_page, evaluate_script, press_key, etc.) resolve the target via the global getSelectedPage(). Since select_page and take_screenshot are two separate tool calls, another agent can call select_page in between, causing agent A to screenshot agent B's page.

Reproduced it reliably: two isolated contexts, different URLs, two agents selecting+screenshotting in parallel. The agent that selects first consistently captures the wrong page.

Suggested fix: add an optional pageId parameter to tools that depend on getSelectedPage(). Something like a resolvePage(pageId?) helper that uses getPageById(pageId) when provided, falling back to getSelectedPage() when omitted (fully backward compatible). This makes page targeting atomic within a single tool call:

// Before (race-prone, two calls):
select_page(pageId: 2)
take_screenshot()           // might capture wrong page

// After (atomic, single call):
take_screenshot(pageId: 2)  // resolves page internally

The infrastructure is already there (getPageById, #pageIdMap). The main tools that would need it: take_screenshot, take_snapshot, navigate_page, evaluate_script, click_at, press_key, upload_file, resize_page, wait_for, and the performance tracing tools.

Should I open a separate issue to track this or here would be the right place?

[OrKoN]

@passtas we specifically decided against a design where each tool needs a page id because usually multiple operations are performed on one page. Having pageId is each tool call increases the tokens consumed for each LLM iteration. Do you have evals that prove that this works better (in terms of token usage and ability of LLMs to use the tools)? cc @natorion

[passtas]

@OrKoN, that is of course fair point. I'd expect some marginal increase in token usage as the agent will have to remember and pass through the pageId within the same session and impact of additional description tokens for the correct tool use.

I guess the trick would also be to have it backward compatible by making this attribute optional, so that use will have to opt-in by putting specific prompt about context isolation etc., if he wouldn't he would still have current behaviour.

  resolvePage(pageId?: number): Page {
    if (pageId !== undefined) {
      return this.getPageById(pageId);
    }
    return this.getSelectedPage();
  }

And the description:

export const pageIdSchema = {
  pageId: zod
    .number()
    .optional()
    .describe(
      'The ID of the page to operate on. If omitted, uses the currently selected page. Use this to avoid race conditions when multiple agents work in parallel.',
    ),
};

My subjective thinking is that without ability to do meaningful work (all mentioned tools use) within browser isolated context - it doesn't make sense to release this PR, as it will lead to the unexpected behaviour.

As a user of agents and teams of agents, I'd like those subagents to be able to work accurately in within their sessions. Browser context isolation provides a bit of that capability, but doesn't enable those separate sessions to work to the 100% of the mcp capability.

I did the fix locally to see if it will work, and it does - opens separate isolated windows and does operations with it locally without loosing that pageId. Of course it requires the finesse to make sure it it works up to the standard.

Let me think on the potential eval to prove myself right or wrong about the token usage hypothesis. I'd also like to explore if the isolatedContextName may be of any help instead of explicit page selection.
Any pointers to similar scenarios how I can demonstrate it?

Thanks.

[OrKoN]

My subjective thinking is that without ability to do meaningful work (all mentioned tools use) within browser isolated context - it doesn't make sense to release this PR, as it will lead to the unexpected behaviour.

@passtas I am not sure I follow, the select_page can be used to switch to a page in the isolated context.

[OrKoN]

// Before (race-prone, two calls):
select_page(pageId: 2)
take_screenshot()           // might capture wrong page

this is not race-prone because we have an internal mutex that processes all commands one by one.

[passtas]

// Before (race-prone, two calls):
select_page(pageId: 2)
take_screenshot()           // might capture wrong page

this is not race-prone because we have an internal mutex that processes all commands one by one.

that's precisely what creates the problem. Here's the sequence:

Step	Mutex processes	#selectedPage after	Correct?
1	Agent A: select_page(2)	Page 2	Yes
2	Agent B: select_page(3)	Page 3	Yes
3	Agent A: take_screenshot()	Page 3 (captures wrong page)	No, wanted Page 2

Each call is atomic, but between Agent A's select_page and take_screenshot, Agent B's select_page can run and mutate the shared #selectedPage.

The mutex guarantees no two tool calls execute simultaneously, but it doesn't guarantee that a two-call sequence from one agent runs without another agent's calls interleaving. Agent A has no way to hold the mutex across both calls.

[OrKoN]

@passtas this is not correct usage of the tools, before any tool call is made the right page needs to be selected.

[OrKoN]

Also, multi-agent flow is not very common, each client should have its own MCP server instance in the current design. Can you describe your set up in more details? perhaps it's best to continue the discussion on the feature issue.

[passtas]

Created #1019, so let's continue there.
On the teams of agents, this is what everyone is hyping about right now https://code.claude.com/docs/en/agent-teams