@deadragdoll/tellymcp 0.0.9 → 0.0.11

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

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TELEGRAM_MCP_XCHANGE_SERVICE_NAME = void 0;
+const runtime_service_1 = require("./runtime.service");
+const remoteConsoleActionClient_1 = require("./src/features/distributed-gateway/model/remoteConsoleActionClient");
+const xchangeService_1 = require("./src/features/xchange/model/xchangeService");
+exports.TELEGRAM_MCP_XCHANGE_SERVICE_NAME = "telegramMcp.xchange";
+const TelegramMcpXchangeService = {
+    name: exports.TELEGRAM_MCP_XCHANGE_SERVICE_NAME,
+    dependencies: [runtime_service_1.TELEGRAM_MCP_RUNTIME_SERVICE_NAME],
+    actions: {
+        listRecordsRemote: {
+            params: {
+                $$strict: false,
+                session_id: { type: "string", optional: true, trim: true, min: 1 },
+                status: {
+                    type: "enum",
+                    optional: true,
+                    values: ["new", "read", "archived"],
+                },
+                category: {
+                    type: "enum",
+                    optional: true,
+                    values: [
+                        "partner_note",
+                        "local_handoff",
+                        "telegram_message",
+                    ],
+                },
+                direction: {
+                    type: "enum",
+                    optional: true,
+                    values: ["incoming", "outgoing", "local"],
+                },
+                limit: { type: "number", integer: true, positive: true, optional: true },
+            },
+            async handler(ctx) {
+                return this.getXchangeService().listRecords(ctx.params);
+            },
+        },
+        getRecordRemote: {
+            params: {
+                $$strict: false,
+                session_id: { type: "string", optional: true, trim: true, min: 1 },
+                record_id: { type: "string", trim: true, min: 1 },
+            },
+            async handler(ctx) {
+                return this.getXchangeService().getRecord(ctx.params);
+            },
+        },
+        markReadRemote: {
+            params: {
+                $$strict: false,
+                session_id: { type: "string", optional: true, trim: true, min: 1 },
+                record_id: { type: "string", trim: true, min: 1 },
+            },
+            async handler(ctx) {
+                return this.getXchangeService().markRead(ctx.params);
+            },
+        },
+        listFileMetasRemote: {
+            params: {
+                $$strict: false,
+                session_id: { type: "string", optional: true, trim: true, min: 1 },
+                source: {
+                    type: "enum",
+                    optional: true,
+                    values: [
+                        "telegram-upload",
+                        "browser-screenshot",
+                        "partner-artifact",
+                    ],
+                },
+            },
+            async handler(ctx) {
+                return this.getXchangeService().listFileMetas(ctx.params);
+            },
+        },
+        getFileMetaRemote: {
+            params: {
+                $$strict: false,
+                session_id: { type: "string", optional: true, trim: true, min: 1 },
+                file_path: { type: "string", trim: true, min: 1 },
+            },
+            async handler(ctx) {
+                return this.getXchangeService().getFileMeta(ctx.params);
+            },
+        },
+        deleteFileMetaRemote: {
+            params: {
+                $$strict: false,
+                session_id: { type: "string", optional: true, trim: true, min: 1 },
+                file_path: { type: "string", trim: true, min: 1 },
+            },
+            async handler(ctx) {
+                return this.getXchangeService().deleteFileMeta(ctx.params);
+            },
+        },
+    },
+    created() {
+        this.xchangeService = null;
+    },
+    methods: {
+        getXchangeService() {
+            if (!this.xchangeService) {
+                throw new Error("telegram_mcp xchange service is not initialized yet");
+            }
+            return this.xchangeService;
+        },
+    },
+    async started() {
+        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`);
+        }
+        const runtime = await runtimeService.waitUntilReady();
+        this.logger.info("Starting telegram_mcp xchange service");
+        this.xchangeService = new xchangeService_1.XchangeService(runtime.config, runtime.sessionStore, runtime.stateStore, runtime.stateStore, runtime.logger, runtime.projectIdentityResolver, new remoteConsoleActionClient_1.RemoteConsoleActionClient((actionName, params) => this.broker.call(actionName, params, { meta: { internal_call: true } })));
+        this.logger.info("telegram_mcp xchange service is ready");
+    },
+};
+exports.default = TelegramMcpXchangeService;

package/docs/STANDALONE-ru.md

@@ -0,0 +1,172 @@
+<div align="center">
+
+# Standalone Deployment
+
+**Развёртывание TellyMCP как одного gateway и одной или нескольких agent-консолей**
+
+[English](./STANDALONE.md) · [Русский](./STANDALONE-ru.md) · [Main README](../README.md) · [README RU](../README-ru.md)
+
+[![npm version](https://img.shields.io/npm/v/@deadragdoll/tellymcp.svg)](https://www.npmjs.com/package/@deadragdoll/tellymcp)
+[![node](https://img.shields.io/badge/node-%3E%3D24-339933.svg)](https://nodejs.org/)
+[![gateway mode](https://img.shields.io/badge/deploy-gateway%20%2B%20agents-1f6feb.svg)](../README-ru.md#текущая-модель)
+[![telegram webhook](https://img.shields.io/badge/telegram-webhook%20ready-26A5E4.svg)](../README-ru.md#webhook)
+
+</div>
+
+Этот файл описывает текущую standalone-модель для `@deadragdoll/tellymcp`.
+
+Рекомендуемая топология:
+
+- один gateway node
+- одна или несколько agent nodes
+- один общий Telegram-бот на gateway
+
+## 1. Установка
+
+```bash
+npm install -g @deadragdoll/tellymcp
+```
+
+Опционально:
+
+```bash
+tellymcp browser install
+tellymcp codex-plugin install
+```
+
+## 2. Инфраструктура
+
+Для gateway обязательно:
+
+- Redis
+- PostgreSQL
+
+Опционально:
+
+- RabbitMQ
+
+## 3. Gateway Env
+
+Стартовая точка:
+
+- [.env.example.gateway](../.env.example.gateway)
+
+Минимально нужные параметры gateway:
+
+```env
+TELEGRAM_BOT_TOKEN=
+REDIS_HOST=127.0.0.1
+DB_HOST=127.0.0.1
+DB_USER=
+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
+ROOT_PREFIX=/api
+PORT=8080
+DISTRIBUTED_MODE=gateway
+```
+
+## 4. Agent Env
+
+Стартовая точка:
+
+- [.env.example.client](../.env.example.client)
+
+Минимально нужные параметры agent:
+
+```env
+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_USER_UUID=put_owner_uuid_here
+```
+
+Для первого запуска также желательно задать:
+
+```env
+TELLYMCP_SESSION_ID=NEW
+TELLYMCP_SESSION_LABEL=NEW
+```
+
+## 5. Запуск
+
+Gateway:
+
+```bash
+tellymcp run --env .env
+```
+
+Agent:
+
+```bash
+tellymcp run --env .env -s NEW
+```
+
+После того как в workspace появится `.mcpsession.json`, дальше обычно достаточно:
+
+```bash
+tellymcp run
+```
+
+## 6. Webhook
+
+Gateway поддерживает polling и webhook.
+
+Нужные env:
+
+```env
+TELEGRAM_WEBHOOK_ENABLED=true
+TELEGRAM_WEBHOOK_PATH=/telegram/webhook
+TELEGRAM_WEBHOOK_PUBLIC_URL=https://your-domain.example/api/telegram/webhook
+TELEGRAM_WEBHOOK_SECRET=change_me_webhook_secret
+```
+
+Если nginx уже проксирует `location /api/ { ... }` на standalone listener, этот же блок покроет:
+
+- `/api/telegram/webhook`
+- `/api/gateway`
+- `/api/webapp`
+- `/api/healthz`
+
+## 7. MCP
+
+Локальный client-mode MCP endpoint:
+
+```text
+http://127.0.0.1:8787/mcp
+```
+
+Используй MCP HTTP endpoint, который поднимает `tellymcp run`.
+
+## 8. Проверки
+
+```bash
+tellymcp doctor --env .env
+```
+
+Разрушительная очистка:
+
+```bash
+tellymcp system-prune --env .env --yes
+```
+
+## 9. Операционные заметки
+
+- gateway-бот — это основной user-facing control plane
+- консоли видны из gateway live registry
+- межсессионные задачи идут через xchange records и `partner_note`
+- ответы человеку в Telegram идут через `notify_telegram`
+- browser screenshot для человека лучше отправлять через `browser_screenshot(send_to_telegram=true)`
+- файлы между консолями лучше отправлять через `send_partner_file`
+
+## 10. Чего не делать в новых setup
+
+Не строй новые setup вокруг:
+
+- pairing codes
+- inbox polling APIs
+- `Local` linked-session меню
+- старых session-link workflow

package/docs/STANDALONE.md

@@ -0,0 +1,172 @@
+<div align="center">
+
+# Standalone Deployment
+
+**Deploy TellyMCP as one gateway and one or more agent nodes**
+
+[English](./STANDALONE.md) · [Русский](./STANDALONE-ru.md) · [Main README](../README.md) · [README RU](../README-ru.md)
+
+[![npm version](https://img.shields.io/npm/v/@deadragdoll/tellymcp.svg)](https://www.npmjs.com/package/@deadragdoll/tellymcp)
+[![node](https://img.shields.io/badge/node-%3E%3D24-339933.svg)](https://nodejs.org/)
+[![gateway mode](https://img.shields.io/badge/deploy-gateway%20%2B%20agents-1f6feb.svg)](../README.md#current-runtime-model)
+[![telegram webhook](https://img.shields.io/badge/telegram-webhook%20ready-26A5E4.svg)](../README.md#webhook-mode)
+
+</div>
+
+This guide describes the current standalone deployment model for `@deadragdoll/tellymcp`.
+
+The recommended topology is:
+
+- one gateway node
+- one or more agent nodes
+- one shared Telegram bot on the gateway
+
+## 1. Install
+
+```bash
+npm install -g @deadragdoll/tellymcp
+```
+
+Optional:
+
+```bash
+tellymcp browser install
+tellymcp codex-plugin install
+```
+
+## 2. Infrastructure
+
+Required for gateway:
+
+- Redis
+- PostgreSQL
+
+Optional:
+
+- RabbitMQ
+
+## 3. Gateway Env
+
+Start from:
+
+- [.env.example.gateway](../.env.example.gateway)
+
+Minimum gateway settings:
+
+```env
+TELEGRAM_BOT_TOKEN=
+REDIS_HOST=127.0.0.1
+DB_HOST=127.0.0.1
+DB_USER=
+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
+ROOT_PREFIX=/api
+PORT=8080
+DISTRIBUTED_MODE=gateway
+```
+
+## 4. Agent Env
+
+Start from:
+
+- [.env.example.client](../.env.example.client)
+
+Minimum client settings:
+
+```env
+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_USER_UUID=put_owner_uuid_here
+```
+
+For the first run, also set:
+
+```env
+TELLYMCP_SESSION_ID=NEW
+TELLYMCP_SESSION_LABEL=NEW
+```
+
+## 5. Run
+
+Gateway:
+
+```bash
+tellymcp run --env .env
+```
+
+Agent:
+
+```bash
+tellymcp run --env .env -s NEW
+```
+
+After `.mcpsession.json` is created in the workspace, later runs can usually use:
+
+```bash
+tellymcp run
+```
+
+## 6. Webhook
+
+Gateway supports polling and webhook.
+
+Webhook env:
+
+```env
+TELEGRAM_WEBHOOK_ENABLED=true
+TELEGRAM_WEBHOOK_PATH=/telegram/webhook
+TELEGRAM_WEBHOOK_PUBLIC_URL=https://your-domain.example/api/telegram/webhook
+TELEGRAM_WEBHOOK_SECRET=change_me_webhook_secret
+```
+
+If nginx already proxies `location /api/ { ... }` to the standalone listener, that block also covers:
+
+- `/api/telegram/webhook`
+- `/api/gateway`
+- `/api/webapp`
+- `/api/healthz`
+
+## 7. MCP
+
+Local client-mode MCP:
+
+```text
+http://127.0.0.1:8787/mcp
+```
+
+Use the MCP HTTP endpoint exposed by `tellymcp run`.
+
+## 8. Health Checks
+
+```bash
+tellymcp doctor --env .env
+```
+
+Destructive cleanup:
+
+```bash
+tellymcp system-prune --env .env --yes
+```
+
+## 9. Operational Notes
+
+- the gateway bot is the user-facing control plane
+- consoles are discovered from the gateway live registry
+- cross-console tasks use xchange records and `partner_note`
+- human Telegram replies use `notify_telegram`
+- browser screenshot replies to humans should use `browser_screenshot(send_to_telegram=true)`
+- file results between consoles should use `send_partner_file`
+
+## 10. Legacy Concepts To Avoid
+
+Do not build new setups around:
+
+- pairing codes
+- inbox polling APIs
+- `Local` linked-session menus
+- old session-link workflows

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deadragdoll/tellymcp",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "TellyMCP - Telegram control plane for MCP-connected coding agents",
   "main": "dist/services/features/telegram-mcp/runtime.service.js",
   "bin": {
@@ -10,10 +10,11 @@
     "dist",
     "scripts",
     "config/templates",
+    "config/codex",
     "README.md",
     "README-ru.md",
-    "STANDALONE.md",
-    "STANDALONE-ru.md",
+    "docs/STANDALONE.md",
+    "docs/STANDALONE-ru.md",
     "VERSION.md",
     "CHANGELOG.md",
     "TOOLS.md",
@@ -38,10 +39,11 @@
     "prepack": "yarn build",
     "prepublishOnly": "yarn build && yarn lint && yarn test",
     "mcp:local": "codex mcp add telegramHuman --url http://127.0.0.1:8787/mcp",
-    "dev:gw": "TS_NODE_TRANSPILE_ONLY=1 TS_NODE_EXPERIMENTAL_RESOLVER=1 NODE_OPTIONS=--openssl-legacy-provider ts-node ./node_modules/moleculer/bin/moleculer-runner.js src/services --config src/moleculer.config.ts --envfile ./.env-dev --hot --mask \"**/*.service.ts\"",
+    "dev:gw": "TS_NODE_TRANSPILE_ONLY=1 TS_NODE_EXPERIMENTAL_RESOLVER=1 NODE_OPTIONS=--openssl-legacy-provider ts-node ./node_modules/moleculer/bin/moleculer-runner.js src/services --config src/moleculer.config.ts --envfile /opt/tellymcp-gateway/.env-gateway --hot --mask \"**/*.service.ts\"",
     "dev:builder": "TS_NODE_TRANSPILE_ONLY=1 TS_NODE_EXPERIMENTAL_RESOLVER=1 NODE_OPTIONS=--openssl-legacy-provider ts-node ./node_modules/moleculer/bin/moleculer-runner.js src/services --config src/moleculer.config.ts --envfile ./.env-builder --hot --mask \"**/*.service.ts\"",
     "dev:gw:telegram": "TS_NODE_TRANSPILE_ONLY=1 TS_NODE_EXPERIMENTAL_RESOLVER=1 NODE_OPTIONS=--openssl-legacy-provider ts-node ./node_modules/moleculer/bin/moleculer-runner.js src/services/features/telegram-mcp --config src/moleculer.config.ts --envfile ./.env-dev --hot --mask \"**/*.service.ts\"",
     "dev:client": "TS_NODE_TRANSPILE_ONLY=1 TS_NODE_EXPERIMENTAL_RESOLVER=1 NODE_OPTIONS=--openssl-legacy-provider ts-node ./node_modules/moleculer/bin/moleculer-runner.js src/services --config src/moleculer.config.ts --envfile ./.env-client --hot --mask \"**/*.service.ts\"",
+    "dev:sh": "TELLYMCP_SOURCE_RUNTIME=true tsx src/cli.ts run --env ./.env-client",
     "dev": "yarn dev:gw",
     "dev:watch": "yarn dev:gw",
     "dev:service": "yarn dev:gw",
@@ -72,16 +74,19 @@
     "@grammyjs/menu": "^1.3.1",
     "@grammyjs/storage-redis": "^2.5.1",
     "@modelcontextprotocol/sdk": "^1.18.1",
+    "@xterm/headless": "5.5.0",
+    "@xterm/xterm": "5.5.0",
     "amqplib": "0.10.9",
     "dotenv": "^17.4.2",
     "grammy": "1.43.0",
     "https-proxy-agent": "^7.0.6",
+    "i18next": "^26.2.0",
     "ioredis": "5.10.1",
     "knex": "^3.2.10",
     "mime-types": "^3.0.2",
     "module-alias": "^2.3.4",
     "moleculer": "0.15.0",
-    "node-fetch": "^3.3.2",
+    "node-pty": "^1.1.0",
     "pg": "^8.20.0",
     "picocolors": "^1.1.1",
     "pino": "^10.3.1",
@@ -96,6 +101,7 @@
     "@types/amqplib": "^0.10.8",
     "@types/mime-types": "^3.0.1",
     "@types/node": "24.12.4",
+    "@types/pg": "^8.20.0",
     "eslint": "^9.34.0",
     "eslint-import-resolver-typescript": "^4.4.4",
     "eslint-plugin-import": "^2.32.0",

package/scripts/build-package-artifact.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+DOCKER_IMAGE="${DOCKER_IMAGE:-node:24-bookworm-slim}"
+
+echo "Building TellyMCP package artifact inside ${DOCKER_IMAGE}"
+
+rm -f deadragdoll-tellymcp-*.tgz
+
+docker run --rm \
+  -u "$(id -u):$(id -g)" \
+  -e HOME=/tmp/tellymcp-build-home \
+  -e npm_config_cache=/tmp/tellymcp-npm-cache \
+  -v "${PWD}:/work" \
+  -w /work \
+  "${DOCKER_IMAGE}" \
+  bash -lc '
+    set -euo pipefail
+    mkdir -p "$HOME" "$npm_config_cache"
+    npx -y yarn@1.22.22 install --frozen-lockfile
+    npx -y yarn@1.22.22 lint
+    npx -y yarn@1.22.22 test
+    npm pack
+  '
+
+echo "Built package artifacts:"
+ls -1 deadragdoll-tellymcp-*.tgz

package/scripts/deploy-gateway.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+GATEWAY_ENV_FILE="${GATEWAY_ENV_FILE:-}"
+DEPLOY_TAG="${CI_COMMIT_TAG:-}"
+LOG_HOST_DIR="${LOG_HOST_DIR:-}"
+
+if [[ -z "${GATEWAY_ENV_FILE}" ]]; then
+  echo "GATEWAY_ENV_FILE is required." >&2
+  exit 1
+fi
+
+if [[ ! -f "${GATEWAY_ENV_FILE}" ]]; then
+  echo "Missing gateway env file: ${GATEWAY_ENV_FILE}" >&2
+  exit 1
+fi
+
+ARCHIVE="$(find . -maxdepth 1 -type f -name 'deadragdoll-tellymcp-*.tgz' | sort | tail -n 1)"
+if [[ -z "${ARCHIVE}" ]]; then
+  echo "No deadragdoll-tellymcp-*.tgz artifact found in current workspace." >&2
+  exit 1
+fi
+
+extract_package_version() {
+  local package_json
+  package_json="$(<package.json)"
+  sed -n 's/^[[:space:]]*"version":[[:space:]]*"\([^"]*\)".*$/\1/p' \
+    <<<"${package_json}" \
+    | head -n 1
+}
+
+PACKAGE_VERSION="$(extract_package_version)"
+if [[ -z "${PACKAGE_VERSION}" ]]; then
+  echo "Failed to extract version from package.json" >&2
+  exit 1
+fi
+if [[ -n "${DEPLOY_TAG}" ]]; then
+  if [[ "${DEPLOY_TAG}" != "${PACKAGE_VERSION}" && "${DEPLOY_TAG}" != "v${PACKAGE_VERSION}" ]]; then
+    echo "Tag ${DEPLOY_TAG} does not match package.json version ${PACKAGE_VERSION}" >&2
+    exit 1
+  fi
+fi
+
+if [[ -z "${LOG_HOST_DIR}" ]]; then
+  LOG_HOST_DIR="$(dirname "${GATEWAY_ENV_FILE}")/.tellymcp"
+fi
+
+mkdir -p "${LOG_HOST_DIR}"
+
+export TELLYMCP_VERSION="${PACKAGE_VERSION}"
+export GATEWAY_ENV_FILE
+export LOG_HOST_DIR
+
+echo "Deploying TellyMCP gateway ${TELLYMCP_VERSION}"
+echo "Artifact: ${ARCHIVE}"
+echo "Gateway env: ${GATEWAY_ENV_FILE}"
+echo "Log host dir: ${LOG_HOST_DIR}"
+
+echo "Rebuilding gateway container stack"
+docker compose build --pull tellymcp-gateway
+docker compose up -d --force-recreate
+
+echo "Gateway deployment completed"
+docker compose ps

package/scripts/deploy-onebot-branch.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PROJECT_DIR="${CI_PROJECT_DIR:-$(pwd)}"
+
+if [[ ! -d "${PROJECT_DIR}" ]]; then
+  echo "Missing project directory: ${PROJECT_DIR}" >&2
+  exit 1
+fi
+
+cd "${PROJECT_DIR}"
+
+PACKAGE_ARCHIVE="$(find . -maxdepth 1 -type f -name 'deadragdoll-tellymcp-*.tgz' | sort | tail -n 1)"
+
+if [[ -z "${PACKAGE_ARCHIVE}" ]]; then
+  echo "Missing package archive in ${PROJECT_DIR}. Expected deadragdoll-tellymcp-*.tgz artifact." >&2
+  exit 1
+fi
+
+echo "Installing TellyMCP from archive: ${PACKAGE_ARCHIVE}"
+npm install -g "${PACKAGE_ARCHIVE}"
+
+echo "Installed version:"
+tellymcp help | sed -n '1,2p'
+
+echo "Restarting existing PM2 instance 0"
+pm2 restart 0