@goodandready/dsh-messenger-gateway 0.3.1 → 0.3.8

package/README.md

@@ -7,9 +7,20 @@ Talk to your Harness agent from Telegram: text, voice, photos, documents, inline
 ## Features
 
 - Long-poll or webhook Telegram bot
+- Multi-transport support: Telegram, Discord (Webhooks & Bot API), and Slack (Webhooks & Bot API)
 - Allowlist + pairing codes
 - Per-user or per-chat sessions (`sessionScope`)
 - Forum topics as separate sessions
+- Quick actions reply keyboard (`/keyboard on|off`)
+- Multi-select interactive ask forms with checkboxes and pagination (`messenger_ask`)
+- Artifact & Mermaid diagram rendering (SVG cards) and monospace table formatting
+- Agent roles & personas (`/role coder`, `/role architect`, `@role` tags in group chats)
+- Agent tools & skills inspection (`/skills`, `/tools`)
+- Session management: dialogue history export to Markdown (`/export`), turn rewind (`/rewind`), session branching (`/fork`)
+- Workspace file manager (`/files [dir]`) and file download (`/get <path>`) with directory traversal protection
+- Admin alert channel for pairing requests, model errors and monitoring (`/setalert`, `/alert`)
+- Persistent scheduled reminders (`/remind <time> <text>`, `/remind list`, `/remind cancel`)
+- Inbound webhook event dispatcher (`POST /dsh-messenger-gateway/events`) for CI/CD and external alerts
 - Steer: follow-up messages while the agent is busy (instead of aborting)
 - `/stop`, `/new`, `/model`, `/status`, `/voice`, `/sethome`, `/home`
 - Agent tool `messenger_ask` (inline keyboard answers return to the agent)
@@ -18,7 +29,7 @@ Talk to your Harness agent from Telegram: text, voice, photos, documents, inline
 - Inbound voice → STT (`dsh-voice`), photos → vision (`dsh-vision-bridge`)
 - Optional TTS replies (`dsh-tts`); mp3 is converted to OGG/Opus via `ffmpeg` for Telegram voice notes
 
-Discord is listed in settings as a placeholder only — the Discord adapter is not implemented yet.
+Discord and Slack adapters are available as outbound transports (Webhooks or Bot REST APIs).
 
 ## Install
 
