feat: add SessionManager and session lifecycle tools

SessionManager creates isolated BrowserContext-based sessions within a
single Chrome instance. Each session has its own McpContext and Mutex,
providing full cookie/storage/network isolation.

- Add SessionManager with createSession, getSession, listSessions,
  closeSession, closeAllSessions
- Add create_session, list_sessions, close_session tool definitions
- Register session tools in the tools array

Author: RobertWsp

src/SessionManager.ts

@@ -0,0 +1,166 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+  BrowserContext,
+  Browser,
+  Debugger,
+  Viewport,
+} from './third_party/index.js';
+import {McpContext} from './McpContext.js';
+import type {McpContextOptions} from './McpContext.js';
+import {Mutex} from './Mutex.js';
+
+export interface SessionInfo {
+  sessionId: string;
+  label?: string;
+  url?: string;
+  createdAt: number;
+}
+
+export interface Session {
+  sessionId: string;
+  label?: string;
+  url?: string;
+  createdAt: number;
+  context: McpContext;
+  mutex: Mutex;
+  browserContext: BrowserContext;
+}
+
+export interface CreateSessionOptions {
+  label?: string;
+  url?: string;
+  viewport?: Viewport;
+}
+
+export class SessionManager {
+  #sessions = new Map<string, Session>();
+  #getBrowser: () => Promise<Browser>;
+  #logger: Debugger;
+  #contextOptions: McpContextOptions;
+  #nextSessionId = 1;
+
+  constructor(
+    getBrowser: () => Promise<Browser>,
+    logger: Debugger,
+    contextOptions: McpContextOptions,
+  ) {
+    this.#getBrowser = getBrowser;
+    this.#logger = logger;
+    this.#contextOptions = contextOptions;
+  }
+
+  async createSession(
+    options: CreateSessionOptions = {},
+  ): Promise<SessionInfo> {
+    const browser = await this.#getBrowser();
+    if (!browser.connected) {
+      throw new Error('Browser is not connected');
+    }
+
+    const sessionId = `session_${this.#nextSessionId++}`;
+    const browserContext = await browser.createBrowserContext();
+
+    this.#logger(`SessionManager: created BrowserContext for ${sessionId}`);
+
+    const contextOptions: McpContextOptions = {
+      ...this.#contextOptions,
+      browserContext,
+    };
+
+    const context = await McpContext.from(
+      browser,
+      this.#logger,
+      contextOptions,
+    );
+
+    if (options.url) {
+      const page = context.getSelectedPage();
+      await page.goto(options.url, {waitUntil: 'load'});
+    }
+
+    if (options.viewport) {
+      const page = context.getSelectedPage();
+      await page.setViewport(options.viewport);
+    }
+
+    const session: Session = {
+      sessionId,
+      label: options.label,
+      url: options.url,
+      createdAt: Date.now(),
+      context,
+      mutex: new Mutex(),
+      browserContext,
+    };
+
+    this.#sessions.set(sessionId, session);
+
+    this.#logger(
+      `SessionManager: session ${sessionId} ready (label: ${options.label ?? 'none'})`,
+    );
+
+    return {
+      sessionId,
+      label: options.label,
+      url: options.url,
+      createdAt: session.createdAt,
+    };
+  }
+
+  getSession(sessionId: string): Session {
+    const session = this.#sessions.get(sessionId);
+    if (!session) {
+      throw new Error(
+        `Session "${sessionId}" not found. Use create_session to create one.`,
+      );
+    }
+    if (session.browserContext.closed) {
+      this.#sessions.delete(sessionId);
+      throw new Error(
+        `Session "${sessionId}" was closed externally. Create a new session.`,
+      );
+    }
+    return session;
+  }
+
+  listSessions(): SessionInfo[] {
+    const result: SessionInfo[] = [];
+    for (const [, session] of this.#sessions) {
+      if (session.browserContext.closed) {
+        this.#sessions.delete(session.sessionId);
+        continue;
+      }
+      result.push({
+        sessionId: session.sessionId,
+        label: session.label,
+        url: session.url,
+        createdAt: session.createdAt,
+      });
+    }
+    return result;
+  }
+
+  async closeSession(sessionId: string): Promise<void> {
+    const session = this.#sessions.get(sessionId);
+    if (!session) {
+      throw new Error(`Session "${sessionId}" not found.`);
+    }
+    this.#sessions.delete(sessionId);
+    session.context.dispose();
+    if (!session.browserContext.closed) {
+      await session.browserContext.close();
+    }
+    this.#logger(`SessionManager: closed session ${sessionId}`);
+  }
+
+  async closeAllSessions(): Promise<void> {
+    for (const sessionId of [...this.#sessions.keys()]) {
+      await this.closeSession(sessionId);
+    }
+  }
+}

src/tools/session.ts

@@ -0,0 +1,73 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {zod} from '../third_party/index.js';
+
+import {ToolCategory} from './categories.js';
+import {defineTool} from './ToolDefinition.js';
+
+export const createSession = defineTool({
+  name: 'create_session',
+  description: `Create an isolated browser session using a new BrowserContext.
+Each session has its own cookies, localStorage, and network state — ideal for
+testing multi-user scenarios (e.g., chat between User A and User B).
+Returns a sessionId to use with other tools.`,
+  annotations: {
+    category: ToolCategory.SESSION,
+    readOnlyHint: false,
+  },
+  schema: {
+    label: zod
+      .string()
+      .optional()
+      .describe('A human-readable label for the session (e.g., "User A").'),
+    url: zod
+      .string()
+      .optional()
+      .describe(
+        'Navigate the initial page to this URL after creating the session.',
+      ),
+  },
+  handler: async (_request, response) => {
+    // The actual session creation is handled by main.ts which intercepts
+    // this tool and delegates to SessionManager. This handler is a placeholder
+    // that will never be called directly.
+    response.appendResponseLine('Session created.');
+  },
+});
+
+export const listSessions = defineTool({
+  name: 'list_sessions',
+  description: `List all active browser sessions. Each session is an isolated
+BrowserContext with its own cookies, storage, and network state.`,
+  annotations: {
+    category: ToolCategory.SESSION,
+    readOnlyHint: true,
+  },
+  schema: {},
+  handler: async (_request, response) => {
+    // Handled by main.ts via SessionManager.
+    response.appendResponseLine('No active sessions.');
+  },
+});
+
+export const closeSession = defineTool({
+  name: 'close_session',
+  description: `Close a browser session and its BrowserContext, freeing resources.`,
+  annotations: {
+    category: ToolCategory.SESSION,
+    readOnlyHint: false,
+  },
+  schema: {
+    sessionId: zod
+      .string()
+      .describe('The ID of the session to close (from create_session).'),
+  },
+  handler: async (_request, response) => {
+    // Handled by main.ts via SessionManager.
+    response.appendResponseLine('Session closed.');
+  },
+});

src/tools/tools.ts

@@ -13,6 +13,7 @@ import * as pagesTools from './pages.js';
 import * as performanceTools from './performance.js';
 import * as screenshotTools from './screenshot.js';
 import * as scriptTools from './script.js';
+import * as sessionTools from './session.js';
 import * as snapshotTools from './snapshot.js';
 import type {ToolDefinition} from './ToolDefinition.js';
 
@@ -26,6 +27,7 @@ const tools = [
   ...Object.values(performanceTools),
   ...Object.values(screenshotTools),
   ...Object.values(scriptTools),
+  ...Object.values(sessionTools),
   ...Object.values(snapshotTools),
 ] as ToolDefinition[];