@deadragdoll/tellymcp 0.0.14 → 0.0.16

package/.env.example.client

@@ -1,21 +1,14 @@
-# TellyMCP client example
+# TellyMCP agent-console example. See docs/ENVIRONMENT.md for the complete contract.
 
-# Optional project label shown in prompts.
+# Workspace identity. NEW generates a stable value on first run.
 # PROJECT_NAME=
+TELLYMCP_SESSION_ID=NEW
+TELLYMCP_SESSION_LABEL=NEW
 
-# Optional explicit session identity for the first run.
-# TELLYMCP_SESSION_ID=NEW
-# TELLYMCP_SESSION_LABEL=NEW
-
-REDIS_HOST=127.0.0.1
-REDIS_PORT=6379
-REDIS_DB=1
-# REDIS_USERNAME=
-# REDIS_PASSWORD=
-
-MODE=reject
-PAIR_CODE_TTL_SECONDS=300
+# Local runtime state is process-local; Redis is not used by clients.
+TELEGRAM_REQUEST_MODE=reject
 
+# Local MCP endpoint exposed to the agent.
 MCP_HTTP_HOST=127.0.0.1
 MCP_HTTP_PORT=8787
 MCP_HTTP_PATH=/mcp
@@ -23,25 +16,26 @@ MCP_HTTP_PATH=/mcp
 MCP_HTTP_ENABLE_DEBUG_ROUTES=false
 MCP_HTTP_ENABLE_PRUNE_ROUTE=false
 
+# Gateway connection.
 DISTRIBUTED_MODE=client
 GATEWAY_PUBLIC_URL=https://your-domain.example/api/gateway
 GATEWAY_WS_URL=wss://your-domain.example/api/gateway/ws
-GATEWAY_WS_PATH=/api/gateway/ws
-GATEWAY_TOKEN=change_me_gateway_token
+# GATEWAY_WS_PATH=/api/gateway/ws
+# Optional data-scope key. Must match the gateway when used.
+GATEWAY_SCOPE_TOKEN=change_me_scope_token
+# Optional owner binding for Telegram visibility.
 GATEWAY_USER_UUID=
-GATEWAY_AUTH_TOKEN=
+# Required shared HTTP/WebSocket transport credential.
+GATEWAY_AUTH_TOKEN=change_me_transport_token
 
+# Built-in PTY runtime.
 TERMINAL_SHELL=bash
 TERMINAL_COLS=120
 TERMINAL_ROWS=40
 TERMINAL_SCROLLBACK_LINES=4000
-
 TERMINAL_NUDGE_ENABLED=true
 TERMINAL_NUDGE_DEBOUNCE_SECONDS=10
 TERMINAL_NUDGE_COOLDOWN_SECONDS=30
-TERMINAL_NUDGE_MESSAGE=получи newest telegram_message через list_xchange_records/get_xchange_record, выполни запрос и ответь человеку через notify_telegram; не останавливайся на анализе
-TERMINAL_PARTNER_NUDGE_MESSAGE=получи newest partner_note через list_xchange_records/get_xchange_record, выполни задачу в текущей консоли и обязательно отправь результат через send_partner_note или send_partner_file; только потом mark_xchange_record_read
-TERMINAL_PARTNER_REPLY_NUDGE_MESSAGE=получи newest partner_note через list_xchange_records/get_xchange_record; если newest note имеет kind=reply или не требует ответа, не отправляй новый send_partner_note/send_partner_file без явного нового запроса. Если этот reply завершает задачу от человека, сразу отправь финальный результат в Telegram через notify_telegram или send_file_to_telegram; только потом mark_xchange_record_read
 TERMINAL_CAPTURE_MODE=visible
 TERMINAL_CAPTURE_LINES=300
 TERMINAL_PROMPT_SCAN_ENABLED=true
@@ -49,18 +43,8 @@ TERMINAL_PROMPT_SCAN_INTERVAL_SECONDS=15
 TERMINAL_PROMPT_SCAN_COOLDOWN_SECONDS=120
 TERMINAL_PROMPT_SCAN_STRATEGY=strict
 TERMINAL_PROMPT_SCAN_MIN_SCORE=5
