@s0nderlabs/anima-plugin-telegram 0.19.1

package/src/recovery.test.ts

@@ -0,0 +1,121 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import {
+  BotTokenLockedError,
+  acquireTelegramTokenLock,
+  classifyStartFailure,
+  clearWebhookBeforePolling,
+} from './recovery'
+
+let lockDir: string
+
+beforeEach(() => {
+  lockDir = mkdtempSync(join(tmpdir(), 'anima-recovery-test-'))
+})
+
+afterEach(() => {
+  rmSync(lockDir, { recursive: true, force: true })
+})
+
+describe('acquireTelegramTokenLock', () => {
+  it('returns release/refresh handle when nothing else holds the token', () => {
+    const lock = acquireTelegramTokenLock('123:fake-token-a', { rootDir: lockDir })
+    expect(lock.release).toBeFunction()
+    expect(lock.refresh).toBeFunction()
+    expect(lock.refresh()).toBe(true)
+    lock.release()
+  })
+
+  it('throws BotTokenLockedError when the same token is held', () => {
+    const a = acquireTelegramTokenLock('123:fake-token-a', { rootDir: lockDir })
+    expect(() => acquireTelegramTokenLock('123:fake-token-a', { rootDir: lockDir })).toThrow(
+      BotTokenLockedError,
+    )
+    a.release()
+  })
+
+  it('different tokens do not collide', () => {
+    const a = acquireTelegramTokenLock('111:token-x', { rootDir: lockDir })
+    const b = acquireTelegramTokenLock('222:token-y', { rootDir: lockDir })
+    expect(a).toBeDefined()
+    expect(b).toBeDefined()
+    a.release()
+    b.release()
+  })
+
+  it('release allows re-acquire by another caller', () => {
+    const a = acquireTelegramTokenLock('agent:t', { rootDir: lockDir })
+    a.release()
+    const b = acquireTelegramTokenLock('agent:t', { rootDir: lockDir })
+    expect(b).toBeDefined()
+    b.release()
+  })
+})
+
+describe('classifyStartFailure', () => {
+  it('classifies error_code 409 as conflict + retryable', () => {
+    const v = classifyStartFailure({ error_code: 409, message: 'Conflict' })
+    expect(v.kind).toBe('conflict')
+    expect(v.retryable).toBe(true)
+  })
+
+  it('classifies error_code 401 as auth + non-retryable', () => {
+    const v = classifyStartFailure({ error_code: 401, message: 'Unauthorized' })
+    expect(v.kind).toBe('auth')
+    expect(v.retryable).toBe(false)
+  })
+
+  it('classifies ECONNRESET as network + retryable', () => {
+    const v = classifyStartFailure(new Error('connect ECONNRESET 1.2.3.4'))
+    expect(v.kind).toBe('network')
+    expect(v.retryable).toBe(true)
+  })
+
+  it('classifies socket hang up as network', () => {
+    const v = classifyStartFailure(new Error('socket hang up'))
+    expect(v.kind).toBe('network')
+  })
+
+  it('classifies aborted as cancelled', () => {
+    const v = classifyStartFailure(new Error('AbortError: aborted'))
+    expect(v.kind).toBe('cancelled')
+    expect(v.retryable).toBe(false)
+  })
+
+  it('falls through to fatal for unknown errors', () => {
+    const v = classifyStartFailure(new Error('something weird'))
+    expect(v.kind).toBe('fatal')
+    expect(v.retryable).toBe(false)
+  })
+})
+
+describe('clearWebhookBeforePolling', () => {
+  it('calls bot.api.deleteWebhook with drop_pending_updates=false', async () => {
+    let called = false
+    let receivedArgs: unknown
+    const fakeBot = {
+      api: {
+        deleteWebhook: async (args: unknown) => {
+          called = true
+          receivedArgs = args
+        },
+      },
+    }
+    await clearWebhookBeforePolling(fakeBot as never)
+    expect(called).toBe(true)
+    expect(receivedArgs).toEqual({ drop_pending_updates: false })
+  })
+
+  it('swallows deleteWebhook errors', async () => {
+    const fakeBot = {
+      api: {
+        deleteWebhook: async () => {
+          throw new Error('telegram down')
+        },
+      },
+    }
+    await expect(clearWebhookBeforePolling(fakeBot as never)).resolves.toBeUndefined()
+  })
+})

