@llblab/pi-telegram 0.6.3 → 0.7.1

package/lib/model.ts

@@ -1,5 +1,6 @@
 /**
  * Telegram model control domain helpers
+ * Zones: pi agent model control, telegram controls, queue continuation
  * Owns model identity, thinking levels, scoped resolution, current-model state, and in-flight model switching
  */
 

package/lib/outbound-handlers.ts

@@ -1,5 +1,6 @@
 /**
  * Telegram outbound handler helpers
+ * Zones: telegram outbound, assistant markup, command templates, callback routing
  * Owns assistant-authored outbound markup extraction, configured artifact generation, callback actions, and Telegram outbound delivery
  */
 
@@ -8,6 +9,7 @@ import { mkdir } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, join, resolve } from "node:path";
 
+import type { TelegramInlineKeyboardMarkup } from "./keyboard.ts";
 import type { PendingTelegramTurn } from "./queue.ts";
 import { buildTelegramMultipartReplyParameters } from "./replies.ts";
 import { truncateTelegramQueueSummary } from "./turns.ts";
@@ -52,6 +54,7 @@ export interface TelegramVoiceExecOptions {
   timeout?: number;
   signal?: AbortSignal;
   stdin?: string;
+  retry?: number;
 }
 
 export interface TelegramVoiceExecResult {
@@ -473,6 +476,9 @@ async function runVoiceReplyCommand(
     {
       cwd: options.cwd,
       timeout: options.timeout,
+      ...(typeof config === "object" && config.retry !== undefined
+        ? { retry: config.retry }
+        : {}),
       ...(options.stdin !== undefined ? { stdin: options.stdin } : {}),
     },
   );
@@ -597,22 +603,27 @@ async function generateTelegramVoiceReplyFileWithHandler(
     const startedAt = Date.now();
     let stdout = "";
     for (const [index, step] of steps.entries()) {
-      const result = await runVoiceReplyCommand(
-        `Outbound voice template step ${index + 1}`,
-        step,
-        values,
-        {
-          cwd: options.cwd,
-          timeout: getVoiceReplyCompositionStepTimeout(
-            options.timeout,
-            step,
-            startedAt,
-          ),
-          execCommand: options.execCommand,
-          ...(index === 0 ? {} : { stdin: stdout }),
-        },
-      );
-      stdout = result.stdout;
+      try {
+        const result = await runVoiceReplyCommand(
+          `Outbound voice template step ${index + 1}`,
+          step,
+          values,
+          {
+            cwd: options.cwd,
+            timeout: getVoiceReplyCompositionStepTimeout(
+              options.timeout,
+              step,
+              startedAt,
+            ),
+            execCommand: options.execCommand,
+            ...(index === 0 ? {} : { stdin: stdout }),
+          },
+        );
+        stdout = result.stdout;
+      } catch (error) {
+        if (typeof step === "object" && step.critical) throw error;
+        stdout = "";
+      }
     }
     return getVoiceReplyOutputPath(options.handler, values, stdout);
   }
@@ -722,9 +733,7 @@ export interface TelegramOutboundButtonStoredAction extends TelegramOutboundButt
   createdAt: number;
 }
 
