@llblab/pi-telegram 0.6.1 → 0.6.2

package/docs/architecture.md

@@ -112,7 +112,7 @@ Dispatch is gated by:
 - `ctx.isIdle()` being true
 - `ctx.hasPendingMessages()` being false
 
-This prevents queue races around rapid follow-ups, `/compact`, and mixed local plus Telegram activity. Telegram `/status` and `/model` execute immediately; the dispatch controller still serializes any deferred control items so a queued control action must settle before the next queued action can dispatch.
+This prevents queue races around rapid follow-ups, `/compact`, and mixed local plus Telegram activity. Post-agent-end dispatch retries are scheduled through a session-bound deferred dispatcher that activates on session start, cancels timers on session shutdown, and skips callbacks from older generations before they touch `ExtensionContext`. Telegram `/status` and `/model` execute immediately; the dispatch controller still serializes any deferred control items so a queued control action must settle before the next queued action can dispatch.
 
 ### Abort Behavior
 

package/index.ts

@@ -46,10 +46,16 @@ export default function (pi: Pi.ExtensionAPI) {
   const runtimeEvents = Status.createTelegramRuntimeEventRecorder({
     getBotToken: configStore.getBotToken,
   });
-  const mediaGroupRuntime =
-    Media.createTelegramMediaGroupController<Api.TelegramMessage>();
+  const mediaGroupRuntime = Media.createTelegramMediaGroupController<
+    Api.TelegramMessage,
+    Pi.ExtensionContext
+  >();
   const telegramQueueStore =
     Queue.createTelegramQueueStore<Pi.ExtensionContext>();
+  const deferredQueueDispatchRuntime =
+    Queue.createTelegramDeferredQueueDispatchRuntime<Pi.ExtensionContext>({
+      recordRuntimeEvent: runtimeEvents.record,
+    });
   const pollingControllerState = Polling.createTelegramPollingControllerState();
   const { getStatusLines, updateStatus } =
     Status.createTelegramBridgeStatusRuntime<
@@ -88,12 +94,14 @@ export default function (pi: Pi.ExtensionAPI) {
       updateStatus,
     });
   const attachmentHandlerRuntime =
-    AttachmentHandlers.createTelegramAttachmentHandlerRuntime<Pi.ExtensionContext>({
-      getHandlers: configStore.getAttachmentHandlers,
-      execCommand: CommandTemplates.execCommandTemplate,
-      getCwd: Pi.getExtensionContextCwd,
-      recordRuntimeEvent: runtimeEvents.record,
-    });
+    AttachmentHandlers.createTelegramAttachmentHandlerRuntime<Pi.ExtensionContext>(
+      {
+        getHandlers: configStore.getAttachmentHandlers,
+        execCommand: CommandTemplates.execCommandTemplate,
+        getCwd: Pi.getExtensionContextCwd,
+        recordRuntimeEvent: runtimeEvents.record,
+      },
+    );
 
   // --- Telegram API ---
 
@@ -149,6 +157,7 @@ export default function (pi: Pi.ExtensionAPI) {
       hasDispatchPending: bridgeRuntime.lifecycle.hasDispatchPending,
       isIdle: Pi.isExtensionContextIdle,
       hasPendingMessages: Pi.hasExtensionContextPendingMessages,
+      hasDispatchContext: deferredQueueDispatchRuntime.isBound,
       updateStatus,
       sendTextReply,
       recordRuntimeEvent: runtimeEvents.record,
@@ -274,8 +283,10 @@ export default function (pi: Pi.ExtensionAPI) {
       setPendingModelSwitch: pendingModelSwitchStore.set,
       syncCounters: bridgeRuntime.queue.syncCounters,
       syncFlags: bridgeRuntime.lifecycle.syncFlags,
+      bindDeferredDispatchContext: deferredQueueDispatchRuntime.bind,
       prepareTempDir,
       updateStatus,
+      unbindDeferredDispatchContext: deferredQueueDispatchRuntime.unbind,
       clearPendingMediaGroups: mediaGroupRuntime.clear,
       clearModelMenuState: modelMenuRuntime.clear,
       getActiveTurnChatId: activeTurnRuntime.getChatId,
@@ -352,6 +363,8 @@ export default function (pi: Pi.ExtensionAPI) {
         clearDispatchPending: bridgeRuntime.lifecycle.clearDispatchPending,
       }),
       dispatchNextQueuedTelegramTurn,
+      requestDeferredDispatchNextQueuedTelegramTurn:
+        deferredQueueDispatchRuntime.request,
       clearPreview: previewRuntime.clear,
       setPreviewPendingText: previewRuntime.setPendingText,
       finalizeMarkdownPreview: previewRuntime.finalizeMarkdown,
@@ -362,16 +375,16 @@ export default function (pi: Pi.ExtensionAPI) {
         sendTextReply,
         recordRuntimeEvent: runtimeEvents.record,
       }),
