@pedrohnas/opencode-telegram 1.2.0 → 1.3.0

package/.claude/skills/playwright-cli/data/page-2026-02-09T01-56-35-534Z.yml

@@ -0,0 +1,49 @@
+- generic [ref=e3]:
+  - region "Site notifications" [ref=e4]:
+    - generic [ref=e8]:
+      - generic [ref=e9]: ⚠️
+      - alert [ref=e11]:
+        - text: "Security Update: Classic tokens have been revoked. Granular tokens are now limited to 90 days and require 2FA by default. Update your CI/CD workflows to avoid disruption."
+        - link "Learn more about npm authentication changes" [ref=e12] [cursor=pointer]:
+          - /url: https://gh.io/all-npm-classic-tokens-revoked
+          - text: Learn more
+        - text: .
+      - button "Close notification" [ref=e13] [cursor=pointer]: ×
+  - generic [ref=e14]:
+    - banner [ref=e15]:
+      - link "Npm" [ref=e18] [cursor=pointer]:
+        - /url: /
+        - img [ref=e19]
+    - main [ref=e21]:
+      - generic [ref=e22]:
+        - heading "Manage Recovery Codes" [level=1] [ref=e23]
+        - generic [ref=e25]:
+          - heading "Manage Recovery Codes" [level=2] [ref=e26]
+          - generic [ref=e27]:
+            - generic [ref=e28]:
+              - img [ref=e30]
+              - heading "Recovery Codes" [level=3] [ref=e36]
+              - paragraph [ref=e37]: Please make sure you have saved your codes in a secure place.
+            - generic [ref=e38]:
+              - button "65f3c8c151b712df1aafdbd003dd13eadb9c6ee9d687c2e3013d8f6add1fc36a 05a76c8c99cb696bd35b7caac484098cb19c653ea310483d6c695de277461398 4c70ca25505284883c2e225357d90fd9fb55ad56eae75a81bd1bb5486f7cb315 a6278db03b5e5f380f865550d119f6235517eced0e5bee47b25c603b4c23ad1c e614086e2300d1679d3e7dea55ab11d4bbe8d1a2843a1a0eefd28a62bf4dbd1e" [ref=e39]:
+                - paragraph [ref=e40]: 65f3c8c151b712df1aafdbd003dd13eadb9c6ee9d687c2e3013d8f6add1fc36a
+                - paragraph [ref=e41]: 05a76c8c99cb696bd35b7caac484098cb19c653ea310483d6c695de277461398
+                - paragraph [ref=e42]: 4c70ca25505284883c2e225357d90fd9fb55ad56eae75a81bd1bb5486f7cb315
+                - paragraph [ref=e43]: a6278db03b5e5f380f865550d119f6235517eced0e5bee47b25c603b4c23ad1c
+                - paragraph [ref=e44]: e614086e2300d1679d3e7dea55ab11d4bbe8d1a2843a1a0eefd28a62bf4dbd1e
+              - generic [ref=e46]:
+                - button "Copy" [ref=e47]:
+                  - img [ref=e48]
+                  - text: Copy
+                - button "Download" [ref=e50] [cursor=pointer]:
+                  - img [ref=e51]
+                  - text: Download
+                - button "Print" [ref=e55]:
+                  - img [ref=e56]
+                  - text: Print
+            - generic [ref=e58]:
+              - heading "Generate New Recovery Codes" [level=3] [ref=e59]
+              - paragraph [ref=e60]: When you generate new recovery codes, you must download or print the new codes. Your old codes won’t work anymore.
+              - button "Generate new recovery codes" [ref=e62]
+        - link "Go back to settings" [ref=e64] [cursor=pointer]:
+          - /url: /settings/pedrohnas/tfa/list

package/.claude/skills/playwright-cli/data/page-2026-02-09T01-57-04-658Z.yml

