@deadragdoll/tellymcp 0.0.4 → 0.0.6

package/README-ru.md

@@ -7,16 +7,73 @@
 [![node >= 24](https://img.shields.io/badge/node-%3E%3D24-339933)](https://nodejs.org/)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-TellyMCP — это Telegram Human-in-the-Loop MCP server для coding agents.
+TellyMCP — это self-hosted Telegram control plane для coding agents.
 
-Он позволяет агенту:
+Он привязывает реальные agent-сессии к Telegram, делает их доступными с телефона и даёт им работать вместе между локальными и удалёнными машинами.
+
+Он не завязан на одного вендора или один coding assistant. Если агент умеет работать с MCP server, он может использовать TellyMCP.
+
+## Зачем он нужен
+
+Coding agents полезны ровно до того момента, пока они не остаются одни в терминале:
+
+- им нужно уточнение, пока тебя нет за компьютером
+- им нужен approval перед рискованным действием
+- им нужно передать скриншот, файл или note между сессиями
+- им нужно быстро подключить человека или другого агента, не ломая общий workflow
+
+TellyMCP даёт каждой сессии мобильную панель управления и collaboration layer:
+
+- `Live` tmux view и лёгкое управление из Telegram
+- session-scoped inbox и уведомления
+- workspace-aware handoff для файлов и note
+- локальную и удалённую коллаборацию между сессиями
+- поддержку mixed agent setups, если они умеют говорить по MCP
+
+## Ключевые идеи продукта
+
+- `Live` tmux view и управление внутри Telegram Mini App
+- `Collab`-сценарии для локальных и удалённых agent-сессий
+- `.mcp-xchange` как workspace-level handoff шина для note, файлов и скриншотов
+- MCP-native pairing сессий и session-scoped tools
+- optional gateway mode для multi-machine и multi-bot проектов
+
+## Human-in-the-loop — это только один слой системы
+
+Telegram HITL здесь тоже есть, но он не исчерпывает продукт:
 
 - задавать человеку уточняющие вопросы через Telegram
 - получать несвязанные входящие сообщения позже через inbox
-- привязывать несколько agent-сессий
-- работать с локальными и удалёнными партнёрскими сессиями
-- открывать Live tmux view внутри Telegram Mini App
-- обмениваться note, скриншотами и файлами через `.mcp-xchange`
+- уведомлять человека о прогрессе, blockers и approvals
+
+## Что отличает TellyMCP от простого Telegram bot bridge
+
+- он завязан на сессии, а не только на чат
+- он понимает локальные и удалённые collaboration targets
+- у него есть live terminal surface, а не только обмен сообщениями
+- он передаёт файлы через workspace-aware exchange paths, а не просто через ad hoc upload
+- он может работать как standalone node или как gateway-backed control plane
+
+## Типовые сценарии
+
+- держать долгоживущего агента доступным с телефона
+- запускать рядом разных агентов, если каждый умеет подключаться по MCP
+- подруливать tmux-сессией без ноутбука
+- маршрутизировать работу между `frontend`, `backend`, `review` и другими локальными сессиями
+- работать с удалёнными сессиями через gateway-backed project
+- передавать note, скриншоты и реальные файлы через `.mcp-xchange`
+- проверять локальный веб-интерфейс через `browser_*` tools и отправлять результат обратно в Telegram
+
+## Группы инструментов
+
+- pairing и session context
+- Telegram ask/notify/inbox
+- `Live` tmux control
+- browser inspection и screenshots
+- partner notes и partner files
+- tools sync и version checks
+
+Полный список MCP tools лучше держать ниже по README и в самом MCP server, а не на первом экране.
 
 ## Prerequisites
 

package/README.md

@@ -7,50 +7,73 @@
 [![node >= 24](https://img.shields.io/badge/node-%3E%3D24-339933)](https://nodejs.org/)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-TellyMCP is a Telegram Human-in-the-Loop MCP server for coding agents.
+TellyMCP is a self-hosted Telegram control plane for coding agents.
 
-It lets an agent:
+It pairs real agent sessions with Telegram, keeps them reachable from mobile, and lets them collaborate across local and remote machines.
+
+It is not tied to one vendor or one coding assistant. If your agent can talk to an MCP server, it can use TellyMCP.
+
+## Why it exists
+
+Coding agents are useful until they leave the terminal:
+
+- they need clarification while you are away from the desk
+- they need approval before doing something risky
+- they need screenshots, files, or notes passed between sessions
+- they need a human or another agent to unblock work without breaking flow
+
+TellyMCP gives each session a mobile control surface and a collaboration layer:
+
+- `Live` tmux view and light control from Telegram
+- session-scoped inbox and notifications
+- workspace-aware file and note handoffs
+- local and remote session collaboration
+- support for mixed agent setups, as long as they speak MCP
+
+## Core ideas
+
+- `Live` tmux view and control inside Telegram Mini App
+- `Collab` flows for local and remote agent sessions
+- `.mcp-xchange` as a workspace-level handoff bus for notes, files, and screenshots
+- MCP-native session pairing and session-scoped tools
+- optional gateway mode for cross-machine and cross-bot projects
+
+## Human-in-the-loop is one layer, not the whole product
+
+Telegram HITL is still supported, but it is not the whole story:
 
 - ask a human for clarification through Telegram
 - receive unsolicited Telegram messages later through an inbox
-- pair multiple agent sessions
-- collaborate across local and remote sessions
-- open a live tmux view inside Telegram Mini App
-- exchange notes, screenshots, and files through `.mcp-xchange`
-
-Current tools:
-
-- `create_session_pair_code`
-- `clear_session_pairing`
-- `set_session_context`
-- `set_tmux_target`
-- `get_tmux_target`
-- `get_session_context`
-- `clear_session_context`
-- `rename_session`
-- `notify_telegram`
-- `get_telegram_inbox_count`
-- `get_telegram_inbox`
-- `delete_telegram_inbox_message`
-- `ask_user_telegram`
-- `browser_open`
-- `browser_reload`
-- `browser_click`
-- `browser_fill`
-- `browser_press`
-- `browser_wait_for`
-- `browser_wait_for_url`
-- `browser_console`
-- `browser_errors`
-- `browser_network_failures`
-- `browser_clear_logs`
-- `browser_dom`
-- `browser_computed_style`
-- `browser_screenshot`
-- `browser_close`
-- `refresh_tools_markdown`
-- `send_partner_note`
-- `send_partner_file`
+- notify a human about progress, blockers, and approvals
+
+## What makes it different from a simple Telegram bot bridge
+
+- it is session-based, not just chat-based
+- it understands local and remote collaboration targets
+- it has a live terminal surface, not only message exchange
+- it moves files through workspace-aware exchange paths, not just ad hoc uploads
+- it can run as a standalone node or as a gateway-backed control plane
+
+## Typical use cases
+
+- keep a long-running agent reachable from your phone
+- run different agents side by side, as long as each one can connect over MCP
+- steer a tmux-based session without opening a laptop
+- route work between `frontend`, `backend`, `review`, or other local sessions
+- collaborate with remote sessions through a gateway-backed project
+- send notes, screenshots, and real files through `.mcp-xchange`
+- inspect or screenshot a local web app with `browser_*` tools and send results back to Telegram
+
+## Tool groups
+
+- session pairing and context
+- Telegram ask/notify/inbox
+- `Live` tmux control
+- browser inspection and screenshots
+- partner notes and partner files
+- tools sync and version checks
+
+The full MCP tool surface is documented later in this README and through the MCP server itself.
 
 ## Prerequisites
 

package/VERSION.md

@@ -21,6 +21,15 @@ For detailed engineering history, refactors, and internal development notes, see
   - [README.md](README.md)
   - [README-ru.md](README-ru.md)
 - Human-readable release notes in this file.
+- Telegram startup notice:
+  - version
+  - protocol
+  - mode
+  - paired sessions
+  - MCP/WebApp/Gateway endpoints
+- Live text input button:
+  - `[txt]`
+  - sends literal text to tmux without pressing `Enter`
 
 ### Changed
 - Default installation path is now npm-first:
@@ -32,6 +41,7 @@ For detailed engineering history, refactors, and internal development notes, see
   - direct terminal control from Telegram
 - Environment examples were split into dedicated client and gateway variants.
 - Package build/publish flow now validates itself before packing/publishing.
+- CLI now shows package version directly in banners and startup output.
 
 ### Collaboration
 - Project collaboration works across local and remote sessions.
@@ -55,6 +65,18 @@ For detailed engineering history, refactors, and internal development notes, see
   - `Down`
   - `Enter`
 - Live approval flow was added for remote project sessions.
+- Live toolbar now includes:
+  - `/`
+  - `↑`
+  - `↓`
+  - `Enter`
+  - `⌫`
+  - `[txt]`
+  - `Tab`
+  - `Esc`
+  - `Ctrl+C`
+- `Ctrl+C` now asks for confirmation before sending an interrupt to the agent.
+- Mobile toolbar layout now wraps cleanly into two rows instead of collapsing into a centered stack.
 
 ### Browser
 - Browser tools use Playwright Chromium.

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

@@ -554,15 +554,26 @@ const TelegramMcpGatewaySocketService = {
                     const action = typeof request.payload?.action === "string"
                         ? request.payload.action
                         : "";
-                    if (!["up", "down", "enter", "slash", "delete", "tab", "escape", "interrupt"].includes(action)) {
+                    const text = typeof request.payload?.text === "string"
+                        ? request.payload.text
+                        : "";
+                    if (!["up", "down", "enter", "slash", "delete", "tab", "escape", "interrupt", "text"].includes(action)) {
                         throw new Error("Unsupported action");
                     }
+                    if (action === "text" && (!text || text.length > 4000)) {
+                        throw new Error("Text payload is required and must be <= 4000 characters");
+                    }
                     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);
+                    if (action === "text") {
+                        await (0, tmux_1.sendTmuxLiteralText)(runtime.config.tmux, session.tmuxTarget, text);
+                    }
+                    else {
+                        await (0, tmux_1.sendAllowedTmuxAction)(runtime.config.tmux, session.tmuxTarget, action);
+                    }
                     return {
                         type: "live_response",
                         request_id: request.request_id,

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

@@ -428,10 +428,19 @@ function createMcpHttpHandler(runtime, input) {
                     typeof Reflect.get(body, "action") === "string"
                     ? String(Reflect.get(body, "action"))
                     : "";
-                if (!["up", "down", "enter", "slash", "delete", "tab", "escape", "interrupt"].includes(action)) {
+                const text = body &&
+                    typeof body === "object" &&
+                    typeof Reflect.get(body, "text") === "string"
+                    ? String(Reflect.get(body, "text"))
+                    : "";
+                if (!["up", "down", "enter", "slash", "delete", "tab", "escape", "interrupt", "text"].includes(action)) {
                     writeText(res, 400, "Unsupported action");
                     return;
                 }
+                if (action === "text" && (!text || text.length > 4000)) {
+                    writeText(res, 400, "Text payload is required and must be <= 4000 characters");
+                    return;
+                }
                 const nowMs = Date.now();
                 if (nowMs - webAppSession.lastActionAtMs <
                     runtime.config.webapp.actionCooldownMs) {
@@ -445,6 +454,7 @@ function createMcpHttpHandler(runtime, input) {
                             clientUuid: relayTarget.clientUuid,
                             localSessionId: relayTarget.localSessionId,
                             action: action,
+                            ...(action === "text" ? { text } : {}),
                         });
                         webAppSessions.touchAction(webAppSession.token, nowMs);
                         writeJson(res, 200, {
@@ -477,12 +487,18 @@ function createMcpHttpHandler(runtime, input) {
                     return;
                 }
                 try {
-                    await (0, tmux_1.sendAllowedTmuxAction)(runtime.config.tmux, session.tmuxTarget, action);
+                    if (action === "text") {
+                        await (0, tmux_1.sendTmuxLiteralText)(runtime.config.tmux, session.tmuxTarget, text);
+                    }
+                    else {
+                        await (0, tmux_1.sendAllowedTmuxAction)(runtime.config.tmux, session.tmuxTarget, action);
+                    }
                     webAppSessions.touchAction(webAppSession.token, nowMs);
                     runtime.logger.info("Telegram WebApp action sent to tmux", {
                         sessionId: webAppSession.sessionId,
                         telegramUserId: webAppSession.telegramUserId,
                         action,
+                        ...(action === "text" ? { textLength: text.length } : {}),
                     });
                     writeJson(res, 200, {
                         ok: true,

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

@@ -42,7 +42,7 @@ body {
   bottom: calc(42px + env(safe-area-inset-bottom, 0px));
   z-index: 30;
   display: flex;
-  justify-content: center;
+  justify-content: flex-start;
   flex-wrap: wrap;
   gap: 8px;
   padding: 10px 14px;
@@ -52,6 +52,11 @@ body {
   backdrop-filter: blur(14px);
 }
 
+.toolbar-spacer {
+  flex: 1 1 auto;
+  min-width: 12px;
+}
+
 .btn {
   appearance: none;
   border: 1px solid var(--border);
@@ -73,6 +78,28 @@ body {
 .btn:disabled { cursor: not-allowed; opacity: 0.55; }
 .btn.danger:hover { border-color: var(--danger); }
 
+.btn.danger {
+  border-color: rgba(255, 116, 116, 0.55);
+  background: linear-gradient(180deg, rgba(78, 18, 24, 0.96) 0%, rgba(50, 14, 18, 0.98) 100%);
+  color: #ffd7d7;
+  box-shadow: inset 0 0 0 1px rgba(255, 116, 116, 0.12);
+}
+
+.btn.danger:hover {
+  border-color: rgba(255, 116, 116, 0.9);
+}
+
+.btn.primary {
+  border-color: rgba(87, 193, 255, 0.45);
+  background: linear-gradient(180deg, rgba(17, 45, 66, 0.96) 0%, rgba(12, 33, 48, 0.98) 100%);
+  color: #d9f3ff;
+  box-shadow: inset 0 0 0 1px rgba(87, 193, 255, 0.1);
+}
+
+.btn.primary:hover {
+  border-color: rgba(87, 193, 255, 0.8);
+}
+
 .statusbar {
   position: fixed;
   left: 0;
@@ -138,6 +165,11 @@ body {
     padding: 8px 10px;
   }
 
+  .toolbar-spacer {
+    flex: 1 1 auto;
+    min-width: 12px;
+  }
+
   .btn.compact {
     min-width: 42px;
     padding: 8px 10px;
@@ -169,6 +201,7 @@ const elements = {
   status: document.querySelector("[data-role=status]"),
   updated: document.querySelector("[data-role=updated]"),
   interrupt: document.querySelector("[data-role=interrupt]"),
+  type: document.querySelector("[data-role=type]"),
   esc: document.querySelector("[data-role=escape]"),
   tab: document.querySelector("[data-role=tab]"),
   slash: document.querySelector("[data-role=slash]"),
@@ -571,6 +604,47 @@ async function sendAction(action) {
   }
 }
 
+async function sendTextInput(text) {
+  if (state.actionBusy || !state.token) {
+    return;
+  }
+
+  state.actionBusy = true;
+  try {
+    const response = await fetch(config.basePath + "/api/action", {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: "Bearer " + state.token,
+      },
+      body: JSON.stringify({ action: "text", text }),
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(text || "Failed to send text.");
+    }
+
+    setStatus("Text sent");
+    await refreshVisibleBuffer();
+  } finally {
+    state.actionBusy = false;
+  }
+}
+
+function confirmInterrupt() {
+  return new Promise((resolve) => {
+    if (tg && typeof tg.showConfirm === "function") {
+      tg.showConfirm("Send Ctrl+C to the tmux session? This can stop the running agent.", (ok) => {
+        resolve(Boolean(ok));
+      });
+      return;
+    }
+
+    resolve(window.confirm("Send Ctrl+C to the tmux session? This can stop the running agent."));
+  });
+}
+
 async function refreshVisibleBuffer() {
   const payload = await fetchVisibleBuffer();
   elements.terminal.innerHTML = renderAnsiToHtml(payload.content || "");
@@ -599,7 +673,22 @@ function startPolling() {
 
 function bindUi() {
   elements.interrupt.addEventListener("click", () => {
-    sendAction("interrupt").catch((error) => setStatus(error.message || String(error), true));
+    confirmInterrupt()
+      .then((ok) => {
+        if (!ok) {
+          return;
+        }
+        return sendAction("interrupt");
+      })
+      .catch((error) => setStatus(error.message || String(error), true));
+  });
+
+  elements.type.addEventListener("click", () => {
+    const value = window.prompt("Send text to tmux without Enter:", "");
+    if (value === null || value.length === 0) {
+      return;
+    }
+    sendTextInput(value).catch((error) => setStatus(error.message || String(error), true));
   });
 
   elements.esc.addEventListener("click", () => {
@@ -670,6 +759,7 @@ async function main() {
 
     if (!bootstrapPayload.tmux_target) {
       elements.interrupt.disabled = true;
+      elements.type.disabled = true;
       elements.esc.disabled = true;
       elements.tab.disabled = true;
       elements.slash.disabled = true;
@@ -710,14 +800,16 @@ function renderWebAppHtml(input) {
   <body>
     <div class="app">
       <div class="toolbar">
-        <button class="btn compact danger" data-role="interrupt" type="button">Ctrl+C</button>
-        <button class="btn compact" data-role="escape" type="button">Esc</button>
-        <button class="btn compact" data-role="tab" type="button">Tab</button>
         <button class="btn compact" data-role="slash" type="button">/</button>
-        <button class="btn compact" data-role="delete" type="button">⌫</button>
         <button class="btn compact" data-role="up" type="button">↑</button>
         <button class="btn compact" data-role="down" type="button">↓</button>
-        <button class="btn compact" data-role="enter" type="button">↵</button>
+        <button class="btn compact primary" data-role="enter" type="button">Enter</button>
+        <button class="btn compact" data-role="delete" type="button">⌫</button>
+        <button class="btn compact" data-role="type" type="button" title="Type text">🔤</button>
+        <button class="btn compact" data-role="tab" type="button">Tab</button>
+        <button class="btn compact" data-role="escape" type="button">Esc</button>
+        <span class="toolbar-spacer" aria-hidden="true"></span>
+        <button class="btn compact danger" data-role="interrupt" type="button">Ctrl+C</button>
       </div>
       <pre class="terminal" data-role="terminal">Waiting for tmux buffer…</pre>
       <div class="statusbar">

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

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.sendAllowedTmuxAction = exports.isTmuxUnavailableError = exports.getTmuxWindowHeight = exports.captureVisibleTmuxPane = exports.captureTmuxPaneRange = void 0;
+exports.sendTmuxLiteralText = exports.sendAllowedTmuxAction = exports.isTmuxUnavailableError = exports.getTmuxWindowHeight = exports.captureVisibleTmuxPane = exports.captureTmuxPaneRange = void 0;
 var client_1 = require("../../shared/integrations/tmux/client");
 Object.defineProperty(exports, "captureTmuxPaneRange", { enumerable: true, get: function () { return client_1.captureTmuxPaneRange; } });
 Object.defineProperty(exports, "captureVisibleTmuxPane", { enumerable: true, get: function () { return client_1.captureVisibleTmuxPane; } });
 Object.defineProperty(exports, "getTmuxWindowHeight", { enumerable: true, get: function () { return client_1.getTmuxWindowHeight; } });
 Object.defineProperty(exports, "isTmuxUnavailableError", { enumerable: true, get: function () { return client_1.isTmuxUnavailableError; } });
 Object.defineProperty(exports, "sendAllowedTmuxAction", { enumerable: true, get: function () { return client_1.sendAllowedTmuxAction; } });
+Object.defineProperty(exports, "sendTmuxLiteralText", { enumerable: true, get: function () { return client_1.sendTmuxLiteralText; } });

package/dist/services/features/telegram-mcp/src/features/distributed-gateway/model/gatewayHttpService.js

@@ -173,6 +173,7 @@ class GatewayHttpService {
             requestType: "action",
             payload: {
                 action: input.action,
+                ...(input.action === "text" ? { text: input.text ?? "" } : {}),
             },
         }, { meta: { internal_call: true } });
         const response = unwrapLiveRelayResult(rawResponse);

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

@@ -14,6 +14,7 @@ exports.getTmuxWindowHeight = getTmuxWindowHeight;
 exports.captureTmuxPaneRange = captureTmuxPaneRange;
 exports.captureVisibleTmuxPane = captureVisibleTmuxPane;
 exports.sendAllowedTmuxAction = sendAllowedTmuxAction;
+exports.sendTmuxLiteralText = sendTmuxLiteralText;
 exports.sendTmuxLiteralLine = sendTmuxLiteralLine;
 const node_child_process_1 = require("node:child_process");
 const promises_1 = require("node:fs/promises");
@@ -258,8 +259,8 @@ async function sendAllowedTmuxAction(config, target, action) {
                                 : "Enter";
     await execFileAsync("tmux", buildTmuxArgs(config, ["send-keys", "-t", target, key]));
 }
-async function sendTmuxLiteralLine(config, target, text) {
-    const normalized = text.replace(/\r?\n/g, " ").trim();
+async function sendTmuxLiteralText(config, target, text) {
+    const normalized = text.replace(/\r?\n/g, " ");
     const bufferName = `telegram-mcp-${Date.now().toString(36)}`;
     if (normalized.length > 0) {
         try {
@@ -276,6 +277,11 @@ async function sendTmuxLiteralLine(config, target, text) {
         finally {
             await execFileAsync("tmux", buildTmuxArgs(config, ["delete-buffer", "-b", bufferName])).catch(() => undefined);
         }
+    }
+}
+async function sendTmuxLiteralLine(config, target, text) {
+    await sendTmuxLiteralText(config, target, text);
+    if (text.length > 0) {
         await delay(ENTER_AFTER_PASTE_DELAY_MS);
     }
     await execFileAsync("tmux", buildTmuxArgs(config, ["send-keys", "-t", target, SUBMIT_LINE_KEY]));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deadragdoll/tellymcp",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "TellyMCP - Telegram Human-in-the-Loop MCP Server",
   "main": "dist/services/features/telegram-mcp/runtime.service.js",
   "bin": {