@webmcp-bridge/local-mcp 0.4.3 → 0.5.1

package/dist/bridge.js

@@ -1,45 +1,25 @@
 /**
  * This module composes runtime startup with the stdio MCP server into one lifecycle handle.
- * It depends on site-source resolution, runtime, and server modules so CLI and tests can start a complete local-mcp bridge in one call.
+ * It depends on site resolution, runtime startup, and session-control helpers so local-mcp can keep one MCP process alive across runtime, bootstrap, and attach transitions.
  */
 import { createLocalMcpStdioServer, } from "./server.js";
 import { startLocalMcpRuntime, } from "./runtime.js";
+import { assertAuthSensitiveBrowserSupport, backupAndResetProfile, describeSessionStateFromAuth, ensureManagedProfile, findBrowserProcessForProfile, focusBrowserWindow, isProcessRunning, launchBootstrapBrowser, launchManagedAttachBrowser, readSessionMetadata, resolveAuthPolicy, stopBrowserProcess, stopManagedBrowser, updateSessionMetadata, waitForProcessExit, } from "./session.js";
 import { createNativeSiteDefinition, resolveSiteSource, } from "./sites.js";
+const BOOTSTRAP_BROWSER_CLOSE_TIMEOUT_MS = 5_000;
+const BOOTSTRAP_PROFILE_RELEASE_DELAY_MS = 500;
 function readAuthState(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value)) {
-        return undefined;
+        return "unknown";
     }
     const state = value.state;
     if (state === "authenticated" || state === "auth_required" || state === "challenge_required") {
         return state;
     }
-    return undefined;
+    return "unknown";
 }
