@llblab/pi-telegram 0.36.9 → 0.36.11

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## 0.36.11: At-Most-Once Prompt Dispatch Hotfix
+
+- `At-Most-Once Prompt Dispatch`: Commits each exact durable Telegram receipt synchronously before Pi model admission and blocks dispatch when that commit fails, closing the session/process-replacement replay window that could deliver an already-processed old prompt again; the narrow commit-before-admission crash boundary now favors no duplicate over retry.
+
+## 0.36.10: Transport-Fenced Typing Hotfix
+
+- `Typing Authority Fence`: Starts and continues Telegram typing activity only while the Pi instance has direct ownership or a live follower registration, stopping quietly when authority disappears so classic takeover cannot re-arm a stale loop or flood diagnostics with expected follower-registration errors.
+
 ## 0.36.9: Telegram Status And Generated Controls Hotfix
 
 - `Classic Takeover Status`: Keeps a classic-mode client visibly `disconnected` after another Pi instance takes Telegram ownership, preventing stale transport-side activity errors from overriding the authoritative connection state.

package/docs/architecture.md

@@ -198,7 +198,7 @@ All inbound updates are gated by the configured authorized user id.
 5. Coalesce media groups, likely split long text, and one adjacent forward-plus-comment pair in either order when needed.
 6. Download files with size limits and partial-download cleanup, then run configured/programmatic inbound handlers.
 7. Build a prompt or control queue item carrying an exact durable receipt for every contributing update id.
-8. Remove journal authority only after prompt handoff, control settlement, or durable follower acknowledgement; execution failures remain durable until automatic replay succeeds.
+8. Remove local prompt journal authority synchronously immediately before `sendUserMessage`, so session/process replacement can lose an unstarted prompt at that narrow crash boundary but can never replay a prompt already admitted to Pi; controls and foreign forwarding retain their explicit settlement boundaries.
 9. Handle `edited_message` updates separately while the original turn is still queued and dispatch only when all safety gates are clear.
 
 #### Durable Admission And Recovery
@@ -286,7 +286,7 @@ Dispatch requires:
 
 A dispatched prompt remains queued until `agent_start` consumes it. This keeps the active Telegram turn bound for previews, attachments, aborts, and final replies. A low-level `agent_end` error also retains that active turn because Pi may retry automatically; a later successful `agent_end` delivers through the original target and metadata, while `agent_settled` proves that an unrecovered error can be finalized once before queue dispatch resumes.
 
-Post-agent-end queue dispatch uses a session-bound deferred dispatcher. It is activated on session start, clears timers on shutdown, and skips callbacks from older generations before touching `ExtensionContext`. Dispatch stays session-bound after polling ownership moves elsewhere. When a queued Telegram prompt is forwarded into Pi, it uses a normal `sendUserMessage(content)` turn after the bridge's idle/dispatch guards pass; it does not use Pi's `followUp` delivery option or inject terminal input.
+Post-agent-end queue dispatch uses a session-bound deferred dispatcher. It is activated on session start, clears timers on shutdown, and skips callbacks from older generations before touching `ExtensionContext`. Dispatch stays session-bound after polling ownership moves elsewhere. When a queued Telegram prompt is forwarded into Pi, the bridge synchronously commits its exact durable receipt before calling normal `sendUserMessage(content)`; failed receipt commitment blocks dispatch, while the unavoidable crash window between commitment and Pi admission favors at-most-once execution over replay. It does not use Pi's `followUp` delivery option or inject terminal input.
 
 One monotonic session generation also fences agent/tool/message events, compaction callbacks, preview state, scheduled final delivery, controls, and shutdown. Distinct Pi context objects observed within one session adopt that generation; contexts already observed under an older generation remain stale after replacement. Session start invalidates pending preview work, delayed finals check their captured context before delivery, and shutdown rechecks after asynchronous polling/preview boundaries with a bounded preview-clear wait.
 

package/index.ts