@@ -0,0 +1,52 @@
+- generic [ref=e3]:
+  - region "Site notifications" [ref=e4]:
+    - generic [ref=e8]:
+      - generic [ref=e9]: ⚠️
+      - alert [ref=e11]:
+        - text: "Security Update: Classic tokens have been revoked. Granular tokens are now limited to 90 days and require 2FA by default. Update your CI/CD workflows to avoid disruption."
+        - link "Learn more about npm authentication changes" [ref=e12] [cursor=pointer]:
+          - /url: https://gh.io/all-npm-classic-tokens-revoked
+          - text: Learn more
+        - text: .
+      - button "Close notification" [ref=e13] [cursor=pointer]: ×
+  - generic [ref=e16]:
+    - alert [ref=e18]: Successfully generated new recovery codes.
+    - button "Close notification" [active] [ref=e19] [cursor=pointer]: ×
+  - generic [ref=e20]:
+    - banner [ref=e21]:
+      - link "Npm" [ref=e24] [cursor=pointer]:
+        - /url: /
+        - img [ref=e25]
+    - main [ref=e27]:
+      - generic [ref=e28]:
+        - heading "Manage Recovery Codes" [level=1] [ref=e29]
+        - generic [ref=e31]:
+          - heading "Manage Recovery Codes" [level=2] [ref=e32]
+          - generic [ref=e33]:
+            - generic [ref=e34]:
+              - img [ref=e36]
+              - heading "Recovery Codes" [level=3] [ref=e42]
+              - paragraph [ref=e43]: Please make sure you have saved your codes in a secure place.
+            - generic [ref=e44]:
+              - button "578abdc2cb48fb0b41b1412a2b02024955524ec30cb2d04e810da940dd264567 fcaae8cf53d18eb3d551e9b1c94a59eb9d0ff92375aacbc12f9761d34b7e74c1 996ce0478fa870cf6eec988e5a5e53b432f10fd1c2b6c3f430edc9f1a6b96905 3685bbc53649f71a076068bab844c9d9702d17d00858ccefdbd5bfefcc35aa3c 35c5f6a1fd6cefa84d2e6c4f399a5a821c4764ae46fd3b4f88a1523b463d2966" [ref=e45]:
+                - paragraph [ref=e46]: 578abdc2cb48fb0b41b1412a2b02024955524ec30cb2d04e810da940dd264567
+                - paragraph [ref=e47]: fcaae8cf53d18eb3d551e9b1c94a59eb9d0ff92375aacbc12f9761d34b7e74c1
+                - paragraph [ref=e48]: 996ce0478fa870cf6eec988e5a5e53b432f10fd1c2b6c3f430edc9f1a6b96905
+                - paragraph [ref=e49]: 3685bbc53649f71a076068bab844c9d9702d17d00858ccefdbd5bfefcc35aa3c
+                - paragraph [ref=e50]: 35c5f6a1fd6cefa84d2e6c4f399a5a821c4764ae46fd3b4f88a1523b463d2966
+              - generic [ref=e52]:
+                - button "Copy" [ref=e53]:
+                  - img [ref=e54]
+                  - text: Copy
+                - button "Download" [ref=e56] [cursor=pointer]:
+                  - img [ref=e57]
+                  - text: Download
+                - button "Print" [ref=e61]:
+                  - img [ref=e62]
+                  - text: Print
+            - generic [ref=e64]:
+              - heading "Generate New Recovery Codes" [level=3] [ref=e65]
+              - paragraph [ref=e66]: When you generate new recovery codes, you must download or print the new codes. Your old codes won’t work anymore.
+              - button "Generate new recovery codes" [ref=e68]
+        - link "Go back to settings" [ref=e70] [cursor=pointer]:
+          - /url: /settings/pedrohnas/tfa/list

package/docs/AUDIT.md

