@pedrohnas/opencode-telegram 0.1.0 → 1.2.0

package/docs/plans/phase-1.md

@@ -0,0 +1,176 @@
+# Phase 1 — Core Loop (MVP)
+
+**Goal:** Send a text message → OpenCode processes it → formatted response in Telegram.
+
+## What This Phase Delivers
+
+The minimum viable bot: a user sends a message, OpenCode's AI processes it,
+and the bot replies with a formatted response. This is the foundation everything
+else builds on.
+
+## Architecture
+
+```
+User sends text message
+  → bot.on("message")
+    → SessionManager.getOrCreate(chatId) → OpenCode session
+    → sdk.session.prompt({ parts: [{ type: "text", text }] })
+
+[EventBus receives SSE events]
+  → message.part.updated (type: "text") → accumulate text
+  → session.idle → send final formatted response
+  → session.error → send error message
+```
+
+## New Files
+
+```
+src/
+  sdk.ts                        ← SDK client factory (createOpencode wrapper)
+  sdk.test.ts
+  session-manager.ts            ← LRU Map<chatKey, SessionEntry>
+  session-manager.test.ts
+  turn-manager.ts               ← Per-turn lifecycle (AbortController)
+  turn-manager.test.ts
+  event-bus.ts                  ← Single SSE connection + dispatcher
+  event-bus.test.ts
+  send/
+    format.ts                   ← Markdown → Telegram HTML
+    format.test.ts
+    chunker.ts                  ← Split messages at 4096 chars
+    chunker.test.ts
+e2e/
+  phase-1.test.ts
+```
+
+## Modified Files
+
+```
+src/
+  bot.ts                        ← Add message handler, /new command
+  bot.test.ts                   ← Add tests for message handler
+  index.ts                      ← Initialize SDK, SessionManager, EventBus, TurnManager
+```
+
+## TDD Execution Order (bottom-up by dependency)
+
+### 1. send/format.ts — Markdown → Telegram HTML
+Pure function, zero dependencies. Tests:
+- Bold: `**text**` → `<b>text</b>`
+- Italic: `*text*` → `<i>text</i>`
+- Code: `` `text` `` → `<code>text</code>`
+- Code block: ``` ```ts\ncode``` ``` → `<pre><code class="language-ts">code</code></pre>`
+- Links: `[text](url)` → `<a href="url">text</a>`
+- HTML escaping: `& < >` → `&amp; &lt; &gt;`
+- Nested: `**bold and *italic***`
+- Edge: empty string, already-escaped HTML
+
+### 2. send/chunker.ts — Message splitting
+Pure function. Tests:
+- Short message (< 4096) returns single chunk
+- Long message splits at ~4096 boundary
+- Never splits inside HTML tags
+- Preserves unclosed tags across chunks (close + reopen)
+- Empty string returns empty array
+
+### 3. session-manager.ts — LRU session map
+Tests:
+- `getOrCreate` creates session via SDK on first access
+- `getOrCreate` returns cached on second access (SDK not called again)
+- `get` returns entry by chatKey
+- `getBySessionId` reverse lookup
+- `remove` clears both maps
+- Evicts oldest when maxEntries exceeded
+- Expired entries cleaned up by TTL
+- `set` allows manual session binding (for /list switch)
+
+### 4. turn-manager.ts — Turn lifecycle
+Tests:
+- `start` creates AbortController for session
+- `get` returns active turn
+- `end` aborts controller, clears timers, removes entry
+- `addTimer` / end clears all timers
+- `abortAll` cleans up everything
+- No leak: ended turn has no remaining references
+
+### 5. event-bus.ts — SSE event routing
+Tests (with mock SSE stream):
+- Routes event to correct chatKey via SessionManager reverse lookup
+- Ignores events for unknown sessionIds
+- Calls onEvent with (sessionId, chatKey, event)
+- Reconnects on stream end (mock reconnect)
+- stop() cleans up (aborts, no more events)
+
+### 6. bot.ts — Message handler + /new
+Tests:
+- Text message calls sdk.session.prompt with correct parts
+- /new command removes old session mapping, creates new one
+- Message to unknown chat creates session automatically
+
+### 7. Integration: index.ts wiring
+No unit test — validated by E2E.
+
+## E2E Tests (phase-1.test.ts)
+
+```ts
+test("text message gets AI response", async () => {
+  const reply = await sendAndWait(client, BOT, "Say the word hello", 30000)
+  assertContains(reply, /hello/i)
+})
+
+test("/new creates fresh session", async () => {
+  const reply = await sendAndWait(client, BOT, "/new")
+  assertContains(reply, /session/i)
+})
+
+test("error is shown in chat", async () => {
+  // Depends on OpenCode server behavior
+  // May need specific prompt to trigger error
+})
+```
+
+## Key Implementation Decisions
+
+### SDK initialization
+Following Slack bot pattern — spawn local OpenCode server:
+```ts
+import { createOpencode } from "@opencode-ai/sdk"
+const opencode = await createOpencode({ port: 0 })
+```
+This makes the bot self-contained. No external server needed.
+
+### Single SSE connection
+One `opencode.client.event.subscribe()` for ALL sessions.
+Events routed via SessionManager's reverse map (sessionId → chatKey).
+
+### Text accumulation
+On `message.part.updated` with `part.type === "text"`, we replace (not append)
+the accumulated text — the SDK sends the full text each time, not deltas.
+
+### Response delivery (Phase 1 — no streaming)
+Wait for `session.idle`, then send the complete formatted response.
+Draft streaming comes in Phase 3.
+
+### Anti-leak measures active from day 1
+- SessionManager: LRU with maxEntries + TTL
+- TurnManager: AbortController per turn, auto-cleanup on end
+- EventBus: single connection, AbortController for shutdown
+- No Grammy ctx stored in closures — extract chatId/text immediately
+
+## Acceptance Criteria
+
+- [ ] Text message → prompt → SSE → formatted reply in chat
+- [ ] `/new` creates fresh session
+- [ ] Long response (>4096 chars) is chunked correctly
+- [ ] Markdown converted to Telegram HTML
+- [ ] HTML parse errors fall back to plain text
+- [ ] Errors shown in chat
+- [ ] `bun test src/` passes (all unit tests, including Phase 0)
+- [ ] `bun test ./e2e/phase-1.test.ts` passes
+- [ ] `bun test ./e2e/phase-0.test.ts` still passes (regression)
+
+## Estimated Scope
+
+- ~6 new source files + 6 test files
+- ~800-1000 LOC (src) + ~400-500 LOC (tests)
+- Heaviest files: event-bus.ts, format.ts, session-manager.ts

