@llblab/pi-telegram 0.5.1 → 0.5.2

package/README.md

@@ -102,6 +102,7 @@ Run these inside pi, not Telegram:
 - `👎` 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.
 - Reactions apply to any waiting Telegram turn, including text, voice, files, images, and media groups. For media groups, a reaction on any message in the group applies to the whole queued turn.
 - 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.
+- Telegram replies to earlier text or caption messages are forwarded as `[reply]` context for normal prompts, while slash commands still parse from the new message text only.
 - Inbound images, albums, and files are saved to `~/.pi/agent/tmp/telegram`. Unhandled local file paths are included in the prompt, handled attachment output is injected into the prompt text, and inbound images are forwarded to pi as image inputs. Inbound downloads default to a 50 MiB limit and can be adjusted with `PI_TELEGRAM_INBOUND_FILE_MAX_BYTES` or `TELEGRAM_MAX_FILE_SIZE_BYTES`.
 - Queue reactions depend on Telegram delivering `message_reaction` updates for your bot and chat type.
 

package/docs/architecture.md

@@ -23,21 +23,21 @@ Naming rule: because the repository already scopes this codebase to Telegram, ex
 
 Current runtime areas use these ownership boundaries:
 
-| Domain | Owns |
-| ------ | ---- |
-| `index.ts` | Single composition root for live pi/Telegram ports, session state, API-bound transport adapters, and status updates |
-| `api` | Bot API transport shapes/helpers, retries, file download, temp-dir lifecycle, inbound limits, chat actions, lazy bot-token clients, runtime error recording |
-| `config` / `setup` | Persisted bot/session pairing state, authorization, first-user pairing, token prompting, env fallback, validation, config persistence |
-| `locks` / `polling` | Singleton `locks.json` ownership, takeover/restart semantics, long-poll controller state, update offset persistence, poll-loop runtime wiring |
-| `updates` / `routing` | Update classification/execution planning, paired authorization, reactions, edits, callbacks, and inbound route composition |
-| `media` / `turns` / `handlers` | Text/media extraction, media-group debounce, inbound downloads, turn building/editing, image reads, attachment-handler matching/execution/fallback output |
-| `queue` | Queue item contracts, lane admission/order, stores, mutations, dispatch readiness/runtime, prompt/control enqueueing, session and agent/tool lifecycle sequencing |
-| `runtime` | Session-local coordination primitives: counters, lifecycle flags, setup guard, abort handler, typing-loop timers, prompt-dispatch flags, agent-end reset binding |
-| `model` / `menu` / `commands` | Model identity/thinking levels, scoped model resolution, in-flight switching, inline status/model/thinking UI, slash commands, bot command registration |
-| `preview` / `replies` / `rendering` | Preview lifecycle/transports, final reply delivery and reply parameters, Telegram HTML Markdown rendering, chunking, stable-preview snapshots |
-| `attachments` | `telegram_attach` registration, outbound attachment queueing, stat/limit checks, photo/document delivery classification |
-| `status` | Status-bar/status-message rendering, queue-lane status views, redacted runtime event ring, grouped pi diagnostics |
-| `lifecycle` / `prompts` / `pi` | pi hook registration, Telegram-specific before-agent prompt injection, centralized direct pi SDK imports and context adapters |
+| Domain                              | Owns                                                                                                                                                              |
+| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `index.ts`                          | Single composition root for live pi/Telegram ports, session state, API-bound transport adapters, and status updates                                               |
+| `api`                               | Bot API transport shapes/helpers, retries, file download, temp-dir lifecycle, inbound limits, chat actions, lazy bot-token clients, runtime error recording       |
+| `config` / `setup`                  | Persisted bot/session pairing state, authorization, first-user pairing, token prompting, env fallback, validation, config persistence                             |
+| `locks` / `polling`                 | Singleton `locks.json` ownership, takeover/restart semantics, long-poll controller state, update offset persistence, poll-loop runtime wiring                     |
+| `updates` / `routing`               | Update classification/execution planning, paired authorization, reactions, edits, callbacks, and inbound route composition                                        |
+| `media` / `turns` / `handlers`      | Text/media extraction, media-group debounce, inbound downloads, turn building/editing, image reads, attachment-handler matching/execution/fallback output         |
+| `queue`                             | Queue item contracts, lane admission/order, stores, mutations, dispatch readiness/runtime, prompt/control enqueueing, session and agent/tool lifecycle sequencing |
+| `runtime`                           | Session-local coordination primitives: counters, lifecycle flags, setup guard, abort handler, typing-loop timers, prompt-dispatch flags, agent-end reset binding  |
+| `model` / `menu` / `commands`       | Model identity/thinking levels, scoped model resolution, in-flight switching, inline status/model/thinking UI, slash commands, bot command registration           |
+| `preview` / `replies` / `rendering` | Preview lifecycle/transports, final reply delivery and reply parameters, Telegram HTML Markdown rendering, chunking, stable-preview snapshots                     |
+| `attachments`                       | `telegram_attach` registration, outbound attachment queueing, stat/limit checks, photo/document delivery classification                                           |
+| `status`                            | Status-bar/status-message rendering, queue-lane status views, redacted runtime event ring, grouped pi diagnostics                                                 |
+| `lifecycle` / `prompts` / `pi`      | pi hook registration, Telegram-specific before-agent prompt injection, centralized direct pi SDK imports and context adapters                                     |
 
 Boundary invariants:
 