@@ -55,10 +66,27 @@ Spoken replies use Telegram `sendVoice`. If TTS returns MP3 (or other non-Opus a
 | `/new` | New agent session |
 | `/stop` | Abort the current turn |
 | `/model` `/status` | Model / gateway status |
+| `/role [name]` | Switch agent persona (`coder`, `architect`, `reviewer`, `writer`, `translator`, `concise`) |
+| `/skills` `/tools` | List active agent tools and capabilities |
+| `/fork` | Fork current session into a new independent session |
+| `/export` | Export session dialogue history to Markdown |
+| `/rewind [N]` | Rewind last N conversation turns |
+| `/files [dir]` | Workspace file manager |
+| `/get <path>` | Download file from workspace |
+| `/remind <time> <text>` | Set a reminder (e.g. `/remind 15m Call client`) |
+| `/setalert` `/alert` | Configure admin alert channel and send test alert |
+| `/keyboard on\|off` | Toggle quick actions reply keyboard |
 | `/voice on\|off` | Per-user spoken replies |
+| `/tts on\|off\|status` | Per-chat spoken replies |
 | `/sethome [name]` | Bind current chat/topic as a named home |
 | `/home` | List homes |
 
+## Multi-Transport Support (Discord & Slack)
+
+In addition to Telegram, outbound messages can be dispatched to Discord and Slack via Webhooks or Bot APIs:
+- **Discord:** set `discord.enabled: true`, provide either `webhookUrl` or `botToken`. Target channels via `chatId: "<channel_id>"`.
+- **Slack:** set `slack.enabled: true`, provide either `webhookUrl` or `botToken`. Target channels via `chatId: "<channel_id>"` or threads via `threadId: "<thread_ts>"`.
+
 ## Agent tools & HTTP
 
 - Tool: `messenger_ask` — ask the user with inline buttons; choice is fed back into the turn

package/README.ru.md

@@ -0,0 +1,125 @@
+# 📦 @goodandready/dsh-messenger-gateway
+
+<div align="center">
+
+<h3>Шлюз Telegram с интерактивными кнопками управления, темами форумов и голосовыми ответами для DeepSeek Harness</h3>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-messenger-gateway"><img src="https://img.shields.io/npm/v/@goodandready/dsh-messenger-gateway.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-10b981.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>
+  <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
+</p>
+
+<p align="center">
+  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/Все_проекты_автора-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="Все проекты автора"></a>
+</p>
+
+<p align="center">
+  <a href="README.md"><b>🇬🇧 English</b></a> •
+  <a href="README.ru.md"><b>🇷🇺 Русский</b></a> •
+  <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
+</p>
+
+</div>
+
+---
+
+## ⚡ Обзор
+
+**`dsh-messenger-gateway`** предоставляет полнофункциональный Telegram-мост корпоративного уровня для агентов **DeepSeek Harness**.
+
+В отличие от простых текстовых релеев, плагин переносит всю интерактивность агента прямо в Telegram: **интерактивные кнопки (Inline Keyboard)** для уточняющих вопросов (`ask_question`), изоляцию **тем форумов (Forum Topics)**, персональные **рабочие папки пользователей**, авторизацию по **6-значным кодам сопряжения** и голосовые **аудио-ответы (TTS)**.
+
+```mermaid
+graph LR
+    subgraph TelegramClient [Пользователь Telegram / Группа / Тема]
+        User[👤 Пользователь / Тема форума] --> TG[Шлюз Telegram Bot API Long-Poll / Webhook]
+    end
+
+    subgraph GatewayCore [Диспетчер шлюза]
+        TG --> Auth{Проверка сопряжения и доступа}
+        Auth -->|Авторизован| Router{Маршрутизатор тем и папок}
+        Router --> Home[Рабочая папка: /homes/user_id]
+        Home --> Thread[Изолированный контекст сессии DSH]
+    end
+
+    subgraph AgentLoop [Цикл работы агента DSH]
+        Thread --> Agent[Выполнение действий агента]
+        Agent -->|ask_question выбор опций| Ask[Интерактивные кнопки Inline Keyboard]
+        Agent -->|Озвучивание ответов| TTS[Синтез голосового сообщения TTS]
+    end
+
+    subgraph Feedback [Доставка ответа]
+        Ask --> TG
+        TTS --> TG
+    end
+
+    style TelegramClient fill:#1e1e2e,stroke:#89b4fa,stroke-width:2px,color:#cdd6f4
+    style GatewayCore fill:#181825,stroke:#cba6f7,stroke-width:2px,color:#cdd6f4
+    style AgentLoop fill:#11111b,stroke:#a6e3a1,stroke-width:2px,color:#cdd6f4
+    style Feedback fill:#181825,stroke:#f38ba8,stroke-width:2px,color:#cdd6f4
+```
+
+---
+
+## ✨ Ключевые возможности
+
+### 1. 🎮 Интерактивные кнопки управления агентом (`ask.js`)
+Когда агент вызывает инструмент `ask_question` со списком вариантов ответа, плагин отправляет нативные **Inline-кнопки** в Telegram. Ход агента безопасно приостанавливается, а при нажатии на кнопку выполнение мгновенно возобновляется.
+
+### 2. 🧵 Темы форумов Telegram (Forum Topics) (`topics.js`, `groups.js`)
+Полная поддержка тем в супергруппах Telegram:
+* Каждая тема (Topic) автоматически привязывается к отдельной сессии DSH;
+* Контексты разных тем не смешиваются между собой;
+* Режим ответов по тегу (`@bot_name`) или постоянное прослушивание.
+
+### 3. 🔊 Голосовые ответы ассистента (TTS) (`tts.js`, `voice-prefs.js`)
+Агент может отвечать голосовыми сообщениями (`sendVoice`):
+* Интеграция с [`dsh-tts`](https://github.com/GooDAnDReaDY/dsh-tts) или отдельными TTS-движками;
+* Индивидуальное переключение пользователем через команды `/voice on` и `/voice off`.
+
+### 4. 📁 Изоляция рабочих папок пользователей (`homes.js`)
+Каждому пользователю Telegram выделяется отдельная изолированная директория на сервере (`workspaces/users/{userId}`):
+* Файловые операции и запуск команд изолированы;
+* Исключен риск перезаписи чужих файлов или доступа к системным ресурсам.
+
+### 5. 🔐 Безопасность и 6-значные коды сопряжения (`pairing.js`)
+* Защита от несанкционированного доступа: новые пользователи должны ввести одноразовый 6-значный код, сгенерированный в Web UI;
+* Белые списки разрешенных ID (`allowedUsers`, `allowedChats`).
+
+### 6. 🤖 Команды бота (`commands.js`)
+* `/start` — приветствие и запуск сопряжения;
+* `/clear` — сброс контекста текущего диалога без удаления рабочих файлов;
+* `/voice [on|off]` — включение/отключение голосовых ответов;
+* `/model` — просмотр и переключение активной модели агента;
+* `/help` — список возможностей.
+
+---
+
+## 📦 Быстрая установка
+
+```bash
+dsh plugin --profile web add @goodandready/dsh-messenger-gateway
+```
+
+---
+
+## ⚙️ Пример конфигурации (`settings.yaml`)
+
+```yaml
+dsh-messenger-gateway:
+  tokenEnv: TELEGRAM_BOT_TOKEN
+  requirePairing: true
+  enableVoiceReplies: true
+  enableForumTopics: true
+  homeBaseDir: data/workspaces/users
+  allowedUsers: []
+  allowedChats: []
+```
+
+---
+
+## 📄 Лицензия
+
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

package/README.zh.md

@@ -0,0 +1,76 @@
+# 📦 @goodandready/dsh-messenger-gateway
+
+<div align="center">
+
+<h3>DeepSeek Harness Telegram 专属网关（支持交互按钮调度、论坛话题隔离与语音条回复）</h3>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-messenger-gateway"><img src="https://img.shields.io/npm/v/@goodandready/dsh-messenger-gateway.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-10b981.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>
+  <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
+</p>
+
+<p align="center">
+  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/作者全部项目-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="作者全部项目"></a>
+</p>
+
+<p align="center">
+  <a href="README.md"><b>🇬🇧 English</b></a> •
+  <a href="README.ru.md"><b>🇷🇺 Русский</b></a> •
+  <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
+</p>
+
+</div>
+
+---
+
+## ⚡ 插件概览
+
+**`dsh-messenger-gateway`** 为 **DeepSeek Harness** 智能体提供企业级 Telegram 接入桥梁。
+
+除常规对话转发外，本插件全面打通了智能体深度交互能力：**问答交互式内联按钮 (Inline Keyboard)**、**Telegram 论坛话题 (Forum Topics) 独立会话隔离**、**单用户工作区目录安全隔离**、**6 位配对码鉴权防护**以及**语音条朗读回复 (TTS)**。
+
+```mermaid
+graph LR
+    subgraph TelegramClient [Telegram 客户端 / 群组 / 话题]
+        User[👤 用户 / 论坛话题] --> TG[Telegram Bot API 轮询 / Webhook]
+    end
+
+    subgraph GatewayCore [网关调度核心]
+        TG --> Auth{配对码与权限校验}
+        Auth -->|已配对用户| Router{话题与目录路由器}
+        Router --> Home[独立工作目录: /homes/user_id]
+        Home --> Thread[DSH 隔离会话上下文]
+    end
+
+    subgraph AgentLoop [DSH 智能体执行流]
+        Thread --> Agent[智能体逻辑流]
+        Agent -->|ask_question 工具调用| Ask[Telegram 原生内联交互按钮]
+        Agent -->|语音回复合成| TTS[TTS 语音条消息下发]
+    end
+
+    subgraph Feedback [交互下发]
+        Ask --> TG
+        TTS --> TG
+    end
+
+    style TelegramClient fill:#1e1e2e,stroke:#89b4fa,stroke-width:2px,color:#cdd6f4
+    style GatewayCore fill:#181825,stroke:#cba6f7,stroke-width:2px,color:#cdd6f4
+    style AgentLoop fill:#11111b,stroke:#a6e3a1,stroke-width:2px,color:#cdd6f4
+    style Feedback fill:#181825,stroke:#f38ba8,stroke-width:2px,color:#cdd6f4
+```
+
+---
+
+## 📦 安装指南
+
+```bash
+dsh plugin --profile web add @goodandready/dsh-messenger-gateway
+```
+
+---
+
+## 📄 开源协议
+
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

package/lib/adapters/discord.js

@@ -1,6 +1,131 @@
-// Discord adapter — planned for a future release.
+import { readFile } from 'node:fs/promises'
+import { basename } from 'node:path'
+
+const DISCORD_API = 'https://discord.com/api/v10'
+const DISCORD_MAX_LENGTH = 2000
+
+export function splitDiscordText(text, limit = DISCORD_MAX_LENGTH) {
+  if (!text) return []
+  if (text.length <= limit) return [text]
+  const chunks = []
+  let rem = text
+  while (rem.length > limit) {
+    let cut = rem.lastIndexOf('\n', limit)
+    if (cut <= 0) cut = rem.lastIndexOf(' ', limit)
+    if (cut <= 0) cut = limit
+    chunks.push(rem.slice(0, cut))
+    rem = rem.slice(cut).trimStart()
+  }
+  if (rem.length > 0) chunks.push(rem)
+  return chunks
+}
+
 export class DiscordAdapter {
-  constructor() { this.name = 'discord' }
-  async start() { throw new Error('Discord adapter is not implemented yet') }
-  stop() {}
+  constructor(opts = {}) {
+    this.name = 'discord'
+    this.botToken = String(opts.botToken || '').trim()
+    this.webhookUrl = String(opts.webhookUrl || '').trim()
+    this.logger = opts.logger
+    this.stopped = false
+  }
+
+  async start() {
+    this.stopped = false
+    if (!this.botToken && !this.webhookUrl) {
+      this.logger?.warn?.('dsh-messenger-gateway: discord adapter enabled but neither botToken nor webhookUrl provided')
+    }
+  }
+
+  stop() {
+    this.stopped = true
+  }
+
+  async sendTo(channelId, payload, opts = {}) {
+    if (this.stopped) throw new Error('discord adapter stopped')
+    const body = typeof payload === 'string' ? { text: payload } : (payload || {})
+    const text = String(body.text || '')
+    const files = Array.isArray(body.files) ? body.files : []
+
+    const chunks = splitDiscordText(text)
+    if (!chunks.length && !files.length) return { ok: true }
+
+    // Case 1: Webhook sending
+    const isWebhookTarget = !channelId || channelId === 'default' || channelId === 'webhook'
+    if (this.webhookUrl && isWebhookTarget) {
+      for (const chunk of (chunks.length ? chunks : [''])) {
+        const res = await fetch(this.webhookUrl, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ content: chunk }),
+        })
+        if (!res.ok) {
+          const errText = await res.text().catch(() => '')
+          throw new Error(`discord webhook error ${res.status}: ${errText}`)
+        }
+      }
+      return { ok: true }
+    }
+
+    // Case 2: Bot REST API
+    if (!this.botToken) {
+      throw new Error('discord botToken required to send to specific channels')
+    }
+
+    const targetChannel = String(channelId || '').trim()
+    if (!targetChannel) throw new Error('discord channelId required')
+
+    // Handle files if any on the first chunk
+    if (files.length > 0 && typeof FormData !== 'undefined') {
+      const form = new FormData()
+      form.append('payload_json', JSON.stringify({
+        content: chunks[0] || '',
+      }))
+      for (let i = 0; i < files.length; i++) {
+        const file = files[i]
+        const bytes = file.bytes || (file.path ? await readFile(file.path) : null)
+        if (bytes) {
+          const name = file.name || (file.path ? basename(file.path) : `file-${i}`)
+          const mime = file.mime || 'application/octet-stream'
+          form.append(`files[${i}]`, new Blob([bytes], { type: mime }), name)
+        }
+      }
+      const res = await fetch(`${DISCORD_API}/channels/${targetChannel}/messages`, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bot ${this.botToken}`,
+        },
+        body: form,
+      })
+      if (!res.ok) {
+        const errText = await res.text().catch(() => '')
+        throw new Error(`discord send error ${res.status}: ${errText}`)
+      }
+      // Send remaining text chunks if any
+      for (let i = 1; i < chunks.length; i++) {
+        await this._sendRestMessage(targetChannel, chunks[i])
+      }
+      return { ok: true }
+    }
+
+    // Pure text chunks
+    for (const chunk of chunks) {
+      await this._sendRestMessage(targetChannel, chunk)
+    }
+    return { ok: true }
+  }
+
+  async _sendRestMessage(channelId, content) {
+    const res = await fetch(`${DISCORD_API}/channels/${channelId}/messages`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bot ${this.botToken}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ content }),
+    })
+    if (!res.ok) {
+      const errText = await res.text().catch(() => '')
+      throw new Error(`discord send error ${res.status}: ${errText}`)
+    }
+  }
 }

package/lib/adapters/index.js

@@ -1,4 +1,6 @@
 import { TelegramAdapter } from './telegram.js'
+import { DiscordAdapter } from './discord.js'
+import { SlackAdapter } from './slack.js'
 
 export default function createAdapters(deps) {
   const { config, onMessage, onCallback, onUnauthorized, isUserAllowed, logger } = deps
@@ -21,6 +23,8 @@ export default function createAdapters(deps) {
       transport: tg.transport,
       webhookUrl: tg.webhookUrl,
       webhookSecret: tg.webhookSecret,
+      quickActions: tg.quickActions !== false,
+      artifactPreviews: tg.artifactPreviews !== false,
       media: config.media,
       onMessage,
       onCallback,
@@ -31,7 +35,19 @@ export default function createAdapters(deps) {
   }
   const dc = config.discord || {}
   if (config.enabled !== false && dc.enabled) {
-    logger?.warn?.('dsh-messenger-gateway: discord adapter is not implemented yet')
+    list.push(new DiscordAdapter({
+      botToken: dc.botToken,
+      webhookUrl: dc.webhookUrl,
+      logger,
+    }))
+  }
+  const sl = config.slack || {}
+  if (config.enabled !== false && sl.enabled) {
+    list.push(new SlackAdapter({
+      botToken: sl.botToken,
+      webhookUrl: sl.webhookUrl,
+      logger,
+    }))
   }
   return list
 }

package/lib/adapters/slack.js

@@ -0,0 +1,91 @@
+const SLACK_API = 'https://slack.com/api'
+const SLACK_MAX_LENGTH = 4000
+
+export function splitSlackText(text, limit = SLACK_MAX_LENGTH) {
+  if (!text) return []
+  if (text.length <= limit) return [text]
+  const chunks = []
+  let rem = text
+  while (rem.length > limit) {
+    let cut = rem.lastIndexOf('\n', limit)
+    if (cut <= 0) cut = rem.lastIndexOf(' ', limit)
+    if (cut <= 0) cut = limit
+    chunks.push(rem.slice(0, cut))
+    rem = rem.slice(cut).trimStart()
+  }
+  if (rem.length > 0) chunks.push(rem)
+  return chunks
+}
+
+export class SlackAdapter {
+  constructor(opts = {}) {
+    this.name = 'slack'
+    this.botToken = String(opts.botToken || '').trim()
+    this.webhookUrl = String(opts.webhookUrl || '').trim()
+    this.logger = opts.logger
+    this.stopped = false
+  }
+
+  async start() {
+    this.stopped = false
+    if (!this.botToken && !this.webhookUrl) {
+      this.logger?.warn?.('dsh-messenger-gateway: slack adapter enabled but neither botToken nor webhookUrl provided')
+    }
+  }
+
+  stop() {
+    this.stopped = true
+  }
+
+  async sendTo(channelId, payload, opts = {}) {
+    if (this.stopped) throw new Error('slack adapter stopped')
+    const body = typeof payload === 'string' ? { text: payload } : (payload || {})
+    const text = String(body.text || '')
+    const chunks = splitSlackText(text)
+    if (!chunks.length) return { ok: true }
+
+    const isWebhookTarget = !channelId || channelId === 'default' || channelId === 'webhook'
+    if (this.webhookUrl && isWebhookTarget) {
+      for (const chunk of chunks) {
+        const res = await fetch(this.webhookUrl, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ text: chunk }),
+        })
+        if (!res.ok) {
+          const errText = await res.text().catch(() => '')
+          throw new Error(`slack webhook error ${res.status}: ${errText}`)
+        }
+      }
+      return { ok: true }
+    }
+
+    if (!this.botToken) {
+      throw new Error('slack botToken required to send to specific channels')
+    }
+
+    const targetChannel = String(channelId || '').trim()
+    if (!targetChannel) throw new Error('slack channelId required')
+
+    const threadTs = opts.threadId || undefined
+    for (const chunk of chunks) {
+      const res = await fetch(`${SLACK_API}/chat.postMessage`, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${this.botToken}`,
+          'Content-Type': 'application/json; charset=utf-8',
+        },
+        body: JSON.stringify({
+          channel: targetChannel,
+          text: chunk,
+          thread_ts: threadTs,
+        }),
+      })
+      const json = await res.json().catch(() => ({}))
+      if (!res.ok || json.ok === false) {
+        throw new Error(`slack chat.postMessage error: ${json.error || res.status}`)
+      }
+    }
+    return { ok: true }
+  }
+}

