@llblab/pi-telegram 0.7.2 → 0.8.1

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;
@@ -601,7 +650,7 @@ async function generateTelegramVoiceReplyFileWithHandler(
   const steps = getTelegramVoiceHandlerCompositionSteps(options.handler);
   if (steps.length > 0) {
     const startedAt = Date.now();
-    let stdout = "";
+    let stdout = text;
     for (const [index, step] of steps.entries()) {
       try {
         const result = await runVoiceReplyCommand(
@@ -616,7 +665,7 @@ async function generateTelegramVoiceReplyFileWithHandler(
               startedAt,
             ),
             execCommand: options.execCommand,
-            ...(index === 0 ? {} : { stdin: stdout }),
+            stdin: stdout,
           },
         );
         stdout = result.stdout;
@@ -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/queue.ts

@@ -78,6 +78,7 @@ export interface PendingTelegramTurn extends TelegramQueueItemBase {
   queuedAttachments: QueuedAttachment[];
   content: TelegramPromptContent[];
   historyText: string;
+  priorityEmoji?: string;
 }
 
 export interface PendingTelegramControlItem<
@@ -304,6 +305,7 @@ export function clearTelegramQueuePromptPriority<TContext = unknown>(
       ...item,
       queueLane: "default" as const,
       laneOrder: item.queueOrder,
+      priorityEmoji: undefined,
     };
   });
   return { items: nextItems, changed };
@@ -313,6 +315,7 @@ export function prioritizeTelegramQueuePrompt<TContext = unknown>(
   items: TelegramQueueItem<TContext>[],
   messageId: number,
   laneOrder: number,
+  priorityEmoji = "⚡",
 ): { items: TelegramQueueItem<TContext>[]; changed: boolean } {
   let changed = false;
   const nextItems = items.map((item) => {
@@ -327,6 +330,7 @@ export function prioritizeTelegramQueuePrompt<TContext = unknown>(
       ...item,
       queueLane: "priority" as const,
       laneOrder,
+      priorityEmoji,
     };
   });
   return { items: nextItems, changed };
@@ -353,7 +357,7 @@ function formatTelegramQueueItemStatusSummary<TContext = unknown>(
   item: TelegramQueueItem<TContext>,
 ): string {
   if (item.queueLane === "priority") {
-    return `⚡ ${item.statusSummary}`;
+    return `${item.kind === "prompt" ? item.priorityEmoji ?? "⚡" : "⚡"} ${item.statusSummary}`;
   }
   return item.statusSummary;
 }
@@ -1161,7 +1165,11 @@ export interface TelegramQueueMutationController<TContext> {
   clear: (ctx: TContext) => number;
   removeByMessageIds: (messageIds: number[], ctx: TContext) => number;
   clearPriorityByMessageId: (messageId: number, ctx: TContext) => boolean;
-  prioritizeByMessageId: (messageId: number, ctx: TContext) => boolean;
+  prioritizeByMessageId: (
+    messageId: number,
+    ctx: TContext,
+    priorityEmoji?: string,
+  ) => boolean;
 }
 
 export interface TelegramControlQueueControllerDeps<TContext> {
@@ -1375,8 +1383,12 @@ export function createTelegramQueueMutationController<TContext>(
       ),
     clearPriorityByMessageId: (messageId, ctx) =>
       clearTelegramQueuePromptPriorityRuntime(messageId, buildRuntimeDeps(ctx)),
-    prioritizeByMessageId: (messageId, ctx) =>
-      prioritizeTelegramQueuePromptRuntime(messageId, buildRuntimeDeps(ctx)),
+    prioritizeByMessageId: (messageId, ctx, priorityEmoji) =>
+      prioritizeTelegramQueuePromptRuntime(
+        messageId,
+        buildRuntimeDeps(ctx),
+        priorityEmoji,
+      ),
   };
 }
 
@@ -1438,6 +1450,7 @@ export function clearTelegramQueuePromptPriorityRuntime<TContext>(
 export function prioritizeTelegramQueuePromptRuntime<TContext>(
   messageId: number,
   deps: TelegramQueueMutationRuntimeDeps<TContext>,
+  priorityEmoji?: string,
 ): boolean {
   const nextPriorityReactionOrder = deps.getNextPriorityReactionOrder?.();
   if (nextPriorityReactionOrder === undefined) return false;
@@ -1445,6 +1458,7 @@ export function prioritizeTelegramQueuePromptRuntime<TContext>(
     deps.getQueuedItems(),
     messageId,
     nextPriorityReactionOrder,
+    priorityEmoji,
   );
   if (!changed) return false;
   deps.setQueuedItems(items);

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/lib/updates.ts

@@ -26,18 +26,23 @@ export type TelegramReactionType =
   | TelegramReactionTypeEmoji
   | TelegramReactionTypeNonEmoji;
 
-export const TELEGRAM_PRIORITY_REACTION_EMOJIS = [
-  "👍",
-  "⚡",
-  "❤",
-  "🕊",
+export const TELEGRAM_PRIORITY_REACTIONS = [
+  { id: 10, name: "like", emoji: "👍" },
+  { id: 11, name: "lightning", emoji: "⚡" },
+  { id: 12, name: "heart", emoji: "❤" },
+  { id: 13, name: "dove", emoji: "🕊" },
 ] as const;
-export const TELEGRAM_REMOVAL_REACTION_EMOJIS = [
-  "👎",
-  "👻",
-  "💔",
-  "💩",
+export const TELEGRAM_REMOVAL_REACTIONS = [
+  { id: 20, name: "dislike", emoji: "👎" },
+  { id: 21, name: "ghost", emoji: "👻" },
+  { id: 22, name: "broken-heart", emoji: "💔" },
+  { id: 23, name: "poop", emoji: "💩" },
 ] as const;
+export const TELEGRAM_PRIORITY_REACTION_EMOJIS =
+  TELEGRAM_PRIORITY_REACTIONS.map((reaction) => reaction.emoji);
+export const TELEGRAM_REMOVAL_REACTION_EMOJIS = TELEGRAM_REMOVAL_REACTIONS.map(
+  (reaction) => reaction.emoji,
+);
 
 export interface TelegramUpdateDeletion {
   deleted_business_messages?: { message_ids?: unknown };
@@ -71,15 +76,22 @@ function hasAnyTelegramReactionEmoji(
   return candidates.some((emoji) => emojis.has(emoji));
 }
 
-function hasAddedTelegramReactionEmoji(
+function getAddedTelegramReactionEmoji(
   oldEmojis: Set<string>,
   newEmojis: Set<string>,
   candidates: readonly string[],
-): boolean {
-  return candidates.some(
+): string | undefined {
+  return candidates.find(
     (emoji) => !oldEmojis.has(emoji) && newEmojis.has(emoji),
   );
 }
+function hasAddedTelegramReactionEmoji(
+  oldEmojis: Set<string>,
+  newEmojis: Set<string>,
+  candidates: readonly string[],
+): boolean {
+  return !!getAddedTelegramReactionEmoji(oldEmojis, newEmojis, candidates);
+}
 
 export function extractDeletedTelegramMessageIds(
   update: TelegramUpdateDeletion,
@@ -410,6 +422,7 @@ export interface TelegramUpdateRuntimeControllerDeps<
   prioritizeQueuedTelegramTurnByMessageId: (
     messageId: number,
     ctx: TContext,
+    priorityEmoji?: string,
   ) => boolean;
   pairTelegramUserIfNeeded: (userId: number, ctx: TContext) => Promise<boolean>;
   answerCallbackQuery: (
@@ -592,6 +605,7 @@ export interface AuthorizedTelegramReactionUpdateDeps<TContext> {
   prioritizeQueuedTelegramTurnByMessageId: (
     messageId: number,
     ctx: TContext,
+    priorityEmoji?: string,
   ) => boolean;
 }
 
@@ -638,17 +652,16 @@ export async function handleAuthorizedTelegramReactionUpdate<TContext>(
       deps.ctx,
     );
   }
-  if (
-    !hasAddedTelegramReactionEmoji(
-      oldEmojis,
-      newEmojis,
-      TELEGRAM_PRIORITY_REACTION_EMOJIS,
-    )
-  )
-    return;
+  const addedPriorityEmoji = getAddedTelegramReactionEmoji(
+    oldEmojis,
+    newEmojis,
+    TELEGRAM_PRIORITY_REACTION_EMOJIS,
+  );
+  if (!addedPriorityEmoji) return;
   deps.prioritizeQueuedTelegramTurnByMessageId(
     reactionUpdate.message_id,
     deps.ctx,
+    addedPriorityEmoji,
   );
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.7.2",
+  "version": "0.8.1",
   "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.