@llblab/pi-telegram 0.12.0 → 0.13.1

package/lib/inbound.ts

@@ -11,6 +11,7 @@ import {
   buildCommandTemplateInvocation,
   expandCommandTemplateConfigs,
   normalizeCommandTemplateConfig,
+  substituteCommandTemplateToken,
   type CommandTemplateConfig,
   type CommandTemplateObjectConfig,
 } from "./command-templates.ts";
@@ -28,10 +29,9 @@ export interface TelegramInboundHandlerConfig {
   mime?: string | string[];
   type?: string | string[];
   template?: string | TelegramInboundCommandTemplateConfig[];
-  pipe?: TelegramInboundCommandTemplateConfig[];
   args?: string[];
   defaults?: Record<string, unknown>;
-  timeout?: number;
+  timeout?: number | string;
 }
 
 export interface TelegramInboundHandlerFile {
@@ -62,6 +62,7 @@ export interface TelegramInboundHandlerExecOptions {
   timeout?: number;
   signal?: AbortSignal;
   stdin?: string;
+  retry?: number;
 }
 
 export interface TelegramInboundHandlerExecResult {
@@ -322,13 +323,28 @@ export function buildTelegramInboundHandlerInvocation(
   );
 }
 
+function resolveTelegramInboundNumericControlField(
+  value: number | string | undefined,
+  values: Record<string, unknown>,
+  label: string,
+): number | undefined {
+  if (value === undefined) return undefined;
+  const resolved =
+    typeof value === "string"
+      ? substituteCommandTemplateToken(value, values, label)
+      : value;
+  if (resolved === "") return undefined;
+  const numeric = Number(resolved);
+  if (!Number.isFinite(numeric) || numeric < 0)
+    throw new Error(`Command template ${label} must be a non-negative number.`);
+  return numeric;
+}
+
 function getTelegramInboundHandlerConfiguredTimeout(
   handler: TelegramInboundCommandTemplateConfig,
 ): number | undefined {
   const timeout = typeof handler === "string" ? undefined : handler.timeout;
-  return typeof timeout === "number" && Number.isFinite(timeout) && timeout > 0
-    ? timeout
-    : undefined;
+  return resolveTelegramInboundNumericControlField(timeout, {}, "timeout");
 }
 
 function getTelegramInboundHandlerTimeout(
@@ -374,8 +390,7 @@ function getTelegramInboundCompositionStepTimeout(
 function getTelegramInboundHandlerKind(
   handler: TelegramInboundHandlerConfig,
 ): string {
-  if (Array.isArray(handler.template) || handler.pipe?.length)
-    return "composition";
+  if (Array.isArray(handler.template)) return "composition";
   if (handler.template) return "template";
   return "unknown";
 }
@@ -410,7 +425,7 @@ async function executeTelegramInboundHandlerInvocation(
     cwd,
     timeout,
     ...(typeof handler === "object" && handler.retry !== undefined
-      ? { retry: handler.retry }
+      ? { retry: resolveTelegramInboundNumericControlField(handler.retry, {}, "retry") }
       : {}),
     ...(stdin !== undefined ? { stdin } : {}),
   });
@@ -427,12 +442,6 @@ function getTelegramInboundHandlerCompositionSteps(
       handler,
     ) as TelegramInboundCommandTemplateConfig[];
   }
-  if (handler.pipe?.length) {
-    return expandCommandTemplateConfigs({
-      ...handler,
-      template: handler.pipe,
-    }) as TelegramInboundCommandTemplateConfig[];
-  }
   return [];
 }
 
@@ -490,7 +499,7 @@ async function executeTelegramTextHandlerInvocation(
     timeout,
     stdin: text,
     ...(typeof handler === "object" && handler.retry !== undefined
-      ? { retry: handler.retry }
+      ? { retry: resolveTelegramInboundNumericControlField(handler.retry, {}, "retry") }
       : {}),
   });
   if (result.code !== 0)
@@ -524,7 +533,7 @@ async function executeTelegramTextHandler(
           : getTelegramInboundCompositionStepTimeout(handler, step, startedAt),
       );
     } catch (error) {
-      if (typeof step === "object" && step.critical) throw error;
+      if (typeof step === "object" && step.failure === "root") throw error;
       output = "";
     }
     if (index > 0 && !output) output = text;
@@ -682,7 +691,7 @@ async function executeTelegramInboundHandler(
         index === 0 ? undefined : output,
       );
     } catch (error) {
-      if (typeof step === "object" && step.critical) throw error;
+      if (typeof step === "object" && step.failure === "root") throw error;
       output = "";
     }
   }

package/lib/lifecycle.ts

@@ -182,6 +182,11 @@ export interface TelegramMessageActivityTypingDeps<TContext> {
   startTypingLoop: (ctx: TContext) => void;
   onMessageStart: TelegramLifecycleRegistrationDeps["onMessageStart"];
   onMessageUpdate: TelegramLifecycleRegistrationDeps["onMessageUpdate"];
+  recordRuntimeEvent?: (
+    category: string,
+    error: unknown,
+    details?: Record<string, unknown>,
+  ) => void;
 }
 
 export function createTelegramMessageActivityTypingHooks<
