@llblab/pi-telegram 0.7.1 → 0.8.0

package/lib/{attachments.ts → outbound-attachments.ts}

@@ -1,7 +1,7 @@
 /**
- * Telegram attachment domain helpers
+ * Telegram outbound attachment helpers
  * Zones: telegram outbound, pi agent tool, filesystem
- * Owns telegram_attach registration, attachment queueing, and attachment delivery so Telegram file output stays in one domain module
+ * Owns telegram_attach registration, outbound attachment queueing, and delivery so Telegram file output stays in one domain module
  */
 
 import { stat } from "node:fs/promises";
@@ -16,7 +16,7 @@ const MAX_ATTACHMENTS_PER_TURN = 10;
 
 export const TELEGRAM_OUTBOUND_ATTACHMENT_DEFAULT_MAX_BYTES = 50 * 1024 * 1024;
 
-export function getTelegramAttachmentByteLimitFromEnv(
+export function getTelegramOutboundAttachmentByteLimitFromEnv(
   env: NodeJS.ProcessEnv,
   names: string[],
   defaultValue = TELEGRAM_OUTBOUND_ATTACHMENT_DEFAULT_MAX_BYTES,
@@ -31,17 +31,17 @@ export function getTelegramAttachmentByteLimitFromEnv(
 }
 
 export const TELEGRAM_OUTBOUND_ATTACHMENT_MAX_BYTES =
-  getTelegramAttachmentByteLimitFromEnv(process.env, [
+  getTelegramOutboundAttachmentByteLimitFromEnv(process.env, [
     "PI_TELEGRAM_OUTBOUND_ATTACHMENT_MAX_BYTES",
     "TELEGRAM_MAX_ATTACHMENT_SIZE_BYTES",
   ]);
 
-export interface TelegramAttachmentToolResult {
+export interface TelegramOutboundAttachmentToolResult {
   content: Array<{ type: "text"; text: string }>;
   details: { paths: string[] };
 }
 
-export interface TelegramAttachmentRuntimeEventRecorderPort {
+export interface TelegramOutboundAttachmentRuntimeEventRecorderPort {
   recordRuntimeEvent?: (
     category: string,
     error: unknown,
@@ -49,28 +49,28 @@ export interface TelegramAttachmentRuntimeEventRecorderPort {
   ) => void;
 }
 
-export interface TelegramAttachmentToolRegistrationDeps extends TelegramAttachmentRuntimeEventRecorderPort {
+export interface TelegramOutboundAttachmentToolRegistrationDeps extends TelegramOutboundAttachmentRuntimeEventRecorderPort {
   maxAttachmentsPerTurn?: number;
   maxAttachmentSizeBytes?: number;
-  getActiveTurn: () => TelegramAttachmentQueueTargetView | undefined;
+  getActiveTurn: () => TelegramOutboundAttachmentQueueTargetView | undefined;
   statPath?: (path: string) => Promise<{ isFile(): boolean; size?: number }>;
 }
 
-export interface TelegramQueuedAttachmentView {
+export interface TelegramQueuedOutboundAttachmentView {
   path: string;
   fileName: string;
 }
 
-export interface TelegramAttachmentQueueTargetView {
-  queuedAttachments: TelegramQueuedAttachmentView[];
+export interface TelegramOutboundAttachmentQueueTargetView {
+  queuedAttachments: TelegramQueuedOutboundAttachmentView[];
 }
 
-export interface TelegramQueuedAttachmentTurnView extends TelegramAttachmentQueueTargetView {
+export interface TelegramQueuedOutboundAttachmentTurnView extends TelegramOutboundAttachmentQueueTargetView {
   chatId: number;
   replyToMessageId: number;
 }
 
-function isTelegramPhotoAttachmentPath(path: string): boolean {
+function isTelegramOutboundPhotoAttachmentPath(path: string): boolean {
   const normalized = path.toLowerCase();
   return (
     normalized.endsWith(".jpg") ||
@@ -81,7 +81,7 @@ function isTelegramPhotoAttachmentPath(path: string): boolean {
   );
 }
 
-function formatTelegramAttachmentSizeLimitError(
+function formatTelegramOutboundAttachmentSizeLimitError(
   size: number,
   maxSize: number,
   path?: string,
@@ -90,14 +90,14 @@ function formatTelegramAttachmentSizeLimitError(
   return path ? `${message}: ${path}` : message;
 }
 
-function formatTelegramAttachmentToolResultText(count: number): string {
+function formatTelegramOutboundAttachmentToolResultText(count: number): string {
   // Pi's compact tool rows need an empty first line to visually separate header and result
   return ["", `Queued ${count} Telegram attachment(s).`].join("\n");
 }
 
-export function registerTelegramAttachmentTool(
+export function registerTelegramOutboundAttachmentTool(
   pi: ExtensionAPI,
-  deps: TelegramAttachmentToolRegistrationDeps,
+  deps: TelegramOutboundAttachmentToolRegistrationDeps,
 ): void {
   const maxAttachmentsPerTurn =
     deps.maxAttachmentsPerTurn ?? MAX_ATTACHMENTS_PER_TURN;
@@ -120,7 +120,7 @@ export function registerTelegramAttachmentTool(
     }),
     async execute(_toolCallId, params) {
       try {
-        return await queueTelegramAttachments({
+        return await queueTelegramOutboundAttachments({
           activeTurn: deps.getActiveTurn(),
           paths: params.paths,
           maxAttachmentsPerTurn,
@@ -138,7 +138,7 @@ export function registerTelegramAttachmentTool(
   });
 }
 
-export interface TelegramQueuedAttachmentDeliveryDeps {
+export interface TelegramQueuedOutboundAttachmentDeliveryDeps {
   sendMultipart: (
     method: string,
     fields: Record<string, string>,
@@ -160,13 +160,13 @@ export interface TelegramQueuedAttachmentDeliveryDeps {
   maxAttachmentSizeBytes?: number;
 }
 
-export async function queueTelegramAttachments(options: {
-  activeTurn: TelegramAttachmentQueueTargetView | undefined;
+export async function queueTelegramOutboundAttachments(options: {
+  activeTurn: TelegramOutboundAttachmentQueueTargetView | undefined;
   paths: string[];
   maxAttachmentsPerTurn: number;
   maxAttachmentSizeBytes?: number;
   statPath?: (path: string) => Promise<{ isFile(): boolean; size?: number }>;
-}): Promise<TelegramAttachmentToolResult> {
+}): Promise<TelegramOutboundAttachmentToolResult> {
   if (!options.activeTurn) {
     throw new Error(
       "telegram_attach can only be used while replying to an active Telegram turn",
@@ -180,7 +180,7 @@ export async function queueTelegramAttachments(options: {
       `Attachment limit reached (${options.maxAttachmentsPerTurn})`,
     );
   }
-  const pendingAttachments: TelegramQueuedAttachmentView[] = [];
+  const pendingAttachments: TelegramQueuedOutboundAttachmentView[] = [];
   for (const inputPath of options.paths) {
     const stats = await (options.statPath ?? stat)(inputPath);
     if (!stats.isFile()) {
@@ -192,7 +192,7 @@ export async function queueTelegramAttachments(options: {
       stats.size > options.maxAttachmentSizeBytes
     ) {
       throw new Error(
-        formatTelegramAttachmentSizeLimitError(
+        formatTelegramOutboundAttachmentSizeLimitError(
           stats.size,
           options.maxAttachmentSizeBytes,
           inputPath,
@@ -210,20 +210,20 @@ export async function queueTelegramAttachments(options: {
     content: [
       {
         type: "text",
-        text: formatTelegramAttachmentToolResultText(added.length),
+        text: formatTelegramOutboundAttachmentToolResultText(added.length),
       },
     ],
     details: { paths: added },
   };
 }
 
-export function createTelegramQueuedAttachmentSender(
-  deps: TelegramQueuedAttachmentDeliveryDeps,
+export function createTelegramQueuedOutboundAttachmentSender(
+  deps: TelegramQueuedOutboundAttachmentDeliveryDeps,
 ) {
   return async function sendQueuedAttachments(
-    turn: TelegramQueuedAttachmentTurnView,
+    turn: TelegramQueuedOutboundAttachmentTurnView,
   ): Promise<void> {
-    await sendQueuedTelegramAttachments(turn, {
+    await sendQueuedTelegramOutboundAttachments(turn, {
       ...deps,
       maxAttachmentSizeBytes:
         deps.maxAttachmentSizeBytes ?? TELEGRAM_OUTBOUND_ATTACHMENT_MAX_BYTES,
@@ -231,9 +231,9 @@ export function createTelegramQueuedAttachmentSender(
   };
 }
 
-export async function sendQueuedTelegramAttachments(
-  turn: TelegramQueuedAttachmentTurnView,
-  deps: TelegramQueuedAttachmentDeliveryDeps,
+export async function sendQueuedTelegramOutboundAttachments(
+  turn: TelegramQueuedOutboundAttachmentTurnView,
+  deps: TelegramQueuedOutboundAttachmentDeliveryDeps,
 ): Promise<void> {
   for (const attachment of turn.queuedAttachments) {
     try {
@@ -241,14 +241,14 @@ export async function sendQueuedTelegramAttachments(
         const stats = await (deps.statPath ?? stat)(attachment.path);
         if (stats.size > deps.maxAttachmentSizeBytes) {
           throw new Error(
-            formatTelegramAttachmentSizeLimitError(
+            formatTelegramOutboundAttachmentSizeLimitError(
               stats.size,
               deps.maxAttachmentSizeBytes,
             ),
           );
         }
       }
-      const isPhoto = isTelegramPhotoAttachmentPath(attachment.path);
+      const isPhoto = isTelegramOutboundPhotoAttachmentPath(attachment.path);
       const method = isPhoto ? "sendPhoto" : "sendDocument";
       const fieldName = isPhoto ? "photo" : "document";
       const replyParameters = buildTelegramMultipartReplyParameters(

package/lib/outbound-handlers.ts

@@ -97,6 +97,55 @@ export interface TelegramVoiceReplySenderDeps {
   ) => void;
 }
 
+export interface TelegramOutboundTextReplyRuntimeDeps<TReplyMarkup = unknown> {
+  execCommand: TelegramVoiceReplySenderDeps["execCommand"];
+  getHandlers?: () => TelegramOutboundHandlerConfig[] | undefined;
+  sendTextReply: (
+    chatId: number,
+    replyToMessageId: number | undefined,
+    text: string,
+    options?: { parseMode?: "HTML" },
+  ) => Promise<number | undefined>;
+  sendMarkdownReply: (
+    chatId: number,
+    replyToMessageId: number | undefined,
+    markdown: string,
+    options?: { replyMarkup?: TReplyMarkup },
+  ) => Promise<number | undefined>;
+  cwd?: string;
+  recordRuntimeEvent?: TelegramVoiceReplySenderDeps["recordRuntimeEvent"];
+}
+
+export interface TelegramInlineKeyboardLike {
+  inline_keyboard: Array<Array<{ text: string; callback_data: string }>>;
+}
+
+export interface TelegramOutboundTextTransformOptions<TReplyMarkup = unknown> {
+  handlers?: TelegramOutboundHandlerConfig[];
+  cwd?: string;
+  execCommand: TelegramVoiceReplySenderDeps["execCommand"];
+  recordRuntimeEvent?: TelegramVoiceReplySenderDeps["recordRuntimeEvent"];
+  replyMarkup?: TReplyMarkup;
+}
+
+export interface TelegramOutboundTextTransformResult<TReplyMarkup = unknown> {
+  text: string;
+  replyMarkup?: TReplyMarkup;
+}
+
+export interface TelegramOutboundTextPreviewRuntimeDeps<TReplyMarkup = unknown> {
+  execCommand: TelegramVoiceReplySenderDeps["execCommand"];
+  getHandlers?: () => TelegramOutboundHandlerConfig[] | undefined;
+  finalizeMarkdownPreview: (
+    chatId: number,
+    markdown: string,
+    replyToMessageId: number,
+    options?: { replyMarkup?: TReplyMarkup },
+  ) => Promise<boolean>;
+  cwd?: string;
+  recordRuntimeEvent?: TelegramVoiceReplySenderDeps["recordRuntimeEvent"];
+}
+
 interface TelegramTopLevelHtmlComment {
   raw: string;
   content: string;
@@ -665,6 +714,202 @@ export async function generateTelegramVoiceReplyFile(
   });
 }
 
+function getOutboundTextTemplateValues(text: string): Record<string, string> {
+  return { text, type: "text" };
+}
+
+async function transformTelegramOutboundTextWithHandler(
+  text: string,
+  options: {
+    handler: TelegramOutboundHandlerConfig;
+    cwd: string;
+    execCommand: TelegramVoiceReplySenderDeps["execCommand"];
+  },
+): Promise<string> {
+  const values = getOutboundTextTemplateValues(text);
+  const steps = getTelegramVoiceHandlerCompositionSteps(options.handler);
+  if (steps.length > 0) {
+    const startedAt = Date.now();
+    let stdout = text;
+    for (const [index, step] of steps.entries()) {
+      try {
+        const result = await runVoiceReplyCommand(
+          `Outbound text template step ${index + 1}`,
+          step,
+          values,
+          {
+            cwd: options.cwd,
+            timeout: getVoiceReplyCompositionStepTimeout(
+              getVoiceReplyTimeout(options.handler),
+              step,
+              startedAt,
+            ),
+            execCommand: options.execCommand,
+            stdin: stdout,
+          },
+        );
+        stdout = result.stdout;
+      } catch (error) {
+        if (typeof step === "object" && step.critical) throw error;
+        stdout = "";
+      }
+      if (!stdout) stdout = text;
+    }
+    return stdout.trim() || text;
+  }
+  const result = await runVoiceReplyCommand(
+    "Outbound text template",
+    options.handler,
+    values,
+    {
+      cwd: options.cwd,
+      timeout: getVoiceReplyTimeout(options.handler),
+      execCommand: options.execCommand,
+      stdin: text,
+    },
+  );
+  return result.stdout.trim() || text;
+}
+
+export async function transformTelegramOutboundText(
+  text: string,
+  options: {
+    handlers?: TelegramOutboundHandlerConfig[];
+    cwd?: string;
+    execCommand: TelegramVoiceReplySenderDeps["execCommand"];
+    recordRuntimeEvent?: TelegramVoiceReplySenderDeps["recordRuntimeEvent"];
+  },
+): Promise<string> {
+  let transformed = text;
+  for (const handler of findTelegramOutboundHandlers(options.handlers, "text")) {
+    try {
+      transformed = await transformTelegramOutboundTextWithHandler(
+        transformed,
+        {
+          handler,
+          cwd: options.cwd ?? process.cwd(),
+          execCommand: options.execCommand,
+        },
+      );
+    } catch (error) {
+      options.recordRuntimeEvent?.("outbound-text-handler", error, {
+        handler: outboundHandlerMatchesType(handler, "text") ? "text" : "unknown",
+      });
+    }
+  }
+  return transformed;
+}
+
+function isTelegramInlineKeyboardLike(
+  replyMarkup: unknown,
+): replyMarkup is TelegramInlineKeyboardLike {
+  if (!replyMarkup || typeof replyMarkup !== "object") return false;
+  const keyboard = (replyMarkup as { inline_keyboard?: unknown }).inline_keyboard;
+  return Array.isArray(keyboard);
+}
+
+async function transformTelegramOutboundReplyMarkup<TReplyMarkup>(
+  replyMarkup: TReplyMarkup | undefined,
+  options: Omit<TelegramOutboundTextTransformOptions, "replyMarkup">,
+): Promise<TReplyMarkup | undefined> {
+  if (!isTelegramInlineKeyboardLike(replyMarkup)) return replyMarkup;
+  const translatedRows = [];
+  for (const row of replyMarkup.inline_keyboard) {
+    const translatedRow = [];
+    for (const button of row) {
+      const text = await transformTelegramOutboundText(button.text, options);
+      translatedRow.push({ ...button, text });
+    }
+    translatedRows.push(translatedRow);
+  }
+  return { ...replyMarkup, inline_keyboard: translatedRows } as TReplyMarkup;
+}
+
+export async function transformTelegramOutboundTextReply<TReplyMarkup = unknown>(
+  text: string,
+  options: TelegramOutboundTextTransformOptions<TReplyMarkup>,
+): Promise<TelegramOutboundTextTransformResult<TReplyMarkup>> {
+  const transformOptions = {
+    handlers: options.handlers,
+    cwd: options.cwd,
+    execCommand: options.execCommand,
+    recordRuntimeEvent: options.recordRuntimeEvent,
+  };
+  const transformedText = await transformTelegramOutboundText(
+    text,
+    transformOptions,
+  );
+  const replyMarkup = await transformTelegramOutboundReplyMarkup(
+    options.replyMarkup,
+    transformOptions,
+  );
+  return { text: transformedText, ...(replyMarkup ? { replyMarkup } : {}) };
+}
+
+export function createTelegramOutboundTextReplyRuntime<TReplyMarkup = unknown>(
+  deps: TelegramOutboundTextReplyRuntimeDeps<TReplyMarkup>,
+): Pick<
+  TelegramOutboundTextReplyRuntimeDeps<TReplyMarkup>,
+  "sendTextReply" | "sendMarkdownReply"
+> {
+  return {
+    sendTextReply: async (chatId, replyToMessageId, text, options) => {
+      const transformed = await transformTelegramOutboundText(text, {
+        handlers: deps.getHandlers?.(),
+        cwd: deps.cwd,
+        execCommand: deps.execCommand,
+        recordRuntimeEvent: deps.recordRuntimeEvent,
+      });
+      return deps.sendTextReply(chatId, replyToMessageId, transformed, options);
+    },
+    sendMarkdownReply: async (chatId, replyToMessageId, markdown, options) => {
+      const transformed = await transformTelegramOutboundTextReply(markdown, {
+        handlers: deps.getHandlers?.(),
+        cwd: deps.cwd,
+        execCommand: deps.execCommand,
+        recordRuntimeEvent: deps.recordRuntimeEvent,
+        replyMarkup: options?.replyMarkup,
+      });
+      return deps.sendMarkdownReply(chatId, replyToMessageId, transformed.text, {
+        ...options,
+        ...(transformed.replyMarkup
+          ? { replyMarkup: transformed.replyMarkup }
+          : {}),
+      });
+    },
+  };
+}
+
+export function createTelegramOutboundTextPreviewRuntime<TReplyMarkup = unknown>(
+  deps: TelegramOutboundTextPreviewRuntimeDeps<TReplyMarkup>,
+): Pick<
+  TelegramOutboundTextPreviewRuntimeDeps<TReplyMarkup>,
+  "finalizeMarkdownPreview"
+> {
+  return {
+    finalizeMarkdownPreview: async (chatId, markdown, replyToMessageId, options) => {
+      const transformed = await transformTelegramOutboundTextReply(markdown, {
+        handlers: deps.getHandlers?.(),
+        cwd: deps.cwd,
+        execCommand: deps.execCommand,
+        recordRuntimeEvent: deps.recordRuntimeEvent,
+        replyMarkup: options?.replyMarkup,
+      });
+      return deps.finalizeMarkdownPreview(
+        chatId,
+        transformed.text,
+        replyToMessageId,
+        {
+          ...options,
+          ...(transformed.replyMarkup
+            ? { replyMarkup: transformed.replyMarkup }
+            : {}),
+        },
+      );
+    },
+  };
+}
+
 export interface TelegramOutboundReplyPlan<TReplyMarkup = unknown> {
   markdown: string;
   replyMarkup?: TReplyMarkup;

package/lib/prompts.ts

@@ -14,7 +14,7 @@ Telegram bridge extension is active.
 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.
+- \`[attachments]\` gives a base directory plus relative local files; resolve and read them as needed. \`[outputs]\` contains inbound-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:

package/lib/routing.ts

@@ -7,13 +7,14 @@
 import * as OutboundHandlers from "./outbound-handlers.ts";
 import * as Commands from "./commands.ts";
 import type { TelegramConfigStore } from "./config.ts";
-import type { TelegramAttachmentHandlerRuntime } from "./attachment-handlers.ts";
+import type { TelegramInboundHandlerRuntime } from "./inbound-handlers.ts";
 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 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>;
@@ -58,7 +60,7 @@ export interface TelegramInboundRouteRuntimeDeps<
     ctx: TContext,
   ) => Promise<boolean>;
   buttonActionStore?: OutboundHandlers.TelegramButtonActionStore;
-  attachmentHandlerRuntime: TelegramAttachmentHandlerRuntime<TContext>;
+  inboundHandlerRuntime: TelegramInboundHandlerRuntime<TContext>;
   updateStatus: (ctx: TContext, error?: string) => void;
   dispatchNextQueuedTelegramTurn: (ctx: TContext) => void;
   answerCallbackQuery: (
@@ -203,7 +205,7 @@ export function createTelegramInboundRouteRuntime<
   >({
     allocateQueueOrder: deps.bridgeRuntime.queue.allocateItemOrder,
     downloadFile: deps.downloadFile,
-    processAttachments: deps.attachmentHandlerRuntime.process,
+    processAttachments: deps.inboundHandlerRuntime.process,
   });
   const enqueueContinueTurn = async (
     message: TMessage,
@@ -321,6 +323,14 @@ export function createTelegramInboundRouteRuntime<
     mediaGroups: deps.mediaGroupRuntime,
     dispatchMessages: commandOrPrompt.dispatchMessages,
   });
+  const textDispatch = TextGroups.createTelegramTextGroupDispatchRuntime<
+    TMessage,
+    TContext
+  >({
+    textGroups: deps.textGroupRuntime,
+    dispatchMessages: commandOrPrompt.dispatchMessages,
+    dispatchSingleMessage: mediaDispatch.handleMessage,
+  });
   const editRuntime = Turns.createTelegramQueuedPromptEditRuntime<
     TMessage,
     TContext
@@ -343,7 +353,7 @@ export function createTelegramInboundRouteRuntime<
     answerCallbackQuery: deps.answerCallbackQuery,
     handleAuthorizedTelegramCallbackQuery: callbackHandler,
     sendTextReply: deps.sendTextReply,
-    handleAuthorizedTelegramMessage: mediaDispatch.handleMessage,
+    handleAuthorizedTelegramMessage: textDispatch.handleMessage,
     handleAuthorizedTelegramEditedMessage: editRuntime.updateFromEditedMessage,
   });
 }