feat: add multi-session support for concurrent Chrome instances#899
feat: add multi-session support for concurrent Chrome instances#899RobertWsp wants to merge 4 commits intoChromeDevTools:mainfrom
Conversation
Introduce SessionManager class that manages multiple isolated Chrome browser instances, each identified by a unique sessionId. Add three new session tools: create_session, list_sessions, and close_session. - Per-session Mutex ensures tool serialization within a session while allowing cross-session parallelism - Orphan prevention: browser is closed if McpContext creation fails - Auto-purge via browser 'disconnected' event listener - Graceful shutdown with #shuttingDown guard - SESSION category added to ToolCategory enum
Replace singleton browser/context with SessionManager. All existing browser tools now receive a mandatory sessionId parameter injected transparently via registerBrowserTool() wrapper — original tool handlers remain unmodified. - registerBrowserTool(): injects sessionId into Zod schema, resolves correct session's McpContext, acquires per-session mutex - registerSessionTool(): full implementations for create/list/close - Signal handling with process.once() and 10s shutdown timeout - Safety check rejects tools that define their own sessionId schema
17 tests covering session creation, retrieval, listing, closing, parallel session isolation, per-session mutex serialization, auto-purge on browser disconnect, and shutdown rejection.
|
Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA). View this failed invocation of the CLA check for more information. For the most up to date status, view the checks section at the bottom of the pull request. |
|
I have signed the CLA. Please re-check. |
|
Thanks for the PR but we do not plan to support multiple sessions right now. Could you please file a feature request to help us better understand scenarios you plan to use it for? |
|
Thanks for the feedback! I've filed a feature request in #926 with detailed use cases. Happy to iterate on the design based on the discussion there. |
|
Thanks for the PR! I think it already has conflicts so I will close it as stale. Once we figure out what we do on the feature request we can open a new one. |
2 participants
Summary
Add multi-session support using Puppeteer's
BrowserContextAPI, allowing multiple isolated browser profiles within a single Chrome instance. Each session gets its own cookies, localStorage, IndexedDB, WebSocket connections, and service workers — enabling parallel browser automation workflows like testing real-time collaborative features.Implements the BrowserContext approach suggested by @OrKoN in #926.
Motivation
The current architecture supports only a single browser context. This limits use cases where an LLM needs to interact with multiple independent browser sessions — for example, verifying that a WebSocket message sent by User A arrives at User B's browser in real time, or testing multi-user collaborative features during development.
Primary use case: Enabling LLMs to validate real-time features (WebSocket chat, live notifications, collaborative editing) by controlling two or more isolated browser sessions simultaneously within the same development conversation.
Changes
New files
src/SessionManager.ts— BrowserContext-based session lifecycle manager with per-sessionMcpContext+Mutex, automatic cleanup on context closesrc/tools/session.ts— Three new tools:create_session,list_sessions,close_sessionModified files
src/PageCollector.ts— AddedTargetEventEmitterinterface +asTargetEmitter()helper to unifyBrowserandBrowserContextevent handlingsrc/DevtoolsUtils.ts—UniverseManagernow acceptsTargetEventEmitterinstead ofBrowsersrc/McpContext.ts— Full BrowserContext support: optionalbrowserContextin options, BrowserContext-first page creation, scoped page snapshots, scoped collector subscriptionssrc/tools/categories.ts— AddedSESSIONcategorysrc/tools/tools.ts— Registered session toolssrc/main.ts— Session integration:SessionManagerinstantiation, session tool interception, optionalsessionIdparameter injected into all non-session tools for routing to session's context + mutextests/DevtoolsUtils.test.ts— Updated forTargetEventEmittertypetests/PageCollector.test.ts— Updated forTargetEventEmittertypeDesign decisions
browser.createBrowserContext()for near-instant session creation within a single Chrome instance, with full isolation (incognito profiles)sessionIdis omitted, all tools work against the default browser context exactly as they do today. Zero breaking changes.sessionIdis injected into each tool's Zod schema at registration time, and the correctMcpContext+Mutexis resolved before calling the unmodified handlerBrowser/BrowserContexttype unification in one place (asTargetEmitter()), keeping PageCollector and UniverseManager genericE2E validation
Tested with two simultaneous sessions performing independent DuckDuckGo searches — different queries, completely isolated results, separate cookies/state. Session creation is near-instant. Full lifecycle verified: create → navigate → interact → screenshot → list → close → verify cleanup.
Test results
All 333 existing tests pass. Zero type errors. Zero breaking changes.
Related