@llblab/pi-telegram 0.37.2 → 0.39.0

package/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/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/lib/updates.ts

@@ -4583,11 +4583,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 {

package/lib/voice.ts

@@ -38,15 +38,9 @@ function getNextAvailableProviderId<T>(
   return id;
 }
 
-export type TelegramVoiceReplyMode = "hidden" | "mirror" | "always";
+export type TelegramVoiceReplyMode = "manual" | "mirror" | "always";
 
-export type TelegramVoiceSynthesisProviderResult =
-  | string
-  | {
-      audioPath: string;
-      transcriptText?: string;
-    }
-  | undefined;
+export type TelegramVoiceSynthesisProviderResult = string | undefined;
 
 export interface TelegramVoiceTurnView {
   voiceReplyPreferred?: boolean;
@@ -215,7 +209,7 @@ export function clearTelegramVoiceTranscriptionProviders(): void {
 // --- Voice Reply Modes ---
 
 export const TELEGRAM_VOICE_REPLY_MODES = [
-  "hidden",
+  "manual",
   "mirror",
   "always",
 ] as const;
@@ -224,33 +218,15 @@ export const TELEGRAM_VOICE_REPLY_MODES = [
  * Returns the active voice reply mode for the current session.
  *
  * Pi-telegram owns reply-mode policy through telegram.json. If
- * config.voice.replyMode is missing, invalid, or legacy `manual`, the effective
- * mode is hidden.
+ * config.voice.replyMode is missing, invalid, or legacy `hidden`, the effective
+ * mode is manual.
  */
 export function getTelegramVoiceReplyMode(config?: {
   voice?: { replyMode?: string };
 }): TelegramVoiceReplyMode {
   const configMode = config?.voice?.replyMode;
-  if (
-    configMode &&
-    (TELEGRAM_VOICE_REPLY_MODES as readonly string[]).includes(configMode)
-  ) {
-    return configMode as TelegramVoiceReplyMode;
-  }
-  return "hidden";
-}
-
-/**
- * Returns whether the user wants the voice synthesis provider's transcript attached
- * as a caption on the voice message.
- *
- * Reads from `config.voice.sendTranscript`.
- * Default: false (no transcript text sent at all).
- */
-export function getTelegramVoiceSendTranscript(config?: {
-  voice?: { sendTranscript?: boolean };
-}): boolean {
-  return !!config?.voice?.sendTranscript;
+  if (configMode === "mirror" || configMode === "always") return configMode;
+  return "manual";
 }
 
 // --- Voice Turn Helpers ---

package/package.json

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

package/skills/telegram-bridge/SKILL.md

@@ -122,7 +122,7 @@ Prefer no-code command-template configuration in `telegram.json` before adding a
 - `outboundHandlers` transforms final replies.
 - Voice transcription handlers can match `type: "voice"` or `mime: "audio/*"`; stdout becomes `[outputs]`.
 
-When asked to configure voice rather than merely operate it, follow the provider-neutral contracts in `docs/voice.md`, `docs/inbound.md`, `docs/outbound.md`, and `docs/command-templates.md` from the pi-telegram package or repository. Inspect the available Skill catalog and trusted local executables for STT, TTS, and media conversion capabilities; check only whether required environment variables exist, never reveal their values. Preserve unrelated `telegram.json` fields, order multiple matching inbound handlers as fallbacks, require OGG/Opus output for native voice delivery, and validate each stage before a live Telegram smoke test. Keep `voice.replyMode` at its existing value unless the user requests a policy change: the default `hidden` mode is fully functional because explicit top-level `telegram_voice` actions still use the configured synthesis pipeline.
+When asked to configure voice rather than merely operate it, follow the provider-neutral contracts in `docs/voice.md`, `docs/inbound.md`, `docs/outbound.md`, and `docs/command-templates.md` from the pi-telegram package or repository. Inspect the available Skill catalog and trusted local executables for STT, TTS, and media conversion capabilities; check only whether required environment variables exist, never reveal their values. Preserve unrelated `telegram.json` fields, order multiple matching inbound handlers as fallbacks, require OGG/Opus output for native voice delivery, and validate each stage before a live Telegram smoke test. Keep `voice.replyMode` at its existing value unless the user requests a policy change: the default `manual` mode is fully functional because explicit top-level `telegram_voice` actions still use the configured synthesis pipeline.
 
 When configuration is insufficient, use documented `@llblab/pi-telegram/*` public API subpaths. Never import package-private `lib/*`, start another polling loop, or bypass bridge ownership with raw Bot API access.