@webmcp-bridge/local-mcp 0.5.4 → 0.7.0

package/dist/bridge.js

@@ -1,23 +1,13 @@
 /**
- * This module composes runtime startup with the stdio MCP server into one lifecycle handle.
- * 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.
+ * This module composes site/runtime startup with the stdio MCP server into one lifecycle handle.
+ * It depends on agent-browser-core orchestration, site resolution, and server wiring so local-mcp stays a thin MCP facade over one browser session.
  */
+import { assertAuthSensitiveBrowserSupport, resolveAuthPolicy, startBrowserSessionController, } from "@webmcp-bridge/agent-browser-core";
 import { createLocalMcpStdioServer, } from "./server.js";
 import { resolveCdpConnectUrl, startLocalMcpRuntime, } from "./runtime.js";
-import { assertAuthSensitiveBrowserSupport, backupAndResetProfile, describeSessionStateFromAuth, ensureManagedProfile, findBrowserProcessForProfile, focusBrowserWindow, isProcessRunning, launchBootstrapBrowser, launchManagedAttachBrowser, readSessionMetadata, resolveAuthPolicy, stopBrowserProcess, stopManagedBrowser, updateSessionMetadata, waitForProcessExit, } from "./session.js";
+import { evaluateDebugScript, evaluateOverlayTool, OverlayStore, } from "./overlays.js";
+import { resolveDefaultUserDataDir } from "./profiles.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 "unknown";
-    }
-    const state = value.state;
-    if (state === "authenticated" || state === "auth_required" || state === "challenge_required") {
-        return state;
-    }
-    return "unknown";
-}
 async function resolveSiteDefinitionFromBridgeOptions(options) {
     const hasAdapterSource = Boolean(options.site || options.adapterModule);
     if (hasAdapterSource) {
@@ -41,7 +31,8 @@ async function resolveSiteDefinitionFromBridgeOptions(options) {
 async function startRuntime(options) {
     return await startLocalMcpRuntime(options);
 }
-function buildRuntimeStartOptions(baseOptions, siteDefinition, controlMode, preferredPresentationMode, browserUrl) {
+function buildRuntimeStartOptions(baseOptions, siteDefinition, userDataDir, controlMode, preferredPresentationMode, browserUrl) {
+    const configuredBrowserUrl = baseOptions.browserUrl?.trim() || undefined;
     const nextOptions = {
         siteDefinition,
         preferredPresentationMode,
@@ -52,8 +43,8 @@ function buildRuntimeStartOptions(baseOptions, siteDefinition, controlMode, pref
     if (baseOptions.browser !== undefined) {
         nextOptions.browser = baseOptions.browser;
     }
-    if (baseOptions.userDataDir !== undefined) {
-        nextOptions.userDataDir = baseOptions.userDataDir;
+    if (userDataDir !== undefined) {
+        nextOptions.userDataDir = userDataDir;
     }
     if (baseOptions.preferNative !== undefined) {
         nextOptions.preferNative = baseOptions.preferNative;
@@ -65,7 +56,7 @@ function buildRuntimeStartOptions(baseOptions, siteDefinition, controlMode, pref
         if (!browserUrl) {
             throw new Error("CONFIG_ERROR: attach mode requires a browserUrl");
         }
-        const explicitAttach = baseOptions.browserUrl !== undefined;
+        const explicitAttach = configuredBrowserUrl !== undefined;
         if (explicitAttach && baseOptions.browserChannel !== undefined) {
             throw new Error("CONFIG_ERROR: --browser-url cannot be combined with --browser-channel");
         }
@@ -84,6 +75,9 @@ function buildRuntimeStartOptions(baseOptions, siteDefinition, controlMode, pref
     }
     return nextOptions;
 }
+function toLocalBridgeState(status) {
+    return status;
+}
 export async function startLocalMcpBridge(options) {
     const siteDefinition = await resolveSiteDefinitionFromBridgeOptions(options);
     const authPolicy = resolveAuthPolicy(siteDefinition.manifest);
@@ -91,625 +85,194 @@ export async function startLocalMcpBridge(options) {
     if (!targetUrl) {
         throw new Error("CONFIG_ERROR: no target url provided (missing --url and manifest.defaultUrl)");
     }
+    const configuredBrowserUrl = options.browserUrl?.trim() || undefined;
+    const managedUserDataDir = configuredBrowserUrl === undefined
+        ? (options.userDataDir ?? resolveDefaultUserDataDir(siteDefinition, targetUrl))
+        : undefined;
     if (authPolicy.mode === "bootstrap_then_attach") {
-        assertAuthSensitiveBrowserSupport(options.browser, options.userDataDir);
+        assertAuthSensitiveBrowserSupport(options.browser, managedUserDataDir);
     }
-    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;
-    const configuredPreferredPresentationMode = options.preferredPresentationMode;
-    let preferredPresentationMode = options.preferredPresentationMode ?? "headed";
-    let presentationMode = preferredPresentationMode;
-    let lastBackupPath;
-    let metadata;
+    const overlayStore = new OverlayStore(siteDefinition.id, managedUserDataDir);
+    await overlayStore.load();
     let server;
-    let closed = false;
-    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 = configuredPreferredPresentationMode ?? 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;
+    let closeRequested = false;
+    let closeResources = async () => { };
+    const toolsetListeners = new Set();
+    const notifyToolsetMayHaveChanged = () => {
+        for (const listener of toolsetListeners) {
+            try {
+                listener();
             }
-            void closeResources().catch((error) => {
+            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 requestClose = () => {
+        closeRequested = true;
+        if (server === undefined) {
+            return;
         }
+        void closeResources().catch((error) => {
+            options.onError?.(error);
+        });
     };
-    const closeResourcesInternal = async () => {
+    const controller = await startBrowserSessionController({
+        site: siteDefinition.id,
+        targetUrl,
+        authPolicy,
+        ...(managedUserDataDir !== undefined ? { profilePath: managedUserDataDir } : {}),
+        ...(options.browserChannel !== undefined ? { browserChannel: options.browserChannel } : {}),
+        ...(options.browserUrl !== undefined ? { browserUrl: options.browserUrl } : {}),
+        ...(options.preferredPresentationMode !== undefined
+            ? { preferredPresentationMode: options.preferredPresentationMode }
+            : {}),
+        runtimeFactory: async ({ controlMode, preferredPresentationMode, browserUrl }) => await startRuntime(buildRuntimeStartOptions(options, siteDefinition, managedUserDataDir, controlMode, preferredPresentationMode, browserUrl)),
+        browserUrlHealthCheck: async (browserUrl) => {
+            await resolveCdpConnectUrl(browserUrl);
+        },
+        onCloseRequested: requestClose,
+        ...(options.onError !== undefined ? { onError: options.onError } : {}),
+    });
+    const unsubscribeControllerToolset = controller.onToolsetMayHaveChanged(() => {
+        notifyToolsetMayHaveChanged();
+    });
+    let closed = false;
+    let lastState = toLocalBridgeState(controller.getState());
+    closeResources = async () => {
         if (closed) {
             return;
         }
         closed = true;
-        unsubscribeRuntimeResourceUpdates?.();
-        const activeMetadata = metadata;
-        const activeRuntime = runtime;
-        clearRuntime();
-        const results = await Promise.allSettled([
-            server?.close(),
-            activeRuntime?.close(),
-            activeMetadata?.ownership === "managed" ? stopManagedBrowser(activeMetadata) : undefined,
-        ]);
+        lastState = toLocalBridgeState(controller.getState());
+        unsubscribeControllerToolset();
+        const activeServer = server;
+        server = undefined;
+        const results = await Promise.allSettled([activeServer?.close(), controller.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 (!explicitBrowserUrl && attachBrowserUrl && ownership === "managed") {
-            const managedBrowserPid = browserPid ?? (profilePath ? await findBrowserProcessForProfile(profilePath) : undefined);
-            const managedBrowserRunning = await isProcessRunning(managedBrowserPid);
-            let managedBrowserUrlHealthy = managedBrowserRunning;
-            if (managedBrowserRunning) {
-                try {
-                    await resolveCdpConnectUrl(attachBrowserUrl);
-                }
-                catch {
-                    managedBrowserUrlHealthy = false;
-                }
-            }
-            if (!managedBrowserRunning || !managedBrowserUrlHealthy) {
-                if (managedBrowserRunning) {
-                    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 stale managed browser ${String(managedBrowserPid)} to exit`);
-                        }
-                        await new Promise((resolve) => setTimeout(resolve, BOOTSTRAP_PROFILE_RELEASE_DELAY_MS));
-                    }
-                }
-                if (profilePath && metadataFallback) {
-                    await updateSessionMetadata(profilePath, metadataFallback, {
-                        controlMode: "none",
-                        ownership: "none",
-                        browserUrl: null,
-                        browserPid: null,
-                    });
-                }
-                attachBrowserUrl = undefined;
-                browserUrl = undefined;
-                browserPid = undefined;
-            }
-        }
-        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 () => {
+            const runtime = controller.getRuntime();
             if (!runtime) {
                 return [];
             }
-            return await runtime.gateway.listTools();
+            const pageTools = await runtime.gateway.listTools();
+            return [...pageTools, ...overlayStore.listEnabledToolDefinitions()];
         },
         callTool: async (name, input) => {
+            const runtime = controller.getRuntime();
             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);
+            const overlayTool = overlayStore.getOverlayTool(name);
+            if (overlayTool) {
+                return await evaluateOverlayTool(runtime.page, overlayTool.overlay, overlayTool.tool, input);
+            }
+            return (await runtime.gateway.callTool(name, input));
         },
         listResources: async () => {
+            const runtime = controller.getRuntime();
             if (!runtime) {
                 return [];
             }
             return await runtime.gateway.listResources();
         },
         readResource: async (uri) => {
+            const runtime = controller.getRuntime();
             if (!runtime) {
                 throw new Error(`RESOURCE_NOT_FOUND: ${uri}`);
             }
             return await runtime.gateway.readResource(uri);
         },
-        onResourceUpdated: (listener) => {
-            resourceUpdatedListeners.add(listener);
-            return () => {
-                resourceUpdatedListeners.delete(listener);
-            };
-        },
+        onResourceUpdated: (listener) => controller.onResourceUpdated(listener),
     };
     try {
         const serverOptions = {
             gateway,
             bridgeControl: {
-                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");
+                getState: () => {
+                    lastState = toLocalBridgeState(controller.getState());
+                    return lastState;
                 },
+                openWindow: async () => await controller.openWindow(),
                 bootstrapSession: async () => {
-                    return await runLifecycleTransition(async () => await bootstrapSessionInternal(authState));
+                    lastState = toLocalBridgeState(await controller.bootstrapSession());
+                    return lastState;
                 },
                 attachSession: async (requestedBrowserUrl) => {
-                    return await runLifecycleTransition(async () => await attachSessionInternal(requestedBrowserUrl));
+                    lastState = toLocalBridgeState(await controller.attachSession(requestedBrowserUrl));
+                    return lastState;
+                },
+                debugEval: async (script, args) => {
+                    const runtime = controller.getRuntime();
+                    if (!runtime) {
+                        throw new Error("SESSION_NOT_AVAILABLE: debug eval requires an active browser runtime");
+                    }
+                    return await evaluateDebugScript(runtime.page, script, args);
+                },
+                listOverlays: async () => overlayStore.list(),
+                installOverlay: async (installOptions) => {
+                    const overlay = await overlayStore.install(installOptions);
+                    notifyToolsetMayHaveChanged();
+                    return overlay;
+                },
+                updateOverlay: async (updateOptions) => {
+                    const overlay = await overlayStore.update(updateOptions);
+                    notifyToolsetMayHaveChanged();
+                    return overlay;
+                },
+                enableOverlay: async (id) => {
+                    const overlay = await overlayStore.enable(id);
+                    notifyToolsetMayHaveChanged();
+                    return overlay;
+                },
+                disableOverlay: async (id) => {
+                    const overlay = await overlayStore.disable(id);
+                    notifyToolsetMayHaveChanged();
+                    return overlay;
+                },
+                deleteOverlay: async (id) => {
+                    await overlayStore.delete(id);
+                    notifyToolsetMayHaveChanged();
+                },
+                getPresentationMode: () => controller.getPresentationMode(),
+                setPresentationMode: async (setModeOptions) => {
+                    lastState = toLocalBridgeState(await controller.setPresentationMode(setModeOptions));
+                    return lastState;
                 },
-                getPresentationMode: () => refreshStatus().presentationMode,
-                setPresentationMode: async (setModeOptions) => await setPresentationMode(setModeOptions),
                 resetProfile: async () => {
-                    return await runLifecycleTransition(async () => await resetProfileInternal());
+                    lastState = toLocalBridgeState(await controller.resetProfile());
+                    await overlayStore.load();
+                    notifyToolsetMayHaveChanged();
+                    return lastState;
                 },
                 closeBridge: async () => {
                     await closeResources();
                 },
             },
             serviceVersion: options.serviceVersion,
+            onToolsetMayHaveChanged: (listener) => {
+                toolsetListeners.add(listener);
+                return () => {
+                    toolsetListeners.delete(listener);
+                };
+            },
+            ...(options.input !== undefined ? { input: options.input } : {}),
+            ...(options.output !== undefined ? { output: options.output } : {}),
+            ...(options.onError !== undefined ? { onError: options.onError } : {}),
         };
-        if (options.input !== undefined) {
-            serverOptions.input = options.input;
-        }
-        if (options.output !== undefined) {
-            serverOptions.output = options.output;
-        }
-        if (options.onError !== undefined) {
-            serverOptions.onError = options.onError;
-        }
         server = createLocalMcpStdioServer(serverOptions);
         await server.start();
+        if (closeRequested) {
+            await closeResources();
+        }
     }
     catch (error) {
-        await closeResourcesInternal().catch(options.onError);
+        await closeResources().catch(options.onError);
         throw error;
     }
     const input = options.input ?? process.stdin;
@@ -721,22 +284,24 @@ export async function startLocalMcpBridge(options) {
     input.once("end", handleInputEnded);
     return {
         get site() {
-            return siteDefinition.id;
+            return lastState.site;
         },
         get targetUrl() {
-            return targetUrl;
+            return lastState.targetUrl;
         },
         get controlMode() {
-            return controlMode;
+            return lastState.controlMode;
         },
         get mode() {
-            return runtimeMode;
+            return lastState.mode;
         },
         get presentationMode() {
-            return presentationMode;
+            lastState = toLocalBridgeState(controller.getState());
+            return lastState.presentationMode;
         },
         get preferredPresentationMode() {
-            return preferredPresentationMode;
+            lastState = toLocalBridgeState(controller.getState());
+            return lastState.preferredPresentationMode;
         },
         close: async () => {
             input.removeListener("end", handleInputEnded);