@llblab/pi-kit 0.31.2 → 0.33.0

package/node_modules/@llblab/pi-telegram/dist/lib/activity.js

@@ -116,10 +116,28 @@ function coalesceActivityEvents(previous, next) {
     }
     return next;
 }
+/** Optional observation must not change queue/transport settlement. */
+function captureActivityDrainObserver(capture) {
+    try {
+        const notify = capture?.();
+        return () => {
+            try {
+                const emitted = notify?.();
+                if (emitted)
+                    void Promise.resolve(emitted).catch(() => undefined);
+            }
+            catch { /* Observer failure is inert. */ }
+        };
+    }
+    catch {
+        return () => { };
+    }
+}
 /** @internal */
 export function createTelegramActivityDispatcher(deps = {}) {
     const queues = new Map();
     let stopped = false;
+    const hasPending = () => Array.from(queues.values()).some(queue => queue.active && (queue.running || queue.events.length > 0));
     const drain = async (queue) => {
         if (queue.running || !queue.active)
             return;
@@ -146,10 +164,12 @@ export function createTelegramActivityDispatcher(deps = {}) {
         }
         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;
@@ -164,6 +184,8 @@ export function createTelegramActivityDispatcher(deps = {}) {
                     };
                     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(previous, event);
@@ -198,6 +220,7 @@ export function createTelegramActivityBridgeRuntime(deps) {
             runtime = createTelegramActivityRuntime({
                 generation: `${deps.generation}:${++generationSequence}`,
                 dispatcher: createTelegramActivityDispatcher({
+                    captureDrain: deps.captureDrain,
                     recordFailure: deps.recordFailure,
                 }),
                 observeEvent: deps.observeEvent,
@@ -470,13 +493,14 @@ export function createTelegramActivityRuntime(deps) {
         },
     };
 }
-export function createTelegramActivityPublicationRuntime() {
+export function createTelegramActivityPublicationRuntime(deps = {}) {
     let generation = 0;
     let tail = Promise.resolve();
     let outstanding = 0, unconfirmed = false;
     const pending = new Set();
     const reserve = () => {
         const admittedGeneration = generation;
+        const notifyDrained = captureActivityDrainObserver(deps.captureDrain);
         let state = "pending";
         let resolve;
         const ready = new Promise((accept) => {
@@ -499,6 +523,8 @@ export function createTelegramActivityPublicationRuntime() {
         })
             .finally(() => {
             outstanding -= 1;
+            if (admittedGeneration === generation && outstanding === 0 && !unconfirmed)
+                notifyDrained();
         });
         tail = result.catch(() => { });
         return {
@@ -522,6 +548,7 @@ export function createTelegramActivityPublicationRuntime() {
         hasUnconfirmed: () => unconfirmed,
         beginWork() {
             const admittedGeneration = generation;
+            const notifyDrained = captureActivityDrainObserver(deps.captureDrain);
             let settled = false;
             outstanding += 1;
             return {
@@ -532,6 +559,8 @@ export function createTelegramActivityPublicationRuntime() {
                     outstanding -= 1;
                     if (outcome === "unconfirmed" && admittedGeneration === generation)
                         unconfirmed = true;
+                    if (admittedGeneration === generation && outstanding === 0 && !unconfirmed)
+                        notifyDrained();
                 },
             };
         },

package/node_modules/@llblab/pi-telegram/dist/lib/bindings.d.ts

@@ -177,6 +177,7 @@ export interface TelegramActivityBindingRuntime {
 /** Compose public activity fanout, verbosity, and assistant output ordering. */
 export declare function createTelegramActivityBindingRuntime<TTransportStamp>(deps: {
     generation: string;
+    captureDrain?: () => (() => void) | undefined;
     assistantOutput: Omit<Parameters<typeof createTelegramAssistantOutputBindingRuntime<TTransportStamp>>[0], "waitForActivityIdle" | "enqueue">;
     activityVerbosity: Omit<Parameters<typeof ActivityVerbosity.createTelegramActivityVerbosityRuntime<TelegramAssistantOutputAuthority<TTransportStamp>>>[0], "captureAuthority" | "isAuthorityActive" | "recordFailure" | "enqueue">;
 }): TelegramActivityBindingRuntime;
@@ -288,11 +289,12 @@ interface TelegramLifecycleBindingDeps {
     }) => void;
     canSendAgentActivity: (ctx: Pi.ExtensionContext) => boolean;
     isSessionContextActive: (ctx: Pi.ExtensionContext) => boolean;
+    getSessionGeneration?: () => number;
     isTurnTransportActive?: (turn: Queue.PendingTelegramTurn) => boolean;
     updateStatus: TelegramBridgeStatusUpdater;
     recordRuntimeEvent: TelegramRuntimeEventRecorder;
     /** Settled-session hint for owners that wait on agent idleness, such as old-tab cleanup after a live rebind. */
     onSessionSettled?: (ctx: Pi.ExtensionContext) => void;
 }
-export declare function registerTelegramLifecycleRuntimeHooks({ pi, publicationRuntime, activityRuntime, activityVerbosityRuntime, diagnostics, assistantOutputRuntime, sessionLifecycleRuntime, configStore, abort, typing, lifecycle, activeTurnRuntime, telegramQueueStore, modelSwitchController, previewRuntime, promptDispatchRuntime, deferredQueueDispatchRuntime, modelContextAvailabilityRuntime, disconnectOnQuit, onSessionStarted, shutdownGenerativeAppLiveSurfaces, resolveAutomaticThreadCleanupEnabled, buttonActionStore, callMultipart, sendChatAction, sendRecordVoiceAction, sendMarkdownReply, sendTextReply, dispatchNextQueuedTelegramTurn, onPromptHandedOff, answerGuestQuery, deleteMessage, sendGuestReply, editGuestReply, stopGuestPlaceholder, preparePreviewDelivery, finalizeMarkdownPreview, proactivePushTargetGetter, getAssistantRenderingMode, recordMessageOwnership, canSendAgentActivity, isSessionContextActive, isTurnTransportActive, updateStatus, recordRuntimeEvent, onSessionSettled, }: TelegramLifecycleBindingDeps): void;
+export declare function registerTelegramLifecycleRuntimeHooks({ pi, publicationRuntime, activityRuntime, activityVerbosityRuntime, diagnostics, assistantOutputRuntime, sessionLifecycleRuntime, configStore, abort, typing, lifecycle, activeTurnRuntime, telegramQueueStore, modelSwitchController, previewRuntime, promptDispatchRuntime, deferredQueueDispatchRuntime, modelContextAvailabilityRuntime, disconnectOnQuit, onSessionStarted, shutdownGenerativeAppLiveSurfaces, resolveAutomaticThreadCleanupEnabled, buttonActionStore, callMultipart, sendChatAction, sendRecordVoiceAction, sendMarkdownReply, sendTextReply, dispatchNextQueuedTelegramTurn, onPromptHandedOff, answerGuestQuery, deleteMessage, sendGuestReply, editGuestReply, stopGuestPlaceholder, preparePreviewDelivery, finalizeMarkdownPreview, proactivePushTargetGetter, getAssistantRenderingMode, recordMessageOwnership, canSendAgentActivity, isSessionContextActive, getSessionGeneration, isTurnTransportActive, updateStatus, recordRuntimeEvent, onSessionSettled, }: TelegramLifecycleBindingDeps): void;
 export {};

package/node_modules/@llblab/pi-telegram/dist/lib/bindings.js

@@ -354,7 +354,7 @@ export function createTelegramAssistantOutputBindingRuntime(deps) {
 }
 /** Compose public activity fanout, verbosity, and assistant output ordering. */
 export function createTelegramActivityBindingRuntime(deps) {
-    const publication = Activity.createTelegramActivityPublicationRuntime();
+    const publication = Activity.createTelegramActivityPublicationRuntime({ captureDrain: deps.captureDrain });
     const assistantOutputBinding = createTelegramAssistantOutputBindingRuntime({
         ...deps.assistantOutput,
         enqueue: publication.enqueue,
@@ -374,6 +374,7 @@ export function createTelegramActivityBindingRuntime(deps) {
     });
     const activityRuntime = Activity.createTelegramActivityBridgeRuntime({
         generation: deps.generation,
+        captureDrain: deps.captureDrain,
         observeEvent(event) {
             assistantOutputBinding.observeEvent(event);
             activityVerbosityRuntime.accept(event);
@@ -626,7 +627,7 @@ export function registerTelegramCommandsAndTools({ pi, agentDir, configStore, pe
         },
     });
 }
-export function registerTelegramLifecycleRuntimeHooks({ pi, publicationRuntime, activityRuntime, activityVerbosityRuntime, diagnostics, assistantOutputRuntime, sessionLifecycleRuntime, configStore, abort, typing, lifecycle, activeTurnRuntime, telegramQueueStore, modelSwitchController, previewRuntime, promptDispatchRuntime, deferredQueueDispatchRuntime, modelContextAvailabilityRuntime, disconnectOnQuit, onSessionStarted, shutdownGenerativeAppLiveSurfaces, resolveAutomaticThreadCleanupEnabled, buttonActionStore, callMultipart, sendChatAction, sendRecordVoiceAction, sendMarkdownReply, sendTextReply, dispatchNextQueuedTelegramTurn, onPromptHandedOff, answerGuestQuery, deleteMessage, sendGuestReply, editGuestReply, stopGuestPlaceholder, preparePreviewDelivery, finalizeMarkdownPreview, proactivePushTargetGetter, getAssistantRenderingMode, recordMessageOwnership, canSendAgentActivity, isSessionContextActive = () => true, isTurnTransportActive, updateStatus, recordRuntimeEvent, onSessionSettled, }) {
+export function registerTelegramLifecycleRuntimeHooks({ pi, publicationRuntime, activityRuntime, activityVerbosityRuntime, diagnostics, assistantOutputRuntime, sessionLifecycleRuntime, configStore, abort, typing, lifecycle, activeTurnRuntime, telegramQueueStore, modelSwitchController, previewRuntime, promptDispatchRuntime, deferredQueueDispatchRuntime, modelContextAvailabilityRuntime, disconnectOnQuit, onSessionStarted, shutdownGenerativeAppLiveSurfaces, resolveAutomaticThreadCleanupEnabled, buttonActionStore, callMultipart, sendChatAction, sendRecordVoiceAction, sendMarkdownReply, sendTextReply, dispatchNextQueuedTelegramTurn, onPromptHandedOff, answerGuestQuery, deleteMessage, sendGuestReply, editGuestReply, stopGuestPlaceholder, preparePreviewDelivery, finalizeMarkdownPreview, proactivePushTargetGetter, getAssistantRenderingMode, recordMessageOwnership, canSendAgentActivity, isSessionContextActive = () => true, getSessionGeneration, isTurnTransportActive, updateStatus, recordRuntimeEvent, onSessionSettled, }) {
     const agentEndResetter = Runtime.createTelegramAgentEndResetter({
         abort,
         typing,
@@ -864,6 +865,8 @@ export function registerTelegramLifecycleRuntimeHooks({ pi, publicationRuntime,
     });
     const messageActivityTypingHooks = Lifecycle.createTelegramMessageActivityTypingHooks({
         hasActiveTurn: activeTurnRuntime.has,
+        isContextActive: isSessionContextActive,
+        getSessionGeneration,
         startTypingLoop: startActiveTurnTypingLoop,
         onMessageStart: previewRuntime.onMessageStart,
         onMessageUpdate: previewRuntime.onMessageUpdate,
@@ -955,9 +958,12 @@ export function registerTelegramLifecycleRuntimeHooks({ pi, publicationRuntime,
         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/node_modules/@llblab/pi-telegram/dist/lib/bus-api.d.ts

@@ -4,8 +4,8 @@
  * Wraps the direct Telegram Bot API runtime so follower instances can route outbound calls through the bus leader
  */
 import { type TelegramBusSelectedMenuDeliveryObservation, type TelegramBusSelectedMenuTextEffect } from "./bus.ts";
-import type { TelegramBridgeApiRuntime } from "./telegram-api.ts";
-export type TelegramBusApiCall = (method: string, args: unknown[]) => Promise<unknown>;
+import type { TelegramApiCallOptions, TelegramBridgeApiRuntime } from "./telegram-api.ts";
+export type TelegramBusApiCall = (method: string, args: unknown[], localOptions?: Pick<TelegramApiCallOptions, "assertAuthority">) => Promise<unknown>;
 export interface TelegramBusAwareApiRuntimeDeps {
     directRuntime: TelegramBridgeApiRuntime;
     ownsDirect: () => boolean;

package/node_modules/@llblab/pi-telegram/dist/lib/bus-api.js

@@ -4,7 +4,7 @@
  * Wraps the direct Telegram Bot API runtime so follower instances can route outbound calls through the bus leader
  */
 import { markTelegramBusCrossTargetDelivery, parseTelegramBusSelectedMenuTextEffect, stripTelegramBusApiMetadata, } from "./bus.js";
-import { buildTelegramAnswerGuestQueryBody, isTelegramApiCommitUnknownError, isTelegramMessageNotModifiedError, TelegramApiAuthorityError, TelegramApiCommitUnknownError, } from "./telegram-api.js";
+import { buildTelegramAnswerGuestQueryBody, assertTelegramApiCallAuthority, isTelegramApiCommitUnknownError, isTelegramMessageNotModifiedError, TelegramApiAuthorityError, TelegramApiCommitUnknownError, } from "./telegram-api.js";
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
         ? value
@@ -142,6 +142,7 @@ export function createTelegramSelectedMenuTextApi(deps) {
 }
 /** Followers route every chat action through the leader's generic `sendChatAction` call. */
 function sendTelegramFollowerChatAction(deps, chatId, action, options) {
+    assertTelegramApiCallAuthority(options?.assertAuthority, false);
     const body = withDefaultThreadTarget({
         chat_id: chatId,
         action,
@@ -149,7 +150,11 @@ function sendTelegramFollowerChatAction(deps, chatId, action, options) {
             ? { message_thread_id: options.message_thread_id }
             : {}),
     }, 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(deps) {
     return {

package/node_modules/@llblab/pi-telegram/dist/lib/bus-follower.d.ts

@@ -12,8 +12,10 @@ import { TELEGRAM_BUS_CAPABILITY_LIVE_REBIND_APPLY, TELEGRAM_BUS_CAPABILITY_SELE
 import type { TelegramConfigStore, TelegramThreadDisplayMode } from "./config.ts";
 import { type TelegramUpdateJournalStoreOptions } from "./journal.ts";
 import { type TelegramLockEntry, type TelegramLockState } from "./locks.ts";
+import * as Machine from "./machine.ts";
 import type { TelegramQueueHandoffStageResult } from "./queue.ts";
 import { type TelegramTarget } from "./target.ts";
+import { type TelegramApiCallOptions } from "./telegram-api.ts";
 import * as Threads from "./threads.ts";
 import { type TelegramWorkspaceAdmissionLedger } from "./workspace-admission.ts";
 export declare const TELEGRAM_BUS_FOLLOWER_HEARTBEAT_TIMEOUT_MS = 8000;
@@ -343,7 +345,9 @@ export declare function createTelegramBusFollowerWorkspaceRestoreHandler<TContex
         expectedTarget?: TelegramTarget & {
             threadId: number;
         };
-        release?: (canRelease: () => boolean) => void;
+        release?: (canRelease: () => boolean, target: TelegramTarget & {
+            threadId: number;
+        }) => void;
         observeWork?: (oldTarget: TelegramTarget & {
             threadId: number;
         }) => void;
@@ -362,7 +366,7 @@ export declare function createTelegramBusFollowerWorkspaceRestoreHandler<TContex
 };
 export declare function createTelegramBusFollowerClientRuntime<TContext, TReactionUpdate, TCallbackQuery, TMessage = unknown>(deps: TelegramBusFollowerClientRuntimeDeps<TMessage>): {
     createRequestId: () => string;
-    callApi: (method: string, args: unknown[]) => Promise<unknown>;
+    callApi: (method: string, args: unknown[], localOptions?: Pick<TelegramApiCallOptions, "assertAuthority">) => Promise<unknown>;
     agentMessages: {
         resolveTarget: (selector: TelegramBusAgentTargetSelector) => Promise<TelegramTarget & {
             threadId: number;
@@ -414,7 +418,7 @@ export declare function createTelegramBusFollowerSelectedMenuCaller<TContext>(de
     effect: TelegramBusSelectedMenuTextEffect;
     assertAuthority: () => void;
 }) => Promise<TelegramBusSelectedMenuDeliveryObservation>;
-export declare function createTelegramBusFollowerApiCaller(deps: TelegramBusFollowerApiCallerDeps): (method: string, args: unknown[]) => Promise<unknown>;
+export declare function createTelegramBusFollowerApiCaller(deps: TelegramBusFollowerApiCallerDeps): (method: string, args: unknown[], localOptions?: Pick<TelegramApiCallOptions, "assertAuthority">) => Promise<unknown>;
 export declare function createTelegramBusFollowerSessionReplacementSuspender(deps: TelegramBusFollowerSessionReplacementSuspenderDeps): (preserveTarget?: boolean) => Promise<void>;
 export declare function createTelegramBusFollowerSessionRefreshHook<TContext>(deps: TelegramBusFollowerSessionRefreshHookDeps<TContext>): (_event: unknown, ctx: TContext) => Promise<void>;
 export declare function createTelegramBusFollowerControlState(): TelegramBusFollowerControlState;
@@ -426,6 +430,48 @@ export type TelegramBusFollowerHeartbeatRecoveryHandler<TContext> = ((error: unk
     halt: () => void;
     resume: () => void;
 };
+/** The whole recovery lifecycle state; only `transitionTelegramBusFollowerRecovery` produces a new one. */
+export interface TelegramBusFollowerRecoveryState {
+    /** Bumped by halt and resume, so a recovery or retry from before an operator stop or connect is inert. */
+    readonly epoch: number;
+    readonly halted: boolean;
+    /** One recovery runs at a time; it belongs to the epoch it started in. */
+    readonly recovering: boolean;
+    readonly retryId: number | null;
+    readonly nextRetryId: number;
+}
+export type TelegramBusFollowerRecoveryEvent = {
+    type: "recoverRequested";
+} | {
+    type: "recoverySettled";
+    epoch: number;
+} | {
+    type: "retryRequested";
+    epoch: number;
+} | {
+    type: "retryFired";
+    retryId: number;
+} | {
+    type: "halted";
+} | {
+    type: "resumed";
+};
+export type TelegramBusFollowerRecoveryEffect = {
+    type: "runRecovery";
+    epoch: number;
+} | {
+    type: "armRetry";
+    retryId: number;
+} | {
+    type: "cancelRetry";
+    retryId: number;
+};
+export declare function createTelegramBusFollowerRecoveryState(): TelegramBusFollowerRecoveryState;
+/**
+ * Pure follower-recovery lifecycle. An operator stop halts it and a connect resumes it, each in a new epoch: work
+ * from the old epoch, a recovery still awaiting or a retry still armed, can no longer register or promote.
+ */
+export declare function transitionTelegramBusFollowerRecovery(state: TelegramBusFollowerRecoveryState, event: TelegramBusFollowerRecoveryEvent): Machine.TelegramMachineStep<TelegramBusFollowerRecoveryState, TelegramBusFollowerRecoveryEffect>;
 export declare function createTelegramBusFollowerHeartbeatRecoveryHandler<TContext>(deps: TelegramBusFollowerHeartbeatRecoveryHandlerDeps<TContext>): TelegramBusFollowerHeartbeatRecoveryHandler<TContext>;
 export declare function createTelegramBusFollowerRegistrationRuntime<TContext extends {
     cwd?: string;