@llblab/pi-telegram 0.2.0

package/AGENTS.md

@@ -0,0 +1,90 @@
+# Project Context
+
+## 0. Meta-Protocol Principles
+
+- `Constraint-Driven Evolution`: Add structure when the bridge gains real operator or runtime constraints
+- `Single Source of Truth`: Keep durable rules in `AGENTS.md`, open work in `BACKLOG.md`, completed delivery in `CHANGELOG.md`, and deeper technical detail in `/docs`
+- `Boundary Clarity`: Separate Telegram transport concerns, pi integration concerns, rendering behavior, and release/documentation state
+- `Progressive Enhancement + Graceful Degradation`: Prefer behavior that upgrades automatically when richer runtime context exists, but always preserves a useful fallback path when it does not
+- `Runtime Safety`: Prefer queue and rendering behavior that fails predictably over clever behavior that can desynchronize the Telegram bridge from pi session state
+
+## 1. Concept
+
+`pi-telegram` is a pi extension that turns a Telegram DM into a session-local frontend for pi, including text/file forwarding, streaming previews, queued follow-ups, model controls, and outbound attachment delivery.
+
+## 2. Identity & Naming Contract
+
+- `Telegram turn`: One unit of Telegram input processed by pi; this may represent one message or a coalesced media group
+- `Queued Telegram turn`: A Telegram turn accepted by the bridge but not yet active in pi
+- `Active Telegram turn`: The Telegram turn currently bound to the running pi agent loop
+- `Preview`: The transient streamed response shown through Telegram drafts or editable messages before the final reply lands
+- `Scoped models`: The subset of models exposed to Telegram model selection when pi settings or CLI flags limit the available list
+
+## 3. Project Topology
+
+- `/index.ts`: Main extension entrypoint and runtime composition layer for the bridge
+- `/lib/*.ts`: Flat domain modules for reusable runtime logic. Favor domain files such as queueing/runtime, replies, polling, updates, attachments, registration/hooks, Telegram API/config, turns, media, setup, rendering, menu/status/model-resolution support, and other cohesive bridge subsystems; use `shared` only when a type or constant truly spans multiple domains
+- `/tests/*.test.ts`: Domain-mirrored regression suites that follow the same flat naming as `/lib`
+- `/docs/README.md`: Documentation index for technical project docs
+- `/docs/architecture.md`: Runtime and subsystem overview for the bridge
+- `/README.md`: User-facing project entry point, install guide, and fork summary
+- `/AGENTS.md`: Durable engineering and runtime conventions
+- `/BACKLOG.md`: Canonical open work
+- `/CHANGELOG.md`: Completed delivery history
+
+## 4. Core Entities
+
+- `TelegramConfig`: Persisted bot/session pairing state
+- `PendingTelegramTurn` / `ActiveTelegramTurn`: Queue and active-turn state for Telegram-originated work
+- `TelegramPreviewState`: Streaming preview state for drafts or editable Telegram messages
+- `TelegramModelMenuState`: Inline menu state for status/model/thinking controls
+- `QueuedAttachment`: Outbound files staged for delivery through `telegram_attach`
+
+## 5. Architectural Decisions
+
+- `index.ts` stays the single extension entrypoint, while reusable runtime logic should be split into flat domain files under `/lib`; prefer domain-oriented grouping over atomizing every helper into its own file, and use `shared` sparingly for genuinely cross-domain types or constants
+- The bridge is session-local and intentionally pairs with a single allowed Telegram user per config
+- Telegram queue state is tracked locally and must stay aligned with pi agent lifecycle hooks; queued items now have explicit kinds and lanes so prompt turns and synthetic control actions can share one ordering model, while dispatch still respects active turns, pending dispatch, compaction, and pi pending-message state
+- Prompt items should remain in the queue until `agent_start` consumes the dispatched turn; removing them earlier breaks active-turn binding, preview delivery, and end-of-turn follow-up behavior
+- In-flight `/model` switching is supported only for Telegram-owned active turns and is implemented as set-model plus synthetic continuation turn plus abort; if a tool call is active, the abort is delayed until that tool finishes instead of interrupting the tool mid-flight
+- Telegram replies render through Telegram HTML, not raw Markdown; real code blocks must stay literal and escaped
+- `telegram_attach` is the canonical outbound file-delivery path for Telegram-originated requests
+
+## 6. Engineering Conventions
+
+- Treat queue handling, compaction interaction, and lifecycle-hook state transitions as regression-prone areas; validate them after changing dispatch logic
+- Treat Markdown rendering as Telegram-specific output work, not generic Markdown rendering; preserve literal code content, avoid HTML chunk splits that break tags, prefer width-efficient monospace table and list formatting for narrow clients, and flatten nested Markdown quotes into indented single-blockquote output because Telegram does not render nested blockquotes reliably
+- Keep comments and user-facing docs in English unless the surrounding file already follows another convention
+- Each project `.ts` file should start with a short multi-line responsibility header comment that explains the file boundary to future maintainers
+- Name extracted `/lib` modules and mirrored `/tests` suites by bare domain when the repository already supplies the Telegram scope; prefer `api.ts`, `queue.ts`, `updates.ts`, and `queue.test.ts` over redundant `telegram-*` filename prefixes
+- Prefer targeted edits, keeping `index.ts` as the orchestration layer and moving reusable logic into flat `/lib` domain modules when a subsystem becomes large enough to earn extraction; current extracted domains include queueing/runtime decisions, replies, polling, updates, attachments, registration and lifecycle-hook binding, Telegram API/config support, turn-building, media extraction, setup, rendering, status rendering, menu/model-resolution/UI support, and model-switch support
+
+## 7. Operational Conventions
+
+- When Telegram-visible behavior changes, sync `README.md` and the relevant `/docs` entry in the same pass
+- When durable runtime constraints or repeat bug patterns emerge, record them here instead of burying them in changelog prose
+- When fork identity changes, keep `README.md`, package metadata, and docs aligned so the published package does not point back at stale upstream coordinates
+- Work only inside this repository during development tasks; updating the installed Pi extension checkout is a separate manual operator step, not part of normal in-repo implementation work
+
+## 8. Integration Protocols
+
+- Telegram API methods currently used include polling, message editing, draft streaming, callback queries, reactions, file download, and media upload endpoints
+- pi integration depends on lifecycle hooks such as `before_agent_start`, `agent_start`, `message_start`, `message_update`, and `agent_end`
+- `ctx.ui.input()` provides placeholder text rather than an editable prefilled value; when a real default must appear already filled in, prefer `ctx.ui.editor()`
+- For `/telegram-setup`, prefer the locally saved bot token over environment variables on repeat setup runs; env vars are the bootstrap path when no local token exists
+- Status/model/thinking controls are driven through Telegram inline keyboards and callback queries
+- Inbound files may become pi image inputs; outbound files must flow through `telegram_attach`
+
+## 9. Pre-Task Preparation Protocol
+
+- Read `README.md` for current user-facing behavior and fork positioning
+- Read `BACKLOG.md` before changing runtime behavior or documentation so open work stays truthful
+- Read `/docs/architecture.md` before restructuring queue, preview, rendering, or command-handling logic
+- Inspect the relevant `index.ts` section before editing because most bridge behavior is stateful and cross-linked
+
+## 10. Task Completion Protocol
+
+- Run the smallest meaningful validation for the touched area; `npm test` is the default regression suite once rendering or queue logic changes
+- For rendering changes, ensure regressions still cover nested lists, code blocks, underscore-heavy text, and long-message chunking
+- For queue/dispatch changes, validate abort, compaction, pending-dispatch, and pi pending-message guard behavior
+- Sync `README.md`, `CHANGELOG.md`, `BACKLOG.md`, and `/docs` whenever user-visible behavior or real open-work state changes

