@s0nderlabs/anima-plugin-telegram 0.19.1

package/README.md

@@ -0,0 +1,43 @@
+# @s0nderlabs/anima-plugin-telegram
+
+Telegram gateway for anima. Operator DMs `@anima_<name>_bot` from any phone; the agent (running in 0G Sandbox or local) replies.
+
+## Highlights
+
+- **Long-poll outbound only.** Works in both Local and Sandbox modes without inbound port exposure.
+- **Allowlisted DMs.** Only configured `allowedUserIds` reach the brain.
+- **Reactions as feedback.** 👀 on processing start, 👍 on success, 👎 on error.
+- **Per-chat debounce.** 600ms quiet window collapses fragmented typing into one brain turn.
+- **Rate-limited.** 30 messages / 60s per user via token bucket.
+- **DM-only MVP.** Group / channel / forwarded messages dropped silently.
+- **Sandboxed handoff.** Bot token never leaves the operator's encrypted blob; harness receives via ECIES envelope.
+
+## Quickstart
+
+```
+anima telegram setup    # one-time interactive: bot token + allowed user IDs
+anima                   # start the TUI; listener boots automatically
+# DM @anima_<name>_bot from your phone — agent replies
+```
+
+## Architecture
+
+The plugin registers one listener (`telegram-bot`) on the gateway. The listener:
+
+1. Spins up a `grammy.Bot` with the operator's token in long-poll mode.
+2. On inbound DM from an allowed user, reactions go to 👀, the message is buffered through the per-chat debounce, then dispatched to the brain via `ctx.telegram.dispatchUserMessage(input)`.
+3. The brain runs a normal turn (refresh prefix, infer, tool calls, sync flush). Source label `'telegram'` flows into the prompt as `<channel source="telegram" chat="..." user="...">${text}</channel>`.
+4. On turn end, the assistant text is sent back via `bot.api.sendMessage`. Reaction transitions to 👍 (success) or 👎 (error).
+
+## Why grammy?
+
+TS-first, lightweight (~30KB minified), bun-compatible. Telegraf and python-telegram-bot are reasonable alternatives but not TS-first.
+
+## Out of scope (future)
+
+- Webhook mode (long-poll covers MVP needs)
+- Group chat support
+- Bot API 9.4 DM Topics (per-A2A-peer topic isolation)
+- Inline-keyboard exec approval (TG turns currently force `permission='off'`)
+- Voice transcription / TTS
+- DNS-over-HTTPS fallback IPs / proxy support

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@s0nderlabs/anima-plugin-telegram",
+  "version": "0.19.1",
+  "type": "module",
+  "description": "Telegram gateway plugin for anima — long-poll bot, debounced dispatch, reactions, allowlist",
+  "license": "MIT",
+  "homepage": "https://github.com/s0nderlabs/anima",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/s0nderlabs/anima.git",
+    "directory": "packages/plugin-telegram"
+  },
+  "bugs": {
+    "url": "https://github.com/s0nderlabs/anima/issues"
+  },
+  "keywords": ["0g", "anima", "agent", "telegram", "grammy", "gateway", "plugin"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.1"
+  },
+  "files": ["src", "README.md"],
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "build": "tsc -b",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@s0nderlabs/anima-core": "0.18.3",
+    "grammy": "^1.42.0",
+    "zod": "^3.23.8"
+  }
+}

package/src/approval-keyboard.test.ts

