local-browser-bridge 0.1.0

package/dist/src/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Stable consumer-facing entrypoint for reusable local-browser-bridge helpers.
+ *
+ * These exports stay transport-neutral and agent-agnostic so local clients can
+ * consume the documented attach/resume and relay-failure interpretation helpers
+ * without reaching into incidental sample code paths.
+ */
+export { connectConnectionRoute, createServiceBridgeAdapter, doctorConnectionRoute, normalizeConnectionRouteName, type ConnectionCategory, type ConnectionConnectEnvelope, type ConnectionDoctorEnvelope, type ConnectionNextStep, type ConnectionOutcome, type ConnectionReason, type ConnectionRouteInput, type ConnectionRouteName, type ConnectionStatus } from "./connection-ux";
+export { chromeRelayBranchPrompt, chromeRelayRetryGuidance, chromeRelayScopeNote, interpretChromeRelayFailure, type ChromeRelayFailureCategory, type ChromeRelayFailureInterpretation } from "./chrome-relay-error-helper";
+export { interpretBrowserAttachUxFromDiagnostics, interpretBrowserAttachUxFromError, interpretBrowserAttachUxFromSession, type BrowserAttachUxInterpretation, type BrowserAttachUxState } from "./browser-attach-ux-helper";
+export { connectViaBridge, createBridgeAdapter, sessionFromBridgeResult, type BridgeAdapter, type BridgeAttachRoute, type BridgeConnectionResult, type BridgeResumeRoute, type BridgeRoute, type BridgeSessionResult } from "./reference-adapter";
+export { connectCodexViaCli, connectCodexViaHttp, normalizeCodexRoute, type CodexRouteInput, type CodexRouteName, type ConnectCodexViaCliOptions, type ConnectCodexViaHttpOptions } from "./codex";
+export { createHttpBridgeAdapter, type CreateHttpBridgeAdapterOptions, type HttpAttachEnvelope, type HttpBridgeExecutor, type HttpBridgeRequest, type HttpBridgeResponse, type HttpCapabilitiesEnvelope, type HttpDiagnosticsEnvelope, type HttpResumeEnvelope } from "./http-reference-adapter";
+export { createCliBridgeAdapter, type CliBridgeCommand, type CliBridgeCommandResult, type CliBridgeExecutor, type CreateCliBridgeAdapterOptions } from "./cli-reference-adapter";
+export { normalizeClaudeCodeRoute, prepareClaudeCodeRoute, type ClaudeCodePreparedRoute, type ClaudeCodeRouteInput, type ClaudeCodeRouteName } from "./claude-code";
+export { createMcpServer, runMcpStdioServer, SUPPORTED_PROTOCOL_VERSIONS } from "./mcp";
+export type { AttachmentSession, BrowserAttachMode, BrowserAttachReadinessState, BrowserDiagnostics, ChromeRelayErrorDetails, ChromeRelayFailureBranch, ChromeRelayFailureOperation, ChromeRelaySharedTabScope, SupportedBrowser } from "./types";