-WEBAPP_ENABLED=true
-WEBAPP_BASE_PATH=/webapp
-WEBAPP_PUBLIC_URL=https://your-domain.example/api/webapp
-WEBAPP_INITDATA_TTL_SECONDS=300
-WEBAPP_SESSION_TTL_SECONDS=900
-WEBAPP_LAUNCH_MODE=fullscreen
-WEBAPP_VISIBLE_SCREENS=10
-WEBAPP_POLL_INTERVAL_MS=2000
-WEBAPP_ACTION_COOLDOWN_MS=150
-
-MCP_XCHANGE_DIR=.mcp-xchange
 
+# Browser automation and optional attach bridge.
 BROWSER_ENABLED=true
 BROWSER_HEADLESS=false
 BROWSER_DEVTOOLS=false
@@ -76,16 +60,12 @@ BROWSER_SLOW_MO_MS=0
 # BROWSER_ATTACH_WS_PORT=9999
 # BROWSER_ATTACH_WS_PATH=/browser-attach/ws
 
+MCP_XCHANGE_DIR=.mcp-xchange
 NAMESPACE=mcp
 NODE_ID=agent
-
-# Optional outbound proxy.
-# PROXY_USE=http
-# HTTP_PROXY=http://user:pass@proxy.example:3128
-# SOCKS5_PROXY=socks5h://user:pass@proxy.example:1080
-
 LOG_LEVEL=info
 LOG_FILE_ENABLED=false
 LOG_FILE_PATH=.tellymcp/log.jsonl
 # LOG_STDERR_LEVEL=error
-ENABLE_LOGFEED=0
+# LOG_FILE_LEVEL=info
+LOGFEED_ENABLED=false

package/.env.example.gateway

@@ -1,7 +1,35 @@
-# TellyMCP gateway example
+# TellyMCP gateway example. See docs/ENVIRONMENT.md for the complete contract.
 
+# Required gateway identity and infrastructure.
 TELEGRAM_BOT_TOKEN=
 TELEGRAM_BOT_USERNAME=
+REDIS_HOST=127.0.0.1
+REDIS_PORT=6379
+REDIS_DB=1
+# REDIS_USERNAME=
+# REDIS_PASSWORD=
+DB_HOST=127.0.0.1
+DB_PORT=5432
+DB_USER=user
+DB_PASSWORD=password
+DB_NAME=mydb
+DB_SCHEMA=mcp
+
+# Public gateway transport.
+DISTRIBUTED_MODE=gateway
+GATEWAY_PUBLIC_URL=https://your-domain.example/api/gateway
+GATEWAY_WS_URL=wss://your-domain.example/api/gateway/ws
+# Optional data-scope key. This is not an authentication credential.
+GATEWAY_SCOPE_TOKEN=change_me_scope_token
+# Required shared HTTP/WebSocket transport credential.
+GATEWAY_AUTH_TOKEN=change_me_transport_token
+ROOT_PREFIX=/api
+PORT=8080
+MCP_HTTP_HOST=0.0.0.0
+MCP_HTTP_PATH=/mcp
+
+# Request handling and operator access.
+TELEGRAM_REQUEST_MODE=reject
 # ADMIN_TOKEN=
 # DEBUG_LANGUAGE=ru
 
@@ -13,23 +41,12 @@ TELEGRAM_BOT_USERNAME=
 # TELEGRAM_WEBHOOK_TRACE=false
 # TELEGRAM_WEBHOOK_DROP_PENDING_UPDATES=false
 
