@llblab/pi-telegram 0.7.0 → 0.7.2

package/AGENTS.md

@@ -132,8 +132,10 @@ 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 registered/displayed, and the bridge expands template files before queueing because extension-originated `sendUserMessage()` bypasses π's interactive template expansion
+- 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
 - Command templates stay compact and shell-free: no `command` field, no shell execution, inline defaults are allowed as `{name=default}`, `template` may be a string or an ordered composition array, only `args`/`defaults` inherit into leaves, top-level `timeout` wraps composed sequences, stdout pipes to the next step's stdin by default, and multi-step work should use `template: [...]` rather than provider-specific fields; `pipe` is only a legacy local alias
 - Command-template documentation examples should use portable executable placeholders such as `/path/to/stt` and `/path/to/tts`, not host-local skill paths or machine-specific install locations
 

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # 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.
+- `[Prompt Templates]` Prompt-template aliases stay visible only inside `/start` and are no longer registered in the Telegram bot command menu. Impact: reusable π workflows remain discoverable without making Telegram's global command menu noisy.
+- `[Package]` Bumped package metadata to `0.7.1` through npm and kept the lockfile in sync.
+
 ## 0.7.0: Unified App Menu & Command Template Hardening
 
 - `[Commands]` Visible Telegram bot command menu now exposes `/start`, `/compact`, `/next`, `/continue`, `/abort`, and `/stop`; `/help`, `/status`, `/model`, `/thinking`, and `/queue` remain hidden compatibility shortcuts. `/start`, `/help`, and `/status` open one unified app menu containing command help, status rows, and inline controls. Command emoji are centralized as fixed adornments in the commands domain and reused by matching menu buttons (`🤖` model, `🧠` thinking); `/next` uses `⏩` and `/continue` uses `▶️`. `/continue` enqueues a priority Telegram-owned `continue` prompt instead of forcing the next queued item or requiring π to be idle. Impact: the visible command surface is cleaner while existing operator muscle memory still works and skills can react to queued `continue` prompts.

package/README.md

@@ -77,14 +77,14 @@ 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`.
 - **`/stop`**: Abort the active run and clear all waiting Telegram queue items.
 - **`/abort`**: Abort the active run without touching the queue.
 
-Prompt-template commands: π prompt templates are mapped to Telegram-safe aliases (`fix-tests.md` becomes `/fix_tests`) and shown as compact command-only rows between the built-in commands and status rows in `/start`, then registered in the Telegram bot command menu unless the mapped name conflicts with a built-in Telegram bridge command or hidden shortcut. Sending `/template_name args` from Telegram expands the matching π prompt-template file and queues the expanded prompt like normal Telegram work.
+Prompt-template commands: π prompt templates are mapped to Telegram-safe aliases (`fix-tests.md` becomes `/fix_tests`) and shown as compact command-only rows between the built-in commands and status rows in `/start`. They are not registered in the Telegram bot command menu, keeping the bot menu focused on bridge controls. Sending `/template_name args` from Telegram expands the matching π prompt-template file and queues the expanded prompt like normal Telegram work.
 
 Hidden compatibility shortcuts: `/help` and `/status` open the same main application menu, `/model` opens the model section, `/thinking` opens the thinking section, and `/queue` opens the queue section. They are intentionally not shown in the bot command menu.
 
@@ -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.
@@ -190,7 +191,7 @@ List the main risks first.
 <!-- telegram_button: OK -->
 ```
 
-Button prompts are routed back into the normal Telegram queue as prompt turns. Keep the opening comment unclosed until the body-ending `-->` for body-form buttons. Closed heads must use `prompt="..."` or the colon shorthand to create a button. Outbound handler details are documented in [`docs/outbound-handlers.md`](./docs/outbound-handlers.md).
+Button prompts are routed back into the normal Telegram queue as prompt turns. Keep the opening comment unclosed until the body-ending `-->` for body-form buttons. Closed heads must use `prompt="..."` or the colon shorthand to create a button. Unknown inline-button callbacks that do not belong to pi-telegram are forwarded to π as `[callback] <data>` so other extensions can namespace and handle their own Telegram buttons without polling the bot themselves; see the [Callback Namespace Standard](./docs/callback-namespaces.md). Outbound handler details are documented in [`docs/outbound-handlers.md`](./docs/outbound-handlers.md).
 
 ## Streaming
 

