@goodandready/dsh-messenger-gateway 0.3.21 → 0.4.0

package/lib/locales/zh.js

@@ -1,114 +1,123 @@
-// Canonical Chinese (zh) locale dictionary
-export const zh = {
-  // Command descriptions
-  'cmd.help': '显示帮助信息',
-  'cmd.new': '开始新会话',
-  'cmd.stop': '中断当前回答',
-  'cmd.model': '交互式模型选择器',
-  'cmd.role': '切换智能体角色/人设',
-  'cmd.rewind': '回退最近N轮对话',
-  'cmd.fork': '将会话派生到新分支',
-  'cmd.export': '导出历史记录为Markdown',
-  'cmd.skills': '列出当前可用工具与技能',
-  'cmd.files': '工作区文件浏览器',
-  'cmd.get': '从工作区下载文件',
-  'cmd.remind': '设置提醒或定时器',
-  'cmd.status': '查看网关与模型状态',
-  'cmd.top': '查看系统资源（内存、运行时间）',
-  'cmd.keyboard': '开关快捷操作键盘',
-  'cmd.voice': '设置语音回复模式',
-  'cmd.tts': '在此聊天开关语音朗读',
-  'cmd.mute': '在此聊天静音通知',
-  'cmd.unmute': '在此聊天恢复通知',
-  'cmd.whoami': '显示你的用户ID',
-  'cmd.pair': '批准配对申请码',
-  'cmd.sethome': '设置主通知频道',
-  'cmd.setalert': '设置告警通知目标',
-  'cmd.bind': '绑定预设或人设到论坛话题',
-  'cmd.preset': '查看或切换智能体预设',
-  'cmd.cron': '配置定时周期性任务报告',
-
-  // Bot replies & statuses
-  'msg.start': '网关已连接。请向智能体发送消息。发送 /help 查看命令。',
-  'msg.steer_added': '↪️ 已追加到当前回答',
-  'msg.turn_stopped': '回答已中断。',
-  'msg.no_active_session': '未找到活跃会话。',
-  'msg.unknown_command': '未知命令 {cmd}。发送 /help',
-  'msg.not_allowed': '访问受限。请联系管理员将您的ID加入白名单。',
-  'msg.pairing_requested': '需要访问配对。\n您的ID: {userId}\n配对码: {code}\n\n管理员请向机器人发送：\n/pair {code}',
-  'msg.pairing_rate_limit': '配对码已发出，请稍候或联系管理员。',
-  'msg.pairing_approved': '✅ 用户 {userId} 已成功授权！',
-  'msg.pairing_invalid': '配对码无效或已过期。',
-  'msg.muted_on': '此聊天通知：已静音 (/unmute)',
-  'msg.muted_off': '此聊天通知：已开启',
-  'msg.no_response': '(无回复)',
-  'msg.agent_error': '智能体错误: {code}: {message}',
-  'msg.exception': '内部处理异常: {message}',
-
-  // Photo & media
-  'photo.received_one': '已收到图片。请输入您的问题 — 例如：“图片中有什么？”',
-  'photo.received_many': '已收到 {count} 个附件。请输入您的问题。',
-  'photo.hint_photo': '[附加图片]',
-  'photo.hint_photos': '[附加了 {count} 张图片]',
-  'doc.hint': '[附加文件: {name}]',
-
-  // Interactive buttons & ask
-  'ask.confirm_title': '⚠️ 需要授权确认\n工具: <code>{tool}</code>{reason}',
-  'ask.allow_once': '✅ 允许单次',
-  'ask.allow_session': '🛡️ 本会话始终允许',
-  'ask.deny': '❌ 拒绝',
-  'ask.chose': '已选择: {choice}',
-  'ask.done': '完成',
-  'ask.cancel': '取消',
-  'ask.canceled': '已取消',
-  'ask.expired': '交互已超时，请重新发起。',
-  'ask.other_chat': '该按钮属于其他聊天',
-
-  // Model selector
-  'model.title': '🤖 <b>选择服务商：</b>',
-  'model.current': '当前: <code>{current}</code>',
-  'model.provider_models': '🤖 <b>服务商:</b> <code>{provider}</code>\n请选择模型 (第 {page}/{total} 页):',
-  'model.no_models': '该服务商暂无可用的模型',
-  'model.switched': '✅ 模型已成功切换至: <b>{provider}/{model}</b>',
-
-  // Personas & Presets
-  'persona.title': '🎭 <b>可用角色与人设:</b>',
-  'persona.usage': '切换角色: <code>/role coder</code> (或 /role reset)',
-  'persona.reset': '🎭 角色已重置为默认 (Default)。',
-  'persona.switched': '🎭 角色已切换为: {icon} <b>{name}</b>\n{description}',
-  'persona.unknown': '未知角色 "{target}"。列表请见: /role list',
-  'persona.bound_topic': '📌 话题已绑定到{kind}: <b>{name}</b>',
-
-  // Builtin persona descriptions
-  'persona.default.name': '默认',
-  'persona.default.desc': '通用智能助手，回答平衡清晰',
-  'persona.coder.name': '开发者',
-  'persona.coder.desc': '资深全栈工程师，直奔代码核心',
-  'persona.writer.name': '文案编辑',
-  'persona.writer.desc': '专业编辑润色，文笔优美流畅',
-  'persona.analyst.name': '分析师',
-  'persona.analyst.desc': '结构化逻辑拆解，深度数据分析',
-  'persona.concise.name': '极简',
-  'persona.concise.desc': '极速短促回复，1-2句话答复',
-
-  // File explorer & export
-  'files.title': '📁 <b>工作区路径:</b> <code>{path}</code>\n文件总计: {count}\n\n',
-  'files.empty': '📁 目录为空: <code>{path}</code>',
-  'files.download_hint': '\n下载文件命令: <code>/get &lt;path&gt;</code>',
-  'files.not_found': '未找到文件: {path}',
-  'export.title': '📄 对话导出 ({count} 条消息):',
-  'export.empty': '会话为空，无消息可导出。',
-
-  // Reminders & Cron
-  'remind.scheduled': '⏰ 提醒已设置在 {time} ({duration} 后):\n{text}',
-  'remind.invalid': '时间格式错误。例如: /remind 10m 检查构建',
-  'remind.prefix': '⏰ <b>[提醒]</b>\n{text}',
-  'cron.scheduled': '⏱️ 定时任务已配置: <code>{id}</code>\n周期表达式: <code>{schedule}</code>\n指令: {prompt}',
-  'cron.list_title': '⏱️ <b>当前定时任务列表:</b>\n',
-  'cron.none': '暂无活动的定时任务。',
-  'cron.cancelled': '✅ 定时任务已取消: <code>{id}</code>',
-  'cron.prefix': '⏱️ <b>[定时报告: {id}]</b>\n',
-
-  // Mirror & Forum
-  'mirror.created': '🪞 <b>[DSH 会话镜像]</b>\n会话ID: <code>{sessionId}</code>\n标题: <b>{title}</b>\n此话题消息与 DSH 双向同步。',
-}
+// Canonical Chinese (zh) locale dictionary
+export const zh = {
+  // Command descriptions
+  'cmd.help': '显示帮助信息',
+  'cmd.new': '开始新会话',
+  'cmd.stop': '中断当前回答',
+  'cmd.model': '交互式模型选择器',
+  'cmd.role': '切换智能体角色/人设',
+  'cmd.rewind': '回退最近N轮对话',
+  'cmd.fork': '将会话派生到新分支',
+  'cmd.export': '导出历史记录为Markdown',
+  'cmd.skills': '列出当前可用工具与技能',
+  'cmd.files': '工作区文件浏览器',
+  'cmd.get': '从工作区下载文件',
+  'cmd.remind': '设置提醒或定时器',
+  'cmd.status': '查看网关与模型状态',
+  'cmd.top': '查看系统资源（内存、运行时间）',
+  'cmd.keyboard': '开关快捷操作键盘',
+  'cmd.voice': '设置语音回复模式',
+  'cmd.tts': '在此聊天开关语音朗读',
+  'cmd.mute': '在此聊天静音通知',
+  'cmd.unmute': '在此聊天恢复通知',
+  'cmd.whoami': '显示你的用户ID',
+  'cmd.pair': '批准配对申请码',
+  'cmd.sethome': '设置主通知频道',
+  'cmd.setalert': '设置告警通知目标',
+  'cmd.bind': '绑定预设或人设到论坛话题',
+  'cmd.preset': '查看或切换智能体预设',
+  'cmd.cron': '配置定时周期性任务报告',
+
+  // Bot replies & statuses
+  'msg.start': '网关已连接。请向智能体发送消息。发送 /help 查看命令。',
+  'msg.steer_added': '↪️ 已追加到当前回答',
+  'msg.turn_stopped': '回答已中断。',
+  'msg.no_active_session': '未找到活跃会话。',
+  'msg.unknown_command': '未知命令 {cmd}。发送 /help',
+  'msg.not_allowed': '访问受限。请联系管理员将您的ID加入白名单。',
+  'msg.pairing_requested': '需要访问配对。\n您的ID: {userId}\n配对码: {code}\n\n管理员请向机器人发送：\n/pair {code}',
+  'msg.pairing_rate_limit': '配对码已发出，请稍候或联系管理员。',
+  'msg.pairing_approved': '✅ 用户 {userId} 已成功授权！',
+  'msg.pairing_invalid': '配对码无效或已过期。',
+  'msg.muted_on': '此聊天通知：已静音 (/unmute)',
+  'msg.muted_off': '此聊天通知：已开启',
+  'msg.no_response': '(无回复)',
+  'msg.agent_error': '智能体错误: {code}: {message}',
+  'msg.exception': '内部处理异常: {message}',
+
+  // Photo & media
+  'photo.received_one': '已收到图片。请输入您的问题 — 例如：“图片中有什么？”',
+  'photo.received_many': '已收到 {count} 个附件。请输入您的问题。',
+  'photo.hint_photo': '[附加图片]',
+  'photo.hint_photos': '[附加了 {count} 张图片]',
+  'doc.hint': '[附加文件: {name}]',
+
+  // Interactive buttons & ask
+  'ask.confirm_title': '⚠️ 需要授权确认\n工具: <code>{tool}</code>{reason}',
+  'ask.allow_once': '✅ 允许单次',
+  'ask.allow_session': '🛡️ 本会话始终允许',
+  'ask.deny': '❌ 拒绝',
+  'ask.chose': '已选择: {choice}',
+  'ask.done': '完成',
+  'ask.cancel': '取消',
+  'ask.canceled': '已取消',
+  'ask.expired': '交互已超时，请重新发起。',
+  'ask.other_chat': '该按钮属于其他聊天',
+
+  // Model selector
+  'model.title': '🤖 <b>选择服务商：</b>',
+  'model.current': '当前: <code>{current}</code>',
+  'model.provider_models': '🤖 <b>服务商:</b> <code>{provider}</code>\n请选择模型 (第 {page}/{total} 页):',
+  'model.no_models': '该服务商暂无可用的模型',
+  'model.switched': '✅ 模型已成功切换至: <b>{provider}/{model}</b>',
+
+  // Personas & Presets
+  'persona.title': '🎭 <b>可用角色与人设:</b>',
+  'persona.usage': '切换角色: <code>/role coder</code> (或 /role reset)',
+  'persona.reset': '🎭 角色已重置为默认 (Default)。',
+  'persona.switched': '🎭 角色已切换为: {icon} <b>{name}</b>\n{description}',
+  'persona.unknown': '未知角色 "{target}"。列表请见: /role list',
+  'persona.bound_topic': '📌 话题已绑定到{kind}: <b>{name}</b>',
+
+  // Builtin persona descriptions
+  'persona.default.name': '默认',
+  'persona.default.desc': '通用智能助手，回答平衡清晰',
+  'persona.coder.name': '开发者',
+  'persona.coder.desc': '资深全栈工程师，直奔代码核心',
+  'persona.writer.name': '文案编辑',
+  'persona.writer.desc': '专业编辑润色，文笔优美流畅',
+  'persona.analyst.name': '分析师',
+  'persona.analyst.desc': '结构化逻辑拆解，深度数据分析',
+  'persona.concise.name': '极简',
+  'persona.concise.desc': '极速短促回复，1-2句话答复',
+
+  // File explorer & export
+  'files.title': '📁 <b>工作区路径:</b> <code>{path}</code>\n文件总计: {count}\n\n',
+  'files.empty': '📁 目录为空: <code>{path}</code>',
+  'files.download_hint': '\n下载文件命令: <code>/get &lt;path&gt;</code>',
+  'files.not_found': '未找到文件: {path}',
+  'export.title': '📄 对话导出 ({count} 条消息):',
+  'export.empty': '会话为空，无消息可导出。',
+
+  // Reminders & Cron
+  'remind.scheduled': '⏰ 提醒已设置在 {time} ({duration} 后):\n{text}',
+  'remind.invalid': '时间格式错误。例如: /remind 10m 检查构建',
+  'remind.prefix': '⏰ <b>[提醒]</b>\n{text}',
+  'cron.scheduled': '⏱️ 定时任务已配置: <code>{id}</code>\n周期表达式: <code>{schedule}</code>\n指令: {prompt}',
+  'cron.list_title': '⏱️ <b>当前定时任务列表:</b>\n',
+  'cron.none': '暂无活动的定时任务。',
+  'cron.cancelled': '✅ 定时任务已取消: <code>{id}</code>',
+  'cron.prefix': '⏱️ <b>[定时报告: {id}]</b>\n',
+
+  // Mirror & Forum
+  'mirror.created': '🪞 <b>[DSH 会话镜像]</b>\n会话ID: <code>{sessionId}</code>\n标题: <b>{title}</b>\n此话题消息与 DSH 双向同步。',
+  // Updates & Maintenance
+  'cmd.update': '检查或安装插件更新',
+  'update.installing': '⏳ <b>正在更新插件…</b>\n正在后台运行 DSH 软件包安装…',
+  'update.already_latest': '✅ 插件已是最新版本 (<code>v{version}</code>)。',
+  'update.success': '🎉 <b>已成功更新至 v{version}！</b>\n请重启服务以使更改生效：<code>sudo systemctl restart dsh-web.service</code>',
+  'update.failed': '❌ <b>更新失败：</b> {error}',
+  'update.available': '📦 <b>发现新版本！</b>\n当前版本：<code>v{current}</code>\n最新版本：<code>v{latest}</code>\n\n发送 <code>/update now</code> 立即安装。',
+  'update.current': '✅ <b>Messenger Gateway 已是最新版本。</b>\n当前版本：<code>v{version}</code>。',
+  'update.check_failed': '⚠️ 检查更新失败：{error}',
+}

