@llblab/pi-telegram 0.8.0 → 0.8.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.8.1: Outbound Voice Translation Hotfix
+
+- `[Outbound Voice]` Composed voice handlers now pass the original `telegram_voice` text to the first pipeline step through stdin, then continue piping each step's stdout into the next step. Impact: translate-from-stdin voice pipelines can translate hidden voice text before TTS instead of failing with an empty first-step input.
+- `[Queue Menu]` Queue item detail previews now render prompt text inside a bounded raw `<pre>` block, and generic queue navigation/headings use the `⏳` waiting icon. Impact: absolute file paths and attachment references remain readable without Telegram interpreting slash-prefixed paths as commands, long previews are truncated below Telegram's message limit, and the queue surface has a clearer generic icon distinct from ordered-list or priority markers.
+- `[Queue Delete]` Queue item removal now uses explicit `🗑 Delete` wording and opens a two-button confirmation (`🗑 Yes, delete` / `❌ No`) before mutating the queue. Impact: accidental queue-item deletion is harder while the item detail flow remains compact.
+- `[Queue Priority]` Priority reactions now preserve the exact normalized promotion emoji and render it in both queue-menu rows and the π status-bar queued preview. Reaction metadata is grouped into semantic id ranges (`10..13` for priority, `20..23` for removal). Impact: `👍`, `⚡`, `❤️`, and `🕊️` keep the same priority semantics while making the user's chosen reaction visible across Telegram and TUI surfaces.
+- `[Configuration Docs]` Documented the configuration philosophy that rich visual/TUI setup stays minimal for now while agents can read README/docs and update `telegram.json` for advanced workflows. Impact: configuration guidance matches the extension's agent-assisted operator model without adding premature TUI surfaces.
+- `[Outbound Docs]` Tightened voice-handler critical-step wording around transform → TTS → conversion pipelines and handler-level fallbacks. Impact: docs now match translated voice pipelines without implying provider-specific TTS fallbacks.
+- `[Package]` Bumped package metadata to `0.8.1` and kept the lockfile in sync.
+- `[Command Template Docs]` Synchronized `docs/command-templates.md` bit-for-bit with the current portable standard shared by `pi-auto-tools`. Impact: the documented standard now includes retry, fail-open composition, critical-step abort semantics, and the 30s default timeout in the same wording across both extensions.
+- `[Lock Docs]` Synchronized `docs/locks.md` bit-for-bit with the extension-neutral Locks Standard shared by `pi-wakeup`. Impact: singleton ownership documentation no longer carries project-specific examples that prevent exact reuse across extensions.
+
 ## 0.8.0: Handler Bus
 
 - `[Inbound Handlers]` Added `inboundHandlers` as the provider-neutral Telegram → π transformation bus. Raw Telegram text can match `type: "text"`, `mime: "text/plain"`, or `mime: "text/*"`, receives text on stdin and `{text}`, and non-empty stdout replaces the prompt text before queueing; media/file handlers keep the existing `{file}`/`{mime}`/`{type}` behavior with optional independent selectors. Impact: translation, normalization, STT, OCR, and file extraction can share one command-template integration model.

package/README.md

@@ -37,6 +37,12 @@ pi install git:github.com/llblab/pi-telegram
 
 ## Configure
 
