@llblab/pi-telegram 0.16.5 → 0.17.0

package/docs/ui-style.md

@@ -46,7 +46,7 @@ Examples:
 
 ## Boolean Toggles
 
-Boolean settings use a horizontal `On` / `Off` pair, like a checkbox stretched across two buttons.
+Boolean settings use a horizontal `On` / `Off` pair.
 
 Rules:
 

package/index.ts

@@ -147,6 +147,8 @@ export default function (pi: Pi.ExtensionAPI) {
     sendRecordVoiceAction,
     sendMessageDraft,
     sendMessage,
+    sendRichMessage,
+    sendRichMessageDraft,
     downloadFile: downloadTelegramBridgeFile,
     editMessageText: editTelegramMessageText,
     answerCallbackQuery,
@@ -161,7 +163,6 @@ export default function (pi: Pi.ExtensionAPI) {
   // --- Message Delivery ---
 
   const sendGuestReply = Replies.createGuestMarkdownReplySender({
-    renderTelegramMessage: Replies.renderTelegramMessage,
     answerGuestQuery,
   });
 
@@ -189,6 +190,7 @@ export default function (pi: Pi.ExtensionAPI) {
 
   const replyRuntime = Replies.createTelegramRenderedMessageDeliveryRuntime({
     sendMessage,
+    sendRichMessage,
     editMessage: editTelegramMessageText,
   });
   const { replyTransport, editInteractiveMessage, sendInteractiveMessage } =
@@ -221,9 +223,16 @@ export default function (pi: Pi.ExtensionAPI) {
     isAssistantMessage: Replies.isAssistantAgentMessage,
     getMessageText: Replies.getAgentMessageText,
     getDefaultReplyToMessageId: activeTurnRuntime.getReplyToMessageId,
-    sendDraft: sendMessageDraft,
+    sendDraft: TelegramApi.createTelegramNativeMarkdownDraftSender({
+      sendMessageDraft,
+      sendRichMessageDraft,
+    }),
     sendMessage,
     editMessageText: editTelegramMessageText,
+    sendMarkdownReply,
+    editMarkdownMessage: Preview.createTelegramNativeMarkdownMessageEditor({
+      editMessageText: editTelegramMessageText,
+    }),
     recordRuntimeEvent,
     ...replyTransport,
   });

package/lib/commands.ts

@@ -494,7 +494,7 @@ export interface TelegramCompactConfirmationDeps {
   sendInteractiveMessage: (
     chatId: number,
     text: string,
-    mode: "html" | "plain",
+    mode: "markdown" | "html" | "plain",
     replyMarkup: TelegramCompactConfirmationReplyMarkup,
   ) => Promise<number | undefined>;
 }
@@ -515,7 +515,7 @@ export interface TelegramCompactConfirmationCallbackDeps<TContext> {
     chatId: number,
     messageId: number,
     text: string,
-    mode: "html" | "plain",
+    mode: "markdown" | "html" | "plain",
     replyMarkup: TelegramCompactConfirmationReplyMarkup,
   ) => Promise<void>;
   runCompact: (

package/lib/keyboard.ts

@@ -12,3 +12,42 @@ export interface TelegramInlineKeyboardButton {
 export interface TelegramInlineKeyboardMarkup {
   inline_keyboard: TelegramInlineKeyboardButton[][];
 }
+
+export const TELEGRAM_CALLBACK_DATA_MAX_BYTES = 64;
+
+export function getTelegramCallbackDataByteLength(value: string): number {
+  return new TextEncoder().encode(value).byteLength;
+}
+
+export function assertTelegramCallbackData(
+  callbackData: string,
+  context = "Telegram callback_data",
+): string {
+  const byteLength = getTelegramCallbackDataByteLength(callbackData);
+  if (byteLength > TELEGRAM_CALLBACK_DATA_MAX_BYTES) {
+    throw new Error(
+      `${context} exceeds ${TELEGRAM_CALLBACK_DATA_MAX_BYTES} bytes (${byteLength}). Use a shorter action/payload or store state behind a compact key.`,
+    );
+  }
+  return callbackData;
+}
+
+export function assertTelegramInlineKeyboardCallbackData(
+  replyMarkup: unknown,
+  context = "Telegram inline keyboard callback_data",
+): void {
+  if (!replyMarkup || typeof replyMarkup !== "object") return;
+  const keyboard = (replyMarkup as { inline_keyboard?: unknown })
+    .inline_keyboard;
+  if (!Array.isArray(keyboard)) return;
+  for (const row of keyboard) {
+    if (!Array.isArray(row)) continue;
+    for (const button of row) {
+      if (!button || typeof button !== "object") continue;
+      const callbackData = (button as { callback_data?: unknown })
+        .callback_data;
+      if (typeof callbackData !== "string") continue;
+      assertTelegramCallbackData(callbackData, context);
+    }
+  }
+}

package/lib/lifecycle.ts

@@ -138,6 +138,11 @@ export function createTelegramSessionContextTracker(
 
 type TelegramLifecycleTimer = number | ReturnType<typeof setTimeout>;
 
+function unrefTelegramLifecycleTimer(timer: TelegramLifecycleTimer): void {
+  if (!timer || typeof timer !== "object") return;
+  if (typeof timer.unref === "function") timer.unref();
+}
+
 export interface TelegramCompactionObserverRuntimeDeps<TContext> {
   setCompactionInProgress: (inProgress: boolean) => void;
   updateStatus: (ctx: TContext) => void;
@@ -196,6 +201,7 @@ export function createTelegramCompactionObserverRuntime<TContext>(
         );
         requestDispatch();
       }, timeoutMs);
+      unrefTelegramLifecycleTimer(fallbackTimer);
     },
     onSessionCompact: (_event, ctx) => {
       clearFallbackTimer();

package/lib/menu-model.ts

@@ -128,13 +128,13 @@ export interface TelegramMenuMessageRuntimeDeps {
     chatId: number,
     messageId: number,
     text: string,
-    mode: "html" | "plain",
+    mode: "markdown" | "html" | "plain",
     replyMarkup: TelegramReplyMarkup,
   ) => Promise<void>;
   sendInteractiveMessage: (
     chatId: number,
     text: string,
-    mode: "html" | "plain",
+    mode: "markdown" | "html" | "plain",
     replyMarkup: TelegramReplyMarkup,
   ) => Promise<number | undefined>;
 }
@@ -200,7 +200,7 @@ export interface TelegramModelMenuPage<TModel extends MenuModel = MenuModel> {
 export interface TelegramMenuRenderPayload {
   nextMode: TelegramModelMenuState["mode"];
   text: string;
-  mode: "html" | "plain";
+  mode: "markdown" | "html" | "plain";
   replyMarkup: TelegramReplyMarkup;
 }
 

package/lib/menu-settings.ts

@@ -98,13 +98,13 @@ export interface TelegramSettingsMenuRuntimeDeps<
     chatId: number,
     messageId: number,
     text: string,
-    mode: "html" | "plain",
+    mode: "markdown" | "html" | "plain",
     replyMarkup: TelegramSettingsMenuReplyMarkup,
   ) => Promise<void>;
   sendInteractiveMessage: (
     chatId: number,
     text: string,
-    mode: "html" | "plain",
+    mode: "markdown" | "html" | "plain",
     replyMarkup: TelegramSettingsMenuReplyMarkup,
   ) => Promise<number | undefined>;
   answerCallbackQuery: (

package/lib/menu.ts

@@ -228,13 +228,13 @@ export interface TelegramMenuCallbackRuntimeDeps<
     chatId: number,
     messageId: number,
     text: string,
-    mode: "html" | "plain",
+    mode: "markdown" | "html" | "plain",
     replyMarkup: TelegramReplyMarkup,
   ) => Promise<void>;
   sendInteractiveMessage?: (
     chatId: number,
     text: string,
-    mode: "html" | "plain",
+    mode: "markdown" | "html" | "plain",
     replyMarkup: TelegramReplyMarkup,
   ) => Promise<number | undefined>;
   enqueueSectionPrompt?: (prompt: string, ctx: TContext) => Promise<void>;
@@ -464,13 +464,13 @@ export interface TelegramMenuCallbackRuntimeAdapterDeps<
     chatId: number,
     messageId: number,
     text: string,
-    mode: "html" | "plain",
+    mode: "markdown" | "html" | "plain",
     replyMarkup: TelegramReplyMarkup,
   ) => Promise<void>;
   sendInteractiveMessage?: (
     chatId: number,
     text: string,
-    mode: "html" | "plain",
+    mode: "markdown" | "html" | "plain",
     replyMarkup: TelegramReplyMarkup,
   ) => Promise<number | undefined>;
   enqueueSectionPrompt?: (prompt: string, ctx: TContext) => Promise<void>;

package/lib/outbound-attachments.ts

@@ -474,6 +474,7 @@ export async function sendQueuedTelegramOutboundAttachments(
       const method = isPhoto ? "sendPhoto" : "sendDocument";
       const fieldName = isPhoto ? "photo" : "document";
       const replyParameters = buildTelegramMultipartReplyParameters(
+        turn.chatId,
         turn.replyToMessageId,
       );
       await deps.sendMultipart(

package/lib/outbound-buttons.ts

@@ -135,6 +135,7 @@ export function createTelegramButtonActionStore(
       cleanup(currentTime);
       const action = actions.get(callbackData);
       if (!action) return undefined;
+      actions.delete(callbackData);
       return { text: action.text, prompt: action.prompt };
     },
   };

package/lib/outbound-voice.ts

@@ -7,6 +7,7 @@
 import { unlink } from "node:fs/promises";
 import { basename, extname } from "node:path";
 
+import { assertTelegramInlineKeyboardCallbackData } from "./keyboard.ts";
 import { getTelegramVoiceSynthesisProviders } from "./voice.ts";
 
 export interface TelegramVoiceReplyTurnView {
@@ -125,6 +126,7 @@ export function createTelegramVoiceReplySender<THandler = unknown>(
     },
   ): Promise<void> {
     const voiceFilePath = await ensureTelegramVoiceFileFormat(filePath);
+    assertTelegramInlineKeyboardCallbackData(options?.replyMarkup);
     await sendVoiceChatAction(deps, turn.chatId);
     const replyParameters = buildVoiceReplyParameters(
       options?.replyToPrompt,

package/lib/polling.ts

@@ -187,11 +187,21 @@ export function shouldStartTelegramPolling(
 export async function stopTelegramPollingRuntime<TContext>(
   deps: TelegramPollingRuntimeDeps<TContext>,
 ): Promise<void> {
-  deps.stopTypingLoop();
-  deps.getPollingController()?.abort();
-  deps.setPollingController(undefined);
-  await deps.getPollingPromise()?.catch(() => undefined);
-  deps.setPollingPromise(undefined);
+  const pollingPromise = deps.getPollingPromise();
+  const pollingController = deps.getPollingController();
+  try {
+    deps.stopTypingLoop();
+  } catch (error) {
+    deps.recordRuntimeEvent?.("polling", error, { phase: "typing-stop" });
+  }
+  pollingController?.abort();
+  await pollingPromise?.catch(() => undefined);
+  if (deps.getPollingPromise() === pollingPromise) {
+    deps.setPollingPromise(undefined);
+  }
+  if (deps.getPollingController() === pollingController) {
+    deps.setPollingController(undefined);
+  }
 }
 
 function updateTelegramPollingStatusSafely<TContext>(
@@ -224,9 +234,12 @@ export function startTelegramPollingRuntime<TContext>(
   }
   const controller = deps.createAbortController?.() ?? new AbortController();
   deps.setPollingController(controller);
-  const promise = deps.runPollLoop(ctx, controller.signal).finally(() => {
-    deps.setPollingPromise(undefined);
-    deps.setPollingController(undefined);
+  let promise: Promise<void>;
+  promise = deps.runPollLoop(ctx, controller.signal).finally(() => {
+    if (deps.getPollingPromise() === promise) deps.setPollingPromise(undefined);
+    if (deps.getPollingController() === controller) {
+      deps.setPollingController(undefined);
+    }
     updateTelegramPollingStatusSafely(deps.updateStatus, ctx, {
       recordRuntimeEvent: deps.recordRuntimeEvent,
     });