package/lib/media.js

@@ -40,14 +40,6 @@ export function classifyDocument(ext, mime) {
   return 'unsupported'
 }
 
-export function mediaKindOf(path) {
-  const ext = extname(path).toLowerCase()
-  if (IMAGE_EXT_TO_MIME[ext]) return 'photo'
-  if (['.ogg', '.opus', '.oga'].includes(ext)) return 'voice'
-  if (['.mp3', '.m4a', '.wav', '.flac'].includes(ext)) return 'audio'
-  return 'document'
-}
-
 export function safeName(name) {
   return String(name || 'file').replace(/[^\w.\- ]/g, '_').slice(0, 120) || 'file'
 }
@@ -65,4 +57,4 @@ export function cacheName(prefix, ext, name) {
   return display ? `${base}-${display}${ext || ''}` : `${base}${ext || ''}`
 }
 
-export { basename }
+export { basename }

package/lib/models.js

@@ -20,11 +20,14 @@ export async function listModelCatalog(ctx, fallback = {}) {
             pId,
             (models || []).map((m) => ({ id: m.id || m, name: m.name || m.id || m }))
           )
-        } catch {
+        } catch (err) {
+          /* safe fallback to empty list when provider cannot list models */
           result.modelsByProvider.set(pId, [])
         }
       }
