@llblab/pi-telegram 0.16.5 → 0.16.6

package/BACKLOG.md

@@ -4,3 +4,5 @@
   - Context: `pi-telegram` is an extension/mobile companion, not a PTY supervisor. A soft `/new` that mutates session internals or filters context without TUI/runtime parity breaks the product boundary.
   - Requirement: only add Telegram `/new` when Pi exposes a safe public API that invokes the same session-replacement path as terminal `/new`, including lifecycle, active-run handling, and TUI rerender semantics.
   - Rejected for this extension: raw TTY injection, ANSI terminal clearing, private TUI container mutation, or running a shadow `pi` subprocess to control the current session.
+
+- [ ] Consider splitting `lib/bindings.ts` if lifecycle/tool wiring grows further.

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## Unreleased
 
+## 0.16.6: Telegram Review Hardening Hotfix
+
+- `[Guest Mode]` Deny `guest_message` updates until the bridge already has a paired Telegram user. Impact: guest mode can no longer become the first pairing surface or trigger guest file/handler processing before explicit DM pairing.
+- `[Lifecycle]` Unref the compaction observer fallback timer when the host timer supports it. Impact: headless or shutdown paths are less likely to linger until the 5-minute safety timeout.
+- `[Shutdown]` Stop polling before clearing active-turn/abort state, keep the abort controller visible until the polling promise settles, and record typing-cleanup failures without skipping polling abort. Impact: session shutdown and polling cleanup ordering is more deterministic.
+- `[Replies]` Scope transport-level reply deduplication by chat id. Impact: equal Telegram message ids in different chats no longer suppress valid reply metadata for each other.
+- `[Buttons]` Consume one-shot `telegram_button` callback actions after the first successful resolve. Impact: repeated taps on an old assistant-authored button no longer enqueue duplicate prompts.
+- `[Buttons]` Centralized Telegram `callback_data` byte-limit guards for generated inline keyboards outside the section helper path. Impact: oversized generated button callbacks fail locally before Telegram rejects the message.
+- `[Diagnostics]` Record `answerCallbackQuery` transport failures in runtime API diagnostics while keeping callback handling non-fatal. Impact: `/telegram-status` can explain failed Telegram callback acknowledgements instead of losing the signal silently.
+- `[Tests]` Added regressions for shutdown during pending control, long-text, and media-group dispatch, for settings menu callbacks persisting voice/time changes to `telegram.json`, for malformed/boundary Markdown rendering, and for runtime outbound delivery retrying a transient Telegram API failure. Impact: high-risk queue/timer/settings/rendering/API paths are pinned at the bridge boundary.
+- `[Docs]` Documented which environment-driven transport defaults should be set before launch because module-load constants intentionally capture them.
+- `[Backlog]` Captured and narrowed the non-blocking 2026-06 review-swarm follow-ups for lifecycle shutdown hardening, reply/callback/button state cleanup, validation coverage, and bindings maintainability.
+
 ## 0.16.5: Context-Aware Prompt Guidance Hotfix
 
 - `[Prompt Guidance]` Made before-agent-start Telegram guidance context-aware: unconfigured sessions receive no bridge suffix, local/TUI prompts receive only explicit direct-delivery guidance, and Telegram-originated turns keep the full inbound, phone-width, voice, and button contract. Impact: ordinary local replies no longer get raw Telegram action-comment syntax unless the current turn actually comes from Telegram.

package/README.md

@@ -68,6 +68,8 @@ Most day-to-day controls live in the Telegram menu or π commands. A few importa
 - **Inbound file limit**: `PI_TELEGRAM_INBOUND_FILE_MAX_BYTES` or `TELEGRAM_MAX_FILE_SIZE_BYTES` changes the default 50 MiB Telegram download limit.
 - **Outbound attachment limit**: `PI_TELEGRAM_OUTBOUND_ATTACHMENT_MAX_BYTES` or `TELEGRAM_MAX_ATTACHMENT_SIZE_BYTES` changes the default 50 MiB `telegram_attach` delivery limit.
 
+Set these variables before launching π. Some transport defaults (notably Telegram temp directory and inbound/outbound byte-limit constants) are intentionally captured when the extension modules load, while setup-token defaults and agent-dir lookups used by config/locks are read through their runtime helpers.
+
 ## Use
 
 Once paired, chat with your bot in Telegram. Text, images, files, replies, edits, media groups, and configured handler output are forwarded into π as Telegram-originated turns.

package/docs/architecture.md

@@ -117,7 +117,7 @@ Deleting `locks.json` resets runtime ownership without deleting Telegram configu
 
 1. Poll updates through `getUpdates`.
 2. Persist update offsets only after successful handling; repeated handler failures are bounded.
-3. Filter to the paired private user.
+3. Filter to the paired private user; guest-mode updates require an existing paired user and cannot establish first pairing.
 4. Dispatch owned callbacks and controls before fallback prompt forwarding.
 5. Coalesce media groups and likely split long text when needed.
 6. Download files into `~/.pi/agent/tmp/telegram` with size limits and partial-download cleanup.

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/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,
     });

