feat(channel): render AskUserQuestion as Telegram inline keyboard (#127)

* feat(channel): render AskUserQuestion as Telegram inline keyboard

* feat(channel): add Skip button

Author: codeaholicguy

docs/ai/design/2026-06-29-feature-telegram-question-buttons.md

@@ -0,0 +1,166 @@
+---
+phase: design
+title: System Design & Architecture
+description: Define the technical architecture, components, and data models
+---
+
+# System Design & Architecture
+
+## Architecture Overview
+
+```mermaid
+graph TD
+  Agent[Claude Code Agent] -->|hook writes agent-request| Hook[(agent-request JSONL)]
+  Hook -->|poll| Runner[channel-runner.ts]
+  Runner -->|tryHandle| Service[AskUserQuestionService]
+  Service -->|sendInlineKeyboard| Adapter[TelegramAdapter]
+  Adapter -->|HTML + reply_markup| TG[Telegram Chat]
+  TG -->|callback_query| Adapter
+  Adapter -->|onCallback| Runner
+  Runner -->|handleCallback| Service
+  Service -->|sendKey digit| TTY[TtyWriter.sendKey]
+  TTY -->|raw keystroke| Agent
+```
+
+| Component | Responsibility |
+|---|---|
+| `channel-runner.ts` | Orchestrate. Route `AskUserQuestion` to the service; register adapter callback handler; inject `TtyWriter.sendKey` as the agent-write callback. |
+| `AskUserQuestionService` (new, in `ask-user-question.ts`) | Parse input, render the keyboard (numbered options + Skip for single-select; Skip-only for multi-select), track an in-memory session per `questionId`, resolve the digit or Esc on tap, write to the agent. |
+| `TelegramAdapter` | Adds 4 methods: `sendInlineKeyboard`, `editInlineKeyboard`, `answerCallback`, `onCallback`. |
+| `TtyWriter.sendKey` (new) | Send a single raw keystroke to the agent's terminal, bypassing bracketed paste and auto-Enter. Translates the Esc byte (`\x1b`) to the backend-native representation. |
+
+## Data Models
+
+```ts
+// ask-user-question.ts (internal)
+
+interface QuestionOption {
+    label: string;
+    description?: string;
+}
+
+interface QuestionSpec {
+    question: string;
+    header?: string;
+    options: QuestionOption[];
+    multiSelect: boolean;
+}
+
+interface ActiveSession {
+    questionId: string;     // short base36 counter, never sent to agent
+    chatId: string;
+    spec: QuestionSpec;
+    messageId: number | null;
+}
+
+// callback_data encoding (≤64 bytes):
+//   q:<questionId>:o:<optionIdx>   — option tap (single-select keyboards only)
+//   q:<questionId>:skip            — Skip tap (every keyboard)
+// questionId is a base36 counter (1-2 chars); optionIdx is decimal — both well under 64 bytes.
+```
+
+```ts
+// channel-connector/src/types.ts (new exports)
+
+export interface InlineKeyboardButton {
+    text: string;
+    callbackData: string;
+}
+export type InlineKeyboard = InlineKeyboardButton[][]; // rows of buttons
+
+export interface IncomingCallback {
+    channelType: string;
+    chatId: string;
+    userId: string;
+    messageId: number;
+    callbackData: string;
+    callbackQueryId: string;
+    timestamp: Date;
+}
+export type CallbackHandler = (callback: IncomingCallback) => Promise<void>;
+```
+
+## API Design
+
+### TelegramAdapter additions
+
+```ts
+class TelegramAdapter implements ChannelAdapter {
+    // existing: start, stop, sendMessage, onMessage, isHealthy
+
+    /** Send a message with an inline keyboard. Returns the Telegram message_id. */
+    async sendInlineKeyboard(chatId: string, html: string, keyboard: InlineKeyboard): Promise<number>;
+
+    /** Replace (or remove with `null`) the keyboard on an existing message. */
+    async editInlineKeyboard(chatId: string, messageId: number, keyboard: InlineKeyboard | null): Promise<void>;
+
+    /** Ack a callback_query, optionally with a transient toast. */
+    async answerCallback(callbackQueryId: string, text?: string): Promise<void>;
+
+    /** Register a handler for inline-keyboard taps. */
+    onCallback(handler: CallbackHandler): void;
+}
+```
+
+`ChannelAdapter` (the abstract interface) stays minimal — keyboard methods live only on the concrete `TelegramAdapter`. Promote to the interface if a second platform needs them.
+
+### TtyWriter addition
+
+```ts
+class TtyWriter {
+    static async send(location, message): Promise<void>;     // existing: bracketed paste + Enter
+    static async sendKey(location, key): Promise<void>;       // NEW: raw single keystroke
+}
+```
+
+- **tmux** path: `tmux send-keys -t <id> <key>` — direct, no paste buffer.
+- **iTerm2 / Terminal.app**: focus the target session/tab, then `tell application "System Events" to keystroke "<key>"`. Requires macOS Accessibility permission.
+
+### ask-user-question.ts service
+
+```ts
+export class AskUserQuestionService {
+    constructor(telegram: KeyboardChannel, sendToAgent: SendToAgent);
+
+    /** Returns true if it owned the request; false → caller falls back to plain text. */
+    tryHandle(toolInput: Record<string, unknown>, chatId: string): Promise<boolean>;
+
+    /** Resolve an inline-keyboard tap, write the digit to the agent, clear the keyboard. */
+    handleCallback(cb: IncomingCallback): Promise<void>;
+}
+```
+
+`KeyboardChannel` is a 3-method subset of `TelegramAdapter` (`sendInlineKeyboard`, `editInlineKeyboard`, `answerCallback`) — kept narrow so unit tests can supply a tiny stub.
+
+`SendToAgent = (key: string) => Promise<void>` — in production wired to `(key) => TtyWriter.sendKey(terminalLocation, key)`.
+
+## Component Breakdown
+
+- `packages/channel-connector/src/types.ts` — add `InlineKeyboardButton`, `InlineKeyboard`, `IncomingCallback`, `CallbackHandler`.
+- `packages/channel-connector/src/index.ts` — re-export new types.
+- `packages/channel-connector/src/adapters/TelegramAdapter.ts` — 4 new methods + `bot.on('callback_query', ...)` wiring.
+- `packages/agent-manager/src/terminal/TtyWriter.ts` — new `sendKey` static method (tmux + iTerm2 + Terminal.app paths).
+- `packages/cli/src/services/channel/ask-user-question.ts` (new) — service, parser, formatter, keyboard builder, escape helper.
+- `packages/cli/src/services/channel/channel-runner.ts`:
+  - `startOutputPolling` accepts optional `askUserQuestionService`.
+  - Polling loop offers `AskUserQuestion` payloads to the service; on `false` (multi-question / malformed) falls back to `formatPromptMessage`.
+  - `runChannelBridge` constructs the service with `TtyWriter.sendKey` and registers `telegram.onCallback`.
+
+## Design Decisions
+
+- **Single-question scope.** Multi-question payloads require sequencing keystrokes across pickers with timing assumptions; we reject them at the parser and fall back to plain `[Question]` text where the user can free-text reply.
+- **Multi-select is supported as Skip + chat reply, not toggle/Submit.** Driving multi-select toggles through the picker is just as fragile as multi-question. Instead, render the question and numbered options as a read-only formatted message with a `Skip`-only keyboard, plus a hint asking the user to reply in chat. The existing `onMessage` → `TtyWriter.send` path delivers the typed reply.
+- **Skip on every keyboard.** A `Skip` button is appended to every keyboard. On tap it sends the Esc byte (`\x1b`) via `sendKey`, which translates per backend (tmux `Escape`, AppleScript `key code 53`, wezterm literal byte).
+- **Digit keystroke via `sendKey`, not text via `send`.** The host picker reads stdin in raw mode. `TtyWriter.send` wraps payloads in bracketed paste markers `\e[200~ ... \e[201~`, which the inner TUI routes to the focused text input ("Other"), not to the picker's digit hotkey. `sendKey` sends a raw keystroke that the picker captures and selects+confirms immediately. Free-text replies (for the multi-select chat-reply path) intentionally use `send` so they reach the picker's text-input field.
+- **Process-memory state.** Bridge restart drops in-flight questions; on tap of a stale button we ack with a "Question expired" toast. Acceptable per requirements; avoids file-IO complexity.
+- **`questionId` is a short base36 counter.** Keeps `callback_data` ≤64 bytes and contains no PII.
+- **HTML escaping at the body builder.** Telegraf does not auto-escape; all user-controlled fields go through `escapeHtml` before insertion.
+- **Defense-in-depth on `chatId`.** The adapter delivers all callbacks; the runner filters by `chatIdRef.value`; the service re-checks `session.chatId`. Three independent gates.
+- **Keep `ChannelAdapter` interface minimal.** Inline keyboards are Telegram-specific; the runner imports `TelegramAdapter` directly. Revisit if a second adapter needs them.
+
+## Non-Functional Requirements
+
+- **Performance.** Callbacks are human-rate. No batching needed.
+- **Security.** HTML-escape every user-controlled field; AppleScript-escape every `sendKey` payload; reject callbacks whose `chatId` doesn't match the authorized chat.
+- **Reliability.** Callback handler errors must not crash the bridge: every external call (`editInlineKeyboard`, `answerCallback`, `sendToAgent`) is wrapped in try/catch + `debug` logging.
+- **Backwards compatibility.** Non-AskUserQuestion tool prompts unchanged. The legacy plain-text `[Question] <text>` path remains as the fallback.

docs/ai/implementation/2026-06-29-feature-telegram-question-buttons.md

@@ -0,0 +1,81 @@
+---
+phase: implementation
+title: Implementation Guide
+description: What was actually built for telegram-question-buttons
+---
+
+# Implementation Guide
+
+## Files Changed
+
+- `packages/channel-connector/src/types.ts` — added `InlineKeyboardButton`, `InlineKeyboard`, `IncomingCallback`, `CallbackHandler`.
+- `packages/channel-connector/src/index.ts` — re-exported the new types.
+- `packages/channel-connector/src/adapters/TelegramAdapter.ts` — added `sendInlineKeyboard`, `editInlineKeyboard`, `answerCallback`, `onCallback`; wired `bot.on('callback_query', ...)` in `start()` to normalize callbacks into `IncomingCallback` and dispatch to the handler.
+- `packages/cli/src/services/channel/ask-user-question.ts` (new) — `AskUserQuestionService` (in-memory session store keyed by base36 question id), `parseAskUserQuestionInput`, `formatAskUserQuestionBody`, `buildKeyboard`, `escapeHtml`. Service exposes `tryHandle(toolInput, chatId)` for the runner and `handleCallback(cb)` for adapter callbacks.
+- `packages/cli/src/services/channel/channel-runner.ts` — `startOutputPolling` accepts an optional `askUserQuestionService`. When the agent-request `toolName` is `AskUserQuestion`, the service is offered the input first; on `false` (malformed payload) the runner falls back to the existing `formatPromptMessage` + `sendMessage` path. `runChannelBridge` constructs the service with `(message) => TtyWriter.send(terminalLocation, message)` and registers `telegram.onCallback`.
+
+## Test Files Changed
+
+- `packages/cli/src/__tests__/services/channel/ask-user-question.test.ts` (new) — tests covering parser (single-select, multi-select, multi-question reject, malformed), escapeHtml, body formatter (header omit, multi-select hint, HTML escape), keyboard builder (single-select numbered + Skip; multi-select Skip-only), service flow (option tap, Skip tap, stale callback, chatId mismatch, malformed, out-of-range).
+- `packages/cli/src/__tests__/services/channel/channel-runner.test.ts` — replaced the two raw-JSON assertions with inline-keyboard assertions; added malformed-payload fallback test.
+- `packages/cli/src/__tests__/commands/channel.test.ts` — widened the `mockTelegramAdapter` shape to include the new keyboard methods.
+- `packages/channel-connector/src/__tests__/adapters/TelegramAdapter.test.ts` — added stub methods (`editMessageReplyMarkup`, `answerCbQuery`) and `_triggerCallback` helper to the mocked bot; added 6 tests for the new adapter methods.
+
+## Scope
+
+**Supported:**
+- Single-select, single-question `AskUserQuestion` payloads: numbered option buttons + Skip button.
+- Multi-select single-question payloads (`multiSelect: true`): Skip-only keyboard; user types the answer in chat.
+- `Skip` button on every keyboard — sends Esc (`\x1b`) to dismiss the picker.
+
+**Deliberately unsupported (fall back to plain `[Question]` text):**
+- `questions` array with length ≠ 1 (multi-question payloads).
+
+Rationale: driving multi-question through the TTY picker is fragile — it requires the bridge to sequence digit + Enter keystrokes across multiple turns, with timing assumptions about when the next picker opens. The fallback path still works for those cases; the user can type a free-text reply.
+
+Multi-select was originally in the unsupported list for the same reason. We now support it as a chat-reply flow (no option buttons, just Skip) because the existing free-text path already handles arbitrary user input correctly and the Skip button gives the user a clean dismiss.
+
+## Callback Data Format
+
+Two shapes, each bounded ≤64 bytes (Telegram cap):
+- `q:<id>:o:<idx>` — option tap (single-select keyboards only)
+- `q:<id>:skip` — Skip tap (every keyboard)
+
+`<id>` is a base36-encoded monotonic counter; never sent to the agent.
+
+## State Model
+
+In-memory `Map<questionId, ActiveSession>` on the service instance. Each session holds `spec`, `messageId`, and `chatId`. Session is deleted on finalization or on send failure. Bridge restart drops all sessions; subsequent taps on dropped questions get a "Question expired" toast.
+
+## Final Answer Delivery
+
+The bridge writes the resolved answer to the agent's TTY via the new `TtyWriter.sendKey` — **not** `TtyWriter.send`, and **not** the option label.
+
+| User action | Sent to agent | Toast |
+|---|---|---|
+| Tap option N (single-select) | digit `String(optionIdx + 1)` | option `label` |
+| Tap Skip (any keyboard) | Esc byte `\x1b` | "Skipped" |
+| Type free-text in Telegram chat | the typed text (via existing `onMessage` → `TtyWriter.send` path) | n/a |
+
+`TtyWriter.send` was unusable for option taps because it wraps the payload in bracketed paste markers and auto-appends Enter — the picker would see a paste of "1\n", which lands in the "Other" free-text field rather than triggering the digit hotkey. `TtyWriter.send` is still the right path for free-text replies because the picker's text-input field *is* the intended destination there.
+
+`TtyWriter.sendKey` sends a raw keystroke:
+- **tmux:** `tmux send-keys -t <id> <key>` (single call, no paste buffer, no auto-Enter). For `\x1b` it sends the named key `Escape`.
+- **WezTerm:** `wezterm cli send-text --pane-id <id> --no-paste <key>` (Esc byte passes through literally).
+- **iTerm2 / Terminal.app:** focus the target session/tab, then `System Events keystroke "<key>"` (typeable chars) or `key code 53` (Esc). Requires Accessibility permissions on macOS.
+
+The Esc translation logic is centralized in `appleScriptKeyAction()` so adding more non-typeable keys (arrows, F-keys) later is a one-line addition.
+
+## Out-of-Scope / Deferred
+
+- Persistent sessions across bridge restarts.
+- Multi-tenant chat support (bridge is single-authorized-chat by design).
+- Multi-question support (intentionally deferred; see Scope).
+- Inline-button toggle/Submit UX for multi-select (we route through chat reply instead).
+- Inline-keyboard support on the abstract `ChannelAdapter` interface (kept Telegram-specific in v1).
+- Live Telegram smoke test (owner: user).
+
+## Verification
+
+- `npm run build` → exit 0 across 5 projects.
+- `npm test` → exit 0; 1,495 tests pass.

docs/ai/planning/2026-06-29-feature-telegram-question-buttons.md

@@ -0,0 +1,35 @@
+---
+phase: planning
+title: Project Planning & Task Breakdown
+description: Break down work into actionable tasks and estimate timeline
+---
+
+# Project Planning & Task Breakdown
+
+Per `feedback_backlog_format.md`: flat checklist, no multi-status sections.
+
+## Tasks
+
+- [x] T1 — Extend `packages/channel-connector/src/types.ts` with `InlineKeyboardButton`, `InlineKeyboard`, `IncomingCallback`, `CallbackHandler`; re-export from `index.ts`.
+- [x] T2 — Add `sendInlineKeyboard`, `editInlineKeyboard`, `answerCallback`, `onCallback` to `TelegramAdapter`. Wire `bot.on('callback_query', ...)` in `start()`.
+- [x] T3 — Adapter unit tests for the four new methods using a stubbed Telegraf bot.
+- [x] T4 — Created new module `packages/cli/src/services/channel/ask-user-question.ts` with `AskUserQuestionService` (in-memory session map), `parseAskUserQuestionInput`, `buildKeyboard`, `formatAskUserQuestionBody`, `escapeHtml`.
+- [x] T5 — Registered `telegram.onCallback(handleCallback)` in `runChannelBridge`; the service is injected into `startOutputPolling`.
+- [x] T6 — Polling loop routes `AskUserQuestion` to `askQuestion.tryHandle(...)`; falls back to `formatPromptMessage` + `sendMessage` when the service is absent or the payload is malformed.
+- [x] T7 — Updated `channel-runner.test.ts:171-226` to assert keyboard shape, not raw JSON.
+- [x] T8 — Added multi-question fixture test in `ask-user-question.test.ts`.
+- [x] T9 — Full repo `npm run build` (exit 0) + `npm test` (exit 0; 1,495 tests across 5 projects).
+- [ ] T10 — Manual Telegram smoke test (live bot). Owner: user.
+- [x] T11 — Implementation doc updated.
+
+## Dependencies
+
+- T2 depends on T1.
+- T3 depends on T2.
+- T4 depends on T1.
+- T5 depends on T2, T4.
+- T6 depends on T4, T5.
+- T7, T8 depend on T6.
+- T9 depends on T7, T8.
+- T10 depends on T9.
+- T11 depends on T10.