@llblab/pi-telegram 0.2.8 → 0.2.10

package/AGENTS.md

@@ -57,7 +57,8 @@
 - 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
+- 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, preview streaming, replies, polling, updates, attachments, registration and lifecycle-hook binding, Telegram API/config support, Telegram Bot API transport types, command parsing/action routing, turn-building, media extraction/media-group coalescing, setup, rendering, status rendering, menu/model-resolution/UI support, and model-switch support
+- Keep preview appearance logic in the rendering domain and preview transport/lifecycle logic in the preview domain so richer streaming strategies can evolve without entangling Telegram delivery state with Markdown formatting rules
 
 ## 7. Operational Conventions
 

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## Current
 
+- `[Turns]` Preserved existing attachment-path blocks and aborted-turn history context when a still-queued Telegram message is edited. Impact: caption edits no longer make queued prompts lose their downloaded file references or prior-message context.
+- `[Polling]` Persisted Telegram long-poll offsets only after each update is handled successfully. Impact: a handler failure no longer marks an unprocessed Telegram update as consumed, reducing the chance of silently dropping inbound messages.
+- `[Telegram API]` Added HTTP-status-aware Bot API response parsing, malformed-success handling, retry/backoff for 429 and 5xx Bot API responses, streaming Telegram downloads with size-limit checks, file-backed multipart upload blobs, partial-download cleanup on limit failures, startup cleanup for stale Telegram temp files, and UUID-based sanitized temp filenames. Impact: Telegram transport failures now report clearer status/description details, transient Telegram throttling/server failures get retried automatically, oversized inbound files are rejected before or during download, outbound multipart sends avoid preloading files into memory, partial and stale temp files are removed, and downloaded files are less prone to timestamp collisions or unsafe local names.
+- `[Rendering]` Escaped generated HTML attributes separately, sanitized code-fence language classes, and chunked raw HTML-mode output below Telegram length limits with balanced tag reopening across raw HTML chunks. Impact: generated Telegram HTML is harder to malformed through link or fence metadata and long raw-HTML replies no longer exceed Telegram's message size limit or break active tags across chunk boundaries.
+- `[Preview]` Serialized overlapping preview flushes through a single in-flight flush chain. Impact: rapid streaming updates no longer allow concurrent Telegram edit calls to overwrite newer preview text with stale snapshots.
+- `[Polling]` Added a bounded poisoned-update policy for repeatedly failing Telegram updates. Impact: one malformed or consistently failing update can no longer stall the long-poll loop forever; after the retry threshold, the bridge records and advances past it.
+- `[Menu]` Added short-lived model-menu input caching plus TTL/LRU cleanup for stored inline menu state. Impact: repeated `/status` and `/model` interactions do less settings/model-registry work, while old Telegram inline keyboards expire predictably instead of accumulating for the whole session.
+- `[Updates]` Routed Telegram `edited_message` updates separately from new messages and applied edits to matching queued turns. Impact: editing a still-queued Telegram message updates the pending prompt instead of enqueueing a duplicate turn.
+- `[Refactor]` Moved shared Telegram Bot API transport shapes out of `index.ts` into `lib/types.ts`. Impact: the entrypoint is smaller and future runtime extraction can reuse one type boundary instead of keeping local duplicate interfaces.
+- `[Refactor]` Moved Telegram media-group debounce and pending-group removal into the existing media domain with mirrored tests. Impact: album coalescing and reaction/delete cleanup are easier to validate without reading the full extension entrypoint, while avoiding an unnecessary extra domain file.
+- `[Refactor]` Extracted Telegram slash-command parsing and command-action routing into `lib/commands.ts` with mirrored tests, and moved queued-turn text replacement for edited messages into the turn domain. Impact: command normalization/execution planning and queued edit mutations are reusable, while the entrypoint keeps less local runtime state logic.
+- `[Rendering]` Hardened link rendering so absolute links stay clickable, markdown-heavy link labels reduce to plain clickable labels, tooltip titles are ignored safely, balanced-parenthesis URLs stay intact, and unsupported link forms degrade without broken anchors. Impact: Telegram replies now keep more links usable while avoiding malformed output for relative, reference-style, or footnote-like link syntax.
+- `[Preview]` Evolved rich streaming from first-chunk snapshots to stable-block previews with a conservative plain tail fallback, while preserving original blank-line spacing between rendered blocks and keeping headings visually separated from following blocks. Impact: closed top-level Markdown blocks now stream as rich Telegram HTML before finalization, incomplete fences, quotes, lists, and other trailing work remain readable without producing broken rich formatting, preview/final block spacing no longer collapses extra empty lines, and headings no longer visually merge into following code blocks when source Markdown omits a blank line.
+- `[Refactor]` Split preview concerns so runtime transport and finalization live in the preview domain while preview snapshot derivation lives in the rendering domain. Impact: rich streaming can evolve independently from final reply delivery while keeping preview appearance decisions closer to the Telegram renderer.
+- `[Streaming]` Switched Telegram previews from plain draft-first text to rich first-chunk message editing, so formatting appears during generation instead of only after finalization. Impact: users now see richer streamed output earlier, while final replies still replace the preview with fully rendered Telegram HTML.
 - `[Rendering]` Preserved leading indentation on the first Markdown line, kept numeric markers for ordered task lists in both preview and final Telegram rendering, and stopped reinterpreting standalone `[x]` or `[ ]` prose as inline checkboxes. Impact: nested content no longer flattens when a message starts with indentation, numbered checklists keep their ordered semantics, and literal checklist-like prose stays literal.
 - `[Queue UI]` Marked liked high-priority queued Telegram turns with `⬆` in the pi status-bar queue preview. Impact: operators can now distinguish reaction-promoted turns from normal queued prompts at a glance.
 - `[Docs]` Added short responsibility header comments to every project `.ts` file. Impact: file boundaries are easier to understand while navigating the growing `/lib` split.