package/docs/plans/phase-2.md

@@ -0,0 +1,235 @@
+# Phase 2 — Interactive Controls
+
+**Goal:** Handle permissions, questions, and abort — without these the AI agent gets stuck
+waiting for user input and the bot appears frozen.
+
+## What This Phase Delivers
+
+1. **Permission handling** — When `permission.asked` SSE event arrives, show inline buttons
+   (Allow / Always / Deny). When clicked, call `sdk.permission.reply()`.
+2. **Question handling** — When `question.asked` SSE event arrives, show inline buttons
+   with the choices. When clicked, call `sdk.question.reply()` or `sdk.question.reject()`.
+3. **`/cancel` command** — Abort generation via `sdk.session.abort({ sessionID })`.
+4. **Typing indicator** — Show "typing..." continuously during active turns.
+
+## Architecture
+
+```
+SSE Events
+  → permission.asked
+    → formatPermissionMessage() → send with inline keyboard
+    → Store requestID in PendingRequests (for double-click protection + TTL)
+
+  → question.asked
+    → formatQuestionMessage() → send with inline keyboard
+    → Store requestID + options in PendingRequests (for index→label resolution)
+
+User clicks button (callback_query)
+  → answerCallbackQuery() ALWAYS first
+  → Parse callback_data: "perm:{reply}:{requestID}" or "q:{requestID}:{index}"
+  → Look up PendingEntry (guard: expired → "This request has expired.")
+  → Call sdk.permission.reply() or sdk.question.reply()/reject()
+  → Edit original message to show the decision
+  → Delete from PendingRequests (idempotency)
+
+/cancel command
+  → Look up session from SessionManager
+  → Look up turn from TurnManager
+  → Call sdk.session.abort({ sessionID })
+  → Call turnManager.end(sessionID)
+  → Reply "Generation cancelled."
+
+Typing indicator
+  → startTypingLoop(chatId, sendAction, signal)
+  → sendChatAction("typing") every 4 seconds
+  → Tied to turn's AbortSignal (auto-stops on end/abort)
+```
+
+## SDK API (verified from sdk.gen.ts)
+
+```ts
+// Permission — only requestID needed (no sessionID!)
+sdk.permission.reply({ requestID, reply: "once" | "always" | "reject", message?: string })
+
+// Question — only requestID needed
+sdk.question.reply({ requestID, answers: [["selected_label"]] })
+sdk.question.reject({ requestID })
+
+// Abort — sessionID in path
+sdk.session.abort({ sessionID })
+```
+
+## Callback Data Design (max 64 bytes)
+
+```
+Permission buttons:
+  perm:once:{requestID}      → 10 + 30 = ~40 bytes ✓
+  perm:always:{requestID}    → 12 + 30 = ~42 bytes ✓
+  perm:deny:{requestID}      → 10 + 30 = ~40 bytes ✓
+
+Question buttons:
+  q:{requestID}:{index}      → 2 + 30 + 1 + 2 = ~35 bytes ✓
+  q:{requestID}:skip         → 2 + 30 + 1 + 4 = ~37 bytes ✓
+```
+
+IDs: `per_` + 26 chars = 30 chars, `que_` + 26 chars = 30 chars. All fit comfortably.
+
+## PendingRequests Design
+
+```ts
+type PendingEntry = {
+  type: "permission" | "question"
+  createdAt: number
+  // Only for questions: store options for index→label resolution
+  questions?: Array<{ options: Array<{ label: string }> }>
+}
+```
+
+Why PendingRequests exists:
+- **Questions**: REQUIRED — callback_data only holds index, need to resolve to label
+- **Permissions**: OPTIONAL but useful — double-click protection + TTL expiry guard
+- Bounded at 200 entries, TTL 10 minutes
+
+## New Files
+
+```
+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            ← 9 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
+```
+
+## Modified Files
+
+```
+src/
+  bot.ts                         ← Add /cancel, callback_query handler, BotDeps.pendingRequests
+  bot.test.ts                    ← Update tests for new handlers
+  index.ts                       ← Wire PendingRequests, add permission/question event cases,
+                                    add typing indicator on turn start
+```
+
+## TDD Execution Order (bottom-up by dependency)
+
+### 1. pending-requests.ts — Bounded request map (7 tests)
+Pure data structure, zero dependencies.
+
+Tests:
+1. `set()` stores, `get()` retrieves
+2. `get()` returns undefined for unknown requestID
+3. `delete()` removes entry and returns true
+4. `delete()` returns false for unknown requestID
+5. Evicts oldest when maxEntries exceeded (bounded at 200)
+6. `get()` returns undefined for expired entries (after TTL)
+7. `cleanup()` removes all expired entries
+
+### 2. handlers/permissions.ts — Permission formatting + parsing (8 tests)
+Pure functions, depends only on types.
+
+Functions:
+- `formatPermissionMessage(perm)` → `{ text, reply_markup }`
+- `parsePermissionCallback(data)` → `{ requestID, reply }` | null
+
+Tests:
+1. `formatPermissionMessage` text contains permission name
+2. `formatPermissionMessage` text contains patterns
+3. `formatPermissionMessage` returns keyboard with 3 buttons (Allow/Always/Deny)
+4. Callback data follows pattern `perm:{action}:{requestID}`
+5. `parsePermissionCallback("perm:once:per_abc123")` → `{ requestID, reply: "once" }`
+6. `parsePermissionCallback("perm:always:per_abc123")` → `{ reply: "always" }`
+7. `parsePermissionCallback("perm:deny:per_abc123")` → `{ reply: "reject" }`
+8. `parsePermissionCallback("invalid:data")` → null
+
+### 3. handlers/questions.ts — Question formatting + parsing (9 tests)
+Pure functions, depends only on types.
+
+Functions:
+- `formatQuestionMessage(questionEvent)` → `{ text, reply_markup }`
+- `parseQuestionCallback(data)` → `{ requestID, action, optionIndex? }` | null
+- `resolveQuestionAnswer(optionIndex, pending)` → `string[]`
+
+Tests:
+1. `formatQuestionMessage` returns question text in message
+2. `formatQuestionMessage` renders options as 1-per-row buttons
+3. `formatQuestionMessage` adds "Skip" button as last row
+4. Callback data: `q:{requestID}:{index}` for selection
+5. Callback data: `q:{requestID}:skip` for skip
+6. `parseQuestionCallback("q:que_abc:0")` → `{ requestID, action: "select", optionIndex: 0 }`
+7. `parseQuestionCallback("q:que_abc:skip")` → `{ requestID, action: "skip" }`
+8. `parseQuestionCallback("invalid")` → null
+9. `resolveQuestionAnswer(0, pending)` maps index to option label
+
+### 4. handlers/cancel.ts — /cancel command (5 tests)
+Depends on SessionManager + TurnManager (existing).
+
+Tests:
+1. Returns "No active session." if no session found
+2. Returns "Nothing running." if session exists but no active turn
+3. Calls `sdk.session.abort({ sessionID })` when turn is active
+4. Calls `turnManager.end(sessionID)` after abort
+5. Returns "Generation cancelled." on success
+
+### 5. handlers/typing.ts — Typing indicator loop (4 tests)
+Pure function, depends only on AbortSignal.
+
+Tests:
+1. Calls sendAction immediately on start
+2. Calls sendAction again after ~4 seconds (fake timers)
+3. Stops calling when signal is aborted
+4. Does not throw if sendAction rejects
+
+### 6. Modified: bot.ts — Callback query handler + /cancel + typing
+- Extend BotDeps with `pendingRequests: PendingRequests`
+- Add `bot.command("cancel", ...)` that calls handleCancel
+- Add `bot.on("callback_query:data", ...)` routing perm: and q: prefixes
+- Change handleMessage return type to `{ turn: ActiveTurn }`
+- Start typing loop after handleMessage in Grammy handler
+
+### 7. Modified: index.ts — Wire new event types + PendingRequests
+- Create PendingRequests instance (maxEntries: 200, ttlMs: 10min)
+- Handle `permission.asked` → formatPermissionMessage + sendMessage + store in PendingRequests
+- Handle `question.asked` → formatQuestionMessage + sendMessage + store in PendingRequests
+- Typing indicator started from bot.ts Grammy handler (not index.ts)
+
+## Edge Cases (Phase 2 MVP decisions)
+
+- **"Always" auto-resolve**: Server may auto-resolve other permissions. Stale buttons handled
+  gracefully ("requestID not found" → "This request has expired.")
+- **Double-click**: PendingRequests.delete() on first click prevents duplicate SDK calls
+- **TTL expiry**: Clicking button after 10min → "This request has expired."
+- **`answerCallbackQuery()` mandatory**: Always call first, prevents Telegram loading spinner
+- **`multiple: true` questions**: Not supported in Phase 2 MVP (single-select only)
+- **`custom: true` questions**: Not supported (no text input in inline keyboards)
+- **Multiple questions per event**: Phase 2 handles first question only (rare in practice)
+
+## Acceptance Criteria
+
+- [ ] Permission request shows inline buttons (Allow/Always/Deny)
+- [ ] Clicking Allow continues AI generation
+- [ ] Clicking Deny stops the tool call
+- [ ] Question shows options as inline buttons
+- [ ] Clicking option sends reply to SDK
+- [ ] Clicking Skip rejects the question
+- [ ] `/cancel` aborts running generation
+- [ ] Typing indicator active during turn
+- [ ] Button messages are edited after click (show decision)
+- [ ] Expired/unknown requests handled gracefully
+- [ ] `bun test` passes (all unit tests)
+- [ ] `bun test ./e2e/phase-2.test.ts` passes
+- [ ] All Phase 0-1 E2E tests still pass (regression)
+
+## Estimated Scope
+
+- 5 new source files + 5 test files + 1 E2E test file
+- ~400-500 LOC (src) + ~300-400 LOC (tests)
+- Modified: bot.ts, index.ts