package/src/recovery.ts

@@ -0,0 +1,105 @@
+// Listener recovery primitives.
+//
+// Token lock: only one anima process per machine can poll a given bot token.
+// Cross-machine collisions (laptop + sandbox both polling same bot) still
+// produce 409 Conflict on bot.start. We classify those failures so callers
+// can decide retry/abort. The 3-retry-409 + 10-retry-network state machines
+// hermes runs internally are deferred to v0.19 when we adopt @grammyjs/runner
+// for finer-grained polling control. For v0.18.x the lock plus explicit
+// classification is sufficient.
+
+import {
+  DEFAULT_LOCK_TTL_SECONDS,
+  type ScopedLockHandle,
+  acquireScopedLock,
+} from '@s0nderlabs/anima-core'
+import type { Bot } from 'grammy'
+
+export const TELEGRAM_TOKEN_LOCK_SCOPE = 'telegram-bot-token'
+
+export class BotTokenLockedError extends Error {
+  readonly heldByPid: number
+  readonly heldSinceSec: number
+  constructor(pid: number, sinceSec: number) {
+    super(`telegram bot token already in use by pid ${pid} (started ${sinceSec})`)
+    this.name = 'BotTokenLockedError'
+    this.heldByPid = pid
+    this.heldSinceSec = sinceSec
+  }
+}
+
+export interface AcquireTokenLockOpts {
+  agentId?: string
+  ttl?: number
+  rootDir?: string
+}
+
+export interface TokenLock {
+  release: () => void
+  refresh: () => boolean
+}
+
+export function acquireTelegramTokenLock(
+  botToken: string,
+  opts: AcquireTokenLockOpts = {},
+): TokenLock {
+  const identity = `${opts.agentId ?? 'default'}:${botToken}`
+  const result = acquireScopedLock({
+    scope: TELEGRAM_TOKEN_LOCK_SCOPE,
+    identity,
+    ttl: opts.ttl ?? DEFAULT_LOCK_TTL_SECONDS,
+    rootDir: opts.rootDir,
+  })
+  if (!result.acquired || !result.handle) {
+    const ex = result.existing ?? { pid: -1, startedAt: 0, updatedAt: 0 }
+    throw new BotTokenLockedError(ex.pid, ex.startedAt)
+  }
+  return wrapLockHandle(result.handle)
+}
+
+function wrapLockHandle(handle: ScopedLockHandle): TokenLock {
+  return { release: handle.releaseFn, refresh: handle.refreshFn }
+}
+
+/**
+ * Pre-polling webhook clear. grammy does this internally on bot.start, but
+ * making it explicit lets us surface failures (rare but possible if someone
+ * sets a webhook between init and start_polling).
+ */
+export async function clearWebhookBeforePolling(bot: Bot): Promise<void> {
+  try {
+    await bot.api.deleteWebhook({ drop_pending_updates: false })
+  } catch {
+    // Best-effort; grammy retries on bot.start. Caller can opt in to logging.
+  }
+}
+
+export type StartFailureKind = 'conflict' | 'network' | 'auth' | 'fatal' | 'cancelled'
+
+export interface StartFailure {
+  kind: StartFailureKind
+  detail: string
+  retryable: boolean
+}
+
+export function classifyStartFailure(err: unknown): StartFailure {
+  const msg = err instanceof Error ? err.message : String(err)
+  const lower = msg.toLowerCase()
+  const code = (err as { error_code?: number }).error_code
+  if (code === 409) return { kind: 'conflict', detail: msg, retryable: true }
+  if (code === 401) return { kind: 'auth', detail: msg, retryable: false }
+  if (
+    lower.includes('econnreset') ||
+    lower.includes('econnrefused') ||
+    lower.includes('enetunreach') ||
+    lower.includes('socket hang up') ||
+    lower.includes('eai_again') ||
+    lower.includes('network')
+  ) {
+    return { kind: 'network', detail: msg, retryable: true }
+  }
+  if (lower.includes('aborted') || lower.includes('cancelled')) {
+    return { kind: 'cancelled', detail: msg, retryable: false }
+  }
+  return { kind: 'fatal', detail: msg, retryable: false }
+}