-    } catch {}
+    } catch (err) {
+      /* safe fallback when ctx.llm.listProviders is unavailable or throws */
+    }
   }
 
   // 2. If no providers from ctx.llm, check settings / fallback
@@ -117,4 +120,4 @@ export function buildModelsKeyboard(providerId, models, currentModel, page = 0,
   rows.push([{ text: '🔙 Back to providers', callback_data: 'mdl:back' }])
 
   return { inline_keyboard: rows, page: curPage, totalPages }
-}
+}

package/lib/outbound.js

@@ -110,4 +110,4 @@ export async function buildOutboundFiles(ctx, baseUrl, collector, opts = {}) {
     }
   }
   return files
-}
+}

package/lib/pairing.js

@@ -19,25 +19,29 @@ function writeJsonAtomicSync(filePath, data) {
     writeFileSync(tmpPath, JSON.stringify(data, null, 2), 'utf8')
     renameSync(tmpPath, filePath)
   } catch (err) {
-    try { unlinkSync(tmpPath) } catch {}
+    try { unlinkSync(tmpPath) } catch { /* safe best-effort temp file cleanup */ }
     throw err
   }
 }
 
-export function createPairingStore(filePath) {
+export function createPairingStore(filePath, { logger } = {}) {
   const state = { pending: {}, /** @type {number[]} */ approved: [] }
   if (filePath && existsSync(filePath)) {
     try {
       const raw = JSON.parse(readFileSync(filePath, 'utf8'))
       if (Array.isArray(raw.approved)) state.approved = raw.approved.map(Number).filter(Number.isFinite)
       if (raw.pending && typeof raw.pending === 'object') state.pending = raw.pending
-    } catch {}
+    } catch (err) {
+      logger?.warn?.('[dsh-messenger-gateway] pairing store read error:', err?.message || err)
+    }
   }
   const persist = () => {
     if (!filePath) return
     try {
       writeJsonAtomicSync(filePath, { approved: state.approved, pending: state.pending })
-    } catch {}
+    } catch (err) {
+      logger?.warn?.('[dsh-messenger-gateway] pairing store persist error:', err?.message || err)
+    }
   }
   const prune = () => {
     const now = Date.now()

package/lib/personas.js

@@ -70,7 +70,7 @@ export function listPersonas() {
   return Object.values(BUILTIN_PERSONAS)
 }
 
-export function createPersonaStore(filePath) {
+export function createPersonaStore(filePath, { logger } = {}) {
   let cache = { personas: {}, presets: {} }
   try {
     const raw = JSON.parse(readFileSync(filePath, 'utf8'))
@@ -81,13 +81,17 @@ export function createPersonaStore(filePath) {
         cache = { personas: raw, presets: {} }
       }
     }
-  } catch {}
+  } catch (err) {
+    if (err?.code !== 'ENOENT') logger?.warn?.('[dsh-messenger-gateway] personas load error:', err?.message || err)
+  }
 
   function save() {
     try {
       mkdirSync(dirname(filePath), { recursive: true })
       writeFileSync(filePath, JSON.stringify(cache, null, 2), 'utf8')
-    } catch {}
+    } catch (err) {
+      logger?.warn?.('[dsh-messenger-gateway] personas save error:', err?.message || err)
+    }
   }
 
   function makeKey(chatId, threadId = 0) {
@@ -148,4 +152,4 @@ export function createPersonaStore(filePath) {
       return { ...cache }
     },
   }