-REDIS_HOST=127.0.0.1
-REDIS_PORT=6379
-REDIS_DB=1
-# REDIS_USERNAME=
-# REDIS_PASSWORD=
-
-MODE=reject
-PAIR_CODE_TTL_SECONDS=300
-
-MCP_HTTP_HOST=127.0.0.1
-MCP_HTTP_PORT=8787
-MCP_HTTP_PATH=/mcp
+# Optional static bearer auth for internal MCP clients.
 # MCP_HTTP_BEARER_TOKEN=
 MCP_HTTP_ENABLE_DEBUG_ROUTES=false
 MCP_HTTP_ENABLE_PRUNE_ROUTE=false
 
-# ChatGPT / Claude OAuth connector. Setting any OAuth value enables the facade.
+# ChatGPT / Claude OAuth facade. Setting any OAuth value enables it.
 # TELLYMCP_PUBLIC_URL=https://your-domain.example/api
 # TELLYMCP_OAUTH_ISSUER=https://your-domain.example/api
 # TELLYMCP_OAUTH_AUDIENCE=https://your-domain.example/api
@@ -43,26 +60,6 @@ MCP_HTTP_ENABLE_PRUNE_ROUTE=false
 # TELLYMCP_OAUTH_SCOPES=tellymcp:read tellymcp:write
 # TELLYMCP_OAUTH_KEY_ID=tellymcp-oauth
 
-DISTRIBUTED_MODE=gateway
-# Also used to derive short-lived file URLs under /api/files/.
-GATEWAY_PUBLIC_URL=https://your-domain.example/api/gateway
-GATEWAY_WS_URL=wss://your-domain.example/api/gateway/ws
-GATEWAY_WS_PATH=/api/gateway/ws
-GATEWAY_TOKEN=change_me_gateway_token
-GATEWAY_AUTH_TOKEN=
-
-ROOT_PREFIX=/api
-PORT=8080
-NAMESPACE=mcp
-NODE_ID=GWAY
-
-DB_HOST=127.0.0.1
-DB_PORT=5432
-DB_USER=
-DB_PASSWORD=
-DB_NAME=
-DB_SCHEME=mcp
-
 # Optional RabbitMQ fanout.
 # RMQ_HOST=127.0.0.1
 # RMQ_PORT=5672
@@ -71,54 +68,33 @@ DB_SCHEME=mcp
 # RMQ_VHOST=/
 # RMQ_EXCHANGE=telegram_mcp.gateway
 
+# Telegram Mini App.
 WEBAPP_ENABLED=true
 WEBAPP_BASE_PATH=/webapp
 WEBAPP_PUBLIC_URL=https://your-domain.example/api/webapp
 WEBAPP_INITDATA_TTL_SECONDS=300
 WEBAPP_SESSION_TTL_SECONDS=900
 WEBAPP_LAUNCH_MODE=fullscreen
-WEBAPP_VISIBLE_SCREENS=10
-WEBAPP_POLL_INTERVAL_MS=2000
+WEBAPP_VISIBLE_SCREENS=2
 WEBAPP_ACTION_COOLDOWN_MS=150
 
-MCP_XCHANGE_DIR=.mcp-xchange
-
-TERMINAL_SHELL=bash
-TERMINAL_COLS=120
-TERMINAL_ROWS=40
-TERMINAL_SCROLLBACK_LINES=4000
-
-TERMINAL_NUDGE_ENABLED=true
-TERMINAL_NUDGE_DEBOUNCE_SECONDS=10
-TERMINAL_NUDGE_COOLDOWN_SECONDS=30
-TERMINAL_NUDGE_MESSAGE=получи newest telegram_message через list_xchange_records/get_xchange_record, выполни запрос и ответь человеку через notify_telegram; не останавливайся на анализе
-TERMINAL_PARTNER_NUDGE_MESSAGE=получи newest partner_note через list_xchange_records/get_xchange_record, выполни задачу в текущей консоли и обязательно отправь результат через send_partner_note или send_partner_file; только потом mark_xchange_record_read
-TERMINAL_PARTNER_REPLY_NUDGE_MESSAGE=получи newest partner_note через list_xchange_records/get_xchange_record; если newest note имеет kind=reply или не требует ответа, не отправляй новый send_partner_note/send_partner_file без явного нового запроса. Если этот reply завершает задачу от человека, сразу отправь финальный результат в Telegram через notify_telegram или send_file_to_telegram; только потом mark_xchange_record_read
-TERMINAL_CAPTURE_MODE=visible
-TERMINAL_CAPTURE_LINES=300
+# Gateway-side terminal prompt detection.
 TERMINAL_PROMPT_SCAN_ENABLED=false
 TERMINAL_PROMPT_SCAN_INTERVAL_SECONDS=15
 TERMINAL_PROMPT_SCAN_COOLDOWN_SECONDS=120
 TERMINAL_PROMPT_SCAN_STRATEGY=strict
 TERMINAL_PROMPT_SCAN_MIN_SCORE=5
