@goodandready/dsh-messenger-gateway 0.1.0 → 0.3.0

package/lib/stream.js

@@ -0,0 +1,64 @@
+/** Helpers for Telegram streaming edits + progress. */
+
+export function extractTextDelta(chunk) {
+  if (!chunk || typeof chunk !== 'object') return ''
+  if (chunk.type === 'text-delta' && typeof chunk.text === 'string') return chunk.text
+  return ''
+}
+
+export function extractToolName(eventData) {
+  const name = eventData?.tool?.name || eventData?.toolName || eventData?.name
+  return name ? String(name) : ''
+}
+
+export function formatProgressLine(toolName) {
+  if (!toolName) return '⏳ Думаю…'
+  return `🔧 ${toolName}…`
+}
+
+export function buildStreamPreview(streamText, toolName, maxLen = 3500) {
+  const body = String(streamText || '').trimEnd()
+  const head = toolName ? `${formatProgressLine(toolName)}\n\n` : ''
+  const combined = head + (body || '…')
+  if (combined.length <= maxLen) return combined
+  return combined.slice(0, maxLen - 1) + '…'
+}
+
+export function createEditScheduler(editFn, intervalMs = 1200) {
+  let pending = null
+  let timer = null
+  let lastSent = ''
+  let inFlight = Promise.resolve()
+  const flush = () => {
+    timer = null
+    if (pending === null || pending === lastSent) return
+    const text = pending
+    inFlight = inFlight.then(async () => {
+      try {
+        await editFn(text)
+        lastSent = text
+      } catch {}
+    })
+  }
+  return {
+    push(text) {
+      pending = text
+      if (timer) return
+      timer = setTimeout(flush, Math.max(200, intervalMs))
+      timer.unref?.()
+    },
+    async flush() {
+      if (timer) { clearTimeout(timer); timer = null }
+      flush()
+      await inFlight
+    },
+  }
+}
+
+export function startTypingHeartbeat(typingFn, intervalMs = 4000) {
+  if (typeof typingFn !== 'function') return () => {}
+  typingFn().catch?.(() => {})
+  const timer = setInterval(() => { typingFn().catch?.(() => {}) }, intervalMs)
+  timer.unref?.()
+  return () => clearInterval(timer)
+}

package/lib/telegram-errors.js

@@ -0,0 +1,41 @@
+// Network error classification for Telegram sends (mirrors Hermes adapter policy).
+//
+// The key distinction: some network failures mean the request NEVER left the
+// process (connect/pool timeout, ECONNRESET before send) → resending is safe.
+// Others (a generic timeout after the request may have reached Telegram) could
+// duplicate a message if we resend → do NOT retry.
+
+function rootCause(err) {
+  let e = err
+  let depth = 0
+  while (e && e.cause && e.cause !== e && depth < 10) {
+    e = e.cause
+    depth++
+  }
+  return e || err
+}
+
+// True when a resend cannot duplicate a message: the request did not reach Telegram.
+export function isResendSafeNetworkError(err) {
+  const c = rootCause(err)
+  const msg = String(c?.message || err?.message || '').toLowerCase()
+  if (/not sent to telegram|connect timeout|und_err_connect|econnreset|enotfound|econnrefused|ECONNRESET|ENOTFOUND|ECONNREFUSED/i.test(msg)) {
+    return true
+  }
+  // undici PoolTimeout message: "Request was *not* sent to Telegram."
+  if (/pool timeout|request was \*?not\*? sent/i.test(msg)) return true
+  return false
+}
+
+// True for a 409 from getUpdates: a second bot instance polls the same token.
+export function isPollingConflict(err) {
+  const msg = String(err?.message || '').toLowerCase()
+  return /terminated by other getupdates request|another bot instance is running|getupdates.*conflict|conflict.*getupdates/i.test(msg)
+}
+
+// True when the target chat/topic no longer exists (deleted/closed/upgraded).
+// Such sends should not be retried and any pending ask binding must be pruned.
+export function isTopicGoneError(err) {
+  const msg = String(err?.message || '').toLowerCase()
+  return /thread not found|message thread not found|topic[_ ]?(not found|closed|deleted)|chat (not found|was (upgraded|deleted))|group chat was (upgraded|deleted)/i.test(msg)
+}

