@goodandready/dsh-messenger-gateway 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GooDAnDReaDY
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# @goodandready/dsh-messenger-gateway
+
+Messenger transport for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).
+
+## 0.1.0 scope (Telegram)
+
+- 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`
+
+Discord adapter is a stub; full Discord support comes after 0.1.0.
+
+## 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
+
+## Install
+
+```bash
+dsh plugin --profile web add @goodandready/dsh-messenger-gateway
+```
+
+Settings → **Messenger gateway** → enable Telegram, paste bot token, set allowed user IDs.
+
+See `docs/deployment/0.1.0-install.md` for staging smoke and prod swap vs legacy hub-media.
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+- insert:
+    - id: dsh-messenger-gateway
+      name: '@goodandready/dsh-messenger-gateway'
+      config: {}

package/docs/architecture/2026-08-23-messenger-gateway-design.md

@@ -0,0 +1,30 @@
+# dsh-messenger-gateway — versioning
+
+## Правило версий
+
+| Версия | Когда |
+|--------|--------|
+| **0.0.1, 0.0.2, 0.0.3…** | Каждая отдельная фича (один bump = одна фича) |
+| **0.1.0** | Финальный релиз согласованного scope (замена hub на prod) |
+| **1.0.0** | Когда-нибудь потом, не планируем сейчас |
+
+## Журнал 0.0.x
+
+| Ver | Фича | Статус |
+|-----|------|--------|
+| 0.0.1 | Скелет: Telegram text, Settings, команды | done |
+| 0.0.2 | Черновик: media, outbound, messenger HTTP, topics, TTS toggle, /stop | done (unit tests) |
+| 0.0.3 | Voice inbound via dsh-voice (signal, errors, unit test) | done (E2E smoke — с ботом) |
+| 0.0.4 | Photo inbound + vision-bridge (attachInboundPhoto, maxImageBytes, photoOnlyHint) | done |
+| 0.0.5 | Documents inbound (formatInboundDocument, documentOnlyHint) | done |
+| 0.0.6 | Outbound tool attachments (nested images, URL fetch, stripImageUrls) | done |
+| 0.0.7 | messenger API (HTTP + ctx.provide messenger, validation, schema) | done |
+| 0.0.8 | Inline keyboards ask (lib/ask.js, cleanup, chat guard) | done |
+| 0.0.9 | Forum topics (threadId sessions + outbound message_thread_id) | done |
+| 0.0.10 | TTS replies (prepareTtsText, AbortSignal, maxChars UI) | done |
+| 0.1.0 | Final Telegram scope + prod swap vs hub-media | done |
+| … | Discord | after 0.1.0 |
+
+## Scope 0.1.0 (финал этой линии)
+
+Всё из roadmap п.4 для Telegram, без Discord (Discord — после 0.1.0 или отдельной веткой 0.0.x).

package/docs/deployment/0.1.0-install.md

@@ -0,0 +1,28 @@
+# 0.1.0 install and prod swap
+
+## Prerequisites
+
+Profile bundles must include:
+
+- `dsh-voice`
+- `dsh-tts` (optional)
+- `dsh-vision-bridge`
+
+## Staging smoke
+
+1. Backup profile `package.json`.
+2. `dsh plugin --profile <staging-profile> add file:/opt/plugins-dev/dsh-messenger-gateway`
+   or `add @goodandready/dsh-messenger-gateway@0.1.0` after npm publish.
+3. Restart Harness; verify client.js 200 and `/dsh-messenger-gateway/status`.
+4. Run `docs/testing/0.1.0-smoke.md`.
+
+## RELEASE → npm
+
+Copy to RELEASE/dhsplugins, `npm test`, `npm publish`.
+
+## Prod swap (user approval only)
+
+```bash
+dsh plugin --profile web remove dsh-im-hub-media
+dsh plugin --profile web add @goodandready/dsh-messenger-gateway@0.1.0
+```

package/docs/testing/0.1.0-smoke.md

@@ -0,0 +1,12 @@
+# 0.1.0 manual smoke
+
+- [ ] `/start`, text reply
+- [ ] Voice → dsh-voice transcript
+- [ ] Photo → vision-bridge
+- [ ] Document metadata in prompt
+- [ ] Outbound tool image
+- [ ] messenger HTTP send/ask/progress
+- [ ] Inline keyboard ask
+- [ ] Forum topic session
+- [ ] TTS voice reply (or log warn if down)
+- [ ] `/new` `/stop` `/whoami`

package/lib/adapters/discord.js

@@ -0,0 +1,6 @@
+// Discord adapter — planned for a future release.
+export class DiscordAdapter {
+  constructor() { this.name = 'discord' }
+  async start() { throw new Error('Discord adapter is not implemented yet') }
+  stop() {}
+}

package/lib/adapters/index.js

@@ -0,0 +1,24 @@
+import { TelegramAdapter } from './telegram.js'
+
+export default function createAdapters(deps) {
+  const { config, onMessage, onCallback, logger } = deps
+  const list = []
+  const tg = config.telegram || {}
+  if (config.enabled !== false && tg.enabled && String(tg.botToken || '').trim()) {
+    list.push(new TelegramAdapter({
+      botToken: tg.botToken,
+      allowedUserIds: tg.allowedUserIds,
+      timeoutSeconds: tg.pollTimeoutSeconds,
+      pollIntervalMs: tg.pollIntervalMs,
+      media: config.media,
+      onMessage,
+      onCallback,
+      logger,
+    }))
+  }
+  const dc = config.discord || {}
+  if (config.enabled !== false && dc.enabled) {
+    logger?.warn?.('dsh-messenger-gateway: discord adapter is not implemented yet')
+  }
+  return list
+}

package/lib/adapters/telegram.js

@@ -0,0 +1,210 @@
+import { readFile } from 'node:fs/promises'
+import {
+  IMAGE_EXT_TO_MIME, VIDEO_EXT_TO_MIME, basename, cacheName, classifyDocument,
+  extOf, mediaKindOf, saveToCache, safeName,
+} from '../media.js'
+import { splitText } from '../text.js'
+import { normalizeThreadId, telegramThreadParams } from '../topics.js'
+
+const API = 'https://api.telegram.org'
+const TELEGRAM_MAX = 4096
+
+export class TelegramAdapter {
+  constructor(opts) {
+    this.name = 'telegram'
+    this.token = String(opts.botToken || '').trim()
+    this.allowedUserIds = (opts.allowedUserIds || []).map(Number).filter((n) => Number.isFinite(n))
+    this.timeoutSeconds = Number(opts.timeoutSeconds) || 50
+    this.pollIntervalMs = Number(opts.pollIntervalMs) || 500
+    this.media = opts.media || {}
+    this.onMessage = opts.onMessage
+    this.onCallback = opts.onCallback
+    this.logger = opts.logger
+    this.offset = 0
+    this.stopped = false
+    this.pollTimer = undefined
+  }
+
+  async call(method, params = {}) {
+    const res = await fetch(`${API}/bot${this.token}/${method}`, {
+      method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(params),
+    })
+    const json = await res.json().catch(() => ({}))
+    if (!res.ok || json.ok === false) throw new Error(`telegram ${method}: ${json.description || res.status}`)
+    return json.result
+  }
+
+  async callMultipart(method, form) {
+    const res = await fetch(`${API}/bot${this.token}/${method}`, { method: 'POST', body: form })
+    const json = await res.json().catch(() => ({}))
+    if (!res.ok || json.ok === false) throw new Error(`telegram ${method}: ${json.description || res.status}`)
+    return json.result
+  }
+
+  async getFile(fileId) { return this.call('getFile', { file_id: fileId }) }
+
+  async downloadFile(filePath) {
+    const res = await fetch(`${API}/file/bot${this.token}/${filePath}`)
+    if (!res.ok) throw new Error(`telegram download HTTP ${res.status}`)
+    return new Uint8Array(await res.arrayBuffer())
+  }
+
+  async start() {
+    if (!this.token) throw new Error('telegram bot token is empty')
+    this.stopped = false
+    this.poll()
+  }
+
+  stop() {
+    this.stopped = true
+    if (this.pollTimer) clearTimeout(this.pollTimer)
+  }
+
+  schedulePoll() {
+    if (this.stopped) return
+    this.pollTimer = setTimeout(() => this.poll(), this.pollIntervalMs)
+    this.pollTimer.unref?.()
+  }
+
+  async poll() {
+    if (this.stopped) return
+    try {
+      const updates = await this.call('getUpdates', {
+        timeout: this.timeoutSeconds,
+        offset: this.offset,
+        allowed_updates: ['message', 'callback_query'],
+      })
+      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}`)
+        }
+      }
+    } catch (e) {
+      if (!this.stopped) this.logger?.warn?.(`poll: ${e.message}`)
+    }
+    this.schedulePoll()
+  }
+
+  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,
+      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,
+      }),
+    }
+  }
+
+  allowed(userId) {
+    return this.allowedUserIds.length === 0 || this.allowedUserIds.includes(Number(userId))
+  }
+
+  async handleMessage(msg) {
+    const chatId = msg.chat.id
+    const userId = msg.from?.id ?? chatId
+    if (!this.allowed(userId)) return
+    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 ?? '') : ''
+
+    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 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' })
+    }
+    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' })
+    }
+    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' })
+    }
+    if (msg.document) {
+      const doc = msg.document
+      const ext = extOf(doc.file_name, doc.mime_type)
+      const kind = classifyDocument(ext, doc.mime_type)
+      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()
+      } 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)
+        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)) {
+          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 typing = async () => { try { await this.call('sendChatAction', { chat_id: chatId, action: 'typing', ...telegramThreadParams(threadId) }) } catch {} }
+
+    await this.onMessage({
+      platform: 'telegram', chatId, userId, threadId, text, attachments, replyText, messageId: msg.message_id, reply, typing,
+    })
+  }
+
+  async sendMedia(chatId, file, threadId = 0) {
+    const form = new FormData()
+    form.append('chat_id', String(chatId))
+    const thread = telegramThreadParams(threadId)
+    if (thread.message_thread_id) form.append('message_thread_id', String(thread.message_thread_id))
+    const blob = new Blob([file.bytes])
+    const name = safeName(file.name || 'file')
+    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) }
+    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)) {
+        await this.call('sendMessage', {
+          chat_id: chatId,
+          text: chunk,
+          reply_to_message_id: replyTo,
+          reply_markup: replyMarkup,
+          ...telegramThreadParams(threadId),
+        })
+      }
+    }
+  }
+
+  async sendTo(chatId, payload, opts = {}) {
+    return this.sendReply(chatId, undefined, payload, normalizeThreadId(opts.threadId))
+  }
+}

