@llblab/pi-telegram 0.7.1 → 0.7.2

package/AGENTS.md

@@ -132,6 +132,7 @@ The canonical detailed ownership map lives in [`docs/architecture.md`](./docs/ar
 - Command help plus prompt-template commands and status/model/thinking/queue controls are driven through `/start`'s Telegram inline application menu and callback queries; the Queue button shows the queued-item count, model-menu scope/pagination controls stay at the top under Main menu, the model pagination indicator opens a compact page picker, and thinking-menu text stays a compact heading because the current level is marked by button state; `/status`, `/model`, `/thinking`, and `/queue` are hidden compatibility shortcuts
 - Shared inline-keyboard structure belongs to `keyboard`; application-control button labels, callback data, and callback behavior stay in `menu`/`menu-model`/`menu-thinking`/`menu-status`/`menu-queue` while core queue mechanics stay in `queue`
 - Inbound files may become π image inputs or configured attachment-handler text before queueing; outbound files must flow through `telegram_attach`
+- Long Telegram text split recovery belongs to `text-groups`: keep it conservative, short-debounced, same chat/user/message-id contiguous, and gated by near-limit human text so normal rapid follow-ups and slash commands stay separate
 - Inbound attachment handlers and command-backed outbound handlers use command templates as the standard integration contract; built-in outbound buttons use inline keyboards plus callback routing because no external command execution is needed
 - Telegram prompt-template commands are discovered from π slash commands with `source: "prompt"`; π template names are mapped to Bot API-compatible aliases (`fix-tests` → `/fix_tests`), aliases that conflict with built-in bridge commands or hidden shortcuts are not displayed, prompt-template aliases stay out of the Telegram bot command menu, and the bridge expands template files before queueing because extension-originated `sendUserMessage()` bypasses π's interactive template expansion
 - Unknown callback data not owned by pi-telegram prefixes (`tgbtn:`, `menu:`, `model:`, `thinking:`, `status:`, `queue:`) may be forwarded as `[callback] <data>` after built-in handlers decline it; external extensions should follow `docs/callback-namespaces.md` and must not poll the same bot independently

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.7.2: Split Text Coalescing Hotfix
+
+- `[Text Coalescing]` Telegram text messages that look like automatic splits of one near-limit human message are now short-debounced and forwarded to π as one prompt, using a conservative 3600-character near-limit threshold. Commands, bot messages, media groups, captions, non-contiguous messages, and normal short follow-ups bypass coalescing. Impact: long pasted logs/prompts are less likely to arrive as separate π turns when Telegram chunks them.
+- `[Runtime Tests]` The media-group runtime regression now waits for the real debounce instead of mixing fake timers with the polling loop, and the reaction-priority runtime test flushes pending microtasks before ending the active turn. Impact: CI should stop failing on timing-only races around delayed dispatch and queued reaction mutations.
+- `[Callback Namespaces]` Current status-screen navigation callbacks now use the canonical `menu:` namespace (`menu:model`, `menu:thinking`, `menu:queue`). `status:` remains reserved as an owned legacy prefix but is no longer emitted by current UI. Impact: new inline menu callbacks align with the unified app-menu model while old `status:` payloads still cannot leak to external fallback handlers.
+- `[Package]` Bumped package metadata to `0.7.2` through npm and kept the lockfile in sync.
+
 ## 0.7.1: Layered Callback Interop
 
 - `[Callback Interop]` Unknown Telegram inline-button callback data that does not belong to pi-telegram-owned prefixes (`tgbtn:`, `menu:`, `model:`, `thinking:`, `status:`, `queue:`) is now forwarded to π as `[callback] <data>` after assistant-button, queue-menu, and app-menu handlers decline it. `docs/callback-namespaces.md` defines the shared callback namespace standard for layered extensions. Impact: layered π extensions can namespace and handle their own Telegram inline buttons without polling the same bot or forking pi-telegram.

package/README.md

@@ -77,7 +77,7 @@ Once paired, simply chat with your bot in Telegram. All text, images, and files
 
 Use these inside the Telegram DM with your bot:
 
-- **`/start`**: Pair the first Telegram user when needed, register the bot command menu, and open the inline application menu with command help, available π prompt templates, status rows, and controls.
+- **`/start`**: Pair the first Telegram user when needed, register bridge bot commands, and open the inline application menu with command help, available π prompt templates, status rows, and controls.
 - **`/compact`**: Start session compaction (only works when the session is idle).
 - **`/next`**: Dispatch the next queued turn (aborts π first if busy).
 - **`/continue`**: Enqueue a priority `continue` prompt. It waits like normal Telegram work when π is busy and can trigger prompt/skill handling that listens for `continue`.
@@ -102,6 +102,7 @@ Run these inside π, not Telegram:
 ### Queue, Reactions, and Media
 
 - If you send more Telegram messages while π is busy, they enter the default prompt queue and are processed in order.
+- Very long text messages that Telegram appears to split automatically are coalesced through a short conservative debounce and forwarded to π as one prompt when the first chunk is near Telegram's text limit, currently using a 3600-character threshold. Commands, bot messages, media groups, and normal short follow-ups are not coalesced.
 - `👍`, `⚡️`, `❤️`, and `🕊` move a waiting prompt into the priority prompt queue, behind control actions but ahead of default prompts. Removing the last priority reaction sends it back to its normal queue position, and adding a priority reaction again gives it a fresh priority position.
 - `👎`, `👻`, `💔`, and `💩` remove 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 removal reactions.
 - 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.

package/docs/architecture.md

@@ -30,7 +30,7 @@ Current runtime areas use these ownership boundaries:
 | `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` / `attachment-handlers` | Text/media extraction, media-group debounce, inbound downloads, turn building/editing, image reads, attachment-handler matching/execution/fallback output         |
+| `media` / `text-groups` / `turns` / `attachment-handlers` | Text/media extraction, media-group debounce, long-text split coalescing, 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-model` / `menu-thinking` / `menu-status` / `menu` / `menu-queue` / `commands` | Model identity/thinking levels, scoped model resolution, in-flight switching, model-menu UI, thinking-menu UI, status-menu UI, inline application callback composition, queue-menu UI, slash commands, bot command registration |
@@ -156,7 +156,7 @@ Preferred order:
 
 Draft streaming can remain as a plain-text fallback path, but rich Telegram previews are driven through editable messages and stable-block snapshot selection.
 
-Telegram prompt responses use explicit delivery context to attach outbound text, rich previews, errors, attachment notices, and uploads as Telegram replies to the source prompt when possible. Reply metadata is opt-in per delivery path, uses `reply_parameters` with `allow_sending_without_reply: true`, and is applied only to the first chunk of split long responses; continuation chunks are sent as normal adjacent messages. Media-group turns reply to the turn's representative `replyToMessageId`, not to every source message in the group.
+Telegram prompt responses use explicit delivery context to attach outbound text, rich previews, errors, attachment notices, and uploads as Telegram replies to the source prompt when possible. Reply metadata is opt-in per delivery path, uses `reply_parameters` with `allow_sending_without_reply: true`, and is applied only to the first chunk of split long responses; continuation chunks are sent as normal adjacent messages. Media-group turns reply to the turn's representative `replyToMessageId`, not to every source message in the group. Long text split coalescing is intentionally conservative: only human text messages at or above the 3600-character near-limit threshold open the short debounce window, immediate same-chat/user contiguous text tails join that prompt, and commands, bot messages, captions, media groups, and normal short follow-ups bypass the coalescer.
 
 Outbound files are sent only after the active Telegram turn completes, must be staged through the `telegram_attach` tool, are staged atomically per tool call, are checked against a default 50 MiB limit configurable through `PI_TELEGRAM_OUTBOUND_ATTACHMENT_MAX_BYTES` or `TELEGRAM_MAX_ATTACHMENT_SIZE_BYTES`, and use file-backed multipart blobs so large sends do not require preloading whole files into memory.
 

package/docs/callback-namespaces.md

@@ -20,7 +20,7 @@ myext:page:2
 
 - Use a stable extension-owned namespace, preferably the package or extension name without scope punctuation.
 - Keep the namespace lowercase ASCII: `a-z`, `0-9`, `_`, `-`.
-- Do not use `pi-telegram` owned prefixes: `tgbtn:`, `menu:`, `model:`, `thinking:`, `status:`, `queue:`.
+- Do not use `pi-telegram` owned prefixes: `tgbtn:`, `menu:`, `model:`, `thinking:`, `status:`, `queue:`. Current app navigation uses `menu:`; `status:` remains reserved for legacy/owned status callbacks but is not emitted by current UI.
 - Keep the full `callback_data` within Telegram's 64-byte limit.
 - Put only opaque ids or small enum values in payloads; do not store secrets, full prompts, or large state.
 - Treat callbacks as untrusted input. Validate namespace, action, and payload before executing side effects.

package/index.ts

@@ -29,6 +29,7 @@ import * as Routing from "./lib/routing.ts";
 import * as Setup from "./lib/setup.ts";
 import * as OutboundHandlers from "./lib/outbound-handlers.ts";
 import * as Status from "./lib/status.ts";
+import * as TextGroups from "./lib/text-groups.ts";
 
 type ActivePiModel = NonNullable<Pi.ExtensionContext["model"]>;
 type RuntimeTelegramQueueItem = Queue.TelegramQueueItem<Pi.ExtensionContext>;
@@ -67,6 +68,10 @@ export default function (pi: Pi.ExtensionAPI) {
     Api.TelegramMessage,
     Pi.ExtensionContext
   >();
+  const textGroupRuntime = TextGroups.createTelegramTextGroupController<
+    Api.TelegramMessage,
+    Pi.ExtensionContext
+  >();
   const telegramQueueStore =
     Queue.createTelegramQueueStore<Pi.ExtensionContext>();
   const deferredQueueDispatchRuntime =
@@ -277,6 +282,7 @@ export default function (pi: Pi.ExtensionAPI) {
     bridgeRuntime,
     activeTurnRuntime,
     mediaGroupRuntime,
+    textGroupRuntime,
     telegramQueueStore,
     queueMutationRuntime,
     modelMenuRuntime,
@@ -342,7 +348,10 @@ export default function (pi: Pi.ExtensionAPI) {
     prepareTempDir,
     updateStatus,
     unbindDeferredDispatchContext: deferredQueueDispatchRuntime.unbind,
-    clearPendingMediaGroups: mediaGroupRuntime.clear,
+    clearPendingMediaGroups: TextGroups.createTelegramGroupedInputClearer({
+      clearMediaGroups: mediaGroupRuntime.clear,
+      clearTextGroups: textGroupRuntime.clear,
+    }),
     clearModelMenuState: modelMenuRuntime.clear,
     getActiveTurnChatId: activeTurnRuntime.getChatId,
     clearPreview: previewRuntime.clear,

package/lib/menu-queue.ts

@@ -463,7 +463,7 @@ function createQueueMenuCallbackHandler<
     const messageId = query.message?.message_id;
     if (!data || typeof chatId !== "number" || typeof messageId !== "number")
       return false;
-    if (data === "status:queue") {
+    if (data === "menu:queue" || data === "status:queue") {
       const state = deps.getStoredModelMenuState(messageId);
       if (!state) {
         await deps.answerCallbackQuery(

package/lib/menu-status.ts

@@ -51,7 +51,7 @@ function isTelegramStatusMenuCallbackAction(
   data: string | undefined,
   action: "model" | "thinking",
 ): boolean {
-  return data === `status:${action}`;
+  return data === `menu:${action}` || data === `status:${action}`;
 }
 
 function applyTelegramMenuRenderPayload(
@@ -144,7 +144,7 @@ export function buildStatusReplyMarkup(
         `${formatTelegramCommandEmojiPrefix("model")}Model`,
         activeModel ? getCanonicalModelId(activeModel) : "unknown",
       ),
-      callback_data: "status:model",
+      callback_data: "menu:model",
     },
   ]);
   if (activeModel?.reasoning) {
@@ -154,14 +154,14 @@ export function buildStatusReplyMarkup(
           `${formatTelegramCommandEmojiPrefix("thinking")}Thinking`,
           currentThinkingLevel,
         ),
-        callback_data: "status:thinking",
+        callback_data: "menu:thinking",
       },
     ]);
   }
   rows.push([
     {
       text: `🔢 Queue: ${queueItemCount}`,
-      callback_data: "status:queue",
+      callback_data: "menu:queue",
     },
   ]);
   return { inline_keyboard: rows };

package/lib/menu.ts

@@ -276,11 +276,15 @@ export type TelegramMenuCallbackAction =
 export function parseTelegramMenuCallbackAction(
   data: string | undefined,
 ): TelegramMenuCallbackAction {
-  if (data === "status:model") return { kind: "status", action: "model" };
-  if (data === "status:thinking") {
+  if (data === "menu:model" || data === "status:model") {
+    return { kind: "status", action: "model" };
+  }
+  if (data === "menu:thinking" || data === "status:thinking") {
     return { kind: "status", action: "thinking" };
   }
-  if (data === "status:queue") return { kind: "status", action: "queue" };
+  if (data === "menu:queue" || data === "status:queue") {
+    return { kind: "status", action: "queue" };
+  }
   if (data?.startsWith("thinking:set:")) {
     return {
       kind: "thinking:set",

package/lib/routing.ts

@@ -14,6 +14,7 @@ import * as Model from "./model.ts";
 import * as Queue from "./queue.ts";
 import * as PromptTemplates from "./prompt-templates.ts";
 import type { TelegramBridgeRuntime } from "./runtime.ts";
+import * as TextGroups from "./text-groups.ts";
 import * as Turns from "./turns.ts";
 import * as Updates from "./updates.ts";
 
@@ -39,6 +40,7 @@ export interface TelegramInboundRouteRuntimeDeps<
   bridgeRuntime: TelegramBridgeRuntime;
   activeTurnRuntime: Queue.TelegramActiveTurnStore;
   mediaGroupRuntime: Media.TelegramMediaGroupController<TMessage, TContext>;
+  textGroupRuntime: TextGroups.TelegramTextGroupController<TMessage, TContext>;
   telegramQueueStore: Queue.TelegramQueueStateStore<TContext>;
   queueMutationRuntime: Queue.TelegramQueueMutationController<TContext>;
   modelMenuRuntime: Menu.TelegramModelMenuRuntime<TModel>;
@@ -321,6 +323,14 @@ export function createTelegramInboundRouteRuntime<
     mediaGroups: deps.mediaGroupRuntime,
     dispatchMessages: commandOrPrompt.dispatchMessages,
   });
+  const textDispatch = TextGroups.createTelegramTextGroupDispatchRuntime<
+    TMessage,
+    TContext
+  >({
+    textGroups: deps.textGroupRuntime,
+    dispatchMessages: commandOrPrompt.dispatchMessages,
+    dispatchSingleMessage: mediaDispatch.handleMessage,
+  });
   const editRuntime = Turns.createTelegramQueuedPromptEditRuntime<
     TMessage,
     TContext
@@ -343,7 +353,7 @@ export function createTelegramInboundRouteRuntime<
     answerCallbackQuery: deps.answerCallbackQuery,
     handleAuthorizedTelegramCallbackQuery: callbackHandler,
     sendTextReply: deps.sendTextReply,
-    handleAuthorizedTelegramMessage: mediaDispatch.handleMessage,
+    handleAuthorizedTelegramMessage: textDispatch.handleMessage,
     handleAuthorizedTelegramEditedMessage: editRuntime.updateFromEditedMessage,
   });
 }

package/lib/text-groups.ts

@@ -0,0 +1,203 @@
+/**
+ * Telegram text-group coalescing helpers
+ * Zones: telegram inbound, queue admission, split-message recovery
+ * Owns conservative delayed grouping for Telegram text messages that look like automatic long-message splits
+ */
+
+const TELEGRAM_TEXT_GROUP_DEBOUNCE_MS = 700;
+const TELEGRAM_TEXT_GROUP_MIN_SPLIT_LENGTH = 3600;
+
+export interface TelegramTextGroupMessage {
+  message_id: number;
+  media_group_id?: string;
+  chat: { id: number };
+  from?: { id: number; is_bot?: boolean };
+  text?: string;
+  caption?: string;
+}
+
+export interface TelegramTextGroupState<TMessage, TContext = unknown> {
+  messages: TMessage[];
+  context?: TContext;
+  flushTimer?: ReturnType<typeof setTimeout>;
+}
+
+export interface TelegramTextGroupController<TMessage, TContext = unknown> {
+  queueMessage: (options: {
+    message: TMessage;
+    context: TContext;
+    dispatchMessages: (messages: TMessage[], ctx: TContext) => void;
+  }) => boolean;
+  clear: () => void;
+}
+
+export interface TelegramTextGroupControllerOptions {
+  debounceMs?: number;
+  minSplitLength?: number;
+  setTimer?: (
+    callback: () => void,
+    ms: number,
+  ) => ReturnType<typeof setTimeout>;
+  clearTimer?: (timer: ReturnType<typeof setTimeout>) => void;
+}
+
+export interface TelegramTextGroupDispatchRuntime<
+  TMessage extends TelegramTextGroupMessage,
+  TContext,
+> {
+  handleMessage: (message: TMessage, ctx: TContext) => Promise<void>;
+}
+
+export interface TelegramGroupedInputClearerDeps {
+  clearMediaGroups: () => void;
+  clearTextGroups: () => void;
+}
+
+function extractTelegramTextGroupText(
+  message: TelegramTextGroupMessage,
+): string {
+  return typeof message.text === "string" ? message.text : "";
+}
+
+function isTelegramTextGroupCommand(text: string): boolean {
+  return text.trimStart().startsWith("/");
+}
+
+function getTelegramTextGroupKey(
+  message: TelegramTextGroupMessage,
+): string | undefined {
+  if (message.media_group_id) return undefined;
+  if (!message.from || message.from.is_bot) return undefined;
+  if (typeof message.text !== "string") return undefined;
+  return `${message.chat.id}:${message.from.id}`;
+}
+
+function canStartTelegramTextGroup(
+  message: TelegramTextGroupMessage,
+  minSplitLength: number,
+): boolean {
+  const text = extractTelegramTextGroupText(message);
+  return text.length >= minSplitLength && !isTelegramTextGroupCommand(text);
+}
+
+function canAppendTelegramTextGroupMessage<
+  TMessage extends TelegramTextGroupMessage,
+>(
+  state: TelegramTextGroupState<TMessage, unknown>,
+  message: TMessage,
+): boolean {
+  const text = extractTelegramTextGroupText(message);
+  const previous = state.messages.at(-1);
+  return (
+    !!previous &&
+    message.message_id > previous.message_id &&
+    message.message_id <= previous.message_id + 2 &&
+    text.length > 0 &&
+    !isTelegramTextGroupCommand(text)
+  );
+}
+
+export function queueTelegramTextGroupMessage<
+  TMessage extends TelegramTextGroupMessage,
+  TContext = unknown,
+>(options: {
+  message: TMessage;
+  context: TContext;
+  groups: Map<string, TelegramTextGroupState<TMessage, TContext>>;
+  debounceMs: number;
+  minSplitLength: number;
+  setTimer: (callback: () => void, ms: number) => ReturnType<typeof setTimeout>;
+  clearTimer: (timer: ReturnType<typeof setTimeout>) => void;
+  dispatchMessages: (messages: TMessage[], ctx: TContext) => void;
+}): boolean {
+  const key = getTelegramTextGroupKey(options.message);
+  if (!key) return false;
+  const existing = options.groups.get(key);
+  if (
+    !existing &&
+    !canStartTelegramTextGroup(options.message, options.minSplitLength)
+  )
+    return false;
+  if (existing && !canAppendTelegramTextGroupMessage(existing, options.message))
+    return false;
+  const state = existing ?? { messages: [] };
+  state.messages.push(options.message);
+  state.context = options.context;
+  if (state.flushTimer) options.clearTimer(state.flushTimer);
+  state.flushTimer = options.setTimer(() => {
+    const queued = options.groups.get(key);
+    options.groups.delete(key);
+    if (!queued || queued.context === undefined) return;
+    options.dispatchMessages(queued.messages, queued.context);
+  }, options.debounceMs);
+  options.groups.set(key, state);
+  return true;
+}
+
+export function createTelegramTextGroupController<
+  TMessage extends TelegramTextGroupMessage,
+  TContext = unknown,
+>(
+  options: TelegramTextGroupControllerOptions = {},
+): TelegramTextGroupController<TMessage, TContext> {
+  const groups = new Map<string, TelegramTextGroupState<TMessage, TContext>>();
+  const debounceMs = options.debounceMs ?? TELEGRAM_TEXT_GROUP_DEBOUNCE_MS;
+  const minSplitLength =
+    options.minSplitLength ?? TELEGRAM_TEXT_GROUP_MIN_SPLIT_LENGTH;
+  const setTimer =
+    options.setTimer ??
+    ((callback: () => void, ms: number): ReturnType<typeof setTimeout> =>
+      setTimeout(callback, ms));
+  const clearTimer = options.clearTimer ?? clearTimeout;
+  return {
+    queueMessage: ({ message, context, dispatchMessages }) =>
+      queueTelegramTextGroupMessage({
+        message,
+        context,
+        groups,
+        debounceMs,
+        minSplitLength,
+        setTimer,
+        clearTimer,
+        dispatchMessages,
+      }),
+    clear: () => {
+      for (const state of groups.values()) {
+        if (state.flushTimer) clearTimer(state.flushTimer);
+      }
+      groups.clear();
+    },
+  };
+}
+
+export function createTelegramTextGroupDispatchRuntime<
+  TMessage extends TelegramTextGroupMessage,
+  TContext,
+>(deps: {
+  textGroups: TelegramTextGroupController<TMessage, TContext>;
+  dispatchMessages: (messages: TMessage[], ctx: TContext) => Promise<void>;
+  dispatchSingleMessage: (message: TMessage, ctx: TContext) => Promise<void>;
+}): TelegramTextGroupDispatchRuntime<TMessage, TContext> {
+  return {
+    handleMessage: async (message, ctx) => {
+      const queuedTextGroup = deps.textGroups.queueMessage({
+        message,
+        context: ctx,
+        dispatchMessages: (messages, queuedCtx) => {
+          void deps.dispatchMessages(messages, queuedCtx);
+        },
+      });
+      if (queuedTextGroup) return;
+      await deps.dispatchSingleMessage(message, ctx);
+    },
+  };
+}
+
+export function createTelegramGroupedInputClearer(
+  deps: TelegramGroupedInputClearerDeps,
+): () => void {
+  return () => {
+    deps.clearMediaGroups();
+    deps.clearTextGroups();
+  };
+}

package/package.json

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