package/lib/preview.ts

@@ -241,6 +241,7 @@ export interface TelegramPreviewMessageTransportDeps {
   sendMessage: (body: TelegramSendMessageBody) => Promise<TelegramSentMessage>;
   editMessageText: (body: TelegramEditMessageTextBody) => Promise<unknown>;
   buildReplyParameters?: (
+    chatId: number,
     replyToMessageId: number | undefined,
   ) => TelegramReplyParameters | undefined;
 }
@@ -252,7 +253,7 @@ export function createTelegramPreviewMessageTransport(
     deps.buildReplyParameters ?? buildTelegramReplyParameters;
   return {
     sendMessage: (chatId, text, options, replyToMessageId) => {
-      const replyParameters = getReplyParameters(replyToMessageId);
+      const replyParameters = getReplyParameters(chatId, replyToMessageId);
       return deps.sendMessage({
         chat_id: chatId,
         text,

package/lib/queue.ts

@@ -1439,6 +1439,7 @@ export async function shutdownTelegramSessionRuntime<TQueueItem>(
   deps: TelegramSessionShutdownRuntimeDeps<TQueueItem>,
 ): Promise<void> {
   deps.unbindDeferredDispatchContext?.();
+  await deps.stopPolling();
   deps.applyState(buildTelegramSessionShutdownState<TQueueItem>());
   deps.clearPendingMediaGroups();
   deps.clearModelMenuState();
@@ -1448,7 +1449,6 @@ export async function shutdownTelegramSessionRuntime<TQueueItem>(
   }
   deps.clearActiveTurn();
   deps.clearAbort();
-  await deps.stopPolling();
 }
 
 export type TelegramSessionLifecycleRuntimeDeps<

package/lib/replies.ts

@@ -4,6 +4,7 @@
  * Owns rendered-message delivery, reply transport wiring, and plain or markdown final replies
  */
 
+import { assertTelegramInlineKeyboardCallbackData } from "./keyboard.ts";
 import type {
   TelegramReplyParameters,
   TelegramSentMessage,
@@ -50,25 +51,29 @@ export function createReplyDedupRuntime(): ReplyDedupRuntime {
 
 // --- Transport-level dedup ---
 
-let lastRepliedToMessageId: number | undefined;
+const lastRepliedToMessageIdByChat = new Map<number, number>();
 
 export function resetTransportReplyDedup(): void {
-  lastRepliedToMessageId = undefined;
+  lastRepliedToMessageIdByChat.clear();
 }
 
 export function buildTelegramReplyParameters(
+  chatId: number,
   messageId: number | undefined,
 ): TelegramReplyParameters | undefined {
   if (messageId === undefined) return undefined;
-  if (messageId === lastRepliedToMessageId) return undefined;
-  lastRepliedToMessageId = messageId;
+  if (lastRepliedToMessageIdByChat.get(chatId) === messageId) {
+    return undefined;
+  }
+  lastRepliedToMessageIdByChat.set(chatId, messageId);
   return { message_id: messageId, allow_sending_without_reply: true };
 }
 
 export function buildTelegramMultipartReplyParameters(
+  chatId: number,
   messageId: number | undefined,
 ): string | undefined {
-  const parameters = buildTelegramReplyParameters(messageId);
+  const parameters = buildTelegramReplyParameters(chatId, messageId);
   return parameters ? JSON.stringify(parameters) : undefined;
 }
 
@@ -178,11 +183,12 @@ export async function sendTelegramRenderedChunks<TReplyMarkup>(
   deps: TelegramReplyDeliveryDeps<TReplyMarkup>,
   options?: { replyMarkup?: TReplyMarkup; replyToMessageId?: number },
 ): Promise<number | undefined> {
+  assertTelegramInlineKeyboardCallbackData(options?.replyMarkup);
   let lastMessageId: number | undefined;
   for (const [index, chunk] of chunks.entries()) {
     const replyParameters =
       index === 0
-        ? buildTelegramReplyParameters(options?.replyToMessageId)
+        ? buildTelegramReplyParameters(chatId, options?.replyToMessageId)
         : undefined;
     const sent = await deps.sendMessage({
       chat_id: chatId,
@@ -204,6 +210,7 @@ export async function editTelegramRenderedMessage<TReplyMarkup>(
   deps: TelegramReplyDeliveryDeps<TReplyMarkup>,
   options?: { replyMarkup?: TReplyMarkup },
 ): Promise<number | undefined> {
+  assertTelegramInlineKeyboardCallbackData(options?.replyMarkup);
   if (chunks.length === 0) return messageId;
   const [firstChunk, ...remainingChunks] = chunks;
   await deps.editMessage({

package/lib/sections.ts

@@ -4,10 +4,12 @@
  * Owns section registration, global registry binding, token mapping, main-menu/settings row injection, and section callback dispatch
  */
 
-import type { TelegramInlineKeyboardMarkup } from "./keyboard.ts";
+import {
+  assertTelegramCallbackData,
+  type TelegramInlineKeyboardMarkup,
+} from "./keyboard.ts";
 
 const SECTION_REGISTRY_KEY = "__piTelegramSectionRegistry__";
-const TELEGRAM_CALLBACK_DATA_MAX_BYTES = 64;
 
 // --- Core Types ---
 
@@ -301,10 +303,6 @@ const BACK_NAV_ROW = {
   text: "⬆️ Back",
 } as const;
 
-function getUtf8ByteLength(value: string): number {
-  return new TextEncoder().encode(value).byteLength;
-}
-
 function sectionErrorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
@@ -317,13 +315,7 @@ function buildTelegramSectionCallbackData(
   const data = payload
     ? `section:${token}:${action}:${payload}`
     : `section:${token}:${action}`;
-  const byteLength = getUtf8ByteLength(data);
-  if (byteLength > TELEGRAM_CALLBACK_DATA_MAX_BYTES) {
-    throw new Error(
-      `Telegram section callback_data exceeds ${TELEGRAM_CALLBACK_DATA_MAX_BYTES} bytes (${byteLength}). Use a shorter action/payload or store state behind a compact key.`,
-    );
-  }
-  return data;
+  return assertTelegramCallbackData(data, "Telegram section callback_data");
 }
 
 function prependBackRow(

package/lib/telegram-api.ts

@@ -234,6 +234,14 @@ export interface TelegramFileDownloadOptions {
   maxFileSizeBytes?: number;
 }
 
+export interface TelegramAnswerCallbackQueryOptions {
+  recordRuntimeEvent?: (
+    kind: "api",
+    error: unknown,
+    details?: Record<string, unknown>,
+  ) => void;
+}
+
 export interface TelegramApiClient {
   call: <TResponse>(
     method: string,
@@ -664,6 +672,7 @@ export async function answerTelegramCallbackQuery(
   botToken: string | undefined,
   callbackQueryId: string,
   text?: string,
+  options: TelegramAnswerCallbackQueryOptions = {},
 ): Promise<void> {
   try {
     await callTelegram<boolean>(
@@ -673,8 +682,10 @@ export async function answerTelegramCallbackQuery(
         ? { callback_query_id: callbackQueryId, text }
         : { callback_query_id: callbackQueryId },
     );
-  } catch {
-    // ignore
+  } catch (error) {
+    options.recordRuntimeEvent?.("api", error, {
+      method: "answerCallbackQuery",
+    });
   }
 }
 
@@ -705,7 +716,9 @@ export function createDefaultTelegramBridgeApiRuntime(deps: {
   recordRuntimeEvent: TelegramBridgeApiRuntimeDeps["recordRuntimeEvent"];
 }): TelegramBridgeApiRuntime {
   return createTelegramBridgeApiRuntime({
-    client: createTelegramApiClient(deps.getBotToken),
+    client: createTelegramApiClient(deps.getBotToken, {
+      recordRuntimeEvent: deps.recordRuntimeEvent,
+    }),
     tempDir: getTelegramApiTempDir(),
     maxFileSizeBytes: TELEGRAM_INBOUND_FILE_MAX_BYTES,
     tempFileMaxAgeMs: TELEGRAM_TEMP_FILE_MAX_AGE_MS,
@@ -834,8 +847,14 @@ export function createTelegramBridgeApiRuntime(
         throw error;
       }
     },
-    answerCallbackQuery: (callbackQueryId, text) => {
-      return deps.client.answerCallbackQuery(callbackQueryId, text);
+    answerCallbackQuery: async (callbackQueryId, text) => {
+      try {
+        await deps.client.answerCallbackQuery(callbackQueryId, text);
+      } catch (error) {
+        deps.recordRuntimeEvent("api", error, {
+          method: "answerCallbackQuery",
+        });
+      }
     },
     answerGuestQuery: (
       guestQueryId: string,
@@ -876,6 +895,7 @@ export function createTelegramBridgeApiRuntime(
  */
 export function createTelegramApiClient(
   getBotToken: () => string | undefined,
+  options: TelegramAnswerCallbackQueryOptions = {},
 ): TelegramApiClient {
   return {
     call: async (method, body, options) => {
@@ -909,7 +929,12 @@ export function createTelegramApiClient(
       );
     },
     answerCallbackQuery: async (callbackQueryId, text) => {
-      await answerTelegramCallbackQuery(getBotToken(), callbackQueryId, text);
+      await answerTelegramCallbackQuery(
+        getBotToken(),
+        callbackQueryId,
+        text,
+        options,
+      );
     },
   };
 }

package/lib/updates.ts

@@ -406,7 +406,8 @@ export function buildTelegramUpdateExecutionPlan<
       return {
         kind: "guest",
         guestMessage: action.guestMessage,
-        shouldDeny: action.authorization.kind === "deny",
+        // Guest mode is an extension of an already paired bridge, not a pairing surface.
+        shouldDeny: action.authorization.kind !== "allow",
       };
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.16.5",
+  "version": "0.16.6",
   "private": false,
   "publishConfig": {
     "access": "public"