dsh-telegram-multiagent 1.0.0

package/README.md

@@ -0,0 +1,107 @@
+# dsh-telegram-multiagent
+
+A Telegram channel for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): message
+your agent from a phone, get answers back, keep one conversation per chat.
+
+The harness ships no messenger channel — there is no channel abstraction in the product at all. This
+plugin builds one out of the two ends the harness does give you:
+
+```
+in:   ctx.agents.create/resume(...) → agent.send(message)
+out:  ctx.on('session/event', ...)  → send to Telegram
+```
+
+One chat = one session = one agent. Sessions live independently, the way the core intends.
+
+## Install
+
+```bash
+# inside your profile directory ($DSH_HOME/profiles/<name>)
+pnpm add dsh-telegram-multiagent
+```
+
+Then add one row to your **agent preset** (`agent.cordis.yml`), not to the profile patch layer —
+see "Where to put the row" below:
+
+```yaml
+- insert:
+    - name: dsh-telegram-multiagent
+      config:
+        agentName: my-agent            # log label only
+        tokenFile: /etc/dsh/bot.token  # preferred: a file readable by this agent
+        appDir: /opt/my-agent/app      # where THIS agent's harness is installed
+        workspace: /opt/my-agent/work
+        allowedUsers: [123456789]      # empty = everyone; you do not want that
+```
+
+## Configuration
+
+| Field | Required | What it does |
+|---|---|---|
+| `tokenFile` | one of these | Path to a file holding the bot token. Preferred: the secret belongs to the machine, the config only carries a path. |
+| `token` / `tokenEnv` | one of these | Literal token, or the name of an env var. For debugging. |
+| `appDir` | yes | Directory where this agent's harness is installed. Platform packages are resolved from **here**, not from the plugin's own location — see "Why appDir" below. |
+| `agentName` | no | Label in log lines. Useful when several bots run on one machine. |
+| `allowedUsers` | no | Numeric user ids allowed to talk to the agent. **Empty means everyone** — an agent usually has real access to the machine, so set it. |
+| `workspace` | no | Working directory handed to the agent session. |
+| `preset` | no | Agent preset to mount for sessions created by this channel. |
+| `provider` / `model` | no | Fallback if the deployment has no default model service. |
+| `a2aDir` | no | Directory for a file-based agent-to-agent channel (`in/`, `out/`). Omit and no such channel exists. |
+| `a2aSession` | no | Session id used for that channel. Default `a2a`. |
+| `transcribeCommand` | no | External command for voice messages: `<cmd> <audio-file> auto` → transcript on stdout. Omit and voice is politely refused. |
+
+## Four things that cost us a day
+
+Each of these fails **while looking like success**. They are commented inline in the source; this is
+the short version.
+
+**1. Polling belongs to the bot, not to the mount.** The harness mounts a composition more than once
+per process and unmounts the extra one. With a single shared `running` flag you get two pollers
+fighting over one bot and Telegram cuts both with `Conflict`. With a polite "new mount asks the old
+one to step aside" you get *no* poller at all — because the new mount is the one that gets unmounted.
+The fix is reference counting: the first mount starts polling, the last unmount stops it.
+
+**2. Delete the incoming message only after it reached the agent.** Reading a file and unlinking it
+immediately loses the message whenever the handoff fails — and the handoff *will* fail, see (3).
+From the outside that is indistinguishable from "the bot ignored me".
+
+**3. The agent factory appears later than the channel.** The first message can arrive before the
+harness has registered it, and you get `no agent factory registered`. Wait for the platform instead
+of assuming it is ready.
+
+**4. A session already on disk must be resumed, not created.** Calling `create()` with an existing
+session id makes the persistence layer abort *every* turn with an id-collision error. Externally:
+"accepted the message and went quiet" — the turn honestly starts and dies in milliseconds. It works
+until the first restart, which is what makes it nasty. Use `resume()` when the session exists.
+
+## Where to put the row
+
+In the `web` profile the common-plane tools are **disabled on purpose**; the toolset comes from the
+agent preset. A plugin row placed in the profile patch layer composes without a single error, is
+listed as mounted — and never reaches the agent. Put the row in the agent preset.
+
+The preset is also picked up when a **session is created**: editing the file does not affect a
+running session. Restart the platform, or change the default preset in settings (hot-reloaded, takes
+effect for the next created session).
+
+## Why `appDir`
+
+The plugin resolves `@deepseek-ai/dsh-llm` and `@deepseek-ai/dsh-agent` from the directory you pass
+in `appDir`, not from its own location. That is deliberate: the module is meant to live once on a
+machine and serve several agents, each with its own harness installation. Hard-linking it to one
+agent's `node_modules` would mean that removing *that* agent breaks the channel for everybody else.
+
+## Security notes
+
+- `allowedUsers` empty means anyone who finds the bot talks to an agent that usually has shell access
+  to the machine. Set it.
+- A rejected stranger is logged and reported to the owner. A silent refusal hides a security event.
+- The token is read from a file at startup; the config carries a path, not a secret.
+
+## Status
+
+Written for our own fleet and running in production on several agents. The harness is young
+(`0.1.0-rc`) and its plugin API moves; expect to adapt. Inline comments are currently in Russian —
+they carry the reasoning behind each non-obvious line, and a translation is welcome.
+
+MIT.

