@llblab/pi-telegram 0.7.2 → 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,7 +7,7 @@
 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";
@@ -60,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: (
@@ -205,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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "private": false,
   "description": "Better Telegram DM bridge extension for π",
   "type": "module",

package/docs/attachment-handlers.md

@@ -1,50 +0,0 @@
-# Attachment Handlers
-
-`pi-telegram` can run ordered inbound attachment handlers after downloading files and before the Telegram turn enters the π queue.
-
-This document is the local adaptation of the portable [Command Template Standard](./command-templates.md).
-
-## Config Shape
-
-`telegram.json` may define `attachmentHandlers`:
-
-```json
-{
-  "attachmentHandlers": [
-    {
-      "type": "voice",
-      "template": "/path/to/stt1 --file {file} --lang {lang=ru}"
-    },
-    {
-      "mime": "audio/*",
-      "template": "/path/to/stt2 --file {file} --lang {lang=ru}"
-    }
-  ]
-}
-```
-
-Handlers match by `type`, `mime`, or `match`. Wildcards such as `audio/*` are accepted. Each matching handler must provide `template`; a string is one command, and an array is ordered composition. Top-level `args` and `defaults` apply to composed steps unless a step defines private values. The command-template default timeout applies automatically. Legacy configs may still use `pipe` as a local alias.
-
-## Template Placeholders
-
-Attachment handlers support these built-in placeholders:
-
-| Placeholder | Value                                                            |
-| ----------- | ---------------------------------------------------------------- |
-| `{file}`    | Full local path to the downloaded file                           |
-| `{mime}`    | MIME type if known                                               |
-| `{type}`    | Attachment kind such as `voice`, `audio`, `document`, or `photo` |
-
-`defaults` may provide additional placeholder values such as `{lang}` or `{model}`. `args` is only a string-array declaration of supported placeholders; defaults belong in `defaults` or inline placeholders such as `{lang=ru}`. Examples prefer explicit flag-style CLIs for readability, but positional forms such as `/path/to/stt {file} {lang=ru} {model=voxtral-mini-latest}` are equally valid when the target script supports them.
-
-If a top-level one-step handler template has no `{file}` placeholder, the downloaded file path is appended as the last command arg as a one-step handler convenience. Composition steps are plain command templates and do not receive implicit file-path args; include `{file}` explicitly where needed.
-
-## Ordered Fallbacks
-
-A handler list is ordered. For each attachment, matching handlers run in list order and stop after the first successful handler. A composed handler counts as one handler for fallback purposes: if any step fails, the next matching handler is tried.
-
-If a matching handler fails with a non-zero exit code, the runtime records diagnostics and tries the next matching handler. If every matching handler fails, the attachment remains visible in the prompt as a normal local file reference.
-
-## Prompt Output
-
-Local attachments stay in the prompt under `[attachments] <directory>` with relative file entries. Successful handler stdout is added under `[outputs]`. For composed handlers, each step receives the previous step's stdout on stdin by default, and stdout from the last successful step is used as the handler output. Empty output and failed handler output are omitted from the prompt text.