@@ -0,0 +1,142 @@
+import { describe, expect, it } from 'bun:test'
+import {
+  APPROVAL_CALLBACK_PREFIX,
+  buildApprovalKeyboard,
+  handleApprovalCallback,
+  makeApprovalIdFactory,
+  parseCallbackData,
+} from './approval-keyboard'
+
+describe('buildApprovalKeyboard', () => {
+  it('produces 4 buttons in 2 rows with the correct callback_data prefix', () => {
+    const k = buildApprovalKeyboard('a-1')
+    expect(k.inline_keyboard.length).toBe(2)
+    expect(k.inline_keyboard[0]!.length).toBe(2)
+    expect(k.inline_keyboard[1]!.length).toBe(2)
+    for (const row of k.inline_keyboard) {
+      for (const btn of row) {
+        const data = (btn as { callback_data?: string }).callback_data
+        expect(data).toMatch(new RegExp(`^${APPROVAL_CALLBACK_PREFIX}:`))
+        expect(data).toContain(':a-1')
+      }
+    }
+  })
+})
+
+describe('parseCallbackData', () => {
+  it('parses well-formed once callback', () => {
+    expect(parseCallbackData('ea:once:a-1')).toEqual({ choice: 'once', approvalId: 'a-1' })
+  })
+  it('parses session/always/deny', () => {
+    expect(parseCallbackData('ea:session:a-1')?.choice).toBe('session')
+    expect(parseCallbackData('ea:always:a-1')?.choice).toBe('always')
+    expect(parseCallbackData('ea:deny:a-1')?.choice).toBe('deny')
+  })
+  it('rejects malformed prefix', () => {
+    expect(parseCallbackData('xx:once:a-1')).toBeNull()
+  })
+  it('rejects malformed choice', () => {
+    expect(parseCallbackData('ea:nope:a-1')).toBeNull()
+  })
+  it('rejects empty string', () => {
+    expect(parseCallbackData('')).toBeNull()
+    expect(parseCallbackData(undefined)).toBeNull()
+  })
+})
+
+describe('handleApprovalCallback', () => {
+  function makePending() {
+    const pending = new Map<string, (choice: 'once' | 'session' | 'always' | 'deny') => void>()
+    let resolved: { id: string; choice: string } | null = null
+    pending.set('a-1', choice => {
+      resolved = { id: 'a-1', choice }
+    })
+    return { pending, getResolved: () => resolved }
+  }
+
+  it('resolves on first match + pops the entry', () => {
+    const { pending, getResolved } = makePending()
+    const r = handleApprovalCallback({
+      callbackData: 'ea:once:a-1',
+      fromUserId: 100,
+      allowedUserIds: [100],
+      pendingApprovals: pending,
+    })
+    expect(r.kind).toBe('resolved')
+    expect(getResolved()?.choice).toBe('once')
+    expect(pending.has('a-1')).toBe(false)
+  })
+
+  it('rejects unauthorized clicker', () => {
+    const { pending } = makePending()
+    const r = handleApprovalCallback({
+      callbackData: 'ea:once:a-1',
+      fromUserId: 999,
+      allowedUserIds: [100],
+      pendingApprovals: pending,
+    })
+    expect(r.kind).toBe('unauthorized')
+    expect(pending.has('a-1')).toBe(true)
+  })
+
+  it('marks unknown approvalId', () => {
+    const { pending } = makePending()
+    const r = handleApprovalCallback({
+      callbackData: 'ea:once:a-999',
+      fromUserId: 100,
+      allowedUserIds: [100],
+      pendingApprovals: pending,
+    })
+    expect(r.kind).toBe('unknown-approval')
+  })
+
+  it('marks malformed callback', () => {
+    const { pending } = makePending()
+    const r = handleApprovalCallback({
+      callbackData: 'garbage',
+      fromUserId: 100,
+      allowedUserIds: [100],
+      pendingApprovals: pending,
+    })
+    expect(r.kind).toBe('malformed')
+  })
+
+  it('allows all when allowedUserIds is empty (pairing-only mode)', () => {
+    const { pending } = makePending()
+    const r = handleApprovalCallback({
+      callbackData: 'ea:once:a-1',
+      fromUserId: 9999,
+      allowedUserIds: [],
+      pendingApprovals: pending,
+    })
+    // Callers with empty allowedUserIds rely on the listener-side pairing
+    // gate, so callback re-validation is permissive here.
+    expect(r.kind).toBe('resolved')
+  })
+
+  it('second click on same approvalId returns unknown-approval', () => {
+    const { pending } = makePending()
+    handleApprovalCallback({
+      callbackData: 'ea:once:a-1',
+      fromUserId: 100,
+      allowedUserIds: [100],
+      pendingApprovals: pending,
+    })
+    const second = handleApprovalCallback({
+      callbackData: 'ea:once:a-1',
+      fromUserId: 100,
+      allowedUserIds: [100],
+      pendingApprovals: pending,
+    })
+    expect(second.kind).toBe('unknown-approval')
+  })
+})
+
+describe('makeApprovalIdFactory', () => {
+  it('returns monotonically increasing ids', () => {
+    const next = makeApprovalIdFactory()
+    expect(next()).toBe('a-1')
+    expect(next()).toBe('a-2')
+    expect(next()).toBe('a-3')
+  })
+})