-async function startRuntime(options, siteDefinition, headless) {
-    const runtimeOptions = {
-        siteDefinition,
-        headless,
-    };
-    if (options.url !== undefined) {
-        runtimeOptions.url = options.url;
-    }
-    if (options.browser !== undefined) {
-        runtimeOptions.browser = options.browser;
-    }
-    if (options.userDataDir !== undefined) {
-        runtimeOptions.userDataDir = options.userDataDir;
-    }
-    if (options.browserChannel !== undefined) {
-        runtimeOptions.browserChannel = options.browserChannel;
-    }
-    if (options.preferNative !== undefined) {
-        runtimeOptions.preferNative = options.preferNative;
-    }
-    return await startLocalMcpRuntime(runtimeOptions);
-}
-async function resolveRuntime(options) {
+async function resolveSiteDefinitionFromBridgeOptions(options) {
     const hasAdapterSource = Boolean(options.site || options.adapterModule);
-    let siteDefinition;
     if (hasAdapterSource) {
         const sourceOptions = {};
         if (options.site !== undefined) {
@@ -51,61 +31,623 @@ async function resolveRuntime(options) {
         if (options.moduleBaseDir !== undefined) {
             sourceOptions.moduleBaseDir = options.moduleBaseDir;
         }
-        siteDefinition = await resolveSiteSource(sourceOptions);
+        return await resolveSiteSource(sourceOptions);
     }
-    else if (options.url) {
-        siteDefinition = createNativeSiteDefinition(options.url);
+    if (options.url) {
+        return createNativeSiteDefinition(options.url);
     }
-    else {
-        throw new Error("CONFIG_ERROR: provide --url or one of --site/--adapter-module");
+    throw new Error("CONFIG_ERROR: provide --url or one of --site/--adapter-module");
+}
+async function startRuntime(options) {
+    return await startLocalMcpRuntime(options);
+}
+function buildRuntimeStartOptions(baseOptions, siteDefinition, controlMode, preferredPresentationMode, browserUrl) {
+    const nextOptions = {
+        siteDefinition,
+        preferredPresentationMode,
+    };
+    if (baseOptions.url !== undefined) {
+        nextOptions.url = baseOptions.url;
     }
-    const requestedHeadless = options.headless ?? false;
-    const primary = await startRuntime(options, siteDefinition, requestedHeadless);
-    const autoLoginFallback = options.autoLoginFallback ?? true;
-    const authProbeTool = siteDefinition.manifest.authProbeTool;
-    if (!autoLoginFallback || !requestedHeadless || !authProbeTool) {
-        return primary;
+    if (baseOptions.browser !== undefined) {
+        nextOptions.browser = baseOptions.browser;
     }
-    try {
-        const authResult = await primary.gateway.callTool(authProbeTool, {});
-        const state = readAuthState(authResult);
-        if (state !== "auth_required" && state !== "challenge_required") {
-            return primary;
+    if (baseOptions.userDataDir !== undefined) {
+        nextOptions.userDataDir = baseOptions.userDataDir;
+    }
+    if (baseOptions.preferNative !== undefined) {
+        nextOptions.preferNative = baseOptions.preferNative;
+    }
+    if (baseOptions.autoLoginFallback !== undefined) {
+        nextOptions.autoLoginFallback = baseOptions.autoLoginFallback;
+    }
+    if (controlMode === "attach") {
+        if (!browserUrl) {
+            throw new Error("CONFIG_ERROR: attach mode requires a browserUrl");
         }
+        const explicitAttach = baseOptions.browserUrl !== undefined;
+        if (explicitAttach && baseOptions.browserChannel !== undefined) {
+            throw new Error("CONFIG_ERROR: --browser-url cannot be combined with --browser-channel");
+        }
+        if (explicitAttach && baseOptions.chromiumLoginWorkaround !== undefined) {
+            throw new Error("CONFIG_ERROR: --browser-url cannot be combined with --chromium-login-workaround");
+        }
+        nextOptions.browserUrl = browserUrl;
+        nextOptions.browserUrlOrigin = explicitAttach ? "external" : "managed";
+        return nextOptions;
     }
-    catch {
-        // Ignore auth probing failures and keep current runtime.
-        return primary;
+    if (baseOptions.browserChannel !== undefined) {
+        nextOptions.browserChannel = baseOptions.browserChannel;
     }
-    await primary.close();
-    return await startRuntime(options, siteDefinition, false);
+    if (baseOptions.chromiumLoginWorkaround !== undefined) {
+        nextOptions.chromiumLoginWorkaround = baseOptions.chromiumLoginWorkaround;
+    }
+    return nextOptions;
 }
 export async function startLocalMcpBridge(options) {
-    const runtime = await resolveRuntime(options);
+    const siteDefinition = await resolveSiteDefinitionFromBridgeOptions(options);
+    const authPolicy = resolveAuthPolicy(siteDefinition.manifest);
+    const targetUrl = options.url?.trim() || siteDefinition.manifest.defaultUrl?.trim() || "";
+    if (!targetUrl) {
+        throw new Error("CONFIG_ERROR: no target url provided (missing --url and manifest.defaultUrl)");
+    }
+    if (authPolicy.mode === "bootstrap_then_attach") {
+        assertAuthSensitiveBrowserSupport(options.browser, options.userDataDir);
+    }
+    let runtime;
+    let runtimeMode = "control-only";
+    let controlMode = "none";
+    let ownership = "none";
+    let authState = "unknown";
+    let sessionState = authPolicy.mode === "bootstrap_then_attach" ? "profile_missing" : "runtime_active";
+    let browserUrl = options.browserUrl;
+    let browserPid;
+    let preferredPresentationMode = options.preferredPresentationMode ?? "headed";
+    let presentationMode = preferredPresentationMode;
+    let lastBackupPath;
+    let metadata;
     let server;
     let closed = false;
-    const closeResources = async () => {
+    let lifecycleTransition = Promise.resolve();
+    const resourceUpdatedListeners = new Set();
+    let unsubscribeRuntimeResourceUpdates;
+    let ownerSessionGeneration = 0;
+    const profilePath = options.userDataDir;
+    const metadataFallback = profilePath
+        ? {
+            site: siteDefinition.id,
+            targetUrl,
+            authPolicy,
+        }
+        : undefined;
+    const refreshStatus = () => {
+        const state = {
+            site: siteDefinition.id,
+            targetUrl,
+            controlMode,
+            ...(browserUrl !== undefined ? { browserUrl } : {}),
+            mode: runtimeMode,
+            presentationMode,
+            preferredPresentationMode,
+            authPolicyMode: authPolicy.mode,
+            authState,
+            sessionState,
+            ownership,
+            ...(profilePath !== undefined ? { profilePath } : {}),
+            ...(browserPid !== undefined ? { browserPid } : {}),
+            ...(lastBackupPath !== undefined ? { lastBackupPath } : {}),
+        };
+        return state;
+    };
+    const syncFromMetadata = (nextMetadata) => {
+        metadata = nextMetadata;
+        controlMode = nextMetadata.controlMode;
+        browserUrl = nextMetadata.browserUrl;
+        browserPid = nextMetadata.browserPid;
+        authState = nextMetadata.authState;
+        sessionState = nextMetadata.sessionState;
+        ownership = nextMetadata.ownership;
+        presentationMode = nextMetadata.presentationMode;
+        preferredPresentationMode = nextMetadata.preferredPresentationMode;
+        if (nextMetadata.lastBackupPath !== undefined) {
+            lastBackupPath = nextMetadata.lastBackupPath;
+        }
+        if (runtime === undefined) {
+            runtimeMode = "control-only";
+            presentationMode = nextMetadata.controlMode === "bootstrap" ? "headed" : nextMetadata.presentationMode;
+        }
+    };
+    const writeMetadata = async (patch) => {
+        if (!profilePath || !metadataFallback) {
+            return;
+        }
+        const nextMetadata = await updateSessionMetadata(profilePath, metadataFallback, patch);
+        syncFromMetadata(nextMetadata);
+    };
+    const hasRunningBootstrapBrowser = async (sourceMetadata) => {
+        const activeMetadata = sourceMetadata ?? metadata;
+        if (!activeMetadata) {
+            return false;
+        }
+        if (authPolicy.mode !== "bootstrap_then_attach" ||
+            activeMetadata.controlMode !== "bootstrap" ||
+            activeMetadata.ownership !== "external") {
+            return false;
+        }
+        if (await isProcessRunning(activeMetadata.browserPid)) {
+            return true;
+        }
+        if (!profilePath) {
+            return false;
+        }
+        const discoveredPid = await findBrowserProcessForProfile(profilePath);
+        if (!discoveredPid) {
+            return false;
+        }
+        if (discoveredPid !== activeMetadata.browserPid) {
+            await writeMetadata({
+                browserPid: discoveredPid,
+            });
+        }
+        return true;
+    };
+    const bindRuntime = (nextRuntime, nextOwnership) => {
+        runtime = nextRuntime;
+        runtimeMode = nextRuntime.mode;
+        controlMode = nextRuntime.controlMode;
+        presentationMode = nextRuntime.presentationMode;
+        ownership = nextOwnership;
+        unsubscribeRuntimeResourceUpdates?.();
+        unsubscribeRuntimeResourceUpdates = nextRuntime.gateway.onResourceUpdated((uri) => {
+            for (const listener of resourceUpdatedListeners) {
+                listener(uri);
+            }
+        });
+        ownerSessionGeneration += 1;
+        const generation = ownerSessionGeneration;
+        void nextRuntime.ownerSessionEnded.then(() => {
+            if (closed || generation !== ownerSessionGeneration) {
+                return;
+            }
+            void closeResources().catch((error) => {
+                options.onError?.(error);
+            });
+        });
+    };
+    const clearRuntime = () => {
+        runtime = undefined;
+        runtimeMode = "control-only";
+        unsubscribeRuntimeResourceUpdates?.();
+        unsubscribeRuntimeResourceUpdates = undefined;
+    };
+    const closeRuntime = async () => {
+        if (!runtime) {
+            return;
+        }
+        const activeRuntime = runtime;
+        clearRuntime();
+        await activeRuntime.close();
+    };
+    const probeRuntimeAuthState = async (activeRuntime) => {
+        if (!authPolicy.authProbeTool) {
+            return "authenticated";
+        }
+        try {
+            const result = await activeRuntime.gateway.callTool(authPolicy.authProbeTool, {});
+            return readAuthState(result);
+        }
+        catch {
+            return "unknown";
+        }
+    };
+    const closeResourcesInternal = async () => {
         if (closed) {
             return;
         }
         closed = true;
-        const results = await Promise.allSettled([server?.close(), runtime.close()]);
+        unsubscribeRuntimeResourceUpdates?.();
+        const activeRuntime = runtime;
+        clearRuntime();
+        const results = await Promise.allSettled([server?.close(), activeRuntime?.close()]);
         const firstFailure = results.find((result) => result.status === "rejected");
         if (firstFailure) {
             throw firstFailure.reason;
         }
     };
+    const runLifecycleTransition = async (operation) => {
+        const previousTransition = lifecycleTransition;
+        let releaseTransition;
+        lifecycleTransition = new Promise((resolve) => {
+            releaseTransition = resolve;
+        });
+        await previousTransition.catch(() => {
+            // Ignore previous transition failures so later lifecycle operations can still proceed.
+        });
+        try {
+            return await operation();
+        }
+        finally {
+            releaseTransition();
+        }
+    };
+    const closeResources = async () => {
+        await runLifecycleTransition(async () => {
+            await closeResourcesInternal();
+        });
+    };
+    const bootstrapSessionInternal = async (nextAuthState = "unknown") => {
+        if (authPolicy.mode !== "bootstrap_then_attach" || !profilePath) {
+            throw new Error("UNSUPPORTED_SESSION_CONTROL: bootstrap is available only for auth-sensitive managed sessions");
+        }
+        await closeRuntime();
+        if (await hasRunningBootstrapBrowser()) {
+            return refreshStatus();
+        }
+        if (metadata?.ownership === "managed") {
+            await stopManagedBrowser(metadata);
+        }
+        await ensureManagedProfile(profilePath);
+        const bootstrapOptions = {
+            targetUrl,
+            userDataDir: profilePath,
+        };
+        if (options.browserChannel !== undefined) {
+            bootstrapOptions.browserChannel = options.browserChannel;
+        }
+        const launchResult = await launchBootstrapBrowser(bootstrapOptions);
+        const bootstrapPatch = {
+            presentationMode: "headed",
+            preferredPresentationMode,
+            sessionState: nextAuthState === "unknown" ? "bootstrap_active" : describeSessionStateFromAuth(nextAuthState),
+            authState: nextAuthState,
+            controlMode: "bootstrap",
+            ownership: "external",
+            browserUrl: null,
+            browserPid: null,
+        };
+        if (launchResult.pid !== undefined) {
+            bootstrapPatch.browserPid = launchResult.pid;
+        }
+        await writeMetadata(bootstrapPatch);
+        return refreshStatus();
+    };
+    const adoptManagedAttachBrowserAsBootstrap = async (nextAuthState, nextBrowserPid) => {
+        await closeRuntime();
+        const bootstrapPatch = {
+            presentationMode: "headed",
+            preferredPresentationMode: "headed",
+            sessionState: describeSessionStateFromAuth(nextAuthState),
+            authState: nextAuthState,
+            controlMode: "bootstrap",
+            ownership: "external",
+            browserUrl: null,
+            browserPid: null,
+        };
+        if (nextBrowserPid !== undefined) {
+            bootstrapPatch.browserPid = nextBrowserPid;
+        }
+        preferredPresentationMode = "headed";
+        await writeMetadata(bootstrapPatch);
+        return refreshStatus();
+    };
+    const activateRuntime = async (nextRuntime, nextOwnership, nextBrowserUrl, nextBrowserPid) => {
+        const nextAuthState = await probeRuntimeAuthState(nextRuntime);
+        bindRuntime(nextRuntime, nextOwnership);
+        browserUrl = nextBrowserUrl;
+        browserPid = nextBrowserPid;
+        authState = nextAuthState;
+        sessionState = "runtime_active";
+        presentationMode = nextRuntime.presentationMode;
+        if (profilePath && metadataFallback) {
+            const runtimePatch = {
+                presentationMode: nextRuntime.presentationMode,
+                preferredPresentationMode,
+                sessionState: "runtime_active",
+                authState: nextAuthState,
+                controlMode: nextRuntime.controlMode,
+                ownership: nextOwnership,
+            };
+            if (nextBrowserUrl !== undefined) {
+                runtimePatch.browserUrl = nextBrowserUrl;
+            }
+            else {
+                runtimePatch.browserUrl = null;
+            }
+            if (nextBrowserPid !== undefined) {
+                runtimePatch.browserPid = nextBrowserPid;
+            }
+            else {
+                runtimePatch.browserPid = null;
+            }
+            await writeMetadata(runtimePatch);
+        }
+        return refreshStatus();
+    };
+    const attachSessionInternal = async (requestedBrowserUrl, requestedPresentationMode = preferredPresentationMode) => {
+        const explicitBrowserUrl = requestedBrowserUrl?.trim() || options.browserUrl?.trim();
+        const relaunchManagedAttachBrowser = !explicitBrowserUrl &&
+            controlMode === "attach" &&
+            ownership === "managed" &&
+            requestedPresentationMode !== presentationMode;
+        const activeBrowserUrl = explicitBrowserUrl || (relaunchManagedAttachBrowser ? undefined : browserUrl);
+        const nextOwnership = explicitBrowserUrl ? "external" : "managed";
+        if (runtime) {
+            await closeRuntime();
+        }
+        if (relaunchManagedAttachBrowser) {
+            const managedBrowserPid = browserPid ?? (profilePath ? await findBrowserProcessForProfile(profilePath) : undefined);
+            if (profilePath && metadataFallback) {
+                await updateSessionMetadata(profilePath, metadataFallback, {
+                    controlMode: "none",
+                    ownership: "none",
+                    browserUrl: null,
+                    browserPid: null,
+                });
+            }
+            await stopBrowserProcess(managedBrowserPid);
+            if (managedBrowserPid) {
+                const didExit = await waitForProcessExit(managedBrowserPid, BOOTSTRAP_BROWSER_CLOSE_TIMEOUT_MS);
+                if (!didExit) {
+                    throw new Error(`BROWSER_CLOSE_TIMEOUT: timed out waiting for managed browser ${String(managedBrowserPid)} to exit`);
+                }
+                await new Promise((resolve) => setTimeout(resolve, BOOTSTRAP_PROFILE_RELEASE_DELAY_MS));
+            }
+            browserUrl = undefined;
+            browserPid = undefined;
+        }
+        let managedAttachPid;
+        let attachBrowserUrl = activeBrowserUrl;
+        if (!attachBrowserUrl) {
+            if (authPolicy.mode !== "bootstrap_then_attach" || !profilePath) {
+                throw new Error("CONFIG_ERROR: bridge.session.attach requires browserUrl when no managed attach session exists");
+            }
+            if (!explicitBrowserUrl && (await hasRunningBootstrapBrowser())) {
+                const bootstrapPid = metadata?.browserPid ?? (profilePath ? await findBrowserProcessForProfile(profilePath) : undefined);
+                await stopBrowserProcess(bootstrapPid);
+                const didExit = await waitForProcessExit(bootstrapPid, BOOTSTRAP_BROWSER_CLOSE_TIMEOUT_MS);
+                if (!didExit) {
+                    throw new Error(`BOOTSTRAP_BROWSER_CLOSE_TIMEOUT: timed out waiting for bootstrap browser ${String(bootstrapPid)} to exit`);
+                }
+                await writeMetadata({
+                    controlMode: "none",
+                    ownership: "none",
+                    browserUrl: null,
+                    browserPid: null,
+                });
+                await new Promise((resolve) => setTimeout(resolve, BOOTSTRAP_PROFILE_RELEASE_DELAY_MS));
+            }
+            const existingProfileBrowserPid = await findBrowserProcessForProfile(profilePath);
+            if (existingProfileBrowserPid) {
+                await stopBrowserProcess(existingProfileBrowserPid);
+                const didExit = await waitForProcessExit(existingProfileBrowserPid, BOOTSTRAP_BROWSER_CLOSE_TIMEOUT_MS);
+                if (!didExit) {
+                    throw new Error(`BROWSER_CLOSE_TIMEOUT: timed out waiting for existing browser ${String(existingProfileBrowserPid)} to exit`);
+                }
+                await new Promise((resolve) => setTimeout(resolve, BOOTSTRAP_PROFILE_RELEASE_DELAY_MS));
+            }
+            await ensureManagedProfile(profilePath);
+            const attachOptions = {
+                targetUrl,
+                userDataDir: profilePath,
+                presentationMode: requestedPresentationMode,
+            };
+            if (options.browserChannel !== undefined) {
+                attachOptions.browserChannel = options.browserChannel;
+            }
+            const managedAttach = await launchManagedAttachBrowser(attachOptions);
+            attachBrowserUrl = managedAttach.browserUrl;
+            managedAttachPid = managedAttach.pid;
+        }
+        try {
+            const nextRuntime = await startRuntime(buildRuntimeStartOptions(options, siteDefinition, "attach", requestedPresentationMode, attachBrowserUrl));
+            const nextAuthState = await probeRuntimeAuthState(nextRuntime);
+            if (authPolicy.mode === "bootstrap_then_attach" &&
+                !explicitBrowserUrl &&
+                (nextAuthState === "auth_required" || nextAuthState === "challenge_required")) {
+                if (managedAttachPid && requestedPresentationMode === "headed") {
+                    bindRuntime(nextRuntime, "managed");
+                    return await adoptManagedAttachBrowserAsBootstrap(nextAuthState, managedAttachPid);
+                }
+                await nextRuntime.close();
+                return await bootstrapSessionInternal(nextAuthState);
+            }
+            preferredPresentationMode = requestedPresentationMode;
+            return await activateRuntime(nextRuntime, nextOwnership, attachBrowserUrl, managedAttachPid ?? browserPid);
+        }
+        catch (error) {
+            if (managedAttachPid && profilePath && metadataFallback) {
+                const cleanupMetadata = await updateSessionMetadata(profilePath, metadataFallback, {
+                    controlMode: "none",
+                    ownership: "none",
+                    browserUrl: null,
+                    browserPid: null,
+                });
+                await stopManagedBrowser({
+                    ...cleanupMetadata,
+                    ownership: "managed",
+                    browserPid: managedAttachPid,
+                });
+            }
+            await closeResourcesInternal().catch(options.onError);
+            throw error;
+        }
+    };
+    const setPresentationModeInternal = async (setModeOptions) => {
+        if (closed) {
+            throw new Error("SESSION_NOT_AVAILABLE: local-mcp bridge session is closed");
+        }
+        const requestedPresentationMode = setModeOptions.presentationMode;
+        const previousRuntime = runtime;
+        const previousState = refreshStatus();
+        const previousPreferredPresentationMode = preferredPresentationMode;
+        if (controlMode === "bootstrap") {
+            throw new Error("UNSUPPORTED_SESSION_CONTROL: bridge.session.mode.set is unavailable while the bridge is in bootstrap mode");
+        }
+        if (ownership === "external") {
+            throw new Error("UNSUPPORTED_SESSION_CONTROL: bridge.session.mode.set is unavailable for external attach sessions");
+        }
+        if (requestedPresentationMode === presentationMode) {
+            preferredPresentationMode = requestedPresentationMode;
+            if (profilePath && metadataFallback) {
+                await writeMetadata({
+                    presentationMode,
+                    preferredPresentationMode,
+                });
+            }
+            return refreshStatus();
+        }
+        if (controlMode === "attach") {
+            preferredPresentationMode = requestedPresentationMode;
+            return await attachSessionInternal(undefined, requestedPresentationMode);
+        }
+        await closeRuntime();
+        preferredPresentationMode = requestedPresentationMode;
+        try {
+            const nextRuntime = await startRuntime(buildRuntimeStartOptions(options, siteDefinition, "launch", requestedPresentationMode));
+            return await activateRuntime(nextRuntime, "managed");
+        }
+        catch (error) {
+            preferredPresentationMode = previousPreferredPresentationMode;
+            if (previousRuntime) {
+                try {
+                    const recoveredRuntime = await startRuntime(buildRuntimeStartOptions(options, siteDefinition, "launch", previousState.presentationMode));
+                    await activateRuntime(recoveredRuntime, previousState.ownership);
+                }
+                catch (recoveryError) {
+                    options.onError?.(recoveryError);
+                    await closeResourcesInternal().catch(options.onError);
+                }
+            }
+            else {
+                await closeResourcesInternal().catch(options.onError);
+            }
+            throw error;
+        }
+    };
+    const setPresentationMode = async (setModeOptions) => {
+        return await runLifecycleTransition(async () => await setPresentationModeInternal(setModeOptions));
+    };
+    const resetProfileInternal = async () => {
+        if (!profilePath || !metadataFallback) {
+            throw new Error("UNSUPPORTED_SESSION_CONTROL: reset_profile requires a managed --user-data-dir");
+        }
+        await closeRuntime();
+        if (metadata?.ownership === "managed") {
+            await stopManagedBrowser(metadata);
+        }
+        const resetResult = await backupAndResetProfile(profilePath, metadataFallback);
+        syncFromMetadata(resetResult.metadata);
+        lastBackupPath = resetResult.backupPath;
+        if (authPolicy.mode === "bootstrap_then_attach") {
+            return await bootstrapSessionInternal();
+        }
+        return refreshStatus();
+    };
+    const initializeControlPlane = async () => {
+        if (authPolicy.mode !== "bootstrap_then_attach") {
+            const nextControlMode = options.browserUrl ? "attach" : "launch";
+            const nextRuntime = await startRuntime(buildRuntimeStartOptions(options, siteDefinition, nextControlMode, preferredPresentationMode, options.browserUrl));
+            await activateRuntime(nextRuntime, nextControlMode === "attach" ? "external" : "managed", options.browserUrl);
+            return;
+        }
+        const managedProfilePath = profilePath;
+        metadata = await readSessionMetadata(managedProfilePath, metadataFallback);
+        syncFromMetadata(metadata);
+        if (options.browserUrl) {
+            await attachSessionInternal(options.browserUrl);
+            return;
+        }
+        const hasRunningBootstrapExternal = await hasRunningBootstrapBrowser(metadata);
+        if (hasRunningBootstrapExternal) {
+            return;
+        }
+        const hasRunningManagedAttach = metadata.controlMode === "attach" &&
+            metadata.browserUrl !== undefined &&
+            metadata.ownership === "managed" &&
+            (await isProcessRunning(metadata.browserPid));
+        if (hasRunningManagedAttach) {
+            await attachSessionInternal();
+            return;
+        }
+        if (metadata.authState === "authenticated") {
+            await attachSessionInternal();
+            return;
+        }
+        if (metadata.sessionState !== "profile_missing") {
+            await attachSessionInternal();
+            return;
+        }
+        await bootstrapSessionInternal(metadata.authState === "auth_required" || metadata.authState === "challenge_required"
+            ? metadata.authState
+            : "unknown");
+    };
+    await initializeControlPlane();
+    const gateway = {
+        listTools: async () => {
+            if (!runtime) {
+                return [];
+            }
+            return await runtime.gateway.listTools();
+        },
+        callTool: async (name, input) => {
+            if (!runtime) {
+                throw new Error("SESSION_NOT_AVAILABLE: page tools are unavailable while local-mcp is waiting for bootstrap or attach");
+            }
+            return await runtime.gateway.callTool(name, input);
+        },
+        listResources: async () => {
+            if (!runtime) {
+                return [];
+            }
+            return await runtime.gateway.listResources();
+        },
+        readResource: async (uri) => {
+            if (!runtime) {
+                throw new Error(`RESOURCE_NOT_FOUND: ${uri}`);
+            }
+            return await runtime.gateway.readResource(uri);
+        },
+        onResourceUpdated: (listener) => {
+            resourceUpdatedListeners.add(listener);
+            return () => {
+                resourceUpdatedListeners.delete(listener);
+            };
+        },
+    };
     try {
         const serverOptions = {
-            gateway: runtime.gateway,
+            gateway,
             bridgeControl: {
-                getState: () => ({
-                    site: runtime.site,
-                    targetUrl: runtime.targetUrl,
-                    mode: runtime.mode,
-                    headless: runtime.headless,
-                }),
-                openWindow: runtime.openWindow,
+                getState: refreshStatus,
+                openWindow: async () => {
+                    if (runtime) {
+                        return await runtime.openWindow();
+                    }
+                    if (authPolicy.mode === "bootstrap_then_attach") {
+                        if (await hasRunningBootstrapBrowser()) {
+                            await focusBrowserWindow(options.browserChannel).catch(() => {
+                                // Focusing an external browser is best-effort; reuse still avoids duplicate windows.
+                            });
+                            return "focused";
+                        }
+                        await runLifecycleTransition(async () => {
+                            await bootstrapSessionInternal(authState);
+                        });
+                        return "opened";
+                    }
+                    throw new Error("SESSION_NOT_AVAILABLE: current page is closed");
+                },
+                bootstrapSession: async () => {
+                    return await runLifecycleTransition(async () => await bootstrapSessionInternal(authState));
+                },
+                attachSession: async (requestedBrowserUrl) => {
+                    return await runLifecycleTransition(async () => await attachSessionInternal(requestedBrowserUrl));
+                },
+                getPresentationMode: () => refreshStatus().presentationMode,
+                setPresentationMode: async (setModeOptions) => await setPresentationMode(setModeOptions),
+                resetProfile: async () => {
+                    return await runLifecycleTransition(async () => await resetProfileInternal());
+                },
                 closeBridge: async () => {
                     await closeResources();
                 },
@@ -125,7 +667,7 @@ export async function startLocalMcpBridge(options) {
         await server.start();
     }
     catch (error) {
-        await runtime.close();
+        await closeResourcesInternal().catch(options.onError);
         throw error;
     }
     const input = options.input ?? process.stdin;
@@ -134,18 +676,26 @@ export async function startLocalMcpBridge(options) {
             options.onError?.(error);
         });
     };
-    const handleOwnerSessionEnded = () => {
-        void closeResources().catch((error) => {
-            options.onError?.(error);
-        });
-    };
     input.once("end", handleInputEnded);
-    void runtime.ownerSessionEnded.then(handleOwnerSessionEnded);
     return {
-        site: runtime.site,
-        targetUrl: runtime.targetUrl,
-        mode: runtime.mode,
-        headless: runtime.headless,
+        get site() {
+            return siteDefinition.id;
+        },
+        get targetUrl() {
+            return targetUrl;
+        },
+        get controlMode() {
+            return controlMode;
+        },
+        get mode() {
+            return runtimeMode;
+        },
+        get presentationMode() {
+            return presentationMode;
+        },
+        get preferredPresentationMode() {
+            return preferredPresentationMode;
+        },
         close: async () => {
             input.removeListener("end", handleInputEnded);
             await closeResources();