@s0nderlabs/anima-plugin-telegram 0.19.1

package/src/sanitize.ts

@@ -0,0 +1,128 @@
+import type { PairingStore } from '@s0nderlabs/anima-core'
+import type { TelegramInboundEvent } from './types'
+
+/**
+ * MVP filter: only DMs from authorized users are dispatched. Group chat,
+ * channel posts, forwarded messages, and bot-to-bot messages are dropped.
+ *
+ * Authorization (hermes default-deny model):
+ *  - If `allowedUserIds` contains the sender, accept.
+ *  - Else if `pairingStore` is provided and the sender is approved, accept.
+ *  - Else if `pairingStore` is provided, generate a pairing code and return
+ *    `{ ok: false, action: 'send-pairing-code', code }` so the listener can
+ *    DM the code to the sender. The operator approves out-of-band via
+ *    `anima pairing approve telegram <code>`.
+ *  - Else (no allowlist + no pairing) reject with `no-allowlist-default-deny`.
+ *
+ * Returns null when the message should be dropped (with reason in debug logs).
+ * Returns a normalized TelegramInboundEvent when accepted.
+ */
+export interface SanitizeOpts {
+  allowedUserIds: number[]
+  /** Hard cap on text length. Default 2000 chars (TG max is 4096). */
+  maxTextLength?: number
+  /** Optional pairing store. When present, unknown senders get a pairing code. */
+  pairingStore?: Pick<PairingStore, 'isApproved' | 'generateCode'>
+  /** Platform key passed to pairingStore (always 'telegram' for this plugin). */
+  pairingPlatform?: string
+}
+
+export interface SanitizeInput {
+  chatType: 'private' | 'group' | 'supergroup' | 'channel'
+  chatId: number
+  fromId: number | null
+  fromIsBot: boolean
+  fromUsername: string | null
+  fromFirstName: string | null
+  fromLastName: string | null
+  text: string | null
+  messageId: number
+  forwardedFrom: unknown
+  mediaGroupId: string | null
+}
+
+export type SanitizeResult =
+  | { ok: true; event: TelegramInboundEvent }
+  | {
+      ok: false
+      reason: SanitizeReason
+      action?: 'send-pairing-code'
+      code?: string
+      pairedUserId?: number
+      pairedUserName?: string | null
+    }
+
+export type SanitizeReason =
+  | 'not-private-chat'
+  | 'sender-is-bot'
+  | 'sender-not-allowed'
+  | 'no-allowlist-default-deny'
+  | 'pairing-rate-limited'
+  | 'forwarded-message'
+  | 'no-text'
+  | 'no-sender-id'
+  | 'media-group'
+
+export function sanitizeInbound(input: SanitizeInput, opts: SanitizeOpts): SanitizeResult {
+  if (input.chatType !== 'private') return { ok: false, reason: 'not-private-chat' }
+  if (input.fromIsBot) return { ok: false, reason: 'sender-is-bot' }
+  if (input.fromId === null) return { ok: false, reason: 'no-sender-id' }
+  if (input.forwardedFrom != null) return { ok: false, reason: 'forwarded-message' }
+  if (input.mediaGroupId != null) return { ok: false, reason: 'media-group' }
+  if (typeof input.text !== 'string' || input.text.trim().length === 0) {
+    return { ok: false, reason: 'no-text' }
+  }
+
+  const platform = opts.pairingPlatform ?? 'telegram'
+  const inAllowlist = opts.allowedUserIds.includes(input.fromId)
+  const pairingApproved = opts.pairingStore?.isApproved(platform, String(input.fromId)) ?? false
+
+  if (!inAllowlist && !pairingApproved) {
+    if (opts.pairingStore) {
+      const code = opts.pairingStore.generateCode(
+        platform,
+        String(input.fromId),
+        input.fromUsername ?? formatDisplayName(input.fromFirstName, input.fromLastName) ?? '',
+      )
+      if (code) {
+        return {
+          ok: false,
+          reason: 'sender-not-allowed',
+          action: 'send-pairing-code',
+          code,
+          pairedUserId: input.fromId,
+          pairedUserName:
+            input.fromUsername ?? formatDisplayName(input.fromFirstName, input.fromLastName),
+        }
+      }
+      return { ok: false, reason: 'pairing-rate-limited' }
+    }
+    if (opts.allowedUserIds.length === 0) {
+      return { ok: false, reason: 'no-allowlist-default-deny' }
+    }
+    return { ok: false, reason: 'sender-not-allowed' }
+  }
+
+  const cap = opts.maxTextLength ?? 2000
+  let text = input.text
+  if (text.length > cap) text = `${text.slice(0, cap)}\n[message truncated]`
+  const displayName = formatDisplayName(input.fromFirstName, input.fromLastName)
+  return {
+    ok: true,
+    event: {
+      chatId: input.chatId,
+      userId: input.fromId,
+      username: input.fromUsername,
+      displayName,
+      text,
+      messageId: input.messageId,
+      ts: Date.now(),
+    },
+  }
+}
+
+function formatDisplayName(first: string | null, last: string | null): string | null {
+  const parts = [first, last].filter((s): s is string => typeof s === 'string' && s.length > 0)
+  if (parts.length === 0) return null
+  return parts.join(' ')
+}

