@llblab/pi-kit 0.1.9 → 0.1.10

package/node_modules/@llblab/pi-telegram/lib/menu.ts

@@ -255,7 +255,10 @@ export interface TelegramMenuActionRuntimeDeps<
     chatId: number,
     replyToMessageId: number,
     text: string,
-    options?: { target?: { chatId: number; threadId?: number } },
+    options?: {
+      target?: { chatId: number; threadId?: number };
+      parseMode?: "HTML";
+    },
   ) => Promise<unknown>;
   sectionRegistry?: TelegramSectionRegistry;
   isVoiceReplyActive?: () => boolean;
@@ -798,8 +801,8 @@ export function createTelegramMenuActionRuntime<
           await deps.sendTextReply(
             chatId,
             replyToMessageId,
-            "Cannot open status while Pi is busy. Send /abort, /next, or /stop.",
-            { target: { chatId, threadId } },
+            "<b>⏳ Cannot open status while Pi is busy. Send /abort, /next, or /stop.</b>",
+            { target: { chatId, threadId }, parseMode: "HTML" },
           );
         },
         getModelMenuState: () => deps.getModelMenuState(chatId, ctx, threadId),
@@ -835,16 +838,16 @@ export function createTelegramMenuActionRuntime<
           await deps.sendTextReply(
             chatId,
             replyToMessageId,
-            "Cannot switch model while Pi is busy. Send /abort, /next, or /stop.",
-            { target: { chatId, threadId } },
+            "<b>⏳ Cannot switch model while Pi is busy. Send /abort, /next, or /stop.</b>",
+            { target: { chatId, threadId }, parseMode: "HTML" },
           );
         },
         sendNoModelsMessage: async () => {
           await deps.sendTextReply(
             chatId,
             replyToMessageId,
-            "No available models with configured auth.",
-            { target: { chatId, threadId } },
+            "<b>🚫 No available models with configured auth.</b>",
+            { target: { chatId, threadId }, parseMode: "HTML" },
           );
         },
         getModelMenuState: () => deps.getModelMenuState(chatId, ctx, threadId),

package/node_modules/@llblab/pi-telegram/lib/prompts.ts

