@llblab/pi-telegram 0.7.0 → 0.7.1

package/AGENTS.md

@@ -133,7 +133,8 @@ The canonical detailed ownership map lives in [`docs/architecture.md`](./docs/ar
 - 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`
 - 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,11 @@
 # Changelog
 
+## 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

@@ -84,7 +84,7 @@ Use these inside the Telegram DM with your bot:
 - **`/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.
 
@@ -190,7 +190,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

@@ -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
 
@@ -160,7 +160,7 @@ Telegram prompt responses use explicit delivery context to attach outbound text,
 
 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:`.
+- 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

@@ -297,6 +297,7 @@ export default function (pi: Pi.ExtensionAPI) {
     getThinkingLevel,
     setThinkingLevel,
     setModel,
+    sendUserMessage,
     isIdle,
     hasPendingMessages,
     compact,

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>[],

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

@@ -71,11 +71,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 +92,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 +185,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 +234,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(),

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/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.1",
   "private": false,
-  "description": "Better Telegram DM bridge extension for pi",
+  "description": "Better Telegram DM bridge extension for π",
   "type": "module",
   "keywords": [
     "pi-package",