package/dist/src/index.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_PROTOCOL_VERSIONS = exports.runMcpStdioServer = exports.createMcpServer = exports.prepareClaudeCodeRoute = exports.normalizeClaudeCodeRoute = exports.createCliBridgeAdapter = exports.createHttpBridgeAdapter = exports.normalizeCodexRoute = exports.connectCodexViaHttp = exports.connectCodexViaCli = exports.sessionFromBridgeResult = exports.createBridgeAdapter = exports.connectViaBridge = exports.interpretBrowserAttachUxFromSession = exports.interpretBrowserAttachUxFromError = exports.interpretBrowserAttachUxFromDiagnostics = exports.interpretChromeRelayFailure = exports.chromeRelayScopeNote = exports.chromeRelayRetryGuidance = exports.chromeRelayBranchPrompt = exports.normalizeConnectionRouteName = exports.doctorConnectionRoute = exports.createServiceBridgeAdapter = exports.connectConnectionRoute = void 0;
+/**
+ * Stable consumer-facing entrypoint for reusable local-browser-bridge helpers.
+ *
+ * These exports stay transport-neutral and agent-agnostic so local clients can
+ * consume the documented attach/resume and relay-failure interpretation helpers
+ * without reaching into incidental sample code paths.
+ */
+var connection_ux_1 = require("./connection-ux");
+Object.defineProperty(exports, "connectConnectionRoute", { enumerable: true, get: function () { return connection_ux_1.connectConnectionRoute; } });
+Object.defineProperty(exports, "createServiceBridgeAdapter", { enumerable: true, get: function () { return connection_ux_1.createServiceBridgeAdapter; } });
+Object.defineProperty(exports, "doctorConnectionRoute", { enumerable: true, get: function () { return connection_ux_1.doctorConnectionRoute; } });
+Object.defineProperty(exports, "normalizeConnectionRouteName", { enumerable: true, get: function () { return connection_ux_1.normalizeConnectionRouteName; } });
+var chrome_relay_error_helper_1 = require("./chrome-relay-error-helper");
+Object.defineProperty(exports, "chromeRelayBranchPrompt", { enumerable: true, get: function () { return chrome_relay_error_helper_1.chromeRelayBranchPrompt; } });
+Object.defineProperty(exports, "chromeRelayRetryGuidance", { enumerable: true, get: function () { return chrome_relay_error_helper_1.chromeRelayRetryGuidance; } });
+Object.defineProperty(exports, "chromeRelayScopeNote", { enumerable: true, get: function () { return chrome_relay_error_helper_1.chromeRelayScopeNote; } });
+Object.defineProperty(exports, "interpretChromeRelayFailure", { enumerable: true, get: function () { return chrome_relay_error_helper_1.interpretChromeRelayFailure; } });
+var browser_attach_ux_helper_1 = require("./browser-attach-ux-helper");
+Object.defineProperty(exports, "interpretBrowserAttachUxFromDiagnostics", { enumerable: true, get: function () { return browser_attach_ux_helper_1.interpretBrowserAttachUxFromDiagnostics; } });
+Object.defineProperty(exports, "interpretBrowserAttachUxFromError", { enumerable: true, get: function () { return browser_attach_ux_helper_1.interpretBrowserAttachUxFromError; } });
+Object.defineProperty(exports, "interpretBrowserAttachUxFromSession", { enumerable: true, get: function () { return browser_attach_ux_helper_1.interpretBrowserAttachUxFromSession; } });
+var reference_adapter_1 = require("./reference-adapter");
+Object.defineProperty(exports, "connectViaBridge", { enumerable: true, get: function () { return reference_adapter_1.connectViaBridge; } });
+Object.defineProperty(exports, "createBridgeAdapter", { enumerable: true, get: function () { return reference_adapter_1.createBridgeAdapter; } });
+Object.defineProperty(exports, "sessionFromBridgeResult", { enumerable: true, get: function () { return reference_adapter_1.sessionFromBridgeResult; } });
+var codex_1 = require("./codex");
+Object.defineProperty(exports, "connectCodexViaCli", { enumerable: true, get: function () { return codex_1.connectCodexViaCli; } });
+Object.defineProperty(exports, "connectCodexViaHttp", { enumerable: true, get: function () { return codex_1.connectCodexViaHttp; } });
+Object.defineProperty(exports, "normalizeCodexRoute", { enumerable: true, get: function () { return codex_1.normalizeCodexRoute; } });
+var http_reference_adapter_1 = require("./http-reference-adapter");
+Object.defineProperty(exports, "createHttpBridgeAdapter", { enumerable: true, get: function () { return http_reference_adapter_1.createHttpBridgeAdapter; } });
+var cli_reference_adapter_1 = require("./cli-reference-adapter");
+Object.defineProperty(exports, "createCliBridgeAdapter", { enumerable: true, get: function () { return cli_reference_adapter_1.createCliBridgeAdapter; } });
+var claude_code_1 = require("./claude-code");
+Object.defineProperty(exports, "normalizeClaudeCodeRoute", { enumerable: true, get: function () { return claude_code_1.normalizeClaudeCodeRoute; } });
+Object.defineProperty(exports, "prepareClaudeCodeRoute", { enumerable: true, get: function () { return claude_code_1.prepareClaudeCodeRoute; } });
+var mcp_1 = require("./mcp");
+Object.defineProperty(exports, "createMcpServer", { enumerable: true, get: function () { return mcp_1.createMcpServer; } });
+Object.defineProperty(exports, "runMcpStdioServer", { enumerable: true, get: function () { return mcp_1.runMcpStdioServer; } });
+Object.defineProperty(exports, "SUPPORTED_PROTOCOL_VERSIONS", { enumerable: true, get: function () { return mcp_1.SUPPORTED_PROTOCOL_VERSIONS; } });

