@pedrohnas/opencode-telegram 0.1.0 → 1.2.0

package/.env.example

@@ -0,0 +1,17 @@
+# Required: Telegram bot token from @BotFather
+TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
+
+# Optional: OpenCode server URL (default: spawns local server)
+# OPENCODE_URL=http://127.0.0.1:4096
+
+# Optional: Project directory for OpenCode (default: cwd)
+# OPENCODE_DIRECTORY=/path/to/project
+
+# Optional: Use Telegram test environment
+# TELEGRAM_TEST_ENV=1
+
+# E2E test credentials (only needed for automated testing)
+# TELEGRAM_API_ID=12345
+# TELEGRAM_API_HASH=0123456789abcdef0123456789abcdef
+# TELEGRAM_SESSION=saved-session-string
+# TELEGRAM_BOT_USERNAME=my_bot

package/bunfig.toml

@@ -0,0 +1,2 @@
+[test]
+root = "./src"

package/docs/PROGRESS.md

@@ -0,0 +1,327 @@
+# OpenCode Telegram Bot — Progress Log
+
+## Phase 0 — E2E Infrastructure + Bot Skeleton ✅
+
+**Status:** Complete
+**Date:** 2026-02-07
+
+### Delivered
+- Project scaffolding inside monorepo (`packages/telegram/`)
+- Grammy bot with `/start` handler
+- Config from env vars with validation
+- Graceful shutdown (SIGINT/SIGTERM)
+- E2E infrastructure: gramjs userbot client, test helpers, runner
+- Session string generation script (`scripts/gen-session.ts`)
+
+### Tests
+| Type | Count | Status |
+|------|-------|--------|
+| Unit (bun test src/) | 12 | ✅ all pass |
+| E2E (bun test ./e2e/phase-0.test.ts) | 2 | ✅ all pass |
+| Manual (/start in Telegram) | 1 | ✅ working |
+
+### Files Created
+```
+packages/telegram/
+  package.json
+  tsconfig.json
+  bunfig.toml
+  .env.example
+  .env                          ← credentials (gitignored)
+  .gitignore
+  src/
+    index.ts                    ← entry point
+    bot.ts                      ← Grammy bot + /start
+    bot.test.ts                 ← 4 tests
+    config.ts                   ← env parsing
+    config.test.ts              ← 8 tests
+  e2e/
+    client.ts                   ← gramjs wrapper
+    helpers.ts                  ← sendAndWait, assertContains, clickInlineButton, etc.
+    runner.ts                   ← setup/teardown (spawn bot + connect client)
+    phase-0.test.ts             ← 2 E2E tests
+  scripts/
+    gen-session.ts              ← generate gramjs session string
+```
+
+### Lessons Learned
+- `bunfig.toml`: `preload = []` is invalid, use `root = "./src"` instead
+- Bun auto-loads `.env` — tests for default values need explicit `delete process.env.VAR`
+- E2E runs in ~3s: gramjs connects, spawns bot, sends /start, verifies, tears down
+
+---
+
+## Phase 1 — Core Loop (MVP) ✅
+
+**Status:** Complete
+**Date:** 2026-02-07
+
+### Delivered
+- **SDK client factory** (`sdk.ts`): spawns local OpenCode server from monorepo source, or connects to external
+- **SessionManager** (`session-manager.ts`): LRU-bounded map with TTL, reverse lookup (sessionId → chatKey)
+- **TurnManager** (`turn-manager.ts`): per-turn AbortController + timer tracking, clean abort
+- **EventBus** (`event-bus.ts`): single SSE connection, routes events to Telegram chats
+- **Markdown formatter** (`send/format.ts`): Markdown → Telegram HTML conversion
+- **Message chunker** (`send/chunker.ts`): split messages at 4096 char boundary
+- **Message handler**: text → SessionManager → SDK prompt → EventBus → formatted response
+- **`/new` command**: removes mapping, creates fresh session
+- **index.ts wiring**: SDK init → bot + managers → EventBus → graceful shutdown
+
+### Tests
+| Type | Count | Status |
+|------|-------|--------|
+| Unit (bun test src/) | 76 | ✅ all pass |
+| E2E Phase 0 (regression) | 2 | ✅ all pass |
+| E2E Phase 1 | 3 | ✅ all pass |
+
+### Files Created
+```
+src/
+  sdk.ts                        ← SDK client factory (spawn or connect)
+  session-manager.ts            ← LRU Map<chatKey, SessionEntry>
+  session-manager.test.ts       ← 13 tests
+  turn-manager.ts               ← Per-turn lifecycle (AbortController)
+  turn-manager.test.ts          ← 12 tests
+  event-bus.ts                  ← Single SSE connection + dispatcher
+  event-bus.test.ts             ← 5 tests
+  send/
+    format.ts                   ← Markdown → Telegram HTML
+    format.test.ts              ← 22 tests
+    chunker.ts                  ← Split messages at 4096 chars
+    chunker.test.ts             ← 8 tests
+e2e/
+  phase-1.test.ts               ← 3 E2E tests
+```
+
+### Files Modified
+```
+src/
+  bot.ts                        ← Added message handler, /new command, BotDeps
+  bot.test.ts                   ← Expanded to 8 tests (handleMessage, handleNew)
+  index.ts                      ← Full wiring: SDK + managers + EventBus + shutdown
+e2e/
+  runner.ts                     ← Spawns server + bot separately, for-await stdout
+  helpers.ts                    ← sendAndWait uses message ID ordering
+  phase-0.test.ts               ← Increased beforeAll timeout for server startup
+```
+
+### How to Run
+
+```bash
+# From the telegram package directory:
+cd packages/telegram
+
+# Set OPENCODE_DIRECTORY to the project you want the AI to work on:
+env $(grep -v '^#' .env | xargs) OPENCODE_DIRECTORY=/home/pedro/dev bun run src/index.ts
+
+# Or connect to an existing OpenCode server:
+env $(grep -v '^#' .env | xargs) OPENCODE_URL=http://127.0.0.1:4096 bun run src/index.ts
+```
+
+**How it works:**
+- Without `OPENCODE_URL`: spawns a local OpenCode server from monorepo source (`packages/opencode`)
+- The server CWD stays at `packages/opencode` (for module resolution)
+- `OPENCODE_DIRECTORY` is sent as `x-opencode-directory` header in every SDK request
+- The OpenCode server uses that header to know which project to operate on
+
+### Lessons Learned
+- `Bun.spawn` stdout with `getReader()` + `Promise.race` timeout breaks stream reading — use `for await` instead
+- `process.execPath` resolves bun correctly; ENOENT from spawn usually means CWD doesn't exist
+- E2E runner must spawn OpenCode server separately (not nested inside bot) to avoid subprocess hang
+- `sendAndWait` must use message ID ordering (not timestamps) to avoid picking up stale responses
+- `createOpencode({ port: 0 })` from SDK needs the `opencode` binary — dev mode uses bun source directly
+- Server CWD must be `packages/opencode` (module resolution); project dir via `x-opencode-directory` header
+
+---
+
+## Phase 2 — Interactive Controls ✅
+
+**Status:** Complete
+**Date:** 2026-02-07
+
+### Delivered
+- **Permission handling** (`handlers/permissions.ts`): Inline keyboard (Allow / Always / Deny) on `permission.asked` SSE events. Callback routes to `sdk.permission.reply()`.
+- **Question handling** (`handlers/questions.ts`): Inline keyboard with option buttons + Skip on `question.asked` SSE events. Callback routes to `sdk.question.reply()` or `sdk.question.reject()`.
+- **PendingRequests** (`pending-requests.ts`): Bounded Map with TTL for request state tracking — enables index→label resolution for questions and double-click protection for both.
+- **`/cancel` command** (`handlers/cancel.ts`): Aborts active turn via `sdk.session.abort()`, cleans up TurnManager.
+- **Typing indicator** (`handlers/typing.ts`): Sends "typing" chat action every 4s during active turns, auto-stops on turn end via AbortSignal.
+- **Callback query routing** in `bot.ts`: Routes `perm:` and `q:` prefixed callbacks, always calls `answerCallbackQuery()` first, edits original message to show decision.
+- **EventBus wiring** in `index.ts`: Handles `permission.asked` and `question.asked` events, stores in PendingRequests, sends formatted messages with keyboards.
+
+### Tests
+| Type | Count | Status |
+|------|-------|--------|
+| Unit (bun test src/) | 108 | ✅ all pass |
+| E2E Phase 0 (regression) | 2 | ✅ all pass |
+| E2E Phase 1 (regression) | 3 | ✅ all pass |
+| E2E Phase 2 | 3 | ✅ all pass |
+
+### Files Created
+```
+src/
+  pending-requests.ts              ← Bounded Map<requestID, PendingEntry> with TTL
+  pending-requests.test.ts         ← 7 tests
+  handlers/
+    permissions.ts                 ← formatPermissionMessage(), parsePermissionCallback()
+    permissions.test.ts            ← 8 tests
+    questions.ts                   ← formatQuestionMessage(), parseQuestionCallback(), resolveQuestionAnswer()
+    questions.test.ts              ← 8 tests
+    cancel.ts                      ← handleCancel()
+    cancel.test.ts                 ← 5 tests
+    typing.ts                      ← startTypingLoop()
+    typing.test.ts                 ← 4 tests
+e2e/
+  phase-2.test.ts                  ← 3 E2E tests (regression, /cancel, AI response)
+```
+
+### Files Modified
+```
+src/
+  bot.ts                           ← Added /cancel, callback_query handler, BotDeps.pendingRequests,
+                                      handleMessage returns { turn }, typing loop start
+  bot.test.ts                      ← Updated tests for new return type
+  index.ts                         ← PendingRequests instance, permission.asked + question.asked
+                                      event handlers, periodic cleanup
+e2e/
+  helpers.ts                       ← Polling interval 500ms → 1500ms (flood wait mitigation)
+  phase-0.test.ts                  ← Unknown command test adapted (bot now responds via AI)
+```
+
+### Key Design Decisions
+- **No sessionID needed for permission/question SDK calls** — only requestID. Simplifies PendingRequests significantly.
+- **Callback data fits 64-byte limit**: `perm:once:per_xxxx` (~40 bytes), `q:que_xxxx:0` (~35 bytes).
+- **Single-select MVP for questions**: `multiple: true` and `custom: true` questions deferred.
+- **E2E permission/cancel-during-generation tests deferred**: Timing-dependent on AI behavior and Grammy's sequential update processing.
+
+### Lessons Learned
+- Grammy processes updates sequentially — `/cancel` can't interrupt a handler blocked on `sdk.session.prompt()`
+- `answerCallbackQuery()` MUST be called immediately in callback handlers (prevents Telegram loading spinner)
+- E2E polling at 500ms triggers Telegram flood waits — 1500ms is safe
+- Permission/question button E2E tests are inherently flaky (depend on AI triggering specific tool calls)
+- Bot now processes unknown commands via AI (Phase 1 `message:text` handler catches them), so Phase 0 regression test needed updating
+
+---
+
+## Phase 3 — Streaming + UX ✅
+
+**Status:** Complete
+**Date:** 2026-02-08
+
+### Delivered
+- **DraftStream** (`send/draft-stream.ts`): Sends initial message on first text part, then edits it as text streams in. Throttled at 400ms, HTML with plain-text fallback, auto-stop via AbortSignal.
+- **Tool progress** (`send/tool-progress.ts`): Appends `⚙ Running tool: title` suffix to draft during tool execution. Cleared on next text update.
+- **Final response** (`finalizeResponse` in `index.ts`): On `session.idle`, stops draft and either edits to final HTML (single chunk) or deletes draft and sends chunked messages (>4096 chars).
+- **Fire-and-forget prompt** (`bot.ts`): `sdk.session.prompt()` no longer blocks the Grammy handler — the DraftStream is created before the prompt fires, so SSE events can update the draft immediately.
+- **E2E project directory** (`runner.ts`): Bot now uses `/home/pedro/dev/` as OPENCODE_DIRECTORY (configurable via env), pointing to the workspace with Opus configured.
+
+### Tests
+| Type | Count | Status |
+|------|-------|--------|
+| Unit (bun test src/) | 137 | ✅ all pass |
+| E2E Phase 0 (regression) | 2 | ✅ all pass |
+| E2E Phase 1 (regression) | 3 | ✅ all pass |
+| E2E Phase 2 (regression) | 3 | ✅ all pass |
+| E2E Phase 3 | 4 | ✅ all pass |
+
+### Files Created
+```
+src/
+  send/
+    draft-stream.ts                ← DraftStream class (throttled message editing)
+    draft-stream.test.ts           ← 18 tests
+    tool-progress.ts               ← formatToolStatus() pure function
+    tool-progress.test.ts          ← 8 tests
+e2e/
+  phase-3.test.ts                  ← 4 E2E tests (streaming, tool progress, 2 regression)
+```
+
+### Files Modified
+```
+src/
+  turn-manager.ts                  ← Added toolSuffix + draft fields to ActiveTurn
+  turn-manager.test.ts             ← 3 new tests for new fields
+  bot.ts                           ← DraftStream created before prompt, fire-and-forget prompt,
+                                      draftDeps parameter for testability
+  bot.test.ts                      ← Updated for fire-and-forget prompt (microtick waits)
+  index.ts                         ← DraftStream updates on text/tool events, finalizeResponse
+                                      on session.idle, tool progress integration
+e2e/
+  runner.ts                        ← OPENCODE_DIRECTORY defaults to project root (/home/pedro/dev/)
+```
+
+### Key Design Decisions
+- **Fire-and-forget prompt**: `sdk.session.prompt()` was blocking Grammy's sequential handler — with Opus max, this could take minutes. Now it's fire-and-forget with `.catch()`, and the DraftStream is ready before any SSE events arrive.
+- **DraftStream dependency injection**: `DraftStreamDeps` abstracts `bot.api.sendMessage/editMessageText` for testability without Grammy mocks.
+- **Tool progress as suffix**: Tool status is appended to the draft text (not sent as separate messages), keeping the chat clean. Cleared when next text part arrives.
+- **Finalization logic**: Single-chunk → edit draft; multi-chunk → delete draft + send chunked; no draft → send normally.
+
+### Lessons Learned
+- `sdk.session.prompt()` blocks until the server responds — with slow models this blocks Grammy's entire update processing. Fire-and-forget is essential.
+- DraftStream must be created BEFORE the prompt call, not after — SSE events arrive immediately and need a target.
+- E2E tests with different model configs (Opus system prompt in Portuguese) may respond differently — regression tests should assert "bot responded" not specific words.
+- Chaining E2E suites with `&&` can cause server port conflicts — run each suite isolated.
+
+---
+
+## Phase 4 — Session Management + Hardening ✅
+
+**Status:** Complete
+**Date:** 2026-02-08
+**Plan:** See `docs/plans/phase-4.md`
+
+### Delivered
+- **Allowlist middleware (N1)** — `TELEGRAM_ALLOWED_USERS` env var restricts bot access to specific Telegram user IDs. Grammy middleware at top of stack silently ignores non-allowed users. Empty list = accept all.
+- **Streaming interruption fix (N2)** — `sdk.session.abort()` called before starting new turn when existing turn is active. Prevents stale SSE events from corrupting new turns. Generation counter as safety net.
+- **Session restore on restart (N3)** — On startup, `sessionManager.restore(sdk)` pre-populates SessionManager with sessions matching "Telegram {chatId}" title pattern.
+- **Telegram command menu (N4)** — `bot.api.setMyCommands()` registers 9 commands in Telegram's "/" autocomplete menu.
+- **`/list`** — Shows sessions with inline keyboard, click `sess:` callback to switch.
+- **`/rename <title>`** — Renames current session via `sdk.session.update()`.
+- **`/delete`** — Deletes current session via `sdk.session.delete()` + removes SessionManager mapping.
+- **`/info`** — Shows session info (title, directory, created, updated).
+- **`/history`** — Shows last 10 messages (role: truncated text).
+- **`/summarize`** — Returns guidance message (avoids requiring model selection).
+- **`handleSessionCallback`** — Switches session via prefix matching on `session.list()`.
+
+### Tests
+| Type | Count | Status |
+|------|-------|--------|
+| Unit (bun test src/) | 184 | ✅ all pass |
+| E2E Phase 0 (regression) | 2 | ✅ all pass |
+| E2E Phase 1 (regression) | 3 | ✅ all pass |
+| E2E Phase 2 (regression) | 3 | ✅ all pass |
+| E2E Phase 3 (regression) | 4 | ✅ all pass |
+| E2E Phase 4 | 5 | ✅ all pass |
+
+### Files Created
+```
+src/
+  handlers/
+    allowlist.ts                   ← Grammy middleware factory
+    allowlist.test.ts              ← 6 tests
+    sessions.ts                    ← Session command handlers + formatting
+    sessions.test.ts               ← 26 tests
+e2e/
+  phase-4.test.ts                  ← 5 E2E tests
+```
+
+### Files Modified
+```
+src/
+  config.ts                        ← Added allowedUsers: number[] field
+  config.test.ts                   ← 3 new tests for allowedUsers parsing
+  turn-manager.ts                  ← Added generation counter to ActiveTurn
+  turn-manager.test.ts             ← 3 new tests for generation field
+  session-manager.ts               ← Added restore() method
+  session-manager.test.ts          ← 5 new tests for restore()
+  bot.ts                           ← Allowlist middleware, 6 new commands, sess: callback,
+                                      sdk.session.abort() before new turn, handleSessionCallback
+  bot.test.ts                      ← 4 new tests (abort behavior, session callback)
+  index.ts                         ← Session restore on startup, setMyCommands registration
+e2e/
+  phase-3.test.ts                  ← Fixed flaky streaming assertion
+```
+
+### Lessons Learned
+- `sdk.session.abort()` is fire-and-forget — errors logged but don't block new turn
+- Phase 3 streaming E2E was flaky: finalizeResponse can shorten text (strips tool suffix), so assert "same message ID + has content" instead of "text grew"
+- `sdk.session.summarize()` requires providerID + modelID — simpler to guide users to ask the AI directly