package/lib/telegram-format.js

@@ -0,0 +1,141 @@
+export function escapeHtml(text) {
+  return String(text ?? '')
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+}
+
+const PH = '\uE000'
+
+// Render inline markdown (bold/italic/code/links) inside already-HTML-escaped text.
+function renderInline(t) {
+  let s = escapeHtml(t)
+  s = s.replace(/\*\*([^*\n]+)\*\*/g, '<b>$1</b>')
+  s = s.replace(/`([^`\n]+)`/g, '<code>$1</code>')
+  s = s.replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, (_, label, url) => `<a href="${escapeHtml(url)}">${label}</a>`)
+  s = s.replace(/(^|[^*])\*([^*\n]+)\*(?!\*)/g, '$1<i>$2</i>')
+  return s
+}
+
+function splitRow(line) {
+  let s = line.trim()
+  if (s.startsWith('|')) s = s.slice(1)
+  if (s.endsWith('|')) s = s.slice(0, -1)
+  return s.split('|').map((c) => c.trim())
+}
+
+function isTableDelimiter(line) {
+  const s = line.trim()
+  if (!s.startsWith('|') || !s.endsWith('|')) return false
+  const cells = s.split('|').slice(1, -1)
+  return cells.length > 0 && cells.every((c) => /^:?-+:?$/.test(c.trim()))
+}
+
+// GFM pipe tables → bold heading + bullet rows (Telegram HTML has no table syntax).
+function convertTables(text, stash) {
+  const lines = text.split('\n')
+  const out = []
+  let i = 0
+  while (i < lines.length) {
+    const line = lines[i]
+    if (line.includes('|') && i + 1 < lines.length && isTableDelimiter(lines[i + 1])) {
+      const headers = splitRow(line)
+      const rows = []
+      let j = i + 2
+      while (j < lines.length && lines[j].includes('|') && !isTableDelimiter(lines[j])) {
+        rows.push(splitRow(lines[j]))
+        j++
+      }
+      let blocks
+      if (headers.length === 2) {
+        // key/value table → bullet list, no separate heading row
+        blocks = rows.map((row) => `• <b>${renderInline(row[0] || '')}</b>: ${renderInline(row[1] || '')}`)
+      } else {
+        blocks = rows.map((row) => {
+          const heading = renderInline(row[0] || '')
+          const bullets = headers
+            .slice(1)
+            .map((h, idx) => {
+              const val = (row[idx + 1] || '').trim()
+              if (!val) return null
+              return `• ${renderInline(h)}: ${renderInline(val)}`
+            })
+            .filter(Boolean)
+          return bullets.length ? `<b>${heading}</b>\n${bullets.join('\n')}` : `<b>${heading}</b>`
+        })
+      }
+      out.push(stash(blocks.join('\n\n')))
+      i = j
+      continue
+    }
+    out.push(line)
+    i++
+  }
+  return out.join('\n')
+}
+
+// GFM task lists → checkbox glyphs.
+function convertTaskLists(text, stash) {
+  const lines = text.split('\n')
+  const out = []
+  let buf = []
+  const flush = () => {
+    if (buf.length) {
+      out.push(stash(buf.join('\n')))
+      buf = []
+    }
+  }
+  for (const line of lines) {
+    const m = line.match(/^(\s*)[-*]\s+\[([ xX])\]\s+(.*)$/)
+    if (m) {
+      buf.push(`${m[1]}${m[2].toLowerCase() === 'x' ? '☑' : '☐'} ${renderInline(m[3])}`)
+    } else {
+      flush()
+      out.push(line)
+    }
+  }
+  flush()
+  return out.join('\n')
+}
+
+// <details><summary>..</summary>..</details> → bold summary + body (no native collapse in HTML).
+function convertDetails(text, stash) {
+  return text.replace(
+    /<details\b[^>]*>\s*<summary>([\s\S]*?)<\/summary>([\s\S]*?)<\/details>/gi,
+    (_, summary, body) => stash(`<b>${renderInline(summary.trim())}</b>\n${renderInline(body.trim())}`),
+  )
+}
+
+/** Convert common Markdown from LLM replies to Telegram HTML parse_mode. */
+export function markdownToTelegramHtml(markdown) {
+  let text = String(markdown ?? '')
+  const slots = []
+
+  const stash = (html) => {
+    const id = slots.length
+    slots.push(html)
+    return `${PH}${id}${PH}`
+  }
+
+  text = text.replace(/```([\s\S]*?)```/g, (_, code) => stash(`<pre><code>${escapeHtml(code.replace(/^\n/, '').replace(/\n$/, ''))}</code></pre>`))
+  text = text.replace(/`([^`\n]+)`/g, (_, code) => stash(`<code>${escapeHtml(code)}</code>`))
+  text = convertTables(text, stash)
+  text = convertDetails(text, stash)
+  text = convertTaskLists(text, stash)
+  text = escapeHtml(text)
+  text = text.replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, (_, label, url) => `<a href="${escapeHtml(url)}">${label}</a>`)
+  text = text.replace(/\*\*([^*\n]+)\*\*/g, '<b>$1</b>')
+  text = text.replace(/__([^_\n]+)__/g, '<b>$1</b>')
+  text = text.replace(/~~([^~\n]+)~~/g, '<s>$1</s>')
+  text = text.replace(/(^|[^*])\*([^*\n]+)\*(?!\*)/g, '$1<i>$2</i>')
+  text = text.replace(/(^|[^_])_([^_\n]+)_(?!_)/g, '$1<i>$2</i>')
+  text = text.replace(/^#{1,6}\s+(.+)$/gm, '<b>$1</b>')
+  for (let i = 0; i < slots.length; i++) text = text.replace(`${PH}${i}${PH}`, slots[i])
+  return text
+}
+
+export function prepareTelegramText(text, format = 'html') {
+  const raw = String(text ?? '')
+  if (!raw || format === 'plain') return { text: raw, parseMode: undefined }
+  return { text: markdownToTelegramHtml(raw), parseMode: 'HTML' }
+}

