@deadragdoll/tellymcp 0.0.14 → 0.0.16

package/dist/services/features/telegram-mcp/src/shared/integrations/memory/processLocalStateStore.js

@@ -0,0 +1,260 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProcessLocalStateStore = void 0;
+const redactSecrets_1 = require("../../lib/redact-secrets/redactSecrets");
+function principalKey(principal) {
+    return `${principal.telegramChatId}:${principal.telegramUserId}`;
+}
+function xchangeKey(sessionId, filePath) {
+    return `${sessionId}\u0000${filePath}`;
+}
+class ProcessLocalStateStore {
+    pairCodes = new Map();
+    bindings = new Map();
+    principalSessions = new Map();
+    principalActiveSessions = new Map();
+    locales = new Map();
+    authorizedPrincipals = new Map();
+    requests = new Map();
+    requestQueue = [];
+    activeRequestId = null;
+    menuPayloads = new Map();
+    xchangeFileMetas = new Map();
+    browserAttachments = new Map();
+    browserRecordings = new Map();
+    projectMenuViews = new Map();
+    outgoingNotices = new Map();
+    gatewayClientUuid;
+    constructor(input = {}) {
+        this.gatewayClientUuid = input.gatewayClientUuid?.trim() || null;
+        this.onGatewayClientUuidChange = input.onGatewayClientUuidChange;
+    }
+    onGatewayClientUuidChange;
+    async createPairCode(record, ttlSeconds) {
+        const existing = this.readExpiring(this.pairCodes, record.code);
+        if (existing)
+            return false;
+        this.pairCodes.set(record.code, { value: record, expiresAt: Date.now() + ttlSeconds * 1000 });
+        return true;
+    }
+    async consumePairCode(code) {
+        const record = this.readExpiring(this.pairCodes, code);
+        this.pairCodes.delete(code);
+        return record;
+    }
+    async getBinding(sessionId) {
+        return this.bindings.get(sessionId) ?? null;
+    }
+    async setBinding(binding) {
+        const previous = this.bindings.get(binding.sessionId);
+        if (previous)
+            this.detachSession(previous, binding.sessionId);
+        this.bindings.set(binding.sessionId, binding);
+        const key = principalKey(binding);
+        const sessions = this.principalSessions.get(key) ?? new Set();
+        sessions.add(binding.sessionId);
+        this.principalSessions.set(key, sessions);
+        this.principalActiveSessions.set(key, binding.sessionId);
+    }
+    async clearBinding(sessionId) {
+        const binding = this.bindings.get(sessionId);
+        this.bindings.delete(sessionId);
+        if (binding)
+            this.detachSession(binding, sessionId);
+    }
+    async getActiveSessionIdForPrincipal(principal) {
+        return this.principalActiveSessions.get(principalKey(principal)) ?? null;
+    }
+    async getActiveSessionIdForTelegramUser(telegramUserId) {
+        for (const [sessionId, binding] of this.bindings) {
+            if (binding.telegramUserId === telegramUserId) {
+                return this.principalActiveSessions.get(principalKey(binding)) ?? sessionId;
+            }
+        }
+        return null;
+    }
+    async clearActiveSessionIdForPrincipal(principal) {
+        this.principalActiveSessions.delete(principalKey(principal));
+    }
+    async setActiveSessionIdForPrincipal(principal, sessionId) {
+        const key = principalKey(principal);
+        const sessions = this.principalSessions.get(key) ?? new Set();
+        sessions.add(sessionId);
+        this.principalSessions.set(key, sessions);
+        this.principalActiveSessions.set(key, sessionId);
+    }
+    async listBoundSessionIdsForPrincipal(principal) {
+        return Array.from(this.principalSessions.get(principalKey(principal)) ?? []);
+    }
+    async listBoundPrincipals() {
+        const principals = new Map();
+        for (const binding of this.bindings.values()) {
+            principals.set(principalKey(binding), {
+                telegramChatId: binding.telegramChatId,
+                telegramUserId: binding.telegramUserId,
+            });
+        }
+        return Array.from(principals.values());
+    }
+    async resetRuntimeState() {
+        this.activeRequestId = null;
+        this.requestQueue.length = 0;
+    }
+    async getActive() {
+        return this.activeRequestId ? this.requests.get(this.activeRequestId) ?? null : null;
+    }
+    async createPending(request) {
+        this.requests.set(request.requestId, request);
+        this.activeRequestId = request.requestId;
+    }
+    async updatePending(request) {
+        this.requests.set(request.requestId, request);
+    }
+    async resolvePending(requestId, resolution) {
+        const current = this.requests.get(requestId);
+        if (current) {
+            this.requests.set(requestId, {
+                ...current,
+                status: resolution.status,
+                ...(resolution.answer ? { answer: (0, redactSecrets_1.redactSecrets)(resolution.answer) } : {}),
+                ...(resolution.receivedAt ? { receivedAt: resolution.receivedAt } : {}),
+                ...(resolution.fallbackUsed ? { fallbackIfTimeout: resolution.fallbackUsed } : {}),
+            });
+        }
+        this.activeRequestId = null;
+    }
+    async enqueue(request) {
+        this.requests.set(request.requestId, request);
+        this.requestQueue.push(request.requestId);
+    }
+    async dequeueNext() {
+        const requestId = this.requestQueue.shift();
+        return requestId ? this.requests.get(requestId) ?? null : null;
+    }
+    async createMenuPayload(record, ttlSeconds) {
+        this.menuPayloads.set(record.key, { value: record, expiresAt: Date.now() + ttlSeconds * 1000 });
+    }
+    async getMenuPayload(key) {
+        return this.readExpiring(this.menuPayloads, key);
+    }
+    async getUserLocale(telegramUserId) {
+        return this.locales.get(telegramUserId) ?? null;
+    }
+    async setUserLocale(telegramUserId, locale) {
+        this.locales.set(telegramUserId, locale);
+    }
+    async isAdminAuthorized(principal) {
+        return this.authorizedPrincipals.has(principalKey(principal));
+    }
+    async setAdminAuthorized(principal) {
+        this.authorizedPrincipals.set(principalKey(principal), principal);
+    }
+    async clearAdminAuthorized(principal) {
+        this.authorizedPrincipals.delete(principalKey(principal));
+    }
+    async listAdminAuthorizedPrincipals() {
+        return Array.from(this.authorizedPrincipals.values());
+    }
+    async setXchangeFileMeta(meta) {
+        this.xchangeFileMetas.set(xchangeKey(meta.sessionId, meta.filePath), meta);
+    }
+    async listXchangeFileMetas(sessionId) {
+        return Array.from(this.xchangeFileMetas.values())
+            .filter((meta) => meta.sessionId === sessionId)
+            .sort((left, right) => right.uploadedAt.localeCompare(left.uploadedAt));
+    }
+    async getXchangeFileMeta(sessionId, filePath) {
+        return this.xchangeFileMetas.get(xchangeKey(sessionId, filePath)) ?? null;
+    }
+    async deleteXchangeFileMeta(sessionId, filePath) {
+        return this.xchangeFileMetas.delete(xchangeKey(sessionId, filePath));
+    }
+    async pruneAll() {
+        const deletedKeys = this.countEntries();
+        this.pairCodes.clear();
+        this.bindings.clear();
+        this.principalSessions.clear();
+        this.principalActiveSessions.clear();
+        this.locales.clear();
+        this.authorizedPrincipals.clear();
+        this.requests.clear();
+        this.requestQueue.length = 0;
+        this.activeRequestId = null;
+        this.menuPayloads.clear();
+        this.xchangeFileMetas.clear();
+        this.browserAttachments.clear();
+        this.browserRecordings.clear();
+        this.projectMenuViews.clear();
+        this.outgoingNotices.clear();
+        this.gatewayClientUuid = null;
+        return { deletedKeys };
+    }
+    async getGatewayClientUuid() { return this.gatewayClientUuid; }
+    async setGatewayClientUuid(clientUuid) {
+        this.gatewayClientUuid = clientUuid;
+        this.onGatewayClientUuidChange?.(clientUuid);
+    }
+    async getBrowserAttachment(sessionId) {
+        return this.browserAttachments.get(sessionId) ?? null;
+    }
+    async setBrowserAttachment(record) {
+        this.browserAttachments.set(record.sessionId, record);
+    }
+    async clearBrowserAttachment(sessionId) { this.browserAttachments.delete(sessionId); }
+    async getBrowserRecording(sessionId) {
+        return this.browserRecordings.get(sessionId) ?? null;
+    }
+    async setBrowserRecording(record) {
+        this.browserRecordings.set(record.sessionId, record);
+    }
+    async clearBrowserRecording(sessionId) { this.browserRecordings.delete(sessionId); }
+    async setProjectMenuViewState(state) {
+        this.projectMenuViews.set(xchangeKey(state.projectUuid, state.sessionId), state);
+    }
+    async listProjectMenuViewStates(projectUuid) {
+        return Array.from(this.projectMenuViews.values()).filter((state) => state.projectUuid === projectUuid);
+    }
+    async deleteProjectMenuViewState(sessionId, projectUuid) {
+        return this.projectMenuViews.delete(xchangeKey(projectUuid, sessionId));
+    }
+    async setOutgoingDeliveryNotice(notice) {
+        this.outgoingNotices.set(notice.deliveryUuid, notice);
+    }
+    async listOutgoingDeliveryNotices() {
+        return Array.from(this.outgoingNotices.values());
+    }
+    async deleteOutgoingDeliveryNotice(deliveryUuid) {
+        return this.outgoingNotices.delete(deliveryUuid);
+    }
+    readExpiring(store, key) {
+        const record = store.get(key);
+        if (!record)
+            return null;
+        if (record.expiresAt <= Date.now()) {
+            store.delete(key);
+            return null;
+        }
+        return record.value;
+    }
+    detachSession(principal, sessionId) {
+        const key = principalKey(principal);
+        const sessions = this.principalSessions.get(key);
+        sessions?.delete(sessionId);
+        if (!sessions?.size)
+            this.principalSessions.delete(key);
+        if (this.principalActiveSessions.get(key) === sessionId) {
+            const next = sessions?.values().next().value;
+            if (next)
+                this.principalActiveSessions.set(key, next);
+            else
+                this.principalActiveSessions.delete(key);
+        }
+    }
+    countEntries() {
+        return this.pairCodes.size + this.bindings.size + this.locales.size +
+            this.authorizedPrincipals.size + this.requests.size + this.menuPayloads.size +
+            this.xchangeFileMetas.size + this.browserAttachments.size + this.browserRecordings.size +
+            this.projectMenuViews.size + this.outgoingNotices.size + (this.gatewayClientUuid ? 1 : 0);
+    }
+}
+exports.ProcessLocalStateStore = ProcessLocalStateStore;

