@llblab/pi-telegram 0.54.4 → 0.55.0

package/lib/activity.ts

@@ -243,6 +243,7 @@ function createTelegramActivityContext(
 }
 
 interface TelegramActivityHandlerQueue {
+  notifyDrained?: () => void;
   registration: RegisteredTelegramActivityHandler;
   events: TelegramActivityEvent[];
   running: boolean;
@@ -287,6 +288,19 @@ function coalesceActivityEvents(
   return next;
 }
 
+/** Optional observation must not change queue/transport settlement. */
+function captureActivityDrainObserver(capture?: () => (() => void) | undefined): () => void {
+  try {
+    const notify = capture?.();
+    return () => {
+      try {
+        const emitted: unknown = notify?.();
+        if (emitted) void Promise.resolve(emitted).catch(() => undefined);
+      } catch { /* Observer failure is inert. */ }
+    };
+  } catch { return () => {}; }
+}
+
 /** @internal */
 export interface TelegramActivityDispatcher {
   hasPending?: () => boolean;
@@ -297,6 +311,7 @@ export interface TelegramActivityDispatcher {
 /** @internal */
 export function createTelegramActivityDispatcher(
   deps: {
+    captureDrain?: () => (() => void) | undefined;
     recordFailure?: (
       handlerId: string,
       event: TelegramActivityEvent,
@@ -306,6 +321,7 @@ export function createTelegramActivityDispatcher(
 ): TelegramActivityDispatcher {
   const queues = new Map<string, TelegramActivityHandlerQueue>();
   let stopped = false;
+  const hasPending = () => Array.from(queues.values()).some(queue => queue.active && (queue.running || queue.events.length > 0));
   const drain = async (queue: TelegramActivityHandlerQueue): Promise<void> => {
     if (queue.running || !queue.active) return;
     queue.running = true;
@@ -341,13 +357,11 @@ export function createTelegramActivityDispatcher(
       }
     } finally {
       queue.running = false;
+      if (!stopped && !hasPending()) queue.notifyDrained?.();
     }
   };
   return {
-    hasPending: () =>
-      Array.from(queues.values()).some(
-        (queue) => queue.active && (queue.running || queue.events.length > 0),
-      ),
+    hasPending,
     dispatch(event) {
       if (stopped) return;
       for (const registration of getTelegramActivityHandlers()) {
@@ -361,6 +375,8 @@ export function createTelegramActivityDispatcher(
           };
           queues.set(registration.id, queue);
         }
+        if (!queue.running && queue.events.length === 0)
+          queue.notifyDrained = captureActivityDrainObserver(deps.captureDrain);
         const previous = queue.events.at(-1);
         if (previous && canCoalesceActivityEvents(previous, event)) {
           queue.events[queue.events.length - 1] = coalesceActivityEvents(
@@ -389,6 +405,7 @@ export function createTelegramActivityDispatcher(
 /** @internal */
 export function createTelegramActivityBridgeRuntime(deps: {
   generation: string;
+  captureDrain?: () => (() => void) | undefined;
   observeEvent?: (event: TelegramActivityEvent) => void;
   recordFailure?: (
     handlerId: string,
@@ -407,6 +424,7 @@ export function createTelegramActivityBridgeRuntime(deps: {
       runtime = createTelegramActivityRuntime({
         generation: `${deps.generation}:${++generationSequence}`,
         dispatcher: createTelegramActivityDispatcher({
+          captureDrain: deps.captureDrain,
           recordFailure: deps.recordFailure,
         }),
         observeEvent: deps.observeEvent,
@@ -766,7 +784,9 @@ export interface TelegramActivityPublicationRuntime {
   reset: () => void;
 }
 
-export function createTelegramActivityPublicationRuntime(): TelegramActivityPublicationRuntime {
+export function createTelegramActivityPublicationRuntime(deps: {
+  captureDrain?: () => (() => void) | undefined;
+} = {}): TelegramActivityPublicationRuntime {
   let generation = 0;
   let tail = Promise.resolve();
   let outstanding = 0,
@@ -774,6 +794,7 @@ export function createTelegramActivityPublicationRuntime(): TelegramActivityPubl
   const pending = new Set<() => void>();
   const reserve = (): TelegramActivityPublicationReservation => {
     const admittedGeneration = generation;
+    const notifyDrained = captureActivityDrainObserver(deps.captureDrain);
     let state: "pending" | "published" | "cancelled" = "pending";
     let resolve!: (task: (() => Promise<void>) | undefined) => void;
     const ready = new Promise<(() => Promise<void>) | undefined>((accept) => {
@@ -794,6 +815,7 @@ export function createTelegramActivityPublicationRuntime(): TelegramActivityPubl
       })
       .finally(() => {
         outstanding -= 1;
+        if (admittedGeneration === generation && outstanding === 0 && !unconfirmed) notifyDrained();
       });
     tail = result.catch(() => {});
     return {
@@ -818,6 +840,7 @@ export function createTelegramActivityPublicationRuntime(): TelegramActivityPubl
     hasUnconfirmed: () => unconfirmed,
     beginWork() {
       const admittedGeneration = generation;
+      const notifyDrained = captureActivityDrainObserver(deps.captureDrain);
       let settled = false;
       outstanding += 1;
       return {
@@ -827,6 +850,7 @@ export function createTelegramActivityPublicationRuntime(): TelegramActivityPubl
           outstanding -= 1;
           if (outcome === "unconfirmed" && admittedGeneration === generation)
             unconfirmed = true;
+          if (admittedGeneration === generation && outstanding === 0 && !unconfirmed) notifyDrained();
         },
       };
     },

package/lib/bindings.ts

@@ -654,6 +654,7 @@ export interface TelegramActivityBindingRuntime {
 /** Compose public activity fanout, verbosity, and assistant output ordering. */
 export function createTelegramActivityBindingRuntime<TTransportStamp>(deps: {
   generation: string;
+  captureDrain?: () => (() => void) | undefined;
   assistantOutput: Omit<
     Parameters<
       typeof createTelegramAssistantOutputBindingRuntime<TTransportStamp>
@@ -669,7 +670,7 @@ export function createTelegramActivityBindingRuntime<TTransportStamp>(deps: {
     "captureAuthority" | "isAuthorityActive" | "recordFailure" | "enqueue"
   >;
 }): TelegramActivityBindingRuntime {
-  const publication = Activity.createTelegramActivityPublicationRuntime();
+  const publication = Activity.createTelegramActivityPublicationRuntime({ captureDrain: deps.captureDrain });
   const assistantOutputBinding = createTelegramAssistantOutputBindingRuntime({
     ...deps.assistantOutput,
     enqueue: publication.enqueue,
@@ -690,6 +691,7 @@ export function createTelegramActivityBindingRuntime<TTransportStamp>(deps: {
     });
   const activityRuntime = Activity.createTelegramActivityBridgeRuntime({
     generation: deps.generation,
+    captureDrain: deps.captureDrain,
     observeEvent(event) {
       assistantOutputBinding.observeEvent(event);
       activityVerbosityRuntime.accept(event);
@@ -1196,6 +1198,7 @@ interface TelegramLifecycleBindingDeps {
   }) => void;
   canSendAgentActivity: (ctx: Pi.ExtensionContext) => boolean;
   isSessionContextActive: (ctx: Pi.ExtensionContext) => boolean;
+  getSessionGeneration?: () => number;
   isTurnTransportActive?: (turn: Queue.PendingTelegramTurn) => boolean;
   updateStatus: TelegramBridgeStatusUpdater;
   recordRuntimeEvent: TelegramRuntimeEventRecorder;
@@ -1246,6 +1249,7 @@ export function registerTelegramLifecycleRuntimeHooks({
   recordMessageOwnership,
   canSendAgentActivity,
   isSessionContextActive = () => true,
+  getSessionGeneration,
   isTurnTransportActive,
   updateStatus,
   recordRuntimeEvent,
@@ -1550,6 +1554,8 @@ export function registerTelegramLifecycleRuntimeHooks({
   const messageActivityTypingHooks =
     Lifecycle.createTelegramMessageActivityTypingHooks({
       hasActiveTurn: activeTurnRuntime.has,
+      isContextActive: isSessionContextActive,
+      getSessionGeneration,
       startTypingLoop: startActiveTurnTypingLoop,
       onMessageStart: previewRuntime.onMessageStart,
       onMessageUpdate: previewRuntime.onMessageUpdate,
@@ -1638,9 +1644,11 @@ export function registerTelegramLifecycleRuntimeHooks({
     },
     async onAgentStart(event, ctx) {
       if (!isSessionContextActive(ctx)) return;
+      const generation = getSessionGeneration?.();
       agentWorkActive = true;
       cancelPendingFinalPublication();
       await agentStartWithDedupReset(event, ctx);
+      if (!isSessionContextActive(ctx) || (getSessionGeneration && !Object.is(getSessionGeneration(), generation))) return;
       const turn = activeTurnRuntime.get();
       activityRuntime.onAgentStart(turn?.target, turn?.replyToMessageId);
       startAgentActivityTypingLoop(ctx);

package/lib/bus-api.ts

@@ -23,10 +23,12 @@ import type {
   TelegramSendRichMessageBody,
   TelegramSendRichMessageDraftBody,
   TelegramSentMessage,
+  TelegramTypingActionOptions,
   TelegramUpdate,
 } from "./telegram-api.ts";
 import {
   buildTelegramAnswerGuestQueryBody,
+  assertTelegramApiCallAuthority,
   isTelegramApiCommitUnknownError,
   isTelegramMessageNotModifiedError,
   TelegramApiAuthorityError,
@@ -36,6 +38,7 @@ import {
 export type TelegramBusApiCall = (
   method: string,
   args: unknown[],
+  localOptions?: Pick<TelegramApiCallOptions, "assertAuthority">,
 ) => Promise<unknown>;
 
 export interface TelegramBusAwareApiRuntimeDeps {
@@ -235,8 +238,9 @@ function sendTelegramFollowerChatAction(
   >,
   chatId: number,
   action: string,
-  options?: { message_thread_id?: number },
+  options?: TelegramTypingActionOptions,
 ): Promise<boolean> {
+  assertTelegramApiCallAuthority(options?.assertAuthority, false);
   const body = withDefaultThreadTarget(
     {
       chat_id: chatId,
@@ -247,7 +251,11 @@ function sendTelegramFollowerChatAction(
     },
     deps.getDefaultTarget?.(),
   );
-  return deps.callFollowerApi("call", ["sendChatAction", body]).then(asBoolean);
+  // Only plain single-attempt policy crosses IPC; the captured assertion is a local issuance fence.
+  const args = ["sendChatAction", body, ...(action === "typing"
+    ? [{ maxAttempts: 1, retrySafety: "non-idempotent" }] : [])];
+  return deps.callFollowerApi("call", args, options?.assertAuthority
+    ? { assertAuthority: options.assertAuthority } : undefined).then(asBoolean);
 }
 
 export function createTelegramBusAwareApiRuntime(
@@ -345,7 +353,7 @@ export function createTelegramBusAwareApiRuntime(
     },
     sendTypingAction(
       chatId: number,
-      options?: { message_thread_id?: number },
+      options?: TelegramTypingActionOptions,
     ): Promise<unknown> {
       return deps.ownsDirect()
         ? deps.directRuntime.sendTypingAction(chatId, options)