package/lib/text.js

@@ -19,4 +19,21 @@ export function assistantText(message) {
     .filter((block) => block.type === 'text')
     .map((block) => block.text)
     .join('')
-}
+}
+
+
+/** Drop English reasoning preamble before the user-facing reply (Telegram). */
+export function stripReasoningPreamble(text) {
+  const raw = String(text ?? '').trim()
+  if (!raw) return raw
+  const paragraphs = raw.split(/\n\n+/)
+  for (let i = 0; i < paragraphs.length; i++) {
+    const p = paragraphs[i]
+    const cyrillic = (p.match(/[\u0400-\u04FF]/g) || []).length
+    const latin = (p.match(/[A-Za-z]/g) || []).length
+    if (cyrillic >= 12 && cyrillic > latin) return paragraphs.slice(i).join('\n\n').trim()
+  }
+  return raw
+}
+
+export const MESSENGER_RELAY_INSTRUCTION = 'Канал: Telegram. Отвечай только пользователю по-русски. Не выводи ход рассуждений, планирование и служебный текст на английском.'

package/lib/topics.js

@@ -6,22 +6,41 @@ export function normalizeThreadId(threadId) {
   return Math.trunc(n)
 }
 
-/** Stable session key: one agent per platform+chat+topic. */
+/** Stable base key: platform+chat+topic. */
 export function chatKey(platform, chatId, threadId = 0) {
   return `${platform}:${chatId}:${normalizeThreadId(threadId)}`
 }
 