@@ -14,11 +14,11 @@ export const TELEGRAM_DISCONNECTED_CONTEXT_MESSAGE =
 
 const LOCAL_SYSTEM_PROMPT_SUFFIX = `
 
-${TELEGRAM_CONNECTED_CONTEXT_MESSAGE} Load the \`telegram-bridge\` Skill for Telegram-originated turns or explicit requests involving Telegram delivery, actions, Threaded Mode, or diagnosis. Do not use Telegram-specific features from unrelated local/TUI prompts.`;
+${TELEGRAM_CONNECTED_CONTEXT_MESSAGE} For Telegram work, consult bundled Skills in routing order: \`telegram-bridge\` for the transport and turn protocol, \`generated-control-surface\` when contextual controls materially shorten feedback, then \`generative-apps\` when the interaction warrants a reusable deterministic app. Load a Skill only if its instructions are not already present in the current context. Do not use Telegram-specific features from unrelated local/TUI prompts.`;
 
 const TELEGRAM_TURN_SYSTEM_PROMPT_SUFFIX = `
 
-Telegram turn note: Load and follow the \`telegram-bridge\` Skill.`;
+Telegram turn note: Follow the applicable bundled Telegram Skills in routing order; load only missing instructions.`;
 
 export const TELEGRAM_ATTACH_PROMPT_SNIPPET =
   "Queue files for the active Telegram reply; outside Telegram turns, send files directly to Telegram.";

package/node_modules/@llblab/pi-telegram/lib/queue.ts

@@ -427,12 +427,22 @@ export function createTelegramTransportStampedQueueStore<TContext>(
   };
 }
 
+export function isTelegramQueueItemSkipped<TContext = unknown>(
+  item: TelegramQueueItem<TContext>,
+): boolean {
+  return item.kind === "prompt" && Boolean(item.reactionSuppressionEmoji);
+}
+
+export function countExecutableTelegramQueueItems<TContext = unknown>(
+  items: readonly TelegramQueueItem<TContext>[],
+): number {
+  return items.filter((item) => !isTelegramQueueItemSkipped(item)).length;
+}
+
 export function createTelegramQueueItemCountGetter<TContext = unknown>(
   store: Pick<TelegramQueueStore<TContext>, "getQueuedItems">,
 ): () => number {
-  return () => {
-    return store.getQueuedItems().length;
-  };
+  return () => countExecutableTelegramQueueItems(store.getQueuedItems());
 }
 
 export function createTelegramActiveTurnStore<
@@ -993,7 +1003,8 @@ export function consumeDispatchedTelegramPrompt<TContext = unknown>(
 export function formatQueuedTelegramItemsStatus<TContext = unknown>(
   items: TelegramQueueItem<TContext>[],
 ): string {
-  return items.length === 0 ? "" : ` +${items.length}`;
+  const count = countExecutableTelegramQueueItems(items);
+  return count === 0 ? "" : ` +${count}`;
 }
 
 export function truncateTelegramQueueSummary(
@@ -2062,6 +2073,7 @@ export interface TelegramSessionStartRuntimeDeps<TContext, TModel = unknown> {
 export interface TelegramSessionShutdownRuntimeDeps<TQueueItem> {
   isSessionActive?: () => boolean;
   unbindDeferredDispatchContext?: () => void;
+  discardQueuedItems?: () => void;
   applyState: (state: TelegramSessionShutdownState<TQueueItem>) => void;
   clearPendingMediaGroups: () => void;
   clearModelMenuState: () => void;
@@ -2090,6 +2102,7 @@ export interface TelegramSessionLifecycleHookRuntimeDeps<
   updateStatus: (ctx: TContext) => void;
   isSessionActive?: (ctx: TContext) => boolean;
   unbindDeferredDispatchContext?: () => void;
+  discardQueuedItems?: (ctx: TContext) => void;
   applySessionShutdownState: (
     state: TelegramSessionShutdownState<TQueueItem>,
   ) => void;
@@ -2286,6 +2299,7 @@ export async function shutdownTelegramSessionRuntime<TQueueItem>(
   deps.unbindDeferredDispatchContext?.();
   await deps.stopPolling();
   if (deps.isSessionActive?.() === false) return;
+  deps.discardQueuedItems?.();
   deps.applyState(buildTelegramSessionShutdownState<TQueueItem>());
   deps.clearPendingMediaGroups();
   deps.clearModelMenuState();
@@ -2339,6 +2353,7 @@ export function createTelegramSessionLifecycleRuntime<
     updateStatus: deps.updateStatus,
     isSessionActive: deps.isSessionActive,
     unbindDeferredDispatchContext: deps.unbindDeferredDispatchContext,
+    discardQueuedItems: deps.discardQueuedItems,
     applySessionShutdownState: stateApplier.applyShutdownState,
     clearPendingMediaGroups: deps.clearPendingMediaGroups,
     clearModelMenuState: deps.clearModelMenuState,
@@ -2387,6 +2402,10 @@ export function createTelegramSessionLifecycleHooks<
           isSessionActive: () =>
             ctx === undefined ? true : (deps.isSessionActive?.(ctx) ?? true),
           unbindDeferredDispatchContext: deps.unbindDeferredDispatchContext,
+          discardQueuedItems:
+            ctx === undefined || !deps.discardQueuedItems
+              ? undefined
+              : () => deps.discardQueuedItems!(ctx),
           applyState: deps.applySessionShutdownState,
           clearPendingMediaGroups: deps.clearPendingMediaGroups,
           clearModelMenuState: deps.clearModelMenuState,
@@ -2476,14 +2495,8 @@ export function clearTelegramQueueItemsRuntime<TContext>(
   const removedItems = deps.getQueuedItems();
   const removedCount = removedItems.length;
   if (removedCount === 0) return 0;
+  deps.onItemsDiscarded?.(removedItems, deps.ctx);
   deps.setQueuedItems([]);
-  try {
-    deps.onItemsDiscarded?.(removedItems, deps.ctx);
-  } catch (error) {
-    deps.recordRuntimeEvent?.("queue", error, {
-      phase: "discard-receipt-settlement",
-    });
-  }
   updateTelegramQueueStatusRuntime(deps);
   return removedCount;
 }
@@ -2877,6 +2890,7 @@ export interface TelegramQueueDispatchControllerDeps<
     item: PendingTelegramControlItem<TContext>,
     ctx: TContext,
   ) => void;
+  onPromptSkipped?: (item: PendingTelegramTurn, ctx: TContext) => boolean;
 }
 
 export interface TelegramQueueDispatchController<TContext = unknown> {
@@ -2940,6 +2954,7 @@ export function createTelegramQueueDispatchRuntime<TContext = unknown>(
       deps.hasPendingInboundQueueMutationForItem,
     isQueueItemAdmissionReady: deps.isQueueItemAdmissionReady,
     onControlSettled: deps.onControlSettled,
+    onPromptSkipped: deps.onPromptSkipped,
     recordRuntimeEvent: deps.recordRuntimeEvent,
   });
 }
@@ -3007,7 +3022,29 @@ export function createTelegramQueueDispatchController<TContext = unknown>(
             deps.updateStatus(ctx);
             return;
           }
+          try {
+            if (deps.onPromptSkipped && !deps.onPromptSkipped(candidate, ctx)) {
+              deps.updateStatus(
+                ctx,
+                "Telegram skipped prompt could not be settled durably.",
+              );
+              return;
+            }
+          } catch (error) {
+            deps.recordRuntimeEvent?.("dispatch", error, {
+              phase: "skip-receipt-settlement",
+            });
+            deps.updateStatus(
+              ctx,
+              "Telegram skipped prompt could not be settled durably.",
+            );
+            return;
+          }
           nextActiveIndex += 1;
+          deps.setQueuedItems([
+            ...activeItems.slice(nextActiveIndex),
+            ...protectedInactiveItems,
+          ]);
         }
       }
       const dispatchableItems = activeItems.slice(nextActiveIndex);
@@ -3031,7 +3068,7 @@ export function createTelegramQueueDispatchController<TContext = unknown>(
         dispatchableItems,
         canDispatch,
       );
-      if (nextActiveIndex > 0 || dispatchPlan.kind !== "none") {
+      if (dispatchPlan.kind !== "none") {
         deps.setQueuedItems([
           ...dispatchPlan.remainingItems,
           ...protectedInactiveItems,

package/node_modules/@llblab/pi-telegram/lib/routing.ts

@@ -1677,9 +1677,12 @@ export function createTelegramInboundRouteRuntime<
                   })
               : undefined,
             stopTypingLoop: deps.stopTypingLoop,
-            sendTextReply: (text) =>
+            sendTextReply: (text, options) =>
               deps
-                .sendTextReply(chatId, replyToMessageId, text, { target })
+                .sendTextReply(chatId, replyToMessageId, text, {
+                  target,
+                  parseMode: options?.parseMode,
+                })
                 .then(() => {}),
             suppressStartNotice: true,
             recordRuntimeEvent: deps.recordRuntimeEvent,

package/node_modules/@llblab/pi-telegram/lib/status.ts

@@ -344,6 +344,7 @@ export interface TelegramBridgeStatusRuntimeDeps<
   getActiveToolExecutions: () => number;
   hasPendingModelSwitch: () => boolean;
   getQueuedItems: () => TQueueItem[];
+  getQueuedItemCount?: (items: TQueueItem[]) => number;
   formatQueuedStatus: (items: TQueueItem[]) => string;
   getRecentRuntimeEvents: () => TelegramRuntimeEvent[];
   getRuntimeLockState?: () => string;
@@ -658,6 +659,7 @@ export function createTelegramBridgeStatusRuntime<
     getStatusBarState: (_ctx, error) => {
       const config = deps.getConfig();
       const queuedItems = deps.getQueuedItems();
+      const queuedItemCount = deps.getQueuedItemCount?.(queuedItems) ?? queuedItems.length;
       const hasActiveTurn = deps.hasActiveTurn();
       const hasPendingDispatch = deps.hasDispatchPending();
       const hasPendingModelSwitch = deps.hasPendingModelSwitch();
@@ -677,13 +679,13 @@ export function createTelegramBridgeStatusRuntime<
           hasPendingDispatch ||
           hasPendingModelSwitch ||
           activeToolExecutions > 0 ||
-          queuedItems.length > 0,
+          queuedItemCount > 0,
         processingStatus: getTelegramStatusBarProcessingStatus({
           hasActiveTurn,
           hasPendingDispatch,
           hasPendingModelSwitch,
           activeToolExecutions,
-          queuedItems: queuedItems.length,
+          queuedItems: queuedItemCount,
         }),
         queuedStatus: deps.formatQueuedStatus(queuedItems),
         error,

package/node_modules/@llblab/pi-telegram/lib/sync.ts

@@ -4,6 +4,7 @@
  * Owns pure contracts for deciding when local Telegram mirror state should be refreshed without querying Telegram on every action
  */
 
+import { getTelegramApiErrorRequestTarget } from "./telegram-api.ts";
 import { getTelegramTargetKey, type TelegramTarget } from "./target.ts";
 import * as ThreadReconciler from "./thread-reconciler.ts";
 import {
@@ -423,6 +424,22 @@ export function createTelegramStaleTopicApiErrorRecoveryRuntime<
     recoverStaleTelegramTopicApiError(apiBody, error, deps);
 }
 
+export async function settleStaleTelegramTopicExecutionFailure<
+  TSyncState extends TelegramSyncState,
+>(
+  error: unknown,
+  deps: TelegramStaleTopicApiErrorRecoveryDeps<TSyncState>,
+): Promise<boolean> {
+  const target = getTelegramApiErrorRequestTarget(error);
+  if (!target || !isTelegramTopicTargetStaleError(error)) return false;
+  await recoverStaleTelegramTopicApiError(
+    { chat_id: target.chatId, message_thread_id: target.threadId },
+    error,
+    deps,
+  );
+  return true;
+}
+
 export async function recoverStaleTelegramTopicApiError<
   TSyncState extends TelegramSyncState,
 >(

package/node_modules/@llblab/pi-telegram/lib/telegram-api.ts

@@ -587,6 +587,7 @@ export function isTelegramApiCommitUnknownError(
 class TelegramApiHttpError extends Error {
   readonly status: number | undefined;
   readonly retryAfterSeconds: number | undefined;
+  requestTarget?: { chatId: number; threadId: number };
   constructor(
     message: string,
     status: number | undefined,
@@ -598,6 +599,41 @@ class TelegramApiHttpError extends Error {
   }
 }
 
+function attachTelegramApiRequestTarget(
+  error: unknown,
+  body: Record<string, unknown> | Record<string, string>,
+): void {
+  if (!(error instanceof TelegramApiHttpError)) return;
+  const chatId = Number(body.chat_id);
+  const threadId = Number(body.message_thread_id);
+  if (!Number.isSafeInteger(chatId) || !Number.isSafeInteger(threadId)) return;
+  error.requestTarget = { chatId, threadId };
+}
+
+export class TelegramApiStaleTargetError extends Error {
+  readonly requestTarget: { chatId: number; threadId: number };
+
+  constructor(
+    message: string,
+    requestTarget: { chatId: number; threadId: number },
+  ) {
+    super(message);
+    this.name = "TelegramApiStaleTargetError";
+    this.requestTarget = { ...requestTarget };
+  }
+}
+
+export function getTelegramApiErrorRequestTarget(
+  error: unknown,
+): { chatId: number; threadId: number } | undefined {
+  const target =
+    error instanceof TelegramApiHttpError ||
+    error instanceof TelegramApiStaleTargetError
+      ? error.requestTarget
+      : undefined;
+  return target ? { ...target } : undefined;
+}
+
 export function isTelegramMessageNotModifiedError(error: unknown): boolean {
   return (
     error instanceof Error && error.message.includes("message is not modified")
@@ -1156,21 +1192,26 @@ export async function callTelegram<TResponse>(
   options?: TelegramApiCallOptions,
 ): Promise<TResponse> {
   const configuredBotToken = assertTelegramBotTokenConfigured(botToken);
-  return callTelegramWithRetry(
-    method,
-    async (family) =>
-      telegramFetch(
-        `${TELEGRAM_API_BASE}/bot${configuredBotToken}/${method}`,
-        {
-          method: "POST",
-          headers: { "content-type": "application/json" },
-          body: JSON.stringify(body),
-          signal: options?.signal,
-        },
-        family,
-      ),
-    options,
-  );
+  try {
+    return await callTelegramWithRetry(
+      method,
+      async (family) =>
+        telegramFetch(
+          `${TELEGRAM_API_BASE}/bot${configuredBotToken}/${method}`,
+          {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(body),
+            signal: options?.signal,
+          },
+          family,
+        ),
+      options,
+    );
+  } catch (error) {
+    attachTelegramApiRequestTarget(error, body);
+    throw error;
+  }
 }
 
 export type TelegramBotIdentityResponse = Pick<
@@ -1206,43 +1247,48 @@ export async function callTelegramMultipart<TResponse>(
 ): Promise<TResponse> {
   const configuredBotToken = assertTelegramBotTokenConfigured(botToken);
   const fileBlob = await openAsBlob(filePath);
-  return callTelegramWithRetry(
-    method,
-    async (family) => {
-      if (family) {
-        const multipart = await buildTelegramMultipartBody(
-          fields,
-          fileField,
-          fileBlob,
-          fileName,
-        );
+  try {
+    return await callTelegramWithRetry(
+      method,
+      async (family) => {
+        if (family) {
+          const multipart = await buildTelegramMultipartBody(
+            fields,
+            fileField,
+            fileBlob,
+            fileName,
+          );
+          return telegramFetch(
+            `${TELEGRAM_API_BASE}/bot${configuredBotToken}/${method}`,
+            {
+              method: "POST",
+              headers: { "content-type": multipart.contentType },
+              body: multipart.body as unknown as BodyInit,
+              signal: options?.signal,
+            },
+            family,
+          );
+        }
+        const form = new FormData();
+        for (const [key, value] of Object.entries(fields)) {
+          form.set(key, value);
+        }
+        form.set(fileField, fileBlob, fileName);
         return telegramFetch(
           `${TELEGRAM_API_BASE}/bot${configuredBotToken}/${method}`,
           {
             method: "POST",
-            headers: { "content-type": multipart.contentType },
-            body: multipart.body as unknown as BodyInit,
+            body: form,
             signal: options?.signal,
           },
-          family,
         );
-      }
-      const form = new FormData();
-      for (const [key, value] of Object.entries(fields)) {
-        form.set(key, value);
-      }
-      form.set(fileField, fileBlob, fileName);
-      return telegramFetch(
-        `${TELEGRAM_API_BASE}/bot${configuredBotToken}/${method}`,
-        {
-          method: "POST",
-          body: form,
-          signal: options?.signal,
-        },
-      );
-    },
-    options,
-  );
+      },
+      options,
+    );
+  } catch (error) {
+    attachTelegramApiRequestTarget(error, fields);
+    throw error;
+  }
 }
 
 export async function downloadTelegramFile(

package/node_modules/@llblab/pi-telegram/lib/threads.ts

@@ -2882,6 +2882,11 @@ export function getTelegramTargetFromApiBody(
 
 export function isTelegramTopicTargetStaleError(error: unknown): boolean {
   if (!(error instanceof Error)) return false;
+  const status =
+    "status" in error && typeof error.status === "number"
+      ? error.status
+      : undefined;
+  if (status !== undefined && status !== 400) return false;
   const message = error.message.toLowerCase();
   return (
     message.includes("topic_id_invalid") ||

package/node_modules/@llblab/pi-telegram/lib/updates.ts

@@ -1782,6 +1782,7 @@ export interface TelegramUpdateWorkerRuntimeDeps<TContext> {
   classifyExecutionFailure?: (
     error: unknown,
   ) => TelegramUpdateExecutionFailureClassification;
+  settleTerminalExecutionFailure?: (error: unknown) => Promise<boolean>;
   scheduleRetry?: (callback: () => void, delayMs: number) => unknown;
   cancelRetry?: (handle: unknown) => void;
   batchSize?: number;
@@ -4583,11 +4584,11 @@ export function createTelegramUpdateAdmissionLifecycleRuntime<TContext>(
         try {
           deps.recordRuntimeEvent?.(
             "inbound-worker",
-            "Recovered queued authority from a confirmed-dead process.",
+            "Discarded session-owned queue authority from a confirmed-dead process.",
             {
-              phase: "dead-queue-owner-recovery",
+              phase: "dead-queue-owner-cleanup",
               receiptId,
-              recoveredUpdateCount: result.recoveredUpdateIds.length,
+              removedUpdateCount: result.recoveredUpdateIds.length,
             },
           );
         } catch {
@@ -4833,13 +4834,20 @@ export function createTelegramUpdateAdmissionWorkerRuntime<
   });
   worker = createTelegramUpdateWorkerRuntime({
     ...deps,
-    executeUpdate: (update, ctx, signal) => {
+    async executeUpdate(update, ctx, signal) {
       const typedUpdate = update as TUpdate;
-      return executeUpdate(
-        deps.prepareUpdateForExecution?.(typedUpdate) ?? typedUpdate,
-        ctx,
-        signal,
-      );
+      try {
+        return await executeUpdate(
+          deps.prepareUpdateForExecution?.(typedUpdate) ?? typedUpdate,
+          ctx,
+          signal,
+        );
+      } catch (error) {
+        if (await deps.settleTerminalExecutionFailure?.(error)) {
+          return { kind: "complete" };
+        }
+        throw error;
+      }
     },
   });
   return worker;

package/node_modules/@llblab/pi-telegram/package.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-kit",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -42,8 +42,8 @@
   "dependencies": {
     "@llblab/pi-actors": "0.50.0",
     "@llblab/pi-codex-usage": "0.9.3",
-    "@llblab/pi-grow-loop": "0.7.2",
-    "@llblab/pi-telegram": "0.38.0"
+    "@llblab/pi-grow-loop": "0.7.3",
+    "@llblab/pi-telegram": "0.39.3"
   },
   "bundledDependencies": [
     "@llblab/pi-actors",