@@ -0,0 +1,193 @@
+# Audit Report — OpenCode Telegram Bot vs OpenClaw Reference
+
+**Date:** 2026-02-08
+**Scope:** Phases 0-6 complete, comparison against OpenClaw Telegram integration (~3,500 LOC, 41 files)
+
+---
+
+## 1. Project Stats
+
+| Metric | Our Bot | OpenClaw |
+|--------|---------|----------|
+| Source LOC | 2,580 (21 files) | ~3,500 (41 files) |
+| Unit tests | 252 | ~200+ (estimated) |
+| E2E tests | 32 | Manual |
+| Total LOC (incl tests + E2E) | ~7,000 | ~10,000+ |
+| Architecture | SDK HTTP bridge | Direct agent integration |
+| Framework | Grammy | Grammy |
+| Runtime | Bun | Node.js |
+
+---
+
+## 2. Quality Assessment by Phase
+
+### Phases 0-4: Excellent
+
+The core foundation is solid:
+- **Anti-leak architecture** consistently applied (LRU, AbortController, bounded Maps)
+- **TDD discipline** maintained — every file has colocated tests
+- **EventBus** single SSE design is clean and memory-efficient
+- **DraftStream** throttled editing works well
+- **Permission/Question** handling with PendingRequests + inline keyboards is correct
+- **Session management** with restore-on-restart is production-ready
+
+### Phase 5 (Model & Agent Selection): Good
+
+- Clean separation: `models.ts` (139 LOC) and `agents.ts` (93 LOC)
+- Callback data fits 64-byte limit using direct IDs
+- Override persistence across `/new` and session switches — properly fixed
+- 28 unit tests + 9 E2E tests
+- **Minor issue:** No pagination for providers with many models (deferred, acceptable)
+
+### Phase 6 (Media & Files): Good
+
+- Download/conversion pipeline is correct and well-tested
+- MIME map is comprehensive (43 extensions)
+- File size limit enforcement works
+- DraftStream race condition properly fixed with `sending` flag
+- 21 unit tests + 6 E2E tests (including fragmentation regression)
+- **Minor issue:** `handleMedia` in bot.ts is an inline anonymous function, not exported for direct unit testing. It works via E2E tests, but differs from the pattern of other exported handlers.
+
+---
+
+## 3. Production Gaps (vs OpenClaw)
+
+### Critical — Should fix before production
+
+| # | Gap | Impact | Effort |
+|---|-----|--------|--------|
+| **G1** | **EventBus has no auto-reconnect** | SSE stream break = bot stops receiving events silently. No exponential backoff. | Medium |
+| **G2** | **No Grammy `apiThrottler()` middleware** | Telegram API 429 rate limits not handled. Under high load, API calls fail. | Low |
+| **G3** | **No `sequentialize()` middleware** | Race conditions possible if Grammy processes concurrent updates for same chat (unlikely in polling mode, but risky with webhooks). | Low |
+
+### Important — Should fix for robustness
+
+| # | Gap | Impact | Effort |
+|---|-----|--------|--------|
+| **G4** | **No error classification** | Network errors (ECONNRESET, ETIMEDOUT) not distinguished from fatal errors. All treated the same. | Medium |
+| **G5** | **EventBus `listen()` doesn't retry** | If the SSE stream ends (server restart, network issue), the bot goes deaf. No automatic reconnection. | Medium |
+| **G6** | **No update deduplication** | Telegram can deliver duplicate updates. We process them again. | Low |
+
+### Nice to have — For future phases
+
+| # | Gap | Impact | Effort |
+|---|-----|--------|--------|
+| G7 | No text fragment assembly | Users who paste >4096 chars get each fragment processed separately | Medium |
+| G8 | No media group buffering | Multi-photo sends = N separate prompts instead of one combined | Medium |
+| G9 | No inbound debouncing | Rapid messages processed individually (can flood the AI) | Low |
+| G10 | No sent-message cache | Can't deduplicate outbound messages | Low |
+| G11 | No update offset persistence | Bot restart may re-process recent updates | Low |
+
+---
+
+## 4. Code Structure Analysis
+
+### Strengths
+
+1. **Clean module boundaries** — Each handler file is self-contained with pure functions + async handlers
+2. **Dependency injection** — `DraftStreamDeps`, `BotDeps`, SDK as params (not globals)
+3. **Testability** — Every handler can be tested without Grammy context
+4. **Anti-leak guarantees** — AbortController per turn, LRU bounded SessionManager, TTL on PendingRequests
+5. **Session restore** — Bot survives restarts by matching "Telegram {chatId}" title pattern
+
+### Areas for Improvement
+
+1. **`bot.ts` is growing** (479 LOC) — Approaching the split threshold. Consider extracting:
+   - Callback routing → `handlers/callbacks.ts`
+   - `handleMedia` → export from `handlers/media.ts` for testability
+   - `handleMessage` is already well-structured
+
+2. **`index.ts` does too much** (283 LOC) — Event routing and `finalizeResponse` live in the entry point. Should be in a dedicated `event-router.ts` for unit testability.
+
+3. **Event types are `any`** — EventBus uses `any` for event types. Type-safe event handling would catch bugs at compile time.
+
+4. **No structured logging** — All errors go to `console.error`. No log levels, no structured format, no error context.
+
+---
+
+## 5. What We Do Better Than OpenClaw
+
+| Aspect | Our Advantage |
+|--------|--------------|
+| **Architecture** | SDK bridge is thinner (~2,580 LOC vs ~3,500). Delegates AI complexity to server. |
+| **Testing** | 252 unit + 32 E2E with TDD rigor. Phase-gated with full regression at each step. |
+| **Memory safety** | Explicit anti-leak design: LRU, AbortController, bounded everything. |
+| **Deployment** | Simple env vars (4-5 vars). No YAML config, no multi-account, no pairing system. |
+| **Session management** | Server-side persistence with local LRU cache. Clean restore on restart. |
+| **Phase gating** | Clear boundaries, docs per phase, regression testing. Sustainable development. |
+
+---
+
+## 6. Feature Parity Matrix
+
+| Feature | Our Bot | OpenClaw | Notes |
+|---------|---------|----------|-------|
+| Text messages | ✅ | ✅ | |
+| Photo/Document/Audio/Video | ✅ | ✅ | Phase 6 |
+| Voice messages | ✅ | ✅ | |
+| Streaming (edit draft) | ✅ | ✅ | With `sending` fix |
+| Permissions (inline buttons) | ✅ | N/A | OpenClaw has no permission system |
+| Questions (inline buttons) | ✅ | N/A | OpenClaw has no question system |
+| /cancel (abort) | ✅ | ✅ | |
+| Session management | ✅ | ✅ | /list, /rename, /delete, /info, /history |
+| Session restore on restart | ✅ | ✅ | Title pattern matching |
+| Model selection | ✅ | ✅ | Phase 5 |
+| Agent selection | ✅ | N/A | OpenClaw has different agent system |
+| Allowlist | ✅ | ✅ | |
+| Markdown → HTML | ✅ | ✅ | |
+| Message chunking | ✅ | ✅ | |
+| HTML fallback | ✅ | ✅ | |
+| Typing indicator | ✅ | ✅ | |
+| Tool progress | ✅ | N/A | |
+| Auto-reconnect SSE | ❌ | ✅ | **Gap G1/G5** |
+| Rate limit middleware | ❌ | ✅ | **Gap G2** |
+| Sequentialize middleware | ❌ | ✅ | **Gap G3** |
+| Text fragment assembly | ❌ | ✅ | Gap G7 |
+| Media group buffering | ❌ | ✅ | Gap G8 |
+| Inbound debouncing | ❌ | ✅ | Gap G9 |
+| Group chat support | ❌ | ✅ | Phase 8 planned |
+| Forum topics | ❌ | ✅ | Phase 8 planned |
+| Webhook mode | ❌ | ✅ | Phase 9 planned |
+| Sticker vision cache | ❌ | ✅ | Nice to have |
+| Voice → voice bubble | ❌ | ✅ | Nice to have |
+| Multi-account | ❌ | ✅ | Not needed |
+| Audit logging | ❌ | ✅ | Not needed |
+| Update offset persistence | ❌ | ✅ | Gap G11 |
+
+---
+
+## 7. Recommendations
+
+### Before Production (Priority)
+
+1. **Fix EventBus reconnection (G1+G5)** — Add exponential backoff loop in `listen()`. When SSE stream ends or errors, wait 2s→30s (1.8x factor) and reconnect. This is the most critical gap.
+
+2. **Add `apiThrottler()` (G2)** — One line of Grammy middleware. Prevents 429 errors.
+
+3. **Add `sequentialize()` (G3)** — One line of Grammy middleware. Prevents per-chat race conditions (important if switching to webhooks later).
+
+### Before Phase 7 (Recommended)
+
+4. **Extract event routing from index.ts** — Move `onEvent` callback and `finalizeResponse` to `event-router.ts`. Enables unit testing of event logic.
+
+5. **Type SSE events** — Replace `any` with typed event union in EventBus.
+
+### For Future Phases
+
+6. **Text fragment assembly (G7)** — Buffer near-limit messages for 1500ms, merge.
+7. **Media group buffering (G8)** — Buffer same `media_group_id` for 200ms.
+8. **Inbound debouncing (G9)** — 300-500ms buffer for rapid messages.
+
+---
+
+## 8. Overall Assessment
+
+**The codebase quality is good.** Phases 5 and 6 maintained the same standards as earlier phases:
+- Clean module boundaries
+- Comprehensive test coverage
+- Anti-leak design throughout
+- Bugs found via manual testing were properly diagnosed and fixed with tests
+
+**The main gaps are infrastructure-level** (reconnection, rate limiting, middleware), not code quality issues. These are expected at the Phase 6 stage and should be addressed in Phase 9 (Infrastructure & Security) or as a hardening pass before production deployment.
+
+**LOC target from spec was ~2,000 for Phase 1.** At Phase 6 we're at 2,580 for all source — well within the expected trajectory toward the spec's full target.

package/docs/PROGRESS.md

@@ -325,3 +325,191 @@ 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 (unit tests pass, E2E written — awaiting E2E run)
+**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 | 8 | Written, pending run |
+
+### Files Created
+```
+src/
+  api-server.ts                    ← Hono app + createApiServer (Bot Control API)
+  api-server.test.ts               ← 15 tests (all endpoints via app.request())
+deploy/
+  skills/
+    telegram-control/
+      SKILL.md                     ← AI skill doc for Bot Control API
+e2e/
+  phase-6.5.test.ts                ← 8 E2E tests (/model filtering + Bot Control API)
+```
+
+### 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.