-BROWSER_ENABLED=false
-BROWSER_HEADLESS=false
-BROWSER_DEVTOOLS=false
-# BROWSER_ADDRESS=http://localhost:5173
-BROWSER_TIMEOUT_MS=20000
-BROWSER_MAX_EVENTS=200
-BROWSER_WAIT_UNTIL=load
-# BROWSER_EXECUTABLE_PATH=
-# BROWSER_CHANNEL=chrome
-BROWSER_SLOW_MO_MS=0
 
-# Optional outbound proxy.
+# Optional outbound proxy for Telegram.
 # PROXY_USE=http
 # HTTP_PROXY=http://user:pass@proxy.example:3128
 # SOCKS5_PROXY=socks5h://user:pass@proxy.example:1080
 
+NAMESPACE=mcp
+NODE_ID=gateway
 LOG_LEVEL=info
-LOG_FILE_ENABLED=true
+LOG_FILE_ENABLED=false
 LOG_FILE_PATH=.tellymcp/log.jsonl
 # LOG_STDERR_LEVEL=error
-ENABLE_LOGFEED=0
+# LOG_FILE_LEVEL=info
+LOGFEED_ENABLED=false

package/CHANGELOG.md

@@ -2,8 +2,33 @@
 
 ## Unreleased
 
+### Changed
+
+- CLI больше не загружает `node-pty` до разбора команды: `tellymcp --help`,
+  setup и diagnostics остаются доступны при отсутствующем native addon.
+  `doctor`, `run` и postinstall теперь реально проверяют `pty.node` и выводят
+  platform-aware инструкции для Linux ARM64, npm lifecycle scripts и чистой
+  переустановки пакета.
+- Исправлен `tellymcp doctor`: WebSocket probe больше не удаляет error-listeners
+  перед закрытием соединения и не падает с unhandled `WebSocket was closed before
+the connection was established` на HTTP reject, timeout или раннем close.
+- Redis теперь используется только в режимах gateway и `both`. Client runtime
+  больше не подключается к Redis и не требует `REDIS_*`; временное состояние
+  хранится локально в процессе, а стабильный `gateway_client_uuid` — в
+  `.mcpsession.json`. Клиентские шаблоны, migration, configure, doctor, prune и
+  runtime diagnostics приведены к этой модели.
+
 ### Added
 
+- Добавлен локальный web-конфигуратор `tellymcp configure`: browser wizard
+  предлагает выбрать Client или Gateway, показывает role-specific поля,
+  формирует HTTP/WS/WebApp/webhook/OAuth URL из одного Public base URL,
+  показывает русские hints и примеры, выполняет role-specific live-check
+  Telegram, Redis, PostgreSQL, gateway HTTP/WS и RabbitMQ, затем скачивает
+  `.env-client` либо `.env-gateway`.
+- Добавлен безопасный MCP tool `get_runtime_diagnostics` для end-to-end проверки
+  версии/protocol, принятой env-схемы, runtime state store, PTY, gateway config и
+  gateway-to-client relay без вывода секретов; Redis проверяется только на gateway.
 - Добавлены связанные MCP tools `get_file_list` и `get_file` для получения
   файлов из workspace выбранной live-консоли через gateway. Первый возвращает
   список managed files и точные пути, второй принимает `file_path` либо