package/src/retry.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, it } from 'bun:test'
+import {
+  DELIVERY_FAILURE_NOTICE,
+  RETRYABLE_PATTERNS,
+  TIMEOUT_PATTERNS,
+  classifyError,
+  isReplyNotFound,
+  isRetryable,
+  isThreadNotFound,
+  isTimeout,
+  sendWithRetry,
+} from './retry'
+
+describe('classifyError', () => {
+  it('treats timeouts as fail (NOT retryable)', () => {
+    expect(classifyError(new Error('ETIMEDOUT'))).toBe('fail')
+    expect(classifyError(new Error('Request Timeout'))).toBe('fail')
+    expect(classifyError(new Error('readtimeout'))).toBe('fail')
+  })
+  it('treats connection errors as retry', () => {
+    expect(classifyError(new Error('ECONNRESET'))).toBe('retry')
+    expect(classifyError(new Error('ECONNREFUSED'))).toBe('retry')
+    expect(classifyError(new Error('Network unreachable'))).toBe('retry')
+    expect(classifyError(new Error('socket hang up'))).toBe('retry')
+  })
+  it('forbidden / blocked surfaces as fail-silent', () => {
+    expect(classifyError(new Error('Forbidden: bot was blocked by the user'))).toBe('fail-silent')
+    expect(classifyError(new Error('chat not found'))).toBe('fail-silent')
+  })
+  it('400 bad request is fail (not retried)', () => {
+    expect(classifyError(new Error('Bad Request: message is empty'))).toBe('fail')
+  })
+})
+
+describe('sendWithRetry', () => {
+  it('returns on first success', async () => {
+    let calls = 0
+    const r = await sendWithRetry(async () => {
+      calls += 1
+      return 'ok'
+    })
+    expect(r).toBe('ok')
+    expect(calls).toBe(1)
+  })
+  it('retries on retryable error then succeeds', async () => {
+    let calls = 0
+    const r = await sendWithRetry(
+      async () => {
+        calls += 1
+        if (calls < 3) throw new Error('ECONNRESET')
+        return 'ok'
+      },
+      { maxRetries: 3, baseDelayMs: 1 },
+    )
+    expect(r).toBe('ok')
+    expect(calls).toBe(3)
+  })
+  it('does NOT retry on timeout', async () => {
+    let calls = 0
+    await expect(
+      sendWithRetry(
+        async () => {
+          calls += 1
+          throw new Error('ETIMEDOUT')
+        },
+        { maxRetries: 3, baseDelayMs: 1 },
+      ),
+    ).rejects.toThrow('ETIMEDOUT')
+    expect(calls).toBe(1)
+  })
+  it('throws after exhausting retries', async () => {
+    let calls = 0
+    await expect(
+      sendWithRetry(
+        async () => {
+          calls += 1
+          throw new Error('ECONNRESET')
+        },
+        { maxRetries: 2, baseDelayMs: 1 },
+      ),
+    ).rejects.toThrow('ECONNRESET')
+    expect(calls).toBe(3)
+  })
+})
+
+describe('classifier helpers (isRetryable / isTimeout)', () => {
+  it('isRetryable matches all RETRYABLE_PATTERNS', () => {
+    for (const p of RETRYABLE_PATTERNS) {
+      expect(isRetryable(new Error(`error: ${p}`))).toBe(true)
+    }
+  })
+
+  it('isTimeout matches all TIMEOUT_PATTERNS', () => {
+    for (const p of TIMEOUT_PATTERNS) {
+      expect(isTimeout(new Error(`error: ${p}`))).toBe(true)
+    }
+  })
+
+  it('isRetryable is false for timeouts (true delivery-unknown errors)', () => {
+    expect(isRetryable(new Error('readtimeout'))).toBe(false)
+    expect(isRetryable(new Error('writetimeout'))).toBe(false)
+  })
+
+  it('isReplyNotFound matches the BadRequest text', () => {
+    expect(isReplyNotFound(new Error('Bad Request: reply message not found'))).toBe(true)
+    expect(isReplyNotFound(new Error('Bad Request: message to be replied not found'))).toBe(true)
+  })
+
+  it('isReplyNotFound is false for unrelated errors', () => {
+    expect(isReplyNotFound(new Error('Forbidden'))).toBe(false)
+  })
+
+  it('isThreadNotFound matches the BadRequest text', () => {
+    expect(isThreadNotFound(new Error('Bad Request: message thread not found'))).toBe(true)
+  })
+})
+
+describe('DELIVERY_FAILURE_NOTICE', () => {
+  it('starts with the warning sigil and is single-line', () => {
+    expect(DELIVERY_FAILURE_NOTICE.startsWith('⚠️')).toBe(true)
+    expect(DELIVERY_FAILURE_NOTICE.includes('\n')).toBe(false)
+  })
+
+  it('mentions delivery failure', () => {
+    expect(DELIVERY_FAILURE_NOTICE.toLowerCase()).toContain('delivery failed')
+  })
+})