package/dist/services/features/telegram-mcp/src/shared/integrations/object-storage/minioExchangeStore.js

@@ -29,7 +29,7 @@ class MinioExchangeStore {
     terminalConfig;
     exchangeDirName;
     logger;
-    constructor(_callBroker, _bindingStore, terminalConfig, exchangeDirName, _vfsScope, logger, _distributedMode = "client", _gatewayPublicUrl, _gatewayAuthToken) {
+    constructor(terminalConfig, exchangeDirName, logger) {
         this.terminalConfig = terminalConfig;
         this.exchangeDirName = exchangeDirName;
         this.logger = logger;

package/dist/services/features/telegram-mcp/src/shared/integrations/telegram/transport.js

@@ -218,7 +218,7 @@ class TelegramTransport {
     }
     isAdminAuthEnabled() {
         return (this.isAdminBotProfile() &&
-            Boolean(this.config.distributed.gatewayToken?.trim()));
+            Boolean(this.config.distributed.gatewayScopeToken?.trim()));
     }
     isAdminBotProfile() {
         return this.config.distributed.mode === "gateway";

package/dist/services/features/telegram-mcp/src/shared/integrations/telegram/transportConsoleRegistry.js

@@ -26,8 +26,8 @@ class TransportConsoleRegistry {
             ...(input?.principal
                 ? { telegram_user_id: input.principal.telegramUserId }
                 : {}),
-            ...(this.host.config.distributed.gatewayToken
-                ? { gateway_token: this.host.config.distributed.gatewayToken }
+            ...(this.host.config.distributed.gatewayScopeToken
+                ? { gateway_token: this.host.config.distributed.gatewayScopeToken }
                 : {}),
         });
         return Array.isArray(response.sessions) ? response.sessions : [];

package/dist/services/features/telegram-mcp/src/shared/integrations/telegram/transportMessageFlow.js

@@ -73,7 +73,7 @@ class TransportMessageFlow {
                 await this.host.replyText(ctx, await this.host.tForContext(ctx, "menu:admin.auth.disabled"), { sessionId: "gateway-auth", kind: "transport" });
                 return true;
             }
-            if (authToken !== this.host.config.distributed.gatewayToken) {
+            if (authToken !== this.host.config.distributed.gatewayScopeToken) {
                 await this.host.replyText(ctx, await this.host.tForContext(ctx, "menu:admin.auth.invalid"), { sessionId: "gateway-auth", kind: "transport" });
                 return true;
             }

package/dist/services/features/telegram-mcp/src/shared/integrations/telegram/transportProjectState.js

@@ -46,8 +46,8 @@ class TransportProjectState {
                 this.host.config.telegram.botUsername ||
                 "telegram-mcp client",
             bot_username: this.host.config.telegram.botUsername,
-            ...(this.host.config.distributed.gatewayToken
-                ? { gateway_token: this.host.config.distributed.gatewayToken }
+            ...(this.host.config.distributed.gatewayScopeToken
+                ? { gateway_token: this.host.config.distributed.gatewayScopeToken }
                 : {}),
             meta: {
                 telegram_chat_id: principal.telegramChatId,

package/dist/services/features/telegram-mcp/src/shared/lib/gatewayScope.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeGatewayToken = normalizeGatewayToken;
-exports.gatewayTokenToScopeKey = gatewayTokenToScopeKey;
+exports.gatewayScopeTokenToScopeKey = gatewayScopeTokenToScopeKey;
 exports.resolveGatewayScopeKey = resolveGatewayScopeKey;
 const node_crypto_1 = require("node:crypto");
 function normalizeGatewayToken(value) {
@@ -11,13 +11,13 @@ function normalizeGatewayToken(value) {
     const token = value.trim();
     return token ? token : null;
 }
-function gatewayTokenToScopeKey(token) {
+function gatewayScopeTokenToScopeKey(token) {
     return (0, node_crypto_1.createHash)("sha256").update(token).digest("hex");
 }
 function resolveGatewayScopeKey(input) {
-    const gatewayToken = normalizeGatewayToken(input.gateway_token);
-    if (gatewayToken) {
-        return gatewayTokenToScopeKey(gatewayToken);
+    const gatewayScopeToken = normalizeGatewayToken(input.gateway_token);
+    if (gatewayScopeToken) {
+        return gatewayScopeTokenToScopeKey(gatewayScopeToken);
     }
     const scopeKey = normalizeGatewayToken(input.scope_key);
     return scopeKey;

package/dist/services/features/telegram-mcp/src/shared/lib/project-identity/projectIdentity.js

@@ -117,6 +117,10 @@ function readSessionMarkerState(inputCwd, logger) {
                 parsed.last_notified_tools_hash.trim()
                 ? { lastNotifiedToolsHash: parsed.last_notified_tools_hash.trim() }
                 : {}),
+            ...(typeof parsed.gateway_client_uuid === "string" &&
+                parsed.gateway_client_uuid.trim()
+                ? { gatewayClientUuid: parsed.gateway_client_uuid.trim() }
+                : {}),
             ...(typeof parsed.updated_at === "string" && parsed.updated_at.trim()
                 ? { updatedAt: parsed.updated_at.trim() }
                 : {}),
@@ -166,6 +170,12 @@ function writeSessionMarkerState(input) {
                 : current?.lastNotifiedToolsHash
                     ? { last_notified_tools_hash: current.lastNotifiedToolsHash }
                     : {}),
+            ...(typeof input.gatewayClientUuid === "string" &&
+                input.gatewayClientUuid.trim()
+                ? { gateway_client_uuid: input.gatewayClientUuid.trim() }
+                : current?.gatewayClientUuid
+                    ? { gateway_client_uuid: current.gatewayClientUuid }
+                    : {}),
             created_at: now,
             updated_at: now,
             ...(current ? { first_seen_local_session_id: current.localSessionId } : {}),

package/docs/STANDALONE-ru.md

@@ -24,7 +24,18 @@
 ## 1. Установка
 
 ```bash
-npm install -g @deadragdoll/tellymcp
+sudo apt install -y python3 make g++
+npm config set ignore-scripts false
+npm install -g @deadragdoll/tellymcp --foreground-scripts
+```
+
+На Linux native addon `node-pty` собирается локально; для Linux ARM64 это
+обязательно, потому что зависимость не поставляет подходящий готовый binary.
+Если после предыдущей установки `pty.node` отсутствует, выполни:
+
+```bash
+npm uninstall -g @deadragdoll/tellymcp
+npm install -g @deadragdoll/tellymcp@latest --foreground-scripts
 ```
 
 Опционально:
@@ -64,7 +75,7 @@ DB_PASSWORD=
 DB_NAME=
 GATEWAY_PUBLIC_URL=https://your-domain.example/api/gateway
 GATEWAY_WS_URL=wss://your-domain.example/api/gateway/ws
-GATEWAY_TOKEN=change_me_gateway_token
+GATEWAY_SCOPE_TOKEN=change_me_scope_token
 GATEWAY_AUTH_TOKEN=put_strong_shared_transport_token_here
 ROOT_PREFIX=/api
 PORT=8080
@@ -83,13 +94,16 @@ DISTRIBUTED_MODE=gateway
 DISTRIBUTED_MODE=client
 GATEWAY_PUBLIC_URL=https://your-domain.example/api/gateway
 GATEWAY_WS_URL=wss://your-domain.example/api/gateway/ws
-GATEWAY_TOKEN=change_me_gateway_token
+GATEWAY_SCOPE_TOKEN=change_me_scope_token
 GATEWAY_AUTH_TOKEN=put_strong_shared_transport_token_here
 GATEWAY_USER_UUID=put_owner_uuid_here
 ```
 
+На машине agent/client Redis не нужен. Временное runtime-состояние хранится
+локально, а стабильный gateway client UUID — в `.mcpsession.json`.
+
 Используйте один и тот же стойкий `GATEWAY_AUTH_TOKEN` на gateway и всех клиентах.
-Не смешивайте его с `GATEWAY_TOKEN`: последний разделяет данные gateway по scope,
+Не смешивайте его с `GATEWAY_SCOPE_TOKEN`: последний разделяет данные gateway по scope,
 но не аутентифицирует HTTP- или WebSocket-транспорт. Сгенерируйте токен один раз,
 например командой `openssl rand -hex 32`, и не используйте пример значения выше.
 
@@ -192,10 +206,22 @@ http://127.0.0.1:8787/mcp
 
 ## 9. Проверки
 
+Настройка dotenv через локальный web-конфигуратор:
+
+```bash
+tellymcp configure
+```
+
 ```bash
 tellymcp doctor --env .env
 ```
 
+Перед запуском старый env можно нормализовать командой:
+
+```bash
+tellymcp migrate-env ./old.env > ./.migrated-env
+```
+
 Разрушительная очистка:
 
 ```bash

package/docs/STANDALONE.md

@@ -24,7 +24,18 @@ The recommended topology is:
 ## 1. Install
 
 ```bash
-npm install -g @deadragdoll/tellymcp
+sudo apt install -y python3 make g++
+npm config set ignore-scripts false
+npm install -g @deadragdoll/tellymcp --foreground-scripts
+```
+
+Linux installs compile the native `node-pty` addon locally; this is required on
+Linux ARM64 because the dependency does not ship a matching prebuilt binary.
+If `pty.node` is missing after an earlier install, run:
+
+```bash
+npm uninstall -g @deadragdoll/tellymcp
+npm install -g @deadragdoll/tellymcp@latest --foreground-scripts
 ```
 
 Optional:
@@ -64,7 +75,7 @@ DB_PASSWORD=
 DB_NAME=
 GATEWAY_PUBLIC_URL=https://your-domain.example/api/gateway
 GATEWAY_WS_URL=wss://your-domain.example/api/gateway/ws
-GATEWAY_TOKEN=change_me_gateway_token
+GATEWAY_SCOPE_TOKEN=change_me_scope_token
 GATEWAY_AUTH_TOKEN=put_strong_shared_transport_token_here
 ROOT_PREFIX=/api
 PORT=8080
@@ -83,13 +94,16 @@ Minimum client settings:
 DISTRIBUTED_MODE=client
 GATEWAY_PUBLIC_URL=https://your-domain.example/api/gateway
 GATEWAY_WS_URL=wss://your-domain.example/api/gateway/ws
-GATEWAY_TOKEN=change_me_gateway_token
+GATEWAY_SCOPE_TOKEN=change_me_scope_token
 GATEWAY_AUTH_TOKEN=put_strong_shared_transport_token_here
 GATEWAY_USER_UUID=put_owner_uuid_here
 ```
 
+The agent/client machine does not need Redis. Its transient runtime state is
+local, while the stable gateway client UUID is stored in `.mcpsession.json`.
+
 Use the same strong `GATEWAY_AUTH_TOKEN` on the gateway and every client. Keep it
-separate from `GATEWAY_TOKEN`, which scopes gateway data but does not authenticate
+separate from `GATEWAY_SCOPE_TOKEN`, which scopes gateway data but does not authenticate
 the HTTP or WebSocket transport. Generate it once, for example with
 `openssl rand -hex 32`, and do not use the illustrative value above.
 
@@ -192,10 +206,22 @@ Use the MCP HTTP endpoint exposed by `tellymcp run`.
 
 ## 9. Health Checks
 
+Guided dotenv setup:
+
+```bash
+tellymcp configure
+```
+
 ```bash
 tellymcp doctor --env .env
 ```
 
+Normalize a legacy env before startup:
+
+```bash
+tellymcp migrate-env ./old.env > ./.migrated-env
+```
+
 Destructive cleanup:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deadragdoll/tellymcp",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "description": "TellyMCP - Telegram control plane for MCP-connected coding agents",
   "main": "dist/services/features/telegram-mcp/runtime.service.js",
   "bin": {

package/scripts/postinstall.js

@@ -15,11 +15,46 @@ function line(value = "") {
   process.stdout.write(`${value}\n`);
 }
 
+function checkNativePty() {
+  try {
+    const nodePty = require("node-pty");
+    return typeof nodePty.spawn === "function"
+      ? { available: true }
+      : {
+          available: false,
+          message: "node-pty loaded without a spawn function.",
+        };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      available: false,
+      message: message.split("\n", 1)[0] || "node-pty failed to load.",
+    };
+  }
+}
+
 line();
 line(`${pc.bold(pc.cyan("TellyMCP"))} ${pc.dim("installed")}`);
 line();
 
-line(`${pc.green("OK")} Built-in PTY terminal runtime is enabled.`);
+const nativePty = checkNativePty();
+if (nativePty.available) {
+  line(`${pc.green("OK")} Built-in PTY native module loaded.`);
+} else {
+  line(`${pc.red("ERROR")} Built-in PTY native module is unavailable.`);
+  line(`  ${nativePty.message}`);
+  line(
+    `  Platform: ${process.platform}-${process.arch}, Node ${process.versions.node}`,
+  );
+  if (process.platform === "linux") {
+    line("  Debian/Ubuntu prerequisites: sudo apt install -y python3 make g++");
+  }
+  line("  Ensure scripts are enabled: npm config set ignore-scripts false");
+  line("  Remove broken install: npm uninstall -g @deadragdoll/tellymcp");
+  line(
+    "  Reinstall: npm install -g @deadragdoll/tellymcp@latest --foreground-scripts",
+  );
+}
 
 line();
 line(`${pc.yellow("INFO")} Browser tools need Playwright browser binaries.`);