package/src/session-key.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'bun:test'
+import { buildSessionKey, sanitizeAgentName } from './session-key'
+
+describe('buildSessionKey', () => {
+  it('DM key for vanilla agent name + chat id', () => {
+    expect(buildSessionKey({ agentName: 'specter', chatId: 12345 })).toBe(
+      'agent:specter:telegram:dm:12345',
+    )
+  })
+  it('group key with thread id', () => {
+    expect(
+      buildSessionKey({ agentName: 'enigma', chatId: -100123, threadId: 7, isGroup: true }),
+    ).toBe('agent:enigma:telegram:group:-100123:7')
+  })
+  it('group key without thread id falls back to thread 0', () => {
+    expect(buildSessionKey({ agentName: 'enigma', chatId: -100123, isGroup: true })).toBe(
+      'agent:enigma:telegram:group:-100123:0',
+    )
+  })
+  it('agent name is sanitized', () => {
+    expect(buildSessionKey({ agentName: 'Spec/t.er!', chatId: 1 })).toBe(
+      'agent:specter:telegram:dm:1',
+    )
+  })
+  it('empty agent name falls back to anima', () => {
+    expect(buildSessionKey({ agentName: '   ', chatId: 1 })).toBe('agent:anima:telegram:dm:1')
+  })
+})
+
+describe('sanitizeAgentName', () => {
+  it('lowercases', () => {
+    expect(sanitizeAgentName('SPECTER')).toBe('specter')
+  })
+  it('strips special chars', () => {
+    expect(sanitizeAgentName('foo.bar/baz!')).toBe('foobarbaz')
+  })
+  it('preserves hyphens', () => {
+    expect(sanitizeAgentName('foo-bar')).toBe('foo-bar')
+  })
+})

package/src/session-key.ts

@@ -0,0 +1,37 @@
+/**
+ * Pure helpers for building stable session keys per inbound surface. The brain
+ * prompt's `<channel source="telegram" chat="..." user="...">` wrapping uses
+ * these so memory writes can be partitioned per chat (future) and rate
+ * limiting can scope per chat.
+ *
+ * Format mirrors hermes:
+ *   agent:<name>:telegram:dm:<chatId>
+ *   agent:<name>:telegram:group:<chatId>:<threadId>     (post-MVP)
+ *
+ * Pure — no IO, no mutation. Safe to test exhaustively.
+ */
+export interface BuildSessionKeyInput {
+  agentName: string
+  chatId: number
+  threadId?: number
+  isGroup?: boolean
+}
+
+export function buildSessionKey(input: BuildSessionKeyInput): string {
+  const safeName = sanitizeAgentName(input.agentName)
+  if (input.isGroup) {
+    const t = input.threadId ?? 0
+    return `agent:${safeName}:telegram:group:${input.chatId}:${t}`
+  }
+  return `agent:${safeName}:telegram:dm:${input.chatId}`
+}
+
+/**
+ * Strip characters that would confuse memory paths or prompt parsing.
+ * Allow lowercase alpha + digits + hyphen only. Empty string falls back to
+ * "anima" so the key is always well-formed.
+ */
+export function sanitizeAgentName(raw: string): string {
+  const cleaned = raw.toLowerCase().replace(/[^a-z0-9-]/g, '')
+  return cleaned.length > 0 ? cleaned : 'anima'
+}