package/src/approval-keyboard.ts

@@ -0,0 +1,108 @@
+// Inline-keyboard approval for tool calls when the active session is on TG.
+//
+// Pattern from hermes telegram.py:1080-1132 (button layout) + 1462-1473
+// (callback re-validation). 4 buttons in 2 rows: Once / Session / Always /
+// Deny. Callback data format: `ea:<once|session|always|deny>:<approvalId>`.
+//
+// The handler re-validates the clicker against `allowedUserIds` because
+// inline-keyboard buttons are visible to any chat-member but only authorized
+// users may click. One-shot pop pattern: the resolver Map drops the entry
+// after the first match so a stale double-click can't re-resolve.
+
+import type { InlineKeyboardMarkup } from 'grammy/types'
+
+export type ApprovalChoice = 'once' | 'session' | 'always' | 'deny'
+
+export const APPROVAL_CALLBACK_PREFIX = 'ea'
+
+export function buildApprovalKeyboard(approvalId: string): InlineKeyboardMarkup {
+  return {
+    inline_keyboard: [
+      [
+        { text: '✅ Allow Once', callback_data: makeCallbackData('once', approvalId) },
+        { text: '✅ Session', callback_data: makeCallbackData('session', approvalId) },
+      ],
+      [
+        { text: '✅ Always', callback_data: makeCallbackData('always', approvalId) },
+        { text: '❌ Deny', callback_data: makeCallbackData('deny', approvalId) },
+      ],
+    ],
+  }
+}
+
+function makeCallbackData(choice: ApprovalChoice, approvalId: string): string {
+  // 64-byte callback_data limit — approvalId must stay short. We use a
+  // monotonic counter (e.g. `a-12345`) so well within budget.
+  return `${APPROVAL_CALLBACK_PREFIX}:${choice}:${approvalId}`
+}
+
+export interface ParsedCallback {
+  choice: ApprovalChoice
+  approvalId: string
+}
+
+export function parseCallbackData(data: string | undefined): ParsedCallback | null {
+  if (!data) return null
+  const parts = data.split(':')
+  if (parts.length !== 3) return null
+  if (parts[0] !== APPROVAL_CALLBACK_PREFIX) return null
+  const choice = parts[1]
+  const approvalId = parts[2]
+  if (
+    !approvalId ||
+    (choice !== 'once' && choice !== 'session' && choice !== 'always' && choice !== 'deny')
+  ) {
+    return null
+  }
+  return { choice: choice as ApprovalChoice, approvalId }
+}
+
+export type ResolveOutcome =
+  | { kind: 'resolved'; approvalId: string; choice: ApprovalChoice; clicker: number }
+  | { kind: 'unauthorized'; approvalId: string; clicker: number }
+  | { kind: 'unknown-approval'; approvalId: string; clicker: number }
+  | { kind: 'malformed' }
+
+export interface HandleCallbackInput {
+  callbackData: string | undefined
+  fromUserId: number
+  allowedUserIds: number[]
+  pendingApprovals: Map<string, (choice: ApprovalChoice) => void>
+}
+
+/**
+ * Decide what to do with a `callback_query`. The bot handler should call this
+ * pure function then `answerCallbackQuery` based on the outcome.
+ */
+export function handleApprovalCallback(input: HandleCallbackInput): ResolveOutcome {
+  const parsed = parseCallbackData(input.callbackData)
+  if (!parsed) return { kind: 'malformed' }
+
+  if (input.allowedUserIds.length > 0 && !input.allowedUserIds.includes(input.fromUserId)) {
+    return { kind: 'unauthorized', approvalId: parsed.approvalId, clicker: input.fromUserId }
+  }
+
+  const resolver = input.pendingApprovals.get(parsed.approvalId)
+  if (!resolver) {
+    return { kind: 'unknown-approval', approvalId: parsed.approvalId, clicker: input.fromUserId }
+  }
+
+  // One-shot pop closes the race against double-clicks
+  input.pendingApprovals.delete(parsed.approvalId)
+  resolver(parsed.choice)
+  return {
+    kind: 'resolved',
+    approvalId: parsed.approvalId,
+    choice: parsed.choice,
+    clicker: input.fromUserId,
+  }
+}
+
+/**
+ * Mint a new approval id. Monotonic counter as a string so callback_data
+ * stays short. Caller seeds and increments.
+ */
+export function makeApprovalIdFactory(): () => string {
+  let next = 1
+  return () => `a-${next++}`
+}