@@ -71,13 +71,14 @@ Telegram bot configuration stays in `~/.pi/agent/telegram.json`; singleton runti
 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 a default 50 MiB size limit, partial-download cleanup on failures, and stale temp cleanup on session start; operators can tune the limit with `PI_TELEGRAM_INBOUND_FILE_MAX_BYTES` or `TELEGRAM_MAX_FILE_SIZE_BYTES`
-6. Configured inbound attachment handlers may run on downloaded files by MIME wildcard, Telegram attachment type, or generic match selector; command templates receive safe command-arg substitution for `{file}`/`{mime}`/`{type}`
-7. Matching handlers are tried in config order: a non-zero exit records diagnostics and falls back to the next matching handler, while the first successful handler stops the chain
-8. Local attachments stay visible under `[attachments] <directory>` with relative file entries, and handler stdout is appended under `[outputs]` before the agent sees the turn; failed handlers omit output while keeping the attachment entry
-9. A `PendingTelegramTurn` is created and queued locally
-10. Telegram `edited_message` updates are routed separately and update a matching queued turn when the original message has not been dispatched yet
-11. The queue dispatcher sends the turn into pi only when dispatch is safe
+5. Slash command parsing uses only the new message text/caption, while Telegram `reply_to_message` text/caption is injected later as prompt-only `[reply]` context for normal queued turns
+6. Files are streamed into `~/.pi/agent/tmp/telegram` with a default 50 MiB size limit, partial-download cleanup on failures, and stale temp cleanup on session start; operators can tune the limit with `PI_TELEGRAM_INBOUND_FILE_MAX_BYTES` or `TELEGRAM_MAX_FILE_SIZE_BYTES`
+7. Configured inbound attachment handlers may run on downloaded files by MIME wildcard, Telegram attachment type, or generic match selector; command templates receive safe command-arg substitution for `{file}`/`{mime}`/`{type}`
+8. Matching handlers are tried in config order: a non-zero exit records diagnostics and falls back to the next matching handler, while the first successful handler stops the chain
+9. Local attachments stay visible under `[attachments] <directory>` with relative file entries, and handler stdout is appended under `[outputs]` before the agent sees the turn; failed handlers omit output while keeping the attachment entry
+10. A `PendingTelegramTurn` is created and queued locally
+11. Telegram `edited_message` updates are routed separately and update a matching queued turn when the original message has not been dispatched yet
+12. The queue dispatcher sends the turn into pi only when dispatch is safe
 
 ### Queue Safety Model
 
@@ -90,12 +91,12 @@ Queued items now use two explicit dimensions:
 
 Admission contract:
 
-| Admission             | Examples                                             | Queue shape                                                          | Dispatch rank |
-| --------------------- | ---------------------------------------------------- | -------------------------------------------------------------------- | ------------- |
-| Immediate execution   | `/compact`, `/stop`, `/help`, `/start`               | Does not enter the Telegram queue; `/stop` also clears queued items  | N/A           |
+| Admission             | Examples                                                     | Queue shape                                                          | Dispatch rank |
+| --------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------- | ------------- |
+| Immediate execution   | `/compact`, `/stop`, `/help`, `/start`                       | Does not enter the Telegram queue; `/stop` also clears queued items  | N/A           |
 | Control queue         | Model-switch continuation turns and future deferred controls | `queueLane: control`; accepts control items and continuation prompts | 0             |
-| Priority prompt queue | A waiting prompt promoted by `👍`                    | `kind: prompt`, `queueLane: priority`                                | 1             |
-| Default prompt queue  | Normal Telegram text/media turns                     | `kind: prompt`, `queueLane: default`                                 | 2             |
+| Priority prompt queue | A waiting prompt promoted by `👍`                            | `kind: prompt`, `queueLane: priority`                                | 1             |
+| Default prompt queue  | Normal Telegram text/media turns                             | `kind: prompt`, `queueLane: default`                                 | 2             |
 
 The command action itself carries its execution mode, and the queue domain exposes lane contracts for admission mode, dispatch rank, and allowed item kinds. Queue append and planning paths validate lane admission so a malformed control/default or other invalid lane pairing fails predictably instead of silently changing priority. This lets synthetic control actions and Telegram prompts share one stable ordering model while still rendering distinctly in status output. In the pi status bar, busy labels distinguish `active`, `dispatching`, `queued`, `tool running`, `model`, and `compacting`; priority prompts are marked with `⬆` while control items keep markers such as `⚡`.
 