@@ -24,6 +49,9 @@
 - Доступ к live `.env`, credential stores, private-key расширениям и чувствительным
   директориям теперь блокируется на клиенте до чтения или отправки файла; выход
   за workspace и через symlink по-прежнему запрещён.
+- Имена временных gateway-файлов очищаются до безопасного basename: управляющие
+  и файлово-зарезервированные символы заменяются перед сохранением и формированием
+  `Content-Disposition`.
 - Перенос `telegram_mcp` на сервисную архитектуру `Moleculer`:
   - `telegramMcp.runtime`
   - `telegramMcp.http`
@@ -143,6 +171,9 @@
 
 ### Fixed
 
+- Remote session-context actions больше не пытаются повторно уйти с client node
+  обратно в gateway без `clientUuid`; backend error payload дополнительно
+  ограничен по размеру, чтобы relay-сбой не создавал рекурсивный exception.
 - Исправлен `Headers have already sent` при работе MCP/WebApp через общий HTTP runtime.
 - Исправлены route/alias проблемы после перехода под `${ROOT_PREFIX}`.
 - Исправлены зависания Mini App bootstrap и проблемы с relative WebApp routes.

package/README-ru.md

@@ -76,6 +76,10 @@ Gateway
 - `send_partner_file`
 - `list_gateway_sessions`
 
+Для диагностики:
+
+- `get_runtime_diagnostics` для безопасной end-to-end проверки gateway/client
+
 Для браузера:
 
 - `browser_open`
@@ -106,17 +110,39 @@ Gateway
 ## Требования
 
 - Node.js `>= 24`
-- Redis
+- Python 3, `make` и C/C++ toolchain на Linux для локальной сборки native addon `node-pty`; npm lifecycle scripts должны быть включены
+- Redis только для режимов gateway и `both`; клиент Redis не использует
 - PostgreSQL для gateway mode
 - опционально RabbitMQ для durable gateway fanout
 - Playwright browser binaries, если нужны browser tools
 
 ## Установка
 
+На Debian/Ubuntu сначала установи зависимости для сборки native PTY:
+
+```bash
+sudo apt install -y python3 make g++
+npm config set ignore-scripts false
+```
+
 ```bash
-npm install -g @deadragdoll/tellymcp
+npm install -g @deadragdoll/tellymcp --foreground-scripts
 ```
 
+Опубликованная зависимость `node-pty` не содержит готового Linux ARM64 binary,
+поэтому install lifecycle собирает `pty.node` локально. Если пакет ранее
+установился без него, восстанови глобальную установку:
+
+```bash
+npm uninstall -g @deadragdoll/tellymcp
+npm install -g @deadragdoll/tellymcp@latest --foreground-scripts
+tellymcp doctor --env <file>
+```
+
+`tellymcp --help` и setup-команды не загружают native PTY. Runtime проверяет
+модуль перед запуском и вместо сырого stack trace выводит те же инструкции по
+восстановлению.
+
 Если нужны browser tools:
 
 ```bash
@@ -150,9 +176,20 @@ tellymcp codex-plugin install
 ```bash
 mkdir -p ~/telly-gateway
 cd ~/telly-gateway
-tellymcp init gateway
+tellymcp configure
 ```
 
+Команда открывает защищённую одноразовым токеном локальную страницу на
+`127.0.0.1`. Выбери в wizard роль `Gateway`, заполни и проверь настройки, затем
+сохрани `.env-gateway` обычным browser download. Перед использованием выставь
+файлу права `0600`. `tellymcp init gateway` остаётся вариантом для ручного
+редактирования шаблона.
+
+Публичный origin или API base вводится один раз. Wizard сам формирует gateway
+HTTP, WebSocket, Mini App, webhook, root-prefix и опциональные OAuth URL.
+На ключевых этапах доступны реальные проверки Telegram, Redis, PostgreSQL,
+gateway HTTP/WebSocket и опционального RabbitMQ.
+
 Или возьми sample:
 
 - [.env.example.gateway](./.env.example.gateway)
@@ -167,7 +204,7 @@ tellymcp init gateway
 - `DB_NAME`
 - `GATEWAY_PUBLIC_URL`
 - `GATEWAY_WS_URL`
-- `GATEWAY_TOKEN`
+- `GATEWAY_SCOPE_TOKEN`
 - `GATEWAY_AUTH_TOKEN`
 
 Запуск:
@@ -183,9 +220,17 @@ tellymcp run --env .env
 ```bash
 mkdir -p ~/agent-a
 cd ~/agent-a