package/src/chunking.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'bun:test'
+import { escapeChunkSuffixForMarkdownV2, splitMessage } from './chunking'
+
+describe('splitMessage', () => {
+  it('returns the input unchanged when shorter than maxLen', () => {
+    const r = splitMessage('hello world', { maxLen: 100 })
+    expect(r).toEqual(['hello world'])
+  })
+
+  it('splits into multiple chunks with (N/N) suffix', () => {
+    const text = 'word '.repeat(2000)
+    const r = splitMessage(text, { maxLen: 1000 })
+    expect(r.length).toBeGreaterThan(1)
+    for (let i = 0; i < r.length; i++) {
+      expect(r[i]).toMatch(new RegExp(`\\(${i + 1}/${r.length}\\)$`))
+    }
+  })
+
+  it('omits suffix when numbered=false', () => {
+    const text = 'x'.repeat(5000)
+    const r = splitMessage(text, { maxLen: 1000, numbered: false })
+    expect(r.length).toBeGreaterThan(1)
+    for (const c of r) expect(c).not.toMatch(/\(\d+\/\d+\)$/)
+  })
+
+  it('preserves total content across chunks (modulo whitespace at split points)', () => {
+    const text = 'hello '.repeat(1000)
+    const r = splitMessage(text, { maxLen: 500, numbered: false })
+    const reassembled = r.join(' ').replace(/\s+/g, ' ').trim()
+    expect(reassembled.split(' ').length).toBe(1000)
+  })
+
+  it('avoids splitting inside fenced code blocks', () => {
+    const code = `\`\`\`\n${'line\n'.repeat(100)}\`\`\``
+    const text = `intro\n${code}\noutro`
+    const r = splitMessage(text, { maxLen: 200, numbered: false })
+    const opens = r.filter(c => c.includes('```'))
+    expect(opens.length % 2).toBe(0)
+  })
+
+  it('handles single huge token without spaces', () => {
+    const text = 'x'.repeat(10000)
+    const r = splitMessage(text, { maxLen: 1000 })
+    expect(r.length).toBe(10)
+  })
+
+  it('returns one element when text length exactly equals maxLen', () => {
+    const text = 'x'.repeat(100)
+    const r = splitMessage(text, { maxLen: 100 })
+    expect(r).toEqual([text])
+  })
+})
+
+describe('escapeChunkSuffixForMarkdownV2', () => {
+  it('escapes parens in the suffix', () => {
+    expect(escapeChunkSuffixForMarkdownV2('hello (1/2)')).toBe('hello \\(1/2\\)')
+    expect(escapeChunkSuffixForMarkdownV2('hello (10/10)')).toBe('hello \\(10/10\\)')
+  })
+
+  it('leaves text without suffix untouched', () => {
+    expect(escapeChunkSuffixForMarkdownV2('hello world')).toBe('hello world')
+  })
+})

package/src/chunking.ts

