@llblab/pi-telegram 0.2.8 → 0.2.9

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, turn-building, media extraction, 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,10 @@
 
 ## Current
 
+- `[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,7 +2,7 @@
 
 ![pi-telegram screenshot](screenshot.png)
 
-Telegram DM bridge for pi.
+Better 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.
 
@@ -19,9 +19,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 +80,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.
 
@@ -104,9 +104,9 @@ Examples:
 
 ## Streaming
 
-The extension streams assistant text previews back to Telegram while pi is generating.
+The extension streams assistant 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`.
+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.
 
 ## Notes
 

package/docs/architecture.md

@@ -21,7 +21,9 @@ 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`
+- 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`
@@ -30,7 +32,7 @@ Current runtime areas include:
 - 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`
@@ -94,13 +96,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, 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
+- 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 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,10 +114,12 @@ During generation, the bridge streams previews back to Telegram.
 
 Preferred order:
 
-1. Try `sendMessageDraft`
-2. Fall back to `sendMessage` plus `editMessageText`
+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. Replace the preview with the final rendered reply when generation ends
 
+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 and must be staged through the `telegram_attach` tool.
 
 ## Interactive Controls

package/index.ts

@@ -87,11 +87,14 @@ import {
   type TelegramRenderMode,
 } from "./lib/rendering.ts";
 import {
-  buildTelegramReplyTransport,
   clearTelegramPreview,
   finalizeTelegramMarkdownPreview,
   finalizeTelegramPreview,
   flushTelegramPreview,
+  type TelegramPreviewRuntimeState,
+} from "./lib/preview.ts";
+import {
+  buildTelegramReplyTransport,
   sendTelegramMarkdownReply,
   sendTelegramPlainReply,
 } from "./lib/replies.ts";
@@ -267,14 +270,7 @@ interface DownloadedTelegramFile {
 
 type ActiveTelegramTurn = PendingTelegramTurn;
 
-interface TelegramPreviewState {
-  mode: "draft" | "message";
-  draftId?: number;
-  messageId?: number;
-  pendingText: string;
-  lastSentText: string;
-  flushTimer?: ReturnType<typeof setTimeout>;
-}
+type TelegramPreviewState = TelegramPreviewRuntimeState;
 
 interface TelegramMediaGroupState {
   messages: TelegramMessage[];
@@ -691,21 +687,28 @@ export default function (pi: ExtensionAPI) {
           text,
         });
       },
-      sendMessage: async (chatId: number, text: string) => {
+      sendMessage: async (
+        chatId: number,
+        text: string,
+        options?: { parseMode?: "HTML" },
+      ) => {
         return callTelegramApi<TelegramSentMessage>("sendMessage", {
           chat_id: chatId,
           text,
+          parse_mode: options?.parseMode,
         });
       },
       editMessageText: async (
         chatId: number,
         messageId: number,
         text: string,
+        options?: { parseMode?: "HTML" },
       ) => {
         await editTelegramMessageText({
           chat_id: chatId,
           message_id: messageId,
           text,
+          parse_mode: options?.parseMode,
         });
       },
       renderTelegramMessage,

package/lib/preview.ts

@@ -0,0 +1,212 @@
+/**
+ * Telegram preview streaming helpers
+ * Owns preview transport selection, runtime updates, and preview finalization
+ */
+
+import {
+  buildTelegramPreviewSnapshot,
+  type TelegramPreviewRenderStrategy,
+  type TelegramPreviewSnapshot,
+  type TelegramRenderedChunk,
+  type TelegramRenderMode,
+} from "./rendering.ts";
+
+export interface TelegramPreviewStateLike {
+  mode: "draft" | "message";
+  draftId?: number;
+  messageId?: number;
+  pendingText: string;
+  lastSentText: string;
+  lastSentParseMode?: "HTML";
+  lastSentStrategy?: TelegramPreviewRenderStrategy;
+}
+
+export interface TelegramPreviewRuntimeState extends TelegramPreviewStateLike {
+  flushTimer?: ReturnType<typeof setTimeout>;
+}
+
+export interface TelegramSentPreviewMessageLike {
+  message_id: number;
+}
+
+export interface TelegramPreviewRuntimeDeps {
+  getState: () => TelegramPreviewRuntimeState | undefined;
+  setState: (state: TelegramPreviewRuntimeState | undefined) => void;
+  clearScheduledFlush: (state: TelegramPreviewRuntimeState) => void;
+  maxMessageLength: number;
+  renderPreviewText: (markdown: string) => string;
+  getDraftSupport: () => "unknown" | "supported" | "unsupported";
+  setDraftSupport: (support: "unknown" | "supported" | "unsupported") => void;
+  allocateDraftId: () => number;
+  sendDraft: (chatId: number, draftId: number, text: string) => Promise<void>;
+  sendMessage: (
+    chatId: number,
+    text: string,
+    options?: { parseMode?: "HTML" },
+  ) => Promise<TelegramSentPreviewMessageLike>;
+  editMessageText: (
+    chatId: number,
+    messageId: number,
+    text: string,
+    options?: { parseMode?: "HTML" },
+  ) => Promise<void>;
+  renderTelegramMessage: (
+    text: string,
+    options?: { mode?: TelegramRenderMode },
+  ) => TelegramRenderedChunk[];
+  sendRenderedChunks: (
+    chatId: number,
+    chunks: TelegramRenderedChunk[],
+  ) => Promise<number | undefined>;
+  editRenderedMessage: (
+    chatId: number,
+    messageId: number,
+    chunks: TelegramRenderedChunk[],
+  ) => Promise<number | undefined>;
+}
+
+export function buildTelegramPreviewFinalText(
+  state: TelegramPreviewStateLike,
+): string | undefined {
+  const finalText = state.pendingText.trim();
+  if (finalText) return finalText;
+  if (
+    state.lastSentStrategy === "rich-stable-blocks" ||
+    state.lastSentParseMode === "HTML"
+  ) {
+    return undefined;
+  }
+  return state.lastSentText.trim() || undefined;
+}
+
+export function shouldUseTelegramDraftPreview(options: {
+  draftSupport: "unknown" | "supported" | "unsupported";
+  snapshot?: TelegramPreviewSnapshot;
+}): boolean {
+  return (
+    options.draftSupport !== "unsupported" &&
+    (options.snapshot === undefined || options.snapshot.strategy === "plain")
+  );
+}
+
+export async function clearTelegramPreview(
+  chatId: number,
+  deps: TelegramPreviewRuntimeDeps,
+): Promise<void> {
+  const state = deps.getState();
+  if (!state) return;
+  deps.clearScheduledFlush(state);
+  deps.setState(undefined);
+  if (state.mode !== "draft" || state.draftId === undefined) return;
+  try {
+    await deps.sendDraft(chatId, state.draftId, "");
+  } catch {
+    // ignore
+  }
+}
+
+export async function flushTelegramPreview(
+  chatId: number,
+  deps: TelegramPreviewRuntimeDeps,
+): Promise<void> {
+  const state = deps.getState();
+  if (!state) return;
+  state.flushTimer = undefined;
+  const snapshot = buildTelegramPreviewSnapshot({
+    state,
+    maxMessageLength: deps.maxMessageLength,
+    renderPreviewText: deps.renderPreviewText,
+    renderTelegramMessage: deps.renderTelegramMessage,
+  });
+  if (!snapshot) return;
+  if (
+    shouldUseTelegramDraftPreview({
+      draftSupport: deps.getDraftSupport(),
+      snapshot,
+    })
+  ) {
+    const draftId = state.draftId ?? deps.allocateDraftId();
+    state.draftId = draftId;
+    try {
+      await deps.sendDraft(chatId, draftId, snapshot.text);
+      deps.setDraftSupport("supported");
+      state.mode = "draft";
+      state.lastSentText = snapshot.text;
+      state.lastSentParseMode = snapshot.parseMode;
+      state.lastSentStrategy = snapshot.strategy;
+      return;
+    } catch {
+      deps.setDraftSupport("unsupported");
+    }
+  }
+  if (state.mode === "draft" && state.draftId !== undefined) {
+    try {
+      await deps.sendDraft(chatId, state.draftId, "");
+    } catch {
+      // ignore
+    }
+  }
+  if (state.messageId === undefined) {
+    const sent = await deps.sendMessage(chatId, snapshot.text, {
+      parseMode: snapshot.parseMode,
+    });
+    state.messageId = sent.message_id;
+    state.mode = "message";
+    state.lastSentText = snapshot.text;
+    state.lastSentParseMode = snapshot.parseMode;
+    state.lastSentStrategy = snapshot.strategy;
+    return;
+  }
+  await deps.editMessageText(chatId, state.messageId, snapshot.text, {
+    parseMode: snapshot.parseMode,
+  });
+  state.mode = "message";
+  state.lastSentText = snapshot.text;
+  state.lastSentParseMode = snapshot.parseMode;
+  state.lastSentStrategy = snapshot.strategy;
+}
+
+export async function finalizeTelegramPreview(
+  chatId: number,
+  deps: TelegramPreviewRuntimeDeps,
+): Promise<boolean> {
+  const state = deps.getState();
+  if (!state) return false;
+  await flushTelegramPreview(chatId, deps);
+  const finalText = buildTelegramPreviewFinalText(state);
+  if (!finalText) {
+    await clearTelegramPreview(chatId, deps);
+    return false;
+  }
+  if (state.mode === "draft") {
+    await deps.sendMessage(chatId, finalText);
+    await clearTelegramPreview(chatId, deps);
+    return true;
+  }
+  deps.setState(undefined);
+  return state.messageId !== undefined;
+}
+
+export async function finalizeTelegramMarkdownPreview(
+  chatId: number,
+  markdown: string,
+  deps: TelegramPreviewRuntimeDeps,
+): Promise<boolean> {
+  const state = deps.getState();
+  if (!state) return false;
+  await flushTelegramPreview(chatId, deps);
+  const chunks = deps.renderTelegramMessage(markdown, { mode: "markdown" });
+  if (chunks.length === 0) {
+    await clearTelegramPreview(chatId, deps);
+    return false;
+  }
+  if (state.mode === "draft") {
+    await deps.sendRenderedChunks(chatId, chunks);
+    await clearTelegramPreview(chatId, deps);
+    return true;
+  }
+  if (state.messageId === undefined) return false;
+  await deps.editRenderedMessage(chatId, state.messageId, chunks);
+  deps.setState(undefined);
+  return true;
+}