-export interface TelegramOutboundButtonMarkup {
-  inline_keyboard: Array<Array<{ text: string; callback_data: string }>>;
-}
+export type TelegramOutboundButtonMarkup = TelegramInlineKeyboardMarkup;
 
 export interface TelegramButtonReplyPlan {
   markdown: string;

package/lib/pi.ts

@@ -1,5 +1,6 @@
 /**
  * pi SDK adapter boundary
+ * Zones: pi agent sdk boundary, shared adapters
  * Owns direct pi SDK imports and exposes narrow bridge-facing helpers/types for the extension composition layer
  */
 
@@ -12,6 +13,7 @@ import {
   type ExtensionContext,
   type SessionShutdownEvent,
   type SessionStartEvent,
+  type SlashCommandInfo,
   SettingsManager,
 } from "@mariozechner/pi-coding-agent";
 
@@ -24,6 +26,7 @@ export type {
   ExtensionContext,
   SessionShutdownEvent,
   SessionStartEvent,
+  SlashCommandInfo,
 };
 
 export interface PiSettingsManager {
@@ -31,9 +34,12 @@ export interface PiSettingsManager {
   getEnabledModels: () => string[] | undefined;
 }
 
+export type PiSlashCommandInfo = SlashCommandInfo;
+
 export interface PiExtensionApiRuntimePorts {
   sendUserMessage: ExtensionAPI["sendUserMessage"];
   exec: ExtensionAPI["exec"];
+  getCommands: ExtensionAPI["getCommands"];
   getThinkingLevel: ExtensionAPI["getThinkingLevel"];
   setThinkingLevel: ExtensionAPI["setThinkingLevel"];
   setModel: ExtensionAPI["setModel"];
@@ -44,6 +50,7 @@ export function createExtensionApiRuntimePorts(
     ExtensionAPI,
     | "sendUserMessage"
     | "exec"
+    | "getCommands"
     | "getThinkingLevel"
     | "setThinkingLevel"
     | "setModel"
@@ -52,6 +59,7 @@ export function createExtensionApiRuntimePorts(
   return {
     sendUserMessage: (content) => api.sendUserMessage(content),
     exec: (command, args, options) => api.exec(command, args, options),
+    getCommands: () => api.getCommands(),
     getThinkingLevel: () => api.getThinkingLevel(),
     setThinkingLevel: (level) => api.setThinkingLevel(level),
     setModel: (model) => api.setModel(model),

package/lib/polling.ts

@@ -1,5 +1,6 @@
 /**
  * Telegram polling domain helpers
+ * Zones: telegram transport, polling runtime
  * Owns polling request builders, stop conditions, and the long-poll loop runtime for Telegram updates
  */
 

package/lib/preview.ts

@@ -1,5 +1,6 @@
 /**
  * Telegram preview streaming helpers
+ * Zones: telegram outbound, streaming preview, rendering
  * Owns preview transport selection, runtime updates, and preview finalization
  */
 
@@ -44,9 +45,11 @@ export interface TelegramPreviewRuntimeState extends TelegramPreviewState {
 }
 
 export type TelegramSentPreviewMessage = TelegramSentMessage;
-export type TelegramPreviewReplyMarkup = any;
+export type TelegramPreviewReplyMarkup = unknown;
 
-export interface TelegramPreviewRuntimeDeps {
+export interface TelegramPreviewRuntimeDeps<
+  TReplyMarkup = TelegramPreviewReplyMarkup,
+> {
   getState: () => TelegramPreviewRuntimeState | undefined;
   setState: (state: TelegramPreviewRuntimeState | undefined) => void;
   clearScheduledFlush: (state: TelegramPreviewRuntimeState) => void;
@@ -78,13 +81,13 @@ export interface TelegramPreviewRuntimeDeps {
   sendRenderedChunks: (
     chatId: number,
     chunks: TelegramRenderedChunk[],
-    options?: { replyMarkup?: TelegramPreviewReplyMarkup },
+    options?: { replyMarkup?: TReplyMarkup },
   ) => Promise<number | undefined>;
   editRenderedMessage: (
     chatId: number,
     messageId: number,
     chunks: TelegramRenderedChunk[],
-    options?: { replyMarkup?: TelegramPreviewReplyMarkup },
+    options?: { replyMarkup?: TReplyMarkup },
   ) => Promise<number | undefined>;
 }
 
@@ -92,7 +95,10 @@ export interface TelegramPreviewActiveTurn {
   chatId: number;
 }
 
-export interface TelegramAssistantMessagePreviewStartDeps<TMessage> {
+export interface TelegramAssistantMessagePreviewStartDeps<
+  TMessage,
+  TReplyMarkup = TelegramPreviewReplyMarkup,
+> {
   getActiveTurn: () => TelegramPreviewActiveTurn | undefined;
   isAssistantMessage: (message: TMessage) => boolean;
   getState: () => TelegramPreviewRuntimeState | undefined;
@@ -102,6 +108,8 @@ export interface TelegramAssistantMessagePreviewStartDeps<TMessage> {
   finalizeMarkdownPreview: (
     chatId: number,
     markdown: string,
+    replyToMessageId?: number,
+    options?: { replyMarkup?: TReplyMarkup },
   ) => Promise<boolean>;
 }
 
@@ -115,9 +123,11 @@ export interface TelegramAssistantMessagePreviewUpdateDeps<TMessage> {
   schedulePreviewFlush: (chatId: number) => void;
 }
 
-export type TelegramAssistantMessagePreviewHookDeps<TMessage> =
-  TelegramAssistantMessagePreviewStartDeps<TMessage> &
-    TelegramAssistantMessagePreviewUpdateDeps<TMessage>;
+export type TelegramAssistantMessagePreviewHookDeps<
+  TMessage,
+  TReplyMarkup = TelegramPreviewReplyMarkup,
+> = TelegramAssistantMessagePreviewStartDeps<TMessage, TReplyMarkup> &
+  TelegramAssistantMessagePreviewUpdateDeps<TMessage>;
 
 export interface TelegramAssistantMessagePreviewHookEvent<TMessage> {
   message: TMessage;
@@ -132,7 +142,9 @@ export interface TelegramAssistantMessagePreviewHooks<TMessage> {
   ) => Promise<void>;
 }
 
-export interface TelegramPreviewControllerDeps {
+export interface TelegramPreviewControllerDeps<
+  TReplyMarkup = TelegramPreviewReplyMarkup,
+> {
   getDefaultReplyToMessageId?: () => number | undefined;
   maxMessageLength?: number;
   renderPreviewText?: (markdown: string) => string;
@@ -162,13 +174,13 @@ export interface TelegramPreviewControllerDeps {
     chatId: number,
     chunks: TelegramRenderedChunk[],
     replyToMessageId: number | undefined,
-    options?: { replyMarkup?: TelegramPreviewReplyMarkup },
+    options?: { replyMarkup?: TReplyMarkup },
   ) => Promise<number | undefined>;
   editRenderedMessage: (
     chatId: number,
     messageId: number,
     chunks: TelegramRenderedChunk[],
-    options?: { replyMarkup?: TelegramPreviewReplyMarkup },
+    options?: { replyMarkup?: TReplyMarkup },
   ) => Promise<number | undefined>;
   throttleMs?: number;
   maxDraftId?: number;
@@ -179,7 +191,9 @@ export interface TelegramPreviewControllerDeps {
   clearTimer?: (timer: ReturnType<typeof setTimeout>) => void;
 }
 
-export interface TelegramPreviewController {
+export interface TelegramPreviewController<
+  TReplyMarkup = TelegramPreviewReplyMarkup,
+> {
   getState: () => TelegramPreviewRuntimeState | undefined;
   setState: (state: TelegramPreviewRuntimeState | undefined) => void;
   setPendingText: (text: string) => void;
@@ -193,7 +207,7 @@ export interface TelegramPreviewController {
     chatId: number,
     markdown: string,
     replyToMessageId?: number,
-    options?: { replyMarkup?: TelegramPreviewReplyMarkup },
+    options?: { replyMarkup?: TReplyMarkup },
   ) => Promise<boolean>;
 }
 
@@ -230,27 +244,31 @@ export function createTelegramPreviewMessageTransport(
   };
 }
 
-export interface TelegramPreviewRenderedChunkTransportDeps {
+export interface TelegramPreviewRenderedChunkTransportDeps<
+  TReplyMarkup = TelegramPreviewReplyMarkup,
+> {
   sendRenderedChunks: (
     chatId: number,
     chunks: TelegramRenderedChunk[],
     options?: {
       replyToMessageId?: number;
-      replyMarkup?: TelegramPreviewReplyMarkup;
+      replyMarkup?: TReplyMarkup;
     },
   ) => Promise<number | undefined>;
   editRenderedMessage: (
     chatId: number,
     messageId: number,
     chunks: TelegramRenderedChunk[],
-    options?: { replyMarkup?: TelegramPreviewReplyMarkup },
+    options?: { replyMarkup?: TReplyMarkup },
   ) => Promise<number | undefined>;
 }
 
-export function createTelegramPreviewRenderedChunkTransport(
-  deps: TelegramPreviewRenderedChunkTransportDeps,
+export function createTelegramPreviewRenderedChunkTransport<
+  TReplyMarkup = TelegramPreviewReplyMarkup,
+>(
+  deps: TelegramPreviewRenderedChunkTransportDeps<TReplyMarkup>,
 ): Pick<
-  TelegramPreviewControllerDeps,
+  TelegramPreviewControllerDeps<TReplyMarkup>,
   "sendRenderedChunks" | "editRenderedMessage"
 > {
   return {
@@ -264,19 +282,23 @@ export function createTelegramPreviewRenderedChunkTransport(
   };
 }
 
-export type TelegramPreviewControllerRuntimeDeps = Omit<
-  TelegramPreviewControllerDeps,
+export type TelegramPreviewControllerRuntimeDeps<
+  TReplyMarkup = TelegramPreviewReplyMarkup,
+> = Omit<
+  TelegramPreviewControllerDeps<TReplyMarkup>,
   | "sendMessage"
   | "editMessageText"
   | "sendRenderedChunks"
   | "editRenderedMessage"
 > &
   TelegramPreviewMessageTransportDeps &
-  TelegramPreviewRenderedChunkTransportDeps;
+  TelegramPreviewRenderedChunkTransportDeps<TReplyMarkup>;
 
-export function createTelegramPreviewControllerRuntime(
-  deps: TelegramPreviewControllerRuntimeDeps,
-): TelegramPreviewController {
+export function createTelegramPreviewControllerRuntime<
+  TReplyMarkup = TelegramPreviewReplyMarkup,
+>(
+  deps: TelegramPreviewControllerRuntimeDeps<TReplyMarkup>,
+): TelegramPreviewController<TReplyMarkup> {
   return createTelegramPreviewController({
     getDefaultReplyToMessageId: deps.getDefaultReplyToMessageId,
     maxMessageLength: deps.maxMessageLength,
@@ -302,18 +324,25 @@ export function createTelegramPreviewControllerRuntime(
 
 export interface TelegramAssistantPreviewRuntimeDeps<
   TMessage,
-> extends TelegramPreviewControllerRuntimeDeps {
+  TReplyMarkup = TelegramPreviewReplyMarkup,
+> extends TelegramPreviewControllerRuntimeDeps<TReplyMarkup> {
   getActiveTurn: () => TelegramPreviewActiveTurn | undefined;
   isAssistantMessage: (message: TMessage) => boolean;
   getMessageText: (message: TMessage) => string;
 }
 
-export type TelegramAssistantPreviewRuntime<TMessage> =
-  TelegramPreviewController & TelegramAssistantMessagePreviewHooks<TMessage>;
+export type TelegramAssistantPreviewRuntime<
+  TMessage,
+  TReplyMarkup = TelegramPreviewReplyMarkup,
+> = TelegramPreviewController<TReplyMarkup> &
+  TelegramAssistantMessagePreviewHooks<TMessage>;
 
-export function createTelegramAssistantPreviewRuntime<TMessage>(
-  deps: TelegramAssistantPreviewRuntimeDeps<TMessage>,
-): TelegramAssistantPreviewRuntime<TMessage> {
+export function createTelegramAssistantPreviewRuntime<
+  TMessage,
+  TReplyMarkup = TelegramPreviewReplyMarkup,
+>(
+  deps: TelegramAssistantPreviewRuntimeDeps<TMessage, TReplyMarkup>,
+): TelegramAssistantPreviewRuntime<TMessage, TReplyMarkup> {
   const controller = createTelegramPreviewControllerRuntime(deps);
   return {
     ...controller,
@@ -331,9 +360,11 @@ export function createTelegramAssistantPreviewRuntime<TMessage>(
   };
 }
 
-export function createTelegramPreviewController(
-  deps: TelegramPreviewControllerDeps,
-): TelegramPreviewController {
+export function createTelegramPreviewController<
+  TReplyMarkup = TelegramPreviewReplyMarkup,
+>(
+  deps: TelegramPreviewControllerDeps<TReplyMarkup>,
+): TelegramPreviewController<TReplyMarkup> {
   let state: TelegramPreviewRuntimeState | undefined;
   const clearTimer = deps.clearTimer ?? clearTimeout;
   const setTimer =
@@ -349,7 +380,7 @@ export function createTelegramPreviewController(
   let nextDraftId = 0;
   const getRuntimeDeps = (
     replyToMessageId?: number,
-  ): TelegramPreviewRuntimeDeps => ({
+  ): TelegramPreviewRuntimeDeps<TReplyMarkup> => ({
     getState: () => state,
     setState: (nextState) => {
       state = nextState;
@@ -420,8 +451,11 @@ export function createTelegramPreviewController(
   };
 }
 
-export function createTelegramAssistantMessagePreviewHooks<TMessage>(
-  deps: TelegramAssistantMessagePreviewHookDeps<TMessage>,
+export function createTelegramAssistantMessagePreviewHooks<
+  TMessage,
+  TReplyMarkup = TelegramPreviewReplyMarkup,
+>(
+  deps: TelegramAssistantMessagePreviewHookDeps<TMessage, TReplyMarkup>,
 ): TelegramAssistantMessagePreviewHooks<TMessage> {
   return {
     onMessageStart: async (
@@ -437,9 +471,12 @@ export function createTelegramAssistantMessagePreviewHooks<TMessage>(
   };
 }
 
-export async function handleTelegramAssistantMessagePreviewStart<TMessage>(
+export async function handleTelegramAssistantMessagePreviewStart<
+  TMessage,
+  TReplyMarkup = TelegramPreviewReplyMarkup,
+>(
   message: TMessage,
-  deps: TelegramAssistantMessagePreviewStartDeps<TMessage>,
+  deps: TelegramAssistantMessagePreviewStartDeps<TMessage, TReplyMarkup>,
 ): Promise<void> {
   const turn = deps.getActiveTurn();
   if (!turn || !deps.isAssistantMessage(message)) return;
@@ -517,9 +554,11 @@ export function shouldUseTelegramDraftPreview(options: {
   );
 }
 
-export async function clearTelegramPreview(
+export async function clearTelegramPreview<
+  TReplyMarkup = TelegramPreviewReplyMarkup,
+>(
   chatId: number,
-  deps: TelegramPreviewRuntimeDeps,
+  deps: TelegramPreviewRuntimeDeps<TReplyMarkup>,
 ): Promise<void> {
   void chatId;
   const state = deps.getState();
@@ -528,10 +567,12 @@ export async function clearTelegramPreview(
   deps.setState(undefined);
 }
 
-async function performTelegramPreviewFlush(
+async function performTelegramPreviewFlush<
+  TReplyMarkup = TelegramPreviewReplyMarkup,
+>(
   chatId: number,
   state: TelegramPreviewRuntimeState,
-  deps: TelegramPreviewRuntimeDeps,
+  deps: TelegramPreviewRuntimeDeps<TReplyMarkup>,
 ): Promise<void> {
   const snapshot = buildTelegramPreviewSnapshot({
     state,
@@ -580,9 +621,11 @@ async function performTelegramPreviewFlush(
   state.lastSentStrategy = snapshot.strategy;
 }
 
-export async function flushTelegramPreview(
+export async function flushTelegramPreview<
+  TReplyMarkup = TelegramPreviewReplyMarkup,
+>(
   chatId: number,
-  deps: TelegramPreviewRuntimeDeps,
+  deps: TelegramPreviewRuntimeDeps<TReplyMarkup>,
 ): Promise<void> {
   const state = deps.getState();
   if (!state) return;
@@ -607,9 +650,11 @@ export async function flushTelegramPreview(
   }
 }
 
-export async function finalizeTelegramPreview(
+export async function finalizeTelegramPreview<
+  TReplyMarkup = TelegramPreviewReplyMarkup,
+>(
   chatId: number,
-  deps: TelegramPreviewRuntimeDeps,
+  deps: TelegramPreviewRuntimeDeps<TReplyMarkup>,
 ): Promise<boolean> {
   const state = deps.getState();
   if (!state) return false;
@@ -628,11 +673,13 @@ export async function finalizeTelegramPreview(
   return state.messageId !== undefined;
 }
 
-export async function finalizeTelegramMarkdownPreview(
+export async function finalizeTelegramMarkdownPreview<
+  TReplyMarkup = TelegramPreviewReplyMarkup,
+>(
   chatId: number,
   markdown: string,
-  deps: TelegramPreviewRuntimeDeps,
-  options?: { replyMarkup?: TelegramPreviewReplyMarkup },
+  deps: TelegramPreviewRuntimeDeps<TReplyMarkup>,
+  options?: { replyMarkup?: TReplyMarkup },
 ): Promise<boolean> {
   const state = deps.getState();
   if (!state) return false;

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
  */
 
@@ -14,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.