package/lib/media.ts

@@ -6,6 +6,7 @@
 import { basename, dirname } from "node:path";
 
 const TELEGRAM_MEDIA_GROUP_DEBOUNCE_MS = 1200;
+const TELEGRAM_REPLY_CONTEXT_MAX_LENGTH = 1000;
 
 export interface TelegramPhotoSize {
   file_id: string;
@@ -27,6 +28,12 @@ export interface TelegramVoice {
   mime_type?: string;
 }
 
+export interface TelegramReplyToMessage {
+  message_id?: number;
+  text?: string;
+  caption?: string;
+}
+
 export interface TelegramSticker {
   file_id: string;
 }
@@ -35,6 +42,7 @@ export interface TelegramMediaMessage {
   message_id: number;
   text?: string;
   caption?: string;
+  reply_to_message?: TelegramReplyToMessage;
   media_group_id?: string;
   photo?: TelegramPhotoSize[];
   document?: TelegramDocument;
@@ -167,12 +175,58 @@ export function extractTelegramMessageText(
   return (message.text || message.caption || "").trim();
 }
 
+function truncateTelegramReplyContextText(text: string): string {
+  if (text.length <= TELEGRAM_REPLY_CONTEXT_MAX_LENGTH) return text;
+  return `${text.slice(0, TELEGRAM_REPLY_CONTEXT_MAX_LENGTH).trimEnd()}…`;
+}
+
+export function extractTelegramReplyContextText(
+  message: TelegramMediaMessage,
+): string {
+  const quoted = (
+    message.reply_to_message?.text ||
+    message.reply_to_message?.caption ||
+    ""
+  ).trim();
+  return quoted ? truncateTelegramReplyContextText(quoted) : "";
+}
+
+export function appendTelegramReplyContext(
+  text: string,
+  replyContext: string,
+): string {
+  if (!replyContext) return text;
+  const replyBlock = `[reply] ${replyContext}`;
+  return text ? `${text}\n\n${replyBlock}` : `_\n\n${replyBlock}`;
+}
+
+export function extractTelegramMessagePromptText(
+  message: TelegramMediaMessage,
+): string {
+  return appendTelegramReplyContext(
+    extractTelegramMessageText(message),
+    extractTelegramReplyContextText(message),
+  );
+}
+
 export function extractTelegramMessagesText(
   messages: TelegramMediaMessage[],
 ): string {
   return messages.map(extractTelegramMessageText).filter(Boolean).join("\n\n");
 }
 
+export function extractTelegramMessagesPromptText(
+  messages: TelegramMediaMessage[],
+): string {
+  const text = extractTelegramMessagesText(messages);
+  const firstMessage = messages[0];
+  if (!firstMessage) return text;
+  return appendTelegramReplyContext(
+    text,
+    extractTelegramReplyContextText(firstMessage),
+  );
+}
+
 export function extractFirstTelegramMessageText(
   messages: TelegramMediaMessage[],
 ): string {

package/lib/turns.ts

@@ -11,7 +11,10 @@ import {
   type DownloadedTelegramMessageFile,
   type DownloadTelegramMessageFilesDeps,
   downloadTelegramMessageFiles,
+  extractTelegramMessagesPromptText,
   extractTelegramMessagesText,
+  appendTelegramReplyContext,
+  extractTelegramReplyContextText,
   formatTelegramHistoryText,
   guessMediaType,
   type TelegramMediaMessage,
@@ -94,6 +97,11 @@ function appendTelegramAttachmentSection(
   return `${prefix}${header}\n${items.map((item) => `- ${item}`).join("\n")}`;
 }
 
+function appendTelegramPromptText(prompt: string, rawText: string): string {
+  if (!rawText) return prompt;
+  return `${prompt} ${rawText}`;
+}
+
 export function buildTelegramTurnPrompt(options: {
   telegramPrefix: string;
   rawText: string;
@@ -112,10 +120,10 @@ export function buildTelegramTurnPrompt(options: {
     prompt += "\n\nCurrent Telegram message:";
   }
   if (options.rawText.length > 0) {
-    prompt +=
+    prompt =
       (options.historyTurns?.length ?? 0) > 0
-        ? `\n${options.rawText}`
-        : ` ${options.rawText}`;
+        ? `${prompt}\n${options.rawText}`
+        : appendTelegramPromptText(prompt, options.rawText);
   }
   const promptFiles = options.promptFiles ?? options.files;
   prompt = appendTelegramAttachmentSection(prompt, promptFiles);
@@ -193,12 +201,11 @@ function buildEditedTelegramPromptText(options: {
       attachmentFiles,
     };
   }
-  const promptText =
-    options.rawText.length > 0
-      ? `${options.telegramPrefix} ${options.rawText}`
-      : options.telegramPrefix;
   return {
-    text: `${promptText}${attachmentSuffix}`,
+    text: `${appendTelegramPromptText(
+      options.telegramPrefix,
+      options.rawText,
+    )}${attachmentSuffix}`,
     attachmentFiles,
   };
 }
@@ -207,6 +214,7 @@ export function updateTelegramPromptTurnText(options: {
   turn: PendingTelegramTurn;
   telegramPrefix: string;
   rawText: string;
+  statusText?: string;
 }): PendingTelegramTurn {
   let attachmentFiles: DownloadedTelegramTurnFile[] = [];
   const nextContent = options.turn.content.map((block, index) => {
@@ -227,7 +235,7 @@ export function updateTelegramPromptTurnText(options: {
     content: nextContent,
     historyText: formatTelegramHistoryText(options.rawText, attachmentFiles),
     statusSummary: formatTelegramTurnStatusSummary(
-      options.rawText,
+      options.statusText ?? options.rawText,
       attachmentFiles,
     ),
   };
@@ -240,6 +248,7 @@ export function updateQueuedTelegramPromptTurnText<
   sourceMessageId: number | undefined;
   telegramPrefix: string;
   rawText: string;
+  statusText?: string;
 }): { items: TelegramQueueItem<TContext>[]; changed: boolean } {
   if (options.sourceMessageId === undefined) {
     return { items: options.items, changed: false };
@@ -257,6 +266,7 @@ export function updateQueuedTelegramPromptTurnText<
       turn: item,
       telegramPrefix: options.telegramPrefix,
       rawText: options.rawText,
+      statusText: options.statusText,
     });
   });
   return { items, changed };
@@ -278,7 +288,8 @@ export function createTelegramQueuedPromptEditRuntime<
         items: deps.getQueuedItems(),
         sourceMessageId: message.message_id,
         telegramPrefix: TELEGRAM_PREFIX,
-        rawText: extractTelegramMessagesText([message]),
+        rawText: extractTelegramMessagesPromptText([message]),
+        statusText: extractTelegramMessagesText([message]),
       });
       deps.setQueuedItems(items);
       if (changed) deps.updateStatus(ctx);
@@ -293,6 +304,7 @@ export interface BuildTelegramPromptTurnOptions {
   historyTurns?: PendingTelegramTurn[];
   queueOrder: number;
   rawText: string;
+  statusText?: string;
   files: DownloadedTelegramTurnFile[];
   promptFiles?: DownloadedTelegramTurnFile[];
   handlerOutputs?: string[];
@@ -332,18 +344,26 @@ export function createTelegramPromptTurnRuntimeBuilder<
 ) => Promise<PendingTelegramTurn> {
   return async (messages, historyTurns = [], ctx) => {
     const rawText = extractTelegramMessagesText(messages);
+    const replyContext = messages[0]
+      ? extractTelegramReplyContextText(messages[0])
+      : "";
     const files = await downloadTelegramMessageFiles(messages, {
       downloadFile: deps.downloadFile,
     });
     const processed = deps.processAttachments
       ? await deps.processAttachments(files, rawText, ctx as TContext)
       : { rawText, promptFiles: files };
+    const promptText = appendTelegramReplyContext(
+      processed.rawText,
+      replyContext,
+    );
     return buildTelegramPromptTurnRuntime({
       telegramPrefix: TELEGRAM_PREFIX,
       messages,
       historyTurns,
       queueOrder: deps.allocateQueueOrder(),
-      rawText: processed.rawText,
+      rawText: promptText,
+      statusText: processed.rawText,
       files,
       promptFiles: processed.promptFiles,
       handlerOutputs: processed.handlerOutputs,
@@ -399,7 +419,7 @@ export async function buildTelegramPromptTurn(
       options.handlerOutputs,
     ),
     statusSummary: formatTelegramTurnStatusSummary(
-      options.rawText,
+      options.statusText ?? options.rawText,
       options.promptFiles ?? options.files,
       options.handlerOutputs,
     ),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "private": false,
   "description": "Better Telegram DM bridge extension for pi",
   "type": "module",