+/**
+ * Session map key.
+ * scope=user in groups → one agent per user in that chat/topic.
+ * Private chats ignore user suffix (already 1:1).
+ */
+export function sessionKey({ platform, chatId, threadId = 0, userId, chatType, scope = "chat" }) {
+  const base = chatKey(platform, chatId, threadId)
+  const isGroup = chatType === "group" || chatType === "supergroup"
+  if (scope === "user" && isGroup && userId != null && Number.isFinite(Number(userId))) {
+    return `${base}:u:${Number(userId)}`
+  }
+  return base
+}
+
 export function parseChatKey(key) {
-  const parts = String(key || '').split(':')
+  const parts = String(key || "").split(":")
   if (parts.length < 2) return null
   const platform = parts[0]
   const chatId = parts[1]
   const threadId = parts.length >= 3 ? normalizeThreadId(parts[2]) : 0
-  return { platform, chatId, threadId }
+  const out = { platform, chatId, threadId }
+  if (parts.length >= 5 && parts[3] === "u") {
+    const userId = Number(parts[4])
+    if (Number.isFinite(userId)) out.userId = userId
+  }
+  return out
 }
 
 /** Extra Telegram API fields for forum topic replies. */
 export function telegramThreadParams(threadId) {
   const tid = normalizeThreadId(threadId)
   return tid > 0 ? { message_thread_id: tid } : {}
-}
+}

package/lib/tts.js

@@ -1,4 +1,9 @@
-/** Prepare agent text for dsh-tts and map audio to Telegram voice messages. */
+/** Prepare agent text for dsh-tts and map audio to Telegram voice notes. */
+
+import { spawn } from 'node:child_process'
+import { mkdtemp, writeFile, readFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 
 export const DEFAULT_TTS_MAX_CHARS = 4000
 
@@ -29,6 +34,11 @@ export function voiceFileNameForMime(mime) {
   return 'reply.dat'
 }
 
+export function isOggOpusMime(mime) {
+  const m = String(mime || '').toLowerCase()
+  return m.includes('ogg') || m.includes('opus')
+}
+
 export function voiceReplyFile(spoken) {
   const mime = spoken?.mime || 'audio/mpeg'
   return {
@@ -37,4 +47,74 @@ export function voiceReplyFile(spoken) {
     kind: 'voice',
     name: voiceFileNameForMime(mime),
   }
-}
+}
+
+function runFfmpeg(args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn('ffmpeg', args, { stdio: ['ignore', 'ignore', 'pipe'] })
+    let err = ''
+    child.stderr.on('data', (chunk) => { err += String(chunk) })
+    child.on('error', reject)
+    child.on('close', (code) => {
+      if (code === 0) resolve()
+      else reject(new Error(`ffmpeg exit ${code}: ${err.slice(-400)}`))
+    })
+  })
+}
+
+/** Convert arbitrary TTS audio bytes to OGG/Opus for Telegram sendVoice. */
+export async function convertToOggOpus(audioBytes, inputMime = 'audio/mpeg') {
+  const dir = await mkdtemp(join(tmpdir(), 'msgw-tts-'))
+  const ext = voiceFileNameForMime(inputMime).split('.').pop() || 'mp3'
+  const input = join(dir, `in.${ext}`)
+  const output = join(dir, 'out.ogg')
+  try {
+    await writeFile(input, audioBytes)
+    await runFfmpeg([
+      '-y', '-hide_banner', '-loglevel', 'error',
+      '-i', input,
+      '-c:a', 'libopus',
+      '-b:a', '32k',
+      '-vbr', 'on',
+      '-application', 'voip',
+      output,
+    ])
+    return await readFile(output)
+  } finally {
+    await rm(dir, { recursive: true, force: true }).catch(() => {})
+  }
+}
+
+/**
+ * Build a Telegram voice-note file from dsh-tts output.
+ * Prefer OGG/Opus; if conversion fails and binary missing, fall back to audio (not voice-note).
+ */
+export async function toTelegramVoiceFile(spoken, { logger } = {}) {
+  if (!spoken?.audio?.length) return null
+  if (isOggOpusMime(spoken.mime)) {
+    return {
+      bytes: spoken.audio,
+      mime: 'audio/ogg',
+      kind: 'voice',
+      name: 'reply.ogg',
+    }
+  }
+  try {
+    const ogg = await convertToOggOpus(spoken.audio, spoken.mime)
+    return {
+      bytes: ogg,
+      mime: 'audio/ogg',
+      kind: 'voice',
+      name: 'reply.ogg',
+    }
+  } catch (err) {
+    logger?.warn?.(`tts opus convert skipped: ${err.message}`)
+    // Telegram sendVoice rejects mp3; send as audio file instead of failing silently.
+    return {
+      bytes: spoken.audio,
+      mime: spoken.mime || 'audio/mpeg',
+      kind: 'audio',
+      name: voiceFileNameForMime(spoken.mime),
+    }
+  }
+}

