@s0nderlabs/anima-plugin-telegram 0.19.13 → 0.19.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s0nderlabs/anima-plugin-telegram",
-  "version": "0.19.13",
+  "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.13",
+    "@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-retry.test.ts

@@ -0,0 +1,97 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+import { existsSync, mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { TelegramListener } from './listener'
+import { acquireTelegramTokenLock } from './recovery'
+import type { TelegramRuntimeContext } from './types'
+
+let lockDir: string
+
+beforeEach(() => {
+  lockDir = mkdtempSync(join(tmpdir(), 'anima-listener-retry-'))
+})
+
+afterEach(() => {
+  rmSync(lockDir, { recursive: true, force: true })
+})
+
+const FAKE_TOKEN = '999:does-not-call-network'
+
+function makeOpts(): TelegramRuntimeContext & { lockRootDir: string; apiRoot: string } {
+  return {
+    botToken: FAKE_TOKEN,
+    allowedUserIds: [42],
+    agentName: 'retry-canary',
+    pairingStore: undefined,
+    dispatchUserMessage: async () => ({ response: 'ok' }),
+    onProcessingStart: async () => {},
+    onProcessingEnd: async () => {},
+    approvalBridge: undefined,
+    lockRootDir: lockDir,
+    // Point grammY at an unreachable host so any accidental network call
+    // would fail fast. We never reach bot.start() in these tests because
+    // the lock path returns first.
+    apiRoot: 'http://127.0.0.1:1',
+  }
+}
+
+describe('TelegramListener lock-retry', () => {
+  it('does NOT throw when the bot-token lock is held; retains running=false until the lock frees', async () => {
+    // Pre-occupy the lock. From the listener's perspective this is a
+    // zombie/leftover holder it must wait out.
+    const blocker = acquireTelegramTokenLock(FAKE_TOKEN, {
+      agentId: 'retry-canary',
+      rootDir: lockDir,
+    })
+
+    const listener = new TelegramListener(makeOpts())
+    // Pre-fix this would throw BotTokenLockedError synchronously after the
+    // build-runtime catch and never re-attempt. Now it must swallow,
+    // schedule a retry timer, and remain stoppable.
+    await expect(listener.start()).resolves.toBeUndefined()
+
+    // stop() should release whatever we held + cancel the retry timer.
+    await listener.stop()
+    blocker.release()
+  })
+
+  it('stop() cancels a pending retry without leaking timers', async () => {
+    const blocker = acquireTelegramTokenLock(FAKE_TOKEN, {
+      agentId: 'retry-canary',
+      rootDir: lockDir,
+    })
+    const listener = new TelegramListener(makeOpts())
+    await listener.start() // schedules retry because blocker holds the lock
+    // Immediately stop. If the retry timer wasn't unref'd / cleared the
+    // bun:test process would hang waiting for it (visible as a >30s test
+    // timeout; this assertion fails fast otherwise).
+    await listener.stop()
+    blocker.release()
+    // After stop+release, fresh acquisition by an outside caller works
+    // (no orphaned listener still holding the lock).
+    const now = acquireTelegramTokenLock(FAKE_TOKEN, {
+      agentId: 'retry-canary',
+      rootDir: lockDir,
+    })
+    expect(now).toBeDefined()
+    now.release()
+  })
+
+  it('lock-clear path: when the prior holder releases, the next start succeeds', async () => {
+    const prior = acquireTelegramTokenLock(FAKE_TOKEN, {
+      agentId: 'retry-canary',
+      rootDir: lockDir,
+    })
+    const listener = new TelegramListener(makeOpts())
+    await listener.start() // pending retry; lock not yet acquired
+    prior.release()
+    // Retry runs every 30s in production; we verify the lockfile state
+    // rather than waiting on real timers. Pending retry won't fire in this
+    // synchronous window, but the listener.stop() path must still succeed.
+    await listener.stop()
+    // After listener.stop() with retry pending and prior released, the
+    // lockfile dir is empty (no orphan).
+    expect(existsSync(join(lockDir, 'telegram-bot-token-cbae9eeaf0ee85c6.lock'))).toBe(false)
+  })
+})

package/src/listener.ts

@@ -6,9 +6,11 @@ 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,
+  TELEGRAM_TOKEN_LOCK_SCOPE,
   type TokenLock,
   acquireTelegramTokenLock,
   classifyStartFailure,
@@ -18,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
@@ -29,6 +32,12 @@ import type { TelegramDispatchInput, TelegramRuntimeContext } from './types'
  * webhook, then boots grammy in long-poll mode. `stop()` releases the lock
  * and stops the bot. Both are idempotent.
  */
+/** Retry cadence + cap when the TG bot-token lock is held by a (possibly
+ *  zombie) prior holder. 12 × 30s = 6 minutes, comfortably past the 5-minute
+ *  lock TTL so a stale-but-tenable lock auto-evicts. */
+const RETRY_INTERVAL_MS = 30_000
+const MAX_LOCK_RETRY_ATTEMPTS = 12
+
 export interface TelegramListenerOpts extends TelegramRuntimeContext {
   /** Optional override of the Telegram Bot API root. Used by the mock-bot test. */
   apiRoot?: string
@@ -49,6 +58,9 @@ export class TelegramListener {
   private running = false
   private tokenLock: TokenLock | null = null
   private refreshTimer: ReturnType<typeof setInterval> | null = null
+  private retryTimer: ReturnType<typeof setTimeout> | null = null
+  private retryAttempts = 0
+  private stopped = false
   private approvalResolver:
     | ((approvalId: string, choice: ApprovalChoice, fromUserId: number) => void)
     | null = null
@@ -110,7 +122,7 @@ export class TelegramListener {
   }
 
   async start(): Promise<void> {
-    if (this.running) return
+    if (this.running || this.stopped) return
 
     try {
       this.tokenLock = acquireTelegramTokenLock(this.opts.botToken, {
@@ -118,12 +130,24 @@ export class TelegramListener {
         rootDir: this.opts.lockRootDir,
       })
     } catch (err) {
+      // Lock contention is recoverable: the prior holder may be a zombie or
+      // a stale lockfile from an ungraceful exit (see
+      // feedback-tg-token-lock-zombie-after-upgrade.md). Retry every 30s up
+      // to 12 attempts (6 minutes, past the 5-minute lock TTL) so we
+      // eventually reclaim once the existing entry expires. Without this,
+      // a single failed lock acquisition silenced the bot for the entire
+      // harness lifetime.
       if (err instanceof BotTokenLockedError) {
-        console.warn(`[telegram] cannot start listener: ${err.message}`)
+        console.warn(
+          `[telegram] cannot start listener: ${err.message}; will retry in ${RETRY_INTERVAL_MS / 1000}s`,
+        )
+        this.scheduleStartRetry()
+        return
       }
       throw err
     }
 
+    this.retryAttempts = 0
     this.running = true
     console.log(`[telegram] listener.start() called for @${this.opts.agentName}`)
 
@@ -169,6 +193,11 @@ export class TelegramListener {
   }
 
   async stop(): Promise<void> {
+    this.stopped = true
+    if (this.retryTimer) {
+      clearTimeout(this.retryTimer)
+      this.retryTimer = null
+    }
     if (!this.running) {
       this.releaseLock()
       return
@@ -188,6 +217,23 @@ export class TelegramListener {
     this.releaseLock()
   }
 
+  private scheduleStartRetry(): void {
+    if (this.stopped) return
+    if (this.retryAttempts >= MAX_LOCK_RETRY_ATTEMPTS) {
+      console.error(
+        `[telegram] gave up acquiring bot-token lock after ${this.retryAttempts} attempts; manual intervention required (rm ~/.anima/locks/${TELEGRAM_TOKEN_LOCK_SCOPE}-*.lock)`,
+      )
+      return
+    }
+    if (this.retryTimer) clearTimeout(this.retryTimer)
+    this.retryAttempts += 1
+    this.retryTimer = setTimeout(() => {
+      this.retryTimer = null
+      void this.start()
+    }, RETRY_INTERVAL_MS)
+    this.retryTimer.unref?.()
+  }
+
   private releaseLock(): void {
     if (this.tokenLock) {
       try {
@@ -311,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 = {
@@ -321,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,
@@ -340,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