@deadragdoll/tellymcp 0.0.1

package/dist/services/features/telegram-mcp/gateway-socket.service.js

@@ -0,0 +1,1463 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TELEGRAM_MCP_GATEWAY_SOCKET_SERVICE_NAME = void 0;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const runtime_service_1 = require("./runtime.service");
+const standalone_http_service_1 = require("./standalone-http.service");
+const auth_1 = require("./src/app/webapp/auth");
+const tmux_1 = require("./src/app/webapp/tmux");
+const gateway_loopback_1 = require("./gateway-loopback");
+const versionHandshake_1 = require("./src/shared/lib/version/versionHandshake");
+const wsLib = require("ws");
+const WebSocketServer = wsLib.WebSocketServer;
+exports.TELEGRAM_MCP_GATEWAY_SOCKET_SERVICE_NAME = "telegramMcp.gatewaySocket";
+const CLIENT_RECONNECT_DELAY_MS = 3000;
+const LIVE_REQUEST_TIMEOUT_MS = 20000;
+const TOOLS_SYNC_CHECK_INTERVAL_MS = 15000;
+const WS_HEARTBEAT_INTERVAL_MS = 10000;
+function normalizeWebSocketUrl(value, defaultPath) {
+    const url = new URL(value);
+    if (url.protocol === "https:") {
+        url.protocol = "wss:";
+    }
+    else if (url.protocol === "http:") {
+        url.protocol = "ws:";
+    }
+    if (!url.pathname || url.pathname === "/") {
+        url.pathname = defaultPath;
+    }
+    return url.toString();
+}
+function formatTmuxRelayError(error) {
+    if ((0, tmux_1.isTmuxUnavailableError)(error)) {
+        return "tmux is unavailable";
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+function computeToolsHashForDir(workspaceDir) {
+    const toolsPath = (0, node_path_1.join)((0, node_path_1.resolve)(workspaceDir), "TOOLS.md");
+    if (!(0, node_fs_1.existsSync)(toolsPath)) {
+        return null;
+    }
+    const content = (0, node_fs_1.readFileSync)(toolsPath, "utf8");
+    return (0, node_crypto_1.createHash)("sha256").update(content).digest("hex");
+}
+function normalizeGatewayBaseUrl(value) {
+    const url = new URL(value);
+    url.pathname = url.pathname.replace(/\/+$/u, "");
+    if (!url.pathname.endsWith("/gateway")) {
+        url.pathname = `${url.pathname}/gateway`.replace(/\/{2,}/gu, "/");
+    }
+    return url;
+}
+const TelegramMcpGatewaySocketService = {
+    name: exports.TELEGRAM_MCP_GATEWAY_SOCKET_SERVICE_NAME,
+    dependencies: [
+        runtime_service_1.TELEGRAM_MCP_RUNTIME_SERVICE_NAME,
+        standalone_http_service_1.TELEGRAM_MCP_STANDALONE_HTTP_SERVICE_NAME,
+    ],
+    actions: {
+        requestLiveRelay: {
+            params: {
+                clientUuid: "string",
+                localSessionId: "string",
+                requestType: {
+                    type: "enum",
+                    values: ["bootstrap", "bootstrap_validate", "view", "action"],
+                },
+                payload: { type: "object", optional: true },
+            },
+            async handler(ctx) {
+                return await this.requestLiveRelay?.({
+                    clientUuid: ctx.params.clientUuid,
+                    localSessionId: ctx.params.localSessionId,
+                    requestType: ctx.params.requestType,
+                    payload: ctx.params.payload ?? {},
+                });
+            },
+        },
+        notifyProjectMemberJoined: {
+            params: {
+                clientUuids: { type: "array", items: "string" },
+                projectUuid: "string",
+                projectName: "string",
+                memberDisplayName: { type: "string", optional: true },
+                memberTelegramUsername: { type: "string", optional: true },
+            },
+            async handler(ctx) {
+                return await this.notifyProjectMemberJoined?.(ctx.params);
+            },
+        },
+        notifyProjectMemberLeft: {
+            params: {
+                clientUuids: { type: "array", items: "string" },
+                projectUuid: "string",
+                projectName: "string",
+                memberDisplayName: { type: "string", optional: true },
+                memberTelegramUsername: { type: "string", optional: true },
+            },
+            async handler(ctx) {
+                return await this.notifyProjectMemberLeft?.(ctx.params);
+            },
+        },
+        notifyProjectDeleted: {
+            params: {
+                clientUuids: { type: "array", items: "string" },
+                projectUuid: "string",
+                projectName: "string",
+            },
+            async handler(ctx) {
+                return await this.notifyProjectDeleted?.(ctx.params);
+            },
+        },
+        notifyLiveApprovalRequest: {
+            params: {
+                clientUuid: "string",
+                payload: { type: "object" },
+            },
+            async handler(ctx) {
+                return {
+                    delivered: await this.notifyLiveApprovalRequest?.(ctx.params),
+                };
+            },
+        },
+        notifyLiveApprovalResolved: {
+            params: {
+                clientUuid: "string",
+                approved: "boolean",
+                payload: { type: "object" },
+            },
+            async handler(ctx) {
+                return {
+                    delivered: await this.notifyLiveApprovalResolved?.(ctx.params),
+                };
+            },
+        },
+        notifyDeliveryQueued: {
+            params: {
+                clientUuid: "string",
+                delivery: { type: "object" },
+            },
+            async handler(ctx) {
+                return await this.notifyDeliveryQueued?.(ctx.params);
+            },
+        },
+        notifyDeliveryStatus: {
+            params: {
+                clientUuid: "string",
+                status: { type: "object" },
+            },
+            async handler(ctx) {
+                return await this.notifyDeliveryStatus?.(ctx.params);
+            },
+        },
+    },
+    created() {
+        this.runtimeService = null;
+        this.standaloneHttpService = null;
+        this.wsServer = null;
+        this.wsClient = null;
+        this.wsReconnectTimer = null;
+        this.wsIdentityRefreshTimer = null;
+        this.wsToolsSyncTimer = null;
+        this.wsHeartbeatTimer = null;
+        this.wsAwaitingPong = false;
+        this.wsConnectionId = null;
+        this.wsHelloClientUuid = null;
+        this.wsHelloSessionToolsSnapshot = null;
+        this.wsClientHasConnectedOnce = false;
+        this.wsUpgradeHandler = null;
+        this.stopRequested = false;
+        this.connectedClients = new Map();
+        this.connectedClientsByUuid = new Map();
+        this.connectedClientToolsAlerts = new Map();
+        this.pendingLiveRequests = new Map();
+    },
+    methods: {
+        getRuntimeOrThrow() {
+            const runtimeService = this.runtimeService ??
+                this.broker.getLocalService(runtime_service_1.TELEGRAM_MCP_RUNTIME_SERVICE_NAME);
+            if (!runtimeService) {
+                throw new Error(`Local Moleculer service '${runtime_service_1.TELEGRAM_MCP_RUNTIME_SERVICE_NAME}' is unavailable`);
+            }
+            this.runtimeService = runtimeService;
+            return runtimeService.getRuntime();
+        },
+        getHttpServerOrThrow() {
+            const standaloneHttpService = this.standaloneHttpService ??
+                this.broker.getLocalService(standalone_http_service_1.TELEGRAM_MCP_STANDALONE_HTTP_SERVICE_NAME);
+            if (!standaloneHttpService?.httpServer) {
+                throw new Error(`Local Moleculer service '${standalone_http_service_1.TELEGRAM_MCP_STANDALONE_HTTP_SERVICE_NAME}' HTTP server is unavailable`);
+            }
+            this.standaloneHttpService = standaloneHttpService;
+            return standaloneHttpService.httpServer;
+        },
+        async collectSessionTools() {
+            const runtime = this.getRuntimeOrThrow();
+            const sessions = await runtime.sessionStore.listSessions();
+            const boundSessions = (await Promise.all(sessions.map(async (session) => (await runtime.bindingStore.getBinding(session.sessionId))
+                ? session
+                : null))).filter((session) => Boolean(session));
+            const sessionTools = boundSessions
+                .map((session) => {
+                const toolsHash = session.cwd
+                    ? computeToolsHashForDir(session.cwd)
+                    : null;
+                return {
+                    local_session_id: session.sessionId,
+                    ...(session.label ? { session_label: session.label } : {}),
+                    ...(toolsHash ? { tools_hash: toolsHash } : {}),
+                };
+            })
+                .sort((left, right) => left.local_session_id.localeCompare(right.local_session_id));
+            return {
+                sessionTools,
+                snapshot: JSON.stringify(sessionTools),
+            };
+        },
+        getGatewayToolsHash() {
+            return computeToolsHashForDir(process.cwd());
+        },
+        getLocalVersionInfo() {
+            return {
+                packageVersion: (0, versionHandshake_1.getTellyMcpPackageVersion)(__dirname),
+                protocolVersion: versionHandshake_1.TELLYMCP_PROTOCOL_VERSION,
+                capabilities: [...versionHandshake_1.TELLYMCP_CAPABILITIES],
+            };
+        },
+        async fetchGatewayToolsHashForClient() {
+            const runtime = this.getRuntimeOrThrow();
+            if (runtime.config.distributed.mode === "gateway" ||
+                runtime.config.distributed.mode === "both") {
+                return this.getGatewayToolsHash?.() ?? null;
+            }
+            const gatewayPublicUrl = runtime.config.distributed.gatewayPublicUrl;
+            if (!gatewayPublicUrl) {
+                return null;
+            }
+            const url = normalizeGatewayBaseUrl(gatewayPublicUrl);
+            url.pathname = `${url.pathname}/tools-md`.replace(/\/{2,}/gu, "/");
+            try {
+                const response = await fetch(url, {
+                    method: "GET",
+                    headers: {
+                        ...(runtime.config.distributed.gatewayAuthToken
+                            ? { authorization: `Bearer ${runtime.config.distributed.gatewayAuthToken}` }
+                            : {}),
+                    },
+                });
+                if (!response.ok) {
+                    const message = await response.text();
+                    throw new Error(`Gateway TOOLS.md request failed with status ${response.status}: ${message || response.statusText}`);
+                }
+                return (0, node_crypto_1.createHash)("sha256").update(await response.text()).digest("hex");
+            }
+            catch (error) {
+                runtime.logger.debug("Gateway TOOLS.md self-check skipped", {
+                    gatewayPublicUrl,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                return null;
+            }
+        },
+        async syncLocalToolsAgainstGateway(sessionId) {
+            const runtime = this.getRuntimeOrThrow();
+            const gatewayToolsHash = await this.fetchGatewayToolsHashForClient?.();
+            if (!gatewayToolsHash) {
+                return 0;
+            }
+            const sessions = sessionId
+                ? [await runtime.sessionStore.getSession(sessionId)].filter((item) => Boolean(item))
+                : await runtime.sessionStore.listSessions();
+            const boundSessions = (await Promise.all(sessions.map(async (session) => (await runtime.bindingStore.getBinding(session.sessionId))
+                ? session
+                : null))).filter((session) => Boolean(session));
+            let delivered = 0;
+            for (const session of boundSessions) {
+                const localHash = session.cwd
+                    ? computeToolsHashForDir(session.cwd)
+                    : null;
+                if (localHash === gatewayToolsHash) {
+                    continue;
+                }
+                if (session.lastSeenToolsHash?.trim() === gatewayToolsHash ||
+                    session.lastNotifiedToolsHash?.trim() === gatewayToolsHash) {
+                    continue;
+                }
+                await runtime.telegramTransport.handleToolsUpdatedEvent({
+                    local_session_id: session.sessionId,
+                    ...(session.label ? { session_label: session.label } : {}),
+                    ...(localHash ? { client_tools_hash: localHash } : {}),
+                    gateway_tools_hash: gatewayToolsHash,
+                    reason: localHash ? "outdated" : "missing",
+                    instruction: "Call refresh_tools_markdown for this session, then re-read the local TOOLS.md and apply it before continuing.",
+                });
+                delivered += 1;
+            }
+            return delivered;
+        },
+        async notifyToolsMismatchForSocket(socket, hello) {
+            const gatewayToolsHash = this.getGatewayToolsHash?.();
+            if (!gatewayToolsHash || !socket || socket.readyState !== 1) {
+                return 0;
+            }
+            const sessionTools = Array.isArray(hello.session_tools)
+                ? hello.session_tools
+                : [];
+            if (sessionTools.length === 0) {
+                return 0;
+            }
+            const alerted = this.connectedClientToolsAlerts?.get(socket) ?? new Map();
+            this.connectedClientToolsAlerts?.set(socket, alerted);
+            let delivered = 0;
+            for (const sessionTool of sessionTools) {
+                const clientToolsHash = typeof sessionTool.tools_hash === "string" && sessionTool.tools_hash.trim()
+                    ? sessionTool.tools_hash.trim()
+                    : null;
+                if (clientToolsHash === gatewayToolsHash) {
+                    alerted.delete(sessionTool.local_session_id);
+                    continue;
+                }
+                if (alerted.get(sessionTool.local_session_id) === gatewayToolsHash) {
+                    continue;
+                }
+                socket.send(JSON.stringify({
+                    type: "tools_event",
+                    payload: {
+                        local_session_id: sessionTool.local_session_id,
+                        ...(sessionTool.session_label
+                            ? { session_label: sessionTool.session_label }
+                            : {}),
+                        ...(clientToolsHash ? { client_tools_hash: clientToolsHash } : {}),
+                        gateway_tools_hash: gatewayToolsHash,
+                        reason: clientToolsHash ? "outdated" : "missing",
+                        instruction: "Call refresh_tools_markdown for this session, then re-read the local TOOLS.md and apply it before continuing.",
+                    },
+                }));
+                alerted.set(sessionTool.local_session_id, gatewayToolsHash);
+                delivered += 1;
+            }
+            return delivered;
+        },
+        async sendClientHello(socket) {
+            const runtime = this.getRuntimeOrThrow();
+            if (!runtime || !socket || socket.readyState !== 1) {
+                return;
+            }
+            const clientUuid = await runtime.maintenanceStore.getGatewayClientUuid();
+            const { sessionTools, snapshot } = await this.collectSessionTools?.() ?? {
+                sessionTools: [],
+                snapshot: "[]",
+            };
+            const versionInfo = this.getLocalVersionInfo?.() ?? {
+                packageVersion: "0.0.0-unknown",
+                protocolVersion: versionHandshake_1.TELLYMCP_PROTOCOL_VERSION,
+                capabilities: [...versionHandshake_1.TELLYMCP_CAPABILITIES],
+            };
+            const hello = {
+                type: "hello",
+                connection_id: this.wsConnectionId || (0, node_crypto_1.randomUUID)(),
+                role: "client",
+                ...(clientUuid ? { client_uuid: clientUuid } : {}),
+                ...(runtime.config.project.name
+                    ? { project_name: runtime.config.project.name }
+                    : {}),
+                ...(this.broker.nodeID ? { node_id: this.broker.nodeID } : {}),
+                package_version: versionInfo.packageVersion,
+                protocol_version: versionInfo.protocolVersion,
+                capabilities: versionInfo.capabilities,
+                ...(sessionTools.length > 0 ? { session_tools: sessionTools } : {}),
+            };
+            this.wsHelloClientUuid = clientUuid ?? null;
+            this.wsHelloSessionTools = sessionTools;
+            this.wsHelloSessionToolsSnapshot = snapshot;
+            socket.send(JSON.stringify(hello));
+        },
+        async isLocalGatewayClientUuid(clientUuid) {
+            const runtime = this.getRuntimeOrThrow();
+            const localClientUuid = await runtime.maintenanceStore.getGatewayClientUuid();
+            return Boolean(localClientUuid && localClientUuid === clientUuid);
+        },
+        async handleLocalIncomingDelivery(params) {
+            const runtime = this.getRuntimeOrThrow();
+            const localTargetSession = await runtime.sessionStore.getSession(params.delivery.target_local_session_id);
+            if (!(0, gateway_loopback_1.hasLocalTargetSession)(localTargetSession)) {
+                return false;
+            }
+            try {
+                await this.broker.call("telegramMcp.gatewayDelivery.materializeIncomingDelivery", {
+                    delivery: params.delivery,
+                }, { meta: { internal_call: true } });
+            }
+            catch (error) {
+                const result = await this.broker.call("telegramMcp.gateway.failDeliveries", {
+                    client_uuid: params.clientUuid,
+                    delivery_ids: [params.delivery.delivery_uuid],
+                    error_text: error instanceof Error ? error.message : String(error),
+                }, { meta: { internal_call: true } });
+                for (const status of Array.isArray(result.deliveries)
+                    ? result.deliveries
+                    : []) {
+                    if (!status.source_client_uuid) {
+                        continue;
+                    }
+                    const published = await this.notifyDeliveryStatus?.({
+                        clientUuid: status.source_client_uuid,
+                        status,
+                    });
+                    if (!published && (await this.isLocalGatewayClientUuid?.(status.source_client_uuid))) {
+                        await this.handleLocalDeliveryStatus?.({
+                            clientUuid: status.source_client_uuid,
+                            status,
+                        });
+                    }
+                }
+                throw error;
+            }
+            const result = await this.broker.call("telegramMcp.gateway.ackDeliveries", {
+                client_uuid: params.clientUuid,
+                delivery_ids: [params.delivery.delivery_uuid],
+            }, { meta: { internal_call: true } });
+            for (const status of Array.isArray(result.deliveries)
+                ? result.deliveries
+                : []) {
+                if (!status.source_client_uuid) {
+                    continue;
+                }
+                const published = await this.notifyDeliveryStatus?.({
+                    clientUuid: status.source_client_uuid,
+                    status,
+                });
+                if (!published && (await this.isLocalGatewayClientUuid?.(status.source_client_uuid))) {
+                    await this.handleLocalDeliveryStatus?.({
+                        clientUuid: status.source_client_uuid,
+                        status,
+                    });
+                }
+            }
+            return true;
+        },
+        async handleLocalDeliveryStatus(params) {
+            const runtime = this.getRuntimeOrThrow();
+            const notices = await runtime.maintenanceStore.listOutgoingDeliveryNotices();
+            if (!(0, gateway_loopback_1.hasOutgoingDeliveryNotice)(notices, params.status.delivery_uuid)) {
+                return false;
+            }
+            await this.broker.call("telegramMcp.gatewayDelivery.applyOutgoingDeliveryStatus", {
+                status: params.status,
+            }, { meta: { internal_call: true } });
+            return true;
+        },
+        async processLiveRequest(request) {
+            const runtime = this.getRuntimeOrThrow();
+            try {
+                if (request.request_type === "bootstrap_validate") {
+                    const payload = request.payload ?? {};
+                    const initDataRaw = typeof payload.initDataRaw === "string" ? payload.initDataRaw : "";
+                    const initDataUnsafe = payload.initDataUnsafe && typeof payload.initDataUnsafe === "object"
+                        ? payload.initDataUnsafe
+                        : null;
+                    if (!initDataRaw || !initDataUnsafe) {
+                        throw new Error("initDataRaw and initDataUnsafe are required");
+                    }
+                    const validated = (0, auth_1.validateTelegramWebAppInitData)(initDataRaw, initDataUnsafe, runtime.config.telegram.botToken, runtime.config.webapp.initDataTtlSeconds);
+                    const launchRecord = runtime.webAppLaunchRegistry.getByUserId(validated.user.id);
+                    if (!launchRecord) {
+                        throw new Error("No pending Telegram WebApp launch was found");
+                    }
+                    runtime.webAppLaunchRegistry.deleteByUserId(validated.user.id);
+                    if (launchRecord?.telegramChatId !== undefined &&
+                        launchRecord?.telegramMessageId !== undefined) {
+                        void runtime.telegramTransport
+                            .deleteMessage(launchRecord.telegramChatId, launchRecord.telegramMessageId)
+                            .catch(() => undefined);
+                    }
+                    return {
+                        type: "live_response",
+                        request_id: request.request_id,
+                        ok: true,
+                        result: {
+                            telegram_user_id: validated.user.id,
+                        },
+                    };
+                }
+                if (request.request_type === "bootstrap") {
+                    const payload = request.payload ?? {};
+                    const allowForeignBinding = payload.allowForeignBinding === true;
+                    const trustedTelegramUserId = typeof payload.telegramUserId === "number"
+                        ? payload.telegramUserId
+                        : typeof payload.telegramUserId === "string" &&
+                            payload.telegramUserId.trim()
+                            ? Number(payload.telegramUserId)
+                            : null;
+                    let telegramUserId = trustedTelegramUserId;
+                    if (telegramUserId !== null &&
+                        (!Number.isFinite(telegramUserId) || telegramUserId <= 0)) {
+                        telegramUserId = null;
+                    }
+                    if (telegramUserId === null) {
+                        const initDataRaw = typeof payload.initDataRaw === "string" ? payload.initDataRaw : "";
+                        const initDataUnsafe = payload.initDataUnsafe && typeof payload.initDataUnsafe === "object"
+                            ? payload.initDataUnsafe
+                            : null;
+                        if (!initDataRaw || !initDataUnsafe) {
+                            throw new Error("initDataRaw and initDataUnsafe are required");
+                        }
+                        const validated = (0, auth_1.validateTelegramWebAppInitData)(initDataRaw, initDataUnsafe, runtime.config.telegram.botToken, runtime.config.webapp.initDataTtlSeconds);
+                        telegramUserId = validated.user.id;
+                    }
+                    const sessionId = request.local_session_id.trim();
+                    if (!sessionId) {
+                        throw new Error("sessionId is missing for relay bootstrap");
+                    }
+                    const binding = await runtime.bindingStore.getBinding(sessionId);
+                    if (!allowForeignBinding &&
+                        (!binding || binding.telegramUserId !== telegramUserId)) {
+                        throw new Error("This Telegram user is not bound to the requested session.");
+                    }
+                    const session = await runtime.sessionStore.getSession(sessionId);
+                    return {
+                        type: "live_response",
+                        request_id: request.request_id,
+                        ok: true,
+                        result: {
+                            session_id: sessionId,
+                            session_label: session?.label ?? null,
+                            tmux_target: Boolean(session?.tmuxTarget),
+                            poll_interval_ms: runtime.config.webapp.pollIntervalMs,
+                            telegram_user_id: telegramUserId,
+                        },
+                    };
+                }
+                if (request.request_type === "view") {
+                    const sessionId = request.local_session_id.trim();
+                    const session = await runtime.sessionStore.getSession(sessionId);
+                    if (!session?.tmuxTarget) {
+                        throw new Error("tmux target is not configured for this session");
+                    }
+                    const content = await (0, tmux_1.captureVisibleTmuxPane)(runtime.config.tmux, session.tmuxTarget, runtime.config.tmux.captureLines, runtime.config.webapp.visibleScreens);
+                    return {
+                        type: "live_response",
+                        request_id: request.request_id,
+                        ok: true,
+                        result: {
+                            session_id: session.sessionId,
+                            session_label: session.label ?? null,
+                            captured_at: new Date().toISOString(),
+                            content,
+                        },
+                    };
+                }
+                if (request.request_type === "action") {
+                    const action = typeof request.payload?.action === "string"
+                        ? request.payload.action
+                        : "";
+                    if (!["up", "down", "enter", "slash", "delete", "tab", "escape"].includes(action)) {
+                        throw new Error("Unsupported action");
+                    }
+                    const sessionId = request.local_session_id.trim();
+                    const session = await runtime.sessionStore.getSession(sessionId);
+                    if (!session?.tmuxTarget) {
+                        throw new Error("tmux target is not configured for this session");
+                    }
+                    await (0, tmux_1.sendAllowedTmuxAction)(runtime.config.tmux, session.tmuxTarget, action);
+                    return {
+                        type: "live_response",
+                        request_id: request.request_id,
+                        ok: true,
+                        result: {
+                            ok: true,
+                        },
+                    };
+                }
+                throw new Error(`Unsupported live request type '${request.request_type}'`);
+            }
+            catch (error) {
+                return {
+                    type: "live_response",
+                    request_id: request.request_id,
+                    ok: false,
+                    error: formatTmuxRelayError(error),
+                };
+            }
+        },
+        async handleGatewayWsServerMessage(socket, raw) {
+            const runtime = this.getRuntimeOrThrow();
+            const parsed = JSON.parse(String(raw));
+            if (parsed.type === "hello") {
+                const hello = {
+                    type: "hello",
+                    connection_id: typeof parsed.connection_id === "string" && parsed.connection_id.trim()
+                        ? parsed.connection_id.trim()
+                        : (0, node_crypto_1.randomUUID)(),
+                    role: parsed.role === "gateway" ? "gateway" : "client",
+                    ...(typeof parsed.client_uuid === "string" && parsed.client_uuid.trim()
+                        ? { client_uuid: parsed.client_uuid.trim() }
+                        : {}),
+                    ...(typeof parsed.project_name === "string" && parsed.project_name.trim()
+                        ? { project_name: parsed.project_name.trim() }
+                        : {}),
+                    ...(typeof parsed.node_id === "string" && parsed.node_id.trim()
+                        ? { node_id: parsed.node_id.trim() }
+                        : {}),
+                    ...(typeof parsed.package_version === "string" &&
+                        parsed.package_version.trim()
+                        ? { package_version: parsed.package_version.trim() }
+                        : {}),
+                    ...(typeof parsed.protocol_version === "string" &&
+                        parsed.protocol_version.trim()
+                        ? { protocol_version: parsed.protocol_version.trim() }
+                        : {}),
+                    ...(Array.isArray(parsed.capabilities)
+                        ? {
+                            capabilities: parsed.capabilities
+                                .map((item) => typeof item === "string" && item.trim()
+                                ? item.trim()
+                                : null)
+                                .filter((item) => Boolean(item)),
+                        }
+                        : {}),
+                    ...(Array.isArray(parsed.session_tools)
+                        ? {
+                            session_tools: parsed.session_tools
+                                .map((item) => item && typeof item === "object"
+                                ? {
+                                    local_session_id: typeof item.local_session_id ===
+                                        "string" &&
+                                        item.local_session_id.trim()
+                                        ? item.local_session_id.trim()
+                                        : null,
+                                    ...(typeof item.session_label ===
+                                        "string" &&
+                                        item.session_label.trim()
+                                        ? {
+                                            session_label: item.session_label.trim(),
+                                        }
+                                        : {}),
+                                    ...(typeof item.tools_hash ===
+                                        "string" &&
+                                        item.tools_hash.trim()
+                                        ? {
+                                            tools_hash: item.tools_hash.trim(),
+                                        }
+                                        : {}),
+                                }
+                                : null)
+                                .filter((item) => Boolean(item?.local_session_id)),
+                        }
+                        : {}),
+                };
+                const previous = this.connectedClients?.get(socket);
+                if (previous?.client_uuid) {
+                    this.connectedClientsByUuid?.delete(previous.client_uuid);
+                }
+                this.connectedClients?.set(socket, hello);
+                if (hello.client_uuid) {
+                    this.connectedClientsByUuid?.set(hello.client_uuid, socket);
+                }
+                runtime.logger.info("Gateway WS hello received", hello);
+                const localVersionInfo = this.getLocalVersionInfo?.() ?? {
+                    packageVersion: "0.0.0-unknown",
+                    protocolVersion: versionHandshake_1.TELLYMCP_PROTOCOL_VERSION,
+                    capabilities: [...versionHandshake_1.TELLYMCP_CAPABILITIES],
+                };
+                const compatibility = (0, versionHandshake_1.evaluateVersionCompatibility)({
+                    gatewayPackageVersion: localVersionInfo.packageVersion,
+                    gatewayProtocolVersion: localVersionInfo.protocolVersion,
+                    ...(hello.package_version
+                        ? { clientPackageVersion: hello.package_version }
+                        : {}),
+                    ...(hello.protocol_version
+                        ? { clientProtocolVersion: hello.protocol_version }
+                        : {}),
+                });
+                const ackInstruction = compatibility.compatibility === "reject"
+                    ? "Upgrade this client before continuing. Gateway transport is blocked until protocol major versions match."
+                    : compatibility.compatibility === "warn"
+                        ? "Client and gateway versions differ. Upgrade the older side and verify TOOLS.md before continuing sensitive work."
+                        : "Version handshake passed.";
+                socket.send(JSON.stringify({
+                    type: "hello_ack",
+                    connection_id: hello.connection_id,
+                    package_version: localVersionInfo.packageVersion,
+                    protocol_version: localVersionInfo.protocolVersion,
+                    capabilities: localVersionInfo.capabilities,
+                    compatibility: compatibility.compatibility,
+                    reasons: compatibility.reasons,
+                    instruction: ackInstruction,
+                }));
+                if (compatibility.compatibility === "reject") {
+                    runtime.logger.warn("Rejecting gateway WS client due to protocol incompatibility", {
+                        clientUuid: hello.client_uuid,
+                        clientPackageVersion: hello.package_version ?? null,
+                        clientProtocolVersion: hello.protocol_version ?? null,
+                        gatewayPackageVersion: localVersionInfo.packageVersion,
+                        gatewayProtocolVersion: localVersionInfo.protocolVersion,
+                        reasons: compatibility.reasons,
+                    });
+                    setTimeout(() => {
+                        try {
+                            socket.close?.(4002, "version_incompatible");
+                        }
+                        catch {
+                            socket.terminate?.();
+                        }
+                    }, 50);
+                    return;
+                }
+                await this.notifyToolsMismatchForSocket?.(socket, hello);
+                if (hello.client_uuid) {
+                    const queued = await this.broker.call("telegramMcp.gateway.pollDeliveries", {
+                        client_uuid: hello.client_uuid,
+                        limit: 50,
+                    }, { meta: { internal_call: true } });
+                    for (const delivery of Array.isArray(queued.deliveries)
+                        ? queued.deliveries
+                        : []) {
+                        socket.send(JSON.stringify({
+                            type: "delivery_event",
+                            event: "incoming_delivery",
+                            payload: delivery,
+                        }));
+                    }
+                    const statuses = await this.broker.call("telegramMcp.gateway.listSenderDeliveryStatuses", {
+                        client_uuid: hello.client_uuid,
+                        limit: 100,
+                    }, { meta: { internal_call: true } });
+                    for (const status of Array.isArray(statuses.deliveries)
+                        ? statuses.deliveries
+                        : []) {
+                        socket.send(JSON.stringify({
+                            type: "delivery_status_event",
+                            payload: status,
+                        }));
+                    }
+                }
+                return;
+            }
+            if (parsed.type === "heartbeat_ping") {
+                socket.send(JSON.stringify({
+                    type: "heartbeat_pong",
+                    ts: typeof parsed.ts === "string" && parsed.ts.trim()
+                        ? parsed.ts.trim()
+                        : new Date().toISOString(),
+                }));
+                return;
+            }
+            if (parsed.type === "live_response") {
+                const requestId = typeof parsed.request_id === "string" ? parsed.request_id.trim() : "";
+                if (!requestId) {
+                    return;
+                }
+                const pending = this.pendingLiveRequests?.get(requestId);
+                if (!pending) {
+                    return;
+                }
+                clearTimeout(pending.timeout);
+                this.pendingLiveRequests?.delete(requestId);
+                if (parsed.ok === true) {
+                    pending.resolve(parsed.result);
+                }
+                else {
+                    pending.reject(new Error(typeof parsed.error === "string" && parsed.error.trim()
+                        ? parsed.error
+                        : "Live relay request failed"));
+                }
+                return;
+            }
+            if (parsed.type === "delivery_ack" || parsed.type === "delivery_fail") {
+                const hello = this.connectedClients?.get(socket);
+                const clientUuid = hello?.client_uuid?.trim();
+                if (!clientUuid) {
+                    throw new Error("Gateway WS delivery update requires hello client_uuid");
+                }
+                const deliveryIds = Array.isArray(parsed.delivery_ids)
+                    ? parsed.delivery_ids
+                        .map((item) => typeof item === "string" && item.trim() ? item.trim() : null)
+                        .filter((item) => Boolean(item))
+                    : [];
+                if (deliveryIds.length === 0) {
+                    return;
+                }
+                const result = await this.broker.call(parsed.type === "delivery_ack"
+                    ? "telegramMcp.gateway.ackDeliveries"
+                    : "telegramMcp.gateway.failDeliveries", {
+                    client_uuid: clientUuid,
+                    delivery_ids: deliveryIds,
+                    ...(parsed.type === "delivery_fail" &&
+                        typeof parsed.error_text === "string" &&
+                        parsed.error_text.trim()
+                        ? { error_text: parsed.error_text.trim() }
+                        : {}),
+                }, { meta: { internal_call: true } });
+                for (const status of Array.isArray(result.deliveries)
+                    ? result.deliveries
+                    : []) {
+                    if (!status.source_client_uuid) {
+                        continue;
+                    }
+                    const publishResult = await this.broker.call("telegramMcp.gatewayRmq.publishDeliveryStatus", {
+                        clientUuid: status.source_client_uuid,
+                        status,
+                    }, { meta: { internal_call: true } });
+                    if (!publishResult?.published) {
+                        await this.notifyDeliveryStatus?.({
+                            clientUuid: status.source_client_uuid,
+                            status,
+                        });
+                    }
+                }
+            }
+        },
+        async handleGatewayWsClientMessage(raw) {
+            const runtime = this.getRuntimeOrThrow();
+            const parsed = JSON.parse(String(raw));
+            if (parsed.type === "hello_ack") {
+                const compatibility = parsed.compatibility === "warn" || parsed.compatibility === "reject"
+                    ? parsed.compatibility
+                    : "ok";
+                const gatewayPackageVersion = typeof parsed.package_version === "string" && parsed.package_version.trim()
+                    ? parsed.package_version.trim()
+                    : "0.0.0-unknown";
+                const gatewayProtocolVersion = typeof parsed.protocol_version === "string" && parsed.protocol_version.trim()
+                    ? parsed.protocol_version.trim()
+                    : versionHandshake_1.TELLYMCP_PROTOCOL_VERSION;
+                const reasons = Array.isArray(parsed.reasons)
+                    ? parsed.reasons
+                        .map((item) => typeof item === "string" && item.trim() ? item.trim() : null)
+                        .filter((item) => Boolean(item))
+                    : [];
+                const gatewayCapabilities = Array.isArray(parsed.capabilities)
+                    ? parsed.capabilities
+                        .map((item) => typeof item === "string" && item.trim() ? item.trim() : null)
+                        .filter((item) => Boolean(item))
+                    : [];
+                const localVersionInfo = this.getLocalVersionInfo?.() ?? {
+                    packageVersion: "0.0.0-unknown",
+                    protocolVersion: versionHandshake_1.TELLYMCP_PROTOCOL_VERSION,
+                    capabilities: [...versionHandshake_1.TELLYMCP_CAPABILITIES],
+                };
+                runtime.logger.info("Gateway WS hello acknowledged", {
+                    connectionId: typeof parsed.connection_id === "string" ? parsed.connection_id : null,
+                    clientUuid: this.wsHelloClientUuid,
+                    compatibility,
+                    gatewayPackageVersion,
+                    gatewayProtocolVersion,
+                });
+                if (compatibility !== "ok") {
+                    const sessionTools = Array.isArray(this.wsHelloSessionTools)
+                        ? this.wsHelloSessionTools
+                        : [];
+                    for (const sessionTool of sessionTools) {
+                        await runtime.telegramTransport.handleGatewayVersionCompatibilityEvent({
+                            local_session_id: sessionTool.local_session_id,
+                            ...(sessionTool.session_label
+                                ? { session_label: sessionTool.session_label }
+                                : {}),
+                            compatibility,
+                            gateway_package_version: gatewayPackageVersion,
+                            gateway_protocol_version: gatewayProtocolVersion,
+                            gateway_capabilities: gatewayCapabilities,
+                            client_package_version: localVersionInfo.packageVersion,
+                            client_protocol_version: localVersionInfo.protocolVersion,
+                            client_capabilities: localVersionInfo.capabilities,
+                            reasons,
+                            instruction: typeof parsed.instruction === "string" && parsed.instruction.trim()
+                                ? parsed.instruction.trim()
+                                : compatibility === "reject"
+                                    ? "Upgrade this client before continuing. Gateway transport is blocked until protocol major versions match."
+                                    : "Client and gateway versions differ. Upgrade the older side and verify TOOLS.md before continuing sensitive work.",
+                        });
+                    }
+                }
+                if (compatibility === "reject") {
+                    try {
+                        this.wsClient?.close?.(4002, "version_incompatible");
+                    }
+                    catch {
+                        this.wsClient?.terminate?.();
+                    }
+                    return;
+                }
+                await this.syncLocalToolsAgainstGateway?.();
+                return;
+            }
+            if (parsed.type === "heartbeat_pong") {
+                this.wsAwaitingPong = false;
+                return;
+            }
+            if (parsed.type === "tools_event" && parsed.payload) {
+                await runtime.telegramTransport.handleToolsUpdatedEvent(parsed.payload);
+                return;
+            }
+            if (parsed.type === "project_event") {
+                if (parsed.event === "member_joined" &&
+                    parsed.payload &&
+                    typeof parsed.payload === "object") {
+                    await runtime.telegramTransport.handleProjectMemberJoinedEvent(parsed.payload);
+                    return;
+                }
+                if (parsed.event === "member_left" &&
+                    parsed.payload &&
+                    typeof parsed.payload === "object") {
+                    await runtime.telegramTransport.handleProjectMemberLeftEvent(parsed.payload);
+                    return;
+                }
+                if (parsed.event === "project_deleted" &&
+                    parsed.payload &&
+                    typeof parsed.payload === "object") {
+                    await runtime.telegramTransport.handleProjectDeletedEvent(parsed.payload);
+                    return;
+                }
+            }
+            if (parsed.type === "live_event" && parsed.payload) {
+                if (parsed.event === "approval_request") {
+                    await runtime.telegramTransport.handleLiveViewApprovalRequestEvent(parsed.payload);
+                    return;
+                }
+                if (parsed.event === "approval_granted" ||
+                    parsed.event === "approval_denied") {
+                    await runtime.telegramTransport.handleLiveViewApprovalResolvedEvent({
+                        approved: parsed.event === "approval_granted",
+                        ...parsed.payload,
+                    });
+                    return;
+                }
+            }
+            if (parsed.type === "delivery_event") {
+                const delivery = parsed.payload;
+                if (!delivery) {
+                    return;
+                }
+                try {
+                    await this.broker.call("telegramMcp.gatewayDelivery.materializeIncomingDelivery", {
+                        delivery,
+                    }, { meta: { internal_call: true } });
+                    this.wsClient?.send(JSON.stringify({
+                        type: "delivery_ack",
+                        delivery_ids: [delivery.delivery_uuid],
+                    }));
+                }
+                catch (error) {
+                    this.wsClient?.send(JSON.stringify({
+                        type: "delivery_fail",
+                        delivery_ids: [delivery.delivery_uuid],
+                        error_text: error instanceof Error ? error.message : String(error),
+                    }));
+                    throw error;
+                }
+                return;
+            }
+            if (parsed.type === "delivery_status_event") {
+                await this.broker.call("telegramMcp.gatewayDelivery.applyOutgoingDeliveryStatus", {
+                    status: parsed.payload,
+                }, { meta: { internal_call: true } });
+                return;
+            }
+            if (parsed.type === "live_request") {
+                const request = parsed;
+                const response = await this.processLiveRequest?.(request);
+                this.wsClient?.send(JSON.stringify(response));
+                return;
+            }
+            runtime.logger.debug("Gateway WS client message received", {
+                payload: String(raw),
+            });
+        },
+        async requestLiveRelay(params) {
+            const runtime = this.getRuntimeOrThrow();
+            const socket = this.connectedClientsByUuid?.get(params.clientUuid);
+            if (!socket || socket.readyState !== 1) {
+                throw new Error(`Gateway WS client '${params.clientUuid}' is not connected`);
+            }
+            const requestId = (0, node_crypto_1.randomUUID)();
+            const response = await new Promise((resolve, reject) => {
+                const timeout = setTimeout(() => {
+                    this.pendingLiveRequests?.delete(requestId);
+                    reject(new Error("Live relay WS request timed out"));
+                }, LIVE_REQUEST_TIMEOUT_MS);
+                this.pendingLiveRequests?.set(requestId, {
+                    clientUuid: params.clientUuid,
+                    resolve,
+                    reject,
+                    timeout,
+                });
+                const request = {
+                    type: "live_request",
+                    request_id: requestId,
+                    request_type: params.requestType,
+                    local_session_id: params.localSessionId,
+                    payload: params.payload,
+                };
+                socket.send(JSON.stringify(request));
+            });
+            runtime.logger.debug("Gateway WS live relay completed", {
+                clientUuid: params.clientUuid,
+                localSessionId: params.localSessionId,
+                requestType: params.requestType,
+            });
+            return response;
+        },
+        async notifyProjectMemberJoined(params) {
+            const message = {
+                type: "project_event",
+                event: "member_joined",
+                payload: {
+                    project_uuid: params.projectUuid,
+                    project_name: params.projectName,
+                    ...(params.memberDisplayName
+                        ? { member_display_name: params.memberDisplayName }
+                        : {}),
+                    ...(params.memberTelegramUsername
+                        ? { member_telegram_username: params.memberTelegramUsername }
+                        : {}),
+                },
+            };
+            let delivered = 0;
+            for (const clientUuid of params.clientUuids) {
+                if (await this.isLocalGatewayClientUuid?.(clientUuid)) {
+                    const runtime = this.getRuntimeOrThrow();
+                    await runtime.telegramTransport.handleProjectMemberJoinedEvent(message.payload);
+                    delivered += 1;
+                    continue;
+                }
+                const socket = this.connectedClientsByUuid?.get(clientUuid);
+                if (!socket || socket.readyState !== 1) {
+                    continue;
+                }
+                socket.send(JSON.stringify(message));
+                delivered += 1;
+            }
+            return delivered;
+        },
+        async notifyProjectMemberLeft(params) {
+            const message = {
+                type: "project_event",
+                event: "member_left",
+                payload: {
+                    project_uuid: params.projectUuid,
+                    project_name: params.projectName,
+                    ...(params.memberDisplayName
+                        ? { member_display_name: params.memberDisplayName }
+                        : {}),
+                    ...(params.memberTelegramUsername
+                        ? { member_telegram_username: params.memberTelegramUsername }
+                        : {}),
+                },
+            };
+            let delivered = 0;
+            for (const clientUuid of params.clientUuids) {
+                if (await this.isLocalGatewayClientUuid?.(clientUuid)) {
+                    const runtime = this.getRuntimeOrThrow();
+                    await runtime.telegramTransport.handleProjectMemberLeftEvent(message.payload);
+                    delivered += 1;
+                    continue;
+                }
+                const socket = this.connectedClientsByUuid?.get(clientUuid);
+                if (!socket || socket.readyState !== 1) {
+                    continue;
+                }
+                socket.send(JSON.stringify(message));
+                delivered += 1;
+            }
+            return delivered;
+        },
+        async notifyProjectDeleted(params) {
+            const message = {
+                type: "project_event",
+                event: "project_deleted",
+                payload: {
+                    project_uuid: params.projectUuid,
+                    project_name: params.projectName,
+                },
+            };
+            let delivered = 0;
+            for (const clientUuid of params.clientUuids) {
+                if (await this.isLocalGatewayClientUuid?.(clientUuid)) {
+                    const runtime = this.getRuntimeOrThrow();
+                    await runtime.telegramTransport.handleProjectDeletedEvent(message.payload);
+                    delivered += 1;
+                    continue;
+                }
+                const socket = this.connectedClientsByUuid?.get(clientUuid);
+                if (!socket || socket.readyState !== 1) {
+                    continue;
+                }
+                socket.send(JSON.stringify(message));
+                delivered += 1;
+            }
+            return delivered;
+        },
+        async notifyLiveApprovalRequest(params) {
+            if (await this.isLocalGatewayClientUuid?.(params.clientUuid)) {
+                const runtime = this.getRuntimeOrThrow();
+                await runtime.telegramTransport.handleLiveViewApprovalRequestEvent(params.payload);
+                return true;
+            }
+            const socket = this.connectedClientsByUuid?.get(params.clientUuid);
+            if (!socket || socket.readyState !== 1) {
+                return false;
+            }
+            socket.send(JSON.stringify({
+                type: "live_event",
+                event: "approval_request",
+                payload: params.payload,
+            }));
+            return true;
+        },
+        async notifyLiveApprovalResolved(params) {
+            if (await this.isLocalGatewayClientUuid?.(params.clientUuid)) {
+                const runtime = this.getRuntimeOrThrow();
+                await runtime.telegramTransport.handleLiveViewApprovalResolvedEvent({
+                    approved: params.approved,
+                    ...params.payload,
+                });
+                return true;
+            }
+            const socket = this.connectedClientsByUuid?.get(params.clientUuid);
+            if (!socket || socket.readyState !== 1) {
+                return false;
+            }
+            socket.send(JSON.stringify({
+                type: "live_event",
+                event: params.approved ? "approval_granted" : "approval_denied",
+                payload: params.payload,
+            }));
+            return true;
+        },
+        async notifyDeliveryQueued(params) {
+            if (await this.handleLocalIncomingDelivery?.(params)) {
+                return true;
+            }
+            const socket = this.connectedClientsByUuid?.get(params.clientUuid);
+            if (!socket || socket.readyState !== 1) {
+                return false;
+            }
+            socket.send(JSON.stringify({
+                type: "delivery_event",
+                event: "incoming_delivery",
+                payload: params.delivery,
+            }));
+            return true;
+        },
+        async notifyDeliveryStatus(params) {
+            if (await this.handleLocalDeliveryStatus?.(params)) {
+                return true;
+            }
+            const socket = this.connectedClientsByUuid?.get(params.clientUuid);
+            if (!socket || socket.readyState !== 1) {
+                return false;
+            }
+            socket.send(JSON.stringify({
+                type: "delivery_status_event",
+                payload: params.status,
+            }));
+            return true;
+        },
+        async startGatewayWsServer() {
+            const runtime = this.getRuntimeOrThrow();
+            if (!runtime || this.wsServer) {
+                return;
+            }
+            const httpServer = this.getHttpServerOrThrow?.();
+            const wsPath = runtime.config.distributed.gatewayWsPath.replace(/\/+$/u, "") || "/";
+            const wsServer = new WebSocketServer({ noServer: true });
+            wsServer.on("connection", (socket, req) => {
+                if (runtime.config.distributed.gatewayAuthToken) {
+                    const authorization = req.headers?.authorization;
+                    if (authorization !==
+                        `Bearer ${runtime.config.distributed.gatewayAuthToken}`) {
+                        socket.close(1008, "Unauthorized");
+                        return;
+                    }
+                }
+                runtime.logger.warn("Gateway WS client connected", {
+                    remoteAddress: req.socket.remoteAddress,
+                    path: req.url,
+                });
+                socket.on("message", (raw) => {
+                    void this.handleGatewayWsServerMessage?.(socket, raw).catch((error) => {
+                        runtime.logger.warn("Gateway WS server message parse failed", {
+                            error: error instanceof Error ? (error.stack ?? error.message) : String(error),
+                        });
+                    });
+                });
+                socket.on("close", () => {
+                    const hello = this.connectedClients?.get(socket);
+                    if (hello?.client_uuid) {
+                        this.connectedClientsByUuid?.delete(hello.client_uuid);
+                    }
+                    this.connectedClientToolsAlerts?.delete(socket);
+                    this.connectedClients?.delete(socket);
+                    runtime.logger.warn("Gateway WS client disconnected", {
+                        connectionId: hello?.connection_id ?? null,
+                        clientUuid: hello?.client_uuid ?? null,
+                    });
+                });
+            });
+            const upgradeHandler = (req, socket, head) => {
+                const requestUrl = new URL(req.url ?? "/", "http://gateway.local");
+                const requestPath = requestUrl.pathname.replace(/\/+$/u, "") || "/";
+                if (requestPath !== wsPath) {
+                    return;
+                }
+                wsServer.handleUpgrade(req, socket, head, (clientSocket) => {
+                    wsServer.emit("connection", clientSocket, req);
+                });
+            };
+            httpServer?.on("upgrade", upgradeHandler);
+            this.wsServer = wsServer;
+            this.wsUpgradeHandler = upgradeHandler;
+            runtime.logger.warn("Gateway WS server attached", {
+                path: runtime.config.distributed.gatewayWsPath,
+            });
+        },
+        ensureGatewayWsClientIsReusable() {
+            if (!this.wsClient) {
+                return true;
+            }
+            const readyState = typeof this.wsClient.readyState === "number"
+                ? this.wsClient.readyState
+                : null;
+            // OPEN=1, CONNECTING=0 are still active; CLOSING=2 and CLOSED=3 are stale.
+            if (readyState === 0 || readyState === 1) {
+                return false;
+            }
+            this.wsClient = null;
+            return true;
+        },
+        scheduleGatewayWsReconnect() {
+            if (this.stopRequested || this.wsReconnectTimer) {
+                return;
+            }
+            const runtime = this.getRuntimeOrThrow?.();
+            runtime?.logger.warn("Gateway WS reconnect scheduled", {
+                delayMs: CLIENT_RECONNECT_DELAY_MS,
+            });
+            this.wsReconnectTimer = setTimeout(() => {
+                this.wsReconnectTimer = null;
+                void this.startGatewayWsClient?.();
+            }, CLIENT_RECONNECT_DELAY_MS);
+        },
+        async startGatewayWsClient() {
+            const runtime = this.getRuntimeOrThrow?.();
+            if (!runtime) {
+                return;
+            }
+            if (!this.ensureGatewayWsClientIsReusable?.()) {
+                return;
+            }
+            const wsUrl = runtime.config.distributed.gatewayWsUrl;
+            if (!wsUrl) {
+                runtime.logger.info("Gateway WS client is disabled", {
+                    reason: "GATEWAY_WS_URL is not configured",
+                });
+                return;
+            }
+            const normalizedUrl = normalizeWebSocketUrl(wsUrl, runtime.config.distributed.gatewayWsPath);
+            this.wsConnectionId = (0, node_crypto_1.randomUUID)();
+            const socket = new wsLib.WebSocket(normalizedUrl, {
+                headers: runtime.config.distributed.gatewayAuthToken
+                    ? {
+                        authorization: `Bearer ${runtime.config.distributed.gatewayAuthToken}`,
+                    }
+                    : undefined,
+            });
+            socket.on("open", () => {
+                runtime.logger.warn(this.wsClientHasConnectedOnce
+                    ? "Gateway WS connected to gateway again"
+                    : "Gateway WS connected to gateway", {
+                    url: normalizedUrl,
+                });
+                this.wsClientHasConnectedOnce = true;
+                this.wsAwaitingPong = false;
+                void this.sendClientHello?.(socket);
+            });
+            socket.on("message", (raw) => {
+                void this.handleGatewayWsClientMessage?.(raw).catch((error) => {
+                    runtime.logger.warn("Gateway WS client message handling failed", {
+                        error: error instanceof Error ? (error.stack ?? error.message) : String(error),
+                    });
+                });
+            });
+            socket.on("error", (error) => {
+                runtime.logger.warn("Gateway WS client error", {
+                    url: normalizedUrl,
+                    error: error instanceof Error ? (error.stack ?? error.message) : String(error),
+                });
+                this.wsAwaitingPong = false;
+                if (this.wsClient === socket && socket.readyState !== 1) {
+                    this.wsClient = null;
+                }
+                this.scheduleGatewayWsReconnect?.();
+            });
+            socket.on("close", () => {
+                runtime.logger.warn("Gateway WS connection to gateway closed", {
+                    url: normalizedUrl,
+                    clientUuid: this.wsHelloClientUuid,
+                });
+                this.wsAwaitingPong = false;
+                if (this.wsClient === socket) {
+                    this.wsClient = null;
+                }
+                this.scheduleGatewayWsReconnect?.();
+            });
+            this.wsClient = socket;
+            if (!this.wsIdentityRefreshTimer) {
+                this.wsIdentityRefreshTimer = setInterval(() => {
+                    if (this.stopRequested || !this.wsClient || this.wsClient.readyState !== 1) {
+                        return;
+                    }
+                    void (async () => {
+                        const currentClientUuid = await runtime.maintenanceStore.getGatewayClientUuid();
+                        const currentSessionTools = await this.collectSessionTools?.() ?? {
+                            sessionTools: [],
+                            snapshot: "[]",
+                        };
+                        if ((currentClientUuid ?? null) === this.wsHelloClientUuid &&
+                            currentSessionTools.snapshot === this.wsHelloSessionToolsSnapshot) {
+                            return;
+                        }
+                        await this.sendClientHello?.(this.wsClient);
+                    })().catch((error) => {
+                        runtime.logger.warn("Gateway WS hello refresh failed", {
+                            error: error instanceof Error ? (error.stack ?? error.message) : String(error),
+                        });
+                    });
+                }, 5000);
+            }
+            if (!this.wsToolsSyncTimer) {
+                this.wsToolsSyncTimer = setInterval(() => {
+                    if (this.stopRequested) {
+                        return;
+                    }
+                    void (async () => {
+                        for (const [clientSocket, hello] of this.connectedClients?.entries() ?? []) {
+                            if (!clientSocket || clientSocket.readyState !== 1) {
+                                continue;
+                            }
+                            await this.notifyToolsMismatchForSocket?.(clientSocket, hello);
+                        }
+                    })().catch((error) => {
+                        runtime.logger.warn("Gateway WS tools sync check failed", {
+                            error: error instanceof Error ? (error.stack ?? error.message) : String(error),
+                        });
+                    });
+                }, TOOLS_SYNC_CHECK_INTERVAL_MS);
+            }
+            if (!this.wsHeartbeatTimer) {
+                this.wsHeartbeatTimer = setInterval(() => {
+                    if (this.stopRequested) {
+                        return;
+                    }
+                    const activeSocket = this.wsClient;
+                    if (!activeSocket || activeSocket.readyState !== 1) {
+                        this.wsAwaitingPong = false;
+                        return;
+                    }
+                    if (this.wsAwaitingPong) {
+                        runtime.logger.warn("Gateway WS heartbeat timed out; terminating stale client socket", {
+                            url: normalizedUrl,
+                            clientUuid: this.wsHelloClientUuid,
+                        });
+                        this.wsAwaitingPong = false;
+                        if (this.wsClient === activeSocket) {
+                            this.wsClient = null;
+                        }
+                        activeSocket.terminate?.();
+                        this.scheduleGatewayWsReconnect?.();
+                        return;
+                    }
+                    this.wsAwaitingPong = true;
+                    try {
+                        activeSocket.send?.(JSON.stringify({
+                            type: "heartbeat_ping",
+                            ts: new Date().toISOString(),
+                        }));
+                    }
+                    catch (error) {
+                        this.wsAwaitingPong = false;
+                        runtime.logger.warn("Gateway WS heartbeat ping failed", {
+                            url: normalizedUrl,
+                            error: error instanceof Error ? (error.stack ?? error.message) : String(error),
+                        });
+                        if (this.wsClient === activeSocket) {
+                            this.wsClient = null;
+                        }
+                        activeSocket.terminate?.();
+                        this.scheduleGatewayWsReconnect?.();
+                    }
+                }, WS_HEARTBEAT_INTERVAL_MS);
+            }
+        },
+        async closeGatewayWsResources() {
+            if (this.wsReconnectTimer) {
+                clearTimeout(this.wsReconnectTimer);
+                this.wsReconnectTimer = null;
+            }
+            if (this.wsIdentityRefreshTimer) {
+                clearInterval(this.wsIdentityRefreshTimer);
+                this.wsIdentityRefreshTimer = null;
+            }
+            if (this.wsToolsSyncTimer) {
+                clearInterval(this.wsToolsSyncTimer);
+                this.wsToolsSyncTimer = null;
+            }
+            if (this.wsHeartbeatTimer) {
+                clearInterval(this.wsHeartbeatTimer);
+                this.wsHeartbeatTimer = null;
+            }
+            this.wsAwaitingPong = false;
+            for (const pending of this.pendingLiveRequests?.values() ?? []) {
+                clearTimeout(pending.timeout);
+                pending.reject(new Error("Gateway WS transport is shutting down"));
+            }
+            this.pendingLiveRequests?.clear();
+            if (this.wsClient) {
+                const socket = this.wsClient;
+                this.wsClient = null;
+                socket.removeAllListeners();
+                socket.close();
+            }
+            this.wsHelloSessionToolsSnapshot = null;
+            if (this.wsServer) {
+                const server = this.wsServer;
+                this.wsServer = null;
+                const httpServer = this.standaloneHttpService?.httpServer;
+                if (httpServer && this.wsUpgradeHandler) {
+                    httpServer.removeListener("upgrade", this.wsUpgradeHandler);
+                }
+                this.wsUpgradeHandler = null;
+                await new Promise((resolve, reject) => {
+                    server.close((error) => {
+                        if (error) {
+                            reject(error);
+                            return;
+                        }
+                        resolve();
+                    });
+                });
+            }
+            this.connectedClientToolsAlerts?.clear();
+        },
+    },
+    async started() {
+        const runtime = this.getRuntimeOrThrow?.();
+        const mode = runtime?.config.distributed.mode;
+        const gatewayEnabled = mode === "gateway" || mode === "both";
+        const clientEnabled = mode === "client" || mode === "both";
+        if (gatewayEnabled) {
+            await this.startGatewayWsServer?.();
+        }
+        if (clientEnabled) {
+            await this.startGatewayWsClient?.();
+        }
+    },
+    async stopped() {
+        this.stopRequested = true;
+        await this.closeGatewayWsResources?.();
+    },
+};
+exports.default = TelegramMcpGatewaySocketService;