package/src/session-state.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it } from 'bun:test'
+import { ActiveSessionTracker, BYPASS_COMMANDS, parseBypassCommand } from './session-state'
+
+describe('parseBypassCommand', () => {
+  it('returns null for non-slash text', () => {
+    expect(parseBypassCommand('hello there')).toBeNull()
+    expect(parseBypassCommand('what time is it')).toBeNull()
+  })
+
+  it('matches each bypass command verbatim', () => {
+    for (const cmd of BYPASS_COMMANDS) {
+      expect(parseBypassCommand(cmd)).toBe(cmd)
+    }
+  })
+
+  it('is case-insensitive', () => {
+    expect(parseBypassCommand('/STOP')).toBe('/stop')
+    expect(parseBypassCommand('/Reset')).toBe('/reset')
+  })
+
+  it('ignores args after the command', () => {
+    expect(parseBypassCommand('/stop please')).toBe('/stop')
+    expect(parseBypassCommand('/new with arg')).toBe('/new')
+  })
+
+  it('returns null for unknown slash commands', () => {
+    expect(parseBypassCommand('/foobar')).toBeNull()
+    expect(parseBypassCommand('/help')).toBeNull()
+  })
+
+  it('returns null for empty text', () => {
+    expect(parseBypassCommand('')).toBeNull()
+    expect(parseBypassCommand('  ')).toBeNull()
+  })
+
+  it('strips leading whitespace', () => {
+    expect(parseBypassCommand('   /stop')).toBe('/stop')
+  })
+})
+
+describe('ActiveSessionTracker', () => {
+  it('isActive returns false initially', () => {
+    const t = new ActiveSessionTracker()
+    expect(t.isActive('a')).toBe(false)
+  })
+
+  it('markActive then markIdle round-trip', () => {
+    const t = new ActiveSessionTracker()
+    t.markActive('a')
+    expect(t.isActive('a')).toBe(true)
+    t.markIdle('a')
+    expect(t.isActive('a')).toBe(false)
+  })
+
+  it('different keys do not collide', () => {
+    const t = new ActiveSessionTracker()
+    t.markActive('a')
+    expect(t.isActive('b')).toBe(false)
+  })
+
+  it('abortActive calls the stored AbortController', () => {
+    const t = new ActiveSessionTracker()
+    const ctrl = new AbortController()
+    t.markActive('a', ctrl)
+    expect(t.abortActive('a')).toBe(true)
+    expect(ctrl.signal.aborted).toBe(true)
+  })
+
+  it('abortActive returns false when there is no active session', () => {
+    const t = new ActiveSessionTracker()
+    expect(t.abortActive('a')).toBe(false)
+  })
+
+  it('abortActive returns false when active session has no AbortController', () => {
+    const t = new ActiveSessionTracker()
+    t.markActive('a', null)
+    expect(t.abortActive('a')).toBe(false)
+  })
+
+  it('setPending / takePending one-shot', () => {
+    const t = new ActiveSessionTracker()
+    t.setPending('a', { kind: 'queued' })
+    expect(t.takePending('a')).toEqual({ kind: 'queued' })
+    expect(t.takePending('a')).toBeUndefined()
+  })
+
+  it('activeKeys lists all active session keys', () => {
+    const t = new ActiveSessionTracker()
+    t.markActive('a')
+    t.markActive('b')
+    expect(t.activeKeys().sort()).toEqual(['a', 'b'])
+  })
+
+  it('synchronous mark-active closes the race window', () => {
+    // Simulate two messages arriving in the same tick: only the first should
+    // see isActive=false; the second sees isActive=true even though no async
+    // work has started yet.
+    const t = new ActiveSessionTracker()
+    expect(t.isActive('a')).toBe(false)
+    t.markActive('a')
+    expect(t.isActive('a')).toBe(true)
+  })
+})

