@goodandready/dsh-messenger-gateway 0.4.26 → 0.4.27

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/commands.js CHANGED
@@ -27,6 +27,8 @@ export const DEFAULT_TELEGRAM_COMMANDS = [
27
27
  { command: 'project', description: 'Bind or show topic workspace: /project' },
28
28
  { command: 'memory', description: 'User memory facts: /memory [add <fact>]' },
29
29
  { command: 'forget', description: 'Forget user memory: /forget <id|all>' },
30
+ { command: 'outbox', description: 'Outbox queue & DLQ: /outbox [retry|clear]' },
31
+ { command: 'cost', description: 'Session token usage and estimated cost' },
30
32
  { command: 'cwd', description: 'Show working directory: /cwd' },
31
33
  { command: 'files', description: 'Workspace file explorer: /files [dir]' },
32
34
  { command: 'get', description: 'Download file to messenger: /get <path>' },
@@ -110,6 +112,8 @@ export const HELP_TEXT = [
110
112
  '• /project — topic workspace binding (/project bind <path>)',
111
113
  '• /memory — show remembered facts about you (/memory add <fact>)',
112
114
  '• /forget <id|all> — delete stored user facts',
115
+ '• /outbox — transactional queue & DLQ (/outbox [retry|clear])',
116
+ '• /cost — session token usage, breakdown & estimated cost',
113
117
  '• /cwd — show current working directory',
114
118
  '• /files [dir] — workspace file explorer',
115
119
  '• /get <path> — download file from workspace',
package/lib/config.js CHANGED
@@ -58,6 +58,8 @@ export const PluginConfig = z.object({
58
58
  .description('mirror: TTS when inbound was voice; always/off override (per-user /voice wins)'),
59
59
  quickActions: z.boolean().default(false).description('Show quick actions keyboard in Telegram (/new, /stop, /voice, /status)'),
60
60
  artifactPreviews: z.boolean().default(true).description('Render diagrams and formatted tables as previews'),
61
+ costFooter: z.boolean().default(false).description('Append compact execution & cost footer to bot replies (e.g. ⏱️ 2.4s · 1.8k tokens · deepseek-chat)'),
62
+ budgetAlertThresholdUsd: z.number().default(0).description('Session budget warning threshold in USD (0 = disabled)'),
61
63
  notifyBridge: z.object({
62
64
  enabled: z.boolean().default(false),
63
65
  events: z.array(z.string()).default(['task_done', 'error']),
@@ -0,0 +1,228 @@
1
+ /**
2
+ * Token usage and cost tracker in messenger sessions (dsh-cost-meter bridge, #156).
3
+ *
4
+ * Provides:
5
+ * - Accurate token extraction from turn events and DSH session projections.
6
+ * - Model cost estimation using standard rate cards and dsh-cost-meter tariffs.
7
+ * - Compact response footer (e.g. ⏱️ 2.4s · 1.8k tokens (~$0.004) · deepseek-chat).
8
+ * - Detailed `/cost` command with session breakdown and daily budget tracking.
9
+ * - Budget threshold alerts when nearing session limits.
10
+ */
11
+
12
+ import { escapeHtml } from './telegram-format.js'
13
+
14
+ export const DEFAULT_MODEL_RATES = {
15
+ 'deepseek-chat': { input: 0.44, output: 1.32, cacheRead: 0.014, cacheWrite: 0.44 },
16
+ 'deepseek-v3': { input: 0.44, output: 1.32, cacheRead: 0.014, cacheWrite: 0.44 },
17
+ 'deepseek-reasoner': { input: 1.32, output: 3.96, cacheRead: 0.044, cacheWrite: 1.32 },
18
+ 'deepseek-r1': { input: 1.32, output: 3.96, cacheRead: 0.044, cacheWrite: 1.32 },
19
+ 'gpt-4o': { input: 2.50, output: 10.00, cacheRead: 1.25, cacheWrite: 2.50 },
20
+ 'gpt-4o-mini': { input: 0.15, output: 0.60, cacheRead: 0.075, cacheWrite: 0.15 },
21
+ 'claude-3-5-sonnet': { input: 3.00, output: 15.00, cacheRead: 0.30, cacheWrite: 3.75 },
22
+ 'fallback': { input: 0.50, output: 1.50, cacheRead: 0.05, cacheWrite: 0.50 },
23
+ }
24
+
25
+ export function resolveModelRates(modelId) {
26
+ if (!modelId || typeof modelId !== 'string') return DEFAULT_MODEL_RATES.fallback
27
+ const clean = modelId.toLowerCase().split('/').pop()
28
+ for (const [key, rates] of Object.entries(DEFAULT_MODEL_RATES)) {
29
+ if (clean.includes(key)) return rates
30
+ }
31
+ return DEFAULT_MODEL_RATES.fallback
32
+ }
33
+
34
+ export function normalizeUsage(rawUsage) {
35
+ if (!rawUsage || typeof rawUsage !== 'object') {
36
+ return {
37
+ inputTokens: 0,
38
+ outputTokens: 0,
39
+ cacheReadTokens: 0,
40
+ cacheWriteTokens: 0,
41
+ totalTokens: 0,
42
+ }
43
+ }
44
+
45
+ const inputTokens = Number(rawUsage.inputTokens || rawUsage.prompt_tokens || rawUsage.promptTokens || rawUsage.input || 0)
46
+ const outputTokens = Number(rawUsage.outputTokens || rawUsage.completion_tokens || rawUsage.completionTokens || rawUsage.output || 0)
47
+ const cacheReadTokens = Number(rawUsage.cacheReadTokens || rawUsage.cache_read_tokens || rawUsage.cached_tokens || 0)
48
+ const cacheWriteTokens = Number(rawUsage.cacheWriteTokens || rawUsage.cache_creation_input_tokens || 0)
49
+ const totalTokens = Number(rawUsage.totalTokens || rawUsage.total_tokens || (inputTokens + outputTokens + cacheReadTokens + cacheWriteTokens))
50
+
51
+ return {
52
+ inputTokens,
53
+ outputTokens,
54
+ cacheReadTokens,
55
+ cacheWriteTokens,
56
+ totalTokens,
57
+ }
58
+ }
59
+
60
+ export function calculateEstimatedCostUsd(usage, modelId) {
61
+ const norm = normalizeUsage(usage)
62
+ const rates = resolveModelRates(modelId)
63
+
64
+ const inputCost = (norm.inputTokens * rates.input) / 1_000_000
65
+ const outputCost = (norm.outputTokens * rates.output) / 1_000_000
66
+ const cacheReadCost = (norm.cacheReadTokens * rates.cacheRead) / 1_000_000
67
+ const cacheWriteCost = (norm.cacheWriteTokens * rates.cacheWrite) / 1_000_000
68
+
69
+ return inputCost + outputCost + cacheReadCost + cacheWriteCost
70
+ }
71
+
72
+ export function formatTokenCount(n) {
73
+ const count = Number(n) || 0
74
+ if (count < 1000) return String(count)
75
+ const k = count / 1000
76
+ return (k >= 10 ? k.toFixed(0) : k.toFixed(1)) + 'k'
77
+ }
78
+
79
+ export function formatDurationSeconds(ms) {
80
+ const sec = Math.max(0.1, (Number(ms) || 0) / 1000)
81
+ return sec >= 10 ? `${sec.toFixed(0)}s` : `${sec.toFixed(1)}s`
82
+ }
83
+
84
+ export function formatCostUsd(usd) {
85
+ const val = Number(usd) || 0
86
+ if (val <= 0) return '$0.00'
87
+ if (val < 0.001) return '<$0.001'
88
+ return `~$${val.toFixed(4)}`
89
+ }
90
+
91
+ export function formatCostFooter({ durationMs, usage, model }) {
92
+ const norm = normalizeUsage(usage)
93
+ if (!norm.totalTokens && !durationMs) return ''
94
+
95
+ const durStr = formatDurationSeconds(durationMs)
96
+ const tokenStr = formatTokenCount(norm.totalTokens)
97
+ const cost = calculateEstimatedCostUsd(norm, model)
98
+ const costStr = formatCostUsd(cost)
99
+ const modelName = (model || 'model').split('/').pop()
100
+
101
+ return `\n\n<i>⏱️ ${durStr} · ${tokenStr} tokens (${costStr}) · ${escapeHtml(modelName)}</i>`
102
+ }
103
+
104
+ export function extractSessionStats(chat) {
105
+ let promptTokens = 0
106
+ let completionTokens = 0
107
+ let cachedTokens = 0
108
+ let totalTokens = 0
109
+ let turnsCount = 0
110
+
111
+ // 1. Try DSH session projections if available
112
+ const session = chat?.agent?.session
113
+ let projection = null
114
+ try {
115
+ if (typeof session?.projection === 'function') {
116
+ projection = session.projection('costByModel')
117
+ }
118
+ } catch {
119
+ /* projection not registered or session closed */
120
+ }
121
+
122
+ if (projection?.models && Array.isArray(projection.models)) {
123
+ for (const m of projection.models) {
124
+ if (m.slots && typeof m.slots === 'object') {
125
+ for (const slot of Object.values(m.slots)) {
126
+ promptTokens += Number(slot.uncachedInputTokens || 0)
127
+ completionTokens += Number(slot.outputTokens || 0)
128
+ cachedTokens += Number(slot.cacheReadTokens || 0)
129
+ }
130
+ }
131
+ }
132
+ if (Array.isArray(projection.turns)) {
133
+ turnsCount = projection.turns.length
134
+ }
135
+ }
136
+
137
+ // 2. Accumulate chat turn metrics if projection empty
138
+ if (!promptTokens && !completionTokens && chat?.turnStats) {
139
+ promptTokens = chat.turnStats.inputTokens || 0
140
+ completionTokens = chat.turnStats.outputTokens || 0
141
+ cachedTokens = chat.turnStats.cacheReadTokens || 0
142
+ turnsCount = chat.turnStats.turnsCount || 0
143
+ }
144
+
145
+ // 3. Fallback to last turn usage if available
146
+ if (!promptTokens && !completionTokens && chat?.lastTurnUsage) {
147
+ const lastNorm = normalizeUsage(chat.lastTurnUsage)
148
+ promptTokens = lastNorm.inputTokens
149
+ completionTokens = lastNorm.outputTokens
150
+ cachedTokens = lastNorm.cacheReadTokens
151
+ turnsCount = 1
152
+ }
153
+
154
+ totalTokens = promptTokens + completionTokens + cachedTokens
155
+
156
+ return {
157
+ promptTokens,
158
+ completionTokens,
159
+ cachedTokens,
160
+ totalTokens,
161
+ turnsCount,
162
+ }
163
+ }
164
+
165
+ export function formatSessionCostReport({ chat, config, model }) {
166
+ const stats = extractSessionStats(chat)
167
+ const activeModel = model || config?.agent?.model || 'deepseek-chat'
168
+ const costUsd = calculateEstimatedCostUsd({
169
+ inputTokens: stats.promptTokens,
170
+ outputTokens: stats.completionTokens,
171
+ cacheReadTokens: stats.cachedTokens,
172
+ }, activeModel)
173
+
174
+ const budgetThreshold = Number(config?.telegram?.budgetAlertThresholdUsd || 0)
175
+
176
+ const lines = [
177
+ '📊 <b>Session Token & Cost Meter:</b>',
178
+ `• Active Model: <code>${escapeHtml(activeModel)}</code>`,
179
+ `• Total Tokens: <b>${formatTokenCount(stats.totalTokens)}</b> (${stats.totalTokens.toLocaleString()})`,
180
+ ` ├─ Prompt (input): ${formatTokenCount(stats.promptTokens)}`,
181
+ ` ├─ Completion (output): ${formatTokenCount(stats.completionTokens)}`,
182
+ ` └─ Cached read: ${formatTokenCount(stats.cachedTokens)}`,
183
+ `• Completed Turns: <b>${stats.turnsCount}</b>`,
184
+ `• Estimated Cost: <b>${formatCostUsd(costUsd)}</b> USD`,
185
+ ]
186
+
187
+ if (budgetThreshold > 0) {
188
+ const remaining = Math.max(0, budgetThreshold - costUsd)
189
+ const pct = Math.min(100, (costUsd / budgetThreshold) * 100).toFixed(1)
190
+ lines.push(
191
+ '',
192
+ '🎯 <b>Budget Tracking:</b>',
193
+ `• Budget Threshold: <b>$${budgetThreshold.toFixed(2)}</b>`,
194
+ `• Consumed: <b>${pct}%</b>`,
195
+ `• Remaining: <b>$${remaining.toFixed(4)}</b>`,
196
+ )
197
+ if (costUsd >= budgetThreshold) {
198
+ lines.push('⚠️ <b>Budget threshold reached!</b> Consider using `/new` to reset context.')
199
+ }
200
+ }
201
+
202
+ lines.push('', '<i>Run <code>/cost</code> anytime to check current session spend.</i>')
203
+ return lines.join('\n')
204
+ }
205
+
206
+ export function checkBudgetThreshold({ currentSpendUsd, thresholdUsd }) {
207
+ const threshold = Number(thresholdUsd) || 0
208
+ if (threshold <= 0) return null
209
+ const spend = Number(currentSpendUsd) || 0
210
+
211
+ if (spend >= threshold) {
212
+ return {
213
+ alert: true,
214
+ level: 'limit',
215
+ message: `Session cost ($${spend.toFixed(4)}) has exceeded the configured budget ($${threshold.toFixed(2)}).`,
216
+ }
217
+ }
218
+
219
+ if (spend >= threshold * 0.8) {
220
+ return {
221
+ alert: true,
222
+ level: 'warning',
223
+ message: `Session cost ($${spend.toFixed(4)}) has reached 80% of budget limit ($${threshold.toFixed(2)}).`,
224
+ }
225
+ }
226
+
227
+ return null
228
+ }
@@ -16,6 +16,7 @@ import { HELP_TEXT } from './commands.js'
16
16
  import { resolveEffectiveCwd, getCwdWarning, inspectGitWorkspace, registerSessionInWorkspace } from './workspace.js'
17
17
  import { escapeHtml } from './telegram-format.js'
18
18
  import { rememberUserFact, listUserMemories, forgetUserMemory } from './memory-brain.js'
19
+ import { formatSessionCostReport } from './cost-tracker.js'
19
20
 
20
21
 
21
22
  export function releaseChatTurn(chat) {
@@ -400,6 +401,51 @@ export async function handleGatewayCommand(gw, key, text, input) {
400
401
  return reply(`🗑️ Forgotten memory <code>${escapeHtml(targetId)}</code>.`)
401
402
  }
402
403
 
404
+ if (cmd === '/outbox') {
405
+ const sub = parts[1]?.toLowerCase()
406
+ if (!gw.outbox) {
407
+ return reply('ℹ️ Outbox queue is not initialized.')
408
+ }
409
+
410
+ if (sub === 'retry') {
411
+ const count = await gw.outbox.retryDlq()
412
+ return reply(`🔄 Moved <b>${count}</b> DLQ items back to outbox queue for retry.`)
413
+ }
414
+
415
+ if (sub === 'clear') {
416
+ const count = await gw.outbox.clearDlq()
417
+ return reply(`🗑️ Cleared <b>${count}</b> items from Dead Letter Queue.`)
418
+ }
419
+
420
+ const st = gw.outbox.status()
421
+ const lines = [
422
+ '📬 <b>Outbox Transactional Queue:</b>',
423
+ `• Pending messages: <b>${st.pendingCount}</b>`,
424
+ `• Dead Letter Queue (DLQ): <b>${st.dlqCount}</b>`,
425
+ ]
426
+ if (st.dlqCount > 0) {
427
+ lines.push('', '<b>Recent DLQ Failures:</b>')
428
+ const sample = st.dlq.slice(0, 5)
429
+ for (const item of sample) {
430
+ lines.push(`- [<code>${escapeHtml(item.id.slice(0, 8))}</code>] to ${escapeHtml(String(item.target?.chatId))}: ${escapeHtml(item.error || 'unknown error')}`)
431
+ }
432
+ lines.push('', 'Commands:', '• Retry all: <code>/outbox retry</code>', '• Clear DLQ: <code>/outbox clear</code>')
433
+ } else {
434
+ lines.push('', '<i>All outbound messages successfully delivered.</i>')
435
+ }
436
+ return reply(lines.join('\n'))
437
+ }
438
+
439
+ if (cmd === '/cost') {
440
+ const chat = gw.chats.get(key)
441
+ const report = formatSessionCostReport({
442
+ chat,
443
+ config: gw.config,
444
+ model: gw.config.agent?.model || 'deepseek-chat',
445
+ })
446
+ return reply(report)
447
+ }
448
+
403
449
  if (cmd === '/cwd') {
404
450
  const chat = gw.chats.get(key)
405
451
  const sessionCwd = chat?.agent?.meta?.cwd || chat?.agent?.session?.meta?.cwd || (gw.resolveEffectiveCwdFor ? gw.resolveEffectiveCwdFor(chatId, threadId) : resolveEffectiveCwd(gw.config.agent?.cwd, gw.ctx?.logger))
@@ -15,6 +15,7 @@ import {
15
15
  buildStreamPreview, formatProgressLine, createEditScheduler, startTypingHeartbeat, parseReasoningStream
16
16
  } from './stream.js'
17
17
  import { escapeHtml } from './telegram-format.js'
18
+ import { formatCostFooter, normalizeUsage, extractSessionStats, calculateEstimatedCostUsd, checkBudgetThreshold } from './cost-tracker.js'
18
19
  import { recallUserMemories, recordTurnMemory } from './memory-brain.js'
19
20
 
20
21
  const PLUGIN = 'dsh-messenger-gateway'
@@ -215,6 +216,7 @@ export async function buildUserContent(gw, input, signal) {
215
216
 
216
217
  export async function runGatewayTurn(gw, chat, input, signal) {
217
218
  const { reply, typing, startStream, startProgress, react, inboundWasVoice, userId } = input
219
+ const turnStartTime = Date.now()
218
220
  chat.turnActive = true
219
221
  const sessionId = chat.agent.session.id
220
222
  const tg = gw.tg()
@@ -330,6 +332,23 @@ export async function runGatewayTurn(gw, chat, input, signal) {
330
332
  else await reply(noResp)
331
333
  return
332
334
  }
335
+ if (collector.usage) {
336
+ chat.lastTurnUsage = collector.usage
337
+ if (!chat.turnStats) chat.turnStats = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, turnsCount: 0 }
338
+ chat.turnStats.turnsCount++
339
+ const norm = normalizeUsage(collector.usage)
340
+ chat.turnStats.inputTokens += norm.inputTokens
341
+ chat.turnStats.outputTokens += norm.outputTokens
342
+ chat.turnStats.cacheReadTokens += norm.cacheReadTokens
343
+ }
344
+ if (tg.costFooter && answer) {
345
+ const footer = formatCostFooter({
346
+ durationMs: Date.now() - turnStartTime,
347
+ usage: collector.usage,
348
+ model: gw.config?.agent?.model,
349
+ })
350
+ if (footer) answer += footer
351
+ }
333
352
  const maxLen = Number(gw.config.agent?.maxMessageLength) || 4000
334
353
  const chunks = answer ? splitText(answer, maxLen) : ['']
335
354
  if (stream) {
@@ -363,6 +382,23 @@ export async function runGatewayTurn(gw, chat, input, signal) {
363
382
  }
364
383
  }
365
384
  }
385
+ const budgetThreshold = Number(tg.budgetAlertThresholdUsd || 0)
386
+ if (budgetThreshold > 0) {
387
+ const stats = extractSessionStats(chat)
388
+ const cost = calculateEstimatedCostUsd({
389
+ inputTokens: stats.promptTokens,
390
+ outputTokens: stats.completionTokens,
391
+ cacheReadTokens: stats.cachedTokens,
392
+ }, gw.config?.agent?.model)
393
+ const warning = checkBudgetThreshold({ currentSpendUsd: cost, thresholdUsd: budgetThreshold })
394
+ if (warning && !chat.budgetWarned) {
395
+ chat.budgetWarned = true
396
+ gw.sendAlert('status', {
397
+ title: 'Budget Alert',
398
+ details: `${warning.message} (Chat: ${input.chatId})`,
399
+ }).catch(() => {})
400
+ }
401
+ }
366
402
  if (gw.config?.memory?.enabled !== false && userId && answer && input.text) {
367
403
  recordTurnMemory({
368
404
  config: gw.config.memory,
package/lib/gateway.js CHANGED
@@ -30,6 +30,7 @@ import {
30
30
  } from './forum-mirror.js'
31
31
  import { resolveInternalBaseUrl } from './config.js'
32
32
  import { resolveEffectiveCwd, registerSessionInWorkspace, createTopicWorkspaceStore, getCwdWarning } from './workspace.js'
33
+ import { createOutboxQueue, resolveOutboxStoragePath } from './outbox.js'
33
34
  import { realpathSync } from 'node:fs'
34
35
  import { resolve } from 'node:path'
35
36
 
@@ -63,6 +64,21 @@ export class Gateway {
63
64
  this.personas = createPersonaStore(join(home, 'messenger-gateway', 'personas.json'), { logger: this.logger })
64
65
  this.topicWorkspaces = createTopicWorkspaceStore(join(home, 'messenger-gateway', 'topic-workspaces.json'), { logger: this.logger })
65
66
  this.chatLocales = createVoicePrefs(join(home, 'messenger-gateway', 'chat-locales.json'), { logger: this.logger })
67
+ this.outbox = createOutboxQueue({
68
+ storagePath: resolveOutboxStoragePath(join(home, 'messenger-gateway')),
69
+ senderFn: async (job) => {
70
+ await this.messengerSend(job.target, job.payload)
71
+ },
72
+ onDlq: (job, err) => {
73
+ this.sendAlert('error', {
74
+ code: 'OUTBOX_DLQ',
75
+ message: `Outbox message failed permanently to ${job.target?.chatId}: ${err.message}`,
76
+ chatId: job.target?.chatId,
77
+ threadId: job.target?.threadId,
78
+ }).catch((e) => this.recordApiFailure('outbox.dlq_alert', e))
79
+ },
80
+ logger: this.logger,
81
+ })
66
82
  this.scheduler = createScheduler(join(home, 'messenger-gateway', 'scheduled.json'), async (task) => {
67
83
  const target = {
68
84
  platform: task.platform || 'telegram',
@@ -210,7 +226,13 @@ export class Gateway {
210
226
  if (text) collector.lastText = text
211
227
  const extra = collectAssistantParts(msg)
212
228
  for (const img of extra.images) collector.images.push(img)
229
+ const usage = event.data?.usage || msg?.usage
230
+ if (usage) collector.usage = usage
213
231
  } else if (event.type === 'assistant/chunk') {
232
+ const chunk = event.data?.chunk || event.data
233
+ if (chunk?.type === 'usage' && chunk?.usage) {
234
+ collector.usage = chunk.usage
235
+ }
214
236
  const delta = extractTextDelta(event.data?.chunk || event.data)
215
237
  const reasoningDelta = extractReasoningDelta(event.data?.chunk || event.data)
216
238
  if (delta || reasoningDelta) {
@@ -293,11 +315,13 @@ export class Gateway {
293
315
  const idleMs = Number.isFinite(rawIdle) && rawIdle > 0 ? rawIdle : 86_400_000
294
316
  this.idleTimer = setInterval(() => this.reapIdle(), Math.min(idleMs, 60_000))
295
317
  this.idleTimer.unref?.()
318
+ this.outbox?.start()
296
319
  this.scheduler.start()
297
320
  }
298
321
 
299
322
  stop() {
300
323
  this.stopped = true
324
+ if (this.outbox) this.outbox.stop()
301
325
  if (this.scheduler) this.scheduler.stop()
302
326
  if (this.disposeListener) this.disposeListener()
303
327
  if (this.idleTimer) clearInterval(this.idleTimer)
@@ -321,6 +345,17 @@ export class Gateway {
321
345
 
322
346
  getAdapter(platform) { return this.adapters.get(platform) }
323
347
 
348
+ async sendToMessenger(target, payload, opts = {}) {
349
+ if (opts.reliable !== false && this.outbox) {
350
+ return this.outbox.enqueue({
351
+ target,
352
+ payload: typeof payload === 'string' ? { text: payload } : payload,
353
+ type: opts.type || 'message',
354
+ })
355
+ }
356
+ return this.messengerSend(target, payload)
357
+ }
358
+
324
359
  async messengerSend(target, payload) {
325
360
  let resolved = target
326
361
  if (!resolved?.chatId && resolved?.platform) {
package/lib/outbox.js ADDED
@@ -0,0 +1,262 @@
1
+ /**
2
+ * Outbound Transactional Queue (Outbox DLQ) with Offline Recovery & Backoff (#155).
3
+ *
4
+ * Guarantees zero message loss during temporary network hiccups, Telegram 429
5
+ * throttling, 502/504 gateway errors, and process restarts:
6
+ * - Atomic persistent disk queue (~/.dsh/storages/outbox-queue.json).
7
+ * - Exponential backoff with jitter and Telegram 429 `retry_after` awareness.
8
+ * - Dead Letter Queue (DLQ) for items failing after max retries or terminal errors.
9
+ * - Recovery of pending uncommitted outbound jobs on gateway startup.
10
+ */
11
+
12
+ import { existsSync, readFileSync } from 'node:fs'
13
+ import { join } from 'node:path'
14
+ import { homedir } from 'node:os'
15
+ import { randomUUID } from 'node:crypto'
16
+ import { writeJsonAtomic } from './storage-atomic.js'
17
+ import { isTopicGoneError } from './telegram-errors.js'
18
+
19
+ export function resolveOutboxStoragePath(baseDir) {
20
+ if (baseDir) return join(baseDir, 'outbox-queue.json')
21
+ const dshHome = (typeof process !== 'undefined' && process.env?.DSH_HOME) || ''
22
+ if (dshHome) return join(dshHome, 'storages', 'outbox-queue.json')
23
+ return join(homedir(), '.dsh', 'storages', 'outbox-queue.json')
24
+ }
25
+
26
+ export function parseRetryAfter(err) {
27
+ if (!err) return null
28
+ if (typeof err.parameters?.retry_after === 'number') {
29
+ return err.parameters.retry_after
30
+ }
31
+ if (typeof err.response?.parameters?.retry_after === 'number') {
32
+ return err.response.parameters.retry_after
33
+ }
34
+ const msg = String(err.message || '')
35
+ const match = msg.match(/retry after (\d+)/i)
36
+ if (match) {
37
+ const val = parseInt(match[1], 10)
38
+ if (!Number.isNaN(val) && val > 0) return val
39
+ }
40
+ return null
41
+ }
42
+
43
+ export function computeOutboxBackoffMs(attempts, retryAfterSeconds, maxDelayMs = 60_000) {
44
+ const jitter = Math.floor(Math.random() * 400)
45
+ if (typeof retryAfterSeconds === 'number' && retryAfterSeconds > 0) {
46
+ return Math.min(maxDelayMs, (retryAfterSeconds * 1000) + jitter)
47
+ }
48
+ const count = Math.max(1, Math.min(10, Number(attempts) || 1))
49
+ const baseDelay = 1000 * Math.pow(2, count - 1)
50
+ return Math.min(maxDelayMs, baseDelay + jitter)
51
+ }
52
+
53
+ export function isTerminalSendError(err) {
54
+ if (!err) return false
55
+ if (isTopicGoneError(err)) return true
56
+ const msg = String(err.message || '').toLowerCase()
57
+ return (
58
+ msg.includes('bot was blocked by the user') ||
59
+ msg.includes('user is deactivated') ||
60
+ msg.includes('chat not found') ||
61
+ msg.includes('message is too long') ||
62
+ msg.includes('message text is empty') ||
63
+ msg.includes("can't parse entities") ||
64
+ msg.includes('wrong file identifier') ||
65
+ msg.includes('have no rights to send a message')
66
+ )
67
+ }
68
+
69
+ export function createOutboxQueue(options = {}) {
70
+ const {
71
+ storagePath = resolveOutboxStoragePath(),
72
+ senderFn,
73
+ onDlq,
74
+ logger,
75
+ flushIntervalMs = 1000,
76
+ defaultMaxAttempts = 5,
77
+ } = options
78
+
79
+ let pending = []
80
+ let dlq = []
81
+ let timer = null
82
+ let isFlushing = false
83
+ let isStopped = false
84
+
85
+ function loadSync() {
86
+ try {
87
+ if (existsSync(storagePath)) {
88
+ const raw = readFileSync(storagePath, 'utf8')
89
+ const data = JSON.parse(raw)
90
+ if (Array.isArray(data.pending)) pending = data.pending
91
+ if (Array.isArray(data.dlq)) dlq = data.dlq
92
+ if (pending.length > 0 && logger) {
93
+ logger.info?.(`[outbox] recovered ${pending.length} pending outbound jobs from disk`)
94
+ }
95
+ }
96
+ } catch (err) {
97
+ if (logger) {
98
+ logger.warn?.(`[outbox] failed to load storage: ${err.message}`)
99
+ }
100
+ }
101
+ }
102
+
103
+ loadSync()
104
+
105
+ async function persist() {
106
+ try {
107
+ await writeJsonAtomic(storagePath, { pending, dlq })
108
+ } catch (err) {
109
+ if (logger) {
110
+ logger.warn?.(`[outbox] failed to persist queue to disk: ${err.message}`)
111
+ }
112
+ }
113
+ }
114
+
115
+ async function flush() {
116
+ if (isFlushing || isStopped) return
117
+ if (!pending.length) return
118
+ isFlushing = true
119
+ const now = Date.now()
120
+ let dirty = false
121
+
122
+ try {
123
+ const readyJobs = pending.filter((j) => (j.nextRetryAt || 0) <= now)
124
+ for (const job of readyJobs) {
125
+ if (isStopped) break
126
+ try {
127
+ if (typeof senderFn !== 'function') {
128
+ throw new Error('outbox senderFn not configured')
129
+ }
130
+ await senderFn(job)
131
+ pending = pending.filter((j) => j.id !== job.id)
132
+ dirty = true
133
+ } catch (err) {
134
+ job.attempts = (job.attempts || 0) + 1
135
+ job.lastError = err?.message || String(err)
136
+ const terminal = isTerminalSendError(err)
137
+ const max = job.maxAttempts || defaultMaxAttempts
138
+
139
+ if (terminal || job.attempts >= max) {
140
+ pending = pending.filter((j) => j.id !== job.id)
141
+ dlq.unshift({
142
+ id: job.id,
143
+ type: job.type,
144
+ target: job.target,
145
+ payload: job.payload,
146
+ attempts: job.attempts,
147
+ createdAt: job.createdAt,
148
+ failedAt: Date.now(),
149
+ terminal,
150
+ error: job.lastError,
151
+ })
152
+ if (dlq.length > 100) dlq.length = 100
153
+ dirty = true
154
+ if (typeof onDlq === 'function') {
155
+ try { onDlq(job, err) } catch (dlqErr) {
156
+ logger?.warn?.(`[outbox] onDlq error: ${dlqErr.message}`)
157
+ }
158
+ }
159
+ } else {
160
+ const retryAfter = parseRetryAfter(err)
161
+ const delayMs = computeOutboxBackoffMs(job.attempts, retryAfter)
162
+ job.nextRetryAt = Date.now() + delayMs
163
+ dirty = true
164
+ if (logger) {
165
+ logger.warn?.(`[outbox] job ${job.id} failed (attempt ${job.attempts}/${max}), retrying in ${Math.round(delayMs / 1000)}s: ${job.lastError}`)
166
+ }
167
+ }
168
+ }
169
+ }
170
+ } finally {
171
+ isFlushing = false
172
+ if (dirty) {
173
+ await persist()
174
+ }
175
+ }
176
+ }
177
+
178
+ async function enqueue(job) {
179
+ const item = {
180
+ id: job.id || randomUUID(),
181
+ type: job.type || 'message',
182
+ target: job.target,
183
+ payload: job.payload,
184
+ attempts: 0,
185
+ maxAttempts: job.maxAttempts || defaultMaxAttempts,
186
+ createdAt: Date.now(),
187
+ nextRetryAt: Date.now(),
188
+ lastError: null,
189
+ }
190
+ pending.push(item)
191
+ await persist()
192
+ void flush()
193
+ return item
194
+ }
195
+
196
+ function start() {
197
+ isStopped = false
198
+ void flush()
199
+ if (!timer && flushIntervalMs > 0) {
200
+ timer = setInterval(() => { void flush() }, flushIntervalMs)
201
+ timer.unref?.()
202
+ }
203
+ }
204
+
205
+ function stop() {
206
+ isStopped = true
207
+ if (timer) {
208
+ clearInterval(timer)
209
+ timer = null
210
+ }
211
+ }
212
+
213
+ function status() {
214
+ return {
215
+ pendingCount: pending.length,
216
+ dlqCount: dlq.length,
217
+ pending: [...pending],
218
+ dlq: [...dlq],
219
+ }
220
+ }
221
+
222
+ async function retryDlq() {
223
+ if (!dlq.length) return 0
224
+ const count = dlq.length
225
+ for (const item of dlq) {
226
+ pending.push({
227
+ id: item.id || randomUUID(),
228
+ type: item.type,
229
+ target: item.target,
230
+ payload: item.payload,
231
+ attempts: 0,
232
+ maxAttempts: defaultMaxAttempts,
233
+ createdAt: Date.now(),
234
+ nextRetryAt: Date.now(),
235
+ lastError: null,
236
+ })
237
+ }
238
+ dlq = []
239
+ await persist()
240
+ await flush()
241
+ return count
242
+ }
243
+
244
+ async function clearDlq() {
245
+ const count = dlq.length
246
+ dlq = []
247
+ await persist()
248
+ return count
249
+ }
250
+
251
+ return {
252
+ enqueue,
253
+ flush,
254
+ start,
255
+ stop,
256
+ status,
257
+ retryDlq,
258
+ clearDlq,
259
+ get pending() { return pending },
260
+ get dlq() { return dlq },
261
+ }
262
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@goodandready/dsh-messenger-gateway",
3
- "version": "0.4.26",
3
+ "version": "0.4.27",
4
4
  "description": "Telegram messenger bridge for DeepSeek Harness: sessions, steer, homes, inline asks, notify bridge, and optional TTS voice notes.",
5
5
  "license": "MIT",
6
6
  "type": "module",