@pedrohnas/opencode-telegram 1.2.1 → 1.3.1

package/docs/PROGRESS.md

@@ -325,3 +325,194 @@ e2e/
 - `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
+
+---
+
+## Phase 5 — Model & Agent Selection ✅
+
+**Status:** Complete
+**Date:** 2026-02-08
+**Plan:** See `docs/plans/phase-5.md`
+
+### Delivered
+- **`/model` command** — Shows providers as inline keyboard. Clicking a provider shows its models. Selecting a model stores a `modelOverride` in SessionEntry, passed to every `session.prompt()`.
+- **`/agent` command** — Shows available agents (filtered: non-hidden) as inline keyboard. Selecting stores `agentOverride` in SessionEntry.
+- **Model reset** — "Reset to default" button clears override.
+- **Agent reset** — Same pattern.
+- **Back navigation** — Model selection supports back→provider list.
+- **Override persistence** — Model/agent overrides survive `/new` and session switches (`/list`).
+- **Callback data encoding** — Uses `mdl:{providerID}:{modelID}` directly (fits 64-byte limit for most providers). Falls back to truncation.
+
+### Tests
+| Type | Count | Status |
+|------|-------|--------|
+| Unit (bun test src/) | 222 | ✅ all pass |
+| E2E Phase 0-4 (regression) | 17 | ✅ all pass |
+| E2E Phase 5 | 3 | ✅ all pass |
+
+### Files Created
+```
+src/
+  handlers/
+    models.ts                      ← formatProviderList, formatModelList, parseModelCallback, handleModel, handleModelSelect
+    models.test.ts                 ← 18 tests
+    agents.ts                      ← formatAgentList, parseAgentCallback, handleAgent, handleAgentSelect
+    agents.test.ts                 ← 10 tests
+e2e/
+  phase-5.test.ts                  ← 3 E2E tests
+```
+
+### Files Modified
+```
+src/
+  session-manager.ts               ← Added modelOverride? and agentOverride? to SessionEntry
+  session-manager.test.ts          ← 3 new tests for override fields
+  bot.ts                           ← /model, /agent commands; mdl: + agt: callback routing;
+                                      pass overrides in handleMessage prompt call
+  bot.test.ts                      ← 6 new tests (override passing, callbacks)
+  index.ts                         ← setMyCommands includes /model and /agent
+```
+
+### Key Design Decisions
+- **Direct ID encoding in callback data** — `mdl:anthropic:claude-sonnet-4-5-20250929` fits 64 bytes. No need for index-based lookup maps.
+- **Override persistence across `/new`** — overrides are per-user preferences, not per-session. Preserved by saving before remove and restoring after create.
+- **Hidden agents filtered** — `sdk.app.agents()` may return hidden agents; we filter them out.
+- **No pagination** — Most providers have <10 models. Deferred for later.
+
+### Lessons Learned
+- SDK v2 uses flat params: `sdk.session.prompt({ sessionID, parts, model: { providerID, modelID } })`, not nested path/body.
+- `sdk.provider.list()` returns `{ data: { all: Provider[] } }` where each Provider has `models: { [modelID]: Model }`.
+
+---
+
+## Phase 6 — Media & Files ✅
+
+**Status:** Complete
+**Date:** 2026-02-08
+**Plan:** See `docs/plans/phase-6.md`
+
+### Delivered
+- **Photo handling** — Highest resolution photo downloaded, converted to base64 data URL, sent as `FilePartInput`.
+- **Document handling** — Any document type (PDF, code, text) downloaded and sent as file part. Original filename preserved.
+- **Voice/Audio handling** — Voice messages (OGG) and audio files downloaded and sent as file parts.
+- **Video handling** — Video files downloaded and sent as file parts.
+- **Caption support** — Caption becomes `TextPartInput` alongside `FilePartInput`.
+- **File size limit** — 20MB check before download (Telegram Bot API limit).
+- **MIME detection** — Extension-based fallback when Telegram doesn't provide MIME type (43 extensions mapped).
+- **DraftStream race condition fix** — Added `sending` flag to prevent concurrent `sendMessage` calls when multiple SSE events arrive before first message is created. Fixes fragmentation with fast models (Gemini Flash).
+- **Override persistence fix** — `handleNew` and `handleSessionCallback` now preserve model/agent overrides across session changes.
+
+### Tests
+| Type | Count | Status |
+|------|-------|--------|
+| Unit (bun test src/) | 252 | ✅ all pass |
+| E2E Phase 0-5 (regression) | 26 | ✅ all pass |
+| E2E Phase 6 | 6 | ✅ all pass |
+
+### Files Created
+```
+src/
+  handlers/
+    media.ts                       ← extractFileRef, downloadTelegramFile, bufferToDataUrl,
+                                      buildFilePart, buildMediaParts, getMimeFromFileName
+    media.test.ts                  ← 21 tests
+e2e/
+  phase-6.test.ts                  ← 6 E2E tests (photo, document, caption, regression text,
+                                      fragmentation, interruption)
+```
+
+### Files Modified
+```
+src/
+  bot.ts                           ← handleMedia function, 5 Grammy media handlers (photo,
+                                      document, voice, audio, video) BEFORE message:text;
+                                      handleMessage accepts optional parts param;
+                                      handleNew/handleSessionCallback preserve overrides
+  bot.test.ts                      ← 6 new tests (media parts, override persistence)
+  send/draft-stream.ts             ← Added `sending` flag to prevent concurrent sendMessage race
+  send/draft-stream.test.ts        ← 3 new tests for race condition scenarios
+e2e/
+  phase-5.test.ts                  ← 6 new tests (model override + persistence + E2E)
+```
+
+### Key Design Decisions
+- **Grammy handler ordering** — Media handlers (`message:photo`, etc.) must come BEFORE `message:text` because photos with captions also match `message:text`.
+- **Shared `handleMedia` function** — All 5 media types share the same handler logic.
+- **Data URL approach** — Download → Buffer → base64 data URL. Simple, no temp files, works within HTTP body limits even for 20MB files (~27MB base64).
+- **`sending` flag pattern** — Based on OpenClaw's `inFlight` pattern: first `update()` sets flag, concurrent calls just store `pending`, flag cleared after `sendMessage` completes.
+
+### Bugs Fixed This Phase
+1. **Streaming fragmentation** — With fast models (Gemini Flash), multiple SSE events called `DraftStream.update()` concurrently. All saw `messageId === null` and each called `sendMessage`, creating N separate messages. Fixed with `sending` guard flag.
+2. **Model/agent override lost on `/new`** — `sessionManager.remove()` deleted the entry with overrides, then `getOrCreate()` created a clean one. Fixed by saving overrides before remove and restoring after.
+
+### Lessons Learned
+- Telegram requires valid PNG encoding — hand-crafted zlib fails, must use `zlib.deflateSync()`.
+- gramjs `CustomFile(name, size, path, buffer)` for sending files in E2E tests.
+- E2E fragmentation test: count bot messages between events, assert ≤ expected (not exact count).
+- `DraftStream` race condition only manifests with fast models (high SSE event rate).
+
+---
+
+## Phase 6.5 — Production Hardening + Bot Control API ✅
+
+**Status:** Complete — deployed to prod as v1.3.0
+**Date:** 2026-02-08
+**Plan:** See `docs/plans/phase-6.5.md`
+**Audit:** See `docs/AUDIT.md`
+
+### Delivered
+- **EventBus auto-reconnect (G1/G5)** — SSE stream break → auto-reconnect with exponential backoff (2s→30s, 1.8x factor, ±25% jitter). Cancellable via `stop()`.
+- **Grammy `apiThrottler()` (G2)** — API transformer that queues and retries on Telegram 429 rate limits.
+- **Grammy `sequentialize()` (G3)** — First middleware, ensures per-chat serial update processing. Prevents race conditions with webhooks.
+- **Smart /model filtering (G12)** — Only connected providers, models grouped by family (most recent per family), active model marked with ✓. Reduces ~400 models → ~16.
+- **Bot Control API** — Hono HTTP server on `127.0.0.1:4097` exposing 7 endpoints for AI-driven model/agent/session control.
+- **SKILL.md** — Teaches AI how to discover its sessionId and use the Bot Control API.
+
+### Tests
+| Type | Count | Status |
+|------|-------|--------|
+| Unit (bun test src/) | 295 | ✅ all pass |
+| E2E Phase 6.5 | 9 | ✅ all pass |
+| E2E Full regression | 41 | ✅ all pass |
+
+### Files Created
+```
+src/
+  api-server.ts                    ← Hono app + createApiServer (Bot Control API)
+  api-server.test.ts               ← 15 tests (all endpoints via app.request())
+e2e/
+  phase-6.5.test.ts                ← 9 E2E tests (/model filtering + Bot Control API)
+docs/plans/
+  phase-6.5.md                     ← Phase plan
+```
+
+### Deployed
+- SKILL.md at `~/.claude/skills/telegram-control/` (WSL + VPS)
+- npm: `@pedrohnas/opencode-telegram@1.3.0`
+
+### Files Modified
+```
+src/
+  event-bus.ts                     ← reconnectLoop + exponential backoff + cancellable sleep
+  event-bus.test.ts                ← 13 new tests (reconnect, backoff, jitter, error recovery)
+  bot.ts                           ← sequentialize() middleware + filterModels in mdl: callback
+  bot.test.ts                      ← 3 new tests (sequentialize, throttler import)
+  config.ts                        ← Added apiPort config (TELEGRAM_API_PORT, default 4097)
+  config.test.ts                   ← 2 new tests for apiPort
+  index.ts                         ← apiThrottler + createApiServer + apiServer.stop in shutdown
+  handlers/models.ts               ← filterModels(), formatProviderList(connected), formatModelList(activeModelID)
+  handlers/models.test.ts          ← 8 new tests (filtering, connected, ✓ marker)
+  package.json                     ← Added hono, @grammyjs/transformer-throttler, @grammyjs/runner
+```
+
+### New Dependencies
+- `hono` ^4.x — HTTP framework for Bot Control API
+- `@grammyjs/transformer-throttler` ^1.x — Telegram API 429 rate limit handling
+- `@grammyjs/runner` ^2.x — sequentialize middleware for per-chat serial processing
+
+### Key Design Decisions
+- **Bot Control API on localhost** — AI calls it via `curl` from bash. No auth needed (bound to 127.0.0.1 only).
+- **AI self-identification** — AI discovers its sessionId by calling OpenCode session list (`localhost:4096/session`), matches title pattern `"Telegram {chatId}"`.
+- **filterModels pattern** — Group by family, sort by release_date descending, pick first. Handles missing family (uses model id as key).
+- **Hono test pattern** — `app.request()` — no real Bun.serve needed in tests.
+- **EventBus backoff** — `delay = min(maxDelay, initialDelay × factor^attempt) × (1 ± jitter)`. Cancellable sleep via sleepReject.

package/docs/plans/phase-5.md

@@ -0,0 +1,410 @@
+# Phase 5 — Model & Agent Selection
+
+**Goal:** Let users pick which AI model and agent to use per-chat via inline
+keyboards. The SDK already supports per-prompt overrides (`session.prompt({
+model, agent })`), so this phase adds the UI layer and per-chat state.
+
+## What This Phase Delivers
+
+1. **`/model` command** — Shows a two-step inline keyboard:
+   first pick a provider, then pick a model from that provider.
+   The selection is stored as a per-chat override applied to every subsequent prompt.
+
+2. **`/agent` command** — Shows available agents (non-hidden) as an inline keyboard.
+   Selecting one stores the override per-chat.
+
+3. **Per-chat overrides in SessionEntry** — Optional `modelOverride` and
+   `agentOverride` fields, passed to `sdk.session.prompt()` on every message.
+
+4. **Reset buttons** — Both `/model` and `/agent` include a "Reset to default"
+   button to clear the override.
+
+## SDK Endpoints Used
+
+```ts
+// Fetch all providers with their models
+sdk.provider.list()
+// → { all: Provider[] }
+// Each Provider: { id, name, models: { [modelID]: Model } }
+// Each Model: { id, name, cost?, limit?, capabilities?, ... }
+
+// Fetch all agents
+sdk.app.agents()
+// → Agent[]
+// Each Agent: { name, description?, mode, hidden?, ... }
+
+// Per-prompt override (existing — just need to pass the fields)
+sdk.session.prompt({
+  sessionID: string,
+  parts: [...],
+  model?: { providerID: string, modelID: string },  // ← override
+  agent?: string,                                     // ← override
+})
+```
+
+## Architecture
+
+### Model Selection Flow
+
+```
+/model
+  → sdk.provider.list()
+  → Filter providers that have ≥1 model
+  → Show provider keyboard (1 per row, max 8)
+  → callback_data: "mdl:{providerID}"
+
+User clicks provider
+  → sdk.provider.list() (re-fetch for models)
+  → Show model keyboard for that provider + "⬅ Back" button
+  → callback_data: "mdl:{providerID}:{modelID}" or "mdl:back"
+
+User clicks model
+  → sessionManager.get(chatKey) → set modelOverride
+  → editMessageText: "Model set to: {providerName} / {modelName}"
+
+User clicks "⬅ Back"
+  → Re-show provider list
+
+User clicks "Reset to default"
+  → Clear modelOverride from SessionEntry
+  → editMessageText: "Model reset to default."
+```
+
+### Agent Selection Flow
+
+```
+/agent
+  → sdk.app.agents()
+  → Filter: not hidden
+  → Show agent keyboard (1 per row) + "Reset to default" button
+  → callback_data: "agt:{agentName}" or "agt:reset"
+
+User clicks agent
+  → sessionManager.get(chatKey) → set agentOverride
+  → editMessageText: "Agent set to: {agentName}"
+
+User clicks reset
+  → Clear agentOverride from SessionEntry
+  → editMessageText: "Agent reset to default."
+```
+
+### Override Passing in handleMessage
+
+```
+BEFORE:
+  sdk.session.prompt({
+    sessionID: entry.sessionId,
+    parts: [{ type: "text", text }],
+  })
+
+AFTER:
+  sdk.session.prompt({
+    sessionID: entry.sessionId,
+    parts: [{ type: "text", text }],
+    ...(entry.modelOverride && { model: entry.modelOverride }),
+    ...(entry.agentOverride && { agent: entry.agentOverride }),
+  })
+```
+
+## Callback Data Design
+
+```
+Model callbacks:
+  mdl:{providerID}                    → show models for provider
+  mdl:{providerID}:{modelID}          → select model
+  mdl:back                            → back to provider list
+  mdl:reset                           → clear model override
+
+  Examples:
+    "mdl:anthropic"                              = 14 bytes ✓
+    "mdl:anthropic:claude-sonnet-4-5-20250929"   = 43 bytes ✓
+    "mdl:back"                                   = 8 bytes ✓
+    "mdl:reset"                                  = 9 bytes ✓
+
+  Worst case: "mdl:" + 20-char provider + ":" + 38-char model = 63 bytes ✓
+
+Agent callbacks:
+  agt:{agentName}                     → select agent
+  agt:reset                           → clear agent override
+
+  Examples:
+    "agt:code"                                   = 8 bytes ✓
+    "agt:reset"                                  = 9 bytes ✓
+```
+
+## SessionEntry Changes
+
+```ts
+export type SessionEntry = {
+  sessionId: string
+  directory: string
+  createdAt: number
+  lastAccessAt: number
+  modelOverride?: { providerID: string; modelID: string }  // ← NEW
+  agentOverride?: string                                     // ← NEW
+}
+```
+
+## Grammy Middleware Stack (updated)
+
+```
+  1. allowlistMiddleware(config.allowedUsers)
+  2. bot.command("start", ...)
+  3. bot.command("new", ...)
+  4. bot.command("list", ...)
+  5. bot.command("rename", ...)
+  6. bot.command("delete", ...)
+  7. bot.command("info", ...)
+  8. bot.command("history", ...)
+  9. bot.command("summarize", ...)
+  10. bot.command("model", ...)              ← NEW
+  11. bot.command("agent", ...)              ← NEW
+  12. bot.command("cancel", ...)
+  13. bot.on("callback_query:data", ...)     ← Extended with mdl: and agt: prefixes
+  14. bot.on("message:text", ...)            ← Modified (pass overrides to prompt)
+```
+
+## New Files
+
+```
+src/
+  handlers/
+    models.ts                    ← formatProviderList, formatModelList,
+                                   parseModelCallback, formatCurrentModel,
+                                   handleModel, handleModelSelect
+    models.test.ts               ← ~18 tests
+    agents.ts                    ← formatAgentList, parseAgentCallback,
+                                   handleAgent, handleAgentSelect
+    agents.test.ts               ← ~10 tests
+e2e/
+  phase-5.test.ts                ← 3 E2E tests
+```
+
+## Modified Files
+
+```
+src/
+  session-manager.ts             ← Add modelOverride? and agentOverride? to SessionEntry
+  session-manager.test.ts        ← 3 new tests for override fields
+  bot.ts                         ← /model, /agent commands, mdl: + agt: callback routing,
+                                   pass overrides in handleMessage prompt call
+  bot.test.ts                    ← ~6 new tests (override passing, new commands)
+  index.ts                       ← Add model/agent to setMyCommands
+```
+
+## TDD Execution Order (bottom-up by dependency)
+
+### Group A — Foundational / Independent Pieces
+
+#### A1. session-manager.ts — model/agent override fields (3 new tests)
+
+Add optional fields to SessionEntry type. No logic changes needed — `set()`
+already stores the full entry object and `get()` returns it.
+
+Tests:
+1. `set/get` with `modelOverride` preserves value
+2. `set/get` with `agentOverride` preserves value
+3. `getOrCreate` returns entry without overrides by default
+
+#### A2. handlers/models.ts — model selection (18 tests)
+
+Pure functions + thin async handlers.
+
+**Pure functions:**
+
+```ts
+formatProviderList(providers: any[]): { text: string; reply_markup: any }
+// → Inline keyboard: one row per provider, button text = provider name
+// → callback_data = "mdl:{providerID}"
+// → Last row: "Reset to default" button (mdl:reset) if override active
+
+formatModelList(providerID: string, providerName: string, models: any[]): { text: string; reply_markup: any }
+// → Inline keyboard: one row per model, button text = model name
+// → callback_data = "mdl:{providerID}:{modelID}"
+// → Last row: "⬅ Back" button (mdl:back)
+
+parseModelCallback(data: string):
+  | { type: "provider"; providerID: string }
+  | { type: "model"; providerID: string; modelID: string }
+  | { type: "back" }
+  | { type: "reset" }
+  | null
+
+formatCurrentModel(override?: { providerID: string; modelID: string }): string
+// → "Current model: {providerID}/{modelID}" or "Using default model"
+```
+
+**Async handlers:**
+
+```ts
+handleModel(params: { sdk, sessionManager, chatKey }):
+  Promise<{ text: string; reply_markup: any }>
+// → Fetches providers, prepends current model text, returns provider keyboard
+
+handleModelSelect(params: { chatKey, providerID, modelID, sessionManager }):
+  Promise<string>
+// → Stores override in SessionEntry, returns confirmation text
+```
+
+Tests:
+1. `parseModelCallback("mdl:anthropic")` → `{ type: "provider", providerID: "anthropic" }`
+2. `parseModelCallback("mdl:anthropic:claude-sonnet")` → `{ type: "model", providerID: "anthropic", modelID: "claude-sonnet" }`
+3. `parseModelCallback("mdl:back")` → `{ type: "back" }`
+4. `parseModelCallback("mdl:reset")` → `{ type: "reset" }`
+5. `parseModelCallback("invalid")` → `null`
+6. `parseModelCallback("mdl:")` → `null` (empty after prefix)
+7. `formatProviderList` with 2 providers → 2 button rows
+8. `formatProviderList` with 0 providers → "No providers available."
+9. `formatProviderList` filters providers with 0 models
+10. `formatModelList` with 3 models → 3 button rows + back button
+11. `formatModelList` with 0 models → "No models available." + back button
+12. `formatModelList` callback_data includes providerID and modelID
+13. `formatCurrentModel` with override → shows provider/model
+14. `formatCurrentModel` without override → "Using default model"
+15. `handleModel` fetches providers and returns keyboard
+16. `handleModel` returns "No providers" when list is empty
+17. `handleModelSelect` stores override in sessionManager
+18. `handleModelSelect` returns confirmation message
+
+#### A3. handlers/agents.ts — agent selection (10 tests)
+
+**Pure functions:**
+
+```ts
+formatAgentList(agents: any[]): { text: string; reply_markup: any }
+// → Inline keyboard: one row per agent (non-hidden), button text = name
+// → callback_data = "agt:{name}"
+// → Last row: "Reset to default" button (agt:reset)
+
+parseAgentCallback(data: string):
+  | { name: string }
+  | { action: "reset" }
+  | null
+```
+
+**Async handlers:**
+
+```ts
+handleAgent(params: { sdk, sessionManager, chatKey }):
+  Promise<{ text: string; reply_markup: any }>
+
+handleAgentSelect(params: { chatKey, agentName, sessionManager }):
+  Promise<string>
+```
+
+Tests:
+1. `parseAgentCallback("agt:code")` → `{ name: "code" }`
+2. `parseAgentCallback("agt:reset")` → `{ action: "reset" }`
+3. `parseAgentCallback("invalid")` → `null`
+4. `parseAgentCallback("agt:")` → `null`
+5. `formatAgentList` with 2 agents → 2 rows + reset row
+6. `formatAgentList` filters hidden agents
+7. `formatAgentList` with 0 agents → "No agents available."
+8. `handleAgent` fetches agents and returns keyboard
+9. `handleAgentSelect` stores override in sessionManager
+10. `handleAgentSelect` returns confirmation message
+
+### Group B — Wiring (bot.ts + index.ts)
+
+#### B4. bot.ts — New commands, callback routing, override passing (6 new tests)
+
+Changes:
+- Add `/model` command → calls `handleModel`, replies with keyboard
+- Add `/agent` command → calls `handleAgent`, replies with keyboard
+- Add `mdl:` callback routing (provider select → show models, model select → store, back → providers, reset → clear)
+- Add `agt:` callback routing (select → store, reset → clear)
+- Modify `handleMessage` prompt call to spread `modelOverride` and `agentOverride`
+
+New tests:
+1. `handleMessage` passes `modelOverride` to `sdk.session.prompt` when set
+2. `handleMessage` passes `agentOverride` to `sdk.session.prompt` when set
+3. `handleMessage` passes no model/agent when overrides not set
+4. `handleMessage` passes both overrides simultaneously
+5. (integration covered by E2E for /model and /agent commands)
+
+#### B5. index.ts — Command menu update
+
+Add to `setMyCommands` array:
+```ts
+{ command: "model", description: "Select model" },
+{ command: "agent", description: "Select agent" },
+```
+
+### Group C — E2E Tests
+
+#### C6. E2E: phase-5.test.ts (3 tests) + full regression
+
+```ts
+describe("Phase 5 — Model & Agent Selection", () => {
+  test("/model shows provider buttons", async () => {
+    const reply = await sendAndWait(client, BOT, "/model", 15000)
+    assertHasButtons(reply)
+  }, 30000)
+
+  test("/agent shows agent buttons", async () => {
+    const reply = await sendAndWait(client, BOT, "/agent", 15000)
+    assertHasButtons(reply)
+  }, 30000)
+
+  test("regression: text message still works", async () => {
+    const reply = await sendAndWait(client, BOT, "Say hello", 60000)
+    expect(reply.text.length).toBeGreaterThan(0)
+  }, 90000)
+})
+```
+
+Full regression: phases 0-5 E2E all pass.
+
+## Edge Cases
+
+### Model Selection
+- Provider with 0 models → filtered out of list
+- Model ID with colons in it → `parseModelCallback` splits on first two colons only
+- `modelOverride` set but provider deleted from server → prompt fails gracefully (SDK error, not bot crash)
+- User switches session via `/list` → override stays (it's per-chatKey, not per-session)
+
+### Agent Selection
+- Hidden agents → filtered out of keyboard
+- Agent name with special chars → callback_data must be safe ASCII
+- No agents configured → "No agents available."
+
+### Override Persistence
+- Overrides live in SessionManager (in-memory) → lost on bot restart
+- This is acceptable: model/agent preference is lightweight, user re-selects if needed
+- SessionEntry eviction (LRU/TTL) also clears overrides — consistent behavior
+
+## Acceptance Criteria
+
+- [ ] `/model` shows provider list with inline keyboard
+- [ ] Selecting provider shows model list for that provider
+- [ ] Selecting model stores override and shows confirmation
+- [ ] "Reset to default" clears model override
+- [ ] "⬅ Back" returns to provider list
+- [ ] `/agent` shows agent list with inline keyboard
+- [ ] Selecting agent stores override and shows confirmation
+- [ ] "Reset to default" clears agent override
+- [ ] Hidden agents excluded from list
+- [ ] Next prompt uses selected model/agent override
+- [ ] Overrides are per-chat (different chats have independent settings)
+- [ ] Commands appear in Telegram "/" menu
+- [ ] `bun test src/` passes (all unit tests)
+- [ ] `bun test ./e2e/phase-5.test.ts` passes
+- [ ] All Phase 0-4 E2E tests still pass (regression)
+
+## Estimated Scope
+
+- 2 new source files + 2 test files + 1 E2E test file
+- ~200-250 LOC (src) + ~350-400 LOC (tests)
+- Modified: session-manager.ts, session-manager.test.ts, bot.ts, bot.test.ts, index.ts
+
+### Test Count Estimate
+
+| File | New Tests |
+|------|-----------|
+| session-manager.test.ts | 3 |
+| handlers/models.test.ts | 18 |
+| handlers/agents.test.ts | 10 |
+| bot.test.ts | 4 |
+| **Unit total** | **~35 new → ~222 total** |
+| E2E phase-5.test.ts | 3 |
+| **E2E total** | **3 new → ~20 total** |