-tellymcp init client
+tellymcp configure
 ```
 
+Выбери в wizard роль `Client`. В форме есть подключение к gateway, identity
+консоли, terminal, browser, MCP и расширенные runtime-настройки. После
+валидации браузер скачает `.env-client`. Флаг `--no-open` выводит локальный URL
+без автоматического открытия браузера.
+
+Для клиента тот же Public base URL автоматически формирует
+`GATEWAY_PUBLIC_URL`, `GATEWAY_WS_URL` и `GATEWAY_WS_PATH`.
+
 Или используй sample:
 
 - [.env.example.client](./.env.example.client)
@@ -194,7 +239,7 @@ tellymcp init client
 
 - `GATEWAY_PUBLIC_URL`
 - `GATEWAY_WS_URL`
-- `GATEWAY_TOKEN`
+- `GATEWAY_SCOPE_TOKEN`
 - `GATEWAY_AUTH_TOKEN` (тот же transport-токен, который задан на gateway)
 - `GATEWAY_USER_UUID`, если консоль должна быть видна конкретному владельцу в gateway-боте
 
@@ -214,6 +259,10 @@ tellymcp run --env .env -s NEW
 - `local_session_id`
 - `session_label`
 - `env_file`
+- `gateway_client_uuid`
+
+Runtime-состояние клиента локальное и не требует Redis. Сохранённый
+`gateway_client_uuid` обеспечивает стабильную идентичность после перезапуска.
 
 Поэтому дальше в том же каталоге обычно достаточно:
 
@@ -353,6 +402,7 @@ Gateway prompt scanner теперь живёт от live-client lifecycle:
 
 Канонические стартовые точки:
 
+- [Контракт env и руководство по миграции](./docs/ENVIRONMENT.md)
 - [.env.example.gateway](./.env.example.gateway)
 - [.env.example.client](./.env.example.client)
 
@@ -368,6 +418,8 @@ Samples уже вычищены под текущий runtime:
 - убраны obsolete pairing-oriented тексты
 - убраны неиспользуемые секреты вроде `SESSION_SECRET`
 - убран неиспользуемый `APP_NAME`
+- неоднозначные старые имена заменены на `TERMINAL_*`, `GATEWAY_SCOPE_TOKEN`,
+  `TELEGRAM_REQUEST_MODE`, `DB_SCHEMA` и `LOGFEED_ENABLED`
 
 ## Операционные команды
 
@@ -383,6 +435,15 @@ tellymcp doctor --env .env
 tellymcp system-prune --env .env --yes
 ```
 
+Миграция старого env в текущий ролевой контракт:
+
+```bash
+tellymcp migrate-env ./old.env > ./.migrated-env
+```
+
+Fallback на старую схему отсутствует. Если найдены legacy-ключи, запуск
+останавливается и выводит команду миграции.
+
 ## Карта документации
 
 - [README.md](./README.md)

package/README.md

@@ -76,6 +76,10 @@ Agent-to-agent:
 - `send_partner_file`
 - `list_gateway_sessions`
 
+Diagnostics:
+
+- `get_runtime_diagnostics` for safe end-to-end gateway/client health checks
+
 Browser:
 
 - `browser_open`
@@ -106,17 +110,39 @@ Tools sync:
 ## Requirements
 
 - Node.js `>= 24`
-- Redis
+- Python 3, `make`, and a C/C++ toolchain on Linux so `node-pty` can build its native addon; npm lifecycle scripts must be enabled
+- Redis for gateway and `both` modes only; clients do not use Redis
 - PostgreSQL for gateway mode
 - optional RabbitMQ for durable gateway fanout
 - Playwright browser binaries if you use browser tools
 
 ## Installation
 