package/lib/adapters/telegram.js

@@ -16,6 +16,19 @@ import { isResendSafeNetworkError, isPollingConflict } from '../telegram-errors.
 const API = 'https://api.telegram.org'
 const TELEGRAM_MAX = 4096
 
+export function buildQuickActionsKeyboard() {
+  return {
+    keyboard: [
+      [{ text: '🔄 /new' }, { text: '🛑 /stop' }],
+      [{ text: '🎙️ /voice' }, { text: '📊 /status' }],
+    ],
+    resize_keyboard: true,
+    is_persistent: true,
+  }
+}
+
+export const REMOVE_REPLY_KEYBOARD = { remove_keyboard: true }
+
 export class TelegramAdapter {
   constructor(opts) {
     this.name = 'telegram'
@@ -34,6 +47,8 @@ export class TelegramAdapter {
     this.groupsEnabled = opts.groupsEnabled !== false
     this.groupRequireMention = opts.groupRequireMention !== false
     this.reactionsEnabled = opts.reactionsEnabled !== false
+    this.quickActions = opts.quickActions !== false
+    this.artifactPreviews = opts.artifactPreviews !== false
     this.transport = opts.transport === 'webhook' ? 'webhook' : 'poll'
     this.statusIndicator = opts.statusIndicator === true
     this.statusOnline = String(opts.statusOnline || 'Online')
@@ -225,6 +240,13 @@ export class TelegramAdapter {
           return this.call('editMessageText', { chat_id: chatId, message_id: messageId, text, reply_markup: replyMarkup })
         }
       },
+      editReplyMarkup: async (replyMarkup) => {
+        return this.call('editMessageReplyMarkup', {
+          chat_id: chatId,
+          message_id: messageId,
+          reply_markup: replyMarkup,
+        })
+      },
     }
   }
 
