arena-bridge 0.6.10 → 0.7.1

package/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to this project are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/) and the project uses
 [Semantic Versioning](https://semver.org/).
 
+## 0.7.1
+
+### Fixed
+- The Telegram listener no longer gives up on a long poll when the network is slow: the request
+  ceiling is now generous enough for the 20-second long poll to answer.
+
+## 0.7.0
+
+### Added
+- **Telegram link.** The bridge can now talk to the user outside the agent chat:
+  - `notify_user` — send a message (progress, a question, a result); with
+    `{"wait_for_reply": true}` the call waits for the answer in Telegram.
+  - `telegram_inbox` — read the messages the user sent to the bot.
+  - `telegram_status` — the bot, the allowed chats, the number of unread messages.
+  - `arena-bridge telegram setup|test|status|inbox|poll` — the same link from the terminal.
+- **Approvals from Telegram.** A pending request is announced in the chat right away, and
+  the user can settle it with `/approve <id>` or `/deny <id>` (the terminal still works:
+  `arena-bridge approve <id>`).
+- The bridge listens for incoming bot messages on its own (the launchd service does it
+  automatically); the inbox lives in `~/.arena-bridge/telegram/`.
+
+### Security
+- The bot token stays in `~/.arena-bridge/config.json` (0600), which the agent cannot read.
+- The bridge may only write to the chats listed in `--chat-id`; 20 messages per minute,
+  4000 characters per message.
+
 ## 0.6.10
 
 ### Fixed

package/README.md

@@ -12,7 +12,7 @@
   <img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="license">
   <img src="https://img.shields.io/badge/node-%3E%3D18-green.svg?style=flat-square" alt="node">
   <img src="https://img.shields.io/badge/dependencies-0-brightgreen.svg?style=flat-square" alt="dependencies">
-  <img src="https://img.shields.io/badge/tests-124%20passed-brightgreen.svg?style=flat-square" alt="tests">
+  <img src="https://img.shields.io/badge/tests-147%20passed-brightgreen.svg?style=flat-square" alt="tests">
 </p>
 
 <p align="center">
@@ -100,6 +100,7 @@ arena-bridge setup --root ~/projects
 | Процессы | `start_process` `read_process_output` `write_process` `kill_process` | фоновые дев-серверы |
 | Chrome | `chrome_launch` `chrome_profiles` `chrome_attach` `chrome_open` `chrome_navigate` `chrome_snapshot` `chrome_click` `chrome_type` `chrome_press` `chrome_screenshot` `chrome_evaluate` `chrome_tabs` `chrome_stop` | браузер через CDP |
 | Десктоп | `mac_see` `mac_element` `mac_click` `mac_set` `mac_type` `mac_key` `mac_scroll` `mac_move` `mac_drag` `mac_menu` `mac_menu_click` `mac_wait` `mac_spaces` `mac_space_switch` `mac_apps` `mac_windows` `mac_app_launch` `mac_app_focus` `mac_app_quit` `mac_permissions` | macOS через Peekaboo |
+| Telegram | `notify_user` `telegram_inbox` `telegram_status` | сообщения вам и ваши ответы |
 
 Полный каталог с JSON-схемами: `GET /tools` или `arena-bridge tools`.
 
@@ -118,6 +119,7 @@ arena-bridge setup --root ~/projects
 | кликнуть в нативном приложении | `mac_click` (id элемента, видимый текст или координаты) |
 | напечатать | `mac_type`, затем `mac_key` для Enter/Tab/cmd+s |
 | посмотреть файлы | `list_dir` (только верхний уровень; глубже — `{"recursive":true}`) |
+| написать вам или спросить | `notify_user` (Telegram), ответ читать через `telegram_inbox` |
 
 ---
 
@@ -219,6 +221,43 @@ arena-bridge audit dir             # где всё это лежит
 
 ---
 
+## Связь с Telegram
+
+Агент может писать вам в Telegram и читать ваши ответы — даже если вы сейчас не в чате с ним.
+
+```bash
+# один раз: привязать бота (токен от @BotFather и ваш chat id)
+arena-bridge telegram setup --token 123456:AA... --chat-id 190771108
+
+# проверить связь
+arena-bridge telegram test
+
+# посмотреть, что вам писали
+arena-bridge telegram inbox
+```
+
+Что это даёт:
+- `notify_user` — агент пишет вам: «сделал», «нужно ваше решение», «вот результат».
+  С `{"wait_for_reply": true}` вызов ждёт вашего ответа прямо в Telegram.
+- `telegram_inbox` — агент читает то, что вы написали боту: ответы, правки, поручения.
+- `telegram_status` — бот, список чатов, число непрочитанных сообщений.
+- **Подтверждения из Telegram.** Когда агенту нужно ваше «да», мост сам пишет вам:
+  `/approve <id>` — разрешить, `/deny <id>` — отказать. Из терминала тоже можно:
+  `arena-bridge approve <id>`.
+
+Как это устроено и что защищено:
+- токен бота лежит только в `~/.arena-bridge/config.json` (права `0600`); агент этот файл
+  прочитать не может — он в списке защищённых путей;
+- писать можно только в те чаты, что перечислены в `--chat-id` (по умолчанию — ваш);
+- не больше 20 сообщений в минуту, одно сообщение — до 4000 символов;
+- входящие сообщения мост слушает сам (служба launchd — автоматически), входящие лежат
+  в `~/.arena-bridge/telegram/`.
+
+Одно уточнение: для бота `api_id`/`api_hash` не нужны — они пригодятся только для режима
+«личного аккаунта» (MTProto), который пока не включён.
+
+---
+
 ## Доверенное окно: работать без подтверждений
 
 ```bash
@@ -319,6 +358,7 @@ arena-bridge audit -n 50       # что происходило
 | `service` | macOS-фоновый сервис: `install` / `uninstall` / `status` |
 | `browser` | профили браузера агента: `list` / `open <name>` / `close <name>` |
 | `rotate` | сменить агентский или девайсный токен |
+| `telegram` | связь с Telegram: `setup` / `test` / `status` / `inbox` / `poll` |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arena-bridge",
-  "version": "0.6.10",
+  "version": "0.7.1",
   "description": "Give a cloud AI agent (Arena.ai Agent Mode, Claude, Cursor, ...) controlled access to your own machine over HTTP/MCP: files, shell, Chrome and the macOS desktop, with an approval gate, trust windows and an audit log.",
   "type": "module",
   "bin": {

package/src/approvals.mjs

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import { APPROVALS_DIR, ensureDirs } from './config.mjs';
+import { sendTelegram } from './telegram.mjs';
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
@@ -74,6 +75,17 @@ export async function requestApproval(tool, args, cfg) {
   };
   fs.writeFileSync(fileOf(id), JSON.stringify(rec, null, 2), { mode: 0o600 });
 
+  // tell the user about it right away, so a pending request is not a dead end
+  if (cfg.telegram?.enabled && cfg.telegram?.botToken) {
+    sendTelegram(cfg, {
+      title: 'Approval needed',
+      text:
+        `Tool: ${tool}\n` +
+        `id: ${id}\n` +
+        `Reply /approve ${id} or /deny ${id} in Telegram, or run: arena-bridge approve ${id}`,
+    }).catch(() => {});
+  }
+
   const waitSec = Math.min(cfg.approvalWaitSec ?? 90, cfg.approvalTtlSec ?? 900);
   const deadline = now + waitSec * 1000;
   while (Date.now() < deadline) {

package/src/cli.mjs

@@ -17,6 +17,13 @@ import { findPeekaboo } from './mac.mjs';
 import { findChrome, listProfiles, resolveProfile, sanitizeProfile } from './browser.mjs';
 import { packageInfo, latestVersion, compareVersions, selfUpdate } from './selfupdate.mjs';
 import { serviceStatus, serviceInstall, serviceUninstall } from './service.mjs';
+import {
+  sendTelegram,
+  telegramSettings,
+  readInbox,
+  inboxState,
+  startPoller,
+} from './telegram.mjs';
 
 const REPEATABLE_FLAGS = new Set(['root']);
 
@@ -74,6 +81,12 @@ Commands:
                        --paths p1,p2   only these paths (bash is not covered)
                        --off | --status
   audit [-n N]         Show the audit log
+  telegram             Talk to the user in Telegram
+                       setup --token <bot token> --chat-id <id>
+                       test              send a test message
+                       status            show the bot, the chats, the unread count
+                       inbox [-n N]      show the messages the user sent
+                       poll              listen for messages in the foreground
   doctor               Check the installation and configuration
   url                  Print the public URL the agent should use
   version              Show the installed version and the latest one on npm
@@ -583,6 +596,85 @@ function cmdRotate(args) {
   );
 }
 
+async function cmdTelegram(args) {
+  const cfg = loadConfig();
+  const sub = args._[1] || 'status';
+
+  if (sub === 'setup') {
+    const t = { ...(cfg.telegram || {}) };
+    if (args.flags.token) t.botToken = String(args.flags.token);
+    if (args.flags['chat-id']) {
+      t.chatIds = String(args.flags['chat-id'])
+        .split(',')
+        .map((v) => v.trim())
+        .filter(Boolean);
+    }
+    if (args.flags['api-id']) t.apiId = String(args.flags['api-id']);
+    if (args.flags['api-hash']) t.apiHash = String(args.flags['api-hash']);
+    if (args.flags['no-poll']) t.poll = false;
+    if (args.flags.poll) t.poll = true;
+    t.enabled = !!(t.botToken && (t.chatIds || []).length);
+    cfg.telegram = t;
+    saveConfig(cfg);
+    console.log(t.enabled ? '✓ Telegram configured' : '✗ both --token and --chat-id are required');
+    if (t.enabled) {
+      const res = await sendTelegram(cfg, {
+        title: 'arena-bridge',
+        text: 'Telegram is connected. The agent can now message you and read your answers.',
+      });
+      console.log(res.ok ? '✓ test message sent' : `✗ ${res.error}: ${res.reason || ''}`);
+    }
+    return;
+  }
+
+  if (sub === 'test') {
+    const res = await sendTelegram(cfg, {
+      title: 'arena-bridge',
+      text: 'Test message from the bridge. If you can read this, the link works.',
+    });
+    console.log(res.ok ? '✓ message sent' : `✗ ${res.error}: ${res.reason || ''}`);
+    if (!res.ok) process.exitCode = 1;
+    return;
+  }
+
+  if (sub === 'inbox') {
+    const limit = Math.min(100, Number(args.flags.n) || 20);
+    const items = readInbox({ limit });
+    if (!items.length) console.log('(no messages yet)');
+    for (const i of items) {
+      console.log(`#${i.id} ${i.from} ${i.read ? '' : '(new) '}${i.text}`);
+    }
+    return;
+  }
+
+  if (sub === 'poll') {
+    const s = telegramSettings(cfg);
+    if (!s.enabled) {
+      console.log('✗ Telegram is not configured. Run: arena-bridge telegram setup --token <bot token> --chat-id <id>');
+      process.exitCode = 1;
+      return;
+    }
+    console.log('listening for Telegram messages (Ctrl+C to stop)…');
+    const poller = startPoller(cfg, {
+      onMessage: async (item) => console.log(`#${item.id} ${item.from}: ${item.text}`),
+    });
+    await new Promise(() => {});
+    return poller;
+  }
+
+  const s = telegramSettings(cfg);
+  const st = inboxState();
+  console.log(`enabled   : ${s.enabled}`);
+  console.log(`bot       : ${st.bot?.username ? '@' + st.bot.username : '(unknown)'}`);
+  console.log(`chats     : ${s.chatIds.join(', ') || '(none)'}`);
+  console.log(`polling   : ${s.poll}`);
+  console.log(`messages  : ${st.total} (${st.unread} unread)`);
+  if (st.lastError) console.log(`last error: ${st.lastError}`);
+  if (!s.enabled) {
+    console.log('\nRun: arena-bridge telegram setup --token <bot token> --chat-id <your id>');
+  }
+}
+
 function cmdDoctor() {
   const cfg = loadConfig();
   const checks = [];
@@ -638,6 +730,8 @@ export async function main(argv = process.argv.slice(2)) {
       return cmdApprove(args);
     case 'audit':
       return cmdAudit(args);
+    case 'telegram':
+      return cmdTelegram(args);
     case 'rotate':
       return cmdRotate(args);
     case 'trust':

package/src/config.mjs

@@ -48,6 +48,14 @@ export const DEFAULTS = {
   maxUploadBytes: 16 * 1024 * 1024,
   commandTimeoutSec: 120,
   audit: true,
+  telegram: {
+    enabled: false, // notify the user in Telegram
+    botToken: null, // bot token from @BotFather
+    chatIds: [], // chats the bridge may write to
+    poll: true, // listen for incoming messages and approval commands
+    apiId: null, // optional MTProto app id (not used by the bot)
+    apiHash: null, // optional MTProto app hash (not used by the bot)
+  },
 };
 
 export function expandHome(p) {

package/src/direct.mjs

@@ -7,6 +7,7 @@ import { listApprovals, decide } from './approvals.mjs';
 import { checkPath } from './policy.mjs';
 import { loadConfig } from './config.mjs';
 import { tailAudit, readArtifact, auditDir } from './audit.mjs';
+import { startPoller, parseCommand, sendTelegram } from './telegram.mjs';
 
 export function createDirectServer(cfg, engine) {
   const mcpCtx = {
@@ -15,6 +16,27 @@ export function createDirectServer(cfg, engine) {
     callTool: (name, args) => engine.call(name, args),
   };
 
+  const handleTelegramMessage = async (item) => {
+    const cmd = parseCommand(item.text);
+    if (!cmd) return;
+    const current = loadConfig();
+    const say = (text) => sendTelegram(current, { text, chatId: item.chat_id });
+    if ((cmd.cmd === 'approve' || cmd.cmd === 'deny') && cmd.args) {
+      const res = decide(cmd.args, cmd.cmd === 'approve' ? 'approve' : 'deny', 'telegram');
+      await say(res.ok ? `${cmd.cmd === 'approve' ? 'Approved' : 'Denied'} ${cmd.args}` : `Cannot ${cmd.cmd}: ${res.error}`);
+      return;
+    }
+    if (cmd.cmd === 'status') {
+      const pending = listApprovals().filter((a) => a.status === 'pending').length;
+      await say(`arena-bridge on ${cfg.device}\nPending approvals: ${pending}`);
+      return;
+    }
+    if (cmd.cmd === 'help') {
+      await say('Commands: /approve <id>, /deny <id>, /status');
+      return;
+    }
+  };
+
   const server = http.createServer(async (req, res) => {
     let url;
     try {
@@ -30,7 +52,7 @@ export function createDirectServer(cfg, engine) {
           ok: true,
           mode: 'direct',
           device: cfg.device,
-          version: '0.6.10',
+          version: '0.7.1',
           uptime_sec: Math.round(process.uptime()),
         });
       }
@@ -60,6 +82,10 @@ export function createDirectServer(cfg, engine) {
           allowShell: cfg.allowShell,
           approvalWaitSec: cfg.approvalWaitSec,
           maxOutputBytes: cfg.maxOutputBytes,
+          telegram: {
+            enabled: !!cfg.telegram?.enabled,
+            chat_ids: cfg.telegram?.chatIds || [],
+          },
         });
       }
 
@@ -152,5 +178,8 @@ export function createDirectServer(cfg, engine) {
     }
   });
 
+  const poller = startPoller(cfg, { onMessage: handleTelegramMessage });
+  server.on('close', () => poller?.stop());
+
   return server;
 }

package/src/engine.mjs

@@ -10,6 +10,7 @@ import { loadConfig, CONFIG_PATH } from './config.mjs';
 import { BrowserManager } from './browser.mjs';
 import { macTools } from './mac.mjs';
 import { trustState, trustAllows } from './trust.mjs';
+import { telegramTools } from './telegram.mjs';
 
 /* ------------------------------------------------------------------ *
  * helpers
@@ -630,7 +631,7 @@ export class Engine {
   }
 
   catalog() {
-    return [...toolCatalog(), ...this.browser.tools(), ...macTools(this.cfg)];
+    return [...toolCatalog(), ...this.browser.tools(), ...macTools(this.cfg), ...telegramTools(this.cfg)];
   }
 
   async call(name, args = {}, { requireApproval } = {}) {

package/src/hub.mjs

@@ -90,7 +90,7 @@ export function createHubServer(cfg) {
         return sendJson(res, 200, {
           ok: true,
           mode: 'hub',
-          version: '0.6.10',
+          version: '0.7.1',
           devices: [...devices.keys()],
         });
       }

package/src/mcp.mjs

@@ -48,7 +48,7 @@ export async function handleMcp(req, res, ctx) {
           mcpResponse(id, {
             protocolVersion: PROTOCOL_VERSION,
             capabilities: { tools: { listChanged: false } },
-            serverInfo: { name: 'arena-bridge', version: '0.6.10' },
+            serverInfo: { name: 'arena-bridge', version: '0.7.1' },
             instructions:
               'Tools operate the user\'s own machine. Dangerous operations may return ' +
               'PROTECTED and require a local human approval.',

package/src/prompt.mjs

@@ -65,6 +65,7 @@ ${tools.join('\n')}
 | wait for a control to appear or vanish | \`mac_wait\` |
 | work on a separate virtual desktop | \`mac_spaces\`, \`mac_space_switch\` |
 | look at files | \`list_dir\` (top level only; add \`{"recursive":true}\` to go deeper), \`read_file\`, \`search_files\` |
+| tell the user something or ask a question | \`notify_user\` (Telegram), \`telegram_inbox\` to read the answer |
 
 ## Browser control (Chrome over CDP)
 1. \`chrome_launch\` starts a browser that belongs to you — own profile, no personal data.
@@ -104,6 +105,15 @@ the accessibility trees that were read are stored next to the log.
 - \`audit_artifact\` — fetch a saved artifact: a screenshot (base64 PNG) or an accessibility tree (JSON).
 Use them when you need to look back at what was on the screen or what the interface contained.
 
+## Talking to the user (Telegram)
+When Telegram is configured for this bridge, you can reach the user outside this chat:
+- \`notify_user\` — send a message (progress, a question, a finished result).
+  Add \`{"wait_for_reply": true}\` to keep the call open until the user answers in Telegram.
+- \`telegram_inbox\` — read the messages the user sent in Telegram (answers, requests, corrections).
+- \`telegram_status\` — the bot, the allowed chats, the number of unread messages.
+- The user can settle a pending approval from Telegram: \`/approve <approval_id>\` or \`/deny <approval_id>\`.
+Use it when a step takes long or when you need a decision: one message is enough, no need to repeat it.
+
 ## Approvals
 ${trustLine}
 - When a call answers \`APPROVAL_PENDING\` it carries an \`approval_id\`: tell the user to run

package/src/telegram.mjs

@@ -0,0 +1,446 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { CONFIG_DIR, ensureDirs, loadConfig } from './config.mjs';
+
+const DEFAULT_BASE = 'https://api.telegram.org';
+const MAX_TEXT = 4000;
+const RATE_LIMIT = 20;
+const RATE_WINDOW_MS = 60_000;
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/* ------------------------------------------------------------------ *
+ * settings
+ * ------------------------------------------------------------------ */
+
+export function telegramSettings(cfg = {}) {
+  const t = cfg.telegram || {};
+  const baseUrl = String(t.baseUrl || process.env.TELEGRAM_API_BASE || DEFAULT_BASE).replace(/\/+$/, '');
+  return {
+    enabled: !!t.enabled && !!t.botToken,
+    botToken: t.botToken || null,
+    chatIds: (t.chatIds || []).map((v) => String(v)),
+    baseUrl,
+    poll: t.poll !== false,
+    apiId: t.apiId || null,
+    apiHash: t.apiHash || null,
+  };
+}
+
+export function telegramDir() {
+  return path.join(CONFIG_DIR, 'telegram');
+}
+
+export function inboxPath() {
+  return path.join(telegramDir(), 'inbox.jsonl');
+}
+
+export function statePath() {
+  return path.join(telegramDir(), 'state.json');
+}
+
+function ensureTelegramDir() {
+  ensureDirs();
+  fs.mkdirSync(telegramDir(), { recursive: true, mode: 0o700 });
+}
+
+function readState() {
+  try {
+    return JSON.parse(fs.readFileSync(statePath(), 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function writeState(state) {
+  ensureTelegramDir();
+  fs.writeFileSync(statePath(), JSON.stringify(state, null, 2) + '\n', { mode: 0o600 });
+}
+
+/* ------------------------------------------------------------------ *
+ * bot api
+ * ------------------------------------------------------------------ */
+
+export async function apiCall(cfg, method, payload = {}) {
+  const s = telegramSettings(cfg);
+  if (!s.botToken) {
+    return {
+      ok: false,
+      error: 'telegram_not_configured',
+      reason: 'no bot token in the configuration',
+      hint: 'Run: arena-bridge telegram setup --token <bot token> --chat-id <your id>',
+    };
+  }
+  let res;
+  let data = null;
+  try {
+    res = await fetch(`${s.baseUrl}/bot${s.botToken}/${method}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(90_000),
+    });
+    data = await res.json().catch(() => null);
+  } catch (e) {
+    return { ok: false, error: 'telegram_unreachable', reason: e.message };
+  }
+  if (!res.ok || !data || data.ok !== true) {
+    return {
+      ok: false,
+      error: 'telegram_api_error',
+      reason: data?.description || res.statusText || 'unknown error',
+      code: data?.error_code,
+    };
+  }
+  return { ok: true, result: data.result };
+}
+
+export function allowedChat(cfg, chatId) {
+  const s = telegramSettings(cfg);
+  return s.chatIds.includes(String(chatId));
+}
+
+const sentAt = [];
+
+export function rateOk(limit = RATE_LIMIT, windowMs = RATE_WINDOW_MS) {
+  const now = Date.now();
+  while (sentAt.length && now - sentAt[0] > windowMs) sentAt.shift();
+  if (sentAt.length >= limit) return false;
+  sentAt.push(now);
+  return true;
+}
+
+/**
+ * Send a text message to one of the allowed chats.
+ */
+export async function sendTelegram(cfg, { text, chatId, title, silent } = {}) {
+  const s = telegramSettings(cfg);
+  if (!s.enabled) {
+    return {
+      ok: false,
+      error: 'telegram_not_configured',
+      reason: 'Telegram is not configured for this bridge',
+      hint: 'Run: arena-bridge telegram setup --token <bot token> --chat-id <your id>',
+    };
+  }
+  const target = String(chatId ?? s.chatIds[0] ?? '');
+  if (!target) {
+    return { ok: false, error: 'telegram_no_chat', reason: 'no chat id configured' };
+  }
+  if (!allowedChat(cfg, target)) {
+    return {
+      ok: false,
+      error: 'telegram_chat_not_allowed',
+      reason: `chat ${target} is not on the allow list`,
+    };
+  }
+  const body = String(text ?? '').trim();
+  if (!body) return { ok: false, error: 'telegram_empty_message', reason: 'the message is empty' };
+  if (body.length > MAX_TEXT) {
+    return {
+      ok: false,
+      error: 'telegram_message_too_long',
+      reason: `the message is ${body.length} characters, the limit is ${MAX_TEXT}`,
+    };
+  }
+  if (!rateOk()) {
+    return {
+      ok: false,
+      error: 'telegram_rate_limited',
+      reason: `more than ${RATE_LIMIT} messages per minute`,
+    };
+  }
+  const text_ = title ? `${title}\n${body}` : body;
+  let res = await apiCall(cfg, 'sendMessage', {
+    chat_id: target,
+    text: text_,
+    disable_notification: !!silent,
+  });
+  if (!res.ok && /parse entities|Markdown/i.test(res.reason || '')) {
+    res = await apiCall(cfg, 'sendMessage', {
+      chat_id: target,
+      text: text_,
+      disable_notification: !!silent,
+    });
+  }
+  if (!res.ok) return res;
+  return {
+    ok: true,
+    chat_id: res.result?.chat?.id ?? target,
+    message_id: res.result?.message_id ?? null,
+    sent_at: new Date().toISOString(),
+  };
+}
+
+/* ------------------------------------------------------------------ *
+ * inbox
+ * ------------------------------------------------------------------ */
+
+export function appendInbox(item) {
+  ensureTelegramDir();
+  fs.appendFileSync(inboxPath(), JSON.stringify(item) + '\n', { mode: 0o600 });
+}
+
+export function readInbox({ limit = 20 } = {}) {
+  let raw = '';
+  try {
+    raw = fs.readFileSync(inboxPath(), 'utf8');
+  } catch {
+    return [];
+  }
+  const read = new Set(readState().read || []);
+  const items = raw
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+  return items.slice(-Math.max(1, limit)).map((i) => ({ ...i, read: read.has(String(i.id)) }));
+}
+
+export function markInboxRead(ids) {
+  const state = readState();
+  const read = new Set(state.read || []);
+  for (const id of ids || []) read.add(String(id));
+  state.read = [...read].slice(-500);
+  writeState(state);
+  return state.read.length;
+}
+
+export function inboxState() {
+  const state = readState();
+  let total = 0;
+  try {
+    total = fs.readFileSync(inboxPath(), 'utf8').split('\n').filter(Boolean).length;
+  } catch {
+    total = 0;
+  }
+  const read = new Set(state.read || []);
+  return {
+    total,
+    unread: Math.max(0, total - read.size),
+    bot: state.bot || null,
+    offset: state.offset || 0,
+    lastError: state.lastError || null,
+  };
+}
+
+export function saveBotInfo(info) {
+  const state = readState();
+  state.bot = info;
+  writeState(state);
+}
+
+/* ------------------------------------------------------------------ *
+ * commands
+ * ------------------------------------------------------------------ */
+
+/**
+ * Parse a chat command like "/approve 1234" into { cmd, args }.
+ */
+export function parseCommand(text) {
+  const raw = String(text ?? '').trim();
+  if (!raw.startsWith('/')) return null;
+  const [cmd, ...rest] = raw.slice(1).split(/\s+/);
+  return { cmd: cmd.toLowerCase(), args: rest.join(' ').trim() };
+}
+
+/* ------------------------------------------------------------------ *
+ * poller
+ * ------------------------------------------------------------------ */
+
+/**
+ * Poll the bot for incoming messages and hand them to the callback.
+ * Returns a handle with stop().
+ */
+export function startPoller(cfg, { onMessage } = {}) {
+  const s = telegramSettings(cfg);
+  if (!s.enabled || !s.poll) return null;
+  let stopped = false;
+  let offset = readState().offset || 0;
+
+  const fresh = () => {
+    try {
+      return loadConfig();
+    } catch {
+      return cfg;
+    }
+  };
+
+  const loop = async () => {
+    if (!readState().bot) {
+      const me = await apiCall(fresh(), 'getMe');
+      if (me.ok) saveBotInfo(me.result);
+    }
+    while (!stopped) {
+      try {
+        const res = await apiCall(fresh(), 'getUpdates', {
+          offset,
+          timeout: 20,
+          allowed_updates: ['message'],
+        });
+        if (!res.ok) {
+          const state = readState();
+          state.lastError = res.reason || res.error;
+          writeState(state);
+          await sleep(res.code === 409 ? 15000 : 5000);
+          continue;
+        }
+        const updates = res.result || [];
+        if (!updates.length) {
+          await sleep(400);
+          continue;
+        }
+        for (const upd of updates) {
+          offset = upd.update_id + 1;
+          const state = readState();
+          state.offset = offset;
+          writeState(state);
+          const msg = upd.message;
+          if (!msg) continue;
+          const item = {
+            id: upd.update_id,
+            chat_id: msg.chat?.id ?? null,
+            from: msg.from?.username || msg.from?.first_name || 'unknown',
+            text: msg.text || '',
+            date: msg.date || null,
+            read: false,
+          };
+          appendInbox(item);
+          if (onMessage) {
+            try {
+              await onMessage(item);
+            } catch {
+              /* the callback must not kill the loop */
+            }
+          }
+        }
+      } catch {
+        await sleep(5000);
+      }
+    }
+  };
+
+  loop();
+  return {
+    stop() {
+      stopped = true;
+    },
+  };
+}
+
+/* ------------------------------------------------------------------ *
+ * tools
+ * ------------------------------------------------------------------ */
+
+const S = (o) => ({ type: 'object', properties: o, required: [], additionalProperties: false });
+
+async function waitForReply(cfg, sinceId, timeoutSec) {
+  const deadline = Date.now() + Math.max(1, timeoutSec) * 1000;
+  while (Date.now() < deadline) {
+    const items = readInbox({ limit: 20 });
+    const fresh = items.find((i) => Number(i.id) > sinceId);
+    if (fresh) return fresh;
+    await sleep(500);
+  }
+  return null;
+}
+
+export function telegramTools(cfg = {}) {
+  return [
+    {
+      name: 'notify_user',
+      description:
+        'Send a message to the user in Telegram. Use it to report progress, ask a question, or hand over ' +
+        'a result without waiting for the chat. Set wait_for_reply to keep the call open until the user ' +
+        'answers in Telegram.',
+      approval: false,
+      schema: S({
+        text: { type: 'string', description: 'the message text (up to 4000 characters)' },
+        title: { type: 'string', description: 'short first line, e.g. "Готово" or "Нужен ответ"' },
+        chat_id: { type: 'string', description: 'target chat id (default: the configured one)' },
+        silent: { type: 'boolean', description: 'send without a sound' },
+        wait_for_reply: { type: 'boolean', description: 'wait for the user to answer in Telegram' },
+        timeout_sec: { type: 'number', description: 'how long to wait for a reply (default 120, max 600)' },
+      }),
+      required: ['text'],
+      handler: async (args, ctx) => {
+        const c = ctx?.cfg || cfg;
+        const sent = await sendTelegram(c, {
+          text: args.text,
+          chatId: args.chat_id,
+          title: args.title,
+          silent: args.silent,
+        });
+        if (!sent.ok) return sent;
+        if (!args.wait_for_reply) return sent;
+        const since = Math.max(0, ...readInbox({ limit: 50 }).map((i) => Number(i.id) || 0));
+        const reply = await waitForReply(c, since, Math.min(600, Number(args.timeout_sec) || 120));
+        if (!reply) {
+          return {
+            ...sent,
+            reply: null,
+            timed_out: true,
+            hint: 'The user did not answer in Telegram. Continue without the answer or ask again later.',
+          };
+        }
+        markInboxRead([reply.id]);
+        return { ...sent, reply: { from: reply.from, text: reply.text, at: reply.date } };
+      },
+    },
+    {
+      name: 'telegram_inbox',
+      description:
+        'Read the messages the user sent in Telegram. Use it to pick up an answer, a file name or a ' +
+        'command given outside the agent chat.',
+      approval: false,
+      schema: S({
+        limit: { type: 'number', description: 'how many messages to return (default 20)' },
+        mark_read: { type: 'boolean', description: 'mark the returned messages as read (default true)' },
+      }),
+      required: [],
+      handler: async (args, ctx) => {
+        const c = ctx?.cfg || cfg;
+        const limit = Math.min(100, Number(args.limit) || 20);
+        const items = readInbox({ limit });
+        if (args.mark_read !== false && items.length) markInboxRead(items.map((i) => i.id));
+        return { ok: true, count: items.length, messages: items };
+      },
+    },
+    {
+      name: 'telegram_status',
+      description: 'Show the Telegram link: the bot, the allowed chats and how many messages are unread.',
+      approval: false,
+      schema: S({}),
+      required: [],
+      handler: async (args, ctx) => {
+        const c = ctx?.cfg || cfg;
+        const s = telegramSettings(c);
+        if (!s.enabled) {
+          return {
+            ok: false,
+            error: 'telegram_not_configured',
+            reason: 'Telegram is not configured for this bridge',
+            hint: 'Run: arena-bridge telegram setup --token <bot token> --chat-id <your id>',
+          };
+        }
+        const st = inboxState();
+        return {
+          ok: true,
+          bot: st.bot?.username ? `@${st.bot.username}` : null,
+          bot_name: st.bot?.first_name || null,
+          chat_ids: s.chatIds,
+          total_messages: st.total,
+          unread: st.unread,
+          polling: s.poll,
+          last_error: st.lastError,
+        };
+      },
+    },
+  ];
+}