+### Configuration Philosophy
+
+The extension intentionally keeps rich visual/TUI configuration minimal for now. Rich setup screens may arrive later, but they are not the main configuration surface yet.
+
+For advanced setup, ask an agent to read this `README.md` and the docs, then update `~/.pi/agent/telegram.json` for your workflow. Agents are good at small configuration changes, and this keeps the bridge simple while handler pipelines and operator preferences continue to evolve.
+
 ### 1. Telegram Bot
 
 1. Open [@BotFather](https://t.me/BotFather)

package/docs/command-templates.md

@@ -4,7 +4,7 @@ Command templates are the portable integration format for deterministic local au
 
 **Meta-contract:** transportable (bit-for-bit identical across projects), high-density (zero fluff), constant (evolve by crystallizing, not speculating), optimal minimum (add only when it hurts).
 
-**Scope:** portable command execution format — shell-free exec, composition/pipes, default timeout, critical-step branching, output artifact selection, handler-level fallback. Single JSON standard; no platform lock-in.
+**Scope:** portable command execution format — shell-free exec, composition/pipes, timeout (30s default), retry, critical-step branching, output artifact selection, handler-level fallback. Single JSON standard; no platform lock-in.
 
 ---
 
@@ -35,8 +35,9 @@ Common object fields:
 | `template` | Required command string or ordered composition array                                       |
 | `args`     | Optional placeholder-name declarations only; never stores defaults                         |
 | `defaults` | Placeholder default values by name                                                         |
-| `timeout`  | Optional execution timeout override in milliseconds; default `30000` (30s)                 |
+| `timeout`  | Optional execution timeout in milliseconds; default `30000` (30s)                          |
 | `output`   | Optional result selector; default `"stdout"`, or a "runtime value", e.g. `"ogg"`           |
+| `retry`    | Optional max attempts (including first); default `1`. Retries immediately on non-zero exit |
 | `critical` | Optional boolean; default `false`. When `true`, failure aborts the entire root composition |
 
 Storage paths, labels, selectors, descriptions, and registry-specific metadata belong to each extension's local schema.
@@ -118,7 +119,7 @@ template="echo 'literal words' {text}"
 
 Composition rules:
 
-- Execute leaves in order and stop on the first non-zero exit
+- Execute leaves in order; non-critical failures are recorded and execution continues, while `critical: true` failures abort the root composition
 - Treat the whole composition as one handler for selector matching and fallback
 - Top-level `args` and `defaults` apply to every leaf unless the leaf defines private values
 - Leaf `args` replace inherited `args`; leaf `defaults` merge over inherited defaults; `timeout` and `output` are not inherited into leaves
@@ -167,6 +168,21 @@ Set `critical: true` on any leaf to abort the entire root composition on failure
 
 A `critical` leaf in a nested composition still aborts the outermost root `template: [...]`. There is no per-branch scoping in the current standard.
 
+## Retry
+
+Set `retry: N` on a leaf to attempt execution up to `N` times (including the first). Retries happen immediately on non-zero exit. The first successful attempt stops the retry loop.
+
+```json
+{
+  "template": [
+    { "template": "npm install", "retry": 3 },
+    { "template": "npm test", "critical": true, "retry": 2 }
+  ]
+}
+```
+
+`npm install` is retried up to 3 times. `npm test` is retried up to 2 times; if all attempts fail, the critical step aborts the pipeline.
+
 ## Progressive Disclosure
 
 The standard uses a single `template` field that grows with the user's needs:
@@ -175,10 +191,10 @@ The standard uses a single `template` field that grows with the user's needs:
 string           → leaf command
 string[]         → sequential composition
 { template }     → leaf with defaults
-{ template, critical, output } → full leaf
+{ template, retry, critical, output } → full leaf
 ```
 
-Start with a string. Add composition when needed. Add critical when safety matters. Same contract, growing capability, no dead weight.
+Start with a string. Add composition when needed. Add retry when flaky. Add critical when safety matters. Same contract, growing capability, no dead weight.
 
 ## Tool Boundary
 

package/docs/locks.md

@@ -16,7 +16,7 @@ Path:
 
 ```json
 {
-  "@llblab/pi-telegram": {
+  "@scope/pi-singleton": {
     "pid": 2590864,
     "cwd": "/home/user/project"
   }
@@ -38,9 +38,9 @@ For npm-style package extensions, the canonical value is the `package.json` `nam
 Examples:
 
 ```text
-extensions/pi-telegram/package.json name=@llblab/pi-telegram -> @llblab/pi-telegram
-extensions/pi-telegram/index.ts without package.json         -> pi-telegram
-extensions/pi-telegram.ts                                    -> pi-telegram
+extensions/pi-singleton/package.json name=@scope/pi-singleton -> @scope/pi-singleton
+extensions/pi-singleton/index.ts without package.json         -> pi-singleton
+extensions/pi-singleton.ts                                    -> pi-singleton
 ```
 
 ## Required fields
@@ -62,7 +62,7 @@ During a user-initiated start/connect event, an extension should:
 
 ## Acquisition timing
 
-Lock writes must be caused by an explicit user-initiated runtime event, such as `/wakeup-start`, `/telegram-connect`, or a confirmed takeover prompt.
+Lock writes must be caused by an explicit user-initiated runtime event, such as a start/connect command or a confirmed takeover prompt.
 
 Extension initialization and session-start hooks may read `locks.json`, update local status, install ownership watchers, and resume local work when the existing lock already points at the current `pid`/`cwd`. After a full process restart, a session-start hook may replace a stale lock from the same `cwd` to restore explicitly requested ownership. They must not create ownership from an inactive lock, take over a live external owner, or replace a stale lock from another directory by themselves. Such locks should stay visible as state until the user runs the start/connect command. Session replacement should suspend local runtime work and ownership watchers without releasing the lock, so the next session in the same `pid`/`cwd` can resume from explicit ownership.
 
@@ -92,11 +92,13 @@ Do not print optional fields in normal UI unless they help the user act.
 
 ## Runtime status
 
-Singleton extensions with footer/status presence should expose quiet but explicit local state. For example, pi-wakeup uses:
+Singleton extensions with footer/status presence should expose quiet but explicit local state:
 
-- `wakeup off` when this pi instance does not own the singleton runtime
-- `wakeup on` when this pi instance owns the runtime but has no pending wake-up detail to show
-- `wakeup [16:32:39]` when the runtime owns scheduled work and can show the next countdown
+- `off` when this pi instance does not own the singleton runtime
+- `on` when this pi instance owns the runtime but has no pending runtime detail to show
+- `[16:32:39]` when the runtime owns scheduled work and can show the next countdown
+
+Extensions may prefix those states with their own compact name, such as `wakeup off` or `telegram on`.
 
 ## Interactive takeover
 
@@ -110,7 +112,7 @@ Start/connect commands should make singleton moves easy:
 Takeover prompts should use the extension name as the dialog title, then the question, a blank line, and source/target lines:
 
 ```text
-pi-telegram
+pi-singleton
 move singleton lock here?
 
 from: pid 2590864, cwd /old
@@ -123,7 +125,7 @@ The previous owner may use `fs.watch`, mtime polling, or an existing status/time
 
 ## Reset
 
-Delete `~/.pi/agent/locks.json` to reset singleton runtime ownership for all participating extensions without deleting their configuration files such as `telegram.json`.
+Delete `~/.pi/agent/locks.json` to reset singleton runtime ownership for all participating extensions without deleting their configuration files.
 
 ## Atomicity
 

package/docs/outbound-handlers.md

@@ -112,7 +112,7 @@ For composed handlers, `output` selects the primary artifact after the compositi
 
 For one-step `template` handlers, stdout remains the default result channel: the command should print the generated OGG/Opus path.
 
-**Critical steps:** voice synthesis is a multi-step pipeline (TTS → ffmpeg → OGG). The ffmpeg conversion step is inherently critical — if it fails, the voice output is invalid. Mark it as `"critical": true` when a composed handler must abort after conversion failure instead of continuing to later non-critical steps. Keep the fallback chain (Mistral TTS → Groq TTS) as the safety net for persistent outages. See [Command Template Standard](./command-templates.md) for semantics.
+**Critical steps:** voice synthesis is often a multi-step transform → TTS → conversion pipeline. The final audio conversion step is inherently critical — if it fails, the voice output is invalid. Mark conversion steps as `"critical": true` when a composed handler must abort after conversion failure instead of continuing to later non-critical steps. Use multiple matching `type: "voice"` handlers when you need provider or command fallbacks. See [Command Template Standard](./command-templates.md) for semantics.
 
 ## Buttons Markup
 

package/lib/menu-queue.ts

@@ -11,11 +11,14 @@ import * as Queue from "./queue.ts";
 
 // --- Queue Menu ---
 
+const QUEUE_ITEM_PROMPT_HTML_LIMIT = 3600;
+const QUEUE_ITEM_PROMPT_TRUNCATION_SUFFIX = "\n… [truncated]";
 type TelegramQueueMenuReplyMarkup = TelegramInlineKeyboardMarkup;
 interface TelegramQueueMenuItem {
   chatId: number;
   replyToMessageId: number;
   isPriority: boolean;
+  priorityEmoji?: string;
   hasAttachments: boolean;
   statusSummary: string;
   promptText: string;
@@ -40,6 +43,7 @@ function toTelegramQueueMenuItems<Context>(
       chatId: item.chatId,
       replyToMessageId: item.replyToMessageId,
       isPriority: item.queueLane === "priority",
+      priorityEmoji: item.kind === "prompt" ? item.priorityEmoji : undefined,
       hasAttachments:
         item.kind === "prompt" && item.queuedAttachments.length > 0,
       statusSummary: item.statusSummary,
@@ -53,7 +57,11 @@ function buildTelegramQueueMenuReplyMarkup(
   const backRow = [{ text: "⬆️ Main menu", callback_data: "menu:back" }];
   if (items.length === 0) return { inline_keyboard: [backRow] };
   const rows = items.map(function buildTelegramQueueMenuRow(item, index) {
-    const prefix = item.isPriority ? "⚡ " : item.hasAttachments ? "📎 " : "";
+    const prefix = item.isPriority
+      ? `${item.priorityEmoji ?? "⚡"} `
+      : item.hasAttachments
+        ? "📎 "
+        : "";
     const label = `${index + 1}. ${prefix}${item.statusSummary}`;
     return [
       {
@@ -82,21 +90,44 @@ function findTelegramQueueMenuItem(
     return item.chatId === chatId && item.replyToMessageId === replyToMessageId;
   });
 }
+function escapeTelegramQueueMenuHtmlChar(char: string): string {
+  if (char === "&") return "&amp;";
+  if (char === "<") return "&lt;";
+  if (char === ">") return "&gt;";
+  return char;
+}
 function escapeTelegramQueueMenuHtml(text: string): string {
-  return text
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;");
+  return Array.from(text).map(escapeTelegramQueueMenuHtmlChar).join("");
+}
+function escapeTelegramQueueMenuHtmlPreview(text: string): string {
+  const suffix = escapeTelegramQueueMenuHtml(QUEUE_ITEM_PROMPT_TRUNCATION_SUFFIX);
+  let escaped = "";
+  let truncated = false;
+  for (const char of text) {
+    const next = escapeTelegramQueueMenuHtmlChar(char);
+    if (
+      escaped.length + next.length + suffix.length >
+      QUEUE_ITEM_PROMPT_HTML_LIMIT
+    ) {
+      truncated = true;
+      break;
+    }
+    escaped += next;
+  }
+  return truncated ? escaped + suffix : escaped;
 }
 function getTelegramQueueMenuItemText(item: TelegramQueueMenuItem): string {
-  return escapeTelegramQueueMenuHtml(item.promptText);
+  return `<pre>${escapeTelegramQueueMenuHtmlPreview(item.promptText)}</pre>`;
 }
 function buildTelegramQueueItemSubmenuReplyMarkup(
   chatId: number,
   replyToMessageId: number,
   isPriority: boolean,
+  priorityEmoji?: string,
 ): TelegramQueueMenuReplyMarkup {
-  const priorityLabel = isPriority ? "🐢 Deprioritize" : "⚡ Prioritize";
+  const priorityLabel = isPriority
+    ? `🐢 Deprioritize ${priorityEmoji ?? "⚡"}`
+    : "⚡ Prioritize";
   return {
     inline_keyboard: [
       [{ text: "⬆️ Back", callback_data: "queue:list" }],
@@ -108,8 +139,29 @@ function buildTelegramQueueItemSubmenuReplyMarkup(
       ],
       [
         {
-          text: "❌ Cancel",
-          callback_data: `queue:cancel:${chatId}:${replyToMessageId}`,
+          text: "🗑 Delete",
+          callback_data: `queue:delete:${chatId}:${replyToMessageId}`,
+        },
+      ],
+    ],
+  };
+}
+function buildTelegramQueueDeleteConfirmationReplyMarkup(
+  chatId: number,
+  replyToMessageId: number,
+): TelegramQueueMenuReplyMarkup {
+  return {
+    inline_keyboard: [
+      [
+        {
+          text: "🗑 Yes, delete",
+          callback_data: `queue:confirm-delete:${chatId}:${replyToMessageId}`,
+        },
+      ],
+      [
+        {
+          text: "❌ No",
+          callback_data: `queue:keep:${chatId}:${replyToMessageId}`,
         },
       ],
     ],
@@ -186,14 +238,38 @@ async function handleTelegramQueueMenuCallback<Context>(
     );
     return true;
   }
-  const cancelMatch = data.match(/^queue:cancel:(\d+):(\d+)$/);
-  if (cancelMatch) {
-    await handleTelegramQueueMenuCancel(
+  const deleteMatch = data.match(/^queue:(?:delete|cancel):(\d+):(\d+)$/);
+  if (deleteMatch) {
+    await handleTelegramQueueMenuDeleteRequest(
       callbackQueryId,
       replyChatId,
       replyMessageId,
-      Number(cancelMatch[1]),
-      Number(cancelMatch[2]),
+      Number(deleteMatch[1]),
+      Number(deleteMatch[2]),
+      deps,
+    );
+    return true;
+  }
+  const keepMatch = data.match(/^queue:keep:(\d+):(\d+)$/);
+  if (keepMatch) {
+    await handleTelegramQueueMenuKeep(
+      callbackQueryId,
+      replyChatId,
+      replyMessageId,
+      Number(keepMatch[1]),
+      Number(keepMatch[2]),
+      deps,
+    );
+    return true;
+  }
+  const confirmDeleteMatch = data.match(/^queue:confirm-delete:(\d+):(\d+)$/);
+  if (confirmDeleteMatch) {
+    await handleTelegramQueueMenuConfirmDelete(
+      callbackQueryId,
+      replyChatId,
+      replyMessageId,
+      Number(confirmDeleteMatch[1]),
+      Number(confirmDeleteMatch[2]),
       ctx,
       deps,
     );
@@ -204,8 +280,8 @@ async function handleTelegramQueueMenuCallback<Context>(
 function getTelegramQueueMenuListText(
   items: readonly TelegramQueueMenuItem[],
 ): string {
-  if (items.length === 0) return "<b>Queue is empty.</b>";
-  return "<b>Queue:</b>";
+  if (items.length === 0) return "<b>⏳ Queue is empty.</b>";
+  return "<b>⏳ Queue:</b>";
 }
 async function updateTelegramQueueMenuList<Context>(
   callbackQueryId: string,
@@ -258,7 +334,12 @@ async function handleTelegramQueueMenuPick<Context>(
     replyChatId,
     replyMessageId,
     getTelegramQueueMenuItemText(item),
-    buildTelegramQueueItemSubmenuReplyMarkup(chatId, msgId, item.isPriority),
+    buildTelegramQueueItemSubmenuReplyMarkup(
+      chatId,
+      msgId,
+      item.isPriority,
+      item.priorityEmoji,
+    ),
   );
   await deps.answerCallbackQuery(callbackQueryId);
 }
@@ -288,14 +369,74 @@ async function handleTelegramQueueMenuPriority<Context>(
     replyChatId,
     replyMessageId,
     getTelegramQueueMenuItemText(item),
-    buildTelegramQueueItemSubmenuReplyMarkup(chatId, msgId, newPriority),
+    buildTelegramQueueItemSubmenuReplyMarkup(
+      chatId,
+      msgId,
+      newPriority,
+      updated?.priorityEmoji ?? item.priorityEmoji,
+    ),
   );
   await deps.answerCallbackQuery(
     callbackQueryId,
     newPriority ? "Prioritized." : "Deprioritized.",
   );
 }
-async function handleTelegramQueueMenuCancel<Context>(
+async function handleTelegramQueueMenuDeleteRequest<Context>(
+  callbackQueryId: string,
+  replyChatId: number,
+  replyMessageId: number,
+  chatId: number,
+  msgId: number,
+  deps: TelegramQueueMenuCallbackDeps<Context>,
+): Promise<void> {
+  const item = deps.findItem(chatId, msgId);
+  if (!item) {
+    return refreshStaleTelegramQueueMenuItem(
+      callbackQueryId,
+      replyChatId,
+      replyMessageId,
+      deps,
+    );
+  }
+  await deps.updateQueueMessage(
+    replyChatId,
+    replyMessageId,
+    "<b>Delete this queued prompt?</b>",
+    buildTelegramQueueDeleteConfirmationReplyMarkup(chatId, msgId),
+  );
+  await deps.answerCallbackQuery(callbackQueryId);
+}
+async function handleTelegramQueueMenuKeep<Context>(
+  callbackQueryId: string,
+  replyChatId: number,
+  replyMessageId: number,
+  chatId: number,
+  msgId: number,
+  deps: TelegramQueueMenuCallbackDeps<Context>,
+): Promise<void> {
+  const item = deps.findItem(chatId, msgId);
+  if (!item) {
+    return refreshStaleTelegramQueueMenuItem(
+      callbackQueryId,
+      replyChatId,
+      replyMessageId,
+      deps,
+    );
+  }
+  await deps.updateQueueMessage(
+    replyChatId,
+    replyMessageId,
+    getTelegramQueueMenuItemText(item),
+    buildTelegramQueueItemSubmenuReplyMarkup(
+      chatId,
+      msgId,
+      item.isPriority,
+      item.priorityEmoji,
+    ),
+  );
+  await deps.answerCallbackQuery(callbackQueryId, "Kept in queue.");
+}
+async function handleTelegramQueueMenuConfirmDelete<Context>(
   callbackQueryId: string,
   replyChatId: number,
   replyMessageId: number,
@@ -311,7 +452,7 @@ async function handleTelegramQueueMenuCancel<Context>(
     replyChatId,
     replyMessageId,
     deps,
-    removed ? "Removed from queue." : "Item not found.",
+    removed ? "Deleted from queue." : "Item not found.",
   );
 }
 

package/lib/menu-status.ts

@@ -160,7 +160,7 @@ export function buildStatusReplyMarkup(
   }
   rows.push([
     {
-      text: `🔢 Queue: ${queueItemCount}`,
+      text: `⏳ Queue: ${queueItemCount}`,
       callback_data: "menu:queue",
     },
   ]);

package/lib/outbound-handlers.ts

@@ -650,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(
@@ -665,7 +665,7 @@ async function generateTelegramVoiceReplyFileWithHandler(
               startedAt,
             ),
             execCommand: options.execCommand,
-            ...(index === 0 ? {} : { stdin: stdout }),
+            stdin: stdout,
           },
         );
         stdout = result.stdout;

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/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.8.0",
+  "version": "0.8.1",
   "private": false,
   "description": "Better Telegram DM bridge extension for π",
   "type": "module",