package/docs/README.md

@@ -9,3 +9,4 @@ Living index of project documentation in `/docs`.
 - [attachment-handlers.md](./attachment-handlers.md) — Local `pi-telegram` attachment-handler config, placeholders, and fallbacks
 - [outbound-handlers.md](./outbound-handlers.md) — Local `pi-telegram` outbound-handler config, voice/button markup, artifact outputs, and callback routing
 - [locks.md](./locks.md) — Shared `locks.json` standard for singleton extension ownership
+- [callback-namespaces.md](./callback-namespaces.md) — Shared Telegram `callback_data` namespace standard for layered extensions

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 |
@@ -117,7 +117,7 @@ Dispatch is gated by:
 
 This prevents queue races around rapid follow-ups, `/compact`, and mixed local plus Telegram activity. Post-agent-end dispatch retries are scheduled through a session-bound deferred dispatcher that activates on session start, cancels timers on session shutdown, and skips callbacks from older generations before they touch `ExtensionContext`. Telegram `/start` and hidden compatibility shortcuts `/status`, `/model`, `/thinking`, and `/queue` execute immediately; the dispatch controller still serializes any deferred control items so a queued control action must settle before the next queued action can dispatch.
 
-`/start` opens the main application menu: visible command help, compact command-only prompt-template rows when π exposes Telegram-compatible prompt-template names, status rows (`Status`, `Usage`, `Cost`, `Context`), and top-level buttons for model, thinking, and queue sections. The Queue button includes the current queued-item count. Hidden compatibility shortcuts `/help`, `/status`, `/model`, `/thinking`, and `/queue` jump directly to their corresponding menu screens. Command emoji come from the `commands` domain map so visible command descriptions and matching menu buttons share one fixed adornment source. Prompt-template commands use a fixed `🧩` marker, map π template names to Telegram-safe aliases such as `fix-tests` → `/fix_tests`, are registered in the Telegram bot command menu when the mapped command does not conflict with built-in bridge commands or hidden shortcuts, and expand before queueing because `ExtensionAPI.sendUserMessage()` intentionally bypasses π prompt-template expansion for extension-originated messages. Every submenu starts with a top Back row so navigation stays anchored near the original user message above the inline keyboard; model-menu scope and pagination controls sit directly under that top row before model choices, and tapping the pagination indicator opens a compact page picker headed by `<b>Choose a page:</b>`. `menu-model` owns model-menu state, scoped model pages, model callback planning, page-picker rendering, and model-menu rendering while `model` owns core model identity/switching semantics. `menu-thinking` owns thinking-menu text, reply markup, callback handling, and message rendering. `menu-status` owns status-menu payloads, status callback handling, and status-message rendering. `menu-queue` owns queue-menu UI only: queue items are rendered under a compact `<b>Queue:</b>` heading, top-to-bottom in dispatch order, numbered, and marked with `⚡` for priority prompts or `📎` for prompts with attachments. An empty queue renders bold message text plus the top Main menu button, not a disabled empty-state button. Selecting an item opens a submenu that displays the full queued prompt text with Back, priority toggle, and Cancel. If a callback targets an item that has already left the queue, the menu refreshes the list instead of applying a stale mutation.
+`/start` opens the main application menu: visible command help, compact command-only prompt-template rows when π exposes Telegram-compatible prompt-template names, status rows (`Status`, `Usage`, `Cost`, `Context`), and top-level buttons for model, thinking, and queue sections. The Queue button includes the current queued-item count. Hidden compatibility shortcuts `/help`, `/status`, `/model`, `/thinking`, and `/queue` jump directly to their corresponding menu screens. Command emoji come from the `commands` domain map so visible command descriptions and matching menu buttons share one fixed adornment source. Prompt-template commands use a fixed `🧩` marker, map π template names to Telegram-safe aliases such as `fix-tests` → `/fix_tests`, stay visible only inside the `/start` menu, and expand before queueing because `ExtensionAPI.sendUserMessage()` intentionally bypasses π prompt-template expansion for extension-originated messages. Every submenu starts with a top Back row so navigation stays anchored near the original user message above the inline keyboard; model-menu scope and pagination controls sit directly under that top row before model choices, and tapping the pagination indicator opens a compact page picker headed by `<b>Choose a page:</b>`. `menu-model` owns model-menu state, scoped model pages, model callback planning, page-picker rendering, and model-menu rendering while `model` owns core model identity/switching semantics. `menu-thinking` owns thinking-menu text, reply markup, callback handling, and message rendering. `menu-status` owns status-menu payloads, status callback handling, and status-message rendering. `menu-queue` owns queue-menu UI only: queue items are rendered under a compact `<b>Queue:</b>` heading, top-to-bottom in dispatch order, numbered, and marked with `⚡` for priority prompts or `📎` for prompts with attachments. An empty queue renders bold message text plus the top Main menu button, not a disabled empty-state button. Selecting an item opens a submenu that displays the full queued prompt text with Back, priority toggle, and Cancel. If a callback targets an item that has already left the queue, the menu refreshes the list instead of applying a stale mutation.
 
 ### Abort Behavior
 
