@s0nderlabs/anima-plugin-telegram 0.19.14 → 0.19.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s0nderlabs/anima-plugin-telegram",
-  "version": "0.19.14",
+  "version": "0.19.15",
   "type": "module",
   "description": "Telegram gateway plugin for anima — long-poll bot, debounced dispatch, reactions, allowlist",
   "license": "MIT",
@@ -28,7 +28,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@s0nderlabs/anima-core": "0.19.14",
+    "@s0nderlabs/anima-core": "0.19.15",
     "grammy": "^1.42.0",
     "zod": "^3.23.8"
   }

package/src/index.ts

@@ -24,7 +24,9 @@ export type {
   TelegramDispatchInput,
   TelegramDispatchResult,
   TelegramInboundEvent,
+  TelegramToolEvent,
 } from './types'
+export { ProgressTracker, PROGRESS_EDIT_INTERVAL } from './progress'
 export { TelegramListener, capForTelegram } from './listener'
 export { buildSessionKey, sanitizeAgentName } from './session-key'
 export { formatTelegramChannel, formatInboundPreview } from './format'
@@ -88,6 +90,7 @@ export {
   REACTION_ERR,
 } from './reactions'
 export { TELEGRAM_GUIDANCE } from './guidance'
+export { startTypingLoop, TYPING_REFRESH_INTERVAL_MS } from './typing'
 
 const plugin: NativePlugin = {
   name: 'telegram',

package/src/listener.ts

@@ -6,6 +6,7 @@ import { formatTelegramChannel } from './format'
 import { RateLimiter } from './limits'
 import { formatMarkdownV2, isMarkdownParseError, stripMarkdownV2 } from './markdown'
 import { formatPairingMessage } from './pairing-flow'
+import { ProgressTracker } from './progress'
 import { reactError, reactProcessing, reactSuccess } from './reactions'
 import {
   BotTokenLockedError,
@@ -19,6 +20,7 @@ import { DELIVERY_FAILURE_NOTICE, sendWithRetry } from './retry'
 import { sanitizeInbound } from './sanitize'
 import { buildSessionKey } from './session-key'
 import type { TelegramDispatchInput, TelegramRuntimeContext } from './types'
+import { startTypingLoop } from './typing'
 
 /**
  * Long-poll Telegram bot. Inbound DMs from allowedUserIds are debounced and
@@ -355,6 +357,17 @@ export class TelegramListener {
         /* never block on hook failures */
       }
     }