package/src/session-state.ts

@@ -0,0 +1,93 @@
+// Active-session tracker for telegram turns.
+//
+// Mirrors hermes base.py:1417-1488. The synchronous mark-active BEFORE async
+// dispatch is the load-bearing detail: without it, two messages in the same
+// event-loop tick can both pass the active-check and both spawn brain turns.
+//
+// Bypass commands (verbatim from hermes base.py:1430): /approve, /deny,
+// /status, /stop, /new, /reset, /background, /restart. These are dispatched
+// inline (skipping the active-session guard) so the operator can interrupt
+// or steer a turn that's already mid-flight from their phone.
+
+export const BYPASS_COMMANDS = [
+  '/stop',
+  '/new',
+  '/reset',
+  '/status',
+  '/approve',
+  '/deny',
+  '/background',
+  '/restart',
+] as const
+
+export type BypassCommand = (typeof BYPASS_COMMANDS)[number]
+
+/**
+ * Detect a bypass command at the start of an inbound message. Returns the
+ * canonical lowercase command if matched, else null. Args after the command
+ * (e.g. `/stop please`) are ignored — only the leading slash-token matters.
+ */
+export function parseBypassCommand(text: string): BypassCommand | null {
+  const trimmed = text.trim()
+  if (!trimmed.startsWith('/')) return null
+  const head = trimmed.split(/\s+/)[0]?.toLowerCase()
+  if (!head) return null
+  if ((BYPASS_COMMANDS as readonly string[]).includes(head)) {
+    return head as BypassCommand
+  }
+  return null
+}
+
+export interface ActiveSession {
+  abortCtrl: AbortController | null
+  startedAt: number
+}
+
+/**
+ * Per-session-key state machine. `markActive` MUST be called synchronously
+ * BEFORE any async dispatch (the race-window-closing detail). `markIdle`
+ * fires from the dispatch's `finally`. `setPending` queues an interrupt
+ * payload; the dispatcher reads it on the next iteration.
+ */
+export class ActiveSessionTracker {
+  readonly #sessions = new Map<string, ActiveSession>()
+  readonly #pending = new Map<string, unknown>()
+
+  isActive(key: string): boolean {
+    return this.#sessions.has(key)
+  }
+
+  markActive(key: string, abortCtrl: AbortController | null = null): void {
+    this.#sessions.set(key, { abortCtrl, startedAt: Date.now() })
+  }
+
+  markIdle(key: string): void {
+    this.#sessions.delete(key)
+  }
+
+  getAbortController(key: string): AbortController | null {
+    return this.#sessions.get(key)?.abortCtrl ?? null
+  }
+
+  /** Called by `/stop` bypass: aborts the active turn for `key` if any. */
+  abortActive(key: string): boolean {
+    const session = this.#sessions.get(key)
+    if (!session?.abortCtrl) return false
+    session.abortCtrl.abort()
+    return true
+  }
+
+  setPending(key: string, event: unknown): void {
+    this.#pending.set(key, event)
+  }
+
+  takePending(key: string): unknown | undefined {
+    const v = this.#pending.get(key)
+    this.#pending.delete(key)
+    return v
+  }
+
+  activeKeys(): string[] {
+    return Array.from(this.#sessions.keys())
+  }
+}

package/src/types.ts

@@ -0,0 +1,114 @@
+import type { PairingStore } from '@s0nderlabs/anima-core'
+
+/**
+ * Side-band runtime context for plugin-telegram. The CLI (chat.tsx, local
+ * mode) or harness (build-runtime.ts, sandbox mode) builds this and attaches
+ * it to the plugin context as `(ctx as any).telegram` before loadPlugins.
+ *
+ * Without this side-band, the plugin registers nothing (soft-init for unit
+ * tests / non-telegram contexts). Mirrors the comms / onchain pattern.
+ */
+export interface TelegramRuntimeContext {
+  /** Bot token from @BotFather, post-decryption. NEVER goes to activity log. */
+  botToken: string
+  /**
+   * Telegram user IDs allowed to DM this bot. Anyone else's messages are
+   * dropped silently (no reply, no reaction, no log entry beyond a debug line).
+   */
+  allowedUserIds: number[]
+  /**
+   * Agent's display name (e.g. "specter", "enigma"). Used in session-key
+   * formatting so each agent's TG context is distinct in the brain prompt.
+   */
+  agentName: string
+  /**
+   * Brain dispatch callback. The listener invokes this when a debounced inbound
+   * is ready. The CLI or harness implementation:
+   *   1. wraps `text` in a `<channel source="telegram" ...>` prompt fragment
+   *   2. fires brain.infer with `source: 'telegram'`
+   *   3. flushes per-turn sync
+   *   4. returns the assistant string for the listener to send back via TG
+   */
+  dispatchUserMessage: (input: TelegramDispatchInput) => Promise<TelegramDispatchResult>
+  /** Optional hook fired before reaction transitions to 👀. CLI may push a TUI row. */
+  onProcessingStart?: (chatId: number, messageId: number) => Promise<void> | void
+  /** Optional hook fired after reaction transitions to 👍/👎. */
+  onProcessingEnd?: (chatId: number, messageId: number, ok: boolean) => Promise<void> | void
+  /** Verbose grammy logs. Default false. */
+  debug?: boolean
+  /**
+   * Optional pairing store. When present, unknown senders get a pairing code
+   * via DM and the operator approves via `anima pairing approve telegram <code>`.
+   * When absent, the listener uses static allowlist only (default-deny on empty).
+   */
+  pairingStore?: PairingStore
+  /**
+   * Optional approval bridge. When present, the listener fills the inner
+   * `sendApproval` + `installCallbackHandler` slots on start so chat-telegram
+   * (or the harness build-runtime in sandbox mode) can swap a TG-side
+   * permission prompter at the start of a turn. When absent, the local TUI
+   * modal handles all approvals as before.
+   */
+  approvalBridge?: TelegramApprovalBridge
+}
+
+export type ApprovalChoiceKind = 'once' | 'session' | 'always' | 'deny'
+
+/**
+ * Mutable bridge object created by the dispatcher (chat-telegram or
+ * harness/build-runtime) and filled by the listener on start. The dispatcher
+ * holds the resolver Map; the listener holds the bot. They cooperate via this
+ * bridge so the inline-keyboard approval can roundtrip TG → brain → TG.
+ */
+export interface TelegramApprovalBridge {
+  /** Filled by listener.start(). Sends the approval inline keyboard. */
+  sendApproval: {
+    current: ((chatId: number, text: string, approvalId: string) => Promise<void>) | null
+  }
+  /**
+   * Filled by listener.start(). Lets the dispatcher install a single
+   * callback_query handler that the listener fans out per click. Returns
+   * an unregister function.
+   */
+  installCallbackHandler: {
+    current:
+      | ((
+          handler: (approvalId: string, choice: ApprovalChoiceKind, fromUserId: number) => void,
+        ) => () => void)
+      | null
+  }
+}
+
+export interface TelegramDispatchInput {
+  /** Composed text after debounce flush; safe to feed into brain prompt. */
+  text: string
+  /** TG numeric chat id (== user id for 1-on-1 DMs). */
+  chatId: number
+  /** TG numeric user id of the sender (always in `allowedUserIds`). */
+  userId: number
+  /** Display username of the sender (no `@` prefix), or null if unset. */
+  username: string | null
+  /** Display first/last name of the sender, or null. */
+  displayName: string | null
+  /** TG message id of the LATEST fragment in the debounced burst. Used for reactions. */
+  latestMessageId: number
+  /** Stable session key for this chat: `agent:<name>:telegram:dm:<chatId>`. */
+  sessionKey: string
+}
+
+export interface TelegramDispatchResult {
+  /** Assistant text to echo back to the user. Empty string skips the reply. */
+  response: string
+  /** Optional 0G mainnet sync tx hash, surfaced as a footer if non-empty. */
+  syncTx?: string
+}
+
+export interface TelegramInboundEvent {
+  chatId: number
+  userId: number
+  username: string | null
+  displayName: string | null
+  text: string
+  messageId: number
+  ts: number
+}