@@ -465,6 +465,15 @@ export default function (pi: Pi.ExtensionAPI) {
       BusApi.createTelegramAggregateTypingActionSender(telegramApiRuntime),
     updateStatus,
     isContextActive: telegramSessionContextStore.isCurrent,
+    getTransportAuthority() {
+      if (ownsTelegramDirectDelivery()) {
+        const epoch = getCurrentLeaderEpoch();
+        return epoch === undefined ? undefined : `direct:${epoch}`;
+      }
+      if (!telegramBusFollowerRegistrationState.isRegistered()) return undefined;
+      const generation = telegramBusFollowerRegistrationState.getGeneration();
+      return generation ? `follower:${generation}` : undefined;
+    },
     recordRuntimeEvent,
   });
   const currentModelRuntime = Model.createCurrentModelRuntime({

package/lib/bindings.ts

@@ -68,6 +68,10 @@ export function createTelegramQueueBindingRuntime<TContext>(deps: {
             ctx: TContext,
           ) => void;
           isItemReady: (item: Queue.TelegramQueueItem<TContext>) => boolean;
+          onPromptHandedOff?: (
+            item: Queue.PendingTelegramTurn,
+            ctx: TContext,
+          ) => void;
           onControlSettled: (
             item: Queue.PendingTelegramControlItem<TContext>,
             ctx: TContext,
@@ -122,6 +126,13 @@ export function createTelegramQueueBindingRuntime<TContext>(deps: {
         (item.admissionReceipts?.length ?? 0) === 0
       );
     },
+    commitPromptDispatch(item, ctx) {
+      if ((item.admissionReceipts?.length ?? 0) === 0) return true;
+      const settlement = deps.admission.getSettlement();
+      if (!settlement?.onPromptHandedOff) return false;
+      settlement.onPromptHandedOff(item, ctx);
+      return !settlement.isItemReady(item);
+    },
     onControlSettled(item, ctx) {
       deps.admission.getSettlement()?.onControlSettled(item, ctx);
     },

package/lib/queue.ts

@@ -2836,6 +2836,9 @@ export interface TelegramDispatchRuntimeDeps<TContext = unknown> {
     >["item"],
   ) => void;
   onPromptDispatchStart: (chatId: number) => void;
+  commitPromptDispatch?: (
+    item: Extract<TelegramQueueDispatchAction<TContext>, { kind: "prompt" }>["item"],
+  ) => boolean;
   sendUserMessage: (
     content: Extract<
       TelegramQueueDispatchAction,
@@ -2859,6 +2862,10 @@ export interface TelegramQueueDispatchControllerDeps<
   updateStatus: (ctx: TContext, error?: string) => void;
   sendTextReply: TelegramControlRuntimeDeps<TContext>["sendTextReply"];
   onPromptDispatchStart: (ctx: TContext, chatId: number) => void;
+  commitPromptDispatch?: (
+    item: Extract<TelegramQueueDispatchAction<TContext>, { kind: "prompt" }>["item"],
+    ctx: TContext,
+  ) => boolean;
   sendUserMessage: TelegramDispatchRuntimeDeps<TContext>["sendUserMessage"];
   onPromptDispatchFailure: (ctx: TContext, message: string) => void;
   isQueueItemTransportActive?: (item: TelegramQueueItem<TContext>) => boolean;
@@ -2890,6 +2897,9 @@ export function executeTelegramQueueDispatchPlan<TContext = unknown>(
   }
   deps.onPromptDispatchStart(plan.item.chatId);
   try {
+    if (deps.commitPromptDispatch && !deps.commitPromptDispatch(plan.item)) {
+      throw new Error("Telegram prompt dispatch could not be committed durably.");
+    }
     deps.sendUserMessage(plan.item.content);
   } catch (error) {
     const message = getTelegramQueueErrorMessage(error);
@@ -2922,6 +2932,7 @@ export function createTelegramQueueDispatchRuntime<TContext = unknown>(
     updateStatus: deps.updateStatus,
     sendTextReply: deps.sendTextReply,
     onPromptDispatchStart: deps.onPromptDispatchStart,
+    commitPromptDispatch: deps.commitPromptDispatch,
     sendUserMessage: deps.sendUserMessage,
     onPromptDispatchFailure: deps.onPromptDispatchFailure,
     isQueueItemTransportActive: deps.isQueueItemTransportActive,
@@ -3061,6 +3072,9 @@ export function createTelegramQueueDispatchController<TContext = unknown>(
         onPromptDispatchStart: (chatId) => {
           deps.onPromptDispatchStart(ctx, chatId);
         },
+        commitPromptDispatch: deps.commitPromptDispatch
+          ? (item) => deps.commitPromptDispatch!(item, ctx)
+          : undefined,
         sendUserMessage: deps.sendUserMessage,
         onPromptDispatchFailure: (message) => {
           deps.onPromptDispatchFailure(ctx, message);

package/lib/runtime.ts

@@ -320,6 +320,8 @@ export interface TelegramTypingLoopDeps {
     options?: { message_thread_id?: number },
   ) => Promise<unknown>;
   sendAggregateTypingAction?: (chatId: number) => Promise<unknown>;
+  shouldContinue?: () => boolean;
+  onStopped?: () => void;
 }
 
 export interface TelegramRuntimeEventRecorderPort {
@@ -365,6 +367,8 @@ export interface TelegramTypingLoopStarterDeps<
   sendAggregateTypingAction?: (chatId: number) => Promise<unknown>;
   updateStatus: (ctx: TContext, error?: string) => void;
   isContextActive?: (ctx: TContext) => boolean;
+  isTransportAvailable?: () => boolean;
+  getTransportAuthority?: () => string | number | undefined;
   intervalMs?: number;
 }
 
@@ -376,15 +380,33 @@ export function createTelegramTypingLoopStarter<TContext>(
   options?: { target?: TelegramTypingLoopTarget },
 ) => void {
   return (ctx, chatId, options) => {
+    const transportAuthority = deps.getTransportAuthority?.();
+    const hasTransport = (): boolean =>
+      deps.getTransportAuthority
+        ? transportAuthority !== undefined &&
+          Object.is(deps.getTransportAuthority(), transportAuthority)
+        : deps.isTransportAvailable?.() !== false;
+    if (!hasTransport()) return;
+    let active = true;
     deps.typing.start({
       chatId: chatId ?? deps.getDefaultChatId(),
       target: options?.target,
       intervalMs: deps.intervalMs ?? TELEGRAM_TYPING_ACTION_INTERVAL_MS,
       sendTypingAction: async (targetChatId, actionOptions) => {
+        if (!active) return;
+        if (!hasTransport()) {
+          deps.typing.stop();
+          return;
+        }
         try {
           await deps.sendTypingAction(targetChatId, actionOptions);
         } catch (error) {
           if (deps.isContextActive?.(ctx) === false) return;
+          if (!active) return;
+          if (!hasTransport()) {
+            deps.typing.stop();
+            return;
+          }
           const message =
             error instanceof Error ? error.message : String(error);
           updateTelegramRuntimeStatusSafely(deps.updateStatus, ctx, {
@@ -404,10 +426,20 @@ export function createTelegramTypingLoopStarter<TContext>(
       },
       sendAggregateTypingAction: deps.sendAggregateTypingAction
         ? async (targetChatId) => {
+            if (!active) return;
+            if (!hasTransport()) {
+              deps.typing.stop();
+              return;
+            }
             try {
               await deps.sendAggregateTypingAction?.(targetChatId);
             } catch (error) {
               if (deps.isContextActive?.(ctx) === false) return;
+              if (!active) return;
+              if (!hasTransport()) {
+                deps.typing.stop();
+                return;
+              }
               const message =
                 error instanceof Error ? error.message : String(error);
               updateTelegramRuntimeStatusSafely(deps.updateStatus, ctx, {
@@ -427,6 +459,10 @@ export function createTelegramTypingLoopStarter<TContext>(
             }
           }
         : undefined,
+      shouldContinue: hasTransport,
+      onStopped: () => {
+        active = false;
+      },
     });
   };
 }
@@ -442,7 +478,12 @@ export function startTelegramTypingLoop(
 ): boolean {
   if (deps.chatId === undefined || deps.chatId === 0) return false;
   const previousKey = state.typingLoopKey;
+  const previousDeps = state.typingLoopDeps;
   const nextKey = getTelegramTypingLoopKey(deps);
+  if (previousDeps && previousDeps !== deps) {
+    previousDeps.onStopped?.();
+    state.typingInFlight = undefined;
+  }
   state.typingLoopDeps = deps;
   state.typingLoopKey = nextKey;
   const sendTyping = (): void => {
@@ -450,10 +491,14 @@ export function startTelegramTypingLoop(
     if (
       !activeDeps ||
       activeDeps.chatId === undefined ||
-      activeDeps.chatId === 0 ||
-      state.typingInFlight
+      activeDeps.chatId === 0
     )
       return;
+    if (activeDeps.shouldContinue?.() === false) {
+      stopTelegramTypingLoop(state);
+      return;
+    }
+    if (state.typingInFlight) return;
     const targetChatId = activeDeps.chatId;
     const threadParams = getTelegramTypingLoopThreadParams(activeDeps.target);
     const typing = Promise.resolve()
@@ -486,9 +531,12 @@ export function stopTelegramTypingLoop(
 ): boolean {
   if (!state.typingInterval) return false;
   clearInterval(state.typingInterval);
+  const activeDeps = state.typingLoopDeps;
   state.typingInterval = undefined;
   state.typingLoopDeps = undefined;
   state.typingLoopKey = undefined;
+  state.typingInFlight = undefined;
+  activeDeps?.onStopped?.();
   return true;
 }
 
@@ -571,6 +619,8 @@ export interface TelegramPromptDispatchRuntimeDeps<
   sendAggregateTypingAction?: (chatId: number) => Promise<unknown>;
   updateStatus: (ctx: TContext, error?: string) => void;
   isContextActive?: (ctx: TContext) => boolean;
+  isTransportAvailable?: () => boolean;
+  getTransportAuthority?: () => string | number | undefined;
   intervalMs?: number;
 }
 

package/package.json

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