-      planOutboundReply: OutboundHandlers.createTelegramOutboundReplyPlanner(
-        buttonActionStore,
-      ),
-      sendOutboundReplyArtifacts: OutboundHandlers.createTelegramOutboundReplyArtifactSender({
-        execCommand: CommandTemplates.execCommandTemplate,
-        sendMultipart: callMultipart,
-        sendTextReply,
-        getHandlers: configStore.getOutboundHandlers,
-        recordRuntimeEvent: runtimeEvents.record,
-      }),
+      planOutboundReply:
+        OutboundHandlers.createTelegramOutboundReplyPlanner(buttonActionStore),
+      sendOutboundReplyArtifacts:
+        OutboundHandlers.createTelegramOutboundReplyArtifactSender({
+          execCommand: CommandTemplates.execCommandTemplate,
+          sendMultipart: callMultipart,
+          sendTextReply,
+          getHandlers: configStore.getOutboundHandlers,
+          recordRuntimeEvent: runtimeEvents.record,
+        }),
       getActiveToolExecutions: bridgeRuntime.lifecycle.getActiveToolExecutions,
       setActiveToolExecutions: bridgeRuntime.lifecycle.setActiveToolExecutions,
       triggerPendingModelSwitchAbort: modelSwitchController.triggerPendingAbort,

package/lib/locks.ts

@@ -246,13 +246,6 @@ export function createTelegramLockedPollingRuntime<
     clearInterval(ownershipInterval);
     ownershipInterval = undefined;
   };
-  const updateStatusSafely = (ctx: TContext, phase: string) => {
-    try {
-      deps.updateStatus(ctx);
-    } catch (error) {
-      deps.recordRuntimeEvent?.("lock", error, { phase });
-    }
-  };
   const suspendPolling = async () => {
     stopOwnershipWatcher();
     if (ownershipStop) {
@@ -261,7 +254,7 @@ export function createTelegramLockedPollingRuntime<
     }
     await deps.stopPolling();
   };
-  const stopAfterOwnershipLoss = (ctx: TContext) => {
+  const stopAfterOwnershipLoss = () => {
     if (ownershipStop) return;
     stopOwnershipWatcher();
     ownershipStop = deps
@@ -271,7 +264,6 @@ export function createTelegramLockedPollingRuntime<
       )
       .finally(() => {
         ownershipStop = undefined;
-        updateStatusSafely(ctx, "ownership-loss-status");
       });
   };
   const startOwnershipWatcher = (ctx: TContext) => {
@@ -279,7 +271,7 @@ export function createTelegramLockedPollingRuntime<
     stopOwnershipWatcher();
     ownershipInterval = setInterval(() => {
       if (deps.lock.owns(owner)) return;
-      stopAfterOwnershipLoss(ctx);
+      stopAfterOwnershipLoss();
     }, ownershipCheckMs);
     ownershipInterval.unref?.();
   };

package/lib/media.ts

@@ -59,17 +59,20 @@ export interface TelegramMediaGroupMessage {
   media_group_id?: string;
 }
 
