nebula-ai-plugin-telegram 0.1.0

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.ts

@@ -0,0 +1,128 @@
+import type { PairingStore } from 'nebula-ai-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
+ *    `nebula 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.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
+ * "nebula" 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 : 'nebula'
+}

package/src/session-state.ts

@@ -0,0 +1,102 @@
+// 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: hermes-derived (/approve, /deny, /status, /stop, /new,
+// /reset, /background, /restart) plus v0.20.0 additions (/yolo, /perms) so
+// operators can flip permission mode from their phone without restarting.
+
+export const BYPASS_COMMANDS = [
+  '/stop',
+  '/new',
+  '/reset',
+  '/status',
+  '/approve',
+  '/deny',
+  '/background',
+  '/restart',
+  '/yolo',
+  '/perms',
+] as const
+
+export type BypassCommand = (typeof BYPASS_COMMANDS)[number]
+
+export interface ParsedBypass {
+  command: BypassCommand
+  args: string[]
+}
+
+/**
+ * Detect a bypass command at the start of an inbound message. Returns the
+ * canonical lowercase command + whitespace-split args, or null when the
+ * message isn't a bypass command. v0.20.0 changed the return shape from
+ * `BypassCommand | null` to `ParsedBypass | null` so handlers (especially
+ * `/perms <mode>`) can read the args alongside the name.
+ */
+export function parseBypassCommand(text: string): ParsedBypass | null {
+  const trimmed = text.trim()
+  if (!trimmed.startsWith('/')) return null
+  const parts = trimmed.split(/\s+/)
+  const head = parts[0]?.toLowerCase()
+  if (!head) return null
+  if ((BYPASS_COMMANDS as readonly string[]).includes(head)) {
+    return { command: head as BypassCommand, args: parts.slice(1) }
+  }
+  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,144 @@
+import type { PairingStore } from 'nebula-ai-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 `nebula 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
+  /**
+   * v0.24.12: outbound slot the listener fills on `start()` with a method
+   * that broadcasts a short text to every allowed operator chat. The
+   * gateway uses it to forward unsolicited brain prompts (clarify on
+   * autonomous market wakes) when no TUI is connected. When absent, the
+   * gateway logs the question to activity-log only.
+   */
+  operatorNotifier?: OperatorNotifierSlot
+}
+
+/** Mutable slot the listener fills on start so the gateway can broadcast clarify questions. */
+export interface OperatorNotifierSlot {
+  current: ((text: string) => Promise<void>) | null
+}
+
+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
+  }
+}
+
+/** 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
+  /** 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
+  /**
+   * 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 {
+  /** Assistant text to echo back to the user. Empty string skips the reply. */
+  response: string
+  /** Optional Mantle 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
+}

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