# Reference Examples for Bot Development

Sanitized code examples from the agent-core project for building
Telegram and Matrix bots that integrate with LLM backends.

## Files

### Telegram Bot with Forum Topics

**`telegram_bot_topics.py`** — Complete Telegram bot using python-telegram-bot 22+.

Key patterns:
- **Forum topics**: Create/rename topics, route messages by `message_thread_id`
- **Message types**: Text, photos, voice/audio, documents — each with its own handler
- **Streaming responses**: Progressive message editing as LLM generates text
- **Outbox pattern**: LLM writes to `outbox.jsonl`, bot sends files after response
- **Topic naming**: LLM generates topic labels, bot auto-renames forum topics
- **Voice transcription**: Download voice → external STT → send text to LLM
- **Proxy support**: SOCKS5 proxy with retry logic for unreliable connections

Dependencies: `python-telegram-bot>=22.0`, `httpx`, `pyyaml`

### Matrix Bot with Room Management

**`matrix_bot_rooms.py`** — Matrix bot using matrix-nio with E2E encryption.

Key patterns:
- **Room creation**: Create private encrypted rooms, invite users, set avatars
- **Room modes**: Per-room behavior (quiet/context/full) stored in config.json
- **Multi-user**: Users map with per-user profiles loaded from YAML
- **E2E encryption**: Crypto store, key upload, cross-signing, device verification
- **Media handling**: Download + decrypt encrypted media (images, voice, files)
- **Message queuing**: Persistent queue (queue.jsonl) for messages arriving while busy
- **Status threads**: Post tool progress as thread replies under user's message
- **Session management**: Per-room Claude sessions with idle timeout, cancel support
- **Room naming**: Auto-generate room names from conversation content via local LLM
- **Bot commands**: `!new`, `!mode`, `!status`, `!security`, `!help`
- **Security modes**: strict/guarded/open for E2E device verification policy
- **Typing indicators**: Show typing while LLM processes

Dependencies: `matrix-nio[e2e]>=0.24`, `httpx`, `markdown`, `pyyaml`

### Shared: LLM Session Manager

**`llm_session.py`** — Process manager for Claude Code CLI (adaptable to any LLM).

Key patterns:
- **Session persistence**: Save/restore session IDs for conversation continuity
- **Stream parsing**: Parse `stream-json` output for real-time tool/status tracking
- **Idle timeout**: Watchdog task resets on output, kills on silence
- **Cancel support**: External event to kill LLM process mid-turn
- **Fallback chain**: Primary LLM fails → try secondary provider
- **Sandbox**: bubblewrap (bwrap) wrapper for filesystem isolation
- **Status callbacks**: Emit events for tool_start, tool_end, thinking text
- **Environment isolation**: Strip sensitive env vars before spawning subprocess

### Shared: Config

**`config_example.py`** — Simple dataclass config loaded from environment variables.

## Architecture

```
User ──► Bot (Telegram/Matrix) ──► LLM Session Manager ──► Claude CLI (sandboxed)
                │                          │
                ├── media download         ├── session persistence
                ├── typing indicators      ├── stream parsing
                ├── outbox file sending    ├── timeout watchdog
                └── topic/room management  └── fallback provider
```

The bot and LLM session are decoupled — the session manager doesn't know
about Telegram or Matrix. It takes a message string, runs the CLI process,
and returns text + status callbacks. The bot handles all platform-specific
concerns (formatting, media, rooms/topics).