@@ -195,15 +200,27 @@ export function createTelegramMessageActivityTypingHooks<
   const ensureTyping = (ctx: TContext): void => {
     if (deps.hasActiveTurn()) deps.startTypingLoop(ctx);
   };
+  const handleMessageActivity = async (
+    phase: "start" | "update",
+    event: Parameters<TelegramLifecycleRegistrationDeps["onMessageStart"]>[0],
+    ctx: ExtensionContext,
+    inner: TelegramLifecycleRegistrationDeps["onMessageStart"],
+  ): Promise<void> => {
+    const typedCtx = ctx as TContext;
+    ensureTyping(typedCtx);
+    try {
+      await inner(event, ctx);
+    } catch (error) {
+      deps.recordRuntimeEvent?.("message-activity", error, { phase });
+    } finally {
+      ensureTyping(typedCtx);
+    }
+  };
   return {
-    onMessageStart: async (event, ctx) => {
-      ensureTyping(ctx as TContext);
-      await deps.onMessageStart(event, ctx);
-    },
-    onMessageUpdate: async (event, ctx) => {
-      ensureTyping(ctx as TContext);
-      await deps.onMessageUpdate(event, ctx);
-    },
+    onMessageStart: (event, ctx) =>
+      handleMessageActivity("start", event, ctx, deps.onMessageStart),
+    onMessageUpdate: (event, ctx) =>
+      handleMessageActivity("update", event, ctx, deps.onMessageUpdate),
   };
 }
 

package/lib/locks.ts

