@llblab/pi-telegram 0.9.3 → 0.9.5

package/lib/command-templates.ts

@@ -10,17 +10,23 @@ import { isAbsolute, resolve } from "node:path";
 
 export const DEFAULT_COMMAND_TIMEOUT_MS = 30_000;
 
+export type CommandTemplateMode = "sequence" | "parallel";
+
 export interface CommandTemplateObjectConfig {
+  label?: string;
+  mode?: CommandTemplateMode;
   template?: CommandTemplateValue;
   args?: string[];
   defaults?: Record<string, unknown>;
   timeout?: number;
+  delay?: number;
   output?: string;
   retry?: number;
   critical?: boolean;
+  repeat?: number;
 }
 
-export type CommandTemplateValue = string | CommandTemplateConfig[];
+export type CommandTemplateValue = string | CommandTemplateConfig[] | CommandTemplateObjectConfig;
 
 export type CommandTemplateConfig = string | CommandTemplateObjectConfig;
 
@@ -78,6 +84,61 @@ function normalizeCommandTemplateDefaults(
   return normalized;
 }
 
+function normalizeRepeat(value: number | undefined): number | undefined {
+  if (value === undefined) return undefined;
+  if (!Number.isInteger(value) || value < 1)
+    throw new Error("Command template repeat must be a positive integer.");
+  return value;
+}
+
+function pad(value: number, width: number): string {
+  return String(value).padStart(width, "0");
+}
+
+export function isCommandTemplateRepeatPlaceholder(name: string): boolean {
+  return /^_{0,6}(?:index|prev|next|repeat)$/.test(name);
+}
+
+export function getCommandTemplateRepeatDefaults(
+  index: number,
+  repeat: number,
+): Record<string, string> {
+  const prev = (index - 1 + repeat) % repeat;
+  const next = (index + 1) % repeat;
+  const values: Record<string, string> = {
+    index: String(index),
+    next: String(next),
+    prev: String(prev),
+    repeat: String(repeat),
+  };
+  for (const name of ["index", "prev", "next", "repeat"]) {
+    const numeric = Number(values[name]);
+    for (let underscores = 1; underscores <= 6; underscores += 1) {
+      values[`${"_".repeat(underscores)}${name}`] = pad(numeric, underscores + 1);
+    }
+  }
+  return values;
+}
+
+function expandRepeatConfig(
+  config: CommandTemplateObjectConfig,
+  context: Pick<CommandTemplateObjectConfig, "args" | "defaults">,
+): CommandTemplateObjectConfig[] | undefined {
+  const repeat = normalizeRepeat(config.repeat);
+  if (repeat === undefined) return undefined;
+  return Array.from({ length: repeat }, (_unused, index0) => {
+    const { repeat: _repeat, ...rest } = config;
+    return {
+      ...rest,
+      defaults: {
+        ...(context.defaults ?? {}),
+        ...(rest.defaults ?? {}),
+        ...getCommandTemplateRepeatDefaults(index0, repeat),
+      },
+    };
+  });
+}
+
 export function expandCommandTemplateConfigs(
   config: CommandTemplateConfig,
   inherited: Pick<CommandTemplateObjectConfig, "args" | "defaults"> = {},
@@ -99,6 +160,10 @@ export function expandCommandTemplateConfigs(
       ? { defaults: { ...(inheritedDefaults ?? {}), ...ownDefaults } }
       : {}),
   };