package/dist/src/mcp-stdio.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/mcp-stdio.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const mcp_1 = require("./mcp");
+function main() {
+    (0, mcp_1.runMcpStdioServer)();
+}
+if (require.main === module) {
+    main();
+}

package/dist/src/mcp.d.ts

@@ -0,0 +1,25 @@
+import { AttachService } from "./service/attach-service";
+declare const SUPPORTED_PROTOCOL_VERSIONS: readonly ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
+type JsonRpcId = string | number | null;
+interface JsonRpcRequest {
+    jsonrpc: "2.0";
+    id: JsonRpcId;
+    method: string;
+    params?: Record<string, unknown>;
+}
+interface JsonRpcNotification {
+    jsonrpc: "2.0";
+    method: string;
+    params?: Record<string, unknown>;
+}
+type JsonRpcMessage = JsonRpcRequest | JsonRpcNotification;
+export declare function createMcpServer(service?: Pick<AttachService, "getCapabilities" | "diagnostics" | "attach" | "resumeSession" | "listTabs">): {
+    handleMessage(message: JsonRpcMessage): Promise<unknown | undefined>;
+};
+export declare function runMcpStdioServer(options?: {
+    service?: Pick<AttachService, "getCapabilities" | "diagnostics" | "attach" | "resumeSession" | "listTabs">;
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+    error?: NodeJS.WritableStream;
+}): void;
+export { SUPPORTED_PROTOCOL_VERSIONS };

package/dist/src/mcp.js