package/BACKLOG.md

@@ -0,0 +1,5 @@
+# Project Backlog
+
+## Open Backlog
+
+- No open backlog items right now

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## Current
+
+- `[Docs]` Added short responsibility header comments to every project `.ts` file. Impact: file boundaries are easier to understand while navigating the growing `/lib` split.
+- `[Naming]` Renamed extracted domain modules and mirrored regression suites to use repo-scoped bare domain filenames such as `api.ts`, `queue.ts`, and `queue.test.ts` instead of repeating `telegram-*` in every path. Impact: the internal topology is easier to scan and stays aligned with the repository-level Telegram scope.
+- `[Controls]` Expanded Telegram session controls with a richer `/status` view, inline model selection, and thinking-level controls. Impact: more bridge configuration can be managed directly from Telegram.
+- `[Queue]` Upgraded Telegram turn queueing with previews, reaction-driven prioritization/removal, media-group handling, aborted-turn history preservation, and safer dispatch gating. Impact: follow-up handling is more transparent and less prone to lifecycle races.
+- `[Rendering]` Added Telegram-oriented Markdown rendering and hardened reply streaming/chunking behavior, including narrower monospace Markdown table output without outer side borders, monospace list markers for unordered and ordered lists, and flattened nested quote indentation inside a single Telegram blockquote. Impact: formatted replies render more reliably while preserving literal code blocks and using width more efficiently on narrow Telegram clients.
+- `[Runtime]` Hardened attachment delivery, polling/runtime behavior, Telegram session integration, preview-finalization and reply-transport routing into the replies domain, lazy Telegram API client routing into the Telegram API domain, turn-building extraction into its own domain, menu/model-resolution plus menu-state, pure menu-page derivation, pure menu render-payload builders, menu-message runtime, callback parsing, callback entry handling, callback mutation helpers, full model-callback planning and execution, and interface-polished callback effect ports into the menu domain, direct execute-from-update routing into the updates domain, model-switch restart glue extraction into the model-switch domain, and tool/command/lifecycle-hook registration extraction into a dedicated registration domain. Impact: the bridge is more robust as a daily Telegram frontend for pi.
+- `[Metadata]` Updated package repository metadata to point at the `llblab/pi-telegram` fork and renamed the npm package to `@llblab/pi-telegram` with public scoped publish settings. Impact: published package links no longer send users to stale upstream coordinates and the package can be published under the fork-owned npm scope.
+- `[Validation]` Added lightweight regression tests for Telegram Markdown rendering, queue/runtime/agent-loop/session/control/dispatch, replies, polling, updates, attachments, registration, turns, menu, and Telegram API/media/config helpers, including quote/list, table, link/code, mixed-link/code chunking, mixed-block chunk transitions, long multi-block, long-quote, long inline-formatting chunk boundaries, list-code-quote-prose chunk transitions, narrower monospace table rendering without outer side borders, monospace unordered and ordered list markers, flattened nested quote indentation inside one Telegram blockquote, inbound poll/pair/dispatch runtime cases, preview finalization, aborted-turn history carry-over, queued-status/model-after-agent-end sequencing, compaction gating, media-group debounce dispatch, direct menu callback planning and execution, pure menu-page derivation, pure menu render-payload builders, reaction-driven reprioritization/removal, immediate in-flight model-switch continuation, delayed abort-after-tool-completion, lazy Telegram API client routing, turn-building, and scoped-model resolution. Impact: key renderer and queue invariants now have repeatable automated coverage across the known high-risk bridge paths.
+- `[Model Switching]` Enabled `/model` during an active Telegram-owned run by applying the new model and continuing on the new model automatically, delaying the abort until the current tool finishes when needed. Impact: Telegram can now approximate pi's manual stop-switch-continue workflow with fewer mid-tool aborts.
+- `[Queue Core]` Introduced queued item kinds and explicit queue-lane ordering semantics so prompt turns and synthetic control actions share one ordering model, then regrouped the extracted helpers into flatter domain-oriented `/lib` modules such as queue, replies, polling, updates, attachments, turns, menu, Telegram API, and registration while keeping `index.ts` as the entrypoint. Prompt items now stay queued until `agent_start` consumes the dispatched turn, which restores correct active-turn binding for previews and final delivery. Impact: the bridge now has a clearer foundation for scheduling async extension operations alongside Telegram prompts without losing a single obvious runtime entry file.
+- `[Registration]` Moved extension tool, command, and lifecycle-hook binding into the registration domain and added registration-focused regression coverage. Impact: extension wiring is easier to reason about and test without dragging full runtime state into every registration change.
+- `[Control Queue]` Moved `/status` and `/model` command handling onto high-priority control queue items. Impact: control actions can wait safely behind the current run while still jumping ahead of normal queued prompts.
+- `[Setup]` `/telegram-setup` now shows the stored bot token first, otherwise prefills from common Telegram bot environment variables before falling back to the placeholder, using an actual prefilled editor when a real default exists. Impact: repeat setup respects local saved state while first-run and secret-managed setup stay fast.