+  const repeated = expandRepeatConfig(normalizedConfig, context);
+  if (repeated) {
+    return repeated.flatMap((step) => expandCommandTemplateConfigs(step, context));
+  }
   if (Array.isArray(normalizedConfig.template)) {
     return normalizedConfig.template.flatMap((step) =>
       expandCommandTemplateConfigs(step, context),
@@ -189,17 +254,92 @@ export function expandCommandTemplateExecutable(
   return command;
 }
 
+function evaluateCommandTemplateExpression(
+  expression: string,
+  values: Record<string, string>,
+): number {
+  let index = 0;
+  const source = expression.replace(/\s+/g, "");
+  function peek(): string | undefined {
+    return source[index];
+  }
+  function consume(char: string): boolean {
+    if (peek() !== char) return false;
+    index += 1;
+    return true;
+  }
+  function parsePrimary(): number {
+    if (consume("(")) {
+      const value = parseExpression();
+      if (!consume(")")) throw new Error(`Invalid command template expression: ${expression}`);
+      return value;
+    }
+    const numberMatch = source.slice(index).match(/^\d+/);
+    if (numberMatch) {
+      index += numberMatch[0].length;
+      return Number(numberMatch[0]);
+    }
+    const nameMatch = source.slice(index).match(/^[A-Za-z_][A-Za-z0-9_-]*/);
+    if (nameMatch) {
+      index += nameMatch[0].length;
+      const value = values[nameMatch[0]];
+      if (value === undefined || !/^-?\d+$/.test(value))
+        throw new Error(`Invalid command template expression variable: ${nameMatch[0]}`);
+      return Number(value);
+    }
+    throw new Error(`Invalid command template expression: ${expression}`);
+  }
+  function parseTerm(): number {
+    let value = parsePrimary();
+    while (true) {
+      if (consume("*")) value *= parsePrimary();
+      else if (consume("/")) value = Math.trunc(value / parsePrimary());
+      else if (consume("%")) value %= parsePrimary();
+      else return value;
+    }
+  }
+  function parseExpression(): number {
+    let value = parseTerm();
+    while (true) {
+      if (consume("+")) value += parseTerm();
+      else if (consume("-")) value -= parseTerm();
+      else return value;
+    }
+  }
+  const value = parseExpression();
+  if (index !== source.length) throw new Error(`Invalid command template expression: ${expression}`);
+  return value;
+}
+
+function substituteCommandTemplateExpression(
+  content: string,
+  values: Record<string, string>,
+): string | undefined {
+  const padded = content.match(/^(_{1,6})\((.+)\)$/);
+  if (padded) {
+    return pad(evaluateCommandTemplateExpression(padded[2], values), padded[1].length + 1);
+  }
+  if (!/[()+\-*\/%]/.test(content)) return undefined;
+  return String(evaluateCommandTemplateExpression(content, values));
+}
+
 export function substituteCommandTemplateToken(
   token: string,
   values: Record<string, string>,
   missingLabel = "command template",
 ): string {
   return token.replace(
-    /\{([A-Za-z_][A-Za-z0-9_-]*)(?:=([^}]*))?\}/g,
-    (_match, name, inlineDefault: string | undefined) => {
-      if (Object.hasOwn(values, name)) return values[name] ?? "";
-      if (inlineDefault !== undefined) return inlineDefault;
-      throw new Error(`Missing ${missingLabel} value: ${name}`);
+    /\{([^{}]+)\}/g,
+    (_match, content: string) => {
+      const simple = content.match(/^([A-Za-z_][A-Za-z0-9_-]*)(?:=([^}]*))?$/);
+      if (simple) {
+        const [, name, inlineDefault] = simple;
+        if (Object.hasOwn(values, name)) return values[name] ?? "";
+        if (inlineDefault !== undefined) return inlineDefault;
+      }
+      const expression = substituteCommandTemplateExpression(content, values);
+      if (expression !== undefined) return expression;
+      throw new Error(`Missing ${missingLabel} value: ${content}`);
     },
   );
 }
@@ -300,6 +440,12 @@ export function buildCommandTemplateInvocation(
   }
   if (!normalizedConfig.template)
     throw new Error(options.emptyMessage ?? "Command template is required");
+  if (typeof normalizedConfig.template !== "string") {
+    throw new Error(
+      options.emptyMessage ??
+        "Command template object cannot be executed as one command",
+    );
+  }
   const parts = splitCommandTemplate(normalizedConfig.template);
   const commandPart = parts[0];
   if (!commandPart)

package/lib/menu-queue.ts

@@ -13,6 +13,12 @@ import * as Queue from "./queue.ts";
 
 const QUEUE_ITEM_PROMPT_HTML_LIMIT = 3600;
 const QUEUE_ITEM_PROMPT_TRUNCATION_SUFFIX = "\n… [truncated]";
+const EMPTY_QUEUE_REFRESH_TITLES = [
+  "<b>⌛ Queue is still empty.</b>",
+  "<b>🫙 Still nothing in queue.</b>",
+  "<b>🍃 Queue remains empty.</b>",
+  "<b>🕳 Nothing queued yet.</b>",
+] as const;
 type TelegramQueueMenuReplyMarkup = TelegramInlineKeyboardMarkup;
 interface TelegramQueueMenuItem {
   chatId: number;
@@ -55,9 +61,16 @@ function toTelegramQueueMenuItems<Context>(
 }
 function buildTelegramQueueMenuReplyMarkup(
   items: readonly TelegramQueueMenuItem[],
+  emptyRefreshIndex = 0,
 ): TelegramQueueMenuReplyMarkup {
   const backRow = [{ text: "⬆️ Main menu", callback_data: "menu:back" }];
-  const refreshRow = [{ text: "🌀 Refresh", callback_data: "queue:refresh" }];
+  const nextEmptyRefreshIndex =
+    (emptyRefreshIndex + 1) % EMPTY_QUEUE_REFRESH_TITLES.length;
+  const refreshData =
+    items.length === 0
+      ? `queue:refresh:${nextEmptyRefreshIndex}`
+      : "queue:refresh";
+  const refreshRow = [{ text: "🌀 Refresh", callback_data: refreshData }];
   if (items.length === 0) return { inline_keyboard: [backRow, refreshRow] };
   const rows = items.map(function buildTelegramQueueMenuRow(item, index) {
     const prefix = item.isPriority
@@ -73,7 +86,7 @@ function buildTelegramQueueMenuReplyMarkup(
       },
     ];
   });
-  return { inline_keyboard: [backRow, ...rows, refreshRow] };
+  return { inline_keyboard: [backRow, refreshRow, ...rows] };
 }
 function findTelegramQueueItem<Context>(
   items: readonly Queue.TelegramQueueItem<Context>[],
@@ -215,7 +228,7 @@ async function handleTelegramQueueMenuCallback<Context>(
     await deps.answerCallbackQuery(callbackQueryId);
     return true;
   }
-  if (data === "queue:list" || data === "queue:refresh") {
+  if (data === "queue:list") {
     await updateTelegramQueueMenuList(
       callbackQueryId,
       replyChatId,
@@ -224,6 +237,18 @@ async function handleTelegramQueueMenuCallback<Context>(
     );
     return true;
   }
+  const refreshMatch = data.match(/^queue:refresh(?::(\d+))?$/);
+  if (refreshMatch) {
+    await updateTelegramQueueMenuList(
+      callbackQueryId,
+      replyChatId,
+      replyMessageId,
+      deps,
+      undefined,
+      refreshMatch[1] === undefined ? 0 : Number(refreshMatch[1]),
+    );
+    return true;
+  }
   const pickMatch = data.match(/^queue:pick:(\d+):(\d+)$/);
   if (pickMatch) {
     await handleTelegramQueueMenuPick(
@@ -306,9 +331,13 @@ async function handleTelegramQueueMenuCallback<Context>(
 }
 function getTelegramQueueMenuListText(
   items: readonly TelegramQueueMenuItem[],
+  emptyRefreshIndex?: number,
 ): string {
-  if (items.length === 0) return "<b>⌛ Queue is empty.</b>";
-  return "<b>⏳ Queue:</b>";
+  if (items.length > 0) return "<b>⏳ Queue:</b>";
+  if (emptyRefreshIndex === undefined) return "<b>⌛ Queue is empty.</b>";
+  return EMPTY_QUEUE_REFRESH_TITLES[
+    emptyRefreshIndex % EMPTY_QUEUE_REFRESH_TITLES.length
+  ];
 }
 async function updateTelegramQueueMenuList<Context>(
   callbackQueryId: string,
@@ -316,13 +345,14 @@ async function updateTelegramQueueMenuList<Context>(
   replyMessageId: number,
   deps: TelegramQueueMenuCallbackDeps<Context>,
   notice?: string,
+  emptyRefreshIndex?: number,
 ): Promise<void> {
   const items = deps.getQueuedItems();
   await deps.updateQueueMessage(
     replyChatId,
     replyMessageId,
-    getTelegramQueueMenuListText(items),
-    buildTelegramQueueMenuReplyMarkup(items),
+    getTelegramQueueMenuListText(items, emptyRefreshIndex),
+    buildTelegramQueueMenuReplyMarkup(items, emptyRefreshIndex),
   );
   await deps.answerCallbackQuery(callbackQueryId, notice);
 }

package/lib/menu-settings.ts

@@ -111,7 +111,6 @@ export function buildProactivePushSettingsText(): string {
     PROACTIVE_PUSH_SETTINGS_TITLE,
     "",
     "Send successful local π task results to Telegram when the bridge is connected.",
-    "Default: off. Persists until disabled or removed from config.",
   ].join("\n");
 }
 

package/lib/preview.ts

@@ -90,6 +90,11 @@ export interface TelegramPreviewRuntimeDeps<
     options?: { replyMarkup?: TReplyMarkup },
   ) => Promise<number | undefined>;
   canSend?: () => boolean;
+  recordRuntimeEvent?: (
+    category: string,
+    error: unknown,
+    details?: Record<string, unknown>,
+  ) => void;
 }
 
 export interface TelegramPreviewActiveTurn {
@@ -191,6 +196,11 @@ export interface TelegramPreviewControllerDeps<
     ms: number,
   ) => ReturnType<typeof setTimeout>;
   clearTimer?: (timer: ReturnType<typeof setTimeout>) => void;
+  recordRuntimeEvent?: (
+    category: string,
+    error: unknown,
+    details?: Record<string, unknown>,
+  ) => void;
 }
 
 export interface TelegramPreviewController<
@@ -421,6 +431,7 @@ export function createTelegramPreviewController<
       ),
     editRenderedMessage: deps.editRenderedMessage,
     canSend: deps.canSend,
+    recordRuntimeEvent: deps.recordRuntimeEvent,
   });
   return {
     getState: () => state,
@@ -645,7 +656,16 @@ export async function flushTelegramPreview<
   state.flushPromise = (async () => {
     do {
       state.flushRequested = false;
-      await performTelegramPreviewFlush(chatId, state, deps);
+      try {
+        await performTelegramPreviewFlush(chatId, state, deps);
+      } catch (error) {
+        deps.recordRuntimeEvent?.("preview", error, {
+          phase: "flush",
+          chatId,
+          messageId: state.messageId,
+        });
+        break;
+      }
     } while (deps.getState() === state && state.flushRequested);
   })();
   try {
@@ -704,13 +724,22 @@ export async function finalizeTelegramMarkdownPreview<
     await clearTelegramPreview(chatId, deps);
     return false;
   }
-  if (state.mode === "draft") {
-    await deps.sendRenderedChunks(chatId, chunks, options);
-    await clearTelegramPreview(chatId, deps);
+  try {
+    if (state.mode === "draft") {
+      await deps.sendRenderedChunks(chatId, chunks, options);
+      await clearTelegramPreview(chatId, deps);
+      return true;
+    }
+    if (state.messageId === undefined) return false;
+    await deps.editRenderedMessage(chatId, state.messageId, chunks, options);
+    deps.setState(undefined);
     return true;
+  } catch (error) {
+    deps.recordRuntimeEvent?.("preview", error, {
+      phase: "finalize-markdown",
+      chatId,
+      messageId: state.messageId,
+    });
+    return false;
   }
-  if (state.messageId === undefined) return false;
-  await deps.editRenderedMessage(chatId, state.messageId, chunks, options);
-  deps.setState(undefined);
-  return true;
 }

package/lib/queue.ts

@@ -1023,20 +1023,28 @@ export async function handleTelegramAgentEndRuntime<
   if (finalText) deps.setPreviewPendingText(finalText);
   if (!finalText && hasOutboundArtifacts) await deps.clearPreview(turn.chatId);
   if (endPlan.kind === "text" && finalText) {
-    const finalized = await deps.finalizeMarkdownPreview(
-      turn.chatId,
-      finalText,
-      turn.replyToMessageId,
-      { replyMarkup },
-    );
-    if (!finalized) {
-      await deps.clearPreview(turn.chatId);
-      await deps.sendMarkdownReply(
+    try {
+      const finalized = await deps.finalizeMarkdownPreview(
         turn.chatId,
-        turn.replyToMessageId,
         finalText,
+        turn.replyToMessageId,
         { replyMarkup },
       );
+      if (!finalized) {
+        await deps.clearPreview(turn.chatId);
+        await deps.sendMarkdownReply(
+          turn.chatId,
+          turn.replyToMessageId,
+          finalText,
+          { replyMarkup },
+        );
+      }
+    } catch (error) {
+      deps.recordRuntimeEvent?.("delivery", error, {
+        phase: "final-text",
+        chatId: turn.chatId,
+        replyToMessageId: turn.replyToMessageId,
+      });
     }
   }
   if (outboundReply && deps.sendOutboundReplyArtifacts) {

package/package.json

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