@@ -156,11 +156,11 @@ 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.
 
-Assistant-authored outbound actions use final-message markup instead of agent tool calls. Preview updates strip closed top-level HTML comments and currently open/partial top-level comment starts before rendering, so users do not see transient metadata even when streaming flushes happen after only `<`, `<!`, or `<!--`. On `agent_end`, the bridge removes top-level comments from the Markdown text reply, but treats column-zero top-level `<!-- telegram_voice ... -->` and `<!-- telegram_button ... -->` blocks specially before delivery; comments inside fenced code, quotes, lists, or indented examples stay literal, including fenced blocks with Markdown-valid indented closing fences. Voice maps to the first matching `outboundHandlers[]` entry with `type: "voice"`, synthesizes body text, `text="..."`, or colon shorthand through command-template execution, and uploads the generated OGG/Opus file via Telegram `sendVoice`; when no outbound voice handler is configured, it silently skips voice delivery. The `template: [...]` form can express TTS plus MP3-to-OGG conversion using configured templates and bridge-provided `{text}`, `{mp3}`, and `{ogg}` placeholders. Top-level `args` and `defaults` apply to all composed steps unless a step defines private values, the default command timeout applies automatically, and each step receives the previous step's stdout on stdin by default, without hard-coded filesystem defaults. Button blocks are built in: each `telegram_button` block becomes one inline-keyboard button on the final text, and callback clicks enqueue the configured prompt text as a normal Telegram prompt turn; the `telegram_button: Label` shorthand uses the same text for label and prompt, `prompt="..."` supports explicit one-line prompts, and body-form buttons use the body as the prompt. This keeps technical Markdown, code, tables, formulas, and numbered lists in the text channel when appropriate while allowing TTS-friendly voice messages and tappable continuations without invoking `telegram_attach` or extra transport tools.
+Assistant-authored outbound actions use final-message markup instead of agent tool calls. Preview updates strip closed top-level HTML comments and currently open/partial top-level comment starts before rendering, so users do not see transient metadata even when streaming flushes happen after only `<`, `<!`, or `<!--`. On `agent_end`, the bridge removes top-level comments from the Markdown text reply, but treats column-zero top-level `<!-- telegram_voice ... -->` and `<!-- telegram_button ... -->` blocks specially before delivery; comments inside fenced code, quotes, lists, or indented examples stay literal, including fenced blocks with Markdown-valid indented closing fences. Voice maps to the first matching `outboundHandlers[]` entry with `type: "voice"`, synthesizes body text, `text="..."`, or colon shorthand through command-template execution, and uploads the generated OGG/Opus file via Telegram `sendVoice`; when no outbound voice handler is configured, it silently skips voice delivery. The `template: [...]` form can express TTS plus MP3-to-OGG conversion using configured templates and bridge-provided `{text}`, `{mp3}`, and `{ogg}` placeholders. Top-level `args` and `defaults` apply to all composed steps unless a step defines private values, the default command timeout applies automatically, and each step receives the previous step's stdout on stdin by default, without hard-coded filesystem defaults. Button blocks are built in: each `telegram_button` block becomes one inline-keyboard button on the final text, and callback clicks enqueue the configured prompt text as a normal Telegram prompt turn; the `telegram_button: Label` shorthand uses the same text for label and prompt, `prompt="..."` supports explicit one-line prompts, and body-form buttons use the body as the prompt. Unknown callback data that does not match pi-telegram-owned prefixes (`tgbtn:`, `menu:`, `model:`, `thinking:`, `status:`, `queue:`) is forwarded to π as `[callback] <data>` after built-in handlers decline it, giving layered extensions a simple namespaced button channel without separate polling; layered callback payloads should follow the [Callback Namespace Standard](./callback-namespaces.md). This keeps technical Markdown, code, tables, formulas, and numbered lists in the text channel when appropriate while allowing TTS-friendly voice messages and tappable continuations without invoking `telegram_attach` or extra transport tools.
 
 ## Interactive Controls
 

