@deadragdoll/tellymcp 0.0.8 → 0.0.10

package/.env.example.client

@@ -4,6 +4,8 @@
 TELEGRAM_BOT_TOKEN=
 # Username бота, с @ или без.
 TELEGRAM_BOT_USERNAME=
+# Принудительный язык UI для отладки локализации: en или ru.
+# DEBUG_LANGUAGE=ru
 # Необязательная подпись проекта/сессии в prompt и note.
 PROJECT_NAME=
 

package/.env.example.gateway

@@ -4,6 +4,8 @@
 TELEGRAM_BOT_TOKEN=
 # Username бота, с @ или без.
 TELEGRAM_BOT_USERNAME=
+# Принудительный язык UI для отладки локализации: en или ru.
+# DEBUG_LANGUAGE=ru
 # Необязательная подпись проекта/сессии.
 PROJECT_NAME=
 

package/README-ru.md

@@ -1,6 +1,6 @@
 # TellyMCP
 
-[English](README.md) | [Русский](README-ru.md) | [Standalone Guide](STANDALONE.md) | [Standalone RU](STANDALONE-ru.md) | [Release Notes](VERSION.md)
+[English](README.md) | [Русский](README-ru.md) | [Standalone Guide](STANDALONE.md) | [Standalone RU](STANDALONE-ru.md) | [Screenshots](screenshots/README.md) | [Gallery](screenshots/GALLERY.md) | [Release Notes](VERSION.md)
 
 [![npm version](https://img.shields.io/npm/v/%40deadragdoll%2Ftellymcp)](https://www.npmjs.com/package/@deadragdoll/tellymcp)
 [![npm downloads](https://img.shields.io/npm/dm/%40deadragdoll%2Ftellymcp)](https://www.npmjs.com/package/@deadragdoll/tellymcp)
@@ -239,6 +239,26 @@ tellymcp run --env .env
 
 - `https://your-host.example/api/mcp`
 
+## Mini App / Live
+
+Если `WEBAPP_ENABLED=true`, в меню сессии появляется `🖥 Live`.
+
+Mini App:
+
+- обслуживается этим же Node service по `WEBAPP_BASE_PATH`
+- в `client`-режиме тоже может открываться через общий gateway domain
+- показывает видимую область tmux pane и отправляет ограниченный набор control actions
+- валидирует Telegram `initData` на сервере
+- умеет открываться в режимах:
+  - `default`
+  - `expand`
+  - `fullscreen` с fallback на `expand`
+- после успешного bootstrap удаляет временное launcher-сообщение
+- автоматически восстанавливается после короткого рестарта шлюза:
+  - краткий `502/503` переживается обычным polling
+  - если in-process WebApp session на шлюзе была потеряна и приходит `401/403`, Mini App сама делает повторный bootstrap
+  - в типовом restart-case переоткрывать `Live` не нужно
+
 ## Docker: только для инфраструктуры или для `gateway`-only
 
 Docker больше не является основным способом запуска TellyMCP, но один container path поддерживается:

package/README.md

@@ -1,6 +1,6 @@
 # TellyMCP
 
-[English](README.md) | [Русский](README-ru.md) | [Standalone Guide](STANDALONE.md) | [Standalone RU](STANDALONE-ru.md) | [Release Notes](VERSION.md)
+[English](README.md) | [Русский](README-ru.md) | [Standalone Guide](STANDALONE.md) | [Standalone RU](STANDALONE-ru.md) | [Screenshots](screenshots/README.md) | [Gallery](screenshots/GALLERY.md) | [Release Notes](VERSION.md)
 
 [![npm version](https://img.shields.io/npm/v/%40deadragdoll%2Ftellymcp)](https://www.npmjs.com/package/@deadragdoll/tellymcp)
 [![npm downloads](https://img.shields.io/npm/dm/%40deadragdoll%2Ftellymcp)](https://www.npmjs.com/package/@deadragdoll/tellymcp)
@@ -521,6 +521,10 @@ The Mini App:
 - requires the Telegram user from `initData` to match the bound session user
 - resolves the active session from the bound Telegram user, so a session id in the URL is not required for normal use
 - deletes the temporary `Open Live View` launcher message after successful Mini App bootstrap
+- auto-recovers after a short gateway restart:
+  - short `502/503` periods are tolerated by polling
+  - expired in-process WebApp sessions (`401/403`) trigger an automatic re-bootstrap
+  - in normal restart cases the user does not need to reopen `Live`
 - allows only a fixed control set:
   - `Esc`
   - `Tab`

package/TOOLS.md

@@ -1,10 +1,12 @@
 # Tools
 
-Version: `2026-05-17.1`
+Version: `2026-05-18.1`
 
 Gateway/client runtime compatibility:
 
 - `TOOLS.md` hash sync and runtime version handshake are separate checks.
+- The authoritative freshness check for `TOOLS.md` is the content hash, not this human-readable `Version:` line.
+- Treat this `Version:` line only as a quick visual marker for humans and logs.
 - `TOOLS.md` sync tells the agent to refresh instructions.
 - `ws hello/hello_ack` checks `package_version`, `protocol_version`, and `capabilities`.
 - If protocol major versions differ, gateway transport is blocked until the older side is upgraded.

package/VERSION.md

@@ -4,6 +4,60 @@ Public, user-facing release notes for published versions of `@deadragdoll/tellym
 
 For detailed engineering history, refactors, and internal development notes, see [CHANGELOG.md](CHANGELOG.md).
 
+## 0.0.10
+
+### Added
+- Telegram UI localization for the bot layer:
+  - English and Russian catalogs for user-facing bot screens
+  - locale resolution from Telegram profile with persisted user preference
+  - `DEBUG_LANGUAGE=en|ru` override for fast testing without changing the Telegram profile
+
+### Changed
+- Localization scope is now explicit:
+  - Telegram bot UI is localized
+  - MCP tools, logs, `TOOLS.md`, and the Live Mini App remain canonical English by design
+- Telegram menus, callbacks, project/collaboration screens, startup notices, and operational bot notices now render through a shared translation layer instead of ad hoc inline strings
+
+### Fixed
+- Builder startup is more robust:
+  - runtime-dependent services now wait for full runtime readiness instead of racing broker registration
+  - this avoids `telegram_mcp runtime is not initialized yet` failures during `yarn dev:builder`
+- Locale resolution is safe for partial test mocks and startup paths
+- Telegram UI text is now consistent across:
+  - main menus
+  - inbox/session flows
+  - project/collab flows
+  - live approval prompts
+  - tmux and operational bot notices
+
+## 0.0.9
+
+### Added
+- Public screenshot docs:
+  - full screenshot index in `screenshots/README.md`
+  - shorter public gallery in `screenshots/GALLERY.md`
+- More explicit Live launch modes from Telegram:
+  - `Fullscreen`
+  - `Expand`
+  - `Default`
+
+### Changed
+- README and README-RU now surface screenshot links directly in the top navigation.
+- The `Live` Mini App UI is more practical on phones:
+  - wrap/unwrap toggle moved into the status bar
+  - session name is shown as a compact state badge
+  - update timestamp is shorter and less noisy
+  - local `Live` screenshots are documented in a clearer flow near the launcher step
+
+### Fixed
+- `Live` now reconnects more gracefully after a gateway restart:
+  - short `502/503` gaps recover through polling
+  - expired in-process WebApp sessions (`401/403`) trigger automatic re-bootstrap
+  - reopening the Mini App is no longer required in the normal restart case
+- Runtime MCP metadata now reports the actual package version instead of stale hardcoded version data.
+- Successful tmux nudges no longer overwrite `tmuxPaneId` with non-pane targets such as `backend:0.0`.
+- If tmux itself is unavailable for a paired session with a saved tmux target, Telegram now receives an operational warning instead of leaving the signal only in backend logs.
+
 ## 0.0.8
 
 ### Added
@@ -32,6 +86,10 @@ For detailed engineering history, refactors, and internal development notes, see
 - Stale tmux pane ids like `%1 -> %2` no longer require manual user understanding before the service can try to wake the session again.
 - Broken tmux nudge targets are now visible to the user in Telegram, not only in backend logs.
 - `Share` inbox instructions are now explicit enough to reduce the chance that one agent re-delegates the task back into the collaboration graph.
+- `Live` Mini App now survives a normal gateway restart much better:
+  - short `502/503` periods recover through polling
+  - lost in-process WebApp sessions (`401/403`) trigger automatic re-bootstrap
+  - reopening the Mini App is no longer required in the normal restart case
 
 ## 0.0.3
 

package/config/templates/env.both.template

@@ -2,6 +2,7 @@
 
 TELEGRAM_BOT_TOKEN=
 TELEGRAM_BOT_USERNAME=
+# DEBUG_LANGUAGE=ru
 PROJECT_NAME=
 
 REDIS_HOST=127.0.0.1

package/config/templates/env.client.template

@@ -2,6 +2,7 @@
 
 TELEGRAM_BOT_TOKEN=
 TELEGRAM_BOT_USERNAME=
+# DEBUG_LANGUAGE=ru
 PROJECT_NAME=
 
 REDIS_HOST=127.0.0.1

package/config/templates/env.gateway.template

@@ -2,6 +2,7 @@
 
 TELEGRAM_BOT_TOKEN=
 TELEGRAM_BOT_USERNAME=
+# DEBUG_LANGUAGE=ru
 PROJECT_NAME=
 
 REDIS_HOST=127.0.0.1

package/dist/services/features/telegram-mcp/approval.service.js

@@ -24,7 +24,7 @@ const TelegramMcpApprovalService = {
         if (!runtimeService) {
             throw new Error(`Local Moleculer service '${runtime_service_1.TELEGRAM_MCP_RUNTIME_SERVICE_NAME}' is unavailable`);
         }
-        const runtime = runtimeService.getRuntime();
+        const runtime = await runtimeService.waitUntilReady();
         this.logger.info("Starting telegram_mcp approval service");
         this.approvalOrchestrator = new orchestrator_1.HumanApprovalOrchestrator(runtime.config, runtime.stateStore, runtime.stateStore, runtime.stateStore, runtime.telegramTransport, runtime.logger, runtime.projectIdentityResolver);
         this.logger.info("telegram_mcp approval service is ready");

package/dist/services/features/telegram-mcp/browser.service.js

@@ -24,7 +24,7 @@ const TelegramMcpBrowserService = {
         if (!runtimeService) {
             throw new Error(`Local Moleculer service '${runtime_service_1.TELEGRAM_MCP_RUNTIME_SERVICE_NAME}' is unavailable`);
         }
-        const runtime = runtimeService.getRuntime();
+        const runtime = await runtimeService.waitUntilReady();
         this.logger.info("Starting telegram_mcp browser service");
         this.browserService = new browserService_1.BrowserService(runtime.config, runtime.stateStore, runtime.stateStore, runtime.stateStore, runtime.objectStore, runtime.telegramTransport, runtime.logger, runtime.projectIdentityResolver);
         this.logger.info("telegram_mcp browser service is ready");

package/dist/services/features/telegram-mcp/collaboration.service.js

@@ -34,7 +34,7 @@ const TelegramMcpCollaborationService = {
         if (!runtimeService) {
             throw new Error(`Local Moleculer service '${runtime_service_1.TELEGRAM_MCP_RUNTIME_SERVICE_NAME}' is unavailable`);
         }
-        const runtime = runtimeService.getRuntime();
+        const runtime = await runtimeService.waitUntilReady();
         this.logger.info("Starting telegram_mcp collaboration service");
         const localBackend = new localCollaborationBackend_1.LocalCollaborationBackend(runtime.config, runtime.stateStore, runtime.stateStore, runtime.stateStore, runtime.stateStore, runtime.objectStore, runtime.telegramTransport, runtime.logger);
         runtime.gatewayHttpService.setPartnerNoteRelayHandler(async (input) => {

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

@@ -276,10 +276,11 @@ const TelegramMcpGatewayRmqService = {
             throw new Error(`Local Moleculer service '${runtime_service_1.TELEGRAM_MCP_RUNTIME_SERVICE_NAME}' is unavailable`);
         }
         this.runtimeService = runtimeService;
+        const runtime = await runtimeService.waitUntilReady();
         if (!this.isEnabled?.()) {
             this.logger.info("Gateway RMQ is disabled", {
-                distributedMode: runtimeService.getRuntime().config.distributed.mode,
-                rmqConfigured: Boolean(runtimeService.getRuntime().config.distributed.rmq?.host),
+                distributedMode: runtime.config.distributed.mode,
+                rmqConfigured: Boolean(runtime.config.distributed.rmq?.host),
             });
             return;
         }

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

@@ -1455,8 +1455,14 @@ const TelegramMcpGatewaySocketService = {
         },
     },
     async started() {
-        const runtime = this.getRuntimeOrThrow?.();
-        const mode = runtime?.config.distributed.mode;
+        await this.broker.waitForServices([runtime_service_1.TELEGRAM_MCP_RUNTIME_SERVICE_NAME]);
+        const 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;
+        const runtime = await runtimeService.waitUntilReady();
+        const mode = runtime.config.distributed.mode;
         const gatewayEnabled = mode === "gateway" || mode === "both";
         const clientEnabled = mode === "client" || mode === "both";
         if (gatewayEnabled) {

package/dist/services/features/telegram-mcp/inbox.service.js

@@ -24,7 +24,7 @@ const TelegramMcpInboxService = {
         if (!runtimeService) {
             throw new Error(`Local Moleculer service '${runtime_service_1.TELEGRAM_MCP_RUNTIME_SERVICE_NAME}' is unavailable`);
         }
-        const runtime = runtimeService.getRuntime();
+        const runtime = await runtimeService.waitUntilReady();
         this.logger.info("Starting telegram_mcp inbox service");
         this.inboxService = new inboxService_1.InboxService(runtime.config, runtime.stateStore, runtime.stateStore, runtime.logger, runtime.projectIdentityResolver);
         this.logger.info("telegram_mcp inbox service is ready");

package/dist/services/features/telegram-mcp/mcp-http.service.js

@@ -52,7 +52,7 @@ const TelegramMcpHttpService = {
         if (!mcpServerService) {
             throw new Error(`Local Moleculer service '${mcp_server_service_1.TELEGRAM_MCP_MCP_SERVER_SERVICE_NAME}' is unavailable`);
         }
-        const runtime = runtimeService.getRuntime();
+        const runtime = await runtimeService.waitUntilReady();
         this.logger.info("Starting telegram_mcp HTTP service");
         this.httpHandler = (0, http_1.createMcpHttpHandler)(runtime, {
             createMcpServer: () => mcpServerService.createServer(),

package/dist/services/features/telegram-mcp/notify.service.js

@@ -24,7 +24,7 @@ const TelegramMcpNotifyService = {
         if (!runtimeService) {
             throw new Error(`Local Moleculer service '${runtime_service_1.TELEGRAM_MCP_RUNTIME_SERVICE_NAME}' is unavailable`);
         }
-        const runtime = runtimeService.getRuntime();
+        const runtime = await runtimeService.waitUntilReady();
         this.logger.info("Starting telegram_mcp notify service");
         this.notifyService = new notifyService_1.NotifyService(runtime.config, runtime.stateStore, runtime.stateStore, runtime.telegramTransport, runtime.logger, runtime.projectIdentityResolver);
         this.logger.info("telegram_mcp notify service is ready");

package/dist/services/features/telegram-mcp/pair.service.js

@@ -24,7 +24,7 @@ const TelegramMcpPairService = {
         if (!runtimeService) {
             throw new Error(`Local Moleculer service '${runtime_service_1.TELEGRAM_MCP_RUNTIME_SERVICE_NAME}' is unavailable`);
         }
-        const runtime = runtimeService.getRuntime();
+        const runtime = await runtimeService.waitUntilReady();
         this.logger.info("Starting telegram_mcp pair service");
         this.pairSessionService = new generatePairCode_1.PairSessionService(runtime.config, runtime.stateStore, runtime.stateStore, runtime.stateStore, runtime.logger, runtime.projectIdentityResolver);
         this.logger.info("telegram_mcp pair service is ready");

package/dist/services/features/telegram-mcp/runtime.service.js

@@ -8,6 +8,10 @@ const TelegramMcpRuntimeService = {
     name: exports.TELEGRAM_MCP_RUNTIME_SERVICE_NAME,
     created() {
         this.runtime = null;
+        this.readyPromise = new Promise((resolve, reject) => {
+            this.resolveReady = resolve;
+            this.rejectReady = reject;
+        });
     },
     methods: {
         getRuntime() {
@@ -16,19 +20,35 @@ const TelegramMcpRuntimeService = {
             }
             return this.runtime;
         },
+        waitUntilReady() {
+            if (this.runtime) {
+                return Promise.resolve(this.runtime);
+            }
+            if (!this.readyPromise) {
+                return Promise.reject(new Error("telegram_mcp runtime readiness promise is unavailable"));
+            }
+            return this.readyPromise;
+        },
     },
     async started() {
         this.logger.info("Starting telegram_mcp runtime service", {
             packageVersion: (0, versionHandshake_1.getTellyMcpPackageVersion)(__dirname),
             protocolVersion: versionHandshake_1.TELLYMCP_PROTOCOL_VERSION,
         });
-        this.runtime = await (0, runtime_1.createAppRuntime)({
-            callBroker: (actionName, params, options) => this.broker.call(actionName, params, options),
-        });
-        this.logger.info("telegram_mcp runtime service is ready", {
-            packageVersion: (0, versionHandshake_1.getTellyMcpPackageVersion)(__dirname),
-            protocolVersion: versionHandshake_1.TELLYMCP_PROTOCOL_VERSION,
-        });
+        try {
+            this.runtime = await (0, runtime_1.createAppRuntime)({
+                callBroker: (actionName, params, options) => this.broker.call(actionName, params, options),
+            });
+            this.resolveReady?.(this.runtime);
+            this.logger.info("telegram_mcp runtime service is ready", {
+                packageVersion: (0, versionHandshake_1.getTellyMcpPackageVersion)(__dirname),
+                protocolVersion: versionHandshake_1.TELLYMCP_PROTOCOL_VERSION,
+            });
+        }
+        catch (error) {
+            this.rejectReady?.(error);
+            throw error;
+        }
     },
     async stopped() {
         if (!this.runtime) {

package/dist/services/features/telegram-mcp/session-context.service.js

@@ -24,7 +24,7 @@ const TelegramMcpSessionContextService = {
         if (!runtimeService) {
             throw new Error(`Local Moleculer service '${runtime_service_1.TELEGRAM_MCP_RUNTIME_SERVICE_NAME}' is unavailable`);
         }
-        const runtime = runtimeService.getRuntime();
+        const runtime = await runtimeService.waitUntilReady();
         this.logger.info("Starting telegram_mcp session-context service");
         this.sessionContextService = new sessionContextService_1.SessionContextService(runtime.stateStore, runtime.stateStore, runtime.logger, runtime.projectIdentityResolver);
         this.logger.info("telegram_mcp session-context service is ready");

package/dist/services/features/telegram-mcp/src/app/bootstrap/runtime.js

@@ -72,7 +72,7 @@ async function createAppRuntime(input) {
     const objectStore = new minioExchangeStore_1.MinioExchangeStore(input.callBroker, stateStore, config.tmux, config.exchange.dir, config.mcp.vfsScope, logger, config.distributed.mode, config.distributed.gatewayPublicUrl, config.distributed.gatewayAuthToken);
     await stateStore.resetRuntimeState();
     logger.info("Runtime pending state reset");
-    const telegramTransport = new transport_1.TelegramTransport(config, stateStore, stateStore, stateStore, stateStore, stateStore, stateStore, objectStore, webAppLaunchRegistry, logger);
+    const telegramTransport = new transport_1.TelegramTransport(config, stateStore, stateStore, stateStore, stateStore, stateStore, stateStore, stateStore, objectStore, webAppLaunchRegistry, logger);
     await telegramTransport.start();
     logger.info("Telegram transport ready");
     await telegramTransport.recoverPendingInboxNudges();
@@ -89,6 +89,7 @@ async function createAppRuntime(input) {
         sessionStore: stateStore,
         bindingStore: stateStore,
         inboxStore: stateStore,
+        localeStore: stateStore,
         xchangeFileMetaStore: stateStore,
         maintenanceStore: stateStore,
         objectStore,

package/dist/services/features/telegram-mcp/src/app/config/env.js

@@ -59,6 +59,7 @@ const envSchema = z.object({
         .int()
         .positive()
         .default(300),
+    DEBUG_LANGUAGE: z.enum(["en", "ru"]).optional(),
     REDIS_HOST: z.string().min(1),
     REDIS_PORT: z.coerce.number().int().positive(),
     REDIS_DB: z.coerce.number().int().nonnegative(),
@@ -205,6 +206,9 @@ function loadConfig() {
             ...(parsed.TELEGRAM_BOT_USERNAME
                 ? { botUsername: parsed.TELEGRAM_BOT_USERNAME }
                 : {}),
+            ...(parsed.DEBUG_LANGUAGE
+                ? { debugLanguage: parsed.DEBUG_LANGUAGE }
+                : {}),
             pollIntervalMs: parsed.TELEGRAM_POLL_INTERVAL_MS,
             defaultTimeoutSeconds: parsed.TELEGRAM_DEFAULT_TIMEOUT_SECONDS,
             maxContextChars: parsed.TELEGRAM_MAX_CONTEXT_CHARS,

package/dist/services/features/telegram-mcp/src/app/http.js

@@ -105,6 +105,11 @@ function normalizePrefixedPathname(pathname) {
     const stripped = pathname.slice(normalizedRootPrefix.length);
     return stripped.startsWith("/") ? stripped : `/${stripped || ""}`;
 }
+function resolveLaunchModeOverride(value) {
+    return value === "default" || value === "expand" || value === "fullscreen"
+        ? value
+        : null;
+}
 function normalizeBasePath(value) {
     const trimmed = value.trim().replace(/\/+$/u, "");
     if (!trimmed) {
@@ -152,9 +157,11 @@ function createMcpHttpHandler(runtime, input) {
                     writeText(res, 405, "Method not allowed");
                     return;
                 }
+                const launchMode = resolveLaunchModeOverride(requestUrl.searchParams.get("launchMode")) ??
+                    runtime.config.webapp.launchMode;
                 writeHtml(res, 200, (0, assets_1.renderWebAppHtml)({
                     basePath: publicWebAppBasePath,
-                    launchMode: runtime.config.webapp.launchMode,
+                    launchMode,
                 }));
                 return;
             }

package/dist/services/features/telegram-mcp/src/app/providers/mcp/server.js

@@ -3,10 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createMcpServer = createMcpServer;
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const registry_1 = require("../../../shared/api/tool-registry/registry");
+const versionHandshake_1 = require("../../../shared/lib/version/versionHandshake");
 function createMcpServer(tools) {
     const server = new mcp_js_1.McpServer({
         name: "tellymcp",
-        version: "0.0.6",
+        version: (0, versionHandshake_1.getTellyMcpPackageVersion)(__dirname),
     });
     (0, registry_1.registerTools)(server, tools);
     return server;