@nudge-ui/mcp 0.2.4 → 0.2.5

package/dist/bridge.js

@@ -1,16 +1,36 @@
 import { createServer, } from "node:http";
 import { randomBytes, randomUUID } from "node:crypto";
-import { AGENT_PROTOCOL_LIMITS, AGENT_PROTOCOL_VERSION, canonicalOrigin, isAgentStatusUpdate, isAgentActivity, isAllowedOrigin, isCanvasCommand, isCanvasGroup, isCanvasState, isSameOriginRoute, validateSketchAttachments, validateRoutes, } from "./internal/agent-protocol.js";
+import { AGENT_PROTOCOL_LIMITS, AGENT_PROTOCOL_VERSION, canonicalOrigin, isAgentActivity, isAgentStatusUpdate, isCanvasCommand, isCanvasCommandResult, validateSketchAttachments, } from "./internal/agent-protocol.js";
+import { BridgeSessionError, createBridgeSession, } from "./bridgeSession.js";
 import { AGENT_CONTROL_ENDPOINTS, BRIDGE_ENDPOINTS } from "./protocol.js";
 const LOOPBACK_HOSTS = new Set(["127.0.0.1", "::1", "localhost"]);
 const MAX_BODY_BYTES = 256 * 1024;
 const MAX_PROMPT_BODY_BYTES = 12 * 1024 * 1024;