package/docs/callback-namespaces.md

@@ -0,0 +1,36 @@
+# Callback Namespace Standard
+
+Telegram `callback_data` is one bot-wide namespace. Any extension that creates inline buttons for a bot shared with `pi-telegram` must use namespaced callback data.
+
+## Format
+
+```text
+<namespace>:<action>[:<payload>]
+```
+
+Examples:
+
+```text
+vividfish:approve:123
+vividfish:deny:123
+myext:page:2
+```
+
+## Rules
+
+- 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:`. 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.
+
+## pi-telegram fallback
+
+If `pi-telegram` receives callback data that is not owned by its built-in prefixes and no built-in handler consumes it, it forwards the click to π as:
+
+```text
+[callback] <callback_data>
+```
+
+Layered extensions may intercept that message and handle their own namespace. If no extension handles it, the assistant may see the fallback message and should tell the user the callback was not handled and the environment may be misconfigured.

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,
@@ -297,6 +303,7 @@ export default function (pi: Pi.ExtensionAPI) {
     getThinkingLevel,
     setThinkingLevel,
     setModel,
+    sendUserMessage,
     isIdle,
     hasPendingMessages,
     compact,
@@ -341,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/attachment-handlers.ts

@@ -259,7 +259,9 @@ function getTelegramAttachmentCompositionStepTimeout(
     startedAt,
   );
   const stepTimeout = getTelegramAttachmentHandlerConfiguredTimeout(step);
-  return stepTimeout === undefined ? remaining : Math.min(stepTimeout, remaining);
+  return stepTimeout === undefined
+    ? remaining
+    : Math.min(stepTimeout, remaining);
 }
 
 function getTelegramAttachmentHandlerKind(
@@ -300,7 +302,9 @@ async function executeTelegramAttachmentHandlerInvocation(
   const result = await deps.execCommand(invocation.command, invocation.args, {
     cwd,
     timeout,
-    ...(typeof handler === "object" && handler.retry !== undefined ? { retry: handler.retry } : {}),
+    ...(typeof handler === "object" && handler.retry !== undefined
+      ? { retry: handler.retry }
+      : {}),
     ...(stdin !== undefined ? { stdin } : {}),
   });
   if (result.code !== 0)

package/lib/command-templates.ts

@@ -210,7 +210,12 @@ export async function execCommandTemplate(
   options: CommandTemplateExecOptions = {},
 ): Promise<CommandTemplateExecResult> {
   const maxAttempts = options.retry ?? 1;
-  let lastResult: CommandTemplateExecResult = { stdout: "", stderr: "", code: 1, killed: false };
+  let lastResult: CommandTemplateExecResult = {
+    stdout: "",
+    stderr: "",
+    code: 1,
+    killed: false,
+  };
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
     const result = await execCommandTemplateOnce(command, args, options);
     if (result.code === 0) return result;

package/lib/commands.ts

@@ -61,84 +61,61 @@ function formatTelegramBotCommandDescription(
   return `${formatTelegramCommandEmojiPrefix(command)}${description}`;
 }
 
-export const TELEGRAM_BUILTIN_BOT_COMMANDS: readonly TelegramBotCommandDefinition[] = [
-  {
-    command: "start",
-    description: formatTelegramBotCommandDescription(
-      "start",
-      "Open menu / Pair bridge",
-    ),
-  },
-  {
-    command: "compact",
-    description: formatTelegramBotCommandDescription(
-      "compact",
-      "Compact current session",
-    ),
-  },
-  {
-    command: "next",
-    description: formatTelegramBotCommandDescription(
-      "next",
-      "Force next turn",
-    ),
-  },
-  {
-    command: "continue",
-    description: formatTelegramBotCommandDescription(
-      "continue",
-      "Queue continue prompt",
-    ),
-  },
-  {
-    command: "abort",
-    description: formatTelegramBotCommandDescription("abort", "Abort π"),
-  },
-  {
-    command: "stop",
-    description: formatTelegramBotCommandDescription(
-      "stop",
-      "Abort π & Clear queue",
-    ),
-  },
-];
+export const TELEGRAM_BUILTIN_BOT_COMMANDS: readonly TelegramBotCommandDefinition[] =
+  [
+    {
+      command: "start",
+      description: formatTelegramBotCommandDescription(
+        "start",
+        "Open menu / Pair bridge",
+      ),
+    },
+    {
+      command: "compact",
+      description: formatTelegramBotCommandDescription(
+        "compact",
+        "Compact current session",
+      ),
+    },
+    {
+      command: "next",
+      description: formatTelegramBotCommandDescription(
+        "next",
+        "Force next turn",
+      ),
+    },
+    {
+      command: "continue",
+      description: formatTelegramBotCommandDescription(
+        "continue",
+        "Queue continue prompt",
+      ),
+    },
+    {
+      command: "abort",
+      description: formatTelegramBotCommandDescription("abort", "Abort π"),
+    },
+    {
+      command: "stop",
+      description: formatTelegramBotCommandDescription(
+        "stop",
+        "Abort π & Clear queue",
+      ),
+    },
+  ];
 
 export const TELEGRAM_BOT_COMMANDS = TELEGRAM_BUILTIN_BOT_COMMANDS;
 
-const TELEGRAM_MAX_BOT_COMMANDS = 100;
-const TELEGRAM_BOT_COMMAND_DESCRIPTION_LIMIT = 256;
-
-function truncateTelegramBotCommandDescription(description: string): string {
-  if (description.length <= TELEGRAM_BOT_COMMAND_DESCRIPTION_LIMIT) return description;
-  return `${description.slice(0, TELEGRAM_BOT_COMMAND_DESCRIPTION_LIMIT - 1)}…`;
-}
-
-export function buildTelegramBotCommands(
-  promptTemplates: readonly TelegramPromptTemplateMenuCommand[] = [],
-): TelegramBotCommandDefinition[] {
-  const remainingSlots = TELEGRAM_MAX_BOT_COMMANDS - TELEGRAM_BUILTIN_BOT_COMMANDS.length;
-  const templateCommands = promptTemplates.slice(0, remainingSlots).map((template) => ({
-    command: template.command,
-    description: truncateTelegramBotCommandDescription(
-      `🧩 ${template.description?.trim() || "Prompt template"}`,
-    ),
-  }));
-  return [...TELEGRAM_BUILTIN_BOT_COMMANDS, ...templateCommands];
-}
-
 export interface TelegramBotCommandRegistrationDeps {
   setMyCommands: (
     commands: readonly TelegramBotCommandDefinition[],
   ) => Promise<unknown>;
-  getPromptTemplateCommands?: () => readonly TelegramPromptTemplateMenuCommand[];
 }
 
 export async function registerTelegramBotCommands(
   deps: TelegramBotCommandRegistrationDeps,
 ): Promise<void> {
-  await deps.setMyCommands(
-    buildTelegramBotCommands(deps.getPromptTemplateCommands?.()),
-  );
+  await deps.setMyCommands(TELEGRAM_BOT_COMMANDS);
 }
 
 export function createTelegramBotCommandRegistrar(
@@ -267,7 +244,10 @@ const TELEGRAM_RESERVED_COMMAND_NAME_SET = new Set<string>(
 export function isTelegramReservedCommandName(
   commandName: string | undefined,
 ): commandName is TelegramReservedCommandName {
-  return commandName !== undefined && TELEGRAM_RESERVED_COMMAND_NAME_SET.has(commandName);
+  return (
+    commandName !== undefined &&
+    TELEGRAM_RESERVED_COMMAND_NAME_SET.has(commandName)
+  );
 }
 
 export type TelegramCommandAction =
@@ -600,8 +580,10 @@ export function buildTelegramAppMenuHtml(
   statusHtml: string,
   promptTemplates: readonly TelegramPromptTemplateMenuCommand[] = [],
 ): string {
-  const promptTemplateHtml = buildTelegramPromptTemplateMenuHtml(promptTemplates);
-  if (!promptTemplateHtml) return `${TELEGRAM_APP_MENU_INTRO_HTML}\n\n${statusHtml}`;
+  const promptTemplateHtml =
+    buildTelegramPromptTemplateMenuHtml(promptTemplates);
+  if (!promptTemplateHtml)
+    return `${TELEGRAM_APP_MENU_INTRO_HTML}\n\n${statusHtml}`;
   return `${TELEGRAM_APP_MENU_INTRO_HTML}\n\n${promptTemplateHtml}\n\n${statusHtml}`;
 }
 
@@ -764,7 +746,7 @@ export async function handleTelegramCompactCommand(
     deps.isCompactionInProgress()
   ) {
     await deps.sendTextReply(
-      "Cannot compact while π or the Telegram queue is busy. Wait for queued turns to finish or send /stop first.",
+      "Cannot compact while π or the Telegram queue is busy. Wait for queued turns to finish or send /abort first.",
     );
     return;
   }
@@ -923,7 +905,6 @@ export function createTelegramCommandHandlerTargetRuntime<
     setAllowedUserId: deps.setAllowedUserId,
     registerBotCommands: createTelegramBotCommandRegistrar({
       setMyCommands: deps.setMyCommands,
-      getPromptTemplateCommands: deps.getPromptTemplateCommands,
     }),
     persistConfig: deps.persistConfig,
     sendTextReply: commandTargetRuntime.sendTextReply,
@@ -955,7 +936,11 @@ export function createTelegramCommandOrPromptRuntime<TMessage, TContext>(
       const firstMessage = messages[0];
       if (!firstMessage) return;
       const command = parseTelegramCommand(deps.extractRawText(messages));
-      const handled = await deps.handleCommand(command?.name, firstMessage, ctx);
+      const handled = await deps.handleCommand(
+        command?.name,
+        firstMessage,
+        ctx,
+      );
       if (handled) return;
       if (command?.name && deps.expandPromptTemplateCommand) {
         const expanded = deps.expandPromptTemplateCommand(
@@ -964,7 +949,10 @@ export function createTelegramCommandOrPromptRuntime<TMessage, TContext>(
         );
         if (expanded !== undefined) {
           await deps.enqueueTurn(
-            [deps.replaceMessageText(firstMessage, expanded), ...messages.slice(1)],
+            [
+              deps.replaceMessageText(firstMessage, expanded),
+              ...messages.slice(1),
+            ],
             ctx,
           );
           return;

package/lib/menu-queue.ts

@@ -24,11 +24,13 @@ function getTelegramQueueItemPromptText<Context>(
   item: Queue.TelegramQueueItem<Context>,
 ): string {
   if (item.kind !== "prompt") return item.statusSummary;
-  return item.content
-    .filter((block) => block.type === "text")
-    .map((block) => block.text)
-    .join("\n")
-    .trim() || item.statusSummary;
+  return (
+    item.content
+      .filter((block) => block.type === "text")
+      .map((block) => block.text)
+      .join("\n")
+      .trim() || item.statusSummary
+  );
 }
 function toTelegramQueueMenuItems<Context>(
   items: readonly Queue.TelegramQueueItem<Context>[],
@@ -461,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/outbound-handlers.ts

@@ -476,7 +476,9 @@ async function runVoiceReplyCommand(
     {
       cwd: options.cwd,
       timeout: options.timeout,
-      ...(typeof config === "object" && config.retry !== undefined ? { retry: config.retry } : {}),
+      ...(typeof config === "object" && config.retry !== undefined
+        ? { retry: config.retry }
+        : {}),
       ...(options.stdin !== undefined ? { stdin: options.stdin } : {}),
     },
   );

package/lib/prompts.ts

@@ -15,6 +15,7 @@ Inbound context:
 - \`[telegram]\` marks Telegram-originated messages.
 - \`[reply]\` is quoted context from the replied-to message, not a new instruction by itself. Use it to resolve references like "this", "it", or "that message"; the actual instruction is before [reply] unless it explicitly asks to act on the quote.
 - \`[attachments]\` gives a base directory plus relative local files; resolve and read them as needed. \`[outputs]\` contains attachment-handler stdout such as transcriptions or extracted text for those attachments.
+- Unknown \`[callback] ...\` messages may be intended for another extension; if you see one, say the callback was not handled and the environment may be misconfigured.
 
 Telegram-visible output:
 - Telegram is often phone-width; prefer narrow table columns because wide monospace tables can become unreadable.

package/lib/queue.ts

@@ -817,11 +817,20 @@ export interface TelegramAgentEndHookRuntimeDeps<
   ) => void;
   clearPreview: (chatId: number) => Promise<void>;
   setPreviewPendingText: (text: string) => void;
-  finalizeMarkdownPreview: TelegramAgentEndRuntimeDeps<TTurn, TReplyMarkup>["finalizeMarkdownPreview"];
-  sendMarkdownReply: TelegramAgentEndRuntimeDeps<TTurn, TReplyMarkup>["sendMarkdownReply"];
+  finalizeMarkdownPreview: TelegramAgentEndRuntimeDeps<
+    TTurn,
+    TReplyMarkup
+  >["finalizeMarkdownPreview"];
+  sendMarkdownReply: TelegramAgentEndRuntimeDeps<
+    TTurn,
+    TReplyMarkup
+  >["sendMarkdownReply"];
   sendTextReply: TelegramAgentEndRuntimeDeps<TTurn>["sendTextReply"];
   sendQueuedAttachments: (turn: TTurn) => Promise<void>;
-  planOutboundReply?: TelegramAgentEndRuntimeDeps<TTurn, TReplyMarkup>["planOutboundReply"];
+  planOutboundReply?: TelegramAgentEndRuntimeDeps<
+    TTurn,
+    TReplyMarkup
+  >["planOutboundReply"];
   sendOutboundReplyArtifacts?: TelegramAgentEndRuntimeDeps<TTurn>["sendOutboundReplyArtifacts"];
 }
 

package/lib/replies.ts

@@ -391,7 +391,9 @@ export function dedupSendTextReply(
   options?: { parseMode?: "HTML" },
 ) => Promise<number | undefined> {
   return async (chatId, replyToMessageId, text, options) => {
-    const effectiveReplyTo = dedup.shouldReply(replyToMessageId) ? replyToMessageId : undefined;
+    const effectiveReplyTo = dedup.shouldReply(replyToMessageId)
+      ? replyToMessageId
+      : undefined;
     return inner(chatId, effectiveReplyTo, text, options);
   };
 }
@@ -412,7 +414,9 @@ export function dedupSendMarkdownReply<TReplyMarkup = unknown>(
   options?: { replyMarkup?: TReplyMarkup },
 ) => Promise<number | undefined> {
   return async (chatId, replyToMessageId, markdown, options) => {
-    const effectiveReplyTo = dedup.shouldReply(replyToMessageId) ? replyToMessageId : undefined;
+    const effectiveReplyTo = dedup.shouldReply(replyToMessageId)
+      ? replyToMessageId
+      : undefined;
     return inner(chatId, effectiveReplyTo, markdown, options);
   };
 }

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>;
@@ -71,11 +73,14 @@ export interface TelegramInboundRouteRuntimeDeps<
     text: string,
   ) => Promise<number | undefined>;
   setMyCommands: Commands.TelegramBotCommandRegistrationDeps["setMyCommands"];
-  getCommands: () => Parameters<typeof PromptTemplates.getTelegramPromptTemplateCommands>[0];
+  getCommands: () => Parameters<
+    typeof PromptTemplates.getTelegramPromptTemplateCommands
+  >[0];
   downloadFile: Media.DownloadTelegramMessageFilesDeps["downloadFile"];
   getThinkingLevel: () => Model.ThinkingLevel;
   setThinkingLevel: (level: Model.ThinkingLevel) => void;
   setModel: (model: TModel) => Promise<boolean>;
+  sendUserMessage?: (message: string) => void;
   isIdle: (ctx: TContext) => boolean;
   hasPendingMessages: (ctx: TContext) => boolean;
   compact: (
@@ -89,6 +94,21 @@ export interface TelegramInboundRouteRuntimeDeps<
   ) => void;
 }
 
+const TELEGRAM_OWNED_CALLBACK_PREFIXES = [
+  "menu:",
+  "model:",
+  "queue:",
+  "status:",
+  "tgbtn:",
+  "thinking:",
+] as const;
+
+function isTelegramOwnedCallbackData(data: string): boolean {
+  return TELEGRAM_OWNED_CALLBACK_PREFIXES.some((prefix) =>
+    data.startsWith(prefix),
+  );
+}
+
 export function createTelegramInboundRouteRuntime<
   TUpdate extends Updates.TelegramUpdateFlow & {
     message?: TMessage;
@@ -167,6 +187,16 @@ export function createTelegramInboundRouteRuntime<
     }
     const handledByQueue = await deps.queueMenuCallbackHandler(query, ctx);
     if (handledByQueue) return;
+    const callbackData = query.data;
+    if (
+      deps.sendUserMessage &&
+      callbackData &&
+      !isTelegramOwnedCallbackData(callbackData)
+    ) {
+      deps.sendUserMessage(`[callback] ${callbackData}`);
+      await deps.answerCallbackQuery(query.id);
+      return;
+    }
     await menuCallbackHandler(query, ctx);
   };
   const promptTurnBuilder = Turns.createTelegramPromptTurnRuntimeBuilder<
@@ -206,7 +236,9 @@ export function createTelegramInboundRouteRuntime<
     deps.queueMutationRuntime.append(continueTurn, ctx);
     deps.dispatchNextQueuedTelegramTurn(ctx);
   };
-  const reservedCommandNames = new Set(Commands.TELEGRAM_RESERVED_COMMAND_NAMES);
+  const reservedCommandNames = new Set(
+    Commands.TELEGRAM_RESERVED_COMMAND_NAMES,
+  );
   const getPromptTemplateCommands = () =>
     PromptTemplates.getTelegramPromptTemplateCommands(
       deps.getCommands(),
@@ -291,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
@@ -313,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/status.ts

@@ -409,13 +409,16 @@ export function buildTelegramStatusBarText(
     return `${label} ${theme.fg("muted", "disconnected")}`;
   if (!state.paired)
     return `${label} ${theme.fg("warning", "awaiting pairing")}`;
-  const queued = state.queuedStatus ? theme.fg("muted", state.queuedStatus) : "";
+  const queued = state.queuedStatus
+    ? theme.fg("muted", state.queuedStatus)
+    : "";
   if (state.compactionInProgress) {
     return `${label} ${theme.fg("accent", "compacting")}${queued}`;
   }
   if (state.processing) {
     const processingStatus = state.processingStatus ?? "processing";
-    const processingToken = processingStatus === "active" ? "warning" : "accent";
+    const processingToken =
+      processingStatus === "active" ? "warning" : "accent";
     return `${label} ${theme.fg(processingToken, processingStatus)}${queued}`;
   }
   return `${label} ${theme.fg("success", "connected")}`;

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/lib/updates.ts

@@ -26,8 +26,18 @@ export type TelegramReactionType =
   | TelegramReactionTypeEmoji
   | TelegramReactionTypeNonEmoji;
 
-export const TELEGRAM_PRIORITY_REACTION_EMOJIS = ["👍", "⚡", "❤", "🕊"] as const;
-export const TELEGRAM_REMOVAL_REACTION_EMOJIS = ["👎", "👻", "💔", "💩"] as const;
+export const TELEGRAM_PRIORITY_REACTION_EMOJIS = [
+  "👍",
+  "⚡",
+  "❤",
+  "🕊",
+] as const;
+export const TELEGRAM_REMOVAL_REACTION_EMOJIS = [
+  "👎",
+  "👻",
+  "💔",
+  "💩",
+] as const;
 
 export interface TelegramUpdateDeletion {
   deleted_business_messages?: { message_ids?: unknown };
@@ -66,7 +76,9 @@ function hasAddedTelegramReactionEmoji(
   newEmojis: Set<string>,
   candidates: readonly string[],
 ): boolean {
-  return candidates.some((emoji) => !oldEmojis.has(emoji) && newEmojis.has(emoji));
+  return candidates.some(
+    (emoji) => !oldEmojis.has(emoji) && newEmojis.has(emoji),
+  );
 }
 
 export function extractDeletedTelegramMessageIds(
@@ -626,7 +638,14 @@ export async function handleAuthorizedTelegramReactionUpdate<TContext>(
       deps.ctx,
     );
   }
-  if (!hasAddedTelegramReactionEmoji(oldEmojis, newEmojis, TELEGRAM_PRIORITY_REACTION_EMOJIS)) return;
+  if (
+    !hasAddedTelegramReactionEmoji(
+      oldEmojis,
+      newEmojis,
+      TELEGRAM_PRIORITY_REACTION_EMOJIS,
+    )
+  )
+    return;
   deps.prioritizeQueuedTelegramTurnByMessageId(
     reactionUpdate.message_id,
     deps.ctx,

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "private": false,
-  "description": "Better Telegram DM bridge extension for pi",
+  "description": "Better Telegram DM bridge extension for π",
   "type": "module",
   "keywords": [
     "pi-package",