@goodandready/dsh-messenger-gateway 0.1.0 → 0.2.0

package/README.md

@@ -1,26 +1,24 @@
 # @goodandready/dsh-messenger-gateway
 
-Messenger transport for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).
+Telegram messenger bridge for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).
 
-## 0.1.0 scope (Telegram)
+Talk to your Harness agent from Telegram: text, voice, photos, documents, inline buttons, named homes, and optional spoken replies.
 
-- Long-poll Telegram bot
-- Text, voice (`dsh-voice`), photos (`attachments` + `dsh-vision-bridge`), documents
-- Outbound images from tool results
-- `messenger` service: HTTP `/messenger/send`, `/ask`, `/progress` and `ctx.provide('messenger')`
-- Forum topics = separate agent sessions (`message_thread_id`)
-- Optional spoken replies (`dsh-tts`)
-- Commands: `/start` `/help` `/new` `/whoami` `/stop`
+## Features
 
-Discord adapter is a stub; full Discord support comes after 0.1.0.
+- Long-poll or webhook Telegram bot
+- Allowlist + pairing codes
+- Per-user or per-chat sessions (`sessionScope`)
+- Forum topics as separate sessions
+- 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)
+- Named homes for outbound notify / `messenger.send`
+- Optional notify bridge: web session events → Telegram home (excludes messenger sessions)
+- 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
 
-## Profile dependencies
-
-Install these plugins in the same Harness profile (they are not npm dependencies):
-
-- `dsh-voice` — inbound voice transcription
-- `dsh-tts` — optional spoken replies
-- `dsh-vision-bridge` — inbound photo understanding
+Discord is listed in settings as a placeholder only — the Discord adapter is not implemented yet.
 
 ## Install
 