-const DEFAULT_COMMAND_TIMEOUT_MS = 5_000;
-const AGENT_CLAIM_TIMEOUT_MS = 30_000;
-const SYSTEM_CLOCK = {
-    now: () => Date.now(),
-    setTimeout: (callback, delayMs) => setTimeout(callback, delayMs),
-    clearTimeout: (handle) => clearTimeout(handle),
+const SESSION_ERROR_STATUS = {
+    project_not_found: 404,
+    origin_not_allowed: 403,
+    origin_mismatch: 403,
+    invalid_session: 401,
+    invalid_page_url: 400,
+    invalid_status: 400,
+    invalid_activity: 400,
+    invalid_canvas_command: 400,
+    invalid_routes: 400,
+    already_paired: 409,
+    browser_unpaired: 409,
+    listener_active: 409,
+    listener_unavailable: 409,
+    listener_cancelled: 409,
+    listener_aborted: 409,
+    request_in_flight: 409,
+    unknown_request: 409,
+    inactive_request: 409,
+    command_in_flight: 409,
+    no_command: 409,
+    unknown_command: 409,
+    session_claimed: 409,
+    agent_not_owner: 409,
+    session_closed: 409,
 };
 class BridgeRequestError extends Error {
     statusCode;
@@ -22,26 +42,18 @@ class BridgeRequestError extends Error {
         this.code = code;
     }
 }
-function randomToken() {
-    return randomBytes(32).toString("base64url");
-}
-function randomId() {
-    return randomUUID();
-}
-function deferred() {
-    let resolvePromise;
-    let rejectPromise;
-    const promise = new Promise((resolve, reject) => {
-        resolvePromise = resolve;
-        rejectPromise = reject;
-    });
-    return { promise, resolve: resolvePromise, reject: rejectPromise };
+function route(method, path, handler) {
+    return [`${method} ${path}`, handler];
 }
 function loopbackAddress(address) {
     if (!address)
         return false;
     return LOOPBACK_HOSTS.has(address) || address === "::ffff:127.0.0.1";
 }
+function requireLoopback(request, code, message) {
+    if (!loopbackAddress(request.socket.remoteAddress))
+        throw new BridgeRequestError(403, code, message);
+}
 function validPort(port) {
     return Number.isInteger(port) && port >= 0 && port <= 65_535;
 }
@@ -54,38 +66,31 @@ function headerValue(request, name) {
 function requestOrigin(request) {
     return canonicalOrigin(headerValue(request, "origin"));
 }
-function parseProjectId(value, expected) {
-    if (value !== expected) {
-        throw new BridgeRequestError(404, "project_not_found", "The requested project is not served by this companion.");
-    }
+function optionalString(value) {
+    return typeof value === "string" ? value : undefined;
 }
-function parseToken(value, expected) {
-    if (!expected || value !== expected) {
-        throw new BridgeRequestError(401, "invalid_session", "The browser session token is invalid or expired.");
-    }
+function setCors(response, origin) {
+    response.setHeader("Access-Control-Allow-Origin", origin);
+    response.setHeader("Access-Control-Allow-Credentials", "true");
+    response.setHeader("Vary", "Origin");
 }
-function jsonHeaders(response, origin) {
+function sendJson(response, statusCode, body, origin) {
     response.setHeader("Content-Type", "application/json; charset=utf-8");
     response.setHeader("Cache-Control", "no-store");
     response.setHeader("X-Content-Type-Options", "nosniff");
-    if (origin) {
-        response.setHeader("Access-Control-Allow-Origin", origin);
-        response.setHeader("Access-Control-Allow-Credentials", "true");
-        response.setHeader("Vary", "Origin");
-    }
-}
-function sendJson(response, statusCode, body, origin) {
-    jsonHeaders(response, origin);
+    if (origin)
+        setCors(response, origin);
     response.statusCode = statusCode;
     response.end(JSON.stringify(body));
 }
-function sendError(response, error, origin) {
+function errorResponse(error) {
     if (error instanceof BridgeRequestError) {
-        const body = { error: { code: error.code, message: error.message } };
-        sendJson(response, error.statusCode, body, origin);
-        return;
+        return { statusCode: error.statusCode, body: { error: { code: error.code, message: error.message } } };
     }
-    sendJson(response, 500, { error: { code: "internal_error", message: "The bridge could not complete the request." } }, origin);
+    if (error instanceof BridgeSessionError) {
+        return { statusCode: SESSION_ERROR_STATUS[error.code], body: { error: { code: error.code, message: error.message } } };
+    }
+    return { statusCode: 500, body: { error: { code: "internal_error", message: "The bridge could not complete the request." } } };
 }
 async function readJsonBody(request, maxBytes = MAX_BODY_BYTES) {
     const chunks = [];
@@ -122,7 +127,7 @@ function pngDimensions(bytes) {
         height: bytes.readUInt32BE(20),
     };
 }
-function parseSketchAttachments(value) {
+function decodeSketchAttachments(value) {
     let attachments;
     try {
         attachments = validateSketchAttachments(value);
@@ -143,591 +148,291 @@ function parseSketchAttachments(value) {
     }
     return attachments;
 }
-function createEnvelope(projectId, sessionToken, event) {
+function decodePromptDispatch(body) {
+    const { prompt, changeRevision, clientDispatchId } = body;
+    if (typeof prompt !== "string" || prompt.length === 0 || prompt.length > AGENT_PROTOCOL_LIMITS.prompt) {
+        throw new BridgeRequestError(400, "invalid_prompt", "prompt must be a bounded non-empty string");
+    }
+    if (changeRevision !== undefined && (typeof changeRevision !== "number" || !Number.isSafeInteger(changeRevision) || changeRevision < 0)) {
+        throw new BridgeRequestError(400, "invalid_revision", "changeRevision must be a non-negative safe integer");
+    }
+    if (clientDispatchId !== undefined && (typeof clientDispatchId !== "string"
+        || clientDispatchId.length === 0 || clientDispatchId.length > AGENT_PROTOCOL_LIMITS.clientDispatchId)) {
+        throw new BridgeRequestError(400, "invalid_dispatch_id", "clientDispatchId must be a bounded non-empty string");
+    }
     return {
-        protocolVersion: AGENT_PROTOCOL_VERSION,
-        projectId,
-        sessionToken,
-        event,
+        prompt,
+        ...(changeRevision === undefined ? {} : { changeRevision }),
+        ...(clientDispatchId === undefined ? {} : { clientDispatchId }),
+        attachments: decodeSketchAttachments(body.attachments),
     };
 }
+function decodeAgentId(value) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value !== "string" || value.length === 0 || value.length > 256) {
+        throw new BridgeRequestError(400, "invalid_agent_id", "agentId must be a bounded non-empty string.");
+    }
+    return value;
+}
 function writeSse(response, envelope) {
     if (response.destroyed || response.writableEnded)
-        return;
-    response.write(`event: ${envelope.event.type}\ndata: ${JSON.stringify(envelope)}\n\n`);
-}
-function connectionFor(listenerActive, paired, request) {
-    if (request?.status === "working")
-        return "working";
-    if (paired)
-        return "paired";
-    if (listenerActive)
-        return "listening";
-    return "offline";
-}
-function statusWith(projectId, listenerActive, paired, request, pageUrl, agentClientName) {
-    return {
-        protocolVersion: AGENT_PROTOCOL_VERSION,
-        projectId,
-        connection: connectionFor(listenerActive, paired, request),
-        listenerActive,
-        paired,
-        pageUrl,
-        ...(agentClientName === undefined ? {} : { agentClientName }),
-        request,
-    };
+        return false;
+    try {
+        response.write(`event: ${envelope.event.type}\ndata: ${JSON.stringify(envelope)}\n\n`);
+        return true;
+    }
+    catch {
+        response.destroy();
+        return false;
+    }
 }
 /**
  * Creates the local browser bridge. It binds only to loopback and keeps every
  * pairing, prompt, command, and acknowledgement in process memory.
  */
 export function createLoopbackBridge(options) {
-    if (typeof options.projectId !== "string" || options.projectId.length === 0
-        || options.projectId.length > AGENT_PROTOCOL_LIMITS.projectId) {
-        throw new TypeError("projectId must be a bounded non-empty string");
-    }
-    const configuredOrigin = options.origin === undefined ? null : canonicalOrigin(options.origin);
-    if (options.origin !== undefined && !configuredOrigin)
-        throw new TypeError("origin must be a canonical HTTP(S) origin");
     const host = options.host ?? "127.0.0.1";
     if (!LOOPBACK_HOSTS.has(host))
         throw new TypeError("The browser bridge must bind to a loopback host");
     const port = options.port ?? 0;
     if (!validPort(port))
         throw new TypeError("port must be between 0 and 65535");
-    const timeoutMs = options.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
-    if (!Number.isInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 60_000) {
-        throw new TypeError("commandTimeoutMs must be between 1 and 60000 milliseconds");
-    }
-    const allowedOrigins = [
-        ...(configuredOrigin ? [configuredOrigin] : []),
-        ...(options.allowedOrigins ?? []),
-    ].map((candidate) => canonicalOrigin(candidate));
-    if (allowedOrigins.some((candidate) => candidate === null)) {
-        throw new TypeError("allowedOrigins must contain canonical HTTP(S) origins");
-    }
-    const canonicalAllowedOrigins = allowedOrigins;
-    const clock = options.clock ?? SYSTEM_CLOCK;
-    const tokenFactory = options.tokenFactory ?? randomToken;
-    const idFactory = options.idFactory ?? randomId;
-    const agentControlToken = options.agentControlToken;
+    const { agentControlToken } = options;
     if (agentControlToken !== undefined && (agentControlToken.length < 32 || agentControlToken.length > 256)) {
         throw new TypeError("agentControlToken must contain between 32 and 256 characters");
     }
-    let lifecycle = "created";
-    let currentAddress = null;
-    let sessionToken = null;
-    let pairedOrigin = null;
-    let lastPageUrl = null;
-    const sseClients = new Set();
-    let listener = null;
-    let currentRequest = null;
-    let pendingCanvas = null;
-    let closePromise = null;
-    let startPromise = null;
-    let agentOwner = null;
-    let agentClientName;
-    let agentOwnerSeenAt = 0;
-    let agentOwnerExpiry = null;
-    const getStatus = () => statusWith(options.projectId, listener !== null, sessionToken !== null, currentRequest, lastPageUrl, agentClientName);
-    const broadcast = (event) => {
-        if (!sessionToken)
-            return;
-        const envelope = createEnvelope(options.projectId, sessionToken, event);
-        for (const response of [...sseClients]) {
-            if (response.destroyed || response.writableEnded) {
-                sseClients.delete(response);
-                continue;
-            }
-            try {
-                writeSse(response, envelope);
-            }
-            catch {
-                sseClients.delete(response);
-                response.destroy();
-            }
-        }
-    };
-    const broadcastStatus = () => {
-        const statusEvent = { type: "status", status: getStatus() };
-        broadcast(statusEvent);
-    };
-    const originIsAllowed = (candidate) => {
-        if (!candidate)
-            return false;
-        // Once paired, the explicitly approved browser's exact origin remains the
-        // only origin accepted. Before pairing, only an origin configured by the
-        // host (directly or through the allow-list) is eligible. An empty list is
-        // deliberately closed rather than a trust-on-first-use wildcard.
-        if (pairedOrigin === candidate)
-            return true;
-        return isAllowedOrigin(candidate, canonicalAllowedOrigins);
-    };
-    const requireBrowserRequest = (request, url, bodyToken) => {
-        if (!loopbackAddress(request.socket.remoteAddress)) {
-            throw new BridgeRequestError(403, "loopback_only", "The browser bridge accepts loopback connections only.");
-        }
-        const incomingOrigin = requestOrigin(request);
-        if (!originIsAllowed(incomingOrigin)) {
-            throw new BridgeRequestError(403, "origin_not_allowed", "The browser origin is not allowed for this project.");
-        }
-        if (pairedOrigin !== incomingOrigin) {
-            throw new BridgeRequestError(403, "origin_mismatch", "The browser origin does not match the paired project.");
-        }
-        const candidate = typeof bodyToken === "string" ? bodyToken : url.searchParams.get("sessionToken");
-        parseToken(candidate, sessionToken);
-        return incomingOrigin;
-    };
-    const handleOptions = (request, response) => {
-        const incomingOrigin = requestOrigin(request);
-        if (incomingOrigin && !originIsAllowed(incomingOrigin)) {
-            sendError(response, new BridgeRequestError(403, "origin_not_allowed", "The browser origin is not allowed for this project."), null);
-            return;
-        }
-        if (incomingOrigin) {
-            response.setHeader("Access-Control-Allow-Origin", incomingOrigin);
-            response.setHeader("Access-Control-Allow-Credentials", "true");
-            response.setHeader("Vary", "Origin");
-        }
-        response.setHeader("Access-Control-Allow-Methods", "GET,POST,OPTIONS");
-        response.setHeader("Access-Control-Allow-Headers", "Content-Type");
-        response.statusCode = 204;
-        response.end();
+    const session = createBridgeSession({
+        projectId: options.projectId,
+        origin: options.origin,
+        allowedOrigins: options.allowedOrigins,
+        commandTimeoutMs: options.commandTimeoutMs,
+        clock: options.clock,
+        tokenFactory: options.tokenFactory ?? (() => randomBytes(32).toString("base64url")),
+        idFactory: options.idFactory ?? randomUUID,
+    });
+    const browserOrigin = (request) => {
+        requireLoopback(request, "loopback_only", "The browser bridge accepts loopback connections only.");
+        return session.authorizeOrigin(requestOrigin(request));
     };
-    const handleHealth = (request, response, url) => {
-        if (!loopbackAddress(request.socket.remoteAddress)) {
-            throw new BridgeRequestError(403, "loopback_only", "The browser bridge accepts loopback connections only.");
-        }
-        const incomingOrigin = requestOrigin(request);
-        if (!originIsAllowed(incomingOrigin)) {
-            throw new BridgeRequestError(403, "origin_not_allowed", "The browser origin is not allowed for this project.");
-        }
-        parseProjectId(url.searchParams.get("projectId"), options.projectId);
-        sendJson(response, 200, {
-            protocolVersion: AGENT_PROTOCOL_VERSION,
-            projectId: options.projectId,
-            origin: incomingOrigin,
-            status: getStatus(),
-            sessionRequired: true,
-            pageUrl: lastPageUrl,
-        }, incomingOrigin);
+    const pairedBrowser = (request, sessionToken) => {
+        requireLoopback(request, "loopback_only", "The browser bridge accepts loopback connections only.");
+        return session.authorizeBrowser(requestOrigin(request), sessionToken);
     };
     const readPairRequest = async (request) => {
-        if (!loopbackAddress(request.socket.remoteAddress)) {
-            throw new BridgeRequestError(403, "loopback_only", "The browser bridge accepts loopback connections only.");
-        }
-        const incomingOrigin = requestOrigin(request);
-        if (!originIsAllowed(incomingOrigin)) {
-            throw new BridgeRequestError(403, "origin_not_allowed", "The browser origin is not allowed for this project.");
-        }
+        const origin = browserOrigin(request);
         const body = await readJsonBody(request);
-        parseProjectId(typeof body.projectId === "string" ? body.projectId : null, options.projectId);
-        const requestedOrigin = canonicalOrigin(body.origin);
-        if (!requestedOrigin || requestedOrigin !== incomingOrigin) {
+        session.assertProject(body.projectId);
+        if (canonicalOrigin(body.origin) !== origin) {
             throw new BridgeRequestError(403, "origin_mismatch", "Pairing requires an explicitly configured project origin.");
         }
-        let requestedPageUrl;
-        if (body.pageUrl !== undefined) {
-            if (typeof body.pageUrl !== "string" || body.pageUrl.length === 0 || body.pageUrl.length > AGENT_PROTOCOL_LIMITS.routeUrl
-                || !isSameOriginRoute({ url: body.pageUrl }, requestedOrigin)) {
-                throw new BridgeRequestError(400, "invalid_page_url", "pageUrl must be a bounded same-origin URL.");
-            }
-            requestedPageUrl = new URL(body.pageUrl, requestedOrigin).href;
+        if (body.pageUrl !== undefined && typeof body.pageUrl !== "string") {
+            throw new BridgeRequestError(400, "invalid_page_url", "pageUrl must be a bounded same-origin URL.");
         }
-        return { body, incomingOrigin, requestedPageUrl };
+        return { origin, ...(body.pageUrl === undefined ? {} : { pageUrl: body.pageUrl }), body };
     };
-    const handlePair = async (request, response) => {
-        const { body, incomingOrigin, requestedPageUrl } = await readPairRequest(request);
-        if (sessionToken) {
-            if (body.sessionToken !== sessionToken) {
-                throw new BridgeRequestError(409, "already_paired", "A browser is already paired with this project.");
-            }
-            lastPageUrl = requestedPageUrl ?? lastPageUrl;
-            const existing = {
-                protocolVersion: AGENT_PROTOCOL_VERSION,
-                projectId: options.projectId,
-                origin: pairedOrigin,
-                sessionToken,
-                ...(lastPageUrl === null ? {} : { pageUrl: lastPageUrl }),
-                status: getStatus(),
-            };
-            sendJson(response, 200, existing, incomingOrigin);
-            return;
-        }
-        sessionToken = tokenFactory();
-        if (!sessionToken || sessionToken.length > AGENT_PROTOCOL_LIMITS.sessionToken) {
-            throw new Error("tokenFactory returned an invalid session token");
-        }
-        pairedOrigin = incomingOrigin;
-        lastPageUrl = requestedPageUrl ?? null;
-        const connected = { type: "connected", status: getStatus() };
-        broadcast(connected);
-        const result = {
-            protocolVersion: AGENT_PROTOCOL_VERSION,
-            projectId: options.projectId,
-            origin: pairedOrigin,
-            sessionToken,
-            ...(lastPageUrl === null ? {} : { pageUrl: lastPageUrl }),
-            status: getStatus(),
-        };
-        sendJson(response, 200, result, incomingOrigin);
-        broadcastStatus();
-    };
-    const handleTakeover = async (request, response) => {
-        const { incomingOrigin, requestedPageUrl } = await readPairRequest(request);
-        // Takeover is intentionally separate from normal pairing. The caller has
-        // made an explicit UI choice to revoke the existing browser session.
-        if (sessionToken)
-            disconnectBrowser(sessionToken);
-        const pairing = pairBrowser(options.projectId, incomingOrigin, requestedPageUrl);
-        sendJson(response, 200, pairing, incomingOrigin);
-    };
-    const handleEvents = (request, response, url) => {
-        parseProjectId(url.searchParams.get("projectId"), options.projectId);
-        const incomingOrigin = requireBrowserRequest(request, url);
-        response.statusCode = 200;
-        response.setHeader("Content-Type", "text/event-stream; charset=utf-8");
-        response.setHeader("Cache-Control", "no-cache, no-store");
-        response.setHeader("Connection", "keep-alive");
-        response.setHeader("X-Accel-Buffering", "no");
-        response.setHeader("Access-Control-Allow-Origin", incomingOrigin);
-        response.setHeader("Access-Control-Allow-Credentials", "true");
-        response.setHeader("Vary", "Origin");
-        response.flushHeaders();
-        sseClients.add(response);
-        const initial = { type: "status", status: getStatus() };
-        writeSse(response, createEnvelope(options.projectId, sessionToken, initial));
-        const closeClient = () => {
-            sseClients.delete(response);
-        };
-        request.once("close", closeClient);
-        response.once("close", closeClient);
-    };
-    const handleStatus = (request, response, url) => {
-        parseProjectId(url.searchParams.get("projectId"), options.projectId);
-        const incomingOrigin = requireBrowserRequest(request, url);
-        sendJson(response, 200, getStatus(), incomingOrigin);
-    };
-    const handlePrompt = async (request, response) => {
-        const body = await readJsonBody(request, MAX_PROMPT_BODY_BYTES);
-        const incomingOrigin = requireBrowserRequest(request, new URL("http://bridge.invalid"), body.sessionToken);
-        parseProjectId(typeof body.projectId === "string" ? body.projectId : null, options.projectId);
-        if (typeof body.prompt !== "string" || body.prompt.length === 0 || body.prompt.length > AGENT_PROTOCOL_LIMITS.prompt) {
-            throw new BridgeRequestError(400, "invalid_prompt", "prompt must be a bounded non-empty string");
-        }
-        if (body.changeRevision !== undefined
-            && (!Number.isSafeInteger(body.changeRevision) || body.changeRevision < 0)) {
-            throw new BridgeRequestError(400, "invalid_revision", "changeRevision must be a non-negative safe integer");
-        }
-        if (body.clientDispatchId !== undefined
-            && (typeof body.clientDispatchId !== "string"
-                || body.clientDispatchId.length === 0
-                || body.clientDispatchId.length > AGENT_PROTOCOL_LIMITS.clientDispatchId)) {
-            throw new BridgeRequestError(400, "invalid_dispatch_id", "clientDispatchId must be a bounded non-empty string");
-        }
-        const attachments = parseSketchAttachments(body.attachments);
-        if (!listener) {
-            throw new BridgeRequestError(409, "listener_unavailable", "The agent has not opened a listening call.");
-        }
-        if (currentRequest) {
-            throw new BridgeRequestError(409, "request_in_flight", "Another Nudge request is still in flight.");
-        }
-        const prompt = {
-            requestId: idFactory(),
-            projectId: options.projectId,
-            prompt: body.prompt,
-            ...(body.changeRevision === undefined ? {} : { changeRevision: body.changeRevision }),
-            ...(body.clientDispatchId === undefined ? {} : { clientDispatchId: body.clientDispatchId }),
-            ...(attachments.length === 0 ? {} : { sketches: attachments.map(({ data: _data, ...metadata }) => metadata) }),
-        };
-        const delivered = {
-            ...prompt,
-            ...(attachments.length === 0 ? {} : { attachments }),
-        };
-        const pending = listener;
-        listener = null;
-        if (pending.abortHandler && pending.signal)
-            pending.signal.removeEventListener("abort", pending.abortHandler);
-        currentRequest = { ...prompt, status: "working" };
-        pending.resolve(delivered);
-        const result = { request: prompt, status: "working" };
-        sendJson(response, 202, result, incomingOrigin);
-        broadcastStatus();
-    };
-    const handleCanvasAcknowledgement = async (request, response) => {
-        const body = await readJsonBody(request);
-        const url = new URL("http://bridge.invalid");
-        const incomingOrigin = requireBrowserRequest(request, url, body.sessionToken);
-        parseProjectId(typeof body.projectId === "string" ? body.projectId : null, options.projectId);
-        if (!pendingCanvas)
-            throw new BridgeRequestError(409, "no_command", "No Canvas command is awaiting an acknowledgement.");
-        if (typeof body.commandId !== "string" || body.commandId !== pendingCanvas.command.commandId) {
-            throw new BridgeRequestError(409, "unknown_command", "The Canvas command is no longer awaiting an acknowledgement.");
-        }
-        if (typeof body.ok !== "boolean")
-            throw new BridgeRequestError(400, "invalid_acknowledgement", "ok must be a boolean");
-        // Acknowledgement payloads flow back to the agent verbatim, so every
-        // optional field is validated before it is accepted into the result.
-        if (body.state !== undefined && !isCanvasState(body.state)) {
-            throw new BridgeRequestError(400, "invalid_acknowledgement", "state must be a valid Canvas state.");
-        }
-        if (body.group !== undefined && !isCanvasGroup(body.group)) {
-            throw new BridgeRequestError(400, "invalid_acknowledgement", "group must be a valid Canvas group.");
-        }
-        if (body.error !== undefined) {
-            const error = body.error;
-            if (typeof error !== "object" || error === null
-                || typeof error.code !== "string" || typeof error.message !== "string") {
-                throw new BridgeRequestError(400, "invalid_acknowledgement", "error must include string code and message fields.");
-            }
-        }
-        const acknowledgement = {
-            commandId: body.commandId,
-            ok: body.ok,
-            ...(body.state === undefined ? {} : { state: body.state }),
-            ...(body.group === undefined ? {} : { group: body.group }),
-            ...(body.error === undefined ? {} : { error: body.error }),
-        };
-        if (acknowledgement.ok && acknowledgement.error) {
-            throw new BridgeRequestError(400, "invalid_acknowledgement", "A successful acknowledgement cannot include an error.");
-        }
-        const pendingCommand = pendingCanvas;
-        pendingCanvas = null;
-        clock.clearTimeout(pendingCommand.timeout);
-        const result = {
-            commandId: acknowledgement.commandId,
-            ok: acknowledgement.ok,
-            ...(acknowledgement.state === undefined ? {} : { state: acknowledgement.state }),
-            ...(acknowledgement.group === undefined ? {} : { group: acknowledgement.group }),
-            ...(acknowledgement.error === undefined ? {} : { error: acknowledgement.error }),
-        };
-        pendingCommand.resolve(result);
-        sendJson(response, 202, { commandId: result.commandId, accepted: true }, incomingOrigin);
-    };
-    const handleDisconnect = async (request, response) => {
-        const body = await readJsonBody(request);
-        const incomingOrigin = requireBrowserRequest(request, new URL("http://bridge.invalid"), body.sessionToken);
-        disconnectBrowser(body.sessionToken);
-        sendJson(response, 200, { disconnected: true }, incomingOrigin);
-    };
-    const requireAgentControl = (request, bodyAgentId) => {
-        if (!agentControlToken || !loopbackAddress(request.socket.remoteAddress)) {
+    const requireAgentControl = (request) => {
+        if (!agentControlToken) {
             throw new BridgeRequestError(403, "agent_control_unavailable", "Private agent control is unavailable.");
         }
+        requireLoopback(request, "agent_control_unavailable", "Private agent control is unavailable.");
         if (headerValue(request, "authorization") !== `Bearer ${agentControlToken}`) {
             throw new BridgeRequestError(401, "invalid_agent_credential", "The agent control credential is invalid.");
         }
-        if (bodyAgentId === undefined)
-            return null;
-        if (typeof bodyAgentId !== "string" || bodyAgentId.length === 0 || bodyAgentId.length > 256) {
-            throw new BridgeRequestError(400, "invalid_agent_id", "agentId must be a bounded non-empty string.");
-        }
-        return bodyAgentId;
     };
-    const requireAgentOwner = (request, body) => {
-        const agentId = requireAgentControl(request, body.agentId);
-        if (!agentId || agentOwner !== agentId) {
-            throw new BridgeRequestError(409, "agent_not_owner", "This MCP adapter does not own the project session.");
-        }
-        agentOwnerSeenAt = clock.now();
-        scheduleAgentOwnerExpiry();
-        return agentId;
-    };
-    const releaseAgentOwner = (reason) => {
-        if (agentOwnerExpiry !== null)
-            clock.clearTimeout(agentOwnerExpiry);
-        agentOwnerExpiry = null;
-        agentOwner = null;
-        agentClientName = undefined;
-        agentOwnerSeenAt = 0;
-        cancelListener(reason);
-        if (currentRequest?.status === "working") {
-            currentRequest = { ...currentRequest, status: "interrupted", error: reason };
-            broadcastStatus();
-        }
-        if (pendingCanvas) {
-            const pendingCommand = pendingCanvas;
-            pendingCanvas = null;
-            clock.clearTimeout(pendingCommand.timeout);
-            pendingCommand.resolve({
-                commandId: pendingCommand.command.commandId,
-                ok: false,
-                error: { code: "agent_released", message: reason },
-            });
-        }
-        broadcastStatus();
-    };
-    const scheduleAgentOwnerExpiry = () => {
-        if (agentOwnerExpiry !== null)
-            clock.clearTimeout(agentOwnerExpiry);
-        const expectedOwner = agentOwner;
-        if (!expectedOwner) {
-            agentOwnerExpiry = null;
-            return;
-        }
-        const expireIfStale = () => {
-            agentOwnerExpiry = null;
-            if (agentOwner !== expectedOwner)
-                return;
-            const remaining = AGENT_CLAIM_TIMEOUT_MS - (clock.now() - agentOwnerSeenAt);
-            if (remaining > 0) {
-                agentOwnerExpiry = clock.setTimeout(expireIfStale, remaining);
-                return;
-            }
-            releaseAgentOwner("The MCP adapter claim expired.");
-        };
-        agentOwnerExpiry = clock.setTimeout(expireIfStale, AGENT_CLAIM_TIMEOUT_MS);
-    };
-    const handleAgentClaim = async (request, response) => {
+    /** Authenticates the adapter before reading its body, then confirms it owns the session. */
+    const readAgentRequest = async (request) => {
+        requireAgentControl(request);
         const body = await readJsonBody(request);
-        const agentId = requireAgentControl(request, body.agentId);
-        if (!agentId)
-            throw new BridgeRequestError(400, "invalid_agent_id", "agentId is required.");
-        if (agentOwner && agentOwner !== agentId && clock.now() - agentOwnerSeenAt <= AGENT_CLAIM_TIMEOUT_MS) {
-            throw new BridgeRequestError(409, "session_claimed", "Another MCP adapter owns this project session.");
-        }
-        if (agentOwner && agentOwner !== agentId)
-            releaseAgentOwner("The previous MCP adapter claim expired.");
-        agentOwner = agentId;
-        agentOwnerSeenAt = clock.now();
-        scheduleAgentOwnerExpiry();
-        sendJson(response, 200, { claimed: true }, null);
-    };
-    const handleAgentRelease = async (request, response) => {
-        const body = await readJsonBody(request);
-        const agentId = requireAgentOwner(request, body);
-        releaseAgentOwner(`Agent ${agentId} released the project session.`);
-        sendJson(response, 200, { released: true }, null);
-    };
-    const handleAgentListen = async (request, response) => {
-        const body = await readJsonBody(request);
-        requireAgentOwner(request, body);
-        const abort = new AbortController();
-        response.once("close", () => abort.abort());
-        const clientName = typeof body.agentClientName === "string" ? body.agentClientName.trim().slice(0, 120) : undefined;
-        const prompt = await waitForPrompt(abort.signal, undefined, clientName);
-        sendJson(response, 200, prompt, null);
-    };
-    const handleAgentReportStatus = async (request, response) => {
-        const body = await readJsonBody(request);
-        requireAgentOwner(request, body);
-        if (!isAgentStatusUpdate(body.update)) {
-            throw new BridgeRequestError(400, "invalid_status", "update must be a valid agent status update.");
-        }
-        updateRequestStatus(body.update);
-        sendJson(response, 200, getStatus(), null);
-    };
-    const handleAgentActivity = async (request, response) => {
-        const body = await readJsonBody(request);
-        requireAgentOwner(request, body);
-        if (!isAgentActivity(body.activity))
-            throw new BridgeRequestError(400, "invalid_activity", "activity must identify a workspace-relative source file.");
-        reportActivity(body.activity);
-        sendJson(response, 200, { accepted: true }, null);
-    };
-    const handleAgentCanvas = async (request, response) => {
-        const body = await readJsonBody(request);
-        requireAgentOwner(request, body);
-        if (!isCanvasCommand(body.command)) {
-            throw new BridgeRequestError(400, "invalid_canvas_command", "command must be a valid Canvas command.");
-        }
-        sendJson(response, 200, await dispatchCanvasCommand(body.command), null);
-    };
-    const httpServer = createServer((request, response) => {
-        void (async () => {
-            const url = new URL(request.url ?? "/", `http://${host}:${port}`);
-            if (request.method === "GET" && url.pathname === AGENT_CONTROL_ENDPOINTS.health) {
-                requireAgentControl(request);
-                sendJson(response, 200, { projectId: options.projectId, available: true, claimed: agentOwner !== null, status: getStatus() }, null);
-                return;
-            }
-            if (request.method === "POST" && url.pathname === AGENT_CONTROL_ENDPOINTS.claim) {
-                await handleAgentClaim(request, response);
-                return;
-            }
-            if (request.method === "POST" && url.pathname === AGENT_CONTROL_ENDPOINTS.release) {
-                await handleAgentRelease(request, response);
-                return;
+        session.confirmAgent(decodeAgentId(body.agentId));
+        return body;
+    };
+    const routes = new Map([
+        route("GET", BRIDGE_ENDPOINTS.health, (request, response, url) => {
+            const origin = browserOrigin(request);
+            session.assertProject(url.searchParams.get("projectId"));
+            const status = session.getStatus();
+            sendJson(response, 200, {
+                protocolVersion: AGENT_PROTOCOL_VERSION,
+                projectId: session.projectId,
+                origin,
+                status,
+                sessionRequired: true,
+                pageUrl: status.pageUrl ?? null,
+            }, origin);
+        }),
+        route("POST", BRIDGE_ENDPOINTS.pair, async (request, response) => {
+            const { origin, pageUrl, body } = await readPairRequest(request);
+            sendJson(response, 200, session.pairBrowser(origin, pageUrl, optionalString(body.sessionToken)), origin);
+        }),
+        route("POST", BRIDGE_ENDPOINTS.takeover, async (request, response) => {
+            const { origin, pageUrl } = await readPairRequest(request);
+            sendJson(response, 200, session.takeOver(origin, pageUrl), origin);
+        }),
+        route("GET", BRIDGE_ENDPOINTS.events, (request, response, url) => {
+            session.assertProject(url.searchParams.get("projectId"));
+            const { origin } = pairedBrowser(request, url.searchParams.get("sessionToken"));
+            response.statusCode = 200;
+            response.setHeader("Content-Type", "text/event-stream; charset=utf-8");
+            response.setHeader("Cache-Control", "no-cache, no-store");
+            response.setHeader("Connection", "keep-alive");
+            response.setHeader("X-Accel-Buffering", "no");
+            setCors(response, origin);
+            response.flushHeaders();
+            const detach = session.attachStream({
+                send: (envelope) => writeSse(response, envelope),
+                end: () => response.end(),
+            });
+            request.once("close", detach);
+            response.once("close", detach);
+        }),
+        route("GET", BRIDGE_ENDPOINTS.status, (request, response, url) => {
+            session.assertProject(url.searchParams.get("projectId"));
+            const { origin } = pairedBrowser(request, url.searchParams.get("sessionToken"));
+            sendJson(response, 200, session.getStatus(), origin);
+        }),
+        route("POST", BRIDGE_ENDPOINTS.prompt, async (request, response) => {
+            const body = await readJsonBody(request, MAX_PROMPT_BODY_BYTES);
+            const { origin } = pairedBrowser(request, optionalString(body.sessionToken));
+            session.assertProject(body.projectId);
+            sendJson(response, 202, session.dispatchPrompt(decodePromptDispatch(body)), origin);
+        }),
+        route("POST", BRIDGE_ENDPOINTS.canvasAcknowledgement, async (request, response) => {
+            const body = await readJsonBody(request);
+            const { origin } = pairedBrowser(request, optionalString(body.sessionToken));
+            session.assertProject(body.projectId);
+            // Acknowledgement payloads flow back to the agent verbatim.
+            const { projectId: _projectId, sessionToken: _sessionToken, ...result } = body;
+            if (!isCanvasCommandResult(result)) {
+                throw new BridgeRequestError(400, "invalid_acknowledgement", "The acknowledgement is not a valid Canvas command result.");
             }
-            if (request.method === "POST" && url.pathname === AGENT_CONTROL_ENDPOINTS.heartbeat) {
-                const body = await readJsonBody(request);
-                requireAgentOwner(request, body);
-                sendJson(response, 200, { alive: true }, null);
-                return;
+            session.acknowledgeCanvas(result);
+            sendJson(response, 202, { commandId: result.commandId, accepted: true }, origin);
+        }),
+        route("POST", BRIDGE_ENDPOINTS.disconnect, async (request, response) => {
+            const body = await readJsonBody(request);
+            const grant = pairedBrowser(request, optionalString(body.sessionToken));
+            session.disconnectBrowser(grant.sessionToken);
+            sendJson(response, 200, { disconnected: true }, grant.origin);
+        }),
+        route("GET", AGENT_CONTROL_ENDPOINTS.health, (request, response) => {
+            requireAgentControl(request);
+            sendJson(response, 200, {
+                projectId: session.projectId,
+                available: true,
+                claimed: session.agentClaimed,
+                status: session.getStatus(),
+            }, null);
+        }),
+        route("POST", AGENT_CONTROL_ENDPOINTS.claim, async (request, response) => {
+            requireAgentControl(request);
+            const agentId = decodeAgentId((await readJsonBody(request)).agentId);
+            if (!agentId)
+                throw new BridgeRequestError(400, "invalid_agent_id", "agentId is required.");
+            session.claimAgent(agentId);
+            sendJson(response, 200, { claimed: true }, null);
+        }),
+        route("POST", AGENT_CONTROL_ENDPOINTS.release, async (request, response) => {
+            requireAgentControl(request);
+            session.releaseAgent(decodeAgentId((await readJsonBody(request)).agentId));
+            sendJson(response, 200, { released: true }, null);
+        }),
+        route("POST", AGENT_CONTROL_ENDPOINTS.heartbeat, async (request, response) => {
+            await readAgentRequest(request);
+            sendJson(response, 200, { alive: true }, null);
+        }),
+        route("POST", AGENT_CONTROL_ENDPOINTS.request, async (request, response) => {
+            const body = await readAgentRequest(request);
+            if (typeof body.requestId !== "string" || !body.requestId || body.requestId.length > AGENT_PROTOCOL_LIMITS.requestId) {
+                throw new BridgeRequestError(400, "invalid_request_id", "requestId must be a bounded non-empty string.");
             }
-            if (request.method === "POST" && url.pathname === AGENT_CONTROL_ENDPOINTS.listen) {
-                await handleAgentListen(request, response);
-                return;
+            sendJson(response, 200, session.getRequest(body.requestId), null);
+        }),
+        route("POST", AGENT_CONTROL_ENDPOINTS.listen, async (request, response) => {
+            const body = await readAgentRequest(request);
+            const abort = new AbortController();
+            response.once("close", () => abort.abort());
+            const prompt = await session.waitForPrompt({
+                signal: abort.signal,
+                agentClientName: optionalString(body.agentClientName),
+            });
+            sendJson(response, 200, prompt, null);
+        }),
+        route("GET", AGENT_CONTROL_ENDPOINTS.status, (request, response, url) => {
+            requireAgentControl(request);
+            session.confirmAgent(decodeAgentId(url.searchParams.get("agentId")));
+            sendJson(response, 200, session.getStatus(), null);
+        }),
+        route("POST", AGENT_CONTROL_ENDPOINTS.reportStatus, async (request, response) => {
+            const { update } = await readAgentRequest(request);
+            if (!isAgentStatusUpdate(update)) {
+                throw new BridgeRequestError(400, "invalid_status", "update must be a valid agent status update.");
             }
-            if (request.method === "GET" && url.pathname === AGENT_CONTROL_ENDPOINTS.status) {
-                const agentId = url.searchParams.get("agentId");
-                requireAgentControl(request, agentId);
-                if (agentOwner !== agentId)
-                    throw new BridgeRequestError(409, "agent_not_owner", "This MCP adapter does not own the project session.");
-                sendJson(response, 200, getStatus(), null);
-                return;
+            session.updateRequestStatus(update);
+            sendJson(response, 200, session.getStatus(), null);
+        }),
+        route("POST", AGENT_CONTROL_ENDPOINTS.activity, async (request, response) => {
+            const { activity } = await readAgentRequest(request);
+            if (!isAgentActivity(activity)) {
+                throw new BridgeRequestError(400, "invalid_activity", "activity must identify a workspace-relative source file.");
             }
-            if (request.method === "POST" && url.pathname === AGENT_CONTROL_ENDPOINTS.reportStatus) {
-                await handleAgentReportStatus(request, response);
-                return;
+            session.reportActivity(activity);
+            sendJson(response, 200, { accepted: true }, null);
+        }),
+        route("POST", AGENT_CONTROL_ENDPOINTS.canvas, async (request, response) => {
+            const { command } = await readAgentRequest(request);
+            if (!isCanvasCommand(command)) {
+                throw new BridgeRequestError(400, "invalid_canvas_command", "command must be a valid Canvas command.");
             }
-            if (request.method === "POST" && url.pathname === AGENT_CONTROL_ENDPOINTS.activity) {
-                await handleAgentActivity(request, response);
-                return;
+            sendJson(response, 200, await session.dispatchCanvasCommand(command), null);
+        }),
+    ]);
+    const handleOptions = (request, response) => {
+        const origin = requestOrigin(request);
+        if (origin) {
+            try {
+                session.authorizeOrigin(origin);
             }
-            if (request.method === "POST" && url.pathname === AGENT_CONTROL_ENDPOINTS.canvas) {
-                await handleAgentCanvas(request, response);
+            catch (error) {
+                const { statusCode, body } = errorResponse(error);
+                sendJson(response, statusCode, body, null);
                 return;
             }
+            setCors(response, origin);
+        }
+        response.setHeader("Access-Control-Allow-Methods", "GET,POST,OPTIONS");
+        response.setHeader("Access-Control-Allow-Headers", "Content-Type");
+        response.statusCode = 204;
+        response.end();
+    };
+    const httpServer = createServer((request, response) => {
+        void (async () => {
+            const url = new URL(request.url ?? "/", `http://${host}:${port}`);
             if (request.method === "OPTIONS") {
                 handleOptions(request, response);
                 return;
             }
-            if (request.method === "GET" && url.pathname === BRIDGE_ENDPOINTS.health) {
-                handleHealth(request, response, url);
-                return;
-            }
-            if (request.method === "POST" && url.pathname === BRIDGE_ENDPOINTS.pair) {
-                await handlePair(request, response);
-                return;
-            }
-            if (request.method === "POST" && url.pathname === BRIDGE_ENDPOINTS.takeover) {
-                await handleTakeover(request, response);
-                return;
-            }
-            if (request.method === "GET" && url.pathname === BRIDGE_ENDPOINTS.events) {
-                handleEvents(request, response, url);
-                return;
-            }
-            if (request.method === "GET" && url.pathname === BRIDGE_ENDPOINTS.status) {
-                handleStatus(request, response, url);
+            const handler = routes.get(`${request.method ?? ""} ${url.pathname}`);
+            if (!handler) {
+                sendJson(response, 404, { error: { code: "not_found", message: "The bridge endpoint does not exist." } }, requestOrigin(request));
                 return;
             }
-            if (request.method === "POST" && url.pathname === BRIDGE_ENDPOINTS.prompt) {
-                await handlePrompt(request, response);
-                return;
-            }
-            if (request.method === "POST" && url.pathname === BRIDGE_ENDPOINTS.canvasAcknowledgement) {
-                await handleCanvasAcknowledgement(request, response);
-                return;
-            }
-            if (request.method === "POST" && url.pathname === BRIDGE_ENDPOINTS.disconnect) {
-                await handleDisconnect(request, response);
-                return;
-            }
-            sendJson(response, 404, { error: { code: "not_found", message: "The bridge endpoint does not exist." } }, requestOrigin(request));
+            await handler(request, response, url);
         })().catch((error) => {
-            sendError(response, error, requestOrigin(request));
+            const { statusCode, body } = errorResponse(error);
+            sendJson(response, statusCode, body, requestOrigin(request));
         });
     });
+    let closed = false;
+    let currentAddress = null;
+    let startPromise = null;
+    let closePromise = null;
     const start = () => {
-        if (lifecycle === "closed")
+        if (closed)
             return Promise.reject(new Error("The browser bridge is closed."));
-        if (lifecycle === "listening" && currentAddress)
+        if (currentAddress)
             return Promise.resolve(currentAddress);
-        if (startPromise)
-            return startPromise;
-        startPromise = new Promise((resolveStart, rejectStart) => {
+        startPromise ??= new Promise((resolveStart, rejectStart) => {
             const onError = (error) => {
                 httpServer.off("listening", onListening);
                 startPromise = null;
@@ -741,7 +446,6 @@ export function createLoopbackBridge(options) {
                     rejectStart(new Error("The browser bridge did not expose a TCP address."));
                     return;
                 }
-                lifecycle = "listening";
                 currentAddress = {
                     host,
                     port: address.port,
@@ -755,217 +459,10 @@ export function createLoopbackBridge(options) {
         });
         return startPromise;
     };
-    const cancelListener = (reason = "listener_cancelled") => {
-        if (!listener)
-            return;
-        const pending = listener;
-        listener = null;
-        if (pending.abortHandler && pending.signal)
-            pending.signal.removeEventListener("abort", pending.abortHandler);
-        pending.reject(new BridgeRequestError(409, "listener_cancelled", reason));
-        broadcastStatus();
-    };
-    const waitForPrompt = (signal, _sessionId, clientName) => {
-        if (lifecycle === "closed")
-            return Promise.reject(new Error("The browser bridge is closed."));
-        if (listener)
-            return Promise.reject(new Error("A listening call is already active for this project."));
-        if (currentRequest?.status === "working")
-            return Promise.reject(new Error("A request is already in flight for this project."));
-        agentClientName = clientName?.trim().slice(0, 120) || undefined;
-        // Keep the terminal outcome visible until the agent explicitly rearms its
-        // listening call. Rearming is the lifecycle boundary for the old request.
-        if (currentRequest)
-            currentRequest = null;
-        const pendingDeferred = deferred();
-        const pending = {
-            resolve: pendingDeferred.resolve,
-            reject: pendingDeferred.reject,
-            signal,
-        };
-        if (signal) {
-            if (signal.aborted)
-                return Promise.reject(new Error("The listening call was aborted."));
-            pending.abortHandler = () => {
-                if (listener !== pending)
-                    return;
-                listener = null;
-                pending.reject(new Error("The listening call was aborted."));
-                broadcastStatus();
-            };
-            signal.addEventListener("abort", pending.abortHandler, { once: true });
-        }
-        listener = pending;
-        broadcastStatus();
-        if (sessionToken && lastPageUrl && sseClients.size === 0 && options.onControllerUnavailable) {
-            void Promise.resolve(options.onControllerUnavailable(lastPageUrl)).catch(() => undefined);
-        }
-        return pendingDeferred.promise;
-    };
-    const updateRequestStatus = (update) => {
-        if (!isAgentStatusUpdate(update))
-            throw new TypeError("Invalid agent status update");
-        if (!currentRequest || currentRequest.requestId !== update.requestId) {
-            throw new BridgeRequestError(409, "unknown_request", "The request is not in flight for this project.");
-        }
-        if (update.status === "working") {
-            currentRequest = { ...currentRequest, status: "working" };
-        }
-        else {
-            currentRequest = {
-                ...currentRequest,
-                status: update.status,
-                ...(update.summary === undefined ? {} : { summary: update.summary }),
-                ...(update.error === undefined ? {} : { error: update.error }),
-            };
-        }
-        broadcastStatus();
-    };
-    const reportActivity = (activity) => {
-        if (!isAgentActivity(activity))
-            throw new TypeError("Invalid agent activity");
-        if (!currentRequest || currentRequest.requestId !== activity.requestId || currentRequest.status !== "working") {
-            throw new BridgeRequestError(409, "inactive_request", "Activity requires the currently working request.");
-        }
-        broadcast({ type: "activity", activity });
-    };
-    const dispatchCanvasCommand = (input) => {
-        if (lifecycle === "closed")
-            return Promise.reject(new Error("The browser bridge is closed."));
-        if (!sessionToken)
-            return Promise.reject(new Error("No browser is paired with this project."));
-        if (pendingCanvas)
-            return Promise.reject(new Error("A Canvas command is already in flight."));
-        const command = { ...input, commandId: input.commandId ?? idFactory() };
-        if (!isCanvasCommand(command))
-            return Promise.reject(new TypeError("Invalid Canvas command"));
-        // The browser performs the final route check too, but rejecting here keeps
-        // the agent side from dispatching a cross-origin URL into the project.
-        const routeOrigin = pairedOrigin ?? configuredOrigin;
-        if (command.type === "present-routes" && !routeOrigin) {
-            return Promise.reject(new Error("Canvas routes require a paired browser origin"));
-        }
-        if (command.type === "present-routes" && command.routes.some((route) => !isSameOriginRoute(route, routeOrigin))) {
-            return Promise.reject(new TypeError("Canvas routes must belong to the paired project origin"));
-        }
-        if (command.type === "present-routes") {
-            try {
-                validateRoutes(command.routes, routeOrigin);
-            }
-            catch (error) {
-                return Promise.reject(error);
-            }
-        }
-        const pendingDeferred = deferred();
-        const timeout = clock.setTimeout(() => {
-            if (!pendingCanvas || pendingCanvas.command.commandId !== command.commandId)
-                return;
-            pendingCanvas = null;
-            pendingDeferred.resolve({
-                commandId: command.commandId,
-                ok: false,
-                error: { code: "ack_timeout", message: "The browser did not acknowledge the Canvas command in time." },
-            });
-        }, timeoutMs);
-        pendingCanvas = { command, resolve: pendingDeferred.resolve, timeout };
-        const event = { type: "canvas-command", command };
-        broadcast(event);
-        return pendingDeferred.promise;
-    };
-    const pairBrowser = (projectId, requestOriginValue, pageUrl) => {
-        if (projectId !== options.projectId)
-            throw new Error("Project identity does not match this bridge");
-        const requestCanonicalOrigin = canonicalOrigin(requestOriginValue);
-        if (!requestCanonicalOrigin)
-            throw new Error("Browser origin does not match this bridge");
-        // This method is the explicit host-side approval path. A bridge without
-        // an HTTP allow-list can still be paired by trusted host code, while all
-        // browser-originated requests remain closed until that approval exists.
-        if (canonicalAllowedOrigins.length > 0 && !originIsAllowed(requestCanonicalOrigin)) {
-            throw new Error("Browser origin is not in the configured allow-list");
-        }
-        let requestedPageUrl;
-        if (pageUrl !== undefined) {
-            if (!isSameOriginRoute({ url: pageUrl }, requestCanonicalOrigin)) {
-                throw new Error("Browser page URL does not match this bridge");
-            }
-            requestedPageUrl = new URL(pageUrl, requestCanonicalOrigin).href;
-        }
-        if (sessionToken)
-            throw new Error("A browser is already paired with this project");
-        const nextSessionToken = tokenFactory();
-        if (!nextSessionToken || nextSessionToken.length > AGENT_PROTOCOL_LIMITS.sessionToken) {
-            throw new Error("tokenFactory returned an invalid session token");
-        }
-        sessionToken = nextSessionToken;
-        pairedOrigin = requestCanonicalOrigin;
-        lastPageUrl = requestedPageUrl ?? null;
-        const result = {
-            protocolVersion: AGENT_PROTOCOL_VERSION,
-            projectId: options.projectId,
-            origin: requestCanonicalOrigin,
-            sessionToken,
-            ...(lastPageUrl === null ? {} : { pageUrl: lastPageUrl }),
-            status: getStatus(),
-        };
-        broadcast({ type: "connected", status: getStatus() });
-        broadcastStatus();
-        return result;
-    };
-    const disconnectBrowser = (token) => {
-        parseToken(token, sessionToken);
-        if (currentRequest?.status === "working") {
-            currentRequest = {
-                ...currentRequest,
-                status: "interrupted",
-                error: "The paired browser disconnected while the request was in flight.",
-            };
-            broadcastStatus();
-        }
-        broadcast({ type: "disconnected", reason: "browser_disconnected" });
-        sessionToken = null;
-        pairedOrigin = null;
-        for (const response of [...sseClients])
-            response.end();
-        sseClients.clear();
-        if (pendingCanvas) {
-            clock.clearTimeout(pendingCanvas.timeout);
-            pendingCanvas.resolve({
-                commandId: pendingCanvas.command.commandId,
-                ok: false,
-                error: { code: "browser_disconnected", message: "The paired browser disconnected before acknowledging the command." },
-            });
-            pendingCanvas = null;
-        }
-        lastPageUrl = null;
-    };
     const close = () => {
-        if (closePromise)
-            return closePromise;
-        lifecycle = "closed";
-        if (agentOwnerExpiry !== null)
-            clock.clearTimeout(agentOwnerExpiry);
-        agentOwnerExpiry = null;
-        agentOwner = null;
-        agentClientName = undefined;
-        agentOwnerSeenAt = 0;
-        cancelListener("bridge_closed");
-        if (pendingCanvas) {
-            clock.clearTimeout(pendingCanvas.timeout);
-            pendingCanvas.resolve({
-                commandId: pendingCanvas.command.commandId,
-                ok: false,
-                error: { code: "bridge_closed", message: "The browser bridge closed before acknowledging the command." },
-            });
-            pendingCanvas = null;
-        }
-        for (const response of [...sseClients])
-            response.end();
-        sseClients.clear();
-        sessionToken = null;
-        pairedOrigin = null;
-        lastPageUrl = null;
-        closePromise = new Promise((resolveClose) => {
+        closed = true;
+        session.close();
+        closePromise ??= new Promise((resolveClose) => {
             if (!httpServer.listening) {
                 resolveClose();
                 return;
@@ -974,25 +471,18 @@ export function createLoopbackBridge(options) {
         });
         return closePromise;
     };
-    const bridge = {
-        httpServer,
-        projectId: options.projectId,
-        origin: configuredOrigin,
-        get effectiveOrigin() { return pairedOrigin ?? configuredOrigin; },
-        get lifecycle() { return lifecycle; },
+    return {
+        projectId: session.projectId,
         get address() { return currentAddress; },
-        get sessionToken() { return sessionToken; },
-        get lastPageUrl() { return lastPageUrl; },
-        getStatus,
         start,
         close,
-        waitForPrompt,
-        cancelListener,
-        updateRequestStatus,
-        reportActivity,
-        dispatchCanvasCommand,
-        pairBrowser,
-        disconnectBrowser,
+        getStatus: session.getStatus,
+        getRequest: session.getRequest,
+        pairBrowser: (origin, pageUrl) => session.pairBrowser(origin, pageUrl),
+        disconnectBrowser: session.disconnectBrowser,
+        waitForPrompt: session.waitForPrompt,
+        updateRequestStatus: session.updateRequestStatus,
+        reportActivity: session.reportActivity,
+        dispatchCanvasCommand: session.dispatchCanvasCommand,
     };
-    return bridge;
 }