@@ -0,0 +1,483 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_PROTOCOL_VERSIONS = void 0;
+exports.createMcpServer = createMcpServer;
+exports.runMcpStdioServer = runMcpStdioServer;
+const node_readline_1 = require("node:readline");
+const connection_ux_1 = require("./connection-ux");
+const errors_1 = require("./errors");
+const attach_service_1 = require("./service/attach-service");
+const SUPPORTED_PROTOCOL_VERSIONS = ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
+exports.SUPPORTED_PROTOCOL_VERSIONS = SUPPORTED_PROTOCOL_VERSIONS;
+const SERVER_NAME = "local-browser-bridge";
+function isRequest(message) {
+    return "id" in message;
+}
+function isJsonRpcMessage(value) {
+    return typeof value === "object" && value !== null && value.jsonrpc === "2.0"
+        && typeof value.method === "string";
+}
+function negotiateProtocolVersion(requested) {
+    if (typeof requested === "string" && SUPPORTED_PROTOCOL_VERSIONS.includes(requested)) {
+        return requested;
+    }
+    return SUPPORTED_PROTOCOL_VERSIONS[0];
+}
+function writeMessage(output, payload) {
+    output.write(JSON.stringify(payload) + "\n");
+}
+function parseRouteArguments(args) {
+    const route = (0, connection_ux_1.normalizeConnectionRouteName)(typeof args?.route === "string" ? args.route : undefined);
+    const sessionId = typeof args?.sessionId === "string" && args.sessionId.trim() ? args.sessionId.trim() : undefined;
+    return sessionId ? { route, sessionId } : { route };
+}
+function routeDescriptor(route) {
+    if (route === "safari") {
+        return { browser: "safari", attachMode: "direct" };
+    }
+    return {
+        browser: "chrome",
+        attachMode: route === "chrome-relay" ? "relay" : "direct"
+    };
+}
+function routeTruth(route, session) {
+    const runtimeActions = session
+        ? {
+            activate: session.capabilities.activate,
+            navigate: session.capabilities.navigate,
+            screenshot: session.capabilities.screenshot
+        }
+        : route.browser === "safari"
+            ? { activate: true, navigate: true, screenshot: true }
+            : { activate: false, navigate: false, screenshot: false };
+    const unsupportedRuntimeActions = Object.entries(runtimeActions)
+        .filter(([, supported]) => !supported)
+        .map(([name]) => name);
+    const readOnly = session ? session.status.state === "read-only" : route.browser === "chrome";
+    const sharedTabScoped = session
+        ? session.browser === "chrome" && session.attach.mode === "relay"
+        : route.browser === "chrome" && route.attachMode === "relay";
+    const actionable = session ? session.status.canAct : route.browser === "safari";
+    const notes = route.browser === "safari"
+        ? ["Safari is actionable in this product surface."]
+        : sharedTabScoped
+            ? [
+                "Chrome relay remains read-only in this phase.",
+                "Chrome relay only covers the currently shared tab."
+            ]
+            : ["Chrome direct remains read-only in this phase."];
+    return {
+        actionable,
+        readOnly,
+        sharedTabScoped,
+        runtimeActions,
+        unsupportedRuntimeActions,
+        notes
+    };
+}
+function toolText(payload) {
+    return JSON.stringify(payload);
+}
+function toolResult(payload, isError = false) {
+    return {
+        content: [{ type: "text", text: toolText(payload) }],
+        structuredContent: payload,
+        ...(isError ? { isError: true } : {})
+    };
+}
+function errorToolResult(code, message, details) {
+    return toolResult({
+        ok: false,
+        error: {
+            code,
+            message,
+            ...(details === undefined ? {} : { details })
+        }
+    }, true);
+}
+function summarizeTabs(browser, count) {
+    const label = browser === "safari" ? "Safari" : "Chrome direct";
+    const suffix = count === 1 ? "tab" : "tabs";
+    return `Listed ${count} ${label} ${suffix}.`;
+}
+function browserTabsRelayBlockedResult() {
+    const route = routeDescriptor("chrome-relay");
+    const reason = {
+        code: "shared_tab_scope_only",
+        message: "Chrome relay is shared-tab scoped and not browser-wide tab enumeration."
+    };
+    return toolResult({
+        tool: "browser_tabs",
+        ok: false,
+        blocked: true,
+        outcome: "unsupported",
+        status: "unsupported",
+        category: "shared-tab-scope",
+        reason,
+        summary: "Chrome relay is shared-tab scoped and does not support browser-wide tab enumeration.",
+        prompt: "Use browser_connect for the currently shared tab, or retry browser_tabs with safari or chrome-direct.",
+        truth: routeTruth(route),
+        supportedRoutes: ["safari", "chrome-direct"],
+        blockedReason: reason
+    });
+}
+function invalidParams(message, data) {
+    return {
+        code: -32602,
+        message,
+        ...(data === undefined ? {} : { data })
+    };
+}
+function requestIdOrNull(message) {
+    return message.id ?? null;
+}
+function isBrowserConnectFailure(payload) {
+    return !payload.ok || !payload.connected;
+}
+function firstDiagnosticBlocker(diagnostics, route) {
+    if (route.browser === "safari") {
+        return [
+            ...(diagnostics.preflight?.inspect.blockers ?? []),
+            ...(diagnostics.preflight?.automation.blockers ?? []),
+            ...(diagnostics.preflight?.screenshot.blockers ?? [])
+        ][0];
+    }
+    return (route.attachMode === "relay" ? diagnostics.attach?.relay?.blockers : diagnostics.attach?.direct?.blockers)?.[0];
+}
+function isUnsupportedReasonCode(code) {
+    return code === "shared_tab_scope_only"
+        || code === "unsupported_action"
+        || code === "unsupported_browser"
+        || code === "activation_unavailable"
+        || code === "navigation_unavailable"
+        || code === "screenshot_unavailable"
+        || code === "relay_transport_not_implemented";
+}
+function doctorResultFields(payload) {
+    const reason = payload.blocked ? firstDiagnosticBlocker(payload.diagnostics, payload.route) : undefined;
+    return {
+        outcome: payload.blocked ? "blocked" : "success",
+        status: payload.blocked ? "blocked" : "ready",
+        category: payload.blocked ? "route-blocked" : "route-ready",
+        ...(reason ? { reason } : {})
+    };
+}
+function connectResultFields(payload) {
+    if (payload.ok && payload.connected) {
+        return {
+            outcome: "success",
+            status: "connected",
+            category: "session-connected"
+        };
+    }
+    if (payload.blocked) {
+        const reason = firstDiagnosticBlocker(payload.diagnostics, payload.route);
+        return {
+            outcome: "blocked",
+            status: "blocked",
+            category: "connection-blocked",
+            ...(reason ? { reason } : {})
+        };
+    }
+    const reason = payload.error
+        ? {
+            code: payload.error.code ?? "unknown_error",
+            message: payload.error.message,
+            ...(payload.errorUx?.retryable === undefined ? {} : { retryable: payload.errorUx.retryable }),
+            ...(payload.errorUx?.userActionRequired === undefined ? {} : { userActionRequired: payload.errorUx.userActionRequired })
+        }
+        : undefined;
+    const unsupported = isUnsupportedReasonCode(reason?.code);
+    return {
+        outcome: unsupported ? "unsupported" : "error",
+        status: unsupported ? "unsupported" : "failed",
+        category: unsupported ? "connection-unsupported" : "connection-failed",
+        ...(reason ? { reason } : {})
+    };
+}
+function tabsSuccessResultFields() {
+    return {
+        outcome: "success",
+        status: "listed",
+        category: "tab-list"
+    };
+}
+function errorResultFields(code, message, details) {
+    const unsupported = isUnsupportedReasonCode(code);
+    const reason = {
+        code,
+        message
+    };
+    return {
+        outcome: unsupported ? "unsupported" : "error",
+        status: unsupported ? "unsupported" : "failed",
+        category: unsupported ? "tool-unsupported" : "tool-error",
+        reason,
+        ...(details === undefined ? {} : { errorDetails: details })
+    };
+}
+function createMcpServer(service = new attach_service_1.AttachService()) {
+    let initialized = false;
+    let protocolVersion = SUPPORTED_PROTOCOL_VERSIONS[0];
+    return {
+        async handleMessage(message) {
+            if (message.method === "notifications/initialized") {
+                initialized = true;
+                return undefined;
+            }
+            if (!isRequest(message)) {
+                return undefined;
+            }
+            if (message.method === "initialize") {
+                protocolVersion = negotiateProtocolVersion(message.params?.protocolVersion);
+                return {
+                    jsonrpc: "2.0",
+                    id: requestIdOrNull(message),
+                    result: {
+                        protocolVersion,
+                        capabilities: {
+                            tools: {}
+                        },
+                        serverInfo: {
+                            name: SERVER_NAME,
+                            version: "0.1.0"
+                        },
+                        instructions: "Use browser_doctor before browser_connect when route readiness is unclear. browser_tabs is available for Safari and Chrome direct. Chrome relay is read-only, limited to the currently shared tab, and does not support browser-wide tab enumeration."
+                    }
+                };
+            }
+            if (message.method === "ping") {
+                return {
+                    jsonrpc: "2.0",
+                    id: requestIdOrNull(message),
+                    result: {}
+                };
+            }
+            if (!initialized) {
+                return {
+                    jsonrpc: "2.0",
+                    id: requestIdOrNull(message),
+                    error: {
+                        code: -32002,
+                        message: "Server not initialized."
+                    }
+                };
+            }
+            if (message.method === "tools/list") {
+                return {
+                    jsonrpc: "2.0",
+                    id: requestIdOrNull(message),
+                    result: {
+                        tools: [
+                            {
+                                name: "browser_doctor",
+                                title: "Browser Doctor",
+                                description: "Check whether the requested route is ready before connect. Safari can be actionable. Chrome direct stays read-only. Chrome relay stays read-only and only covers the currently shared tab.",
+                                inputSchema: {
+                                    type: "object",
+                                    additionalProperties: false,
+                                    properties: {
+                                        route: {
+                                            type: "string",
+                                            enum: ["safari", "chrome-direct", "chrome-relay"]
+                                        },
+                                        sessionId: {
+                                            type: "string",
+                                            description: "Optional saved session ID to check resume readiness instead of a fresh attach."
+                                        }
+                                    },
+                                    required: ["route"]
+                                }
+                            },
+                            {
+                                name: "browser_tabs",
+                                title: "Browser Tabs",
+                                description: "List tabs only for browser-wide safe contexts. Safari and Chrome direct can enumerate tabs. Chrome relay returns a structured blocked result because relay is shared-tab scoped, not browser-wide.",
+                                inputSchema: {
+                                    type: "object",
+                                    additionalProperties: false,
+                                    properties: {
+                                        route: {
+                                            type: "string",
+                                            enum: ["safari", "chrome-direct", "chrome-relay"]
+                                        }
+                                    },
+                                    required: ["route"]
+                                }
+                            },
+                            {
+                                name: "browser_connect",
+                                title: "Browser Connect",
+                                description: "Attach or resume the requested route-first session. Returns explicit read-only, shared-tab scope, and unsupported runtime action metadata.",
+                                inputSchema: {
+                                    type: "object",
+                                    additionalProperties: false,
+                                    properties: {
+                                        route: {
+                                            type: "string",
+                                            enum: ["safari", "chrome-direct", "chrome-relay"]
+                                        },
+                                        sessionId: {
+                                            type: "string",
+                                            description: "Optional saved session ID to resume."
+                                        }
+                                    },
+                                    required: ["route"]
+                                }
+                            }
+                        ]
+                    }
+                };
+            }
+            if (message.method !== "tools/call") {
+                return {
+                    jsonrpc: "2.0",
+                    id: requestIdOrNull(message),
+                    error: {
+                        code: -32601,
+                        message: `Method not found: ${message.method}`
+                    }
+                };
+            }
+            const toolName = typeof message.params?.name === "string" ? message.params.name : undefined;
+            const args = typeof message.params?.arguments === "object" && message.params.arguments !== null
+                ? message.params.arguments
+                : undefined;
+            if (!toolName) {
+                return {
+                    jsonrpc: "2.0",
+                    id: requestIdOrNull(message),
+                    error: invalidParams("tools/call requires a string params.name.")
+                };
+            }
+            try {
+                if (toolName === "browser_doctor") {
+                    const route = parseRouteArguments(args);
+                    const payload = await (0, connection_ux_1.doctorConnectionRoute)(service, route);
+                    return {
+                        jsonrpc: "2.0",
+                        id: requestIdOrNull(message),
+                        result: toolResult({
+                            tool: "browser_doctor",
+                            ok: payload.ok,
+                            blocked: payload.blocked,
+                            ...doctorResultFields(payload),
+                            summary: payload.summary,
+                            prompt: payload.prompt,
+                            nextStep: payload.nextStep,
+                            truth: routeTruth(payload.route),
+                            envelope: payload
+                        })
+                    };
+                }
+                if (toolName === "browser_connect") {
+                    const route = parseRouteArguments(args);
+                    const payload = await (0, connection_ux_1.connectConnectionRoute)(service, route);
+                    return {
+                        jsonrpc: "2.0",
+                        id: requestIdOrNull(message),
+                        result: toolResult({
+                            tool: "browser_connect",
+                            ok: payload.ok,
+                            connected: payload.connected,
+                            ...connectResultFields(payload),
+                            summary: payload.summary,
+                            prompt: payload.prompt,
+                            nextStep: payload.nextStep,
+                            truth: routeTruth(payload.route, payload.session),
+                            envelope: payload
+                        }, isBrowserConnectFailure(payload))
+                    };
+                }
+                if (toolName === "browser_tabs") {
+                    const routeName = parseRouteArguments(args).route;
+                    if (routeName === "chrome-relay") {
+                        return {
+                            jsonrpc: "2.0",
+                            id: requestIdOrNull(message),
+                            result: browserTabsRelayBlockedResult()
+                        };
+                    }
+                    const route = routeDescriptor(routeName);
+                    const tabs = await service.listTabs(route.browser);
+                    return {
+                        jsonrpc: "2.0",
+                        id: requestIdOrNull(message),
+                        result: toolResult({
+                            tool: "browser_tabs",
+                            ok: true,
+                            blocked: false,
+                            ...tabsSuccessResultFields(),
+                            summary: summarizeTabs(route.browser, tabs.length),
+                            truth: routeTruth(route),
+                            count: tabs.length,
+                            tabs
+                        })
+                    };
+                }
+                return {
+                    jsonrpc: "2.0",
+                    id: requestIdOrNull(message),
+                    error: invalidParams(`Unsupported tool: ${toolName}`)
+                };
+            }
+            catch (error) {
+                const { payload } = (0, errors_1.toErrorPayload)(error);
+                return {
+                    jsonrpc: "2.0",
+                    id: requestIdOrNull(message),
+                    result: toolResult({
+                        ok: false,
+                        error: {
+                            code: payload.error.code,
+                            message: payload.error.message,
+                            ...(payload.error.details === undefined ? {} : { details: payload.error.details })
+                        },
+                        ...errorResultFields(payload.error.code, payload.error.message, payload.error.details)
+                    }, true)
+                };
+            }
+        }
+    };
+}
+function runMcpStdioServer(options = {}) {
+    const server = createMcpServer(options.service);
+    const input = options.input ?? process.stdin;
+    const output = options.output ?? process.stdout;
+    const error = options.error ?? process.stderr;
+    const reader = (0, node_readline_1.createInterface)({ input, crlfDelay: Infinity });
+    let chain = Promise.resolve();
+    reader.on("line", (line) => {
+        if (!line.trim()) {
+            return;
+        }
+        chain = chain.then(async () => {
+            try {
+                const parsed = JSON.parse(line);
+                if (!isJsonRpcMessage(parsed)) {
+                    throw new errors_1.AppError("Message must be a JSON-RPC 2.0 request or notification.", 400, "invalid_request");
+                }
+                const response = await server.handleMessage(parsed);
+                if (response !== undefined) {
+                    writeMessage(output, response);
+                }
+            }
+            catch (errorValue) {
+                writeMessage(output, {
+                    jsonrpc: "2.0",
+                    id: null,
+                    error: errorValue instanceof SyntaxError
+                        ? {
+                            code: -32700,
+                            message: "Parse error"
+                        }
+                        : errorValue instanceof errors_1.AppError
+                            ? invalidParams(errorValue.message, { code: errorValue.code })
+                            : invalidParams("Invalid JSON-RPC message.")
+                });
+            }
+        }).catch((errorValue) => {
+            error.write(`${errorValue instanceof Error ? errorValue.stack ?? errorValue.message : String(errorValue)}\n`);
+        });
+    });
+}