package/src/retry.ts

@@ -0,0 +1,114 @@
+// sendMessage / setMessageReaction retry classifier.
+//
+// RULE: timeout errors are NOT retryable, because the message MAY have been
+// delivered already. Retrying could double-send. Connection errors (ECONNRESET,
+// ENETUNREACH) are retryable because the server never received the request.
+//
+// Pattern from hermes (`base.py:1302` `_send_with_retry`).
+
+export type RetryClassification = 'retry' | 'fail' | 'fail-silent'
+
+/** Substrings that signal a transient network/connection failure. */
+export const RETRYABLE_PATTERNS = [
+  'connecterror',
+  'connectionerror',
+  'connectionreset',
+  'connectionrefused',
+  'connecttimeout',
+  'network',
+  'broken pipe',
+  'remotedisconnected',
+  'eoferror',
+  'enetunreach',
+  'eai_again',
+  'socket hang up',
+  'econnreset',
+  'econnrefused',
+] as const
+
+/** Substrings that signal a true delivery-status-unknown timeout (NOT retryable). */
+export const TIMEOUT_PATTERNS = [
+  'timed out',
+  'readtimeout',
+  'writetimeout',
+  'etimedout',
+  'request timeout',
+  'aborted',
+] as const
+
+/** User-facing notice when retries exhaust mid-stream. Hermes-aligned text. */
+export const DELIVERY_FAILURE_NOTICE =
+  '⚠️ Message delivery failed after multiple attempts. Please try again. Your request was processed but the response could not be sent.'
+
+export function isRetryable(err: unknown): boolean {
+  const lower = errorMessage(err).toLowerCase()
+  return RETRYABLE_PATTERNS.some(p => lower.includes(p))
+}
+
+export function isTimeout(err: unknown): boolean {
+  const lower = errorMessage(err).toLowerCase()
+  return TIMEOUT_PATTERNS.some(p => lower.includes(p))
+}
+
+export function isReplyNotFound(err: unknown): boolean {
+  const lower = errorMessage(err).toLowerCase()
+  return (
+    lower.includes('reply message not found') ||
+    lower.includes('replied message not found') ||
+    lower.includes('message to be replied')
+  )
+}
+
+export function isThreadNotFound(err: unknown): boolean {
+  const lower = errorMessage(err).toLowerCase()
+  return lower.includes('thread') && lower.includes('not found')
+}
+
+export function classifyError(err: unknown): RetryClassification {
+  if (isTimeout(err)) return 'fail'
+  if (isRetryable(err)) return 'retry'
+  const lower = errorMessage(err).toLowerCase()
+  if (
+    lower.includes('forbidden') ||
+    lower.includes('chat not found') ||
+    lower.includes('blocked')
+  ) {
+    return 'fail-silent'
+  }
+  if (lower.includes('bad request') || lower.includes('400')) return 'fail'
+  return 'retry'
+}
+
+export interface RetryOpts {
+  /** Max retry attempts. Default 2 (so 3 total attempts). */
+  maxRetries?: number
+  /** Base delay in ms; doubles per attempt. Default 250. */
+  baseDelayMs?: number
+}
+
+export async function sendWithRetry<T>(fn: () => Promise<T>, opts: RetryOpts = {}): Promise<T> {
+  const maxRetries = opts.maxRetries ?? 2
+  const baseDelay = opts.baseDelayMs ?? 250
+  let lastErr: unknown
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn()
+    } catch (err) {
+      lastErr = err
+      const verdict = classifyError(err)
+      if (verdict !== 'retry' || attempt === maxRetries) throw err
+      await new Promise(r => setTimeout(r, baseDelay * 2 ** attempt))
+    }
+  }
+  throw lastErr
+}
+
+function errorMessage(err: unknown): string {
+  if (err instanceof Error) return err.message
+  if (typeof err === 'string') return err
+  try {
+    return JSON.stringify(err)
+  } catch {
+    return String(err)
+  }
+}