@@ -28,8 +26,59 @@ Install these plugins in the same Harness profile (they are not npm dependencies
 dsh plugin --profile web add @goodandready/dsh-messenger-gateway
 ```
 
-Settings → **Messenger gateway** → enable Telegram, paste bot token, set allowed user IDs.
+Then open **Settings → Plugins → Messenger gateway**:
+
+1. Enable Telegram
+2. Paste the BotFather token (write-only; leave blank to keep the current token)
+3. Set allowed Telegram user IDs (or use pairing)
+
+### Optional companion plugins (same profile)
+
+| Plugin | Role |
+|--------|------|
+| `@goodandready/dsh-voice` | Transcribe inbound voice messages |
+| `@goodandready/dsh-tts` | Speak agent replies |
+| `@goodandready/dsh-vision-bridge` | Describe inbound photos |
+
+They are **not** npm dependencies of this package — install them separately if you want those features.
+
+### Voice notes
+
+Spoken replies use Telegram `sendVoice`. If TTS returns MP3 (or other non-Opus audio), the gateway runs `ffmpeg` (`libopus`) to produce OGG. If `ffmpeg` is missing or conversion fails, the audio is sent as a regular audio file instead of a voice note.
+
+## Commands (Telegram)
+
+| Command | Description |
+|---------|-------------|
+| `/start` `/help` | Help |
+| `/whoami` | Your Telegram user id |
+| `/new` | New agent session |
+| `/stop` | Abort the current turn |
+| `/model` `/status` | Model / gateway status |
+| `/voice on\|off` | Per-user spoken replies |
+| `/sethome [name]` | Bind current chat/topic as a named home |
+| `/home` | List homes |
+
+## Agent tools & HTTP
+
+- Tool: `messenger_ask` — ask the user with inline buttons; choice is fed back into the turn
+- HTTP (when enabled): `/messenger/send`, `/messenger/ask`, `/messenger/progress`
+- Cordis service: `ctx.messenger` for other plugins
+
+## Configuration notes
+
+- `sessionScope`: `user` (default) or `chat` — how group chats isolate sessions
+- `voiceMode`: `mirror` / `always` / `off` — when to speak replies (also `/voice`)
+- `tts.enabled` / `tts.maxChars` — TTS gate and length cap
+- `notifyBridge` — forward non-messenger web session events to a home
+- Bot token is a DSH secret field — never commit it
+
+## Requirements
+
+- DeepSeek Harness web (or compatible) profile
+- Node.js matching your Harness install
+- For voice notes from non-Opus TTS: `ffmpeg` on the host `PATH`
 
-See `docs/deployment/0.1.0-install.md` for staging smoke and prod swap vs legacy hub-media.
+## License
 
 MIT

package/lib/adapters/index.js

@@ -1,7 +1,7 @@
 import { TelegramAdapter } from './telegram.js'
 
 export default function createAdapters(deps) {
-  const { config, onMessage, onCallback, logger } = deps
+  const { config, onMessage, onCallback, onUnauthorized, isUserAllowed, logger } = deps
   const list = []
   const tg = config.telegram || {}
   if (config.enabled !== false && tg.enabled && String(tg.botToken || '').trim()) {
@@ -10,9 +10,19 @@ export default function createAdapters(deps) {
       allowedUserIds: tg.allowedUserIds,
       timeoutSeconds: tg.pollTimeoutSeconds,
       pollIntervalMs: tg.pollIntervalMs,
+      commands: tg.commands,
+      textFormat: tg.textFormat,
+      groupsEnabled: tg.groupsEnabled,
+      groupRequireMention: tg.groupRequireMention,
+      reactionsEnabled: tg.reactionsEnabled,
+      transport: tg.transport,
+      webhookUrl: tg.webhookUrl,
+      webhookSecret: tg.webhookSecret,
       media: config.media,
       onMessage,
       onCallback,
+      onUnauthorized,
+      isUserAllowed,
       logger,
     }))
   }
@@ -21,4 +31,4 @@ export default function createAdapters(deps) {
     logger?.warn?.('dsh-messenger-gateway: discord adapter is not implemented yet')
   }
   return list
-}
+}

package/lib/adapters/telegram.js

@@ -1,10 +1,16 @@
 import { readFile } from 'node:fs/promises'
 import {
   IMAGE_EXT_TO_MIME, VIDEO_EXT_TO_MIME, basename, cacheName, classifyDocument,
-  extOf, mediaKindOf, saveToCache, safeName,
+  extOf, saveToCache, safeName,
 } from '../media.js'
+import { TEXT_INJECT_EXTS } from '../documents.js'
 import { splitText } from '../text.js'
+import { prepareTelegramText } from '../telegram-format.js'
+import { normalizeTelegramCommands } from '../commands.js'
 import { normalizeThreadId, telegramThreadParams } from '../topics.js'
+import {
+  shouldProcessTelegramMessage, stripBotCommandSuffix,
+} from '../groups.js'
 
 const API = 'https://api.telegram.org'
 const TELEGRAM_MAX = 4096
@@ -19,10 +25,26 @@ export class TelegramAdapter {
     this.media = opts.media || {}
     this.onMessage = opts.onMessage
     this.onCallback = opts.onCallback
+    this.onUnauthorized = opts.onUnauthorized
+    this.isUserAllowed = opts.isUserAllowed
     this.logger = opts.logger
+    this.commands = normalizeTelegramCommands(opts.commands)
+    this.textFormat = opts.textFormat === 'plain' ? 'plain' : 'html'
+    this.groupsEnabled = opts.groupsEnabled !== false
+    this.groupRequireMention = opts.groupRequireMention !== false
+    this.reactionsEnabled = opts.reactionsEnabled !== false
+    this.transport = opts.transport === 'webhook' ? 'webhook' : 'poll'
+    this.webhookUrl = String(opts.webhookUrl || '').trim()
+    this.webhookSecret = String(opts.webhookSecret || '').trim()
     this.offset = 0
     this.stopped = false
     this.pollTimer = undefined
+    this.botId = 0
+    this.botUsername = ''
+  }
+
+  setAllowedUserIds(ids) {
+    this.allowedUserIds = (ids || []).map(Number).filter((n) => Number.isFinite(n))
   }
 
   async call(method, params = {}) {
@@ -49,9 +71,44 @@ export class TelegramAdapter {
     return new Uint8Array(await res.arrayBuffer())
   }
 
+  async registerCommands() {
+    if (!this.commands.length) return
+    await this.call('setMyCommands', { commands: this.commands })
+  }
+
   async start() {
     if (!this.token) throw new Error('telegram bot token is empty')
     this.stopped = false
+    try {
+      const me = await this.call('getMe')
+      this.botId = Number(me.id) || 0
+      this.botUsername = String(me.username || '')
+      this.logger?.info?.(`dsh-messenger-gateway: telegram bot @${this.botUsername} (${this.botId})`)
+    } catch (err) {
+      this.logger?.warn?.(`dsh-messenger-gateway: telegram getMe: ${err.message}`)
+    }
+    try {
+      await this.registerCommands()
+      this.logger?.info?.(`dsh-messenger-gateway: telegram commands registered (${this.commands.length})`)
+    } catch (err) {
+      this.logger?.warn?.(`dsh-messenger-gateway: telegram setMyCommands: ${err.message}`)
+    }
+    if (this.transport === 'webhook') {
+      if (!this.webhookUrl) throw new Error('telegram webhookUrl is required for webhook transport')
+      try {
+        await this.call('deleteWebhook', { drop_pending_updates: false })
+      } catch {}
+      const params = {
+        url: this.webhookUrl,
+        allowed_updates: ['message', 'callback_query'],
+        drop_pending_updates: false,
+      }
+      if (this.webhookSecret) params.secret_token = this.webhookSecret
+      await this.call('setWebhook', params)
+      this.logger?.info?.(`dsh-messenger-gateway: telegram webhook set → ${this.webhookUrl}`)
+      return
+    }
+    try { await this.call('deleteWebhook', { drop_pending_updates: false }) } catch {}
     this.poll()
   }
 
@@ -76,17 +133,7 @@ export class TelegramAdapter {
       })
       for (const update of updates || []) {
         this.offset = Math.max(this.offset, update.update_id + 1)
-        if (update.callback_query) {
-          try { await this.onCallback?.(this.wrapCallback(update.callback_query)) } catch (e) {
-            this.logger?.warn?.(`callback: ${e.message}`)
-          }
-          continue
-        }
-        const msg = update.message
-        if (!msg) continue
-        try { await this.handleMessage(msg) } catch (e) {
-          this.logger?.warn?.(`message: ${e.message}`)
-        }
+        await this.dispatchUpdate(update)
       }
     } catch (e) {
       if (!this.stopped) this.logger?.warn?.(`poll: ${e.message}`)
@@ -94,51 +141,183 @@ export class TelegramAdapter {
     this.schedulePoll()
   }
 
+  async dispatchUpdate(update) {
+    if (update.callback_query) {
+      try { await this.onCallback?.(this.wrapCallback(update.callback_query)) } catch (e) {
+        this.logger?.warn?.(`callback: ${e.message}`)
+      }
+      return
+    }
+    const msg = update.message
+    if (!msg) return
+    try { await this.handleMessage(msg) } catch (e) {
+      this.logger?.warn?.(`message: ${e.message}`)
+    }
+  }
+
+  /** HTTP webhook entry (caller verifies secret). */
+  async handleWebhookUpdate(update) {
+    if (this.stopped) return
+    await this.dispatchUpdate(update)
+  }
+
   wrapCallback(cq) {
     const chatId = cq.message?.chat?.id
     const messageId = cq.message?.message_id
     return {
       platform: 'telegram', chatId, threadId: cq.message?.message_thread_id || 0, userId: cq.from?.id, data: cq.data, callbackQueryId: cq.id,
+      message: cq.message,
       answer: async (text) => this.call('answerCallbackQuery', { callback_query_id: cq.id, text: text || '' }),
-      editMessage: async (text, replyMarkup) => this.call('editMessageText', {
-        chat_id: chatId, message_id: messageId, text, reply_markup: replyMarkup,
-      }),
+      editMessage: async (text, replyMarkup) => {
+        const { text: formatted, parseMode } = this.formatOutgoingText(text)
+        const params = { chat_id: chatId, message_id: messageId, text: formatted, reply_markup: replyMarkup }
+        if (parseMode) params.parse_mode = parseMode
+        try {
+          return await this.call('editMessageText', params)
+        } catch (err) {
+          if (!parseMode) throw err
+          return this.call('editMessageText', { chat_id: chatId, message_id: messageId, text, reply_markup: replyMarkup })
+        }
+      },
     }
   }
 
   allowed(userId) {
+    if (typeof this.isUserAllowed === 'function') return this.isUserAllowed(userId)
     return this.allowedUserIds.length === 0 || this.allowedUserIds.includes(Number(userId))
   }
 
+  async downloadByFileId(fileId, prefix, ext, name = '') {
+    const file = await this.getFile(fileId)
+    const bytes = await this.downloadFile(file.file_path)
+    const resolvedExt = ext || extOf(file.file_path, '') || ''
+    const path = saveToCache(this.media.cacheDir, cacheName(prefix, resolvedExt, name), bytes)
+    return { path, bytes, file }
+  }
+
+  async setReaction(chatId, messageId, emoji) {
+    if (!this.reactionsEnabled || !messageId) return
+    try {
+      await this.call('setMessageReaction', {
+        chat_id: chatId,
+        message_id: messageId,
+        reaction: emoji ? [{ type: 'emoji', emoji }] : [],
+      })
+    } catch (e) {
+      this.logger?.warn?.(`reaction: ${e.message}`)
+    }
+  }
+
   async handleMessage(msg) {
     const chatId = msg.chat.id
+    const chatType = msg.chat?.type || 'private'
     const userId = msg.from?.id ?? chatId
-    if (!this.allowed(userId)) return
+    let text = msg.text ?? msg.caption ?? ''
+    const entities = msg.entities || msg.caption_entities || []
+    const gate = shouldProcessTelegramMessage({
+      chatType,
+      text,
+      entities,
+      replyTo: msg.reply_to_message,
+      botId: this.botId,
+      botUsername: this.botUsername,
+      groupsEnabled: this.groupsEnabled,
+      requireMention: this.groupRequireMention,
+    })
+    if (!gate.ok) return
+
+    if (!this.allowed(userId)) {
+      if (chatType !== 'private') return
+      if (this.onUnauthorized) {
+        await this.onUnauthorized({
+          platform: 'telegram', chatId, userId, threadId: msg.message_thread_id || 0,
+          username: msg.from?.username || '',
+          reply: async (payload) => this.sendReply(chatId, msg.message_id, payload, msg.message_thread_id || 0),
+        })
+      }
+      return
+    }
+
+    text = stripBotCommandSuffix(text, this.botUsername)
     const threadId = msg.message_thread_id || 0
-    const cacheDir = this.media.cacheDir
     const maxDocBytes = this.media.maxDocBytes ?? 20 * 1024 * 1024
     const maxTextInjectBytes = this.media.maxTextInjectBytes ?? 100 * 1024
-    let text = msg.text ?? msg.caption ?? ''
     const attachments = []
-    const replyText = msg.reply_to_message ? (msg.reply_to_message.text ?? msg.reply_to_message.caption ?? '') : ''
+    const replyMsg = msg.reply_to_message
+    let replyText = ''
+    if (replyMsg) {
+      const quoted = replyMsg.text ?? replyMsg.caption ?? ''
+      const quoteFrag = msg.quote?.text || ''
+      replyText = quoteFrag
+        ? `${quoted}${quoted ? '\n' : ''}[цитата: ${quoteFrag}]`
+        : quoted
+    }
 
     if (msg.photo?.length) {
       const largest = msg.photo[msg.photo.length - 1]
-      const file = await this.getFile(largest.file_id)
-      const bytes = await this.downloadFile(file.file_path)
+      const { path, file } = await this.downloadByFileId(largest.file_id, 'photo', extOf('', '') || '.jpg')
       const ext = extOf(file.file_path, '') || '.jpg'
-      attachments.push({ kind: 'photo', path: saveToCache(cacheDir, cacheName('photo', ext, ''), bytes), mime: IMAGE_EXT_TO_MIME[ext] || 'image/jpeg' })
+      attachments.push({ kind: 'photo', path, mime: IMAGE_EXT_TO_MIME[ext] || 'image/jpeg' })
+    }
+    if (msg.sticker) {
+      const st = msg.sticker
+      if (st.is_video) {
+        try {
+          const { path } = await this.downloadByFileId(st.file_id, 'sticker-video', '.webm', st.file_unique_id || '')
+          attachments.push({ kind: 'animation', path, mime: 'video/webm', emoji: st.emoji || '', name: `sticker${st.emoji || ''}.webm` })
+          if (st.emoji) text = `${text}\n[Видео-стикер ${st.emoji}]`.trim()
+        } catch (e) {
+          text = `${text}\n[Видео-стикер ${st.emoji || ''} (не скачан: ${e.message})]`.trim()
+        }
+      } else if (st.is_animated) {
+        try {
+          const { path } = await this.downloadByFileId(st.file_id, 'sticker-anim', '.tgs', st.file_unique_id || '')
+          attachments.push({ kind: 'document', path, mime: 'application/x-tgsticker', emoji: st.emoji || '', name: `sticker${st.emoji || ''}.tgs` })
+          if (st.emoji) text = `${text}\n[Анимированный стикер ${st.emoji}]`.trim()
+        } catch (e) {
+          text = `${text}\n[Анимированный стикер ${st.emoji || ''} (не скачан: ${e.message})]`.trim()
+        }
+      } else {
+        const { path } = await this.downloadByFileId(st.file_id, 'sticker', '.webp', st.file_unique_id || '')
+        attachments.push({ kind: 'sticker', path, mime: 'image/webp', emoji: st.emoji || '', name: `sticker${st.emoji || ''}.webp` })
+      }
     }
     if (msg.voice) {
-      const file = await this.getFile(msg.voice.file_id)
-      const bytes = await this.downloadFile(file.file_path)
-      attachments.push({ kind: 'voice', path: saveToCache(cacheDir, cacheName('voice', '.ogg', ''), bytes), mime: 'audio/ogg' })
+      const { path } = await this.downloadByFileId(msg.voice.file_id, 'voice', '.ogg')
+      attachments.push({ kind: 'voice', path, mime: 'audio/ogg' })
     }
     if (msg.audio) {
-      const file = await this.getFile(msg.audio.file_id)
-      const bytes = await this.downloadFile(file.file_path)
       const ext = extOf(msg.audio.file_name, msg.audio.mime_type) || '.mp3'
-      attachments.push({ kind: 'audio', path: saveToCache(cacheDir, cacheName('audio', ext, msg.audio.file_name || ''), bytes), mime: msg.audio.mime_type || 'audio/mpeg' })
+      const { path } = await this.downloadByFileId(msg.audio.file_id, 'audio', ext, msg.audio.file_name || '')
+      attachments.push({ kind: 'audio', path, mime: msg.audio.mime_type || 'audio/mpeg' })
+    }
+    if (msg.video) {
+      const ext = extOf(msg.video.file_name, msg.video.mime_type) || '.mp4'
+      if ((msg.video.file_size || 0) > maxDocBytes) {
+        text = `${text}\n[Video too large]`.trim()
+      } else {
+        const { path } = await this.downloadByFileId(msg.video.file_id, 'video', ext, msg.video.file_name || '')
+        attachments.push({ kind: 'video', path, mime: msg.video.mime_type || VIDEO_EXT_TO_MIME[ext] || 'video/mp4', name: msg.video.file_name || basename(path) })
+      }
+    }
+    if (msg.video_note) {
+      const vn = msg.video_note
+      if ((vn.file_size || 0) > maxDocBytes) {
+        text = `${text}\n[Video note too large]`.trim()
+      } else {
+        const { path } = await this.downloadByFileId(vn.file_id, 'videonote', '.mp4')
+        attachments.push({ kind: 'video', path, mime: 'video/mp4', name: 'video_note.mp4' })
+      }
+    }
+    if (msg.animation) {
+      const an = msg.animation
+      const ext = extOf(an.file_name, an.mime_type) || '.mp4'
+      if ((an.file_size || 0) > maxDocBytes) {
+        text = `${text}\n[Animation too large]`.trim()
+      } else {
+        const { path } = await this.downloadByFileId(an.file_id, 'anim', ext, an.file_name || '')
+        attachments.push({ kind: 'animation', path, mime: an.mime_type || 'video/mp4', name: an.file_name || basename(path) })
+      }
     }
     if (msg.document) {
       const doc = msg.document
@@ -147,28 +326,95 @@ export class TelegramAdapter {
       if (doc.file_size > maxDocBytes) {
         text = `${text}\n[Document too large: ${doc.file_name || 'file'}]`.trim()
       } else if (kind === 'unsupported') {
-        text = `${text}\n[Unsupported document type: ${doc.file_name || ext}]`.trim()
+        const { path } = await this.downloadByFileId(doc.file_id, 'doc', ext, doc.file_name || '')
+        attachments.push({ kind: 'document', path, mime: doc.mime_type || 'application/octet-stream', name: doc.file_name || basename(path) })
       } else {
-        const file = await this.getFile(doc.file_id)
-        const bytes = await this.downloadFile(file.file_path)
-        const path = saveToCache(cacheDir, cacheName('doc', ext, doc.file_name || ''), bytes)
+        const { path, bytes } = await this.downloadByFileId(doc.file_id, 'doc', ext, doc.file_name || '')
         if (kind === 'image') attachments.push({ kind: 'photo', path, mime: IMAGE_EXT_TO_MIME[ext] || doc.mime_type || 'image/jpeg', name: doc.file_name })
         else if (kind === 'video') attachments.push({ kind: 'video', path, mime: VIDEO_EXT_TO_MIME[ext] || doc.mime_type || 'video/mp4', name: doc.file_name })
-        else if (bytes.length <= maxTextInjectBytes && ['.md', '.txt', '.csv', '.log', '.json', '.xml', '.yaml', '.yml', '.toml', '.ini', '.cfg', '.ts', '.py', '.sh'].includes(ext)) {
+        else if (bytes.length <= maxTextInjectBytes && TEXT_INJECT_EXTS.has(ext)) {
           const body = new TextDecoder('utf-8', { fatal: false }).decode(bytes).slice(0, maxTextInjectBytes)
           text = `${text}\n\n[Document ${doc.file_name}]\n${body}`.trim()
         } else attachments.push({ kind: 'document', path, mime: doc.mime_type || 'application/octet-stream', name: doc.file_name || basename(path) })
       }
     }
 
-    const reply = async (payload) => this.sendReply(chatId, msg.message_id, payload, threadId)
+    const messageId = msg.message_id
+    const reply = async (payload) => this.sendReply(chatId, messageId, payload, threadId)
     const typing = async () => { try { await this.call('sendChatAction', { chat_id: chatId, action: 'typing', ...telegramThreadParams(threadId) }) } catch {} }
+    const startStream = async () => this.startStreamMessage(chatId, messageId, threadId)
+    const startProgress = async () => this.startProgressMessage(chatId, messageId, threadId)
+    const react = async (emoji) => this.setReaction(chatId, messageId, emoji)
 
     await this.onMessage({
-      platform: 'telegram', chatId, userId, threadId, text, attachments, replyText, messageId: msg.message_id, reply, typing,
+      platform: 'telegram', chatId, userId, threadId, chatType, text, attachments, replyText,
+      messageId, reply, typing, startStream, startProgress, react,
     })
   }
 
+  async startProgressMessage(chatId, replyTo, threadId = 0) {
+    const result = await this.call('sendMessage', {
+      chat_id: chatId,
+      text: '⏳ Думаю…',
+      reply_to_message_id: replyTo,
+      ...telegramThreadParams(threadId),
+    })
+    const messageId = result?.message_id
+    return {
+      messageId,
+      edit: async (text) => {
+        const plain = String(text || '⏳ Думаю…').slice(0, TELEGRAM_MAX)
+        try {
+          await this.call('editMessageText', { chat_id: chatId, message_id: messageId, text: plain || '⏳ Думаю…' })
+        } catch (err) {
+          const msg = String(err.message || '')
+          if (!msg.includes('message is not modified')) this.logger?.warn?.(`progress edit: ${err.message}`)
+        }
+      },
+      remove: async () => {
+        try { await this.call('deleteMessage', { chat_id: chatId, message_id: messageId }) } catch {}
+      },
+    }
+  }
+
+  async startStreamMessage(chatId, replyTo, threadId = 0) {
+    const result = await this.call('sendMessage', {
+      chat_id: chatId,
+      text: '…',
+      reply_to_message_id: replyTo,
+      ...telegramThreadParams(threadId),
+    })
+    const messageId = result?.message_id
+    return {
+      messageId,
+      edit: async (text) => {
+        const plain = String(text || '…').slice(0, TELEGRAM_MAX)
+        try {
+          await this.call('editMessageText', { chat_id: chatId, message_id: messageId, text: plain || '…' })
+        } catch (err) {
+          const msg = String(err.message || '')
+          if (!msg.includes('message is not modified')) throw err
+        }
+      },
+      finalize: async (text, payload = {}) => {
+        const { text: formatted, parseMode } = this.formatOutgoingText(String(text || ''), payload)
+        const chunk = splitText(formatted, TELEGRAM_MAX)[0] || '…'
+        const params = { chat_id: chatId, message_id: messageId, text: chunk }
+        if (parseMode) params.parse_mode = parseMode
+        try {
+          await this.call('editMessageText', params)
+        } catch (err) {
+          if (!parseMode) {
+            const msg = String(err.message || '')
+            if (!msg.includes('message is not modified')) throw err
+            return
+          }
+          await this.call('editMessageText', { chat_id: chatId, message_id: messageId, text: splitText(String(text || ''), TELEGRAM_MAX)[0] || '…' })
+        }
+      },
+    }
+  }
+
   async sendMedia(chatId, file, threadId = 0) {
     const form = new FormData()
     form.append('chat_id', String(chatId))
@@ -179,31 +425,62 @@ export class TelegramAdapter {
     if (file.kind === 'photo') { form.append('photo', blob, name); return this.callMultipart('sendPhoto', form) }
     if (file.kind === 'voice') { form.append('voice', blob, name); return this.callMultipart('sendVoice', form) }
     if (file.kind === 'audio') { form.append('audio', blob, name); return this.callMultipart('sendAudio', form) }
+    if (file.kind === 'video') { form.append('video', blob, name); return this.callMultipart('sendVideo', form) }
     form.append('document', blob, name)
     return this.callMultipart('sendDocument', form)
   }
 
-  async sendReply(chatId, replyTo, payload, threadId = 0) {
-    const body = typeof payload === 'string' ? { text: payload } : (payload || {})
-    const files = Array.isArray(body.files) ? body.files : []
-    const text = String(body.text || '')
-    const replyMarkup = body.replyMarkup
-    for (const file of files) {
-      try { await this.sendMedia(chatId, file, threadId) } catch (e) { this.logger?.warn?.(`send media: ${e.message}`) }
-    }
-    if (text) {
-      for (const chunk of splitText(text, TELEGRAM_MAX)) {
+  formatOutgoingText(text, payload = {}) {
+    const mode = payload.parseMode === 'HTML' ? 'html'
+      : payload.parseMode === 'plain' ? 'plain'
+      : this.textFormat
+    return prepareTelegramText(text, mode)
+  }
+
+  async sendFormattedMessage(chatId, replyTo, text, payload, threadId, replyMarkup) {
+    const { text: formatted, parseMode } = this.formatOutgoingText(text, payload)
+    const chunks = splitText(formatted, TELEGRAM_MAX)
+    const plainChunks = splitText(text, TELEGRAM_MAX)
+    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,
+        ...telegramThreadParams(threadId),
+      }
+      if (parseMode) params.parse_mode = parseMode
+      try {
+        await this.call('sendMessage', params)
+      } catch (err) {
+        if (!parseMode) throw err
+        this.logger?.warn?.(`telegram HTML send failed, fallback plain: ${err.message}`)
         await this.call('sendMessage', {
           chat_id: chatId,
-          text: chunk,
+          text: plainChunks[i] ?? chunks[i],
           reply_to_message_id: replyTo,
-          reply_markup: replyMarkup,
+          reply_markup: i === 0 ? replyMarkup : undefined,
           ...telegramThreadParams(threadId),
         })
       }
     }
   }
 
+  async sendReply(chatId, replyTo, payload, threadId = 0) {
+    const body = typeof payload === 'string' ? { text: payload } : (payload || {})
+    const files = Array.isArray(body.files) ? body.files : []
+    const text = String(body.text || '')
+    const replyMarkup = body.replyMarkup
+    for (const file of files) {
+      try {
+        const bytes = file.bytes || (file.path ? await readFile(file.path) : null)
+        if (!bytes) continue
+        await this.sendMedia(chatId, { ...file, bytes }, threadId)
+      } catch (e) { this.logger?.warn?.(`send media: ${e.message}`) }
+    }
+    if (text) await this.sendFormattedMessage(chatId, replyTo, text, body, threadId, replyMarkup)
+  }
+
   async sendTo(chatId, payload, opts = {}) {
     return this.sendReply(chatId, undefined, payload, normalizeThreadId(opts.threadId))
   }