package/dist/src/reference-adapter.d.ts

@@ -0,0 +1,32 @@
+import { type BrowserAttachUxInterpretation } from "./browser-attach-ux-helper";
+import type { AttachmentSession, BrowserAttachMode, BrowserDiagnostics, BridgeCapabilitiesContract, ChromeRelayFailureOperation, ResumedSession, SupportedBrowser } from "./types";
+export interface BridgeAttachRoute {
+    browser: SupportedBrowser;
+    attachMode?: BrowserAttachMode;
+}
+export interface BridgeResumeRoute extends BridgeAttachRoute {
+    sessionId: string;
+}
+export type BridgeRoute = BridgeAttachRoute | BridgeResumeRoute;
+export type BridgeSessionResult = AttachmentSession | ResumedSession | {
+    session: AttachmentSession;
+};
+export interface BridgeAdapter<TCapabilities = BridgeCapabilitiesContract, TAttachResult extends BridgeSessionResult = BridgeSessionResult, TResumeResult extends BridgeSessionResult = BridgeSessionResult> {
+    getCapabilities(): Promise<TCapabilities>;
+    getDiagnostics(browser: SupportedBrowser): Promise<BrowserDiagnostics>;
+    attach(args: BridgeAttachRoute): Promise<TAttachResult>;
+    resume(sessionId: string): Promise<TResumeResult>;
+}
+export interface BridgeConnectionResult<TCapabilities, TResult extends BridgeSessionResult> {
+    capabilities: TCapabilities;
+    diagnostics: BrowserDiagnostics;
+    operation: ChromeRelayFailureOperation;
+    route: BridgeRoute;
+    routeUx: BrowserAttachUxInterpretation;
+    result: TResult;
+    session: AttachmentSession;
+    sessionUx: BrowserAttachUxInterpretation;
+}
+export declare function createBridgeAdapter<TCapabilities = BridgeCapabilitiesContract, TAttachResult extends BridgeSessionResult = BridgeSessionResult, TResumeResult extends BridgeSessionResult = BridgeSessionResult>(adapter: BridgeAdapter<TCapabilities, TAttachResult, TResumeResult>): BridgeAdapter<TCapabilities, TAttachResult, TResumeResult>;
+export declare function sessionFromBridgeResult<TResult extends BridgeSessionResult>(result: TResult): AttachmentSession;
+export declare function connectViaBridge<TCapabilities = BridgeCapabilitiesContract, TAttachResult extends BridgeSessionResult = BridgeSessionResult, TResumeResult extends BridgeSessionResult = BridgeSessionResult>(adapter: BridgeAdapter<TCapabilities, TAttachResult, TResumeResult>, route: BridgeRoute): Promise<BridgeConnectionResult<TCapabilities, TAttachResult | TResumeResult>>;