package/lib/ask.js

@@ -0,0 +1,63 @@
+import { randomUUID } from 'node:crypto'
+import { normalizeThreadId } from './topics.js'
+
+export const TELEGRAM_CALLBACK_DATA_MAX = 64
+
+export function makeAskToken() {
+  return randomUUID().replace(/-/g, '').slice(0, 12)
+}
+
+export function buildCallbackData(token, buttonId) {
+  const data = `${token}:${buttonId}`
+  if (data.length > TELEGRAM_CALLBACK_DATA_MAX) {
+    const err = new Error(`callback_data too long (${data.length} > ${TELEGRAM_CALLBACK_DATA_MAX})`)
+    err.status = 400
+    throw err
+  }
+  return data
+}
+
+export function parseCallbackData(data) {
+  const raw = String(data || '')
+  const idx = raw.indexOf(':')
+  if (idx <= 0) return { token: undefined, buttonId: raw }
+  return { token: raw.slice(0, idx), buttonId: raw.slice(idx + 1) }
+}
+
+export function buildInlineKeyboard(token, buttons) {
+  const callbackKeys = []
+  const rows = (buttons || []).map((row) => row.map((btn) => {
+    const callback_data = buildCallbackData(token, btn.id)
+    callbackKeys.push(callback_data)
+    return { text: btn.text, callback_data }
+  }))
+  return {
+    replyMarkup: rows.length ? { inline_keyboard: rows } : undefined,
+    callbackKeys,
+  }
+}
+
+export function indexCallbacks(callbackIndex, keys, token) {
+  for (const key of keys || []) callbackIndex.set(key, token)
+}
+
+export function releaseCallbacks(callbackIndex, keys) {
+  for (const key of keys || []) callbackIndex.delete(key)
+}
+
+export function targetMatchesAsk(pending, cb) {
+  const target = pending?.target
+  if (!target) return false
+  if (cb?.platform && target.platform && cb.platform !== target.platform) return false
+  if (cb?.chatId !== undefined && String(target.chatId) !== String(cb.chatId)) return false
+  if (normalizeThreadId(target.threadId) !== normalizeThreadId(cb?.threadId)) return false
+  return true
+}
+
+export function rejectPendingAsk(pending, err) {
+  if (!pending) return
+  clearTimeout(pending.timer)
+  pending.reject(err)
+}
+
+export const REMOVE_KEYBOARD = { inline_keyboard: [] }