+    // Show "typing..." in the chat header for the duration of the brain turn.
+    // TG's chat action expires after ~5s, so the loop refreshes on a 4.5s
+    // interval. Cancel via try/finally so it stops in both happy and error
+    // paths. See `typing.ts` for the cancel-fn pattern.
+    const stopTyping = startTypingLoop(this.bot, chatId)
+    // Tool-call progress message: hermes-style scratch message that gets
+    // edited as the brain progresses through tools. See `progress.ts`.
+    // Always created; the tracker only sends a message when the brain
+    // actually fires a tool event, so prompts that go straight to a
+    // text answer don't get a noisy progress preamble.
+    const tracker = new ProgressTracker(this.bot, chatId)
     let ok = true
     try {
       const input: TelegramDispatchInput = {
@@ -365,6 +378,9 @@ export class TelegramListener {
         displayName: batch.displayName,
         latestMessageId: messageId,
         sessionKey: buildSessionKey({ agentName: this.opts.agentName, chatId }),
+        onToolEvent: ev => {
+          void tracker.push(ev)
+        },
       }
       const channelText = formatTelegramChannel({
         chatId,
@@ -384,15 +400,26 @@ export class TelegramListener {
       const stack = err instanceof Error && err.stack ? `\n${err.stack}` : ''
       console.error(`[telegram] dispatch failed: ${msg.slice(0, 500)}${stack}`)
       void reactError(this.bot, chatId, messageId)
+      // Translate LedgerInsufficientError into an actionable topup hint
+      // instead of the generic "something went wrong" reply. Detect by
+      // name (avoids requiring the plugin to import core's typed class).
+      const isLedger = err instanceof Error && err.name === 'LedgerInsufficientError'
+      const replyText = isLedger
+        ? `⚠️ I need a top-up to keep working.\n\n${msg}`
+        : 'sorry, something went wrong on my side. try again in a moment.'
       try {
-        await this.bot.api.sendMessage(
-          chatId,
-          'sorry, something went wrong on my side. try again in a moment.',
-          { reply_parameters: { message_id: messageId, allow_sending_without_reply: true } },
-        )
+        await this.bot.api.sendMessage(chatId, replyText, {
+          reply_parameters: { message_id: messageId, allow_sending_without_reply: true },
+        })
       } catch {
         /* swallow */
       }
+    } finally {
+      // Flush any pending throttled progress edit before clearing the
+      // typing loop. finalize() is idempotent, swallows errors, and is safe
+      // even if the tracker never rendered anything.
+      await tracker.finalize().catch(() => {})
+      stopTyping()
     }
     if (this.opts.onProcessingEnd) {
       try {

package/src/progress.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, it } from 'bun:test'
+import type { Bot } from 'grammy'
+import { PROGRESS_EDIT_INTERVAL, ProgressTracker } from './progress'
+
+interface CallLog {
+  sendMessage: { text: string; messageId: number }[]
+  editMessageText: { messageId: number; text: string }[]
+  /** Reject the editMessageText this many times before succeeding. Use to drive the flood-mode fallback. */
+  rejectEditNTimes?: number
+  /** Reject editMessageText with this exact error each time it's called. */
+  editError?: string
+}
+
+function makeStubBot(log: CallLog): Bot {
+  let nextMessageId = 1000
+  return {
+    api: {
+      sendMessage: async (_chatId: number, text: string) => {
+        const id = nextMessageId++
+        log.sendMessage.push({ text, messageId: id })
+        return { message_id: id, chat: { id: _chatId } } as unknown as Awaited<
+          ReturnType<Bot['api']['sendMessage']>
+        >
+      },
+      editMessageText: async (_chatId: number, messageId: number, text: string) => {
+        if (log.rejectEditNTimes && log.rejectEditNTimes > 0) {
+          log.rejectEditNTimes -= 1
+          throw new Error(log.editError ?? 'Bad Request: 429 Too Many Requests')
+        }
+        log.editMessageText.push({ messageId, text })
+        return true as const
+      },
+    },
+  } as unknown as Bot
+}
+
+describe('ProgressTracker', () => {
+  it('first push sends a new message and records messageId', async () => {
+    const log: CallLog = { sendMessage: [], editMessageText: [] }
+    const bot = makeStubBot(log)
+    const t = new ProgressTracker(bot, 999)
+    await t.push({ kind: 'start', tool: 'shell.run', callId: 'c1', argsPreview: 'date' })
+    expect(log.sendMessage.length).toBe(1)
+    expect(log.editMessageText.length).toBe(0)
+    expect(t.hasRendered()).toBe(true)
+    expect(log.sendMessage[0]?.text).toContain('shell\\.run')
+    expect(log.sendMessage[0]?.text).toContain('date')
+  })
+
+  it('subsequent push within throttle does NOT immediately edit', async () => {
+    const log: CallLog = { sendMessage: [], editMessageText: [] }
+    const bot = makeStubBot(log)
+    const t = new ProgressTracker(bot, 999)
+    await t.push({ kind: 'start', tool: 'shell.run', callId: 'c1' })
+    await t.push({ kind: 'start', tool: 'web.fetch', callId: 'c2' })
+    expect(log.sendMessage.length).toBe(1)
+    expect(log.editMessageText.length).toBe(0)
+    await t.finalize()
+    // finalize forces a flush of the pending edit.
+    expect(log.editMessageText.length).toBe(1)
+    expect(log.editMessageText[0]?.text).toContain('shell\\.run')
+    expect(log.editMessageText[0]?.text).toContain('web\\.fetch')
+  })
+
+  it('end event marks the line with a check', async () => {
+    const log: CallLog = { sendMessage: [], editMessageText: [] }
+    const bot = makeStubBot(log)
+    const t = new ProgressTracker(bot, 999)
+    await t.push({ kind: 'start', tool: 'shell.run', callId: 'c1' })
+    await t.push({ kind: 'end', tool: 'shell.run', callId: 'c1', ok: true })
+    await t.finalize()
+    expect(log.editMessageText.length).toBe(1)
+    expect(log.editMessageText[0]?.text).toContain('✓')
+  })
+
+  it('end event with ok=false marks the line with an X', async () => {
+    const log: CallLog = { sendMessage: [], editMessageText: [] }
+    const bot = makeStubBot(log)
+    const t = new ProgressTracker(bot, 999)
+    await t.push({ kind: 'start', tool: 'shell.run', callId: 'c1' })
+    await t.push({ kind: 'end', tool: 'shell.run', callId: 'c1', ok: false })
+    await t.finalize()
+    expect(log.editMessageText.length).toBe(1)
+    expect(log.editMessageText[0]?.text).toContain('✗')
+  })
+
+  it('finalize is idempotent', async () => {
+    const log: CallLog = { sendMessage: [], editMessageText: [] }
+    const bot = makeStubBot(log)
+    const t = new ProgressTracker(bot, 999)
+    await t.push({ kind: 'start', tool: 'shell.run', callId: 'c1' })
+    await t.finalize()
+    await t.finalize()
+    await t.finalize()
+    expect(log.sendMessage.length).toBe(1)
+    // No additional edits triggered by repeated finalize.
+    expect(log.editMessageText.length).toBeLessThanOrEqual(0)
+  })
+
+  it('flood error flips canEdit off and falls back to sendMessage', async () => {
+    const log: CallLog = {
+      sendMessage: [],
+      editMessageText: [],
+      rejectEditNTimes: 99,
+      editError: 'Bad Request: 429 Too Many Requests',
+    }
+    const bot = makeStubBot(log)
+    const t = new ProgressTracker(bot, 999)
+    // 1st push: sendMessage (new message)
+    await t.push({ kind: 'start', tool: 'shell.run', callId: 'c1' })
+    expect(log.sendMessage.length).toBe(1)
+    // Wait past throttle to force an edit attempt on next push.
+    await new Promise(r => setTimeout(r, PROGRESS_EDIT_INTERVAL + 50))
+    // 2nd push triggers editMessageText, which rejects with 429 → canEdit=false
+    await t.push({ kind: 'start', tool: 'web.fetch', callId: 'c2' })
+    // Wait past throttle again so 3rd push goes through.
+    await new Promise(r => setTimeout(r, PROGRESS_EDIT_INTERVAL + 50))
+    // 3rd push: now canEdit=false, falls back to sendMessage of the latest line.
+    await t.push({ kind: 'start', tool: 'fs.read', callId: 'c3' })
+    expect(log.sendMessage.length).toBe(2)
+  })
+
+  it('end event before start event is silently ignored', async () => {
+    const log: CallLog = { sendMessage: [], editMessageText: [] }
+    const bot = makeStubBot(log)
+    const t = new ProgressTracker(bot, 999)
+    // Receiving an 'end' for a callId we never saw 'start' for.
+    await t.push({ kind: 'end', tool: 'shell.run', callId: 'unknown', ok: true })
+    expect(log.sendMessage.length).toBe(0)
+    expect(t.hasRendered()).toBe(false)
+  })
+})

package/src/progress.ts

@@ -0,0 +1,220 @@
+/**
+ * Tool-call progress tracker for live TG dispatch surfacing.
+ *
+ * Mirrors hermes' `send_progress_messages` (run.py:7070-7272): the agent's
+ * tool calls accumulate into a single "scratch" TG message that gets edited
+ * in place as the brain progresses through the turn. Final answer arrives
+ * later as a separate message.
+ *
+ * Behavior:
+ *  - First `push` sends a new message and saves messageId.
+ *  - Subsequent pushes within the throttle window are coalesced — a single
+ *    trailing edit fires after the throttle elapses.
+ *  - On a TG flood error (HTTP 429), `canEdit` flips off and remaining
+ *    pushes go as separate messages instead of edits.
+ *  - All errors swallowed: progress is best-effort, never blocks dispatch.
+ *  - `finalize()` is idempotent and forces any pending edit to flush.
+ *
+ * Tool emoji mapping is a small allowlist; everything else gets the wrench.
+ * Args preview is provided by the brain via `BrainToolEvent.argsPreview`
+ * (see `previewToolArgs` in og-compute.ts).
+ */
+import type { Bot } from 'grammy'
+import { escapeMarkdownV2, isMarkdownParseError, stripMarkdownV2 } from './markdown'
+
+const PROGRESS_EDIT_INTERVAL_MS = 1_500
+/** TG hard cap is 4096; keep margin for `(N/N)` suffix and edit growth. */
+const PROGRESS_TEXT_CAP = 3_800
+
+const TOOL_EMOJI: Record<string, string> = {
+  'shell.run': '💻',
+  'shell.cd': '📁',
+  'shell.process_start': '🚀',
+  'shell.process_output': '📥',
+  'shell.process_list': '📋',
+  'shell.process_kill': '🛑',
+  'fs.read': '📄',
+  'fs.write': '✏️',
+  'fs.patch': '🩹',
+  'fs.search': '🔍',
+  'web.fetch': '🌐',
+  'browser.navigate': '🌐',
+  'browser.snapshot': '📸',
+  'browser.click': '🖱️',
+  'browser.type': '⌨️',
+  'browser.scroll': '🖱️',
+  'browser.back': '⬅️',
+  'browser.press': '⌨️',
+  'browser.get_images': '🖼️',
+  'browser.console': '🛠',
+  'browser.vision': '👁',
+  'memory.read': '🧠',
+  'memory.save': '💾',
+  todo: '📝',
+  clarify: '❓',
+  'skills.list': '📚',
+  'skills.view': '📖',
+  'skills.manage': '🛠',
+  'session.search': '🔎',
+  'code.execute': '🐍',
+  'vision.analyze': '👁',
+  'delegate.task': '🤝',
+  'tool.search': '🔧',
+  'chain.gas': '⛽',
+  'chain.balance': '💰',
+  'chain.contract': '📜',
+  'chain.tx': '📝',
+  'wallet.transfer': '💸',
+  'swap.quote': '🔁',
+  'swap.execute': '🔄',
+  'stake.delegate': '🥩',
+  'comms.send': '📨',
+  'comms.list': '📬',
+  'market.list': '🛒',
+  'market.bid': '🪙',
+  'account.info': 'ℹ️',
+}
+
+interface ProgressEvent {
+  kind: 'start' | 'end'
+  tool: string
+  callId: string
+  argsPreview?: string
+  ok?: boolean
+}
+
+export class ProgressTracker {
+  private messageId: number | null = null
+  /** Map of callId → line index in `lines` so 'end' events can mark ✓/✗. */
+  private callIndex = new Map<string, number>()
+  private lines: string[] = []
+  private lastEditTs = 0
+  /** Last text we successfully sent or edited; used to skip no-op flushes. */
+  private lastFlushedText = ''
+  private canEdit = true
+  private pendingTimer: ReturnType<typeof setTimeout> | null = null
+  private finalized = false
+
+  constructor(
+    private readonly bot: Bot,
+    private readonly chatId: number,
+  ) {}
+
+  /**
+   * Add an event to the progress timeline. Drives a sendMessage on first
+   * call, editMessageText on subsequent calls (throttled at 1.5s).
+   *
+   * Returns the in-flight flush promise so dispatch can `await tracker.push`
+   * if it wants strict ordering, but normal use is fire-and-forget.
+   */
+  async push(ev: ProgressEvent): Promise<void> {
+    if (this.finalized) return
+    if (ev.kind === 'start') {
+      const line = formatStartLine(ev)
+      this.callIndex.set(ev.callId, this.lines.length)
+      this.lines.push(line)
+    } else {
+      const idx = this.callIndex.get(ev.callId)
+      if (idx == null || this.lines[idx] == null) return
+      this.lines[idx] = `${this.lines[idx]} ${ev.ok === false ? '✗' : '✓'}`
+    }
+    await this.flush()
+  }
+
+  /**
+   * Force any pending throttled edit to fire NOW, then mark the tracker
+   * closed. Future pushes are no-ops.
+   */
+  async finalize(): Promise<void> {
+    if (this.finalized) return
+    if (this.pendingTimer) {
+      clearTimeout(this.pendingTimer)
+      this.pendingTimer = null
+    }
+    await this.flush(true)
+    this.finalized = true
+  }
+
+  /**
+   * Whether the tracker has rendered anything yet. Used by the listener to
+   * decide whether to skip the final reply ("..." sandwich UX).
+   */
+  hasRendered(): boolean {
+    return this.messageId !== null
+  }
+
+  private async flush(force = false): Promise<void> {
+    if (this.lines.length === 0) return
+    const text = capProgressText(this.lines.join('\n'))
+    // Skip no-op flushes: nothing changed since the last send/edit.
+    if (text === this.lastFlushedText) return
+    const remaining = PROGRESS_EDIT_INTERVAL_MS - (Date.now() - this.lastEditTs)
+    if (!force && remaining > 0 && this.messageId !== null) {
+      // Throttle: schedule one trailing edit if not already pending.
+      if (!this.pendingTimer) {
+        this.pendingTimer = setTimeout(() => {
+          this.pendingTimer = null
+          void this.flush()
+        }, remaining)
+      }
+      return
+    }
+    this.pendingTimer = null
+    const md = escapeMarkdownV2(text)
+    try {
+      if (this.messageId === null) {
+        const sent = await this.bot.api.sendMessage(this.chatId, md, {
+          parse_mode: 'MarkdownV2',
+        })
+        this.messageId = sent.message_id
+      } else if (this.canEdit) {
+        await this.bot.api.editMessageText(this.chatId, this.messageId, md, {
+          parse_mode: 'MarkdownV2',
+        })
+      } else {
+        // Flood-mode fallback: append the latest line as a new message.
+        const lastLine = this.lines[this.lines.length - 1] ?? ''
+        await this.bot.api.sendMessage(this.chatId, escapeMarkdownV2(lastLine), {
+          parse_mode: 'MarkdownV2',
+        })
+      }
+      this.lastEditTs = Date.now()
+      this.lastFlushedText = text
+    } catch (err) {
+      const msg = String((err as Error).message ?? '').toLowerCase()
+      if (msg.includes('flood') || msg.includes('too many requests') || msg.includes('429')) {
+        this.canEdit = false
+      } else if (isMarkdownParseError(err)) {
+        // MarkdownV2 escape miss; retry as plain text once.
+        try {
+          const plain = stripMarkdownV2(text)
+          if (this.messageId === null) {
+            const sent = await this.bot.api.sendMessage(this.chatId, plain)
+            this.messageId = sent.message_id
+          } else {
+            await this.bot.api.editMessageText(this.chatId, this.messageId, plain)
+          }
+          this.lastEditTs = Date.now()
+        } catch {
+          /* swallow — never block dispatch */
+        }
+      }
+      // All other errors swallowed.
+    }
+  }
+}
+
+function formatStartLine(ev: ProgressEvent): string {
+  const emoji = TOOL_EMOJI[ev.tool] ?? '🔧'
+  if (ev.argsPreview && ev.argsPreview.length > 0) {
+    return `${emoji} ${ev.tool}: ${ev.argsPreview}`
+  }
+  return `${emoji} ${ev.tool}`
+}
+
+function capProgressText(text: string): string {
+  if (text.length <= PROGRESS_TEXT_CAP) return text
+  return `${text.slice(0, PROGRESS_TEXT_CAP - 1)}…`
+}
+
+export const PROGRESS_EDIT_INTERVAL = PROGRESS_EDIT_INTERVAL_MS

package/src/types.ts

@@ -79,6 +79,15 @@ export interface TelegramApprovalBridge {
   }
 }
 
+/** Tool-call lifecycle event observed by the TG dispatcher for live UI rendering. */
+export interface TelegramToolEvent {
+  kind: 'start' | 'end'
+  tool: string
+  callId: string
+  argsPreview?: string
+  ok?: boolean
+}
+
 export interface TelegramDispatchInput {
   /** Composed text after debounce flush; safe to feed into brain prompt. */
   text: string
@@ -94,6 +103,14 @@ export interface TelegramDispatchInput {
   latestMessageId: number
   /** Stable session key for this chat: `agent:<name>:telegram:dm:<chatId>`. */
   sessionKey: string
+  /**
+   * Per-turn observer of tool-call lifecycle. Listener supplies this so it
+   * can stream progress to a TG message as the brain works through the turn.
+   * Dispatch implementation (chat-telegram.ts in local mode, build-runtime.ts
+   * in sandbox mode) must forward this to `brain.infer({ onToolEvent: ... })`.
+   * Errors swallowed; observer must NEVER block dispatch.
+   */
+  onToolEvent?: (ev: TelegramToolEvent) => void
 }
 
 export interface TelegramDispatchResult {

package/src/typing.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'bun:test'
+import type { Bot } from 'grammy'
+import { TYPING_REFRESH_INTERVAL_MS, startTypingLoop } from './typing'
+
+function makeStubBot(callLog: { count: number; rejectOnce?: boolean }): Bot {
+  return {
+    api: {
+      sendChatAction: async (_chatId: number, action: string): Promise<true> => {
+        if (action !== 'typing') throw new Error(`unexpected action: ${action}`)
+        callLog.count += 1
+        if (callLog.rejectOnce) {
+          callLog.rejectOnce = false
+          throw new Error('429 too many requests')
+        }
+        return true as const
+      },
+    },
+  } as unknown as Bot
+}
+
+describe('startTypingLoop', () => {
+  it('fires sendChatAction immediately on start', () => {
+    const log = { count: 0 }
+    const bot = makeStubBot(log)
+    const stop = startTypingLoop(bot, 1234)
+    stop()
+    expect(log.count).toBe(1)
+  })
+
+  it('refreshes on the configured interval', async () => {
+    const log = { count: 0 }
+    const bot = makeStubBot(log)
+    const stop = startTypingLoop(bot, 1234)
+    // Wait 4.6s real time to see the immediate fire + first refresh.
+    await new Promise(r => setTimeout(r, TYPING_REFRESH_INTERVAL_MS + 100))
+    stop()
+    expect(log.count).toBeGreaterThanOrEqual(2)
+  })
+
+  it('cancel fn stops further refreshes', async () => {
+    const log = { count: 0 }
+    const bot = makeStubBot(log)
+    const stop = startTypingLoop(bot, 1234)
+    stop()
+    await new Promise(r => setTimeout(r, TYPING_REFRESH_INTERVAL_MS + 100))
+    expect(log.count).toBe(1)
+  })
+
+  it('survives sendChatAction failures', async () => {
+    const log = { count: 0, rejectOnce: true }
+    const bot = makeStubBot(log)
+    const stop = startTypingLoop(bot, 1234)
+    // First fire rejects (caught silently); subsequent refresh still happens.
+    await new Promise(r => setTimeout(r, TYPING_REFRESH_INTERVAL_MS + 100))
+    stop()
+    // Total fires: 1 (rejected) + 1 (refresh) = 2
+    expect(log.count).toBe(2)
+  })
+
+  it('cancel fn is idempotent', () => {
+    const log = { count: 0 }
+    const bot = makeStubBot(log)
+    const stop = startTypingLoop(bot, 1234)
+    stop()
+    stop() // second call should not throw
+    stop() // third call should not throw
+    expect(log.count).toBe(1)
+  })
+})

package/src/typing.ts

@@ -0,0 +1,31 @@
+/**
+ * Typing-indicator loop for the active brain turn. TG's `chat_action="typing"`
+ * auto-expires after ~5 seconds, so we refresh on a 4.5s interval. Fires once
+ * immediately so the user sees `typing...` within the first message-handler tick.
+ *
+ * Errors are swallowed: if `sendChatAction` rate-limits or fails the network
+ * call, the loop keeps running and the brain dispatch must NEVER block on a
+ * cosmetic indicator.
+ *
+ * Mirrors hermes' `_keep_typing` (gateway/platforms/base.py), but uses
+ * `setInterval` instead of an asyncio task. `clearInterval(timer)` from the
+ * returned cancel fn is idempotent.
+ */
+import type { Bot } from 'grammy'
+
+const TYPING_REFRESH_MS = 4_500
+
+export function startTypingLoop(bot: Bot, chatId: number): () => void {
+  const fire = (): void => {
+    void bot.api.sendChatAction(chatId, 'typing').catch(() => {
+      /* cosmetic; never block dispatch */
+    })
+  }
+  fire()
+  const timer = setInterval(fire, TYPING_REFRESH_MS)
+  return () => {
+    clearInterval(timer)
+  }
+}
+
+export const TYPING_REFRESH_INTERVAL_MS = TYPING_REFRESH_MS