package/dist/src/reference-adapter.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBridgeAdapter = createBridgeAdapter;
+exports.sessionFromBridgeResult = sessionFromBridgeResult;
+exports.connectViaBridge = connectViaBridge;
+const browser_attach_ux_helper_1 = require("./browser-attach-ux-helper");
+function hasSession(result) {
+    return typeof result === "object" && result !== null && "session" in result;
+}
+function createBridgeAdapter(adapter) {
+    return adapter;
+}
+function sessionFromBridgeResult(result) {
+    return hasSession(result) ? result.session : result;
+}
+async function connectViaBridge(adapter, route) {
+    const capabilities = await adapter.getCapabilities();
+    const diagnostics = await adapter.getDiagnostics(route.browser);
+    const operation = "sessionId" in route ? "resumeSession" : "attach";
+    const attachMode = route.attachMode ?? (route.browser === "chrome" ? "direct" : "direct");
+    const routeUx = (0, browser_attach_ux_helper_1.interpretBrowserAttachUxFromDiagnostics)({
+        browser: route.browser,
+        attachMode,
+        diagnostics,
+        operation
+    });
+    const result = "sessionId" in route ? await adapter.resume(route.sessionId) : await adapter.attach({ browser: route.browser, attachMode });
+    const session = sessionFromBridgeResult(result);
+    return {
+        capabilities,
+        diagnostics,
+        operation,
+        route,
+        routeUx,
+        result,
+        session,
+        sessionUx: (0, browser_attach_ux_helper_1.interpretBrowserAttachUxFromSession)({
+            session,
+            operation
+        })
+    };
+}