Telegram messaging adapter (Phase 0) — pull forward from v0.23.0

[kovtcharov]

Goal

Ship a Telegram messaging adapter in v0.18.2 (May 22) — pulled forward from v0.23.0 (Jun 23). The "your agent lives in Telegram" experience is a category-defining consumer feature; competitors ship it day-one.

Why pull this forward (5+ weeks)

GAIA's current roadmap puts all messaging adapters in v0.23.0 (Autonomous Agent Infrastructure, Jun 23). The flagship comparator — Hermes Agent (Nous Research) — ships 15+ messaging gateways (Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost, Email, SMS, …) on day one. AMD's own April 2026 blog "Run Hermes Agent Locally on AMD Ryzen AI Max+" recommends Hermes specifically because of this.

For consumer positioning ("your agent meets you where you already chat"), the gap is 8+ weeks of competitive disadvantage. Telegram is the cheapest unlock — python-telegram-bot is mature, no business-account hoops (unlike WhatsApp), no enterprise SSO (unlike Slack). One adapter ships the pitch.

Scope (single PR for v0.18.2)

A. Telegram bot adapter

• Create src/gaia/messaging/telegram.py — wraps python-telegram-bot
• Subscribe to /start, /help, /clear slash commands + free-form text
• Bridge to existing AgentSDK (gaia.chat.sdk) — every Telegram message becomes a chat turn
• Stream agent response chunks back as Telegram message edits (matches Hermes UX)
• Support file attachments (image upload → VLM, document → RAG ingest)

B. CLI integration

• New CLI: gaia telegram start --token $TELEGRAM_BOT_TOKEN [--allowed-users ...]
• Daemon mode (--background) with health check endpoint
• Per-user session isolation — each Telegram user_id maps to a distinct GAIA session
• Allowed-users gate (env GAIA_TELEGRAM_ALLOWED or --allowed-users 12345,67890) — privacy default

C. Security defaults

• Restricted tool set by default (no shell, no file_io without explicit opt-in) — matches the security pattern from Messaging security: restricted default tool set and input sanitization #690 (Messaging security)
• Input sanitization on incoming messages
• Rate limiting per user (cribs from Messaging adapter rate limiting infrastructure #689)
• No persistence of bot token in logs

D. Documentation

• docs/guides/telegram.mdx — setup walkthrough (BotFather → token → gaia telegram start)
• Privacy section: tokens stay local, messages stay local (Lemonade), only Telegram's transit goes through Telegram servers
• Add to docs/docs.json navigation

E. Tests

• Unit tests with mocked python-telegram-bot Updater
• Integration test gated behind GAIA_TELEGRAM_TEST_TOKEN env (skipped in default CI; runs nightly)

What this is NOT

• ❌ Not Discord (own PR — easier than Telegram in some ways)
• ❌ Not Slack (enterprise SSO complexity)
• ❌ Not Signal (privacy-first but harder integration; stays in v0.23.0 as Signal messaging adapter (Phase 1 — privacy-first priority) #693)
• ❌ Not WhatsApp (Business API, expensive)
• ❌ Not the unified communication hub (Unified communication hub: SMS + email + messaging in single prioritized feed #703) — single adapter, no aggregation

Acceptance criteria

• gaia telegram start --token $TOKEN boots and the bot responds to /start within 5 seconds
• Free-form messages produce streaming agent responses with Telegram message edits
• Image upload → VLM tool fires → response cites image
• File upload (.pdf, .csv) → RAG ingest → subsequent question retrieves correctly
• Allowed-users gate rejects messages from unlisted users with a polite error
• Restricted tool set is enforced by default (verified via test that requests a shell command)

Attribution / prior art

• Hermes Agent (Nous Research) (github.com/NousResearch/hermes-agent) — the messaging-native paradigm; their adapter pattern informs this design
• python-telegram-bot (python-telegram-bot.org) — upstream library, MIT
• Messaging adapters: Telegram, Discord, Slack integration #635 — full multi-platform messaging adapter (Telegram + Discord + Slack); this issue carves Telegram out as Phase 0

Dependencies

• Resolves part of Messaging adapters: Telegram, Discord, Slack integration #635 (Telegram leg only)
• Adjacent: Messaging adapter rate limiting infrastructure #689 (rate limiting), Messaging security: restricted default tool set and input sanitization #690 (security), Signal messaging adapter (Phase 1 — privacy-first priority) #693 (Signal — separate Phase 1 in v0.23.0)
• Blocks: Email Triage Agent: AI-powered inbox management (Tier 1 use case) #645 (Email Triage Agent — uses messaging surfaces), Personalized daily briefs: morning digest of email, calendar, news, and tasks #663 (Personalized daily briefs), Messaging adapters: Telegram, Discord, Slack integration #635 (full multi-platform)

[kovtcharov]

Scope expansion: voice notes (OGG/Opus output)

Per the consumer-use-case review, this Phase 0 should include voice-note output, not just text. The cost is ~50 LOC since Kokoro TTS already exists in src/gaia/audio/kokoro_tts.py. Telegram natively supports OGG/Opus voice messages via send_voice().

Added scope

• Configurable per-user preference: text replies (default) vs. voice notes
• When voice mode is on, agent response is rendered via Kokoro TTS to OGG/Opus and sent as a Telegram voice message
• Configurable per-skill override (e.g., morning-brief skill explicitly requests voice; code-review skill explicitly requests text)
• Inbound voice messages (user sends voice to bot) — transcribe via Whisper ASR (src/gaia/audio/whisper_asr.py) before passing to agent

Why this matters now

Closes the 'voice message on my phone' use case without waiting for the full voice-first parity work in v0.21.0 (#702). The local-Telegram path is also our mobile experience until / unless we ship a native mobile app — so it has to support voice both directions.

Attribution

The voice-note pattern is what Hermes Agent's Telegram integration uses; this just brings GAIA to feature parity on the same platform.