@vibesdotdev/control 0.0.0-stage → 1.0.0-rc.3

package/dist/browser/runtime/manager.js

@@ -0,0 +1,731 @@
+/**
+ * Browser Runtime Manager
+ */
+import { resolveFileSystemAdapter, statChecked } from '@vibesdotdev/filesystem';
+import { getLogger } from '@vibesdotdev/logging';
+import { CapabilityError, settle, composeChildEnv, CaughtFailureSchema } from '@vibesdotdev/kernel';
+import { runCapture } from '@vibesdotdev/kernel/execution';
+import { resolveProfilesDir, resolveStorageDir } from "../shared/paths.js";
+import { DEFAULT_MAX_ACTIVE_SESSIONS, DEFAULT_SESSION_IDLE_TIMEOUT_MS, DEFAULT_CLEANUP_INTERVAL_MS } from "../shared/constants.js";
+import { launchBrowserContext } from "./launcher.js";
+import { assertSafeBrowserUrl, launchTrustedBrowserOrigins, normalizeTrustedBrowserOrigins } from "./safe-url.js";
+import { closeBrowserSessionLease, withBrowserSessionLease } from "./session-lease.js";
+/** Map the legacy launch-options shape onto the backend launch input. */
+function toBackendLaunchInput(runtime, opts, extra) {
+    return {
+        runtime,
+        profileDir: extra.profileDir,
+        extensions: extra.extensions,
+        storageStatePath: extra.storageStatePath,
+        headless: opts?.headless,
+        viewport: opts?.viewport,
+        recordVideo: opts?.recordVideo?.enabled
+            ? { dir: opts.recordVideo.dir, size: opts.recordVideo.size }
+            : undefined,
+        trustedOrigins: extra.trustedOrigins
+    };
+}
+/** The exact origin a session's base URL declares; none when it has no base URL. */
+function sessionBaseOrigins(baseUrl) {
+    if (!baseUrl)
+        return [];
+    if (!URL.canParse(baseUrl))
+        throw new Error(`Browser session base URL is invalid: ${baseUrl}`);
+    return [...normalizeTrustedBrowserOrigins([new URL(baseUrl).origin])];
+}
+/** A session's navigation trust: its base origin, else the runtime's declared local proxy origins. */
+function sessionTrustedOrigins(runtime, baseUrl) {
+    return launchTrustedBrowserOrigins(runtime, sessionBaseOrigins(baseUrl));
+}
+function sessionTrustedOriginList(baseUrl) {
+    const origins = sessionBaseOrigins(baseUrl);
+    return origins.length > 0 ? origins : undefined;
+}
+function cleanupErrorDetail(error) {
+    if (error instanceof AggregateError) {
+        const nested = error.errors.map((cause) => cleanupErrorDetail(CaughtFailureSchema.parse(cause))).join('; ');
+        return nested ? `${error.message}: ${nested}` : error.message;
+    }
+    if (error instanceof Error) {
+        return error.cause === undefined
+            ? error.message
+            : `${error.message}: ${cleanupErrorDetail(CaughtFailureSchema.parse(error.cause))}`;
+    }
+    return error.description;
+}
+function cleanupFailure(resource, error) {
+    const detail = cleanupErrorDetail(error);
+    return new Error(`Failed to close browser resource '${resource}': ${detail}`, { cause: error });
+}
+function throwCleanupFailures(failures, operation) {
+    if (failures.length === 0)
+        return;
+    throw new AggregateError(failures, `${operation} failed for ${failures.length} resource${failures.length === 1 ? '' : 's'}`);
+}
+export async function activatePresentationWindow(runtime) {
+    const platform = runtime.localEnvironment.getPlatform?.();
+    if (!platform) {
+        throw new CapabilityError('Browser presentation requires a declared host platform.', 'UNAVAILABLE', {
+            reason: 'host-platform-undeclared'
+        });
+    }
+    if (platform !== 'darwin')
+        return;
+    const script = [
+        'tell application "System Events"',
+        '  try',
+        '    set p to first process whose name contains "Chromium"',
+        '    set frontmost of p to true',
+        '  end try',
+        'end tell'
+    ].join('\n');
+    const result = await runCapture(runtime, 'osascript', ['-e', script], {
+        envMode: 'replace',
+        env: composeChildEnv(runtime, {}),
+        signal: runtime.lifecycle.signal
+    });
+    if (result.exitCode !== 0) {
+        throw new CapabilityError('Browser presentation activation failed.', 'UNAVAILABLE', {
+            reason: 'presentation-activation-failed',
+            details: { exitCode: result.exitCode }
+        });
+    }
+}
+export class BrowserRuntimeManager {
+    runtime;
+    workspacePath;
+    backend;
+    maxActive;
+    presentationLauncher;
+    presentationActivator;
+    sessions = new Map();
+    sessionAliases = new Map();
+    ephemeralSessions = new Set();
+    sessionActivity = new Map();
+    tabs = new Map();
+    closedTabs = new Set();
+    closedContexts = new Set();
+    stopCleanupTimer = null;
+    closeAllPromise = null;
+    instanceId = crypto.randomUUID();
+    idleTimeout = DEFAULT_SESSION_IDLE_TIMEOUT_MS;
+    presentationBrowser = null;
+    // Storage descriptors
+    sessionsStorage;
+    tabsStorage;
+    profilesStorage;
+    storageInitialized = false;
+    constructor(runtime, workspacePath, 
+    /** Runtime-selected browser provider. Construction never invents a fallback. */
+    backend, maxActive = DEFAULT_MAX_ACTIVE_SESSIONS, presentationLauncher = launchBrowserContext, presentationActivator = () => activatePresentationWindow(runtime)) {
+        this.runtime = runtime;
+        this.workspacePath = workspacePath;
+        this.backend = backend;
+        this.maxActive = maxActive;
+        this.presentationLauncher = presentationLauncher;
+        this.presentationActivator = presentationActivator;
+        this.startCleanupInterval();
+    }
+    getBackendId() {
+        return this.backend.id;
+    }
+    async resolveStorageRecord(id) {
+        return this.runtime
+            .query('storage/record')
+            .withId(id)
+            .enabled()
+            .resolve();
+    }
+    async ensureStorage() {
+        if (this.storageInitialized)
+            return;
+        this.sessionsStorage = await this.resolveStorageRecord('browser.sessions');
+        this.tabsStorage = await this.resolveStorageRecord('browser.tabs');
+        this.profilesStorage = await this.resolveStorageRecord('browser.profiles');
+        this.storageInitialized = true;
+    }
+    setMaxActiveSessions(maxActive) {
+        this.maxActive = maxActive;
+    }
+    setIdleTimeout(timeoutMs) {
+        this.idleTimeout = timeoutMs;
+    }
+    /** Start periodic cleanup of idle sessions */
+    startCleanupInterval() {
+        if (this.stopCleanupTimer)
+            return;
+        // A finite host (the CLI) starts no autonomous background work; its sessions are
+        // closed when the runtime host disposes (BrowserRuntimeManagerHost.dispose).
+        if (this.runtime.scope.lifecycle === 'finite')
+            return;
+        const logger = getLogger('control:browser-manager', this.runtime);
+        this.stopCleanupTimer = this.runtime.lifecycle.interval(async () => {
+            const cleaned = await settle(async () => {
+                await this.heartbeatSessions();
+                await this.cleanupIdleSessions();
+            });
+            if (!cleaned.ok)
+                logger.warn('browser session cleanup tick failed', { error: cleaned.cause });
+        }, DEFAULT_CLEANUP_INTERVAL_MS);
+    }
+    async heartbeatSessions() {
+        if (this.sessions.size === 0)
+            return;
+        await this.ensureStorage();
+        await Promise.all([...this.sessions.values()].map(async (runtimeSession) => this.sessionsStorage.update(runtimeSession.session.id, {
+            metadata: await withBrowserSessionLease(this.runtime, runtimeSession.session.metadata, {
+                instanceId: this.instanceId,
+                persistence: this.ephemeralSessions.has(runtimeSession.session.id)
+                    ? 'ephemeral'
+                    : 'persistent'
+            })
+        })));
+    }
+    /** Stop the cleanup interval */
+    stopCleanupInterval() {
+        this.stopCleanupTimer?.();
+        this.stopCleanupTimer = null;
+    }
+    /** Update activity timestamp for a session */
+    touchSession(sessionId) {
+        this.sessionActivity.set(sessionId, Date.now());
+    }
+    /** Get oldest idle session ID */
+    getOldestIdleSession() {
+        let oldest = null;
+        for (const [id, time] of this.sessionActivity.entries()) {
+            if (!oldest || time < oldest.time) {
+                oldest = { id, time };
+            }
+        }
+        return oldest?.id ?? null;
+    }
+    /** Close sessions that have been idle too long */
+    async cleanupIdleSessions() {
+        const now = Date.now();
+        const toClose = [];
+        for (const [id, lastActivity] of this.sessionActivity.entries()) {
+            if (now - lastActivity > this.idleTimeout) {
+                toClose.push(id);
+            }
+        }
+        const results = await Promise.allSettled(toClose.map((id) => this.closeSession(id)));
+        const failures = [];
+        for (const [index, result] of results.entries()) {
+            if (result.status === 'rejected')
+                failures.push(cleanupFailure(`idle-session:${toClose[index]}`, CaughtFailureSchema.parse(result.reason)));
+        }
+        throwCleanupFailures(failures, 'Idle browser session cleanup');
+        return toClose.length;
+    }
+    /** Ensure capacity, closing oldest idle session if needed */
+    async ensureCapacity() {
+        if (this.sessions.size < this.maxActive)
+            return;
+        // Try to close oldest idle session first
+        const oldest = this.getOldestIdleSession();
+        if (oldest) {
+            await this.closeSession(oldest);
+            return;
+        }
+        throw new Error(`Maximum active browser sessions (${this.maxActive}) exceeded`);
+    }
+    async getOrCreateSession(sessionOptions, launchOptions) {
+        // Validate host-declared trust before creating records, profiles, or browsers.
+        sessionBaseOrigins(sessionOptions?.baseUrl);
+        await this.ensureStorage();
+        const mode = sessionOptions?.mode ?? 'ephemeral';
+        const shouldPersist = sessionOptions?.persist === true || mode !== 'ephemeral';
+        if (shouldPersist && !this.backend.capabilities.storageStateFile) {
+            throw new CapabilityError(`Browser backend '${this.backend.id}' does not support persistent session storage`, 'UNAVAILABLE', { reason: 'browser-backend-capability-unsupported', details: { backendId: this.backend.id, feature: 'storage-state' } });
+        }
+        if (sessionOptions?.profile && !this.backend.capabilities.profiles) {
+            throw new CapabilityError(`Browser backend '${this.backend.id}' does not support profiles`, 'UNAVAILABLE', { reason: 'browser-backend-capability-unsupported', details: { backendId: this.backend.id } });
+        }
+        if (launchOptions?.recordVideo?.enabled && !this.backend.capabilities.recording) {
+            throw new CapabilityError(`Browser backend '${this.backend.id}' does not support video recording`, 'UNAVAILABLE', { reason: 'browser-backend-capability-unsupported', details: { backendId: this.backend.id } });
+        }
+        const requestedIdOrName = sessionOptions?.id ?? sessionOptions?.name ?? '';
+        if (requestedIdOrName) {
+            const existing = this.sessions.get(requestedIdOrName);
+            if (existing)
+                return existing;
+            const aliasId = this.sessionAliases.get(requestedIdOrName);
+            const aliased = aliasId ? this.sessions.get(aliasId) : undefined;
+            if (aliased)
+                return aliased;
+        }
+        let sessionRecord = null;
+        if (requestedIdOrName && shouldPersist) {
+            sessionRecord = await this.sessionsStorage.get(requestedIdOrName);
+            // Fall back to name-based lookup when requestedIdOrName is not a UUID
+            if (!sessionRecord) {
+                const byName = await this.sessionsStorage.list({
+                    where: { name: requestedIdOrName },
+                    limit: 1
+                });
+                sessionRecord = byName.items[0] ?? null;
+            }
+        }
+        if (!sessionRecord && mode === 'load' && shouldPersist) {
+            throw new Error(`Browser session not found: ${requestedIdOrName}`);
+        }
+        if (!sessionRecord) {
+            await this.ensureCapacity();
+            const sessionId = sessionOptions?.id ?? crypto.randomUUID();
+            const name = sessionOptions?.name ?? `browser-session-${sessionId.slice(0, 8)}`;
+            const storageDir = resolveStorageDir(this.workspacePath);
+            const storageStatePath = shouldPersist ? `${storageDir}/${sessionId}.json` : undefined;
+            let profileId;
+            let profileDir;
+            if (sessionOptions?.profile?.name || sessionOptions?.profile?.id) {
+                const profileKey = sessionOptions.profile.id ?? sessionOptions.profile.name ?? '';
+                const profileMode = sessionOptions.profile.mode ?? 'upsert';
+                const existingProfile = profileKey ? await this.profilesStorage.get(profileKey) : null;
+                if (!existingProfile && profileMode === 'load') {
+                    throw new Error(`Browser profile not found: ${profileKey}`);
+                }
+                if (existingProfile) {
+                    profileId = existingProfile.id;
+                    profileDir = existingProfile.dirPath;
+                    await this.profilesStorage.update(existingProfile.id, {
+                        lastUsedAt: new Date().toISOString()
+                    });
+                }
+                else {
+                    const newProfileId = sessionOptions.profile.id ?? crypto.randomUUID();
+                    profileDir = `${resolveProfilesDir(this.workspacePath)}/${newProfileId}`;
+                    const newProfile = await this.profilesStorage.create({
+                        id: newProfileId,
+                        name: sessionOptions.profile.name ?? `profile-${newProfileId.slice(0, 8)}`,
+                        dirPath: profileDir,
+                        createdAt: new Date().toISOString(),
+                        lastUsedAt: new Date().toISOString()
+                    });
+                    profileId = newProfile.id;
+                }
+            }
+            // Always persist session to DB to satisfy FK constraint for tabs.
+            // Ephemeral sessions can be cleaned up when the session closes.
+            sessionRecord = await this.sessionsStorage.create({
+                id: sessionId,
+                name,
+                baseUrl: sessionOptions?.baseUrl,
+                profileId,
+                storageStatePath,
+                createdAt: new Date().toISOString(),
+                lastUsedAt: new Date().toISOString(),
+                status: 'active',
+                metadata: await withBrowserSessionLease(this.runtime, undefined, {
+                    instanceId: this.instanceId,
+                    persistence: shouldPersist ? 'persistent' : 'ephemeral'
+                })
+            });
+        }
+        const storageStatePath = sessionRecord.storageStatePath;
+        const hasStorageState = storageStatePath
+            ? (await statChecked(await resolveFileSystemAdapter(this.runtime), storageStatePath)).found
+            : false;
+        const profileDir = sessionRecord.profileId
+            ? (await this.profilesStorage.get(sessionRecord.profileId))?.dirPath
+            : undefined;
+        const launched = await this.backend.launch(toBackendLaunchInput(this.runtime, launchOptions, {
+            profileDir,
+            extensions: sessionOptions?.extensions,
+            storageStatePath: hasStorageState ? storageStatePath : undefined,
+            trustedOrigins: sessionTrustedOriginList(sessionRecord.baseUrl)
+        }));
+        const runtimeSession = {
+            session: sessionRecord,
+            context: launched.context,
+            persistent: launched.persistent
+        };
+        this.sessions.set(sessionRecord.id, runtimeSession);
+        this.sessionAliases.set(sessionRecord.name, sessionRecord.id);
+        this.touchSession(sessionRecord.id);
+        if (!shouldPersist) {
+            this.ephemeralSessions.add(sessionRecord.id);
+        }
+        await this.sessionsStorage.update(sessionRecord.id, {
+            lastUsedAt: new Date().toISOString(),
+            status: 'active',
+            metadata: await withBrowserSessionLease(this.runtime, sessionRecord.metadata, {
+                instanceId: this.instanceId,
+                persistence: shouldPersist ? 'persistent' : 'ephemeral'
+            })
+        });
+        return runtimeSession;
+    }
+    async getOrCreateTab(runtimeSession, url, tabOptions) {
+        await this.ensureStorage();
+        const trustedOrigins = sessionTrustedOrigins(this.runtime, runtimeSession.session.baseUrl);
+        const tabId = tabOptions?.id;
+        const forceNew = tabOptions?.newTab === true;
+        // Return specific tab by ID if it exists
+        const existingTab = tabId ? this.tabs.get(tabId) : undefined;
+        if (existingTab && !forceNew)
+            return existingTab;
+        // Reuse the most recent open tab for this session when no tab is specified
+        if (!tabId && !forceNew) {
+            const sessionTab = this.getActiveTabForSession(runtimeSession.session.id);
+            if (sessionTab) {
+                // Navigate if URL provided and different from current
+                if (url && sessionTab.page.url() !== url) {
+                    await sessionTab.page.goto(assertSafeBrowserUrl(url, trustedOrigins), {
+                        waitUntil: 'domcontentloaded',
+                        timeout: 30000
+                    });
+                }
+                this.touchSession(runtimeSession.session.id);
+                return sessionTab;
+            }
+        }
+        const page = await runtimeSession.context.newPage();
+        if (url) {
+            await page.goto(assertSafeBrowserUrl(url, trustedOrigins), {
+                waitUntil: 'domcontentloaded',
+                timeout: 30000
+            });
+        }
+        const newTabId = forceNew ? crypto.randomUUID() : (tabId ?? crypto.randomUUID());
+        const tabRecord = await this.tabsStorage.create({
+            id: newTabId,
+            sessionId: runtimeSession.session.id,
+            url: url ?? undefined,
+            createdAt: new Date().toISOString(),
+            lastActiveAt: new Date().toISOString(),
+            status: 'open'
+        });
+        const runtimeTab = { tab: tabRecord, page };
+        this.tabs.set(newTabId, runtimeTab);
+        this.touchSession(runtimeSession.session.id);
+        return runtimeTab;
+    }
+    /** Find the most recent active tab for a session */
+    getActiveTabForSession(sessionId) {
+        let latestTab;
+        let latestTime = 0;
+        for (const tab of this.tabs.values()) {
+            if (tab.tab.sessionId === sessionId && tab.tab.status === 'open') {
+                const time = new Date(tab.tab.lastActiveAt).getTime();
+                if (!latestTab || time > latestTime) {
+                    latestTab = tab;
+                    latestTime = time;
+                }
+            }
+        }
+        return latestTab;
+    }
+    async updateTabUrl(tabId, page) {
+        await this.ensureStorage();
+        await this.tabsStorage.update(tabId, {
+            url: page.url(),
+            status: 'open',
+            lastActiveAt: new Date().toISOString()
+        });
+    }
+    async closeTab(tabId) {
+        await this.ensureStorage();
+        const runtimeTab = this.tabs.get(tabId);
+        if (!runtimeTab)
+            return;
+        if (!this.closedTabs.has(tabId)) {
+            await runtimeTab.page.close();
+            this.closedTabs.add(tabId);
+        }
+        await this.tabsStorage.update(tabId, {
+            status: 'closed',
+            lastActiveAt: new Date().toISOString()
+        });
+        this.tabs.delete(tabId);
+        this.closedTabs.delete(tabId);
+    }
+    async closeSession(sessionId) {
+        const runtimeSession = this.sessions.get(sessionId);
+        if (!runtimeSession)
+            return;
+        const failures = [];
+        const wasEphemeral = this.ephemeralSessions.has(sessionId);
+        const sessionTabs = [...this.tabs.entries()].filter(([, tab]) => tab.tab.sessionId === sessionId);
+        if (!this.closedContexts.has(sessionId)) {
+            const results = await Promise.allSettled(sessionTabs.map(async ([tabId, tab]) => {
+                if (!this.closedTabs.has(tabId)) {
+                    await tab.page.close();
+                    this.closedTabs.add(tabId);
+                }
+            }));
+            for (const [index, result] of results.entries()) {
+                if (result.status === 'rejected') {
+                    failures.push(cleanupFailure(`session:${sessionId}:tab:${sessionTabs[index]?.[0]}`, CaughtFailureSchema.parse(result.reason)));
+                }
+            }
+            const closed = await settle(() => runtimeSession.context.close());
+            if (closed.ok) {
+                this.closedContexts.add(sessionId);
+                for (const [tabId] of sessionTabs)
+                    this.closedTabs.add(tabId);
+            }
+            else {
+                failures.push(cleanupFailure(`session:${sessionId}:context`, closed.cause));
+            }
+        }
+        throwCleanupFailures(failures, `Browser session '${sessionId}' cleanup`);
+        // Keep the complete session and tab custody until every storage operation
+        // succeeds. A retry skips resources already closed, then retries persistence.
+        await this.ensureStorage();
+        for (const [tabId] of sessionTabs) {
+            if (wasEphemeral)
+                await this.tabsStorage.delete(tabId);
+            else
+                await this.tabsStorage.update(tabId, { status: 'closed', lastActiveAt: new Date().toISOString() });
+        }
+        if (wasEphemeral)
+            await this.sessionsStorage.delete(sessionId);
+        else
+            await this.sessionsStorage.update(sessionId, {
+                status: 'closed',
+                metadata: closeBrowserSessionLease(runtimeSession.session.metadata, 'closed')
+            });
+        for (const [tabId] of sessionTabs) {
+            this.tabs.delete(tabId);
+            this.closedTabs.delete(tabId);
+        }
+        this.closedContexts.delete(sessionId);
+        this.ephemeralSessions.delete(sessionId);
+        this.sessions.delete(sessionId);
+        this.sessionAliases.delete(runtimeSession.session.name);
+        this.sessionActivity.delete(sessionId);
+    }
+    async persistSessionState(runtimeSession) {
+        if (!this.backend.capabilities.storageStateFile) {
+            throw new CapabilityError(`Browser backend '${this.backend.id}' does not support persistent session storage`, 'UNAVAILABLE', { reason: 'browser-backend-capability-unsupported', details: { backendId: this.backend.id, feature: 'storage-state' } });
+        }
+        await this.ensureStorage();
+        let path = runtimeSession.session.storageStatePath;
+        if (!path) {
+            // Upgrade ephemeral session to persistent: assign a storage path and stop treating
+            // it as ephemeral so closeSession won't delete the DB record on cleanup.
+            const storageDir = resolveStorageDir(this.workspacePath);
+            await (await resolveFileSystemAdapter(this.runtime)).mkdir(storageDir, { recursive: true });
+            path = `${storageDir}/${runtimeSession.session.id}.json`;
+        }
+        await runtimeSession.context.storageState({ path });
+        await this.sessionsStorage.update(runtimeSession.session.id, {
+            storageStatePath: path,
+            lastUsedAt: new Date().toISOString()
+        });
+        runtimeSession.session.storageStatePath = path;
+        this.ephemeralSessions.delete(runtimeSession.session.id);
+        this.touchSession(runtimeSession.session.id);
+    }
+    /**
+     * Get a runtime session by ID/name from memory, or re-load it from the DB
+     * (re-creating its Playwright context) if the MCP server restarted.
+     */
+    async getOrLoadSession(idOrName) {
+        // Check in-memory first
+        const inMemory = this.getRuntimeSession(idOrName);
+        if (inMemory)
+            return inMemory;
+        if (!this.backend.capabilities.storageStateFile) {
+            throw new Error(`Browser backend '${this.backend.id}' does not support loading persistent sessions`);
+        }
+        // Try to load from DB by ID or name
+        await this.ensureStorage();
+        let sessionRecord = await this.sessionsStorage.get(idOrName);
+        if (!sessionRecord) {
+            const byName = await this.sessionsStorage.list({ where: { name: idOrName }, limit: 1 });
+            sessionRecord = byName.items[0] ?? null;
+        }
+        if (!sessionRecord)
+            return null;
+        // Re-create the Playwright context from stored state
+        const storageStatePath = sessionRecord.storageStatePath;
+        const hasStorageState = storageStatePath
+            ? (await statChecked(await resolveFileSystemAdapter(this.runtime), storageStatePath)).found
+            : false;
+        const launched = await this.backend.launch(toBackendLaunchInput(this.runtime, { headless: true }, {
+            storageStatePath: hasStorageState ? storageStatePath : undefined,
+            trustedOrigins: sessionTrustedOriginList(sessionRecord.baseUrl)
+        }));
+        const runtimeSession = {
+            session: sessionRecord,
+            context: launched.context,
+            persistent: launched.persistent
+        };
+        this.sessions.set(sessionRecord.id, runtimeSession);
+        this.sessionAliases.set(sessionRecord.name, sessionRecord.id);
+        this.touchSession(sessionRecord.id);
+        await this.sessionsStorage.update(sessionRecord.id, { lastUsedAt: new Date().toISOString() });
+        return runtimeSession;
+    }
+    /**
+     * Present a session in a headed browser window and raise it to the foreground.
+     *
+     * Persists the session's cookies/storage state and opens a new headed browser
+     * pre-loaded with that state. On macOS, activates the window via System Events.
+     * Call dismissPresentation() to close the presentation browser.
+     */
+    async presentSession(runtimeSessionInput, url) {
+        if (!this.backend.capabilities.present) {
+            throw new CapabilityError(`Browser backend '${this.backend.id}' does not support headed presentation`, 'UNAVAILABLE', { reason: 'browser-backend-capability-unsupported', details: { backendId: this.backend.id } });
+        }
+        const sessionId = runtimeSessionInput.session.id;
+        const presentedPages = this.presentationBrowser?.sessionId === sessionId
+            ? this.presentationBrowser.context.pages()
+            : [];
+        const presentedUrl = presentedPages[presentedPages.length - 1]?.url();
+        const activeTabUrl = this.getActiveTabForSession(sessionId)?.page.url();
+        const current = this.sessions.get(sessionId);
+        const contextPages = current?.context === runtimeSessionInput.context
+            ? await current.context.pages()
+            : [];
+        const contextUrl = contextPages[contextPages.length - 1]?.url();
+        const targetUrl = url ??
+            [presentedUrl, activeTabUrl, contextUrl, runtimeSessionInput.session.baseUrl].find((candidate) => candidate && candidate !== 'about:blank');
+        const safeTargetUrl = targetUrl
+            ? assertSafeBrowserUrl(targetUrl, sessionTrustedOrigins(this.runtime, runtimeSessionInput.session.baseUrl))
+            : undefined;
+        // Close any existing presentation first (saves state before closing)
+        await this.dismissPresentation();
+        // Dismissal intentionally evicts the old headless context after copying the
+        // headed browser's auth state. Always re-resolve so repeated presentation
+        // never persists or navigates a context that dismissal just closed.
+        const runtimeSession = await this.getOrLoadSession(sessionId);
+        if (!runtimeSession) {
+            throw new Error(`Browser session not found: ${sessionId}`);
+        }
+        // Persist state so the presentation browser loads the same cookies/storage
+        await this.persistSessionState(runtimeSession);
+        const storageStatePath = runtimeSession.session.storageStatePath;
+        // Launch a headed browser with the saved state
+        const presRuntime = await this.presentationLauncher(this.runtime, {
+            options: { headless: false },
+            storageStatePath: storageStatePath ?? undefined
+        });
+        this.presentationBrowser = {
+            context: presRuntime.context,
+            browser: presRuntime.browser,
+            sessionId: runtimeSession.session.id,
+            storageStatePath
+        };
+        // Navigate to the target URL
+        const page = await presRuntime.context.newPage();
+        if (safeTargetUrl) {
+            await page.goto(safeTargetUrl, {
+                waitUntil: 'domcontentloaded',
+                timeout: 30000
+            });
+        }
+        // Bring to front within Playwright's context
+        await page.bringToFront();
+        // Retain custody before activation so a refused activation can still be disposed.
+        await this.presentationActivator();
+        return { url: page.url() };
+    }
+    /**
+     * Dismiss the current presentation browser (if any).
+     * Saves the presentation browser's auth state back to the headless session before closing,
+     * so that any credentials entered in the headed browser are available to subsequent tool calls.
+     */
+    async dismissPresentation(evictSession = true) {
+        if (!this.presentationBrowser)
+            return;
+        const presentation = this.presentationBrowser;
+        const { context, browser, sessionId } = presentation;
+        const failures = [];
+        // Auth state must reach storage before its only context can be discarded.
+        const runtimeSession = sessionId ? this.sessions.get(sessionId) : undefined;
+        const path = presentation.storageStatePath ?? runtimeSession?.session.storageStatePath;
+        if (path && !presentation.contextClosed)
+            await context.storageState({ path });
+        if (!presentation.contextClosed) {
+            const closed = await settle(() => context.close());
+            if (closed.ok)
+                presentation.contextClosed = true;
+            else
+                failures.push(cleanupFailure(`presentation:${sessionId ?? 'unbound'}:context`, closed.cause));
+        }
+        if (browser && !presentation.browserClosed) {
+            const closed = await settle(() => browser.close());
+            if (closed.ok)
+                presentation.browserClosed = true;
+            else
+                failures.push(cleanupFailure(`presentation:${sessionId ?? 'unbound'}:browser`, closed.cause));
+        }
+        throwCleanupFailures(failures, 'Browser presentation cleanup');
+        // Evict stale headless custody only after both presentation resources close.
+        if (runtimeSession && sessionId && evictSession) {
+            await runtimeSession.context.close();
+            this.sessions.delete(sessionId);
+            this.sessionAliases.delete(runtimeSession.session.name);
+            for (const [tabId, tab] of this.tabs) {
+                if (tab.tab.sessionId === sessionId) {
+                    this.tabs.delete(tabId);
+                    this.closedTabs.delete(tabId);
+                }
+            }
+            this.sessionActivity.delete(sessionId);
+        }
+        this.presentationBrowser = null;
+    }
+    /** Close all active sessions under an explicit runtime/host lifecycle owner. */
+    closeAllSessions() {
+        if (this.closeAllPromise)
+            return this.closeAllPromise;
+        this.stopCleanupInterval();
+        const closeOperation = (async () => {
+            const failures = [];
+            const dismissed = await settle(() => this.dismissPresentation(false));
+            if (!dismissed.ok)
+                failures.push(cleanupFailure('presentation', dismissed.cause));
+            const sessionIds = [...this.sessions.keys()];
+            const results = await Promise.allSettled(sessionIds.map((id) => this.closeSession(id)));
+            for (let index = 0; index < results.length; index++) {
+                const result = results[index];
+                if (result?.status !== 'rejected')
+                    continue;
+                const id = sessionIds[index] ?? `session-${index + 1}`;
+                failures.push(cleanupFailure(`session:${id}`, CaughtFailureSchema.parse(result.reason)));
+            }
+            throwCleanupFailures(failures, 'Browser manager cleanup');
+        })();
+        this.closeAllPromise = closeOperation.finally(() => {
+            this.closeAllPromise = null;
+        });
+        return this.closeAllPromise;
+    }
+    /** Get active session count */
+    getActiveSessionCount() {
+        return this.sessions.size;
+    }
+    /** Get session IDs with their last activity time */
+    getSessionActivity() {
+        return new Map(this.sessionActivity);
+    }
+    /**
+     * Get an active runtime session by ID or name.
+     * If idOrName is omitted, returns the most recently active session.
+     */
+    getRuntimeSession(idOrName) {
+        if (!idOrName) {
+            // Most recently active session
+            let latestId = null;
+            let latestTime = 0;
+            for (const [id, time] of this.sessionActivity.entries()) {
+                if (time > latestTime) {
+                    latestTime = time;
+                    latestId = id;
+                }
+            }
+            return latestId ? this.sessions.get(latestId) : undefined;
+        }
+        if (this.sessions.has(idOrName))
+            return this.sessions.get(idOrName);
+        const aliasId = this.sessionAliases.get(idOrName);
+        if (aliasId)
+            return this.sessions.get(aliasId);
+        return undefined;
+    }
+}
+//# sourceMappingURL=manager.js.map