/** * BrowserManager: session-scoped lifecycle for DEBUG browser connections. * * Holds active BrowserSession instances keyed by session ID. One session per * agent run/build/chat session - the harness gets a persistent browser across * multiple MCP tool calls within the same session. * * LIFECYCLE (2026-09): the bridge now closes the debug browser it OWNS - on * `browser_close`, when the task ends, and when it goes idle. Two invariants * make that safe: * 1. OWNERSHIP. Only a Chrome this bridge launched is ever terminated. One the * human started (signed in, watching) is disconnected and left running. * 2. SEPARATION. The debug browser runs on DEBUG_CDP_PORT with its own profile; * the auto-answer browser (`browse --auto-answer`, which the human watches * and answers on-screen questions in) runs on AUTO_ANSWER_CDP_PORT with a * different profile and is not a session here at all. * * `disconnect` remains available for the CDP-only release path. */ import { BrowserSession, type BrowserSessionOptions } from './session'; export declare class BrowserManager { private sessions; /** * Get an existing session or create a new one. * If the session exists but is disconnected, reconnects it. */ getOrCreate(sessionId: string, opts?: BrowserSessionOptions): BrowserSession; /** * Get the session for an identity, reconfiguring it when it is NOT connected. * * A dead browser leaves a disconnected session behind; when it comes back the * port it used may belong to another agent and the shared debug profile may be * in use by a concurrent session. `configure` only touches launch-time * options, never a live connection. */ ensure(sessionId: string, opts: BrowserSessionOptions): BrowserSession; /** Ports owned by live sessions, excluding one id. */ usedPorts(exceptSessionId?: string): number[]; /** Profile directories owned by live sessions, excluding one id. */ usedProfileDirs(exceptSessionId?: string): string[]; /** * Get a session by ID (returns undefined if not found). */ get(sessionId: string): BrowserSession | undefined; /** * Close a session AND the debug browser it owns. * * 2026-09: `browser_close` used to report success while closing nothing (it * only dropped the CDP connection). It now actually terminates the Chrome the * bridge launched. A Chrome the human started is only disconnected. * * Returns whether a browser process was really closed (a failed close is * reported as `false` so the caller never claims a window died that is still * open). */ close(sessionId: string): Promise; /** * Close every session the bridge owns, dropping the rest. * * The auto-answer browser (a separate `browse --auto-answer` process on its own * port/profile) is NOT a session here and is never touched here. */ closeAll(): Promise; /** * Release every CDP connection WITHOUT terminating any browser. * * This is the daemon-shutdown path: a restart is not "the task ended", and the * human may be mid-session in a window they started (or in the auto-answer * browser). A bridge-launched debug browser is not lost: it is recorded in * `owned-registry.ts` and reclaimed at the next boot. */ disconnectAll(): void; /** Stamp activity on a session (drives the idle-close timer). */ touch(sessionId: string): void; /** * Close debug browsers that have been idle for longer than `graceMs`. * Returns how many were closed. Human-launched browsers are never touched. */ closeIdleOwned(graceMs: number, now?: number): Promise; /** * List active session IDs. */ list(): string[]; /** * Session summaries for `GET /internal/browser-state` (2026-10). * Multiple browsers per machine make "which Chrome is which run" a real * question for the UI and for a human watching the task manager. */ listDetails(): Array<{ sessionId: string; port: number; profileDir: string; connected: boolean; ownedByBridge: boolean; lastUsedAt: string; actor: string | null; }>; /** * Count of active (connected) sessions. */ get activeCount(): number; } /** * Get the global BrowserManager singleton. * Created lazily on first access. */ export declare function getBrowserManager(): BrowserManager;