package/lib/client.js

@@ -0,0 +1,96 @@
+window.__ModuleLoader__.load({
+  id: '@goodandready/dsh-messenger-gateway',
+  factory: (require) => {
+    var module = { exports: {} }
+    var exports = module.exports
+    const React = require('react')
+
+    function idsToText(ids) { return (Array.isArray(ids) ? ids : []).map(String).filter(Boolean).join(', ') }
+    function textToIds(text) {
+      return String(text || '').split(/[\s,]+/).map((s) => s.trim()).filter(Boolean).map(Number).filter((n) => Number.isFinite(n))
+    }
+
+    function Section() {
+      const [cfg, setCfg] = React.useState(null)
+      const [token, setToken] = React.useState('')
+      const [allowText, setAllowText] = React.useState('')
+      const [err, setErr] = React.useState('')
+      const [busy, setBusy] = React.useState(false)
+
+      const load = React.useCallback(async () => {
+        const res = await fetch('/dsh-messenger-gateway/config', { credentials: 'same-origin' })
+        const data = await res.json()
+        if (!res.ok || !data.ok) throw new Error(data.error || res.status)
+        setCfg(data.config)
+        setAllowText(idsToText(data.config?.telegram?.allowedUserIds))
+      }, [])
+
+      React.useEffect(() => { load().catch((e) => setErr(String(e.message || e))) }, [load])
+
+      const save = async (patch) => {
+        setBusy(true); setErr('')
+        try {
+          const body = {
+            config: {
+              ...cfg,
+              ...patch,
+              telegram: { ...cfg.telegram, ...(patch.telegram || {}) },
+              tts: { ...cfg.tts, ...(patch.tts || {}) },
+            },
+          }
+          if (token.trim()) body.config.telegram = { ...body.config.telegram, botToken: token.trim() }
+          body.config.telegram.allowedUserIds = textToIds(allowText)
+          const res = await fetch('/dsh-messenger-gateway/config', {
+            method: 'PUT', credentials: 'same-origin',
+            headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body),
+          })
+          const data = await res.json()
+          if (!res.ok || !data.ok) throw new Error(data.error || res.status)
+          setCfg(data.config); setToken('')
+          setAllowText(idsToText(data.config?.telegram?.allowedUserIds))
+        } catch (e) { setErr(String(e.message || e)) } finally { setBusy(false) }
+      }
+
+      if (!cfg) return React.createElement('div', null, err || 'Loading…')
+
+      return React.createElement('div', { style: { display: 'flex', flexDirection: 'column', gap: 12, maxWidth: 720 } },
+        React.createElement('div', { style: { fontWeight: 600 } }, 'Messenger gateway'),
+        React.createElement('div', { style: { fontSize: 12, opacity: 0.75 } }, 'Telegram: text, voice (dsh-voice), photos, documents. Optional voice replies via dsh-tts.'),
+        React.createElement('label', null, 'Bot token (write-only)'),
+        React.createElement('input', { type: 'password', value: token, placeholder: cfg.telegram?.botTokenConfigured ? '••••••••' : 'BotFather token', onChange: (e) => setToken(e.target.value) }),
+        React.createElement('label', null, 'Allowed user ids (comma-separated, empty = all)'),
+        React.createElement('textarea', { value: allowText, onChange: (e) => setAllowText(e.target.value), rows: 2 }),
+        React.createElement('label', { style: { display: 'flex', gap: 8, alignItems: 'center' } },
+          React.createElement('input', { type: 'checkbox', checked: !!cfg.tts?.enabled, onChange: (e) => save({ tts: { enabled: e.target.checked } }) }),
+          'Speak agent replies (dsh-tts)',
+        ),
+        cfg.tts?.enabled ? React.createElement('label', null,
+          'Max spoken chars',
+          React.createElement('input', {
+            type: 'number', min: 100, max: 8000,
+            value: cfg.tts?.maxChars ?? 4000,
+            onChange: (e) => setCfg({ ...cfg, tts: { ...cfg.tts, maxChars: Number(e.target.value) || 4000 } }),
+          }),
+        ) : null,
+        React.createElement('div', { style: { display: 'flex', gap: 8, flexWrap: 'wrap' } },
+          React.createElement('button', { disabled: busy, onClick: () => save({ telegram: { enabled: !cfg.telegram.enabled } }) }, cfg.telegram.enabled ? 'Disable Telegram' : 'Enable Telegram'),
+          React.createElement('button', { disabled: busy, onClick: () => save({}) }, 'Save'),
+        ),
+        err ? React.createElement('div', { style: { color: 'crimson', fontSize: 12 } }, err) : null,
+      )
+    }
+
+    function apply(ctx) {
+      ctx.slots.inject('settings.section', () => ctx.slots.register({
+        name: 'settings.section',
+        id: '@goodandready/dsh-messenger-gateway',
+        order: 36,
+        label: () => 'Messenger gateway',
+      }, Section))
+    }
+
+    exports.apply = apply
+    exports.inject = ['slots']
+    return module.exports
+  },
+})

package/lib/documents.js

@@ -0,0 +1,16 @@
+/** Format a cached inbound document/video path for the agent (fs tools). */
+export function formatInboundDocument(att) {
+  const kind = att?.kind || 'document'
+  const label = kind === 'video' ? 'Видео' : 'Документ'
+  const name = att?.name ? ` ${att.name}` : ''
+  const mime = att?.mime ? ` (${att.mime})` : ''
+  return `[${label}${name}${mime}]\nПуть: ${att.path}`
+}
+
+export function documentOnlyHint(attachments, userText) {
+  if (String(userText || '').trim()) return ''
+  const docs = attachments.filter((a) => a.kind === 'document' || a.kind === 'video')
+  if (!docs.length) return ''
+  if (docs.length === 1) return '[Пользователь отправил файл]'
+  return `[Пользователь отправил ${docs.length} файла]`
+}