@llblab/pi-telegram 0.6.2 → 0.7.0

package/lib/prompt-templates.ts

@@ -0,0 +1,150 @@
+/**
+ * π prompt-template bridge helpers
+ * Zones: pi agent prompts, telegram controls, filesystem
+ * Discovers π prompt-template slash commands and expands them before Telegram queue dispatch
+ */
+
+import { readFileSync } from "node:fs";
+import type { PiSlashCommandInfo } from "./pi.ts";
+
+export interface TelegramPromptTemplateCommand {
+  command: string;
+  description?: string;
+  path: string;
+}
+
+export type TelegramPromptTemplateReader = (path: string) => string;
+
+const TELEGRAM_BOT_COMMAND_NAME_PATTERN = /^[a-z0-9_]{1,32}$/;
+
+function stripPromptTemplateFrontmatter(content: string): string {
+  if (!content.startsWith("---")) return content;
+  const lines = content.split("\n");
+  if (lines[0]?.trim() !== "---") return content;
+  for (let index = 1; index < lines.length; index += 1) {
+    if (lines[index]?.trim() === "---")
+      return lines.slice(index + 1).join("\n");
+  }
+  return content;
+}
+
+export function parsePromptTemplateArgs(argsString: string): string[] {
+  const args: string[] = [];
+  let current = "";
+  let quote: string | undefined;
+  for (const char of argsString) {
+    if (quote) {
+      if (char === quote) {
+        quote = undefined;
+      } else {
+        current += char;
+      }
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (char === " " || char === "\t") {
+      if (current) args.push(current);
+      current = "";
+      continue;
+    }
+    current += char;
+  }
+  if (current) args.push(current);
+  return args;
+}
+
+export function substitutePromptTemplateArgs(
+  content: string,
+  args: readonly string[],
+): string {
+  let result = content.replace(/\$(\d+)/g, (_, num: string) => {
+    const index = Number.parseInt(num, 10) - 1;
+    return args[index] ?? "";
+  });
+  result = result.replace(
+    /\$\{@:(\d+)(?::(\d+))?\}/g,
+    (_, startValue: string, lengthValue: string | undefined) => {
+      const start = Math.max(Number.parseInt(startValue, 10) - 1, 0);
+      if (lengthValue) {
+        const length = Number.parseInt(lengthValue, 10);
+        return args.slice(start, start + length).join(" ");
+      }
+      return args.slice(start).join(" ");
+    },
+  );
+  const allArgs = args.join(" ");
+  return result.replace(/\$ARGUMENTS/g, allArgs).replace(/\$@/g, allArgs);
+}
+
+export function isTelegramPromptTemplateCommandName(name: string): boolean {
+  return TELEGRAM_BOT_COMMAND_NAME_PATTERN.test(name);
+}
+
+export function mapPiPromptTemplateNameToTelegramCommandName(
+  name: string,
+): string | undefined {
+  const command = name
+    .toLowerCase()
+    .replace(/[^a-z0-9_]+/g, "_")
+    .replace(/_+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .slice(0, 32)
+    .replace(/_+$/g, "");
+  return isTelegramPromptTemplateCommandName(command) ? command : undefined;
+}
+
+export interface TelegramPromptTemplateCommandGetterDeps {
+  getCommands: () => readonly PiSlashCommandInfo[];
+  reservedCommandNames?: readonly string[];
+}
+
+export function getTelegramPromptTemplateCommands(
+  commands: readonly PiSlashCommandInfo[],
+  reservedNames: ReadonlySet<string> = new Set(),
+): TelegramPromptTemplateCommand[] {
+  const seen = new Set<string>();
+  const promptCommands: TelegramPromptTemplateCommand[] = [];
+  for (const command of commands) {
+    if (command.source !== "prompt") continue;
+    const telegramCommand = mapPiPromptTemplateNameToTelegramCommandName(
+      command.name,
+    );
+    if (!telegramCommand) continue;
+    if (reservedNames.has(telegramCommand)) continue;
+    if (seen.has(telegramCommand)) continue;
+    seen.add(telegramCommand);
+    promptCommands.push({
+      command: telegramCommand,
+      description: command.description,
+      path: command.sourceInfo.path,
+    });
+  }
+  return promptCommands.sort((a, b) => a.command.localeCompare(b.command));
+}
+
+export function createTelegramPromptTemplateCommandGetter(
+  deps: TelegramPromptTemplateCommandGetterDeps,
+): () => TelegramPromptTemplateCommand[] {
+  const reservedNames = new Set(deps.reservedCommandNames);
+  return function getPromptTemplateCommands() {
+    return getTelegramPromptTemplateCommands(deps.getCommands(), reservedNames);
+  };
+}
+
+export function expandTelegramPromptTemplateCommand(
+  commandName: string,
+  args: string,
+  commands: readonly TelegramPromptTemplateCommand[],
+  readTemplate: TelegramPromptTemplateReader = (path) =>
+    readFileSync(path, "utf-8"),
+): string | undefined {
+  const command = commands.find(
+    (candidate) => candidate.command === commandName,
+  );
+  if (!command) return undefined;
+  const content = stripPromptTemplateFrontmatter(readTemplate(command.path));
+  return substitutePromptTemplateArgs(content, parsePromptTemplateArgs(args));
+}

package/lib/prompts.ts

@@ -1,5 +1,6 @@
 /**
  * Telegram prompt injection helpers
+ * Zones: pi agent prompts, telegram guidance
  * Owns Telegram-specific system prompt suffixes injected into pi agent turns
  */
 
@@ -9,15 +10,22 @@ import { TELEGRAM_PREFIX } from "./turns.ts";
 const SYSTEM_PROMPT_SUFFIX = `
 
 Telegram bridge extension is active.
-- Messages forwarded from Telegram are prefixed with "[telegram]".
-- [telegram] messages may include [attachments] sections with a base directory plus relative local file entries. Resolve and read those files as needed.
-- [telegram] messages may include a [reply] block after the user's current text. Treat [reply] as quoted context from the Telegram message the user replied to, not as a new instruction by itself; use it to resolve references like "this", "it", or "that message". The actual new user instruction is the message text before [reply], unless it explicitly asks you to act on the quoted context.
-- Telegram is often read on narrow phone screens, so prefer narrow table columns when presenting tabular data; wide monospace tables can become unreadable.
-- If a [telegram] user asked for a file or generated artifact, use telegram_attach with the local path instead of only mentioning the path in text.
-- Do not assume mentioning a local file path in plain text will send it to Telegram. Use telegram_attach.
-- For Telegram-native outbound actions, use hidden top-level Markdown comments instead of agent-side tool calls: write a normal answer plus correctly formatted column-zero \`telegram_voice\` or \`telegram_button\` blocks outside code, quotes, and lists. The bridge handles delivery after \`agent_end\`, so do not call or register transport/TTS/text-to-OGG tools for these actions.
-- A \`telegram_voice\` block body is the text to synthesize through the extension's configured outbound-handler pipeline. It may be a short companion summary when useful, but no specific summary format is required. Keep it TTS-friendly; avoid raw Markdown, code, formulas, tables, or long lists.
-- Button blocks should contain quick reply prompts the user can tap; use independent blocks like \`<!-- telegram_button label="OK"\nPrompt text\n-->\`, or \`<!-- telegram_button label="OK" -->\` when the prompt should equal the label. The callback prompt is routed back as a normal Telegram turn.`;
+
+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.
+
+Telegram-visible output:
+- Telegram is often phone-width; prefer narrow table columns because wide monospace tables can become unreadable.
+- For requested/generated files, call tool \`telegram_attach(local_path)\`; mentioning a local path in text does not send it.
+
+Native outbound actions:
+- Use top-level column-zero hidden Markdown comments outside code, quotes, and lists; the bridge handles them after agent_end, so do not call or register transport/TTS/text-to-OGG tools.
+- \`telegram_voice\`: text is synthesized through the configured outbound-handler pipeline. Use body text for multiline voice, \`<!-- telegram_voice text="Short summary" -->\` for explicit one-line voice, or \`<!-- telegram_voice: Short summary -->\` for one-line voice with no attributes. A companion summary is optional, no specific summary format is required. Keep it TTS-friendly; avoid raw Markdown, code, formulas, tables, or long lists.
+- \`telegram_button\`: callback prompt is routed back as a normal Telegram turn. Use \`<!-- telegram_button: OK -->\` when prompt equals label, \`<!-- telegram_button label=Continue prompt="Continue with the current plan." -->\` for one-line prompts, or body form \`<!-- telegram_button label="Show risks"\nList the main risks first.\n-->\` for multiline prompts.
+- If only hidden action comments would remain, add visible parent text like "Choose one:".
+`;
 
 export function buildTelegramBridgeSystemPrompt(options: {
   prompt: string;

package/lib/queue.ts

@@ -1,6 +1,7 @@
 /**
- * Telegram queue and queue-runtime domain helpers
- * Owns queue items, queue mutations, dispatch and lifecycle planning, session resets, and queue-adjacent runtime helpers
+ * Telegram queue core contracts and pure planning helpers
+ * Zones: telegram queue, pi agent lifecycle, scheduling
+ * Owns queue item contracts, lane admission, pure queue mutations, and dispatch planning
  */
 
 // --- Queue Items ---
@@ -178,6 +179,14 @@ export function createTelegramQueueStore<TContext = unknown>(
   };
 }
 
+export function createTelegramQueueItemCountGetter<TContext = unknown>(
+  store: Pick<TelegramQueueStore<TContext>, "getQueuedItems">,
+): () => number {
+  return function getTelegramQueueItemCount() {
+    return store.getQueuedItems().length;
+  };
+}
+
 export function createTelegramActiveTurnStore<
   TTurn extends PendingTelegramTurn = PendingTelegramTurn,
 >(): TelegramActiveTurnStore<TTurn> {
@@ -344,7 +353,7 @@ function formatTelegramQueueItemStatusSummary<TContext = unknown>(
   item: TelegramQueueItem<TContext>,
 ): string {
   if (item.queueLane === "priority") {
-    return `⬆ ${item.statusSummary}`;
+    return `⚡ ${item.statusSummary}`;
   }
   return item.statusSummary;
 }
@@ -665,18 +674,32 @@ export type TelegramAgentLifecycleHooksRuntimeDeps<
   TTurn extends PendingTelegramTurn,
   TContext,
   TMessage,
+  TReplyMarkup = unknown,
 > = TelegramAgentStartHookRuntimeDeps<TTurn, TContext> &
-  TelegramAgentEndHookRuntimeDeps<TTurn, TContext, TMessage> &
+  TelegramAgentEndHookRuntimeDeps<TTurn, TContext, TMessage, TReplyMarkup> &
   TelegramToolExecutionHookRuntimeDeps<TContext>;
 
 export function createTelegramAgentLifecycleHooks<
   TTurn extends PendingTelegramTurn,
   TContext,
   TMessage,
->(deps: TelegramAgentLifecycleHooksRuntimeDeps<TTurn, TContext, TMessage>) {
+  TReplyMarkup = unknown,
+>(
+  deps: TelegramAgentLifecycleHooksRuntimeDeps<
+    TTurn,
+    TContext,
+    TMessage,
+    TReplyMarkup
+  >,
+) {
   return {
     onAgentStart: createTelegramAgentStartHook<TTurn, TContext>(deps),
-    onAgentEnd: createTelegramAgentEndHook<TTurn, TContext, TMessage>(deps),
+    onAgentEnd: createTelegramAgentEndHook<
+      TTurn,
+      TContext,
+      TMessage,
+      TReplyMarkup
+    >(deps),
     ...createTelegramToolExecutionHooks<TContext>(deps),
   };
 }
@@ -737,6 +760,7 @@ export interface TelegramAgentEndOutboundReplyPlan<TReplyMarkup = unknown> {
 
 export interface TelegramAgentEndRuntimeDeps<
   TTurn extends PendingTelegramTurn,
+  TReplyMarkup = unknown,
 > {
   turn: TTurn | undefined;
   assistant: TelegramAgentEndAssistantResult;
@@ -750,13 +774,13 @@ export interface TelegramAgentEndRuntimeDeps<
     chatId: number,
     markdown: string,
     replyToMessageId: number,
-    options?: { replyMarkup?: unknown },
+    options?: { replyMarkup?: TReplyMarkup },
   ) => Promise<boolean>;
   sendMarkdownReply: (
     chatId: number,
     replyToMessageId: number,
     markdown: string,
-    options?: { replyMarkup?: unknown },
+    options?: { replyMarkup?: TReplyMarkup },
   ) => Promise<unknown>;
   sendTextReply: (
     chatId: number,
@@ -764,7 +788,9 @@ export interface TelegramAgentEndRuntimeDeps<
     text: string,
   ) => Promise<unknown>;
   sendQueuedAttachments: (turn: TTurn) => Promise<void>;
-  planOutboundReply?: (markdown: string) => TelegramAgentEndOutboundReplyPlan;
+  planOutboundReply?: (
+    markdown: string,
+  ) => TelegramAgentEndOutboundReplyPlan<TReplyMarkup>;
   sendOutboundReplyArtifacts?: (
     turn: TTurn,
     plan: TelegramAgentEndOutboundReplyPlan,
@@ -776,6 +802,7 @@ export interface TelegramAgentEndHookRuntimeDeps<
   TTurn extends PendingTelegramTurn,
   TContext,
   TMessage,
+  TReplyMarkup = unknown,
 > {
   getActiveTurn: () => TTurn | undefined;
   extractAssistant: (
@@ -790,11 +817,11 @@ export interface TelegramAgentEndHookRuntimeDeps<
   ) => void;
   clearPreview: (chatId: number) => Promise<void>;
   setPreviewPendingText: (text: string) => void;
-  finalizeMarkdownPreview: TelegramAgentEndRuntimeDeps<TTurn>["finalizeMarkdownPreview"];
-  sendMarkdownReply: TelegramAgentEndRuntimeDeps<TTurn>["sendMarkdownReply"];
+  finalizeMarkdownPreview: TelegramAgentEndRuntimeDeps<TTurn, TReplyMarkup>["finalizeMarkdownPreview"];
+  sendMarkdownReply: TelegramAgentEndRuntimeDeps<TTurn, TReplyMarkup>["sendMarkdownReply"];
   sendTextReply: TelegramAgentEndRuntimeDeps<TTurn>["sendTextReply"];
   sendQueuedAttachments: (turn: TTurn) => Promise<void>;
-  planOutboundReply?: TelegramAgentEndRuntimeDeps<TTurn>["planOutboundReply"];
+  planOutboundReply?: TelegramAgentEndRuntimeDeps<TTurn, TReplyMarkup>["planOutboundReply"];
   sendOutboundReplyArtifacts?: TelegramAgentEndRuntimeDeps<TTurn>["sendOutboundReplyArtifacts"];
 }
 
@@ -872,7 +899,15 @@ export function createTelegramAgentEndHook<
   TTurn extends PendingTelegramTurn,
   TContext,
   TMessage,
->(deps: TelegramAgentEndHookRuntimeDeps<TTurn, TContext, TMessage>) {
+  TReplyMarkup = unknown,
+>(
+  deps: TelegramAgentEndHookRuntimeDeps<
+    TTurn,
+    TContext,
+    TMessage,
+    TReplyMarkup
+  >,
+) {
   return async function onAgentEnd(
     event: TelegramAgentEndHookEvent<TMessage>,
     ctx: TContext,
@@ -903,7 +938,8 @@ export function createTelegramAgentEndHook<
 
 export async function handleTelegramAgentEndRuntime<
   TTurn extends PendingTelegramTurn,
->(deps: TelegramAgentEndRuntimeDeps<TTurn>): Promise<void> {
+  TReplyMarkup = unknown,
+>(deps: TelegramAgentEndRuntimeDeps<TTurn, TReplyMarkup>): Promise<void> {
   const { turn, assistant } = deps;
   const rawFinalText = assistant.text;
   const outboundReply = rawFinalText
@@ -934,7 +970,7 @@ export async function handleTelegramAgentEndRuntime<
       turn.chatId,
       turn.replyToMessageId,
       assistant.errorMessage ||
-        "Telegram bridge: pi failed while processing the request.",
+        "Telegram bridge: π failed while processing the request.",
     );
     if (endPlan.shouldDispatchNext) deps.dispatchNextQueuedTelegramTurn();
     return;

package/lib/rendering.ts

@@ -1,5 +1,6 @@
 /**
  * Telegram preview and markdown rendering helpers
+ * Zones: telegram rendering, shared text utils
  * Converts assistant output into Telegram-safe plain text and HTML chunks with chunk-boundary handling
  */
 

package/lib/replies.ts

@@ -1,5 +1,6 @@
 /**
  * Telegram reply delivery helpers
+ * Zones: telegram outbound, rendering transport
  * Owns rendered-message delivery, reply transport wiring, and plain or markdown final replies
  */
 
@@ -10,10 +11,48 @@ import {
   type TelegramRenderMode,
 } from "./rendering.ts";
 
+// --- Reply Dedup ---
+
+/** Non-persistent reply deduplication for a single agent turn.
+ *  First reply to a prompt gets `reply_parameters.reply_to_message_id`;
+ *  subsequent replies in the same turn skip it to avoid stacking
+ *  duplicate reply headers in the chat viewport. */
+export interface ReplyDedupRuntime {
+  /** Returns true if this is the first reply for the given prompt
+   *  message id in the current turn. Side-effect: marks it replied. */
+  shouldReply(promptMessageId: number): boolean;
+  /** Reset the tracker when a new prompt enters the queue. */
+  reset(): void;
+}
+
+export function createReplyDedupRuntime(): ReplyDedupRuntime {
+  const replied = new Map<number, boolean>();
+  return {
+    shouldReply(promptMessageId: number): boolean {
+      if (replied.has(promptMessageId)) return false;
+      replied.set(promptMessageId, true);
+      return true;
+    },
+    reset(): void {
+      replied.clear();
+    },
+  };
+}
+
+// --- Transport-level dedup ---
+
+let lastRepliedToMessageId: number | undefined;
+
+export function resetTransportReplyDedup(): void {
+  lastRepliedToMessageId = undefined;
+}
+
 export function buildTelegramReplyParameters(
   messageId: number | undefined,
 ): TelegramReplyParameters | undefined {
   if (messageId === undefined) return undefined;
+  if (messageId === lastRepliedToMessageId) return undefined;
+  lastRepliedToMessageId = messageId;
   return { message_id: messageId, allow_sending_without_reply: true };
 }
 
@@ -219,13 +258,13 @@ export interface TelegramRenderedMessageRuntimeDeps<TReplyMarkup> {
 export interface TelegramRenderedMessageRuntime<TReplyMarkup> {
   sendTextReply: (
     chatId: number,
-    replyToMessageId: number,
+    replyToMessageId: number | undefined,
     text: string,
     options?: { parseMode?: "HTML" },
   ) => Promise<number | undefined>;
   sendMarkdownReply: (
     chatId: number,
-    replyToMessageId: number,
+    replyToMessageId: number | undefined,
     markdown: string,
     options?: { replyMarkup?: unknown },
   ) => Promise<number | undefined>;
@@ -332,3 +371,48 @@ export function createTelegramRenderedMessageRuntime<TReplyMarkup>(
     },
   };
 }
+
+// --- Dedup-wrapped Reply Wrappers ---
+
+/** Wrap a sendTextReply with reply dedup so only the first message
+ *  in a turn carries `reply_to_message_id`. */
+export function dedupSendTextReply(
+  dedup: ReplyDedupRuntime,
+  inner: (
+    chatId: number,
+    replyToMessageId: number | undefined,
+    text: string,
+    options?: { parseMode?: "HTML" },
+  ) => Promise<number | undefined>,
+): (
+  chatId: number,
+  replyToMessageId: number,
+  text: string,
+  options?: { parseMode?: "HTML" },
+) => Promise<number | undefined> {
+  return async (chatId, replyToMessageId, text, options) => {
+    const effectiveReplyTo = dedup.shouldReply(replyToMessageId) ? replyToMessageId : undefined;
+    return inner(chatId, effectiveReplyTo, text, options);
+  };
+}
+
+/** Wrap a sendMarkdownReply with reply dedup. */
+export function dedupSendMarkdownReply<TReplyMarkup = unknown>(
+  dedup: ReplyDedupRuntime,
+  inner: (
+    chatId: number,
+    replyToMessageId: number | undefined,
+    markdown: string,
+    options?: { replyMarkup?: TReplyMarkup },
+  ) => Promise<number | undefined>,
+): (
+  chatId: number,
+  replyToMessageId: number,
+  markdown: string,
+  options?: { replyMarkup?: TReplyMarkup },
+) => Promise<number | undefined> {
+  return async (chatId, replyToMessageId, markdown, options) => {
+    const effectiveReplyTo = dedup.shouldReply(replyToMessageId) ? replyToMessageId : undefined;
+    return inner(chatId, effectiveReplyTo, markdown, options);
+  };
+}

package/lib/routing.ts

@@ -1,5 +1,6 @@
 /**
  * Telegram inbound routing composition
+ * Zones: telegram inbound, orchestration, queue/menu/command composition
  * Wires authorized updates into menus, commands, media grouping, and prompt queueing
  */
 
@@ -11,6 +12,7 @@ import * as Media from "./media.ts";
 import * as Menu from "./menu.ts";
 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 Turns from "./turns.ts";
 import * as Updates from "./updates.ts";
@@ -25,11 +27,6 @@ export type TelegramRoutedCallbackQuery = Updates.TelegramCallbackQuery &
   Menu.MenuCallbackQuery;
 
 export interface TelegramInboundRouteRuntimeDeps<
-  TUpdate extends Updates.TelegramUpdateFlow & {
-    message?: TMessage;
-    edited_message?: TMessage;
-    callback_query?: TCallbackQuery;
-  },
   TMessage extends TelegramRoutedMessage,
   TCallbackQuery extends TelegramRoutedCallbackQuery,
   TContext,
@@ -51,6 +48,15 @@ export interface TelegramInboundRouteRuntimeDeps<
     Model.ScopedTelegramModel<TModel>
   >;
   menuActions: Menu.TelegramMenuActionRuntime<TContext, TModel>;
+  openQueueMenu: (
+    chatId: number,
+    replyToMessageId: number,
+    ctx: TContext,
+  ) => Promise<void>;
+  queueMenuCallbackHandler: (
+    query: TCallbackQuery,
+    ctx: TContext,
+  ) => Promise<boolean>;
   buttonActionStore?: OutboundHandlers.TelegramButtonActionStore;
   attachmentHandlerRuntime: TelegramAttachmentHandlerRuntime<TContext>;
   updateStatus: (ctx: TContext, error?: string) => void;
@@ -65,6 +71,7 @@ export interface TelegramInboundRouteRuntimeDeps<
     text: string,
   ) => Promise<number | undefined>;
   setMyCommands: Commands.TelegramBotCommandRegistrationDeps["setMyCommands"];
+  getCommands: () => Parameters<typeof PromptTemplates.getTelegramPromptTemplateCommands>[0];
   downloadFile: Media.DownloadTelegramMessageFilesDeps["downloadFile"];
   getThinkingLevel: () => Model.ThinkingLevel;
   setThinkingLevel: (level: Model.ThinkingLevel) => void;
@@ -94,7 +101,6 @@ export function createTelegramInboundRouteRuntime<
   TModel extends Model.MenuModel,
 >(
   deps: TelegramInboundRouteRuntimeDeps<
-    TUpdate,
     TMessage,
     TCallbackQuery,
     TContext,
@@ -159,8 +165,53 @@ export function createTelegramInboundRouteRuntime<
       );
       if (handled) return;
     }
+    const handledByQueue = await deps.queueMenuCallbackHandler(query, ctx);
+    if (handledByQueue) return;
     await menuCallbackHandler(query, ctx);
   };
+  const promptTurnBuilder = Turns.createTelegramPromptTurnRuntimeBuilder<
+    TMessage,
+    TContext
+  >({
+    allocateQueueOrder: deps.bridgeRuntime.queue.allocateItemOrder,
+    downloadFile: deps.downloadFile,
+    processAttachments: deps.attachmentHandlerRuntime.process,
+  });
+  const enqueueContinueTurn = async (
+    message: TMessage,
+    ctx: TContext,
+  ): Promise<void> => {
+    const enqueuePlan = Queue.planTelegramPromptEnqueue(
+      deps.telegramQueueStore.getQueuedItems(),
+      deps.bridgeRuntime.lifecycle.shouldPreserveQueuedTurnsAsHistory(),
+    );
+    deps.bridgeRuntime.lifecycle.setPreserveQueuedTurnsAsHistory(false);
+    const continueMessage = {
+      ...message,
+      text: "continue",
+      caption: undefined,
+    } as TMessage;
+    const turn = await promptTurnBuilder(
+      [continueMessage],
+      enqueuePlan.historyTurns,
+      ctx,
+    );
+    const continueTurn = {
+      ...turn,
+      queueLane: "priority" as const,
+      laneOrder: Number.MIN_SAFE_INTEGER + turn.queueOrder,
+      statusSummary: "continue",
+    };
+    deps.telegramQueueStore.setQueuedItems(enqueuePlan.remainingItems);
+    deps.queueMutationRuntime.append(continueTurn, ctx);
+    deps.dispatchNextQueuedTelegramTurn(ctx);
+  };
+  const reservedCommandNames = new Set(Commands.TELEGRAM_RESERVED_COMMAND_NAMES);
+  const getPromptTemplateCommands = () =>
+    PromptTemplates.getTelegramPromptTemplateCommands(
+      deps.getCommands(),
+      reservedCommandNames,
+    );
   const commandHandler = Commands.createTelegramCommandHandlerTargetRuntime<
     TMessage,
     TContext
@@ -181,15 +232,25 @@ export function createTelegramInboundRouteRuntime<
       deps.bridgeRuntime.lifecycle.setCompactionInProgress,
     updateStatus: deps.updateStatus,
     dispatchNextQueuedTelegramTurn: deps.dispatchNextQueuedTelegramTurn,
+    enqueueContinueTurn,
     compact: deps.compact,
     allocateItemOrder: deps.bridgeRuntime.queue.allocateItemOrder,
     allocateControlOrder: deps.bridgeRuntime.queue.allocateControlOrder,
     appendControlItem: deps.queueMutationRuntime.append,
     showStatus: deps.menuActions.sendStatusMessage,
     openModelMenu: deps.menuActions.openModelMenu,
+    openThinkingMenu: (message, ctx) => {
+      const chatId = (message as { chat: { id: number } }).chat.id;
+      return deps.menuActions.openThinkingMenu(chatId, message.message_id, ctx);
+    },
+    openQueueMenu: (message, ctx) => {
+      const chatId = (message as { chat: { id: number } }).chat.id;
+      return deps.openQueueMenu(chatId, message.message_id, ctx);
+    },
     getAllowedUserId: deps.configStore.getAllowedUserId,
     setAllowedUserId: deps.configStore.setAllowedUserId,
     setMyCommands: deps.setMyCommands,
+    getPromptTemplateCommands,
     persistConfig: deps.configStore.persist,
     sendTextReply: deps.sendTextReply,
     recordRuntimeEvent: deps.recordRuntimeEvent,
@@ -203,14 +264,7 @@ export function createTelegramInboundRouteRuntime<
       deps.bridgeRuntime.lifecycle.shouldPreserveQueuedTurnsAsHistory,
     setPreserveQueuedTurnsAsHistory:
       deps.bridgeRuntime.lifecycle.setPreserveQueuedTurnsAsHistory,
-    createTurn: Turns.createTelegramPromptTurnRuntimeBuilder<
-      TMessage,
-      TContext
-    >({
-      allocateQueueOrder: deps.bridgeRuntime.queue.allocateItemOrder,
-      downloadFile: deps.downloadFile,
-      processAttachments: deps.attachmentHandlerRuntime.process,
-    }),
+    createTurn: promptTurnBuilder,
     updateStatus: deps.updateStatus,
     dispatchNextQueuedTelegramTurn: deps.dispatchNextQueuedTelegramTurn,
   }).enqueue;
@@ -220,6 +274,14 @@ export function createTelegramInboundRouteRuntime<
   >({
     extractRawText: Media.extractFirstTelegramMessageText,
     handleCommand: commandHandler,
+    expandPromptTemplateCommand: (commandName, args) =>
+      PromptTemplates.expandTelegramPromptTemplateCommand(
+        commandName,
+        args,
+        getPromptTemplateCommands(),
+      ),
+    replaceMessageText: (message, text) =>
+      ({ ...message, text, caption: undefined }) as TMessage,
     enqueueTurn: promptEnqueue,
   });
   const mediaDispatch = Media.createTelegramMediaGroupDispatchRuntime<

package/lib/runtime.ts

@@ -1,5 +1,6 @@
 /**
  * Telegram bridge runtime-state helpers
+ * Zones: pi agent runtime state, telegram session, shared coordination
  * Owns small session-local runtime primitives that are shared by orchestration but are not specific to queueing, rendering, polling, or Telegram transport
  */
 
@@ -350,6 +351,7 @@ export function createTelegramTypingLoopStarter<TContext>(
         } catch (error) {
           const message =
             error instanceof Error ? error.message : String(error);
+          deps.updateStatus(ctx, message);
           deps.recordRuntimeEvent?.("typing", error, {
             chatId: targetChatId,
           });

package/lib/setup.ts

@@ -1,5 +1,6 @@
 /**
  * Telegram setup prompt helpers
+ * Zones: pi agent command ui, telegram config
  * Computes token-prefill defaults and prompt mode selection for /telegram-setup
  */