@@ -125,7 +125,10 @@ export function writeLocks(path: string, locks: Record<string, unknown>): void {
   mkdirSync(dirname(path), { recursive: true });
   const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
   try {
-    writeFileSync(tempPath, `${JSON.stringify(locks, null, 2)}\n`, "utf8");
+    writeFileSync(tempPath, `${JSON.stringify(locks, null, 2)}\n`, {
+      encoding: "utf8",
+      mode: 0o600,
+    });
     renameSync(tempPath, path);
   } catch (error) {
     try {

package/lib/outbound-buttons.ts

@@ -0,0 +1,226 @@
+/**
+ * Telegram outbound button helpers
+ * Zones: telegram outbound, assistant markup, callback routing
+ * Owns assistant-authored telegram_button extraction, button action storage, callback handling, and prompt-turn construction
+ */
+
+import { randomUUID } from "node:crypto";
+
+import type { TelegramInlineKeyboardMarkup } from "./keyboard.ts";
+import {
+  parseTelegramCommentAttributes,
+  parseTopLevelTelegramComment,
+  replaceTopLevelHtmlComments,
+} from "./outbound-markup.ts";
+import {
+  type PendingTelegramTurn,
+  truncateTelegramQueueSummary,
+} from "./queue.ts";
+
+const TELEGRAM_BUTTON_CALLBACK_PREFIX = "tgbtn";
+const TELEGRAM_BUTTON_ACTION_TTL_MS = 24 * 60 * 60 * 1000;
+
+export interface TelegramOutboundButtonAction {
+  text: string;
+  prompt: string;
+}
+
+export interface TelegramOutboundButtonStoredAction extends TelegramOutboundButtonAction {
+  createdAt: number;
+}
+
+export type TelegramOutboundButtonMarkup = TelegramInlineKeyboardMarkup;
+
+export interface TelegramButtonReplyPlan {
+  markdown: string;
+  replyMarkup?: TelegramOutboundButtonMarkup;
+}
+
+export interface TelegramButtonActionStore {
+  register: (action: TelegramOutboundButtonAction) => string;
+  resolve: (
+    callbackData: string | undefined,
+  ) => TelegramOutboundButtonAction | undefined;
+}
+
+export interface TelegramButtonCallbackQuery {
+  id: string;
+  data?: string;
+  message?: {
+    message_id?: number;
+    chat?: { id?: number };
+  };
+}
+
+export interface TelegramButtonCallbackHandlerDeps<TContext = unknown> {
+  resolveAction: (
+    callbackData: string | undefined,
+  ) => TelegramOutboundButtonAction | undefined;
+  answerCallbackQuery: (
+    callbackQueryId: string,
+    text?: string,
+  ) => Promise<void>;
+  enqueueButtonPrompt: (
+    query: TelegramButtonCallbackQuery,
+    action: TelegramOutboundButtonAction,
+    ctx: TContext,
+  ) => void;
+}
+
+function nowMs(): number {
+  return Date.now();
+}
+
+function normalizeMarkdownAfterButtonExtraction(markdown: string): string {
+  return markdown.replace(/\n{3,}/g, "\n\n").trim();
+}
+
+function parseButtonsCommentAttributes(input: string): {
+  label?: string;
+  prompt?: string;
+} {
+  const attributes = parseTelegramCommentAttributes(input);
+  return {
+    ...(attributes.label ? { label: attributes.label } : {}),
+    ...(attributes.prompt ? { prompt: attributes.prompt } : {}),
+  };
+}
+
+function parseButtonsCommentRows(
+  head: string,
+  body: string | undefined,
+): TelegramOutboundButtonAction[][] {
+  const trimmedHead = head.trim();
+
+  if (body === undefined) {
+    if (trimmedHead.startsWith(":")) {
+      const label = trimmedHead.slice(1).trim();
+      return label ? [[{ text: label, prompt: label }]] : [];
+    }
+    const attributes = parseButtonsCommentAttributes(head);
+    return attributes.label && attributes.prompt
+      ? [[{ text: attributes.label, prompt: attributes.prompt }]]
+      : [];
+  }
+
+  const label = parseButtonsCommentAttributes(head).label;
+  const prompt = body.trim();
+  if (!label || !prompt) return [];
+  return [[{ text: label, prompt }]];
+}
+
+export function createTelegramButtonActionStore(
+  options: { ttlMs?: number } = {},
+): TelegramButtonActionStore {
+  const ttlMs = options.ttlMs ?? TELEGRAM_BUTTON_ACTION_TTL_MS;
+  const actions = new Map<string, TelegramOutboundButtonStoredAction>();
+  function cleanup(currentTime: number): void {
+    for (const [key, action] of actions) {
+      if (currentTime - action.createdAt > ttlMs) actions.delete(key);
+    }
+  }
+  return {
+    register: (action) => {
+      const currentTime = nowMs();
+      cleanup(currentTime);
+      const key = `${TELEGRAM_BUTTON_CALLBACK_PREFIX}:${randomUUID().slice(0, 8)}`;
+      actions.set(key, { ...action, createdAt: currentTime });
+      return key;
+    },
+    resolve: (callbackData) => {
+      if (!callbackData?.startsWith(`${TELEGRAM_BUTTON_CALLBACK_PREFIX}:`)) {
+        return undefined;
+      }
+      const currentTime = nowMs();
+      cleanup(currentTime);
+      const action = actions.get(callbackData);
+      if (!action) return undefined;
+      return { text: action.text, prompt: action.prompt };
+    },
+  };
+}
+
+export function planTelegramButtonReply(
+  markdown: string,
+  deps: { registerAction: (action: TelegramOutboundButtonAction) => string },
+): TelegramButtonReplyPlan {
+  const keyboard: TelegramOutboundButtonMarkup["inline_keyboard"] = [];
+  const stripped = replaceTopLevelHtmlComments(markdown, (comment) => {
+    const command = parseTopLevelTelegramComment(comment, "telegram_button");
+    if (!command) return comment.raw;
+    const rows = parseButtonsCommentRows(command.head, command.body);
+    for (const row of rows) {
+      keyboard.push(
+        row.map((button) => ({
+          text: button.text,
+          callback_data: deps.registerAction(button),
+        })),
+      );
+    }
+    return "";
+  });
+  return {
+    markdown: normalizeMarkdownAfterButtonExtraction(stripped),
+    ...(keyboard.length > 0
+      ? { replyMarkup: { inline_keyboard: keyboard } }
+      : {}),
+  };
+}
+
+export function createTelegramButtonReplyPlanner(
+  store: Pick<TelegramButtonActionStore, "register">,
+): (markdown: string) => TelegramButtonReplyPlan {
+  return (markdown) =>
+    planTelegramButtonReply(markdown, { registerAction: store.register });
+}
+
+export function createTelegramButtonPromptTurn(options: {
+  chatId: number;
+  replyToMessageId: number;
+  queueOrder: number;
+  action: TelegramOutboundButtonAction;
+}): PendingTelegramTurn {
+  const prompt = `[telegram] ${options.action.prompt}`;
+  return {
+    kind: "prompt",
+    chatId: options.chatId,
+    replyToMessageId: options.replyToMessageId,
+    sourceMessageIds: [options.replyToMessageId],
+    queueOrder: options.queueOrder,
+    queueLane: "default",
+    laneOrder: options.queueOrder,
+    queuedAttachments: [],
+    content: [{ type: "text", text: prompt }],
+    historyText: options.action.prompt,
+    statusSummary: truncateTelegramQueueSummary(
+      options.action.text || options.action.prompt,
+    ),
+  };
+}
+
+export async function handleTelegramButtonCallbackQuery<TContext = unknown>(
+  query: TelegramButtonCallbackQuery,
+  ctx: TContext,
+  deps: TelegramButtonCallbackHandlerDeps<TContext>,
+): Promise<boolean> {
+  const action = deps.resolveAction(query.data);
+
+  if (!action) {
+    if (query.data?.startsWith(`${TELEGRAM_BUTTON_CALLBACK_PREFIX}:`)) {
+      await deps.answerCallbackQuery(query.id, "Button action expired.");
+      return true;
+    }
+    return false;
+  }
+
+  const chatId = query.message?.chat?.id;
+  const messageId = query.message?.message_id;
+  if (typeof chatId !== "number" || typeof messageId !== "number") {
+    await deps.answerCallbackQuery(query.id, "Button action expired.");
+    return true;
+  }
+
+  deps.enqueueButtonPrompt(query, action, ctx);
+  await deps.answerCallbackQuery(query.id, "Queued.");
+  return true;
+}