-export interface TelegramMediaGroupState<TMessage> {
+export interface TelegramMediaGroupState<TMessage, TContext = unknown> {
   messages: TMessage[];
+  context?: TContext;
   flushTimer?: ReturnType<typeof setTimeout>;
 }
 
 export interface TelegramMediaGroupController<
   TMessage extends TelegramMediaGroupMessage,
+  TContext = unknown,
 > {
   queueMessage: (options: {
     message: TMessage;
-    dispatchMessages: (messages: TMessage[]) => void;
+    context?: TContext;
+    dispatchMessages: (messages: TMessage[], ctx?: TContext) => void;
   }) => boolean;
   removeMessages: (messageIds: number[]) => number;
   clear: () => void;
@@ -79,7 +82,7 @@ export interface TelegramMediaGroupDispatchRuntimeDeps<
   TMessage extends TelegramMediaGroupMessage,
   TContext,
 > {
-  mediaGroups: TelegramMediaGroupController<TMessage>;
+  mediaGroups: TelegramMediaGroupController<TMessage, TContext>;
   dispatchMessages: (messages: TMessage[], ctx: TContext) => Promise<void>;
 }
 
@@ -249,7 +252,7 @@ export function getTelegramMediaGroupKey(
 export function removePendingTelegramMediaGroupMessages<
   TMessage extends TelegramMediaGroupMessage,
 >(
-  groups: Map<string, TelegramMediaGroupState<TMessage>>,
+  groups: Map<string, TelegramMediaGroupState<TMessage, unknown>>,
   messageIds: number[],
   clearTimer: (timer: ReturnType<typeof setTimeout>) => void,
 ): number {
@@ -273,24 +276,27 @@ export function removePendingTelegramMediaGroupMessages<
 
 export function queueTelegramMediaGroupMessage<
   TMessage extends TelegramMediaGroupMessage,
+  TContext = unknown,
 >(options: {
   message: TMessage;
-  groups: Map<string, TelegramMediaGroupState<TMessage>>;
+  context?: TContext;
+  groups: Map<string, TelegramMediaGroupState<TMessage, TContext>>;
   debounceMs: number;
   setTimer: (callback: () => void, ms: number) => ReturnType<typeof setTimeout>;
   clearTimer: (timer: ReturnType<typeof setTimeout>) => void;
-  dispatchMessages: (messages: TMessage[]) => void;
+  dispatchMessages: (messages: TMessage[], ctx?: TContext) => void;
 }): boolean {
   const key = getTelegramMediaGroupKey(options.message);
   if (!key) return false;
   const existing = options.groups.get(key) ?? { messages: [] };
   existing.messages.push(options.message);
+  existing.context = options.context;
   if (existing.flushTimer) options.clearTimer(existing.flushTimer);
   existing.flushTimer = options.setTimer(() => {
     const state = options.groups.get(key);
     options.groups.delete(key);
     if (!state) return;
-    options.dispatchMessages(state.messages);
+    options.dispatchMessages(state.messages, state.context);
   }, options.debounceMs);
   options.groups.set(key, existing);
   return true;
@@ -298,10 +304,11 @@ export function queueTelegramMediaGroupMessage<
 
 export function createTelegramMediaGroupController<
   TMessage extends TelegramMediaGroupMessage,
+  TContext = unknown,
 >(
   options: TelegramMediaGroupControllerOptions = {},
-): TelegramMediaGroupController<TMessage> {
-  const groups = new Map<string, TelegramMediaGroupState<TMessage>>();
+): TelegramMediaGroupController<TMessage, TContext> {
+  const groups = new Map<string, TelegramMediaGroupState<TMessage, TContext>>();
   const debounceMs = options.debounceMs ?? TELEGRAM_MEDIA_GROUP_DEBOUNCE_MS;
   const setTimer =
     options.setTimer ??
@@ -309,9 +316,10 @@ export function createTelegramMediaGroupController<
       setTimeout(callback, ms));
   const clearTimer = options.clearTimer ?? clearTimeout;
   return {
-    queueMessage: ({ message, dispatchMessages }) =>
+    queueMessage: ({ message, context, dispatchMessages }) =>
       queueTelegramMediaGroupMessage({
         message,
+        context,
         groups,
         debounceMs,
         setTimer,
@@ -339,8 +347,11 @@ export function createTelegramMediaGroupDispatchRuntime<
     handleMessage: async (message, ctx) => {
       const queuedMediaGroup = deps.mediaGroups.queueMessage({
         message,
-        dispatchMessages: (messages) => {
-          void deps.dispatchMessages(messages, ctx);
+        context: ctx,
+        dispatchMessages: (messages, queuedCtx) => {
+          if (queuedCtx !== undefined) {
+            void deps.dispatchMessages(messages, queuedCtx);
+          }
         },
       });
       if (queuedMediaGroup) return;

package/lib/polling.ts

@@ -97,7 +97,7 @@ export interface TelegramPollingRuntimeDeps<TContext> {
   setPollingController: (controller: AbortController | undefined) => void;
   stopTypingLoop: () => unknown;
   runPollLoop: (ctx: TContext, signal: AbortSignal) => Promise<void>;
-  updateStatus: (ctx: TContext) => void;
+  updateStatus: (ctx: TContext, message?: string) => void;
   createAbortController?: () => AbortController;
 }
 

package/lib/queue.ts

@@ -785,6 +785,9 @@ export interface TelegramAgentEndHookRuntimeDeps<
   resetRuntimeState: () => void;
   updateStatus: (ctx: TContext) => void;
   dispatchNextQueuedTelegramTurn: (ctx: TContext) => void;
+  requestDeferredDispatchNextQueuedTelegramTurn: (
+    dispatch: (ctx: TContext) => void,
+  ) => void;
   clearPreview: (chatId: number) => Promise<void>;
   setPreviewPendingText: (text: string) => void;
   finalizeMarkdownPreview: TelegramAgentEndRuntimeDeps<TTurn>["finalizeMarkdownPreview"];
@@ -882,7 +885,9 @@ export function createTelegramAgentEndHook<
       resetRuntimeState: deps.resetRuntimeState,
       updateStatus: () => deps.updateStatus(ctx),
       dispatchNextQueuedTelegramTurn: () => {
-        setTimeout(() => deps.dispatchNextQueuedTelegramTurn(ctx), 0);
+        deps.requestDeferredDispatchNextQueuedTelegramTurn(
+          deps.dispatchNextQueuedTelegramTurn,
+        );
       },
       clearPreview: deps.clearPreview,
       setPreviewPendingText: deps.setPreviewPendingText,
@@ -1020,15 +1025,18 @@ export interface TelegramSessionStateApplier<TQueueItem, TModel> {
   applyShutdownState: (state: TelegramSessionShutdownState<TQueueItem>) => void;
 }
 
-export interface TelegramSessionStartRuntimeDeps<TModel = unknown> {
+export interface TelegramSessionStartRuntimeDeps<TContext, TModel = unknown> {
+  ctx: TContext;
   currentModel: TModel | undefined;
   loadConfig: () => Promise<void>;
   applyState: (state: TelegramSessionStartState<TModel>) => void;
+  bindDeferredDispatchContext?: (ctx: TContext) => void;
   prepareTempDir: () => Promise<unknown>;
   updateStatus: () => void;
 }
 
 export interface TelegramSessionShutdownRuntimeDeps<TQueueItem> {
+  unbindDeferredDispatchContext?: () => void;
   applyState: (state: TelegramSessionShutdownState<TQueueItem>) => void;
   clearPendingMediaGroups: () => void;
   clearModelMenuState: () => void;
@@ -1047,8 +1055,10 @@ export interface TelegramSessionLifecycleHookRuntimeDeps<
   getCurrentModel: (ctx: TContext) => TModel | undefined;
   loadConfig: () => Promise<void>;
   applySessionStartState: (state: TelegramSessionStartState<TModel>) => void;
+  bindDeferredDispatchContext?: (ctx: TContext) => void;
   prepareTempDir: () => Promise<unknown>;
   updateStatus: (ctx: TContext) => void;
+  unbindDeferredDispatchContext?: () => void;
   applySessionShutdownState: (
     state: TelegramSessionShutdownState<TQueueItem>,
   ) => void;
@@ -1185,18 +1195,20 @@ export function buildTelegramSessionShutdownState<
   };
 }
 
-export async function startTelegramSessionRuntime<TModel = unknown>(
-  deps: TelegramSessionStartRuntimeDeps<TModel>,
+export async function startTelegramSessionRuntime<TContext, TModel = unknown>(
+  deps: TelegramSessionStartRuntimeDeps<TContext, TModel>,
 ): Promise<void> {
   await deps.loadConfig();
   deps.applyState(buildTelegramSessionStartState(deps.currentModel));
   await deps.prepareTempDir();
+  deps.bindDeferredDispatchContext?.(deps.ctx);
   deps.updateStatus();
 }
 
 export async function shutdownTelegramSessionRuntime<TQueueItem>(
   deps: TelegramSessionShutdownRuntimeDeps<TQueueItem>,
 ): Promise<void> {
+  deps.unbindDeferredDispatchContext?.();
   deps.applyState(buildTelegramSessionShutdownState<TQueueItem>());
   deps.clearPendingMediaGroups();
   deps.clearModelMenuState();
@@ -1235,8 +1247,10 @@ export function createTelegramSessionLifecycleRuntime<
     getCurrentModel: deps.getCurrentModel,
     loadConfig: deps.loadConfig,
     applySessionStartState: stateApplier.applyStartState,
+    bindDeferredDispatchContext: deps.bindDeferredDispatchContext,
     prepareTempDir: deps.prepareTempDir,
     updateStatus: deps.updateStatus,
+    unbindDeferredDispatchContext: deps.unbindDeferredDispatchContext,
     applySessionShutdownState: stateApplier.applyShutdownState,
     clearPendingMediaGroups: deps.clearPendingMediaGroups,
     clearModelMenuState: deps.clearModelMenuState,
@@ -1261,9 +1275,11 @@ export function createTelegramSessionLifecycleHooks<
     ): Promise<void> => {
       try {
         await startTelegramSessionRuntime({
+          ctx,
           currentModel: deps.getCurrentModel(ctx),
           loadConfig: deps.loadConfig,
           applyState: deps.applySessionStartState,
+          bindDeferredDispatchContext: deps.bindDeferredDispatchContext,
           prepareTempDir: deps.prepareTempDir,
           updateStatus: () => deps.updateStatus(ctx),
         });
@@ -1275,6 +1291,7 @@ export function createTelegramSessionLifecycleHooks<
     onSessionShutdown: async (): Promise<void> => {
       try {
         await shutdownTelegramSessionRuntime<TQueueItem>({
+          unbindDeferredDispatchContext: deps.unbindDeferredDispatchContext,
           applyState: deps.applySessionShutdownState,
           clearPendingMediaGroups: deps.clearPendingMediaGroups,
           clearModelMenuState: deps.clearModelMenuState,
@@ -1490,6 +1507,68 @@ export async function executeTelegramControlItemRuntime<TContext>(
   }
 }
 
+// --- Deferred Dispatch Runtime ---
+
+export interface TelegramDeferredQueueDispatchRuntimeDeps extends TelegramRuntimeEventRecorderPort {
+  delayMs?: number;
+  setTimer?: (
+    callback: () => void,
+    ms: number,
+  ) => ReturnType<typeof setTimeout>;
+  clearTimer?: (timer: ReturnType<typeof setTimeout>) => void;
+}
+
+export interface TelegramDeferredQueueDispatchRuntime<TContext = unknown> {
+  bind: (ctx: TContext) => void;
+  unbind: () => void;
+  isBound: () => boolean;
+  request: (dispatchNextQueuedTelegramTurn: (ctx: TContext) => void) => void;
+}
+
+export function createTelegramDeferredQueueDispatchRuntime<TContext = unknown>(
+  deps: TelegramDeferredQueueDispatchRuntimeDeps = {},
+): TelegramDeferredQueueDispatchRuntime<TContext> {
+  let boundContext: TContext | undefined;
+  let generation = 0;
+  const timers = new Set<ReturnType<typeof setTimeout>>();
+  const delayMs = deps.delayMs ?? 0;
+  const setTimer =
+    deps.setTimer ??
+    ((callback: () => void, ms: number): ReturnType<typeof setTimeout> =>
+      setTimeout(callback, ms));
+  const clearTimer =
+    deps.clearTimer ??
+    ((timer: ReturnType<typeof setTimeout>): void => clearTimeout(timer));
+  const clearTimers = (): void => {
+    for (const timer of timers) clearTimer(timer);
+    timers.clear();
+  };
+  return {
+    bind: (ctx) => {
+      boundContext = ctx;
+      generation += 1;
+    },
+    unbind: () => {
+      boundContext = undefined;
+      generation += 1;
+      clearTimers();
+    },
+    isBound: () => boundContext !== undefined,
+    request: (dispatchNextQueuedTelegramTurn) => {
+      if (boundContext === undefined) return;
+      const scheduledGeneration = generation;
+      let timer: ReturnType<typeof setTimeout>;
+      timer = setTimer(() => {
+        timers.delete(timer);
+        if (generation !== scheduledGeneration || boundContext === undefined)
+          return;
+        dispatchNextQueuedTelegramTurn(boundContext);
+      }, delayMs);
+      timers.add(timer);
+    },
+  };
+}
+
 // --- Dispatch Runtime ---
 
 export interface TelegramDispatchRuntimeDeps<TContext = unknown> {
@@ -1516,6 +1595,7 @@ export interface TelegramQueueDispatchControllerDeps<
   getQueuedItems: () => TelegramQueueItem<TContext>[];
   setQueuedItems: (items: TelegramQueueItem<TContext>[]) => void;
   canDispatch: (ctx: TContext) => boolean;
+  hasDispatchContext?: () => boolean;
   updateStatus: (ctx: TContext, error?: string) => void;
   sendTextReply: TelegramControlRuntimeDeps<TContext>["sendTextReply"];
   onPromptDispatchStart: (ctx: TContext, chatId: number) => void;
@@ -1567,6 +1647,7 @@ export function createTelegramQueueDispatchRuntime<TContext = unknown>(
       isIdle: deps.isIdle,
       hasPendingMessages: deps.hasPendingMessages,
     }),
+    hasDispatchContext: deps.hasDispatchContext,
     updateStatus: deps.updateStatus,
     sendTextReply: deps.sendTextReply,
     onPromptDispatchStart: deps.onPromptDispatchStart,
@@ -1582,6 +1663,7 @@ export function createTelegramQueueDispatchController<TContext = unknown>(
   let controlDispatchPending = false;
   const controller: TelegramQueueDispatchController<TContext> = {
     dispatchNext: (ctx) => {
+      if (deps.hasDispatchContext && !deps.hasDispatchContext()) return;
       if (controlDispatchPending) {
         deps.updateStatus(ctx);
         return;
@@ -1603,6 +1685,7 @@ export function createTelegramQueueDispatchController<TContext = unknown>(
             recordRuntimeEvent: deps.recordRuntimeEvent,
             onSettled: () => {
               controlDispatchPending = false;
+              if (deps.hasDispatchContext && !deps.hasDispatchContext()) return;
               deps.updateStatus(ctx);
               controller.dispatchNext(ctx);
             },

package/lib/routing.ts

@@ -41,7 +41,7 @@ export interface TelegramInboundRouteRuntimeDeps<
   >;
   bridgeRuntime: TelegramBridgeRuntime;
   activeTurnRuntime: Queue.TelegramActiveTurnStore;
-  mediaGroupRuntime: Media.TelegramMediaGroupController<TMessage>;
+  mediaGroupRuntime: Media.TelegramMediaGroupController<TMessage, TContext>;
   telegramQueueStore: Queue.TelegramQueueStateStore<TContext>;
   queueMutationRuntime: Queue.TelegramQueueMutationController<TContext>;
   modelMenuRuntime: Menu.TelegramModelMenuRuntime<TModel>;

package/lib/runtime.ts

@@ -353,7 +353,6 @@ export function createTelegramTypingLoopStarter<TContext>(
           deps.recordRuntimeEvent?.("typing", error, {
             chatId: targetChatId,
           });
-          deps.updateStatus(ctx, `typing failed: ${message}`);
         }
       },
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "private": false,
   "description": "Better Telegram DM bridge extension for pi",
   "type": "module",