package/src/sanitize.test.ts

@@ -0,0 +1,163 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { PairingStore } from '@s0nderlabs/anima-core'
+import { type SanitizeInput, sanitizeInbound } from './sanitize'
+
+const baseInput: SanitizeInput = {
+  chatType: 'private',
+  chatId: 12345,
+  fromId: 12345,
+  fromIsBot: false,
+  fromUsername: 'elpabl0',
+  fromFirstName: 'Alkautsar',
+  fromLastName: null,
+  text: 'hello',
+  messageId: 1,
+  forwardedFrom: null,
+  mediaGroupId: null,
+}
+
+let pairingDir: string
+
+beforeEach(() => {
+  pairingDir = mkdtempSync(join(tmpdir(), 'anima-sanitize-pairing-'))
+})
+
+afterEach(() => {
+  rmSync(pairingDir, { recursive: true, force: true })
+})
+
+describe('sanitizeInbound', () => {
+  it('accepts a plain DM from a user in the allowlist', () => {
+    const r = sanitizeInbound(baseInput, { allowedUserIds: [12345] })
+    expect(r.ok).toBe(true)
+    if (r.ok) {
+      expect(r.event.chatId).toBe(12345)
+      expect(r.event.text).toBe('hello')
+      expect(r.event.username).toBe('elpabl0')
+      expect(r.event.displayName).toBe('Alkautsar')
+    }
+  })
+
+  it('drops not-private chat types', () => {
+    const r = sanitizeInbound({ ...baseInput, chatType: 'group' }, { allowedUserIds: [12345] })
+    expect(r.ok).toBe(false)
+    if (!r.ok) expect(r.reason).toBe('not-private-chat')
+  })
+
+  it('drops bots', () => {
+    const r = sanitizeInbound({ ...baseInput, fromIsBot: true }, { allowedUserIds: [12345] })
+    expect(r.ok).toBe(false)
+    if (!r.ok) expect(r.reason).toBe('sender-is-bot')
+  })
+
+  it('drops forwarded messages', () => {
+    const r = sanitizeInbound(
+      { ...baseInput, forwardedFrom: { id: 1 } },
+      { allowedUserIds: [12345] },
+    )
+    expect(r.ok).toBe(false)
+    if (!r.ok) expect(r.reason).toBe('forwarded-message')
+  })
+
+  it('drops media groups', () => {
+    const r = sanitizeInbound({ ...baseInput, mediaGroupId: 'xyz' }, { allowedUserIds: [12345] })
+    expect(r.ok).toBe(false)
+    if (!r.ok) expect(r.reason).toBe('media-group')
+  })
+
+  it('drops empty/whitespace text', () => {
+    const r = sanitizeInbound({ ...baseInput, text: '   ' }, { allowedUserIds: [12345] })
+    expect(r.ok).toBe(false)
+    if (!r.ok) expect(r.reason).toBe('no-text')
+  })
+
+  it('truncates over-cap text', () => {
+    const r = sanitizeInbound(
+      { ...baseInput, text: 'x'.repeat(3000) },
+      { allowedUserIds: [12345], maxTextLength: 100 },
+    )
+    expect(r.ok).toBe(true)
+    if (r.ok) {
+      expect(r.event.text.length).toBeLessThan(150)
+      expect(r.event.text).toContain('[message truncated]')
+    }
+  })
+
+  it('rejects null fromId', () => {
+    const r = sanitizeInbound({ ...baseInput, fromId: null }, { allowedUserIds: [12345] })
+    expect(r.ok).toBe(false)
+    if (!r.ok) expect(r.reason).toBe('no-sender-id')
+  })
+
+  it('default-deny: empty allowedUserIds + no pairingStore rejects unknown senders', () => {
+    const r = sanitizeInbound({ ...baseInput, fromId: 99999 }, { allowedUserIds: [] })
+    expect(r.ok).toBe(false)
+    if (!r.ok) expect(r.reason).toBe('no-allowlist-default-deny')
+  })
+
+  it('default-deny: non-empty allowedUserIds without sender + no pairingStore rejects', () => {
+    const r = sanitizeInbound({ ...baseInput, fromId: 99999 }, { allowedUserIds: [12345] })
+    expect(r.ok).toBe(false)
+    if (!r.ok) expect(r.reason).toBe('sender-not-allowed')
+  })
+
+  it('pairing flow: unknown sender gets a pairing code', () => {
+    const store = new PairingStore({ dir: pairingDir })
+    const r = sanitizeInbound(
+      { ...baseInput, fromId: 99999 },
+      {
+        allowedUserIds: [],
+        pairingStore: store,
+      },
+    )
+    expect(r.ok).toBe(false)
+    if (!r.ok) {
+      expect(r.action).toBe('send-pairing-code')
+      expect(r.code).toBeDefined()
+      expect(r.code!.length).toBe(8)
+      expect(r.pairedUserId).toBe(99999)
+    }
+  })
+
+  it('pairing flow: approved user passes through even when not in static allowlist', () => {
+    const store = new PairingStore({ dir: pairingDir })
+    const code = store.generateCode('telegram', '99999', 'phantom')!
+    store.approveCode('telegram', code)
+    const r = sanitizeInbound(
+      { ...baseInput, fromId: 99999 },
+      {
+        allowedUserIds: [],
+        pairingStore: store,
+      },
+    )
+    expect(r.ok).toBe(true)
+    if (r.ok) expect(r.event.userId).toBe(99999)
+  })
+
+  it('pairing flow: rate-limited unknown sender gets pairing-rate-limited reason', () => {
+    const store = new PairingStore({ dir: pairingDir })
+    // Burn 3 codes to hit MAX_PENDING_PER_PLATFORM
+    for (let i = 0; i < 3; i++) store.generateCode('telegram', `bot-${i}`, '')
+    const r = sanitizeInbound(
+      { ...baseInput, fromId: 99999 },
+      {
+        allowedUserIds: [],
+        pairingStore: store,
+      },
+    )
+    expect(r.ok).toBe(false)
+    if (!r.ok) expect(r.reason).toBe('pairing-rate-limited')
+  })
+
+  it('explicit allowlist wins even when pairingStore is present', () => {
+    const store = new PairingStore({ dir: pairingDir })
+    const r = sanitizeInbound(baseInput, {
+      allowedUserIds: [12345],
+      pairingStore: store,
+    })
+    expect(r.ok).toBe(true)
+  })
+})