package/cordis.patch.yml

@@ -0,0 +1,19 @@
+# Bundle patch: what `dsh plugin add` composes into the profile.
+#
+# 🔴 Note for anyone copying this: in the `web` profile the common-plane tools
+# are disabled on purpose and the agent's toolset comes from its preset. If your
+# agent must use tools, the channel row belongs in the AGENT PRESET, not here —
+# a row in the profile layer composes cleanly, reports as mounted, and never
+# reaches the agent. This file exists so the plugin is installable in one
+# command; see the README for the preset placement.
+- insert:
+    - name: dsh-telegram-multiagent
+      config:
+        # Path to a file holding the bot token. Preferred over a literal token.
+        tokenFile: /etc/dsh/bot.token
+        # Where THIS agent's harness is installed — platform packages resolve
+        # from here, so one shared module can serve several agents.
+        appDir: /opt/agent/app
+        # Empty means everyone can talk to an agent that usually has shell
+        # access. Set it.
+        allowedUsers: []

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "dsh-telegram-multiagent",
+  "version": "1.0.0",
+  "description": "Telegram channel for DeepSeek Harness — one shared module serving several agents on a machine, each with its own bot, token file and allow-list.",
+  "type": "module",
+  "main": "src/index.js",
+  "files": [
+    "src",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "telegram",
+    "agent",
+    "channel"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iia-arg/dsh-plugins.git",
+    "directory": "packages/telegram-channel"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}

package/src/client.js