package/README.md

@@ -0,0 +1,202 @@
+# pi-telegram
+
+![pi-telegram screenshot](screenshot.png)
+
+Telegram DM bridge for pi.
+
+This repository is a fork of the original [`badlogic/pi-telegram`](https://github.com/badlogic/pi-telegram).
+It started from upstream commit [`cb34008460b6c1ca036d92322f69d87f626be0fc`](https://github.com/badlogic/pi-telegram/commit/cb34008460b6c1ca036d92322f69d87f626be0fc) and has since diverged substantially.
+
+## Start Here
+
+- [Project Context](./AGENTS.md)
+- [Open Backlog](./BACKLOG.md)
+- [Changelog](./CHANGELOG.md)
+- [Documentation](./docs/README.md)
+
+## What Changed In This Fork
+
+Compared to upstream commit `cb34008`, this fork significantly extends and hardens the extension.
+
+- Better Telegram control UI, including an improved `/status` view with inline buttons for model and thinking selection
+- Interactive model selection improvements, including scoped model lists, thinking-level control for reasoning-capable models, and in-flight restart on a newly selected model for active Telegram-owned runs
+- Queueing and interaction upgrades, including queue previews, reaction-based prioritization/removal, media-group handling, high-priority control actions, and safer dispatch behavior
+- Markdown and reply rendering improvements, with richer formatting support, narrow-client-friendly table/list rendering, quote compatibility fixes, and multiple fixes for incorrect Telegram rendering and chunking edge cases
+- Streaming, attachment, and delivery workflow hardening, including more robust preview updates and file handling
+- General runtime polish, bug fixes, and refactors across pairing, command handling, and Telegram session behavior
+- Cleaner internal domain layout, with flat `/lib/*.ts` modules and mirrored `/tests/*.test.ts` suites that use repo-scoped domain names instead of redundant `telegram-*` filename prefixes
+
+In short: this fork is no longer just a repackaged copy of upstream; it is a feature-expanded and bug-fixed Telegram frontend for pi.
+
+## Install
+
+From npm once published:
+
+```bash
+pi install @llblab/pi-telegram
+```
+
+From git:
+
+```bash
+pi install git:github.com/llblab/pi-telegram
+```
+
+Or for a single run:
+
+```bash
+pi -e @llblab/pi-telegram
+```
+
+## Configure
+
+### Telegram
+
+1. Open [@BotFather](https://t.me/BotFather)
+2. Run `/newbot`
+3. Pick a name and username
+4. Copy the bot token
+
+### pi
+
+Start pi, then run:
+
+```bash
+/telegram-setup
+```
+
+Paste the bot token when prompted.
+If a bot token is already saved in `~/.pi/agent/telegram.json`, `/telegram-setup` shows that stored value by default. Otherwise it pre-fills from the first configured environment variable in `TELEGRAM_BOT_TOKEN`, `TELEGRAM_BOT_KEY`, `TELEGRAM_TOKEN`, or `TELEGRAM_KEY`.
+
+The extension stores config in:
+
+```text
+~/.pi/agent/telegram.json
+```
+
+## Connect a pi session
+
+The Telegram bridge is session-local. Connect it only in the pi session that should own the bot:
+
+```bash
+/telegram-connect
+```
+
+To stop polling in the current session:
+
+```bash
+/telegram-disconnect
+```
+
+Check status:
+
+```bash
+/telegram-status
+```
+
+## Pair your Telegram account
+
+After token setup and `/telegram-connect`:
+
+1. Open the DM with your bot in Telegram
+2. Send `/start`
+
+The first DM user becomes the allowed Telegram user for the bridge. The extension only accepts messages from that user.
+
+## Usage
+
+Chat with your bot in Telegram DMs.
+
+Additional fork-specific controls:
+
+- `/status` now has a richer view with inline buttons for model and thinking controls, and joins the high-priority control queue when pi is busy
+- `/model` opens the interactive model selector, joins the high-priority control queue when pi is busy, and can restart the active Telegram-owned run on the newly selected model, waiting for the current tool call to finish when needed
+- `/compact` starts session compaction when pi and the Telegram queue are idle
+- Queue reactions: `👍` prioritizes a waiting turn, `👎` removes it
+
+### Send text
+
+Send any message in the bot DM. It is forwarded into pi with a `[telegram]` prefix.
+
+### Send images and files
+
+Send images, albums, or files in the DM.
+
+The extension:
+
+- downloads them to `~/.pi/agent/tmp/telegram`
+- includes local file paths in the prompt
+- forwards inbound images as image inputs to pi
+
+### Ask for files back
+
+If you ask pi for a file or generated artifact, pi should call the `telegram_attach` tool. The extension then sends those files with the next Telegram reply.
+
+Examples:
+
+- `summarize this image`
+- `read this README and summarize it`
+- `write me a markdown file with the plan and send it back`
+- `generate a shell script and attach it`
+
+### Stop a run
+
+In Telegram, send:
+
+```text
+stop
+```
+
+or:
+
+```text
+/stop
+```
+
+That aborts the active pi turn.
+
+### Queue follow-ups
+
+If you send more Telegram messages while pi is busy, they are queued and processed in order.
+
+The pi status bar shows queued Telegram turns as compact previews, for example:
+
+```text
++3: [summarize this image…, write a shell script…, 📎 2 attachments]
+```
+
+Each preview is limited to at most 5 words or 40 characters.
+
+### Reprioritize or discard queued messages
+
+While a message is still waiting in the queue:
+
+- React with 👍 to move it into the priority block
+- React with 👎 to remove it from the queue
+
+Priority is stable:
+
+- The first liked queued message stays ahead of later liked messages
+- Removing 👍 sends the message back to its normal queue position
+- Adding 👍 again gives it a fresh priority position
+
+For media groups, a reaction on any message in the group applies to the whole queued turn.
+
+Message reactions depend on Telegram delivering `message_reaction` updates for your bot and chat type.
+
+## Streaming
+
+The extension streams assistant text previews back to Telegram while pi is generating.
+
+It tries Telegram draft streaming first with `sendMessageDraft`. If that is not supported for your bot, it falls back to `sendMessage` plus `editMessageText`.
+
+## Notes
+
+- Only one pi session should be connected to the bot at a time
+- Replies are sent as normal Telegram messages, not quote-replies
+- Long replies are split below Telegram's 4096 character limit
+- Outbound files are sent via `telegram_attach`
+
+## License
+
+MIT

package/docs/README.md

@@ -0,0 +1,9 @@
+# Documentation Index
+
+Living index of project documentation in `/docs`.
+
+## Documents
+
+| Document | Description |
+| --- | --- |
+| [architecture.md](./architecture.md) | Overview of the Telegram bridge runtime, queueing model, rendering pipeline, and interactive controls |

package/docs/architecture.md

@@ -0,0 +1,148 @@
+# Telegram Bridge Architecture
+
+## Overview
+
+`pi-telegram` is a session-local pi extension that binds one Telegram DM to one running pi session. The bridge owns four main responsibilities:
+
+- Poll Telegram updates and enforce single-user pairing
+- Translate Telegram messages and media into pi inputs
+- Stream and deliver pi responses back to Telegram
+- Manage Telegram-specific controls such as queue reactions, `/status`, `/model`, and `/compact`
+
+## Runtime Structure
+
+`index.ts` remains the extension entrypoint and composition layer. Reusable runtime logic is split into flat domain files under `/lib` rather than into a deep local module tree.
+
+Domain grouping rule: prefer cohesive domain files over atomizing every helper into its own file. A `shared` domain is allowed only for types or constants that genuinely span multiple bridge domains.
+
+Naming rule: because the repository already scopes this codebase to Telegram, extracted module and test filenames use bare domain names such as `api.ts`, `queue.ts`, `updates.ts`, and `queue.test.ts` rather than repeating `telegram-*` in every filename.
+
+Current runtime areas include:
+
+- Telegram API types and local bridge state in `index.ts`
+- Queueing and queue-runtime helpers in `/lib/queue.ts`
+- Reply, preview, preview-finalization, reply-transport, and rendered-message delivery helpers in `/lib/replies.ts`
+- Polling request, stop-condition, and long-poll loop helpers in `/lib/polling.ts`
+- Telegram API/config helpers and lazy bot-token client wrappers in `/lib/api.ts`
+- Telegram turn-building helpers in `/lib/turns.ts`
+- Telegram media/text extraction helpers in `/lib/media.ts`
+- Telegram updates extraction, authorization, flow, execution-planning, direct execute-from-update routing, and runtime helpers in `/lib/updates.ts`
+- Telegram attachment queueing and delivery helpers in `/lib/attachments.ts`
+- Telegram tool, command, and lifecycle-hook registration helpers in `/lib/registration.ts`
+- Setup/token prompt helpers in `/lib/setup.ts`
+- Markdown and Telegram message rendering helpers in `/lib/rendering.ts`
+- Status rendering helpers in `/lib/status.ts`
+- Menu/model-resolution, menu-state construction, pure menu-page derivation, pure menu render-payload builders, menu-message runtime, callback parsing, callback entry handling, callback mutation helpers, full model-callback planning and execution, interface-polished callback effect ports, status-thinking callback handling, and UI helpers in `/lib/menu.ts`
+- Model-switch guard, continuation, and restart helpers in `/lib/model-switch.ts`
+- Telegram API-bound reply transport wiring and broader event-side orchestration in `index.ts`
+- Additional domains can be extracted into `/lib/*.ts` as the bridge grows, while keeping `index.ts` as the single entrypoint
+- Mirrored domain regression coverage lives in `/tests/*.test.ts` using the same bare domain naming scheme
+
+## Configuration UX
+
+`/telegram-setup` uses a progressive-enhancement flow for the bot token prompt:
+
+1. Show the locally saved token from `~/.pi/agent/telegram.json` when one already exists
+2. Otherwise use the first configured environment variable from the supported Telegram token list
+3. Fall back to the example placeholder when no real value exists
+
+Because `ctx.ui.input()` only exposes placeholder text, the bridge uses `ctx.ui.editor()` whenever a real default value must appear already filled in.
+
+## Message And Queue Flow
+
+### Inbound Path
+
+1. Telegram updates are polled through `getUpdates`
+2. The bridge filters to the paired private user
+3. Media groups are coalesced into a single Telegram turn when needed
+4. Files are downloaded into `~/.pi/agent/tmp/telegram`
+5. A `PendingTelegramTurn` is created and queued locally
+6. The queue dispatcher sends the turn into pi only when dispatch is safe
+
+### Queue Safety Model
+
+The bridge keeps its own Telegram queue and does not rely only on pi's internal pending-message state.
+
+Queued items now use two explicit dimensions:
+
+- `kind`: prompt vs control
+- `queueLane`: control vs priority vs default
+
+This lets synthetic control actions and Telegram prompts share one stable ordering model while still rendering distinctly in status output.
+
+A dispatched prompt remains in the queue until `agent_start` consumes it. That keeps the active Telegram turn bound correctly for previews, attachments, abort handling, and final reply delivery.
+
+Dispatch is gated by:
+
+- No active Telegram turn
+- No pending Telegram dispatch already sent to pi
+- No compaction in progress
+- `ctx.isIdle()` being true
+- `ctx.hasPendingMessages()` being false
+
+This prevents queue races around rapid follow-ups, `/compact`, and mixed local plus Telegram activity.
+
+### Abort Behavior
+
+When `/stop` aborts an active Telegram turn, queued follow-up Telegram messages can be preserved as prior-user history for the next turn. This keeps later Telegram input from being silently dropped after an interrupted run.
+
+## Rendering Model
+
+Telegram replies are rendered as Telegram HTML rather than raw Markdown.
+
+Key rules:
+
+- Rich text should render cleanly in Telegram chats
+- Real code blocks must remain literal and escaped
+- Markdown tables should keep their internal separators but drop the outer left and right borders when rendered as monospace blocks so narrow Telegram clients keep more usable width
+- Unordered Markdown lists should render with a monospace `-` marker and ordered Markdown lists should render with monospace numeric markers so list indentation stays more predictable on narrow Telegram clients
+- Nested Markdown quotes should flatten into one Telegram blockquote with added non-breaking-space indentation because Telegram does not render nested blockquotes reliably
+- Long replies must be split below Telegram's 4096-character limit
+- Chunking should avoid breaking HTML structure where possible
+- Preview rendering is intentionally simpler than final rich rendering
+
+The renderer is a Telegram-specific formatter, not a general Markdown engine, so rendering changes should be treated as regression-prone.
+
+## Streaming And Delivery
+
+During generation, the bridge streams previews back to Telegram.
+
+Preferred order:
+
+1. Try `sendMessageDraft`
+2. Fall back to `sendMessage` plus `editMessageText`
+3. Replace the preview with the final rendered reply when generation ends
+
+Outbound files are sent only after the active Telegram turn completes and must be staged through the `telegram_attach` tool.
+
+## Interactive Controls
+
+The bridge exposes Telegram-side session controls in addition to regular chat forwarding.
+
+Current operator controls include:
+
+- `/status` for model, usage, cost, and context visibility, queued as a high-priority control item when needed
+- Inline status buttons for model and thinking adjustments
+- `/model` for interactive model selection, queued as a high-priority control item when needed and supporting in-flight restart of the active Telegram-owned run on a newly selected model
+- `/compact` for Telegram-triggered pi session compaction when the bridge is idle
+- Queue reactions using `👍` and `👎`
+
+## In-Flight Model Switching
+
+When `/model` is used during an active Telegram-owned run, the bridge can emulate the interactive pi workflow of stopping, switching model, and continuing.
+
+The current implementation does this by:
+
+1. Applying the newly selected model immediately
+2. Queuing or staging a synthetic Telegram continuation turn
+3. Aborting the active Telegram turn immediately, or delaying the abort until the current tool finishes when a tool call is in flight
+4. Dispatching the continuation turn after the abort completes
+
+This behavior is intentionally limited to runs currently owned by the Telegram bridge. If pi is busy with non-Telegram work, the bridge still refuses the switch instead of hijacking unrelated session activity.
+
+## Related
+
+- [README.md](../README.md)
+- [Project Context](../AGENTS.md)
+- [Project Backlog](../BACKLOG.md)
+- [Changelog](../CHANGELOG.md)