package/README.md

@@ -2,8 +2,6 @@
 
 ![pi-telegram screenshot](screenshot.png)
 
-Telegram DM bridge for pi.
-
 This repository is an actively maintained fork of [`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
@@ -19,9 +17,9 @@ This repository is an actively maintained fork of [`badlogic/pi-telegram`](https
 - **Interactive UI**: Manage your session directly from Telegram. Inline buttons allow you to switch models and adjust reasoning (thinking) levels on the fly.
 - **In-flight Model Switching**: Change the active model mid-generation. The agent gracefully pauses, applies the new model, and restarts its response without losing context.
 - **Smart Message Queue**: Messages sent while the agent is busy are queued and previewed in the pi status bar, and queued turns can be reprioritized or removed with Telegram reactions.
-- **Mobile-Optimized Rendering**: Tables and lists are formatted for narrow screens. Markdown is correctly parsed and split to fit Telegram's limits without breaking HTML structures or code blocks.
+- **Mobile-Optimized Rendering**: Tables and lists are formatted for narrow screens. Markdown is correctly parsed and split to fit Telegram's limits without breaking HTML structures or code blocks, block spacing stays faithful to the original Markdown with readable heading separation, supported absolute links stay clickable, and unsupported link forms degrade safely.
 - **File Handling & Attachments**: Send images and files to the agent, or ask it to generate and return artifacts. Outbound files are delivered automatically via the `telegram_attach` tool.
-- **Streaming Responses**: Smooth, real-time typing effect using Telegram Drafts (or message edits as a fallback).
+- **Streaming Responses**: Closed Markdown blocks stream back as rich Telegram HTML while pi is generating, and the still-growing tail stays readable until the final fully rendered reply lands.
 
 ## Install
 
@@ -80,7 +78,7 @@ Once paired, simply chat with your bot in Telegram. All text, images, and files
 - **`/status`**: View session stats, cost, and use inline buttons to change models.
 - **`/model`**: Open the interactive model selector.
 - **`/compact`**: Start session compaction (only works when the session is idle).
-- **`/stop`** (or just **`stop`**): Abort the active run.
+- **`/stop`**: Abort the active run.
 - **`/telegram-disconnect`** (in pi): Stop polling in the current session.
 - **`/telegram-status`** (in pi): Check bridge status.
 
@@ -90,30 +88,35 @@ Once paired, simply chat with your bot in Telegram. All text, images, and files
 - `👍` moves a waiting turn into the priority block. Removing `👍` sends it back to its normal queue position, and adding `👍` again gives it a fresh priority position.
 - `👎` removes a waiting turn from the queue. Telegram Bot API does not expose ordinary DM message-deletion events through the polling path used here, so queue removal is bound to the dislike reaction.
 - For media groups, a reaction on any message in the group applies to the whole queued turn.
-- Inbound images, albums, and files are downloaded to `~/.pi/agent/tmp/telegram`, local file paths are included in the prompt, and inbound images are forwarded to pi as image inputs.
+- If you edit a Telegram message while it is still waiting in the queue, the queued turn is updated instead of creating a duplicate prompt. Edits after a turn has already started may not affect the active run.
+- Inbound images, albums, and files are saved to `~/.pi/agent/tmp/telegram`, local file paths are included in the prompt, and inbound images are forwarded to pi as image inputs.
 - Queue reactions depend on Telegram delivering `message_reaction` updates for your bot and chat type.
 
 ### Requesting Files
 
 If you ask pi for a file or generated artifact (e.g., _"generate a shell script and attach it"_), pi will call the `telegram_attach` tool, and the extension will send the file alongside its next Telegram reply.
 
-Examples:
+## Streaming
 
-- `summarize this image`
-- `generate a shell script and attach it`
+The extension streams assistant previews back to Telegram while pi is generating.
 
-## Streaming
+Rich previews are sent through editable messages because Telegram drafts are text-only. Closed top-level Markdown blocks can appear with formatting before the answer finishes, while the still-growing tail remains conservative and readable until the preview is replaced with the fully rendered Telegram HTML reply.
 
-The extension streams assistant text previews back to Telegram while pi is generating.
+## Status bar
 
-It tries Telegram draft streaming first with `sendMessageDraft`. If that is not supported for your bot, it falls back to `sendMessage` plus `editMessageText`.
+The pi status bar shows queued Telegram turns as compact previews, for example:
+
+```text
++3: [⬆ write a shell script…, summarize this image…, 📎 2 attachments]
+```
 
 ## 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
+- Long replies are split below Telegram's 4096 character limit without intentionally breaking Telegram HTML formatting
 - Outbound files are sent via `telegram_attach`
+- Temporary inbound Telegram files are cleaned up on later session starts
 
 ## License
 

package/docs/architecture.md

@@ -19,18 +19,21 @@ Naming rule: because the repository already scopes this codebase to Telegram, ex
 
 Current runtime areas include:
 
-- Telegram API types and local bridge state in `index.ts`
+- Telegram Bot API transport shape types in `/lib/types.ts`, with local bridge state still composed 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`
+- Preview transport-selection, preview-finalization, and preview-runtime helpers in `/lib/preview.ts`
+- Reply-transport and rendered-message delivery helpers in `/lib/replies.ts`
+- Preview appearance and snapshot derivation stay in `/lib/rendering.ts`, while `/lib/preview.ts` owns transport and lifecycle decisions, so richer preview strategies can evolve without entangling Markdown formatting with Telegram delivery state
 - 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 media/text extraction, file-info normalization, and media-group debounce helpers in `/lib/media.ts`
+- Telegram slash-command parsing and command-action routing helpers in `/lib/commands.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`
+- Markdown, preview-snapshot, 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`
@@ -53,11 +56,13 @@ Because `ctx.ui.input()` only exposes placeholder text, the bridge uses `ctx.ui.
 ### 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
+2. Each update offset is persisted only after the update handler succeeds; repeated handler failures are bounded so one poisoned update cannot stall polling forever
+3. The bridge filters to the paired private user
+4. Media groups are coalesced into a single Telegram turn when needed
+5. Files are streamed into `~/.pi/agent/tmp/telegram` with size-limit checks, partial-download cleanup on failures, and stale temp cleanup on session start
+6. A `PendingTelegramTurn` is created and queued locally
+7. Telegram `edited_message` updates are routed separately and update a matching queued turn when the original message has not been dispatched yet
+8. The queue dispatcher sends the turn into pi only when dispatch is safe
 
 ### Queue Safety Model
 
@@ -94,13 +99,15 @@ Key rules:
 
 - Rich text should render cleanly in Telegram chats
 - Real code blocks must remain literal and escaped
+- Supported absolute HTTP(S) and mailto links should stay clickable, with generated HTML attributes escaped separately from text content, while unsupported link forms such as unresolved references, footnotes, or relative links without a known base should degrade safely instead of producing broken Telegram anchors
 - 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
 - Real Markdown task-list items should render with checkbox markers, while standalone `[x]` and `[ ]` prose should stay literal instead of being reinterpreted as checklists
 - 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
+- Original blank-line spacing between Markdown blocks should stay intact in both preview and final rendering instead of being collapsed to one generic block separator, while headings should still keep readable separation from following blocks such as code fences even when source Markdown omits a blank line
+- Long replies, including raw HTML-mode replies used by interactive/status flows, 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
+- Preview rendering uses stable top-level Markdown blocks for rich Telegram HTML and appends the still-growing tail conservatively as readable plain text so the preview stays valid even when the answer is incomplete
 
 The renderer is a Telegram-specific formatter, not a general Markdown engine, so rendering changes should be treated as regression-prone.
 
@@ -110,11 +117,14 @@ 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
+1. Re-render the current Markdown buffer into a preview snapshot that renders closed top-level blocks as rich Telegram HTML and keeps the unstable tail conservative and readable
+2. Send or update that preview through `sendMessage` plus `editMessageText`, because `sendMessageDraft` is text-only for rich previews
+3. Serialize overlapping preview flushes so older Telegram edit calls cannot race newer streamed snapshots
+4. 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.
+Draft streaming can remain as a plain-text fallback path, but rich Telegram previews are driven through editable messages and stable-block snapshot selection.
+
+Outbound files are sent only after the active Telegram turn completes, must be staged through the `telegram_attach` tool, and use file-backed multipart blobs so large sends do not require preloading whole files into memory.
 
 ## Interactive Controls
 
@@ -123,7 +133,7 @@ The bridge exposes Telegram-side session controls in addition to regular chat fo
 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, applying idle selections immediately while still respecting busy-run restart rules
+- Inline status buttons for model and thinking adjustments, applying idle selections immediately while still respecting busy-run restart rules; model-menu inputs are cached briefly and stored inline-menu states are pruned by TTL/LRU so old keyboards expire predictably
 - `/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 `👎`, with `👎` acting as the canonical queue-removal path because ordinary Telegram DM message deletions are not exposed through the Bot API polling path this bridge uses