@@ -0,0 +1,83 @@
+/**
+ * Telegram Bot API — минимальный клиент, БЕЗ зависимостей.
+ *
+ * 🔴 Почему руками, а не готовой библиотекой: плагин dsh обязан быть
+ * самодостаточным бандлом и НЕ ТАЩИТЬ второй экземпляр фреймворка Cordis.
+ * Любая крупная библиотека рискует притащить свой. Здесь только fetch.
+ */
+
+const API = 'https://api.telegram.org/bot';
+
+export class TelegramClient {
+  constructor(token, log) {
+    this.token = token;
+    this.log = log ?? (() => {});
+    this.offset = 0;
+  }
+
+  async call(method, payload, timeoutMs = 15000) {
+    const ctl = new AbortController();
+    const t = setTimeout(() => ctl.abort(), timeoutMs);
+    try {
+      const res = await fetch(`${API}${this.token}/${method}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(payload ?? {}),
+        signal: ctl.signal,
+      });
+      const data = await res.json();
+      if (!data.ok) throw new Error(`${method}: ${data.description ?? 'неизвестная ошибка'}`);
+      return data.result;
+    } finally {
+      clearTimeout(t);
+    }
+  }
+
+  /** Длинный опрос. Возвращает пришедшие обновления и двигает смещение. */
+  async poll(timeoutSec = 25) {
+    // timeout запроса больше, чем у сервера, иначе рвём его же длинный опрос
+    const updates = await this.call('getUpdates',
+      { offset: this.offset, timeout: timeoutSec, allowed_updates: ['message'] },
+      (timeoutSec + 10) * 1000);
+    for (const u of updates) {
+      if (u.update_id >= this.offset) this.offset = u.update_id + 1;
+    }
+    return updates;
+  }
+
+  /**
+   * Отправка с нарезкой: у Telegram предел 4096 знаков на сообщение.
+   * Режем по границам абзацев и строк, чтобы не рвать слова и разметку.
+   */
+  async send(chatId, text) {
+    const LIMIT = 4000;
+    const chunks = [];
+    let rest = String(text ?? '').trim();
+    if (!rest) return;
+    while (rest.length > LIMIT) {
+      let cut = rest.lastIndexOf('\n\n', LIMIT);
+      if (cut < LIMIT * 0.5) cut = rest.lastIndexOf('\n', LIMIT);
+      if (cut < LIMIT * 0.5) cut = rest.lastIndexOf(' ', LIMIT);
+      if (cut < LIMIT * 0.5) cut = LIMIT;
+      chunks.push(rest.slice(0, cut));
+      rest = rest.slice(cut).trimStart();
+    }
+    if (rest) chunks.push(rest);
+    for (const c of chunks) {
+      await this.call('sendMessage', { chat_id: chatId, text: c });
+    }
+  }
+
+  async typing(chatId) {
+    try { await this.call('sendChatAction', { chat_id: chatId, action: 'typing' }, 8000); }
+    catch { /* индикатор необязателен, молча пропускаем */ }
+  }
+
+  async whoAmI() { return this.call('getMe'); }
+
+  /** Возвращает file_path для скачивания (нужен для голосовых). */
+  async getFilePath(fileId) {
+    const file = await this.call('getFile', { file_id: fileId });
+    return file.file_path;
+  }
+}

package/src/index.js

@@ -0,0 +1,568 @@
+/**
+ * Канал Telegram для DeepSeek Harness — ОБЩИЙ МОДУЛЬ МАШИНЫ.
+ *
+ * Написан нами, а не взят из каталога плагинов, сознательно: к боту заходят
+ * живые люди, а чужие плагины в этой экосистеме публикуются в том числе без
+ * исходников, и проверять там нечего.
+ *
+ * 🔴 ОДИН КОД — МНОГО АГЕНТОВ (требование владельца 19.08.2026). Раньше модуль
+ * назывался именем агента и стоял в его личном каталоге; второму агенту канал
+ * пришлось бы копировать, и дальше две копии расходятся молча. Теперь код
+ * лежит в системном каталоге в ЕДИНСТВЕННОМ экземпляре, а всё различающее
+ * агентов живёт в НАСТРОЙКЕ: токен, кто допущен, модель, рабочий каталог, имя
+ * в журнале, каталог межагентского обмена. Подключение нового бота — строка в
+ * слое профиля плюс файл токена, без единой правки кода.
+ *
+ * ГДЕ ТОКЕН. Никогда в конфиге агента и не в переменной окружения по умолчанию:
+ * `tokenFile` — путь к файлу, который читает только этот агент (как сделано с
+ * подпиской). Значение через `token`/переменную оставлено для отладки.
+ *
+ * УСТРОЙСТВО. Своего понятия «канал» у dsh нет — контракт складывается из двух концов:
+ *   вход:  ctx.agents.create(...) → agent.followup(сообщение)
+ *   выход: ctx.on('session/event') → отправка в Telegram
+ * Один чат = одна сессия = один агент. Сессии живут независимо, как и задумано ядром.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { execFileSync } from 'node:child_process';
+import { TelegramClient } from './client.js';
+import { createRequire } from 'node:module';
+
+/**
+ * 🔴 ПАКЕТЫ ПЛАТФОРМЫ РАЗРЕШАЕМ ОТ КАТАЛОГА АГЕНТА, А НЕ ОТ СВОЕГО.
+ * Код общий и лежит в системном каталоге, где никакой платформы рядом нет.
+ * Обычный импорт искал бы её рядом с собой и падал, а привязка к установке
+ * одного агента (симлинк на его node_modules) означала бы, что снос ЕГО
+ * платформы ломает канал у ВСЕХ остальных. Поэтому каждый агент передаёт
+ * `appDir` — свою установку, — и связь остаётся его собственной.
+ * `installModelSelection` берём из dsh-agent, а не dsh-session: проверено по
+ * импортам самого продукта.
+ */
+let platformCache = null;
+function platformOf(config, log) {
+  if (platformCache) return platformCache;
+  const from = config.appDir || process.env.DSH_APP_DIR;
+  if (!from) {
+    log('🔴 не задан appDir: канал не знает, где установлена платформа этого агента');
+    return null;
+  }
+  try {
+    const req = createRequire(path.join(from, 'разрешение-зависимостей.js'));
+    platformCache = {
+      createUserMessage: req('@deepseek-ai/dsh-llm').createUserMessage,
+      installModelSelection: req('@deepseek-ai/dsh-agent').installModelSelection,
+    };
+    return platformCache;
+  } catch (e) {
+    log(`🔴 пакеты платформы не разрешились от ${from}: ${e?.message ?? e}`);
+    return null;
+  }
+}
+
+/**
+ * Опросы Telegram, живущие в ЭТОМ процессе, по токену бота. Нужен именно
+ * общий на модуль реестр: платформа монтирует состав несколько раз, и без него
+ * два опроса одного бота дерутся, а Telegram рвёт обоих ошибкой Conflict.
+ */
+const ACTIVE_POLLERS = new Map();
+
+export const name = 'dsh-telegram-channel';
+export const inject = ['agents'];
+
+/**
+ * Токен бота: файл (наш способ) → значение в конфиге → переменная окружения.
+ * Файл предпочтителен: секрет принадлежит машине, права выдаются агенту, а в
+ * составе профиля лежит только ПУТЬ, который не жалко ни в журнале, ни в копии.
+ */
+function readTokenFrom(config, log) {
+  if (config.tokenFile) {
+    try {
+      const t = fs.readFileSync(config.tokenFile, 'utf8').trim();
+      if (t) return t;
+      log(`🔴 файл токена ${config.tokenFile} пуст`);
+    } catch (e) {
+      // Не глотать: «бот молчит» и «мне не дали прочитать токен» — разные беды,
+      // а выглядят снаружи одинаково.
+      log(`🔴 не прочитан файл токена ${config.tokenFile}: ${e?.message ?? e}`);
+    }
+    return null;
+  }
+  const t = config.token || process.env[config.tokenEnv || 'DSH_TELEGRAM_BOT_TOKEN'];
+  if (t) return t;
+  log('🔴 нет токена: задайте config.tokenFile (предпочтительно), config.token или переменную окружения');
+  return null;
+}
+
+export function apply(ctx, config = {}) {
+  // Имя агента — только для журнала: при нескольких ботах на машине нужно
+  // видеть, чья строка. К логике отношения не имеет.
+  const who = config.agentName || 'telegram';
+  const log = (m) => console.error(`[${who}] ${m}`);
+
+  const token = readTokenFrom(config, log);
+  if (!token) return;
+
+  const platform = platformOf(config, log);
+  if (!platform) return;  // без пакетов платформы канал бесполезен — молчать нельзя, выше уже сказано почему
+
+  // Белый список: пусто = пускать всех. Понятия «пользователь» в ядре нет,
+  // ограничение доступа целиком на нашей стороне.
+  const allowed = new Set((config.allowedUsers ?? []).map(Number));
+  const isAllowed = (userId) => allowed.size === 0 || allowed.has(Number(userId));
+
+  const tg = new TelegramClient(token, log);
+  const chats = new Map();          // chatId → { handle, sessionId }
+  const sessionToChat = new Map();  // sessionId → chatId
+
+  /** Один чат — один агент. Создаём лениво, при первом сообщении. */
+  // ── ДОБИТЬ ПОБУДКУ (обосновано замером 18.08.2026, а не догадкой).
+  // В dsh-agent-loop, wakeDriver(): если агент НЕ в простое и это не maintenance
+  // и не пробуждение после отмены — флаг побудки НЕ запоминается, функция просто
+  // выходит. Наблюдали живьём: агент завис в вызове инструмента, сообщение легло
+  // в очередь next-turn в 20:06:46, побудка пропала, хода не началось вовсе —
+  // ни ошибки, ни turn/start, полная тишина.
+  //
+  // Поэтому после отправки следим: как только агент освободился, а сообщение всё
+  // ещё в очереди — будим повторно.
+  //
+  // 🔴 НИКАКИХ ТИХИХ ВЫХОДОВ: каждая ветка что-то пишет в журнал. Ровно на этом
+  // обжглись сегодня — `agent.inbox?.hasPending` при недоступном inbox даёт
+  // undefined, условие «всё хорошо» проходит, и отказ маскируется под успех.
+  function nudgeUntilClaimed(agent, tag, budgetMs = 120000) {
+    void (async () => {
+      const deadline = Date.now() + budgetMs;
+      let woke = 0;
+      while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 500));
+        if (typeof agent?.inbox?.hasPending !== 'boolean') {
+          log(`${tag} 🔴 очередь агента недоступна — добивать побудку нечем`);
+          return;
+        }
+        if (agent.status === 'running') continue;
+        if (!agent.inbox.hasPending) {
+          if (woke) log(`${tag} сообщение забрано после ${woke} повторных побудок`);
+          return;
+        }
+        if (typeof agent.wakeDriver !== 'function') {
+          log(`${tag} 🔴 сообщение висит в очереди, а wakeDriver недоступен`);
+          return;
+        }
+        agent.wakeDriver();
+        woke += 1;
+      }
+      log(`${tag} 🔴 за ${budgetMs} мс сообщение так и не забрали (побудок: ${woke})`);
+    })();
+  }
+
+  /**
+   * 🔴 ФАБРИКА АГЕНТОВ ПОЯВЛЯЕТСЯ ПОЗЖЕ КАНАЛА (поймано 19.08.2026 инструментовкой).
+   * Канал монтируется раньше, чем платформа регистрирует фабрику, и первое же
+   * сообщение падало с «no agent factory registered». Снаружи — «написал боту,
+   * он молчит», причём вопрос к тому моменту уже был удалён из входящих.
+   * Поэтому ждём готовности платформы, а не считаем её данностью.
+   */
+  async function withFactoryRetry(tag, fn, tries = 60) {
+    for (let i = 0; i < tries; i++) {
+      try {
+        return await fn();
+      } catch (e) {
+        const why = String(e?.message ?? e);
+        if (!why.includes('no agent factory registered')) throw e;  // другая беда — наверх, не глотать
+        if (i === 0) log(`${tag} фабрика агентов ещё не зарегистрирована — жду платформу`);
+        await new Promise((r) => setTimeout(r, 1000));
+      }
+    }
+    throw new Error(`фабрика агентов не появилась за ${tries} с`);
+  }
+
+  async function agentFor(chatId) {
+    const key = String(chatId);
+    const found = chats.get(key);
+    if (found) return found;
+    const sessionId = `telegram-${key}`;
+    // 🔴 Модель берём из штатного сервиса agentDefaultModel, а НЕ хардкодом,
+    // и передаём setup с installModelSelection — ровно так создаёт агента сам
+    // продукт (образец в dsh-headless). Без setup агент собирается неполным:
+    // в запрос к модели не попадает поле tools вообще, и агент физически не
+    // может вызвать ни один инструмент, хотя они смонтированы (проверено
+    // 2026-08-18 по событию request/header в журнале сессии).
+    const presets = ctx.get('agentPresets');
+    const presetId = presets ? (await presets.resolve(config.preset)).id : undefined;
+    const defaultModel = ctx.get('agentDefaultModel');
+    const selection = defaultModel?.currentSelection?.() ?? {
+      provider: config.provider,
+      model: config.model,
+    };
+    const setupFn = async (agentCtx) => {
+      platform.installModelSelection(agentCtx, { current: selection, assembled: undefined });
+      if (presets && presetId) await presets.mount(agentCtx, presetId);
+    };
+
+    // 🔴 СЕССИЮ, КОТОРАЯ УЖЕ ЛЕЖИТ НА ДИСКЕ, НАДО ПРОДОЛЖАТЬ, А НЕ СОЗДАВАТЬ ЗАНОВО.
+    // Раньше здесь всегда звался create() с тем же sessionId. Продукт при этом
+    // заводит НОВУЮ живую сессию, её семя не сходится с сохранёнными событиями,
+    // и dsh-session-persistence обрывает КАЖДЫЙ ход ошибкой:
+    //   session "..." is already persisted with N event(s) that do not match
+    //   this live session (id collision)
+    // Снаружи это выглядело как «принял сообщение и замолчал»: ход честно
+    // начинался и умирал за 7 мс. Работало только пока сессии не было на диске —
+    // то есть до первого перезапуска. Поймано 18.08.2026 печатью event.data
+    // события turn/end (раньше плагин печатал только тип события).
+    // Правильный путь — ctx.agents.resume(): «загрузить сохранённую сессию и
+    // продолжить агента на ней» (dsh-agent/lib/index.js, resume()).
+    const persistence = ctx.get('sessionPersistence');
+    let handle;
+    if (persistence) {
+      let onDisk = false;
+      try {
+        onDisk = (await persistence.list()).some((h) => h.id === sessionId);
+      } catch (e) {
+        log(`не смогла перечислить сохранённые сессии: ${e?.message ?? e}`);
+      }
+      if (onDisk) {
+        try {
+          handle = await ctx.agents.resume({
+            resumeSessionId: sessionId,
+            agentOptions: { provider: selection.provider, model: selection.model },
+            setup: setupFn,
+          });
+          log(`сессия ${sessionId} продолжена с диска (история сохранена)`);
+        } catch (e) {
+          log(`🔴 продолжить сессию ${sessionId} не удалось: ${e?.message ?? e}`);
+        }
+      }
+    }
+
+    if (handle === undefined) handle = await withFactoryRetry(`[${key}]`, () => ctx.agents.create({
+      sessionId,
+      meta: { cwd: config.workspace ?? process.cwd() },
+      agentOptions: { provider: selection.provider, model: selection.model },
+      // 🔴 ПРЕСЕТ ОБЯЗАТЕЛЕН, иначе агент остаётся БЕЗ ИНСТРУМЕНТОВ.
+      // В профиле web инструменты на общем плане ВЫКЛЮЧЕНЫ намеренно
+      // (в его сборке 9 строк с disabled: true) — набор приходит из
+      // агент-пресета, и его надо примонтировать явно. Без монтирования
+      // в запрос к модели не попадает поле tools вообще: агент отвечает
+      // «сейчас выполню команду» и не выполняет ничего, ход при этом
+      // честно завершается completed. Образец — composeAgent в dsh-host-apiproxy.
+      agentPreset: presetId,
+      setup: setupFn,
+    }));
+    const entry = { handle, sessionId };
+    chats.set(key, entry);
+    sessionToChat.set(sessionId, chatId);
+    log(`создан агент для чата ${key} (сессия ${sessionId})`);
+    return entry;
+  }
+
+  // ── ВЫХОД: события сессии → сообщения в Telegram
+  ctx.on('session/event', (session, event) => {
+    // 🔴 DEBUG 2026-08-18: все типы событий
+    log(`[event] type=${event.type} session.id=${session?.id} knownSessions=${[...sessionToChat.keys()].join('|')}`);
+    const chatId = sessionToChat.get(String(session?.id ?? ''));
+    if (chatId === undefined) {
+      if (event.type === 'assistant/message') log(`[event] chatId undefined для session ${session?.id} — игнорирую`);
+      return;
+    }
+    try {
+      if (event.type === 'turn/start') {
+        void tg.typing(chatId);
+      } else if (event.type === 'turn/end' && event.data?.reason?.kind === 'error') {
+        // 🔴 18.08.2026: ход может оборваться с внятной ошибкой, и она приходит
+        // ИМЕННО ЗДЕСЬ, в event.data.reason. Раньше плагин печатал только тип
+        // события и выбрасывал содержимое — снаружи это выглядело как «принял
+        // и замолчал», и на выдумывание причин ушёл вечер. Настоящая ошибка
+        // (столкновение идентификаторов сессии) лежала в потоке всё это время.
+        // Правило: причину обрыва показывать ВСЕГДА, и в журнал, и собеседнику.
+        const why = event.data.reason.error?.message ?? 'без описания';
+        log(`🔴 ход оборван ошибкой: ${why}`);
+        if (chatId === A2A_CHAT) {
+          try {
+            fs.mkdirSync(A2A_OUT, { recursive: true });
+            fs.writeFileSync(path.join(A2A_OUT, `${Date.now()}.txt`), `🔴 ход оборван ошибкой: ${why}`);
+          } catch { /* канал и так сломан, писать больше некуда */ }
+        } else {
+          void tg.send(chatId, `Не смог выполнить ход: ${why}`);
+        }
+      } else if (event.type === 'assistant/message' && chatId === A2A_CHAT) {
+        // ответ для координатора — в файл, Telegram тут ни при чём
+        const blocks = event.data?.message?.content ?? [];
+        const text = blocks.filter((b) => b?.type === 'text').map((b) => b.text).join('\n').trim();
+        if (text) {
+          try {
+            fs.mkdirSync(A2A_OUT, { recursive: true });
+            fs.writeFileSync(path.join(A2A_OUT, `${Date.now()}.txt`), text);
+            log(`[a2a] ответ координатору записан (${text.length} знаков)`);
+          } catch (e) { log(`[a2a] не смог записать ответ: ${e?.message ?? e}`); }
+        }
+      } else if (event.type === 'assistant/message') {
+        // Берём только видимый текст: рассуждения модели наружу не отдаём.
+        const blocks = event.data?.message?.content ?? [];
+        const text = blocks
+          .filter((b) => b?.type === 'text')
+          .map((b) => b.text)
+          .join('\n')
+          .trim();
+        if (text) {
+          log(`[event] отправляю в Telegram chatId=${chatId} (${text.length} знаков)`);
+          tg.send(chatId, text).catch((e) => log(`🔴 send к chatId=${chatId} не удался: ${e?.message ?? e}`));
+        }
+      }
+    } catch (e) {
+      log(`ошибка обработки события для чата ${chatId}: ${e?.message ?? e}`);
+    }
+  });
+
+  // ── ВХОД: длинный опрос Telegram → сообщения агенту
+  // Скачивает файл Telegram по file_id и возвращает временный путь.
+  async function downloadTelegramFile(fileId) {
+    const filePath = await tg.getFilePath(fileId);
+    const url = `https://api.telegram.org/file/bot${token}/${filePath}`;
+    const ext = path.extname(filePath) || '.oga';
+    const tmp = path.join(os.tmpdir(), `dsh-voice-${Date.now()}${ext}`);
+    // curl доступен на хосте; fetch тоже можно, но curl проще для бинарника.
+    execFileSync('curl', ['-s', '-o', tmp, url]);
+    return tmp;
+  }
+
+  // Транскрибирует голосовое сообщение через нашу локальную цепочку.
+  // Возвращает строку с текстом или null при ошибке.
+  async function transcribeVoice(fileId) {
+    let tmpAudio = null;
+    try {
+      tmpAudio = await downloadTelegramFile(fileId);
+      // внешняя команда расшифровки, задаётся настройкой transcribeCommand
+      if (!config.transcribeCommand) {
+        log('голосовые не расшифровываются: не задан config.transcribeCommand');
+        return null;
+      }
+      const transcript = execFileSync(config.transcribeCommand,
+        [tmpAudio, 'auto'], { timeout: 120_000 }).toString().trim();
+      return transcript || null;
+    } catch (e) {
+      log(`transcribeVoice: ошибка: ${e?.message ?? e}`);
+      return null;
+    } finally {
+      if (tmpAudio) try { fs.unlinkSync(tmpAudio); } catch { /* уже удалён */ }
+    }
+  }
+
+  async function handleUpdate(u) {
+    const msg = u.message;
+    // Принимаем текст И голосовые/аудио. Всё остальное молча пропускаем.
+    const isVoice = !!(msg?.voice || msg?.audio);
+    if (!msg?.text && !isVoice) return;
+    const chatId = msg.chat.id;
+    const userId = msg.from?.id;
+
+    let text;
+    if (isVoice) {
+      const fileId = (msg.voice ?? msg.audio).file_id;
+      void tg.typing(chatId);
+      const transcript = await transcribeVoice(fileId);
+      if (!transcript) {
+        await tg.send(chatId, '⚠️ Не смог расшифровать голосовое сообщение. Попробуйте ещё раз.');
+        return;
+      }
+      text = `[Voice transcript]: ${transcript}`;
+      log(`голосовое расшифровано: ${transcript.length} знаков`);
+    } else {
+      text = msg.text.trim();
+    }
+
+    if (!isAllowed(userId)) {
+      // 🔴 Чужой стучится к агенту, у которого полный доступ к серверу.
+      // Отказываем И поднимаем тревогу владельцу — молча отказывать нельзя:
+      // сам факт попытки это событие безопасности, а не бытовая мелочь.
+      const who = msg.from ?? {};
+      const alert = `🔴 Чужой написал агенту\n` +
+        `id: ${userId}\n` +
+        `имя: ${who.first_name ?? '?'} ${who.last_name ?? ''}`.trim() + `\n` +
+        `ник: ${who.username ? '@' + who.username : 'нет'}\n` +
+        `чат: ${chatId}\n` +
+        `текст: ${text.slice(0, 200)}`;
+      log(`ОТКАЗ чужому ${userId} (@${who.username ?? '—'}): ${text.slice(0, 60)}`);
+      for (const owner of allowed) {
+        try { await tg.send(owner, alert); } catch (e) { log(`тревога не ушла: ${e?.message ?? e}`); }
+      }
+      await tg.send(chatId, 'Извините, у меня нет разрешения с вами работать.');
+      return;
+    }
+
+    // Команды обрабатываем сами, до агента.
+    if (text === '/start' || text === '/help') {
+      await tg.send(chatId, 'агент на связи. Пишите задачу обычным сообщением.\n' +
+        '/new — начать разговор заново.');
+      return;
+    }
+    if (text === '/new') {
+      const old = chats.get(String(chatId));
+      if (old) {
+        try { await old.handle.dispose(); } catch { /* уже мог отвалиться */ }
+        chats.delete(String(chatId));
+        sessionToChat.delete(old.sessionId);
+      }
+      await tg.send(chatId, 'Начал заново.');
+      return;
+    }
+
+    const { handle } = await agentFor(chatId);
+    // 🔴 ТОЛЬКО send(), НЕ followup(). Проверено на установленной версии 0.1.0-rc.7:
+    // followup объявлен в описании типов, но В КОДЕ ЕГО НЕТ — вызов молча не делает
+    // ничего, и снаружи это выглядит как «бот принял сообщение и замолчал».
+    // Правильный вызов подсмотрен в самом продукте: this.send(input, "next-turn", true).
+    //   next-turn — обычный следующий ход;
+    //   true      — разбудить исполнителя, иначе сообщение будет ждать вечно.
+    const userMsg = platform.createUserMessage({
+      content: [{ type: 'text', text }],
+      source: { kind: 'user' },
+    });
+    try {
+      // 🔴 Ждём, пока агент домотает replay. send() во время replay молча
+      // игнорируется (wakeDriver не срабатывает) — снаружи это выглядит как
+      // «бот принял сообщение и замолчал». Диагноз 18.08.2026.
+      // Ожидание ОБЯЗАНО быть с пределом: whenIdle() не обязан разрешиться,
+      // а ожидание без границы превращает «не потеряли» в «висим вечно».
+      await Promise.race([
+        handle.agent.whenIdle(),
+        new Promise((r) => setTimeout(r, 15000)),
+      ]);
+      handle.agent.send(userMsg, 'next-turn', true);
+      nudgeUntilClaimed(handle.agent, '');
+      log(`сообщение передано агенту чата ${chatId} (${text.length} знаков)`);
+    } catch (e) {
+      log(`🔴 не удалось передать сообщение агенту: ${e?.message ?? e}`);
+      await tg.send(chatId, 'Не смог передать ваше сообщение агенту. Разбираюсь.');
+    }
+  }
+
+  // ── КАНАЛ АГЕНТ↔АГЕНТ (координатор ↔ агент), через файлы.
+  //
+  // Telegram тут не годится: у агента нет и не может быть учётной записи
+  // пользователя, а бот боту не пишет — так устроен мессенджер. Поэтому связь
+  // через каталог обмена, он же работает поверх ssh с любой машины фермы.
+  //
+  //   входящие мне:  <a2aDir>/in/*.txt   — кладёт координатор, я передаю агенту
+  //   исходящие ей:  <a2aDir>/out/*.txt  — пишет агент, забирает координатор
+  // Каталог обмена задаётся настройкой: у каждого агента он свой. Не задан —
+  // межагентского канала у этого агента просто нет, и опрос не ведётся вовсе
+  // (молчаливое создание чужих каталогов было бы хуже отсутствия связи).
+  const A2A_DIR = config.a2aDir || null;
+  const A2A_IN = A2A_DIR ? path.join(A2A_DIR, 'in') : null;
+  const A2A_OUT = A2A_DIR ? path.join(A2A_DIR, 'out') : null;
+  const A2A_CHAT = config.a2aSession || 'a2a';  // отдельная сессия, не смешивается с Telegram
+
+  async function pollA2A() {
+    if (!A2A_DIR) return;
+    let files = [];
+    try {
+      fs.mkdirSync(A2A_IN, { recursive: true });
+      fs.mkdirSync(A2A_OUT, { recursive: true });
+      files = fs.readdirSync(A2A_IN).filter((f) => f.endsWith('.txt')).sort();
+    } catch { return; }
+    for (const f of files) {
+      const full = path.join(A2A_IN, f);
+      let text = '';
+      try {
+        text = fs.readFileSync(full, 'utf-8').trim();
+      } catch (e) {
+        // 🔴 НЕ ГЛОТАТЬ. Раньше здесь стоял `catch { continue; }` — и файл,
+        // который нам не по правам (например 600 root:root), молча оставался
+        // лежать во входящих. Снаружи это «агент не отвечает», а на деле
+        // мы даже не смогли прочитать вопрос. Поймано 18.08.2026.
+        log(`[a2a] 🔴 не смогла прочитать ${f}: ${e?.message ?? e} (права: попробуй chown dsh:dsh + chmod 644)`);
+        continue;
+      }
+      if (!text) continue;
+      try {
+        const { handle } = await agentFor(A2A_CHAT);
+        handle.agent.send(platform.createUserMessage({
+          content: [{ type: 'text', text }],
+          source: { kind: 'user' },
+        }), 'next-turn', true);
+        nudgeUntilClaimed(handle.agent, '[a2a]');
+        // 🔴 УДАЛЯЕМ ТОЛЬКО ПОСЛЕ УСПЕШНОЙ ПЕРЕДАЧИ (19.08.2026). Раньше файл
+        // стирался сразу после чтения — и когда передача падала (фабрика
+        // агентов ещё не поднялась), вопрос исчезал молча: ни ответа, ни следа.
+        try { fs.unlinkSync(full); } catch { /* уже убрали — не беда */ }
+        log(`[a2a] принято (${text.length} знаков)`);
+      } catch (e) {
+        log(`[a2a] 🔴 не удалось передать агенту: ${e?.message ?? e} — файл ${f} ОСТАВЛЕН во входящих, попробую снова`);
+      }
+    }
+  }
+
+  async function loop(run) {
+    while (run.alive) {
+      try {
+        await pollA2A();
+        const updates = await tg.poll(25);
+        for (const u of updates) {
+          try { await handleUpdate(u); }
+          catch (e) { log(`ошибка обработки обновления: ${e?.message ?? e}`); }
+        }
+      } catch (e) {
+        // Сеть моргнула или Telegram ответил ошибкой — ждём и продолжаем.
+        log(`опрос не удался: ${e?.message ?? e}`);
+        await new Promise((r) => setTimeout(r, 3000));
+      }
+    }
+    run.finished = true;
+  }
+
+  // ctx.effect — регистрация с обязательным откатом: при выгрузке плагина
+  // опрос корректно останавливается, а не остаётся висеть.
+  //
+  // 🔴 ОДИН ОПРОС НА БОТА, СЧЁТЧИК МОНТАЖЕЙ — А НЕ ЭСТАФЕТА (19.08.2026, три
+  // неверные попытки подряд, поэтому пишу подробно).
+  //
+  // Платформа за один запуск процесса монтирует канал ДВАЖДЫ и второй монтаж
+  // тут же снимает. Что из этого выходило:
+  //   1) общий флаг `running`: откат гасил его, но второй цикл жил дальше →
+  //      два опроса одного бота → Telegram рвёт обоих ошибкой Conflict;
+  //   2) «своя жизнь у каждого запуска» + вежливая передача эстафеты: новый
+  //      монтаж просил прежний уступить, а сам был снят платформой → не
+  //      опрашивал НИКТО, при этом в журнале честно значилось «подключён как».
+  //      Снаружи неотличимо от работающего канала — бот просто молчит.
+  //
+  // Верная модель: опрос принадлежит БОТУ, а не монтажу. Монтажи лишь считают
+  // ссылки: первый поднимает опрос, последний снятый — гасит. Снятие ОДНОГО из
+  // двух монтажей ничего не останавливает.
+  ctx.effect(() => {
+    let state = ACTIVE_POLLERS.get(token);
+    if (!state) {
+      state = { refs: 0, run: null };
+      ACTIVE_POLLERS.set(token, state);
+    }
+    state.refs += 1;
+
+    if (!state.run) {
+      const run = { alive: true, finished: false };
+      state.run = run;
+      void (async () => {
+        tg.whoAmI()
+          .then((me) => log(`подключён как @${me.username} (${me.first_name})`))
+          .catch((e) => log(`не удалось представиться Telegram: ${e?.message ?? e}`));
+        log(`опрос запущен (монтажей: ${state.refs})`);
+        await loop(run);
+        log('опрос завершён');
+      })();
+    } else {
+      log(`опрос уже идёт — второй не поднимаю (монтажей: ${state.refs})`);
+    }
+
+    return () => {
+      state.refs -= 1;
+      if (state.refs > 0) {
+        log(`монтаж снят, опрос продолжается (осталось монтажей: ${state.refs})`);
+        return;
+      }
+      if (state.run) {
+        state.run.alive = false;
+        state.run = null;
+      }
+      log('снят последний монтаж — опрос остановлен');
+    };
+  }, 'dsh-telegram-channel.poll');
+}