package/lib/voice-prefs.js

@@ -0,0 +1,44 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs"
+import { dirname } from "node:path"
+
+export function createVoicePrefs(filePath) {
+  /** @type {Record<string, boolean>} */
+  let state = {}
+  if (filePath && existsSync(filePath)) {
+    try {
+      const raw = JSON.parse(readFileSync(filePath, "utf8"))
+      if (raw && typeof raw === "object") state = raw
+    } catch {}
+  }
+  const persist = () => {
+    if (!filePath) return
+    mkdirSync(dirname(filePath), { recursive: true })
+    writeFileSync(filePath, JSON.stringify(state, null, 2))
+  }
+  const key = (userId) => String(Number(userId) || userId || "")
+  return {
+    get(userId) {
+      const k = key(userId)
+      if (!k || !(k in state)) return null
+      return Boolean(state[k])
+    },
+    set(userId, enabled) {
+      const k = key(userId)
+      if (!k) return false
+      state[k] = Boolean(enabled)
+      persist()
+      return true
+    },
+  }
+}
+
+/** Decide whether to speak the reply. */
+export function shouldSpeakReply({ globalTts, voiceMode, inboundWasVoice, userPref }) {
+  if (globalTts) return true
+  if (userPref === true) return true
+  if (userPref === false) return false
+  if (voiceMode === "always") return true
+  if (voiceMode === "off") return false
+  // mirror: speak if inbound was voice
+  return Boolean(inboundWasVoice)
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@goodandready/dsh-messenger-gateway",
-  "version": "0.1.0",
-  "description": "Messenger gateway for DeepSeek Harness: Telegram transport (0.1.0 scope). Discord planned.",
+  "version": "0.3.0",
+  "description": "Telegram messenger bridge for DeepSeek Harness: sessions, steer, homes, inline asks, notify bridge, and optional TTS voice notes.",
   "license": "MIT",
   "type": "module",
   "main": "./lib/index.js",
@@ -15,24 +15,26 @@
     "lib/",
     "cordis.patch.yml",
     "README.md",
-    "LICENSE",
-    "docs/"
+    "LICENSE"
   ],
   "keywords": [
     "dsh",
     "dsh-plugin",
     "telegram",
-    "discord",
     "messenger",
-    "deepseek-harness"
+    "deepseek-harness",
+    "bot"
   ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/GooDAnDReaDY/dsh-messenger-gateway.git"
   },
-  "homepage": "https://github.com/GooDAnDReaDY/dsh-messenger-gateway",
+  "homepage": "https://github.com/GooDAnDReaDY/dsh-messenger-gateway#readme",
   "scripts": {
-    "test": "node --test test/*.test.mjs"
+    "test": "node --test test/*.test.mjs",
+    "test:load": "node scripts/verify-dsh-load.mjs",
+    "test:all": "npm test && npm run test:load",
+    "smoke:http": "node scripts/smoke-http.mjs"
   },
   "dsh": {
     "bundle": {
@@ -56,9 +58,13 @@
     "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
-    "@deepseek-ai/schemastery": "^3.18.1"
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "bugs": {
+    "url": "https://github.com/GooDAnDReaDY/dsh-messenger-gateway/issues"
   }
 }

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

@@ -1,30 +0,0 @@
-# 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

@@ -1,28 +0,0 @@
-# 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

@@ -1,12 +0,0 @@
-# 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`