-}
+}

package/lib/photos.js

@@ -28,4 +28,4 @@ export function photoOnlyHint(attachments, userText) {
   if (!photos.length) return ''
   if (photos.length === 1) return '[User attached a photo]'
   return `[User attached ${photos.length} photos]`
-}
+}

package/lib/scheduler.js

@@ -33,7 +33,8 @@ export function formatRemaining(ms, locale = 'en') {
   return remMin ? `${hr}h ${remMin}m` : `${hr}h`
 }
 
-export function createScheduler(filePath, onDue) {
+export function createScheduler(filePath, onDue, options = {}) {
+  const logger = options?.logger || console
   let tasks = []
   let loaded = false
   let timer = null
@@ -42,7 +43,10 @@ export function createScheduler(filePath, onDue) {
     try {
       const raw = await readFile(filePath, 'utf8')
       tasks = JSON.parse(raw)
-    } catch {
+    } catch (err) {
+      if (err?.code !== 'ENOENT') {
+        logger?.debug?.('[dsh-messenger-gateway] scheduler load error:', err?.message || err)
+      }
       tasks = []
     }
     loaded = true
@@ -60,7 +64,9 @@ export function createScheduler(filePath, onDue) {
         return (now - finishTime) < RETENTION_MS
       })
       await writeJsonAtomic(filePath, tasks)
-    } catch {}
+    } catch (err) {
+      logger?.warn?.('[dsh-messenger-gateway] scheduler save failed:', err?.message || err)
+    }
   }
 
   async function checkDue() {
@@ -77,7 +83,11 @@ export function createScheduler(filePath, onDue) {
         task.firedAt = now
       }
       if (typeof onDue === 'function') {
-        try { await onDue(task) } catch {}
+        try {
+          await onDue(task)
+        } catch (err) {
+          logger?.warn?.('[dsh-messenger-gateway] scheduler task execution failed:', err?.message || err)
+        }
       }
     }
 

package/lib/stream.js

@@ -1,116 +1,116 @@
-/** 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, locale = 'en') {
-  if (!toolName) {
-    return String(locale || '').toLowerCase().startsWith('zh') ? '⏳ 思考中…' : '⏳ Thinking…'
-  }
-  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)
-  }
+/** 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, locale = 'en') {
+  if (!toolName) {
+    return String(locale || '').toLowerCase().startsWith('zh') ? '⏳ 思考中…' : '⏳ Thinking…'
+  }
+  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 { /* safe best-effort final stream update delivery */ }
+      }
+    },
+  }
+}
+
+export function startTypingHeartbeat(typingFn, intervalMs = 4000) {
+  if (typeof typingFn !== 'function') return () => {}
+  let active = true
+  const safeInvoke = () => {
+    if (!active) return
+    try {
+      typingFn()?.catch?.(() => { /* safe best-effort typing indicator */ })
+    } catch { /* safe best-effort typing indicator */ }
+  }
+  safeInvoke()
+  const timer = setInterval(safeInvoke, intervalMs)
+  timer.unref?.()
+  return () => {
+    active = false
+    clearInterval(timer)
+  }
 }