package/docs/mapping.md

@@ -0,0 +1,326 @@
+# OpenCode Telegram Bot - Feature Mapping Report
+
+Comparative analysis between the OpenCode SDK (as consumed by the `app` web UI) and the OpenClaw Telegram integration, to plan a comprehensive Telegram bot for OpenCode.
+
+---
+
+## 1. OpenCode SDK - Complete API Surface
+
+The SDK (`@opencode-ai/sdk`) exposes the `OpencodeClient` class with these namespaces:
+
+| Namespace | Key Methods | Used by App |
+|-----------|------------|-------------|
+| `global` | `get`, `update`, `health`, `event` (SSE stream), `dispose` | Yes - bootstrap, config, SSE |
+| `auth` | `remove`, `set` | Yes - provider auth |
+| `project` | `list`, `current`, `update` | Yes - multi-project |
+| `pty` | `list`, `create`, `remove`, `get`, `update`, `connect` | No |
+| `config` | `get`, `update`, `providers` | Yes - settings |
+| `tool` | `ids`, `list` | No |
+| `worktree` | `list`, `remove`, `create`, `reset` | Yes - git worktrees |
+| `experimental` | `resource.list` | No |
+| `session` | `list`, `create`, `status`, `delete`, `get`, `update`, `children`, `todo`, `init`, `fork`, `abort`, `share`, `unshare`, `diff`, `summarize`, `messages`, `prompt`, `message`, `promptAsync`, `command`, `shell`, `revert`, `unrevert` | Yes - all core |
+| `part` | `delete`, `update` | No |
+| `permission` | `respond`, `reply`, `list` | Yes - permission dialogs |
+| `question` | `list`, `reply`, `reject` | Yes - question dialogs |
+| `provider` | `list`, `auth` | Yes - provider mgmt |
+| `find` | `text`, `files`, `symbols` | No |
+| `file` | `list`, `read`, `status` | Yes - file tree |
+| `mcp` | `remove`, `start`, `callback`, `authenticate`, `status`, `add`, `connect`, `disconnect` | No |
+| `tui` | `next`, `response`, `appendPrompt`, `openHelp/Sessions/Themes/Models`, `submitPrompt`, `clearPrompt`, `executeCommand`, `showToast`, `publish`, `selectSession` | No (TUI-specific) |
+| `instance` | `dispose` | No |
+| `path` | `get` | Yes - directory paths |
+| `vcs` | `get` | Yes - git status |
+| `command` | `list` | Yes - slash commands |
+| `app` | `log`, `agents`, `skills` | Yes - agent list |
+| `lsp` | `status` | Yes - LSP indicators |
+| `formatter` | `status` | No |
+| `event` | `subscribe` (per-instance SSE) | Yes - realtime updates |
+
+---
+
+## 2. OpenCode App (Web UI) - SDK Usage Breakdown
+
+### 2.1 Session Lifecycle
+- `session.create()` - new conversation
+- `session.list()` - sidebar session list
+- `session.get()` - load specific session
+- `session.update()` - rename, archive
+- `session.delete()` - delete session
+- `session.fork()` - fork from message
+- `session.share()` / `unshare()` - sharing URLs
+- `session.abort()` - cancel running response
+- `session.diff()` - view file changes
+- `session.todo()` - task list
+- `session.children()` - sub-sessions
+
+### 2.2 Messaging
+- `session.prompt()` - send user message (text + files + images + agent + model + variant)
+- `session.shell()` - execute shell command
+- `session.command()` - execute slash command (with agent, model, variant, parts)
+- `session.messages()` - load message history (paginated)
+- `session.message()` - get single message
+- `session.summarize()` - summarize session
+- `session.revert()` / `unrevert()` - undo/redo changes
+
+### 2.3 Events (SSE)
+- `global.event()` - global SSE stream, events by directory
+- Event types handled:
+  - `message.updated` - new/updated messages
+  - `message.part.updated` - tool calls, text streaming
+  - `session.updated` - session metadata changes
+  - `session.status` - busy/idle state
+  - `session.idle` - turn complete (triggers notifications)
+  - `session.error` - error events
+  - `permission.asked` - permission request
+  - `lsp.updated` - LSP status change
+
+### 2.4 Permissions
+- `permission.list()` - pending permissions for directory
+- `permission.respond()` - once/always/reject
+
+### 2.5 Questions
+- `question.list()` - pending questions
+- `question.reply()` - answer question
+- `question.reject()` - reject question
+
+### 2.6 Config & Providers
+- `global.get()` → config, providers, provider_auth, path, project list
+- `global.update()` → update global config
+- `config.get()` / `config.update()` - per-project config
+- `provider.list()` / `provider.auth()` - provider management
+- `auth.set()` / `auth.remove()` - API key management
+
+### 2.7 Files & VCS
+- `file.list()` - directory file tree
+- `file.read()` - read file content
+- `file.status()` - git status
+- `vcs.get()` - VCS info
+- `worktree.create()` / `list()` / `remove()` / `reset()` - git worktree management
+
+### 2.8 Other
+- `app.agents()` - list available agents
+- `app.skills()` - list skills
+- `command.list()` - list slash commands
+- `lsp.status()` - LSP server status
+
+---
+
+## 3. OpenClaw Telegram - Feature Breakdown
+
+~6,500 LOC (excluding tests). Built on Grammy (Telegram Bot Framework).
+
+### 3.1 Core Architecture
+- **bot.ts** (494 LOC) - Bot creation, Grammy setup, sequentialization, throttling
+- **bot-handlers.ts** (928 LOC) - Message/callback routing, media groups, text fragment assembly, debouncing
+- **bot-message.ts** (93 LOC) - Message processor factory
+- **bot-message-context.ts** (700 LOC) - Rich context building (sender info, group config, history, media, permissions)
+- **bot-message-dispatch.ts** (357 LOC) - Dispatches to AI agent, handles reply delivery
+
+### 3.2 Message Handling
+- Text messages (DM + group)
+- Media: photos, videos, documents, audio, voice, stickers
+- Media groups (multiple photos/videos in one message)
+- Text fragment assembly (long messages split across multiple Telegram messages)
+- Inbound debouncing (batches rapid messages)
+- Forward/reply context extraction
+- Sticker image analysis via vision model
+- Inline button callbacks (callback_query)
+
+### 3.3 Sending / Response Delivery
+- **send.ts** (754 LOC) - Full send pipeline:
+  - Markdown → Telegram HTML conversion
+  - Message chunking (4096 char limit)
+  - Media attachments (photo, video, audio, document, voice, GIF)
+  - Caption splitting for media
+  - Inline keyboard buttons
+  - Reply threading (reply_to_message_id)
+  - Forum topic support (message_thread_id)
+  - Silent messages (disable_notification)
+  - Voice messages (via ElevenLabs TTS)
+  - Reactions (emoji reactions on messages)
+  - Proxy support (SOCKS5/HTTP)
+  - Retry with exponential backoff
+
+### 3.4 Draft Streaming
+- **draft-stream.ts** (139 LOC) - Live streaming of AI response as editable message draft
+- Throttled updates (300ms)
+- Max 4096 chars per draft
+- Falls back gracefully on failure
+
+### 3.5 Native Commands (/command)
+- **bot-native-commands.ts** (699 LOC) - Telegram /commands:
+  - `/status` - bot status
+  - `/models` - model selection with inline keyboard pagination
+  - `/help` - command list
+  - `/commands` - list available commands
+  - Custom commands from config
+  - Skill-based commands
+  - Plugin commands
+  - Per-group/topic command gating
+
+### 3.6 Model Selection UI
+- **model-buttons.ts** (217 LOC) - Inline keyboard for model selection:
+  - Provider grouping
+  - Paginated model list
+  - Per-session model override storage
+
+### 3.7 Group Chat Support
+- Group policy (allow/deny/mentionOnly)
+- Per-group configuration
+- Forum/topic support (supergroups with topics)
+- Topic-specific skill filters and system prompts
+- Mention detection (@botname)
+- Sender allowlists
+- Group migration handling (when group ID changes)
+- Group history tracking
+
+### 3.8 Multi-Account
+- **accounts.ts** (139 LOC) - Multiple Telegram bot accounts
+- Account binding per DM chat
+- Account-specific config
+
+### 3.9 Security & Access Control
+- **bot-access.ts** (94 LOC) - Allowlist checking
+- **audit.ts** (162 LOC) - Audit logging for messages
+- Sender verification (phone number, username, Telegram ID)
+- Per-group allowlists
+
+### 3.10 Infrastructure
+- **webhook.ts** (127 LOC) - Webhook mode (alternative to polling)
+- **monitor.ts** (215 LOC) - Health monitoring, connection status
+- **network-errors.ts** (150 LOC) - Recoverable error detection
+- **proxy.ts** - SOCKS5/HTTP proxy support
+- **token.ts** (102 LOC) - Token validation
+- **format.ts** (98 LOC) - Markdown → Telegram HTML
+- **download.ts** - Media file downloads
+- **sent-message-cache.ts** - Deduplication of sent messages
+- **update-offset-store.ts** - Persistent update offset tracking
+
+---
+
+## 4. Feature Mapping: OpenClaw Telegram → OpenCode SDK
+
+| OpenClaw Telegram Feature | OpenCode SDK Equivalent | Implementation Notes |
+|--------------------------|------------------------|---------------------|
+| **Session/Thread Management** | `session.create/get/list/delete` | Map Telegram chat/thread → OpenCode session |
+| **Send Message to AI** | `session.prompt()` | Main interaction point |
+| **Shell Commands** | `session.shell()` | Could support `!command` syntax |
+| **Slash Commands** | `session.command()` | Map Telegram /commands → OpenCode commands |
+| **Abort Response** | `session.abort()` | /cancel command or inline button |
+| **Stream Response** | `global.event()` SSE | Listen for `message.part.updated` events |
+| **Tool Call Updates** | `message.part.updated` events | Show tool progress in chat |
+| **Permission Requests** | `permission.list/respond` | Inline buttons: Allow/Deny/Always |
+| **Question Dialogs** | `question.list/reply/reject` | Inline buttons or reply-based |
+| **Model Selection** | `app.agents()` + config | Inline keyboard like OpenClaw |
+| **Agent Selection** | `app.agents()` | /agent command with inline keyboard |
+| **Session Rename** | `session.update()` | /rename command |
+| **Session Fork** | `session.fork()` | /fork command |
+| **Session Share** | `session.share()` | /share → returns URL |
+| **View Diff** | `session.diff()` | /diff → formatted file changes |
+| **View Todo** | `session.todo()` | /todo → task list |
+| **Revert Changes** | `session.revert/unrevert` | /undo /redo commands |
+| **File Attachment** | `session.prompt()` with FileParts | Photo/document → file part |
+| **Media Download** | Direct from Telegram API | Download → base64 → file part |
+| **Voice Messages** | Download → transcription/attach | Could use whisper or send as audio |
+| **Message History** | `session.messages()` | /history or context loading |
+| **Multi-Project** | `project.list()` + directory header | /project command to switch |
+| **Config** | `config.get/update` | /config command |
+| **Provider Auth** | `auth.set/remove` | /auth command |
+| **Notifications** | `session.idle/error` events | Proactive messages on completion |
+| **Draft Streaming** | `message.part.updated` + edit_message | Edit message as response streams in |
+| **Markdown Formatting** | n/a (SDK returns markdown) | Convert markdown → Telegram HTML |
+| **Message Chunking** | n/a | Split >4096 char messages |
+| **Inline Buttons** | n/a | Permissions, questions, model selection |
+| **Reactions** | n/a | Ack reaction on message receipt |
+| **Group Support** | Works with directory header | Group chat → shared project session |
+| **Forum Topics** | Works with directory header | Topic → separate session |
+| **Error Handling** | `session.error` events | Show errors in chat |
+
+---
+
+## 5. Proposed Architecture
+
+```
+opencode-telegram/
+  src/
+    index.ts              # Entry point, bot startup
+    bot.ts                # Grammy bot creation, middleware
+    session-map.ts        # Telegram chat/thread → OpenCode session mapping
+    handlers/
+      message.ts          # Text + media message handling
+      command.ts          # /start, /new, /model, /agent, /cancel, etc.
+      callback.ts         # Inline button callbacks
+      media.ts            # Photo, document, voice, sticker handling
+    events/
+      listener.ts         # SSE event listener (global.event)
+      dispatcher.ts       # Route events → Telegram responses
+    send/
+      format.ts           # Markdown → Telegram HTML
+      chunker.ts          # Message splitting (4096 limit)
+      media.ts            # Send photos, files, voice
+      draft-stream.ts     # Live response streaming via edit_message
+    ui/
+      permissions.ts      # Inline keyboard for permissions
+      questions.ts        # Inline keyboard for questions
+      models.ts           # Model selection inline keyboard
+      agents.ts           # Agent selection inline keyboard
+    config.ts             # Bot configuration
+    types.ts              # Shared types
+```
+
+### 5.1 Priority Features (MVP)
+
+1. **Session Management** - chat → session mapping, /new, /list
+2. **Prompting** - text messages → `session.prompt()`
+3. **SSE Events** - stream responses back to Telegram
+4. **Response Delivery** - markdown formatting, chunking, streaming edits
+5. **Permission Handling** - inline buttons for allow/deny
+6. **Question Handling** - inline buttons for question replies
+7. **Abort** - /cancel to stop generation
+8. **Model/Agent Selection** - /model, /agent commands with inline keyboards
+9. **File Attachments** - photos/documents → file parts
+10. **Error Handling** - show errors, retry logic
+
+### 5.2 Advanced Features (Post-MVP)
+
+1. **Draft Streaming** - edit message as response arrives
+2. **Group Chat Support** - mention detection, allowlists
+3. **Forum Topics** - topic → session mapping
+4. **Voice Messages** - download + attach as audio
+5. **Slash Commands** - /commit, /review, etc. → `session.command()`
+6. **Shell Mode** - `!ls` → `session.shell()`
+7. **Session Sharing** - /share → public URL
+8. **Diff View** - /diff → formatted file changes
+9. **Multi-Project** - /project to switch directories
+10. **Notifications** - proactive messages on turn completion
+11. **Reactions** - ack reaction on message receipt, reactions on completion
+
+### 5.3 Key Differences from OpenClaw
+
+| Aspect | OpenClaw Telegram | OpenCode Telegram (Proposed) |
+|--------|------------------|------------------------------|
+| Backend | Direct AI agent integration | SDK HTTP client (like web UI) |
+| Session Store | Custom session store | OpenCode manages sessions |
+| Model Catalog | Internal model catalog | `app.agents()` + provider list |
+| Commands | Custom command registry | `command.list()` from OpenCode |
+| Streaming | Token-by-token streaming | SSE `message.part.updated` events |
+| Config | OpenClaw config system | `config.get/update` from SDK |
+| Permissions | Not applicable | Full permission system via SDK |
+| Questions | Not applicable | Full question system via SDK |
+| Multi-Project | Not applicable | Directory header in SDK client |
+
+---
+
+## 6. SDK Methods NOT Used by Web App (Available for Telegram)
+
+These SDK features are available but the web app doesn't use them:
+
+- `pty.*` - Terminal sessions (could power interactive shell in Telegram)
+- `tool.ids/list` - Enumerate available tools
+- `find.text/files/symbols` - Code search
+- `mcp.*` - MCP server management
+- `session.promptAsync()` - Non-blocking prompt (useful for Telegram's async nature)
+- `part.delete/update` - Edit/delete message parts
+- `instance.dispose` - Cleanup
+
+Of particular interest: **`session.promptAsync()`** could be ideal for Telegram since it doesn't block, allowing the bot to handle other messages while waiting for AI responses.