+On Debian/Ubuntu, install the native PTY build prerequisites first:
+
+```bash
+sudo apt install -y python3 make g++
+npm config set ignore-scripts false
+```
+
 ```bash
-npm install -g @deadragdoll/tellymcp
+npm install -g @deadragdoll/tellymcp --foreground-scripts
 ```
 
+The published `node-pty` dependency does not provide a Linux ARM64 binary, so
+the install lifecycle builds `pty.node` locally. If a previous installation
+completed without it, repair the global package with:
+
+```bash
+npm uninstall -g @deadragdoll/tellymcp
+npm install -g @deadragdoll/tellymcp@latest --foreground-scripts
+tellymcp doctor --env <file>
+```
+
+`tellymcp --help` and setup commands do not load the native PTY module. Runtime
+startup validates it and prints the same recovery instructions instead of a
+raw native-module stack trace.
+
 Optional browser runtime:
 
 ```bash
@@ -150,9 +176,20 @@ Create a gateway workspace and env:
 ```bash
 mkdir -p ~/telly-gateway
 cd ~/telly-gateway
-tellymcp init gateway
+tellymcp configure
 ```
 
+This opens a token-protected local page on `127.0.0.1`. Choose `Gateway` in the
+wizard, fill and validate the settings, then save `.env-gateway` through the
+normal browser download flow. Set its permissions to `0600` before use. Use
+`tellymcp init gateway` when you specifically want a commented template for
+manual editing.
+
+Enter the public origin or API base only once. The wizard derives gateway HTTP,
+WebSocket, Mini App, webhook, root-prefix, and optional OAuth connector URLs.
+The key stages include live connection checks for Telegram, Redis, PostgreSQL,
+the gateway HTTP/WebSocket endpoints, and optional RabbitMQ.
+
 Or copy the sample from this package:
 
 - [.env.example.gateway](./.env.example.gateway)
@@ -167,7 +204,7 @@ Required gateway values:
 - `DB_NAME`
 - `GATEWAY_PUBLIC_URL`
 - `GATEWAY_WS_URL`
-- `GATEWAY_TOKEN`
+- `GATEWAY_SCOPE_TOKEN`
 - `GATEWAY_AUTH_TOKEN`
 
 Then run:
@@ -183,9 +220,17 @@ Create one workspace per agent console:
 ```bash
 mkdir -p ~/agent-a
 cd ~/agent-a
-tellymcp init client
+tellymcp configure
 ```
 
+Choose `Client` in the wizard. The form includes the gateway connection, local
+console identity, terminal, browser, MCP, and advanced runtime settings.
+After validation the browser downloads `.env-client`. Use `--no-open` to print
+the local URL without opening a browser automatically.
+
+For clients, the same Public base URL automatically produces
+`GATEWAY_PUBLIC_URL`, `GATEWAY_WS_URL`, and `GATEWAY_WS_PATH`.
+
 Or copy:
 
 - [.env.example.client](./.env.example.client)
@@ -194,7 +239,7 @@ Required client values:
 
 - `GATEWAY_PUBLIC_URL`
 - `GATEWAY_WS_URL`
-- `GATEWAY_TOKEN`
+- `GATEWAY_SCOPE_TOKEN`
 - `GATEWAY_AUTH_TOKEN` (the same transport token configured on the gateway)
 - `GATEWAY_USER_UUID` if this console should be scoped to a specific Telegram owner
 
@@ -214,6 +259,10 @@ After that, `.mcpsession.json` stores:
 - `local_session_id`
 - `session_label`
 - `env_file`
+- `gateway_client_uuid`
+
+Client runtime state is local and does not require Redis. The persisted
+`gateway_client_uuid` keeps the client identity stable across restarts.
 
 So later the same workspace can usually start with:
 
@@ -352,6 +401,7 @@ Expected agent behavior:
 
 Use the shipped samples as the canonical starting point:
 
+- [Environment contract and migration guide](./docs/ENVIRONMENT.md)
 - [.env.example.gateway](./.env.example.gateway)
 - [.env.example.client](./.env.example.client)
 
@@ -367,6 +417,8 @@ The samples were cleaned to match the current runtime:
 - removed obsolete pairing-oriented wording
 - removed unused secrets like `SESSION_SECRET`
 - removed unused `APP_NAME`
+- renamed ambiguous legacy keys to `TERMINAL_*`, `GATEWAY_SCOPE_TOKEN`,
+  `TELEGRAM_REQUEST_MODE`, `DB_SCHEMA`, and `LOGFEED_ENABLED`
 
 ## Operational Commands
 
@@ -382,6 +434,15 @@ Destructive local+gateway cleanup:
 tellymcp system-prune --env .env --yes
 ```
 
