@goodandready/dsh-messenger-gateway 0.3.14 → 0.3.19

package/lib/content-guard.js

@@ -0,0 +1,14 @@
+/**
+ * Normalize any content value to ContentBlock[].
+ * DSH core (dsh-llm) calls content.some() without Array.isArray guard,
+ * so we must ensure every message we create or copy has array content.
+ * Refs: #51
+ */
+export function ensureContentArray(content) {
+  if (Array.isArray(content)) return content
+  if (typeof content === 'string') {
+    return content ? [{ type: 'text', text: content }] : [{ type: 'text', text: '(пустое сообщение)' }]
+  }
+  if (content && typeof content === 'object' && content.type) return [content]
+  return [{ type: 'text', text: String(content ?? '(пустое сообщение)') }]
+}

package/lib/gateway.js

@@ -33,6 +33,8 @@ import {
   createEditScheduler, startTypingHeartbeat,
 } from './stream.js'
 import { isTopicGoneError } from './telegram-errors.js'
+import { ensureContentArray } from './content-guard.js'
+
 
 function whenIdleWithTimeout(agent, timeoutMs, signal) {
   const idle = agent.whenIdle()
@@ -338,8 +340,8 @@ export class Gateway {
           return
         }
         if (action.kind === 'done') {
-          clearTimeout(pending.timer)
           this.pendingAsks.delete(askToken)
+          clearTimeout(pending.timer)
           releaseCallbacks(this.callbackIndex, pending.callbackKeys)
           await cb.answer('OK')
           try { await cb.editMessage(cb.message?.text || 'Выбрано', REMOVE_KEYBOARD) } catch {}
@@ -347,8 +349,8 @@ export class Gateway {
           return
         }
         if (action.kind === 'cancel') {
-          clearTimeout(pending.timer)
           this.pendingAsks.delete(askToken)
+          clearTimeout(pending.timer)
           releaseCallbacks(this.callbackIndex, pending.callbackKeys)
           await cb.answer('Отменено')
           try { await cb.editMessage(cb.message?.text || 'Отменено', REMOVE_KEYBOARD) } catch {}
@@ -356,8 +358,8 @@ export class Gateway {
           return
         }
       }
-      clearTimeout(pending.timer)
       this.pendingAsks.delete(askToken)
+      clearTimeout(pending.timer)
       releaseCallbacks(this.callbackIndex, pending.callbackKeys)
       await cb.answer('OK')
       try { await cb.editMessage(cb.message?.text || 'Выбрано', REMOVE_KEYBOARD) } catch {}
@@ -522,7 +524,7 @@ export class Gateway {
           steer: true,
         }, undefined)
         chat.agent.followup(createUserMessage({
-          content,
+          content: ensureContentArray(content),
           source: { kind: 'plugin', plugin: PLUGIN, form: 'steer' },
         }))
         chat.lastUsed = Date.now()
@@ -532,6 +534,7 @@ export class Gateway {
 
       // Mark busy BEFORE yielding to the poll loop, otherwise steer/stop never see an active turn.
       chat.turnActive = true
+      try { chat.abort?.abort?.() } catch {}
       chat.abort = new AbortController()
       const run = chat.busy.then(() => this.runTurn(chat, turnInput, chat.abort.signal))
       chat.busy = run.catch(() => {})
@@ -625,9 +628,9 @@ export class Gateway {
       return reply(`🎭 Роль изменена на: ${persona.icon} <b>${persona.name}</b>\n${persona.description}`)
     }
     if (cmd === '/skills' || cmd === '/tools') {
-      const toolsList = []
-      if (this.ctx.tools?.tools) {
-        for (const [name, t] of this.ctx.tools.tools.entries()) {
+      const tools = this.ctx.get?.('tools') || this.ctx.tools
+      if (tools?.tools) {
+        for (const [name, t] of tools.tools.entries()) {
           toolsList.push(`• <b>${name}</b>: ${t.description || '(нет описания)'}`)
         }
       }
@@ -655,7 +658,6 @@ export class Gateway {
           mime: 'text/markdown',
           kind: 'document',
           bytes: buffer,
-          dataBase64: buffer.toString('base64'),
         }
         return reply({ text: `📄 Экспорт диалога (${messagesCount} сообщений):`, files: [file] })
       } catch (err) {
@@ -672,7 +674,8 @@ export class Gateway {
       if (!res.removed) {
         return reply('В истории сессии нет сообщений для отката.')
       }
-      try { await this.ctx.sessions?.flush(chat.agent.session) } catch {}
+      const sessions = this.ctx.get?.('sessions') || this.ctx.sessions
+      try { await sessions?.flush(chat.agent.session) } catch {}
       return reply(`⏪ Откачено сообщений: ${res.removed}. Осталось в контексте: ${res.remaining}.`)
     }
     if (cmd === '/fork') {
@@ -682,11 +685,14 @@ export class Gateway {
       }
       try {
         const oldSession = chat.agent.session
-        const oldMessages = Array.isArray(oldSession.messages) ? [...oldSession.messages] : []
+        const oldMessages = Array.isArray(oldSession.messages)
+          ? oldSession.messages.map(m => ({ ...m, content: ensureContentArray(m.content) }))
+          : []
         const newChat = await this.createChat(key, input)
         if (newChat.agent?.session && oldMessages.length) {
           newChat.agent.session.messages = oldMessages
-          try { await this.ctx.sessions?.flush(newChat.agent.session) } catch {}
+          const sessions = this.ctx.get?.('sessions') || this.ctx.sessions
+          try { await sessions?.flush(newChat.agent.session) } catch {}
         }
         this.chats.set(key, newChat)
         return reply(`🔀 Создан форк сессии!\nСтарая сессия: ${oldSession.id}\nНовая активная сессия: ${newChat.agent.session.id}\nКонтекст сохранён (${oldMessages.length} сообщений).`)
@@ -1074,7 +1080,8 @@ export class Gateway {
     const agentCfg = this.config.agent || {}
     const cwd = agentCfg.cwd || process.cwd()
     const self = this
-    const handle = await this.ctx.agents.create({
+    const agents = this.ctx.get?.('agents') || this.ctx.agents
+    const handle = await agents.create({
       sessionId: SessionId(`msgw-${randomUUID()}`),
       meta: { cwd },
       agentOptions: { provider, model },
@@ -1192,12 +1199,13 @@ export class Gateway {
       if (typeof react === 'function' && tg.reactionsEnabled !== false) {
         react('👀').catch?.(() => {})
       }
-      if (progressEnabled) stopTyping = startTypingHeartbeat(typing, 4000)
+      if (typeof typing === 'function') stopTyping = startTypingHeartbeat(typing, 4000)
       if (streaming) {
         try {
           stream = await startStream()
           scheduler = createEditScheduler((text) => stream.edit(text), Number(tg.streamEditIntervalMs) || 1200)
           collector.onStream = (text, toolName) => {
+            if (text) stopTyping()
             if (!progressEnabled && !text) return
             scheduler.push(buildStreamPreview(text, progressEnabled ? toolName : ''))
           }
@@ -1216,15 +1224,13 @@ export class Gateway {
         } catch (e) {
           this.ctx.logger?.warn?.(`progress start: ${e.message}`)
           progress = null
-          if (typing) await typing()
         }
-      } else if (typing) {
-        await typing()
       }
 
+
       const content = await this.buildUserContent(input, signal)
       chat.agent.followup(createUserMessage({
-        content,
+        content: ensureContentArray(content),
         source: { kind: 'plugin', plugin: PLUGIN, form: 'relay' },
       }))
       const turnTimeoutMs = Number(this.config.agent?.turnTimeoutMs) || 600_000
@@ -1236,7 +1242,8 @@ export class Gateway {
         else return reply('Прервано.')
         return
       }
-      await this.ctx.sessions.flush(chat.agent.session)
+      const sessions = this.ctx.get?.('sessions') || this.ctx.sessions
+      await sessions?.flush?.(chat.agent.session)
       if (progress) try { await progress.remove() } catch {}
       progress = null
       if (typeof react === 'function') react('').catch?.(() => {})
@@ -1353,6 +1360,26 @@ export class Gateway {
     return this.pairing.rejectCode(code)
   }
 
+  async probeTelegram(timeoutMs = 10000) {
+    const adapter = this.getAdapter('telegram')
+    if (!adapter) {
+      return { ok: false, error: 'Telegram adapter not initialized' }
+    }
+    if (typeof adapter.probeHealth === 'function') {
+      return adapter.probeHealth(timeoutMs)
+    }
+    return { ok: false, error: 'probeHealth not implemented on adapter' }
+  }
+
+  getBotInfo() {
+    const adapter = this.getAdapter('telegram')
+    return {
+      botId: adapter?.botId || 0,
+      botUsername: adapter?.botUsername || '',
+      pollingConflict: Boolean(adapter?.pollingConflict),
+    }
+  }
+
   async messengerAskFromAgent(agent, payload, timeoutMs) {
     const sessionId = String(agent?.session?.id || '')
     const key = this.sessionToChat.get(sessionId)
@@ -1372,6 +1399,8 @@ export class Gateway {
       send: (target, payload) => this.messengerSend(target, payload),
       ask: (target, payload, timeoutMs) => this.messengerAsk(target, payload, timeoutMs),
       progress: (target, payload) => this.messengerProgress(target, payload),
+      probeTelegram: (timeoutMs) => this.probeTelegram(timeoutMs),
+      getBotInfo: () => this.getBotInfo(),
     }
   }
 }

package/lib/index.js

@@ -78,7 +78,7 @@ function publicConfig(cfg) {
 }
 
 function registerMessengerRoute(ctx, getGw, path, action) {
-  ctx.effect(() => ctx.webServer.register({
+  ctx.effect(() => (ctx.get?.('webServer') || ctx.webServer).register({
     kind: 'exact', path,
     handler: async (req, res) => {
       if (req.method !== 'POST') return writeJson(res, 405, { ok: false, error: 'POST only' })
@@ -112,6 +112,7 @@ export function apply(ctx, config) {
   let source = () => entry
   let settingsApi
   const turnStarts = new Map()
+  const getWebServer = () => ctx.get?.('webServer') || ctx.webServer
 
   const sync = () => {
     if (gateway) { gateway.stop(); gateway = undefined }
@@ -154,8 +155,9 @@ export function apply(ctx, config) {
     gateway.start().catch((err) => ctx.logger?.warn?.(`dsh-messenger-gateway: ${err.message}`))
   }
 
-  if (ctx.settings?.register) {
-    settingsApi = ctx.settings.register(SETTINGS_NAMESPACE, Config, { base: config || {} })
+  const settings = ctx.get?.('settings') || ctx.settings
+  if (settings?.register) {
+    settingsApi = settings.register(SETTINGS_NAMESPACE, Config, { base: config || {} })
     source = () => resolveConfig(settingsApi.get() ?? config ?? {})
     ctx.effect(() => settingsApi.watch(sync), 'dsh-messenger-gateway: settings')
   }
@@ -165,8 +167,9 @@ export function apply(ctx, config) {
   ctx.effect(() => ctx.provide('messenger', createMessengerService(getGw)), 'dsh-messenger-gateway: messenger service')
 
   // Agent tool: inline buttons in the telegram chat bound to this msgw session
-  if (ctx.tools?.register) {
-    ctx.effect(() => ctx.tools.register(defineTool({
+  const tools = ctx.get?.('tools') || ctx.tools
+  if (tools?.register) {
+    ctx.effect(() => tools.register(defineTool({
       name: 'messenger_ask',
       description:
         'Ask the Telegram user a single or multiple-choice question with inline buttons/checkboxes and wait for their choice. '
@@ -267,11 +270,13 @@ export function apply(ctx, config) {
       .catch((e) => ctx.logger?.warn?.(`notify bridge: ${e.message}`))
   }), 'dsh-messenger-gateway: notify bridge')
 
-  ctx.effect(() => ctx.webServer.register({
+  ctx.effect(() => getWebServer().register({
     kind: 'exact', path: '/dsh-messenger-gateway/status',
     handler: async (req, res) => {
       if (req.method !== 'GET') return writeJson(res, 405, { ok: false, error: 'GET only' })
       const gw = getGw()
+      const botInfo = gw?.getBotInfo?.() || {}
+      const uptimeSec = gw?.stats?.startedAt ? Math.max(0, Math.round((Date.now() - gw.stats.startedAt) / 1000)) : 0
       writeJson(res, 200, {
         ok: true,
         running: Boolean(gw),
@@ -279,15 +284,44 @@ export function apply(ctx, config) {
         activeChats: gw?.messenger.activeChats() || 0,
         ttsEnabled: Boolean(source().tts?.enabled),
         messengerService: 'messenger',
-        home: gateway?.messenger.home?.() || null,
-        homes: gateway?.messenger.homes?.() || [],
+        home: gw?.messenger.home?.() || null,
+        homes: gw?.messenger.homes?.() || [],
         pairingPending: gw?.messenger.pairingPending?.()?.length || 0,
+        botId: botInfo.botId || 0,
+        botUsername: botInfo.botUsername || '',
+        pollingConflict: Boolean(botInfo.pollingConflict),
+        uptimeSec,
+        stats: {
+          sent: gw?.stats?.sent || 0,
+          errors: gw?.stats?.errors || 0,
+          startedAt: gw?.stats?.startedAt || 0,
+        },
         config: publicConfig(source()),
       })
     },
   }), 'dsh-messenger-gateway: status')
 
-  ctx.effect(() => ctx.webServer.register({
+  ctx.effect(() => getWebServer().register({
+    kind: 'exact', path: '/dsh-messenger-gateway/smoke',
+    handler: async (req, res) => {
+      if (req.method !== 'POST') return writeJson(res, 405, { ok: false, error: 'POST only' })
+      if (!isTrustedSettingsRequest(req)) return writeJson(res, 403, { ok: false, error: 'forbidden' })
+      const gw = getGw()
+      if (!gw) return writeJson(res, 503, { ok: false, error: 'gateway not running' })
+      let payload = {}
+      try {
+        const raw = (await readBody(req)).toString('utf8').trim()
+        if (raw) payload = JSON.parse(raw)
+      } catch {
+        return writeJson(res, 400, { ok: false, error: 'invalid json' })
+      }
+      const timeoutMs = Number(payload.timeoutMs) || 10000
+      const result = await gw.probeTelegram(timeoutMs)
+      writeJson(res, result.ok ? 200 : 502, result)
+    },
+  }), 'dsh-messenger-gateway: smoke test')
+
+  ctx.effect(() => getWebServer().register({
     kind: 'exact', path: '/dsh-messenger-gateway/messenger',
     handler: async (req, res) => {
       if (req.method !== 'GET') return writeJson(res, 405, { ok: false, error: 'GET only' })
@@ -295,7 +329,7 @@ export function apply(ctx, config) {
     },
   }), 'dsh-messenger-gateway: messenger schema')
 
-  ctx.effect(() => ctx.webServer.register({
+  ctx.effect(() => getWebServer().register({
     kind: 'exact', path: '/dsh-messenger-gateway/events',
     handler: async (req, res) => {
       if (req.method !== 'POST') return writeJson(res, 405, { ok: false, error: 'POST only' })
@@ -334,7 +368,7 @@ export function apply(ctx, config) {
     },
   }), 'dsh-messenger-gateway: webhook events')
 
-  ctx.effect(() => ctx.webServer.register({
+  ctx.effect(() => getWebServer().register({
     kind: 'exact', path: '/dsh-messenger-gateway/config',
     handler: async (req, res) => {
       if (req.method === 'GET') return writeJson(res, 200, { ok: true, config: publicConfig(source()) })
@@ -370,7 +404,7 @@ export function apply(ctx, config) {
     },
   }), 'dsh-messenger-gateway: config')
 
-  ctx.effect(() => ctx.webServer.register({
+  ctx.effect(() => getWebServer().register({
     kind: 'exact', path: '/dsh-messenger-gateway/pairing',
     handler: async (req, res) => {
       if (req.method !== 'GET') return writeJson(res, 405, { ok: false, error: 'GET only' })
@@ -385,7 +419,7 @@ export function apply(ctx, config) {
     },
   }), 'dsh-messenger-gateway: pairing list')
 
-  ctx.effect(() => ctx.webServer.register({
+  ctx.effect(() => getWebServer().register({
     kind: 'exact', path: '/dsh-messenger-gateway/pairing/approve',
     handler: async (req, res) => {
       if (req.method !== 'POST') return writeJson(res, 405, { ok: false, error: 'POST only' })
@@ -399,7 +433,7 @@ export function apply(ctx, config) {
     },
   }), 'dsh-messenger-gateway: pairing approve')
 
-  ctx.effect(() => ctx.webServer.register({
+  ctx.effect(() => getWebServer().register({
     kind: 'exact', path: '/dsh-messenger-gateway/pairing/reject',
     handler: async (req, res) => {
       if (req.method !== 'POST') return writeJson(res, 405, { ok: false, error: 'POST only' })
@@ -418,7 +452,7 @@ export function apply(ctx, config) {
     return p || '/dsh-messenger-gateway/telegram/webhook'
   }
 
-  ctx.effect(() => ctx.webServer.register({
+  ctx.effect(() => getWebServer().register({
     kind: 'exact', path: webhookPath(),
     handler: async (req, res) => {
       if (req.method !== 'POST') return writeJson(res, 405, { ok: false, error: 'POST only' })

package/lib/models.js

@@ -7,14 +7,15 @@ export async function listModelCatalog(ctx, fallback = {}) {
   }
 
   // 1. Try ctx.llm if available
-  if (ctx?.llm?.listProviders) {
+  const llm = ctx?.get?.('llm') || ctx?.llm
+  if (llm?.listProviders) {
     try {
-      const providers = await ctx.llm.listProviders()
+      const providers = await llm.listProviders()
       for (const p of providers || []) {
         const pId = p.id || p
         result.providers.push({ id: pId, name: p.name || pId })
         try {
-          const models = await ctx.llm.listModels(pId)
+          const models = await llm.listModels(pId)
           result.modelsByProvider.set(
             pId,
             (models || []).map((m) => ({ id: m.id || m, name: m.name || m.id || m }))

package/lib/outbound.js

@@ -62,7 +62,8 @@ export function fileNameForRef(ref) {
 }
 
 export async function readAttachmentBytes(ctx, ref) {
-  const stored = await ctx.attachments.readImage(ref)
+  const attachments = ctx.get?.('attachments') || ctx.attachments
+  const stored = await attachments.readImage(ref)
   return {
     bytes: stored.data,
     mime: ref.mediaType || stored.ref?.mediaType || 'image/png',

package/lib/photos.js

@@ -12,7 +12,8 @@ export async function attachInboundPhoto(ctx, att, opts = {}) {
   if (maxBytes > 0 && bytes.length > maxBytes) {
     throw new Error(`image too large (${bytes.length} bytes, max ${maxBytes})`)
   }
-  const ref = await ctx.attachments.saveImage({
+  const attachments = ctx.get?.('attachments') || ctx.attachments
+  const ref = await attachments.saveImage({
     data: bytes,
     mediaType: att.mime || 'image/jpeg',
     ...(att.name ? { name: att.name } : {}),

package/lib/session-ops.js

@@ -87,9 +87,19 @@ export function rewindSession(session, turnsCount = 1) {
     }
   }
 
-  const removed = messages.splice(messages.length - toRemove, toRemove)
+  const keepCount = Math.max(0, messages.length - toRemove)
+  const kept = messages.slice(0, keepCount).map(m => {
+    // Only wrap non-string invalid/nullish/object content to array
+    if (m && m.content && typeof m.content === 'object' && !Array.isArray(m.content) && m.content.type) {
+      return { ...m, content: [m.content] }
+    }
+    return m
+  })
+  const removedCount = messages.length - keepCount
+  session.messages = kept
+
   return {
-    removed: removed.length,
-    remaining: messages.length,
+    removed: removedCount,
+    remaining: session.messages.length,
   }
-}
+}

package/lib/stream.js

@@ -1,101 +1,114 @@
-/** 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 parseRetryAfter(err) {
-  if (!err) return 0
-  const msg = err.message || String(err)
-  const match = /retry after (\d+)/i.exec(msg)
-  if (match) return parseInt(match[1], 10) * 1000
-  return 0
-}
-
-export function createEditScheduler(editFn, intervalMs = 1200) {
-  let pending = null
-  let timer = null
-  let lastSent = ''
-  let inFlight = Promise.resolve()
-  let retryDelayMs = 0
-
-  const flush = () => {
-    timer = null
-    if (pending === null || pending === lastSent) return
-    const text = pending
-    inFlight = inFlight.then(async () => {
-      try {
-        if (retryDelayMs > 0) {
-          const delay = retryDelayMs
-          retryDelayMs = 0
-          await new Promise((r) => setTimeout(r, delay))
-        }
-        await editFn(text)
-        lastSent = text
-      } catch (err) {
-        const retry = parseRetryAfter(err)
-        if (retry > 0) {
-          retryDelayMs = retry
-          // Re-schedule flush with retry delay
-          if (!timer) {
-            timer = setTimeout(flush, retry + 100)
-            timer.unref?.()
-          }
-        }
-      }
-    })
-  }
-
-  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
-      // If there's still a pending difference (e.g. rate limit delay happened), wait and retry
-      if (pending !== null && pending !== lastSent) {
-        if (retryDelayMs > 0) {
-          await new Promise((r) => setTimeout(r, retryDelayMs + 50))
-          retryDelayMs = 0
-        }
-        try {
-          await editFn(pending)
-          lastSent = pending
-        } catch {}
-      }
-    },
-  }
-}
-
-export function startTypingHeartbeat(typingFn, intervalMs = 4000) {
-  if (typeof typingFn !== 'function') return () => {}
-  typingFn().catch?.(() => {})
-  const timer = setInterval(() => { typingFn().catch?.(() => {}) }, intervalMs)
-  timer.unref?.()
-  return () => clearInterval(timer)
-}
+/** 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 parseRetryAfter(err) {
+  if (!err) return 0
+  const msg = err.message || String(err)
+  const match = /retry after (\d+)/i.exec(msg)
+  if (match) return parseInt(match[1], 10) * 1000
+  return 0
+}
+
+export function createEditScheduler(editFn, intervalMs = 1200, firstChunkDelayMs = 250) {
+  let pending = null
+  let timer = null
+  let lastSent = ''
+  let inFlight = Promise.resolve()
+  let retryDelayMs = 0
+
+  const flush = () => {
+    timer = null
+    if (pending === null || pending === lastSent) return
+    const text = pending
+    inFlight = inFlight.then(async () => {
+      try {
+        if (retryDelayMs > 0) {
+          const delay = retryDelayMs
+          retryDelayMs = 0
+          await new Promise((r) => setTimeout(r, delay))
+        }
+        await editFn(text)
+        lastSent = text
+      } catch (err) {
+        const retry = parseRetryAfter(err)
+        if (retry > 0) {
+          retryDelayMs = retry
+          // Re-schedule flush with retry delay
+          if (!timer) {
+            timer = setTimeout(flush, retry + 100)
+            timer.unref?.()
+          }
+        }
+      }
+    })
+  }
+
+  return {
+    push(text) {
+      pending = text
+      if (timer) return
+      // Fast first chunk: when lastSent is empty, dispatch quickly so user sees immediate response.
+      // Subsequent edits throttle to intervalMs to respect Telegram rate limits.
+      const delay = !lastSent ? Math.min(firstChunkDelayMs, intervalMs) : Math.max(200, intervalMs)
+      timer = setTimeout(flush, delay)
+      timer.unref?.()
+    },
+    async flush() {
+      if (timer) { clearTimeout(timer); timer = null }
+      flush()
+      await inFlight
+      // If there's still a pending difference (e.g. rate limit delay happened), wait and retry
+      if (pending !== null && pending !== lastSent) {
+        if (retryDelayMs > 0) {
+          await new Promise((r) => setTimeout(r, retryDelayMs + 50))
+          retryDelayMs = 0
+        }
+        try {
+          await editFn(pending)
+          lastSent = pending
+        } catch {}
+      }
+    },
+  }
+}
+
+export function startTypingHeartbeat(typingFn, intervalMs = 4000) {
+  if (typeof typingFn !== 'function') return () => {}
+  let active = true
+  const safeInvoke = () => {
+    if (!active) return
+    try {
+      typingFn()?.catch?.(() => {})
+    } catch {}
+  }
+  safeInvoke()
+  const timer = setInterval(safeInvoke, intervalMs)
+  timer.unref?.()
+  return () => {
+    active = false
+    clearInterval(timer)
+  }
+}

package/lib/telegram-errors.js

@@ -39,3 +39,13 @@ 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)
 }
+
+/**
+ * Calculates exponential backoff with max cap for polling retries.
+ * errorCount is 1-indexed.
+ */
+export function computePollBackoffMs(baseIntervalMs, errorCount, maxDelayMs = 30_000) {
+  const count = Math.max(1, Math.min(10, Number(errorCount) || 1))
+  const base = Math.max(100, Number(baseIntervalMs) || 500)
+  return Math.min(maxDelayMs, base * Math.pow(2, count - 1))
+}