@s0nderlabs/anima-plugin-telegram 0.24.17 → 0.26.0

package/package.json

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

package/src/listener-e2e.test.ts

@@ -0,0 +1,570 @@
+// End-to-end listener test against an in-process fake Telegram Bot API.
+//
+// Committed, CI-safe port of the gitignored test/local/e2e-telegram-mock.ts
+// script, EXTENDED with callback_query (inline-keyboard approval) coverage.
+//
+// What this exercises against the REAL `TelegramListener` (no live token, no
+// 0G, no real network):
+//   1. inbound message -> debounce -> dispatchUserMessage callback -> reply
+//   2. allowlist / pairing default-deny (unknown sender -> pairing code DM)
+//   3. MarkdownV2 translation (**bold** -> *bold*, inline code preserved) +
+//      long-message chunking with (i/N) suffixes
+//   4. NEW: callback_query (approval button tap) -> handleCallbackQuery ->
+//      approvalResolver resolves the pending approval with the mapped choice,
+//      answerCallbackQuery fires, and the message keyboard is cleaned up.
+//      Also covers the unauthorized-clicker reject path.
+//
+// HERMETIC: the fake Bot API binds on port 0 (OS-assigned). Each test uses a
+// UNIQUE random bot token (the listener takes a process-wide token lock keyed
+// by token) and a fresh lock dir, and stops the listener + releases the lock
+// in a finally block, so it never flakes under parallel runs.
+
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+import { mkdtempSync, rmSync } from 'node:fs'
+import http from 'node:http'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { PairingStore } from '@s0nderlabs/anima-core'
+import { buildApprovalKeyboard } from './approval-keyboard'
+import { TelegramListener } from './listener'
+import type { ApprovalChoiceKind, TelegramApprovalBridge, TelegramRuntimeContext } from './types'
+
+// ---------------------------------------------------------------------------
+// Fake Telegram Bot API server
+// ---------------------------------------------------------------------------
+
+interface SentMessage {
+  chatId: number
+  text: string
+  reply_markup?: unknown
+  parse_mode?: string
+}
+
+interface AnsweredCallback {
+  callbackQueryId: string
+  text?: string
+}
+
+interface EditedText {
+  chatId?: number
+  messageId?: number
+  text: string
+  reply_markup?: unknown
+}
+
+interface EditedReplyMarkup {
+  chatId?: number
+  messageId?: number
+  reply_markup?: unknown
+}
+
+interface MockServer {
+  url: string
+  sends: SentMessage[]
+  answeredCallbacks: AnsweredCallback[]
+  editedTexts: EditedText[]
+  editedReplyMarkups: EditedReplyMarkup[]
+  getDeleteWebhookCount: () => number
+  inject: (update: unknown) => void
+  stop: () => Promise<void>
+}
+
+async function startMockServer(): Promise<MockServer> {
+  const updates: unknown[] = []
+  let nextMessageId = 1
+  const sends: SentMessage[] = []
+  const answeredCallbacks: AnsweredCallback[] = []
+  const editedTexts: EditedText[] = []
+  const editedReplyMarkups: EditedReplyMarkup[] = []
+  let deletedWebhookCount = 0
+
+  const server = http.createServer(async (req, res) => {
+    const url = req.url ?? '/'
+    let body = ''
+    for await (const chunk of req) body += String(chunk)
+    const params = (() => {
+      try {
+        return JSON.parse(body || '{}') as Record<string, unknown>
+      } catch {
+        return {}
+      }
+    })()
+    const ok = (result: unknown): void => {
+      res.writeHead(200, { 'content-type': 'application/json' })
+      res.end(JSON.stringify({ ok: true, result }))
+    }
+
+    if (url.endsWith('/getMe')) {
+      ok({ id: 12345, is_bot: true, first_name: 'mock', username: 'mockbot' })
+      return
+    }
+    if (url.endsWith('/getUpdates')) {
+      ok(updates.splice(0, updates.length))
+      return
+    }
+    if (url.endsWith('/deleteWebhook')) {
+      deletedWebhookCount++
+      ok(true)
+      return
+    }
+    if (url.endsWith('/sendMessage')) {
+      sends.push({
+        chatId: Number(params.chat_id ?? 0),
+        text: String(params.text ?? ''),
+        reply_markup: params.reply_markup,
+        parse_mode: params.parse_mode as string | undefined,
+      })
+      ok({ message_id: nextMessageId++ })
+      return
+    }
+    if (url.endsWith('/answerCallbackQuery')) {
+      answeredCallbacks.push({
+        callbackQueryId: String(params.callback_query_id ?? ''),
+        text: params.text as string | undefined,
+      })
+      ok(true)
+      return
+    }
+    if (url.endsWith('/editMessageText')) {
+      editedTexts.push({
+        chatId: params.chat_id != null ? Number(params.chat_id) : undefined,
+        messageId: params.message_id != null ? Number(params.message_id) : undefined,
+        text: String(params.text ?? ''),
+        reply_markup: params.reply_markup,
+      })
+      // Telegram returns the edited Message object on success.
+      ok({ message_id: Number(params.message_id ?? 0), text: String(params.text ?? '') })
+      return
+    }
+    if (url.endsWith('/editMessageReplyMarkup')) {
+      editedReplyMarkups.push({
+        chatId: params.chat_id != null ? Number(params.chat_id) : undefined,
+        messageId: params.message_id != null ? Number(params.message_id) : undefined,
+        reply_markup: params.reply_markup,
+      })
+      ok({ message_id: Number(params.message_id ?? 0) })
+      return
+    }
+    // setMyCommands, setMessageReaction, sendChatAction, etc.
+    ok(true)
+  })
+
+  await new Promise<void>(r => server.listen(0, '127.0.0.1', () => r()))
+  const addr = server.address()
+  const port = typeof addr === 'object' && addr ? addr.port : 0
+
+  return {
+    url: `http://127.0.0.1:${port}`,
+    sends,
+    answeredCallbacks,
+    editedTexts,
+    editedReplyMarkups,
+    getDeleteWebhookCount: () => deletedWebhookCount,
+    inject: u => updates.push(u),
+    stop: () => new Promise<void>(r => server.close(() => r())),
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Unique token per run avoids the process-wide token-lock contention. */
+function uniqueToken(): string {
+  return `${Math.floor(Math.random() * 1e9)}:fake-${Math.random().toString(36).slice(2)}`
+}
+
+const sleep = (ms: number): Promise<void> => new Promise(r => setTimeout(r, ms))
+
+/** Poll until `pred()` is true or `timeoutMs` elapses. Avoids fixed sleeps. */
+async function waitFor(pred: () => boolean, timeoutMs = 4000): Promise<boolean> {
+  const start = Date.now()
+  while (Date.now() - start < timeoutMs) {
+    if (pred()) return true
+    await sleep(50)
+  }
+  return pred()
+}
+
+function injectMessage(
+  mock: MockServer,
+  opts: { updateId: number; fromId: number; chatId: number; messageId: number; text: string },
+): void {
+  mock.inject({
+    update_id: opts.updateId,
+    message: {
+      message_id: opts.messageId,
+      from: { id: opts.fromId, is_bot: false, username: 'op', first_name: 'Op' },
+      chat: { id: opts.chatId, type: 'private' },
+      date: Math.floor(Date.now() / 1000),
+      text: opts.text,
+    },
+  })
+}
+
+function injectCallbackQuery(
+  mock: MockServer,
+  opts: {
+    updateId: number
+    fromId: number
+    chatId: number
+    messageId: number
+    callbackData: string
+    messageText?: string | null
+  },
+): void {
+  const message: Record<string, unknown> = {
+    message_id: opts.messageId,
+    from: { id: 12345, is_bot: true, username: 'mockbot', first_name: 'mock' },
+    chat: { id: opts.chatId, type: 'private' },
+    date: Math.floor(Date.now() / 1000),
+    reply_markup: buildApprovalKeyboard(opts.callbackData.split(':')[2] ?? 'a-1'),
+  }
+  if (opts.messageText != null) message.text = opts.messageText
+  mock.inject({
+    update_id: opts.updateId,
+    callback_query: {
+      id: `cbq-${opts.updateId}`,
+      from: { id: opts.fromId, is_bot: false, username: 'op', first_name: 'Op' },
+      message,
+      chat_instance: 'ci-1',
+      data: opts.callbackData,
+    },
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Test rig
+// ---------------------------------------------------------------------------
+
+let lockDir: string
+let pairingDir: string
+const cleanups: Array<() => Promise<void> | void> = []
+
+beforeEach(() => {
+  lockDir = mkdtempSync(join(tmpdir(), 'anima-tg-e2e-lock-'))
+  pairingDir = mkdtempSync(join(tmpdir(), 'anima-tg-e2e-pairing-'))
+})
+
+afterEach(async () => {
+  // Tear down listeners + servers FIRST so the token lock is released and the
+  // server socket is closed before the next test (hermetic / no flake).
+  for (const fn of cleanups.splice(0, cleanups.length)) {
+    try {
+      await fn()
+    } catch {
+      /* best-effort teardown */
+    }
+  }
+  rmSync(lockDir, { recursive: true, force: true })
+  rmSync(pairingDir, { recursive: true, force: true })
+})
+
+interface Harness {
+  mock: MockServer
+  listener: TelegramListener
+}
+
+async function makeHarness(
+  overrides: Partial<TelegramRuntimeContext> & { approvalBridge?: TelegramApprovalBridge } = {},
+): Promise<Harness> {
+  const mock = await startMockServer()
+  const listener = new TelegramListener({
+    botToken: uniqueToken(),
+    apiRoot: mock.url,
+    allowedUserIds: [42],
+    agentName: 'e2e-agent',
+    // small debounce so the round-trip finishes fast in CI
+    debounceMs: 150,
+    dispatchUserMessage: async () => ({ response: 'pong' }),
+    ...overrides,
+    // lockRootDir is not part of TelegramRuntimeContext; merge after spread
+    lockRootDir: lockDir,
+  } as TelegramRuntimeContext & { apiRoot: string; lockRootDir: string; debounceMs: number })
+  cleanups.push(async () => {
+    await listener.stop()
+    await mock.stop()
+  })
+  return { mock, listener }
+}
+
+// ---------------------------------------------------------------------------
+// 1. Inbound message -> debounce -> dispatch -> reply round-trip
+// ---------------------------------------------------------------------------
+
+describe('TelegramListener e2e: inbound -> dispatch -> reply', () => {
+  it('debounces an inbound DM, dispatches the channel-wrapped text, and replies', async () => {
+    let dispatchedText = ''
+    const { mock, listener } = await makeHarness({
+      dispatchUserMessage: async input => {
+        dispatchedText = input.text
+        return { response: 'pong from brain' }
+      },
+    })
+    await listener.start()
+
+    expect(await waitFor(() => mock.getDeleteWebhookCount() >= 1)).toBe(true)
+
+    injectMessage(mock, {
+      updateId: 1001,
+      fromId: 42,
+      chatId: 42,
+      messageId: 1,
+      text: 'hello there',
+    })
+
+    expect(await waitFor(() => dispatchedText.length > 0)).toBe(true)
+    // dispatch receives the <channel>-wrapped untrusted text
+    expect(dispatchedText).toContain('hello there')
+    expect(dispatchedText).toContain('<channel')
+    expect(dispatchedText).toContain('source="telegram"')
+
+    const reply = await waitFor(() =>
+      mock.sends.some(s => s.chatId === 42 && s.text.includes('pong')),
+    )
+    expect(reply).toBe(true)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 2. Allowlist / pairing default-deny
+// ---------------------------------------------------------------------------
+
+describe('TelegramListener e2e: allowlist + pairing default-deny', () => {
+  it('drops a non-allowlisted sender with no pairing store (no reply at all)', async () => {
+    const { mock, listener } = await makeHarness({
+      allowedUserIds: [42],
+      pairingStore: undefined,
+    })
+    await listener.start()
+    expect(await waitFor(() => mock.getDeleteWebhookCount() >= 1)).toBe(true)
+
+    // stranger (id 7) is not in the allowlist -> dropped, no pairing store
+    injectMessage(mock, { updateId: 2001, fromId: 7, chatId: 7, messageId: 1, text: 'let me in' })
+
+    // give the listener time to process + (not) reply
+    await sleep(700)
+    expect(mock.sends.filter(s => s.chatId === 7)).toHaveLength(0)
+  })
+
+  it('sends a pairing code to an unknown sender when a pairing store is configured', async () => {
+    const store = new PairingStore({ dir: pairingDir })
+    const { mock, listener } = await makeHarness({
+      // empty allowlist + pairing store => unknown sender gets a pairing code
+      allowedUserIds: [],
+      pairingStore: store,
+    })
+    await listener.start()
+    expect(await waitFor(() => mock.getDeleteWebhookCount() >= 1)).toBe(true)
+
+    injectMessage(mock, { updateId: 2101, fromId: 555, chatId: 555, messageId: 1, text: 'hi' })
+
+    const got = await waitFor(() => mock.sends.some(s => s.chatId === 555))
+    expect(got).toBe(true)
+    const pairingMsg = mock.sends.find(s => s.chatId === 555)
+    expect(pairingMsg).toBeDefined()
+    // pairing message carries an 8-char code; assert a code-shaped token exists
+    expect(/[A-Z0-9]{8}/.test(pairingMsg?.text ?? '')).toBe(true)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 3. MarkdownV2 translation + chunking
+// ---------------------------------------------------------------------------
+
+describe('TelegramListener e2e: MarkdownV2 translation + chunking', () => {
+  it('translates **bold** -> *bold* and preserves inline code on the wire', async () => {
+    const { mock, listener } = await makeHarness({
+      allowedUserIds: [99],
+      dispatchUserMessage: async () => ({
+        response: 'Your balance: **0.0819 0G**. Wallet `0xd56b...9683`.',
+      }),
+    })
+    await listener.start()
+    expect(await waitFor(() => mock.getDeleteWebhookCount() >= 1)).toBe(true)
+
+    injectMessage(mock, { updateId: 3001, fromId: 99, chatId: 99, messageId: 1, text: 'balance?' })
+
+    const got = await waitFor(() =>
+      mock.sends.some(s => s.chatId === 99 && s.parse_mode === 'MarkdownV2'),
+    )
+    expect(got).toBe(true)
+    const body = mock.sends.find(s => s.chatId === 99)?.text ?? ''
+    expect(body).toContain('*0\\.0819 0G*') // **bold** -> *bold* (dot escaped)
+    expect(body).toContain('`0xd56b...9683`') // inline code preserved
+    expect(body).not.toContain('**') // no literal markdown bold left
+    expect(body).not.toContain('\\`') // inline-code backticks not escaped
+  })
+
+  it('splits a long reply into multiple chunks with (i/N) suffixes', async () => {
+    const longReply = 'paragraph '.repeat(900) // well over the 4096 TG cap
+    const { mock, listener } = await makeHarness({
+      allowedUserIds: [88],
+      dispatchUserMessage: async () => ({ response: longReply }),
+    })
+    await listener.start()
+    expect(await waitFor(() => mock.getDeleteWebhookCount() >= 1)).toBe(true)
+
+    injectMessage(mock, {
+      updateId: 3101,
+      fromId: 88,
+      chatId: 88,
+      messageId: 1,
+      text: 'tell me a lot',
+    })
+
+    const got = await waitFor(() => mock.sends.filter(s => s.chatId === 88).length >= 2, 6000)
+    expect(got).toBe(true)
+    const chunks = mock.sends.filter(s => s.chatId === 88)
+    expect(chunks.length).toBeGreaterThan(1)
+    // first + last chunk carry (i/N) ordinal suffixes. In MarkdownV2 the
+    // wrapping parens are backslash-escaped (`\(1/N\)`), so assert on the
+    // ordinal core that survives escaping.
+    expect(chunks[0]?.text).toContain(`1/${chunks.length}`)
+    expect(chunks[chunks.length - 1]?.text).toContain(`${chunks.length}/${chunks.length}`)
+    // sanity: the escaped-paren suffix shape is present on the last chunk
+    expect(chunks[chunks.length - 1]?.text).toContain(`\\(${chunks.length}/${chunks.length}\\)`)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 4. NEW: callback_query (inline approval button) resolution path
+// ---------------------------------------------------------------------------
+
+describe('TelegramListener e2e: callback_query approval resolution', () => {
+  /**
+   * Wire an approval bridge the way the gateway/chat dispatcher does:
+   * listener.start() fills `installCallbackHandler.current` with a registrar;
+   * we call it to install our resolver, which the pre-installed
+   * `callback_query:data` handler invokes on each click.
+   */
+  function makeBridge(): {
+    bridge: TelegramApprovalBridge
+    install: () => void
+    resolved: Array<{ approvalId: string; choice: ApprovalChoiceKind; fromUserId: number }>
+  } {
+    const resolved: Array<{ approvalId: string; choice: ApprovalChoiceKind; fromUserId: number }> =
+      []
+    const bridge: TelegramApprovalBridge = {
+      sendApproval: { current: null },
+      installCallbackHandler: { current: null },
+    }
+    const install = (): void => {
+      const registrar = bridge.installCallbackHandler.current
+      if (!registrar) throw new Error('installCallbackHandler not filled by listener.start()')
+      registrar((approvalId, choice, fromUserId) => {
+        resolved.push({ approvalId, choice, fromUserId })
+      })
+    }
+    return { bridge, install, resolved }
+  }
+
+  it('resolves a pending approval with the mapped choice and answers + clears the keyboard', async () => {
+    const { bridge, install, resolved } = makeBridge()
+    const { mock, listener } = await makeHarness({ allowedUserIds: [42], approvalBridge: bridge })
+    await listener.start()
+    // bridge slots are filled inside start(); install the resolver now
+    install()
+    expect(bridge.sendApproval.current).not.toBeNull()
+
+    // Operator taps "Session" on the approval keyboard for approval a-7.
+    injectCallbackQuery(mock, {
+      updateId: 4001,
+      fromId: 42,
+      chatId: 42,
+      messageId: 50,
+      callbackData: 'ea:session:a-7',
+      messageText: 'Approve shell.run? rm tmp file',
+    })
+
+    expect(await waitFor(() => resolved.length === 1)).toBe(true)
+    expect(resolved[0]).toEqual({ approvalId: 'a-7', choice: 'session', fromUserId: 42 })
+
+    // The handler answers the callback query (dismisses the phone spinner)
+    expect(await waitFor(() => mock.answeredCallbacks.length >= 1)).toBe(true)
+    expect(mock.answeredCallbacks.some(a => (a.text ?? '').includes('session'))).toBe(true)
+
+    // ...and visually resolves the modal: since the message had text, it edits
+    // the text and drops the inline keyboard.
+    expect(await waitFor(() => mock.editedTexts.length >= 1)).toBe(true)
+    const edit = mock.editedTexts.find(e => e.text.includes('Approve shell.run'))
+    expect(edit).toBeDefined()
+    expect(edit?.text).toContain('Allowed for session')
+    expect(edit?.reply_markup).toBeUndefined() // keyboard removed
+  })
+
+  it('maps each choice (once/always/deny) through to the resolver verbatim', async () => {
+    const cases: Array<{ data: string; choice: ApprovalChoiceKind; approvalId: string }> = [
+      { data: 'ea:once:a-1', choice: 'once', approvalId: 'a-1' },
+      { data: 'ea:always:a-2', choice: 'always', approvalId: 'a-2' },
+      { data: 'ea:deny:a-3', choice: 'deny', approvalId: 'a-3' },
+    ]
+    for (const c of cases) {
+      const { bridge, install, resolved } = makeBridge()
+      const { mock, listener } = await makeHarness({ allowedUserIds: [42], approvalBridge: bridge })
+      await listener.start()
+      install()
+      injectCallbackQuery(mock, {
+        updateId: 4100,
+        fromId: 42,
+        chatId: 42,
+        messageId: 60,
+        callbackData: c.data,
+        messageText: 'Approve a tool call?',
+      })
+      expect(await waitFor(() => resolved.length === 1)).toBe(true)
+      expect(resolved[0]).toEqual({ approvalId: c.approvalId, choice: c.choice, fromUserId: 42 })
+      // stop this harness before the next iteration so locks/servers free
+      await cleanups.splice(0, cleanups.length).reduce(async (p, fn) => {
+        await p
+        await fn()
+      }, Promise.resolve())
+    }
+  })
+
+  it('rejects an unauthorized clicker: answers with a denial, does NOT resolve, no keyboard edit', async () => {
+    const { bridge, install, resolved } = makeBridge()
+    const { mock, listener } = await makeHarness({ allowedUserIds: [42], approvalBridge: bridge })
+    await listener.start()
+    install()
+
+    // user 9999 is NOT in the allowlist; the click must be rejected
+    injectCallbackQuery(mock, {
+      updateId: 4200,
+      fromId: 9999,
+      chatId: 9999,
+      messageId: 70,
+      callbackData: 'ea:always:a-99',
+      messageText: 'Approve dangerous thing?',
+    })
+
+    expect(await waitFor(() => mock.answeredCallbacks.length >= 1)).toBe(true)
+    expect(mock.answeredCallbacks.some(a => (a.text ?? '').includes('not authorized'))).toBe(true)
+    // resolver was never invoked
+    expect(resolved).toHaveLength(0)
+    // and no message edit happened (modal untouched)
+    await sleep(300)
+    expect(mock.editedTexts).toHaveLength(0)
+    expect(mock.editedReplyMarkups).toHaveLength(0)
+  })
+
+  it('drops a malformed callback payload: answers, never resolves', async () => {
+    const { bridge, install, resolved } = makeBridge()
+    const { mock, listener } = await makeHarness({ allowedUserIds: [42], approvalBridge: bridge })
+    await listener.start()
+    install()
+
+    injectCallbackQuery(mock, {
+      updateId: 4300,
+      fromId: 42,
+      chatId: 42,
+      messageId: 80,
+      callbackData: 'garbage-not-an-approval',
+      messageText: 'whatever',
+    })
+
+    expect(await waitFor(() => mock.answeredCallbacks.length >= 1)).toBe(true)
+    expect(mock.answeredCallbacks.some(a => (a.text ?? '').includes('malformed'))).toBe(true)
+    expect(resolved).toHaveLength(0)
+  })
+})

package/src/listener.ts

@@ -64,7 +64,7 @@ export function formatApprovalResolution(choice: ApprovalChoice, byUserId: numbe
  * buttons rendered for tool approvals). Without `'callback_query'` here,
  * Telegram silently filters the click events out of `getUpdates`, the
  * `bot.on('callback_query:data', ...)` handler never fires, and operator
- * taps register on the device but never reach the harness — the modal
+ * taps register on the device but never reach the harness, the modal
  * appears stuck and the brain's tool call hangs until timeout.
  *
  * Latent bug from v0.18.0 (the introduction of inline-keyboard approvals);
@@ -172,7 +172,7 @@ export class TelegramListener {
     // Resolve the modal visually: append the choice + drop the inline
     // keyboard. Without this, every clicked approval message stays on
     // screen with all four buttons, leaving operators unsure whether
-    // their tap registered. Best-effort — if the edit fails (rate
+    // their tap registered. Best-effort, if the edit fails (rate
     // limit, message age, deleted), the underlying approval is still
     // resolved at the runtime level, so we swallow the error.
     const originalText =
@@ -185,7 +185,7 @@ export class TelegramListener {
         await ctx.editMessageReplyMarkup({ reply_markup: undefined })
       }
     } catch {
-      /* ignore — modal was clicked, runtime already resolved; keyboard cleanup is cosmetic */
+      /* ignore, modal was clicked, runtime already resolved; keyboard cleanup is cosmetic */
     }
   }
 
@@ -514,11 +514,15 @@ 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
+      // Translate a credit/ledger-exhaustion error into an actionable topup
+      // hint instead of the generic "something went wrong" reply. Detect by
+      // name (avoids importing core's typed classes): Direct throws
+      // LedgerInsufficientError ("anima topup --compute"), Router throws
+      // RouterCreditError ("anima topup --router"), both carry the actionable
+      // message, so surface it verbatim.
+      const errName = err instanceof Error ? err.name : ''
+      const isTopupHint = errName === 'LedgerInsufficientError' || errName === 'RouterCreditError'
+      const replyText = isTopupHint
         ? `⚠️ I need a top-up to keep working.\n\n${msg}`
         : 'sorry, something went wrong on my side. try again in a moment.'
       try {