+Normalize an older env file to the current role-aware contract:
+
+```bash
+tellymcp migrate-env ./old.env > ./.migrated-env
+```
+
+The runtime does not fall back to the old schema. If legacy keys are detected,
+startup stops and prints the migration command.
+
 ## Documentation Map
 
 - [README-ru.md](./README-ru.md)

package/TOOLS.md

@@ -92,7 +92,7 @@ Utility tools:
 Gateway-first runtime model:
 
 - agents authenticate the gateway HTTP/WS transport through `GATEWAY_AUTH_TOKEN`
-  and register into their gateway scope through `GATEWAY_TOKEN`
+  and register into their gateway scope through `GATEWAY_SCOPE_TOKEN`
 - Telegram no longer links sessions with pair codes
 - `/menu` in the gateway bot shows available remote consoles directly
 - one running agent console is one logical session/console target
@@ -207,6 +207,42 @@ Output:
 - `terminal?`
   Terminal runtime metadata for the console.
 
+## `get_runtime_diagnostics`
+
+Purpose:
+
+- Run safe, read-only health checks for one console through the same gateway route used by normal tools.
+- Diagnose configuration, runtime state storage, PTY state, version/protocol metadata, and gateway-to-client relay without returning secrets or raw connection strings.
+- Redis is probed only for gateway/`both` runtimes. On a client, the `redis` compatibility check reports that Redis is not required and process-local state is active.
+- Return a structured degraded result when relay fails instead of a deeply nested backend exception.
+
+Input:
+
+- `session_id?`
+  In gateway mode, use the canonical `session_id` returned by `list_gateway_sessions`.
+
+Output:
+
+- `status`
+  - `ok`
+  - `degraded`
+- `checked_at`
+- `session_id`
+- `runtime`
+  - `mode`
+  - `package_version`
+  - `protocol_version`
+  - `node_id?`
+- `checks`
+  - `configuration`
+  - `redis`
+  - `session_store`
+  - `terminal`
+  - `gateway_configuration`
+  - `relay`
+
+Each check contains only `status` and a redacted human-readable `message`.
+
 ## `get_file_list`
 
 Purpose:
@@ -287,6 +323,7 @@ Behavior:
 - source extensions such as `.ts` and `.tsx` use text MIME overrides instead of the generic MPEG/octet-stream mappings
 - sensitive paths including live `.env` files, credential stores, private-key extensions, and secret directories are rejected server-side; documented `.env.example`/`.env.sample`/`.env.template` files remain readable
 - URL mode uploads the file as a binary stream to `.tellymcp/tmp/file-links` on the gateway and returns a link valid for 10 minutes
+- temporary-link filenames are sanitized before storage and download headers: control and filesystem-reserved characters are replaced, while a safe basename is preserved
 - image mode is explicit: `structuredContent.type` is `image`, `structuredContent.data` contains the URL, and the native top-level MCP `image` is the first content block without duplicating base64 into structured output
 - image mode accepts only `image/*` files up to the safe native-inline limit; use `url` for larger images
 - URL links allow up to three GET downloads; HEAD requests do not consume the limit