@@ -487,12 +509,15 @@ export class TelegramAdapter {
     const { text: formatted, parseMode } = this.formatOutgoingText(text, payload)
     const chunks = splitText(formatted, TELEGRAM_MAX)
     const plainChunks = splitText(text, TELEGRAM_MAX)
+    const effectiveMarkup = (replyMarkup === undefined && this.quickActions && !threadId)
+      ? buildQuickActionsKeyboard()
+      : replyMarkup
     for (let i = 0; i < chunks.length; i++) {
       const params = {
         chat_id: chatId,
         text: chunks[i],
         reply_to_message_id: replyTo,
-        reply_markup: i === 0 ? replyMarkup : undefined,
+        reply_markup: i === 0 ? effectiveMarkup : undefined,
         ...telegramThreadParams(threadId),
       }
       if (parseMode) params.parse_mode = parseMode
@@ -505,7 +530,7 @@ export class TelegramAdapter {
           chat_id: chatId,
           text: plainChunks[i] ?? chunks[i],
           reply_to_message_id: replyTo,
-          reply_markup: i === 0 ? replyMarkup : undefined,
+          reply_markup: i === 0 ? effectiveMarkup : undefined,
           ...telegramThreadParams(threadId),
         })
       }

package/lib/alerts.js

@@ -0,0 +1,64 @@
+import { escapeHtml } from './telegram-format.js'
+import { normalizeThreadId } from './topics.js'
+
+export function formatAlertMessage(type, payload = {}) {
+  const timestamp = new Date().toLocaleTimeString()
+
+  if (type === 'pairing') {
+    const { userId, username, code } = payload
+    const userStr = username ? `@${username} (id: <code>${userId}</code>)` : `id: <code>${userId}</code>`
+    return [
+      `🔐 <b>[Запрос сопряжения]</b> <i>(${timestamp})</i>`,
+      '',
+      `Пользователь: ${userStr}`,
+      `Код доступа: <code>${code}</code>`,
+      '',
+      `Для одобрения отправьте боту:`,
+      `<code>/pair ${code}</code>`,
+    ].join('\n')
+  }
+
+  if (type === 'error') {
+    const { message, code, sessionId, chatId, threadId } = payload
+    const location = chatId ? `Чат: <code>${chatId}</code>${threadId ? ` / топик <code>${threadId}</code>` : ''}` : ''
+    const sess = sessionId ? `Сессия: <code>${sessionId}</code>` : ''
+    const meta = [location, sess].filter(Boolean).join('\n')
+
+    return [
+      `🚨 <b>[Ошибка шлюза]</b> <i>(${timestamp})</i>`,
+      meta ? `\n${meta}` : '',
+      `Ошибка: <b>${escapeHtml(String(code || 'error'))}</b>`,
+      `<code>${escapeHtml(String(message || 'unknown error'))}</code>`,
+    ].filter(Boolean).join('\n')
+  }
+
+  if (type === 'status') {
+    const { title, details } = payload
+    return [
+      `⚡ <b>[Шлюз: ${escapeHtml(title || 'Статус')}]</b> <i>(${timestamp})</i>`,
+      details ? `\n${escapeHtml(details)}` : '',
+    ].filter(Boolean).join('\n')
+  }
+
+  return `🔔 <b>[Алерт: ${type}]</b> <i>(${timestamp})</i>\n${escapeHtml(JSON.stringify(payload))}`
+}
+
+export function resolveAlertTarget(gateway) {
+  const alertsCfg = gateway?.config?.telegram?.alerts
+  if (!alertsCfg || alertsCfg.enabled === false) return null
+
+  // If a named home is specified
+  if (alertsCfg.home) {
+    const home = gateway.resolveHomeTarget('telegram', alertsCfg.home)
+    if (home) return home
+  }
+
+  const chatId = alertsCfg.chatId
+  if (!chatId) return null
+
+  return {
+    platform: 'telegram',
+    chatId,
+    threadId: normalizeThreadId(alertsCfg.threadId),
+  }
+}