@@ -0,0 +1,63 @@
+// Long-message chunking with (1/N) (2/N) suffix.
+//
+// Pattern from hermes telegram.py:829-836. Telegram's hard limit is 4096
+// characters per message. We split at 4000 (leave room for the suffix) and
+// attach `(1/N)` `(2/N)` `(N/N)` to each chunk. We avoid breaking inside
+// fenced code blocks so the runtime grammar stays intact across chunks.
+
+const DEFAULT_MAX_LEN = 4000
+
+export interface SplitOpts {
+  maxLen?: number
+  /** Add `(1/N)` suffixes to multi-chunk output. Default true. */
+  numbered?: boolean
+}
+
+export function splitMessage(text: string, opts: SplitOpts = {}): string[] {
+  const maxLen = opts.maxLen ?? DEFAULT_MAX_LEN
+  const numbered = opts.numbered ?? true
+
+  if (text.length <= maxLen) return [text]
+
+  const chunks: string[] = []
+  let cursor = 0
+  while (cursor < text.length) {
+    let end = Math.min(cursor + maxLen, text.length)
+
+    // Avoid splitting inside a fenced code block — if there's an unclosed
+    // ``` between cursor and end, back up to the last newline before end.
+    if (end < text.length) {
+      const segment = text.slice(cursor, end)
+      const fencesInSegment = (segment.match(/```/g) || []).length
+      if (fencesInSegment % 2 === 1) {
+        const lastNewline = text.lastIndexOf('\n', end - 1)
+        if (lastNewline > cursor) end = lastNewline
+      } else {
+        // Prefer to split on word boundary when possible
+        const lastSpace = text.lastIndexOf(' ', end)
+        const lastNewline = text.lastIndexOf('\n', end)
+        const splitAt = Math.max(lastSpace, lastNewline)
+        if (splitAt > cursor + Math.floor(maxLen / 2)) {
+          end = splitAt
+        }
+      }
+    }
+
+    chunks.push(text.slice(cursor, end))
+    cursor = end
+    // Skip the leading whitespace at the new cursor (we split on it)
+    while (cursor < text.length && (text[cursor] === ' ' || text[cursor] === '\n')) cursor++
+  }
+
+  if (!numbered || chunks.length === 1) return chunks
+  const total = chunks.length
+  return chunks.map((c, i) => `${c} (${i + 1}/${total})`)
+}
+
+/**
+ * If a chunk is going through MarkdownV2 mode, the parens in `(N/N)` need to
+ * be escaped. Hermes telegram.py:836.
+ */
+export function escapeChunkSuffixForMarkdownV2(text: string): string {
+  return text.replace(/\s\((\d+)\/(\d+)\)$/, ' \\($1/$2\\)')
+}

package/src/debounce.test.ts

@@ -0,0 +1,140 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+import { DebounceBuffer, type FlushedBatch } from './debounce'
+
+describe('DebounceBuffer', () => {
+  let originalSetTimeout: typeof setTimeout
+  let originalClearTimeout: typeof clearTimeout
+  let scheduled: { fn: () => void; delay: number; id: number }[] = []
+  let nextId = 1
+
+  beforeEach(() => {
+    originalSetTimeout = global.setTimeout
+    originalClearTimeout = global.clearTimeout
+    scheduled = []
+    nextId = 1
+    global.setTimeout = ((fn: () => void, delay: number) => {
+      const id = nextId++
+      scheduled.push({ fn, delay, id })
+      return id as unknown as ReturnType<typeof setTimeout>
+    }) as typeof setTimeout
+    global.clearTimeout = ((id: number) => {
+      scheduled = scheduled.filter(s => s.id !== id)
+    }) as typeof clearTimeout
+  })
+
+  afterEach(() => {
+    global.setTimeout = originalSetTimeout
+    global.clearTimeout = originalClearTimeout
+  })
+
+  function fragment(
+    overrides: Partial<{
+      text: string
+      messageId: number
+      ts: number
+      userId: number
+      username: string | null
+      displayName: string | null
+    }> = {},
+  ) {
+    return {
+      text: overrides.text ?? 'hi',
+      messageId: overrides.messageId ?? 1,
+      ts: overrides.ts ?? 1,
+      userId: overrides.userId ?? 100,
+      username: overrides.username ?? null,
+      displayName: overrides.displayName ?? null,
+    }
+  }
+
+  function fireLatestTimer(): void {
+    const last = scheduled.pop()
+    if (last) last.fn()
+  }
+
+  it('coalesces rapid fragments into one batch', () => {
+    const flushed: { chatId: number; batch: FlushedBatch }[] = []
+    const buf = new DebounceBuffer((chatId, batch) => flushed.push({ chatId, batch }), {
+      quietPeriodMs: 100,
+    })
+    buf.push(1, fragment({ text: 'hello', messageId: 1, ts: 100 }))
+    buf.push(1, fragment({ text: 'world', messageId: 2, ts: 200 }))
+    buf.push(1, fragment({ text: '!', messageId: 3, ts: 300 }))
+    expect(flushed).toHaveLength(0)
+    fireLatestTimer()
+    expect(flushed).toHaveLength(1)
+    expect(flushed[0]!.chatId).toBe(1)
+    expect(flushed[0]!.batch.text).toBe('hello\nworld\n!')
+    expect(flushed[0]!.batch.fragmentCount).toBe(3)
+    expect(flushed[0]!.batch.latestMessageId).toBe(3)
+  })
+
+  it('keeps separate buffers per chat', () => {
+    const flushed: { chatId: number; batch: FlushedBatch }[] = []
+    const buf = new DebounceBuffer((chatId, batch) => flushed.push({ chatId, batch }), {
+      quietPeriodMs: 100,
+    })
+    buf.push(1, fragment({ text: 'a' }))
+    buf.push(2, fragment({ text: 'b' }))
+    expect(flushed).toHaveLength(0)
+    expect(scheduled).toHaveLength(2)
+    while (scheduled.length > 0) fireLatestTimer()
+    expect(flushed).toHaveLength(2)
+    expect(flushed.find(f => f.chatId === 1)?.batch.text).toBe('a')
+    expect(flushed.find(f => f.chatId === 2)?.batch.text).toBe('b')
+  })
+
+  it('forced flush via flushAll', () => {
+    const flushed: { chatId: number; batch: FlushedBatch }[] = []
+    const buf = new DebounceBuffer((chatId, batch) => flushed.push({ chatId, batch }))
+    buf.push(1, fragment({ text: 'pending' }))
+    buf.flushAll()
+    expect(flushed).toHaveLength(1)
+    expect(flushed[0]!.batch.text).toBe('pending')
+  })
+
+  it('exceeding maxBufferChars triggers immediate flush', () => {
+    const flushed: { chatId: number; batch: FlushedBatch }[] = []
+    const buf = new DebounceBuffer((chatId, batch) => flushed.push({ chatId, batch }), {
+      maxBufferChars: 10,
+    })
+    buf.push(1, fragment({ text: 'aaaaa', messageId: 1, ts: 1 }))
+    buf.push(1, fragment({ text: 'bbbbbb', messageId: 2, ts: 2 }))
+    expect(flushed).toHaveLength(1)
+    expect(flushed[0]!.batch.text).toBe('aaaaa\nbbbbbb')
+  })
+
+  it('uses quietPeriodMs delay for short fragments', () => {
+    const buf = new DebounceBuffer(() => {}, {
+      quietPeriodMs: 600,
+      adaptiveDelayMs: 2000,
+      adaptiveSplitThreshold: 4000,
+    })
+    buf.push(1, fragment({ text: 'short' }))
+    expect(scheduled[0]!.delay).toBe(600)
+  })
+
+  it('uses adaptiveDelayMs delay when last fragment exceeds threshold', () => {
+    const buf = new DebounceBuffer(() => {}, {
+      quietPeriodMs: 600,
+      adaptiveDelayMs: 2000,
+      adaptiveSplitThreshold: 100,
+    })
+    const longText = 'x'.repeat(150)
+    buf.push(1, fragment({ text: longText }))
+    expect(scheduled[0]!.delay).toBe(2000)
+  })
+
+  it('FlushedBatch carries userId, username, displayName from the last fragment', () => {
+    const flushed: { chatId: number; batch: FlushedBatch }[] = []
+    const buf = new DebounceBuffer((chatId, batch) => flushed.push({ chatId, batch }), {
+      quietPeriodMs: 100,
+    })
+    buf.push(1, fragment({ text: 'a', userId: 111, username: 'alice', displayName: 'Alice' }))
+    buf.push(1, fragment({ text: 'b', userId: 111, username: 'alice', displayName: 'Alice' }))
+    fireLatestTimer()
+    expect(flushed[0]!.batch.userId).toBe(111)
+    expect(flushed[0]!.batch.username).toBe('alice')
+    expect(flushed[0]!.batch.displayName).toBe('Alice')
+  })
+})