@llblab/pi-kit 0.5.0 → 0.5.2

package/node_modules/@llblab/pi-telegram/lib/locks.ts

@@ -871,6 +871,7 @@ export function createTelegramLockRuntime<TContext extends TelegramLockContext>(
     options.runtimeGeneration ?? allocateTelegramLockRuntimeGeneration();
   let ownedLockKey: string | undefined;
   let ownedLock: TelegramLockEntry | undefined;
+  let deliveryRevoked = false;
   const stateOptions = () => ({
     nowMs: getNowMs(),
     staleHeartbeatMs: options.staleHeartbeatMs,
@@ -917,7 +918,8 @@ export function createTelegramLockRuntime<TContext extends TelegramLockContext>(
         );
         if (
           state.kind === "active-here" &&
-          hasSameLockOwner(current, expectedOwned)
+          hasSameLockOwner(current, expectedOwned) &&
+          !deliveryRevoked
         ) {
           return {
             result: {
@@ -958,6 +960,7 @@ export function createTelegramLockRuntime<TContext extends TelegramLockContext>(
         if (
           !acquireOptions.election &&
           (state.kind === "active-here" || state.kind === "active-elsewhere") &&
+          !(deliveryRevoked && hasSameLockOwner(current, expectedOwned)) &&
           (!acquireOptions.force ||
             !expectedReplacementMatches ||
             !canReplaceCurrent)
@@ -978,6 +981,7 @@ export function createTelegramLockRuntime<TContext extends TelegramLockContext>(
         locks[effectiveKey] = lock;
         ownedLockKey = effectiveKey;
         ownedLock = lock;
+        deliveryRevoked = false;
         return {
           result: {
             ok: true,
@@ -987,8 +991,10 @@ export function createTelegramLockRuntime<TContext extends TelegramLockContext>(
           changed: true,
         };
       }),
-    release: () =>
-      withLockTransaction(locksPath, (locks) => {
+    release: () => {
+      // Withdraw local send authority even if the durable release fails.
+      deliveryRevoked = true;
+      return withLockTransaction(locksPath, (locks) => {
         const effectiveKey = resolveEffectiveKey();
         const state = getLockState(
           parseTelegramLockEntry(locks[effectiveKey]),
@@ -1008,17 +1014,20 @@ export function createTelegramLockRuntime<TContext extends TelegramLockContext>(
           ownedLock = undefined;
         }
         return { result: state, changed };
-      }),
+      });
+    },
     getState: () => getLockState(readLock(), pid, isAlive, stateOptions()),
     getStatusLabel: () =>
       formatLockState(getLockState(readLock(), pid, isAlive, stateOptions())),
     getOwnedLeaderEpoch: () => {
+      if (deliveryRevoked) return undefined;
       const effectiveKey = resolveEffectiveKey();
       const lock = parseTelegramLockEntry(readLocks(locksPath)[effectiveKey]);
       const exactOwner = adoptCompatibleOwnedLock(effectiveKey, lock);
       return hasSameLockOwner(lock, exactOwner) ? lock?.leaderEpoch : undefined;
     },
     owns: (ctx) => {
+      if (deliveryRevoked) return false;
       const effectiveKey = resolveEffectiveKey();
       const lock = parseTelegramLockEntry(readLocks(locksPath)[effectiveKey]);
       return hasSameLockOwner(
@@ -1027,7 +1036,7 @@ export function createTelegramLockRuntime<TContext extends TelegramLockContext>(
       );
     },
     commitIfOwned: (commit) =>
-      withLockTransaction(locksPath, (locks) => {
+      !deliveryRevoked && withLockTransaction(locksPath, (locks) => {
         const effectiveKey = resolveEffectiveKey();
         const lock = parseTelegramLockEntry(locks[effectiveKey]);
         const exactOwner =
@@ -1043,7 +1052,7 @@ export function createTelegramLockRuntime<TContext extends TelegramLockContext>(
         return { result: true, changed: false };
       }),
     refresh: (ctx) =>
-      withLockTransaction(locksPath, (locks) => {
+      !deliveryRevoked && withLockTransaction(locksPath, (locks) => {
         const effectiveKey = resolveEffectiveKey();
         const lock = parseTelegramLockEntry(locks[effectiveKey]);
         const expectedOwner = adoptCompatibleOwnedLock(effectiveKey, lock, ctx);
@@ -1116,6 +1125,7 @@ export interface TelegramLockedPollingRuntime<
   ) => Promise<TelegramLockedPollingStartResult>;
   stop: () => Promise<string>;
   suspend: () => Promise<void>;
+  onPersistentConflict: (ctx: TContext, count: number) => Promise<void>;
   onSessionStart: (_event: unknown, ctx: TContext) => Promise<void>;
   registerFollowerWithOwner?: (
     ctx: TContext,
@@ -1130,6 +1140,7 @@ export interface TelegramLockedPollingRuntimeDeps<
   lock: TelegramLockRuntime<TContext>;
   hasBotToken: () => boolean;
   canStartPolling?: (ctx: TContext) => boolean;
+  isContextCurrent?: (ctx: TContext) => boolean;
   formatStartBlockedMessage?: (ctx: TContext) => string;
   startPolling: (
     ctx: TContext,
@@ -1142,6 +1153,7 @@ export interface TelegramLockedPollingRuntimeDeps<
   ) => boolean | undefined | Promise<boolean | undefined>;
   stopFollowerRegistration?: () => void;
   onTransportAvailabilityChanged?: () => void;
+  transportMonitor?: { start: (ctx: TContext) => void; stop: () => void };
   updateStatus: (ctx: TContext) => void;
   recordRuntimeEvent?: (
     category: string,
@@ -1164,9 +1176,10 @@ export function createTelegramLockedPollingRuntime<
   let ownershipCheckInterval: ReturnType<typeof setInterval> | undefined;
   let ownershipRefreshInterval: ReturnType<typeof setInterval> | undefined;
   let ownershipStop: Promise<void> | undefined;
+  let activeContext: TContext | undefined;
   let takeoverCandidate: TelegramLockEntry | undefined;
   let sessionAutoStartRun: Promise<void> | undefined;
-  let sessionAutoStartGeneration = 0;
+  let pollingGeneration = 0;
   const ownershipCheckMs =
     deps.ownershipCheckMs ?? TELEGRAM_OWNERSHIP_CHECK_MS;
   const ownershipRefreshMs =
@@ -1178,7 +1191,9 @@ export function createTelegramLockedPollingRuntime<
     ownershipRefreshInterval = undefined;
   };
   const suspendPolling = async () => {
-    sessionAutoStartGeneration += 1;
+    pollingGeneration += 1;
+    activeContext = undefined;
+    deps.transportMonitor?.stop();
     deps.stopFollowerRegistration?.();
     stopOwnershipWatcher();
     if (sessionAutoStartRun) {
@@ -1192,6 +1207,8 @@ export function createTelegramLockedPollingRuntime<
   };
   const stopAfterOwnershipLoss = () => {
     if (ownershipStop) return;
+    activeContext = undefined;
+    deps.transportMonitor?.stop();
     stopOwnershipWatcher();
     deps.onTransportAvailabilityChanged?.();
     ownershipStop = deps
@@ -1228,7 +1245,10 @@ export function createTelegramLockedPollingRuntime<
   const runOwnedPollingStart = async (
     ctx: TContext,
     options: TelegramLockedPollingStartOptions,
+    isCurrent: () => boolean,
   ): Promise<boolean> => {
+    if (!isCurrent()) return false;
+    activeContext = ctx;
     startOwnershipWatcher(ctx);
     try {
       if (!deps.lock.refresh(snapshotLockContext(ctx))) {
@@ -1236,8 +1256,10 @@ export function createTelegramLockedPollingRuntime<
         return false;
       }
       await options.onAcquired?.();
+      if (!isCurrent()) return false;
       await deps.startPolling(ctx, options);
     } catch (error) {
+      if (!isCurrent()) return false;
       stopOwnershipWatcher();
       try {
         await deps.stopPolling();
@@ -1246,14 +1268,22 @@ export function createTelegramLockedPollingRuntime<
           phase: "startup-rollback",
         });
       }
+      if (!isCurrent()) return false;
       deps.lock.release();
       deps.onTransportAvailabilityChanged?.();
       throw error;
     }
-    if (deps.lock.owns(ctx)) return true;
+    if (!isCurrent()) return false;
+    if (deps.lock.owns(ctx)) {
+      if (activeContext !== ctx) return false;
+      deps.transportMonitor?.start(ctx);
+      return true;
+    }
     stopOwnershipWatcher();
     if (ownershipStop) await ownershipStop;
+    if (!isCurrent()) return false;
     await deps.stopPolling();
+    if (!isCurrent()) return false;
     deps.onTransportAvailabilityChanged?.();
     return false;
   };
@@ -1270,6 +1300,17 @@ export function createTelegramLockedPollingRuntime<
       if (!canStartPolling(ctx)) {
         return { ok: false, message: formatStartBlockedMessage(ctx) };
       }
+      const cancelled = {
+        ok: false as const,
+        canTakeover: false as const,
+        message: "Telegram polling startup was cancelled or superseded.",
+      };
+      if (deps.isContextCurrent?.(ctx) === false) return cancelled;
+      const generation = ++pollingGeneration;
+      const isCurrent = () => generation === pollingGeneration &&
+        (deps.isContextCurrent?.(ctx) ?? true);
+      if (ownershipStop) await ownershipStop;
+      if (!isCurrent()) return cancelled;
       let acquired = deps.lock.acquire(ctx, {
         force: options.force,
         expectedOwner:
@@ -1306,6 +1347,7 @@ export function createTelegramLockedPollingRuntime<
               ctx,
               acquired.lock,
             );
+            if (!isCurrent()) return cancelled;
             if (registered) {
               deps.updateStatus(ctx);
               return { ok: true, canTakeover: false };
@@ -1337,13 +1379,15 @@ export function createTelegramLockedPollingRuntime<
         };
       }
       takeoverCandidate = undefined;
-      if (!(await runOwnedPollingStart(ctx, options))) {
+      if (!(await runOwnedPollingStart(ctx, options, isCurrent))) {
+        if (!isCurrent()) return cancelled;
         return {
           ok: false,
           canTakeover: false,
           message: "Telegram leadership changed during polling startup.",
         };
       }
+      if (!isCurrent()) return cancelled;
       deps.onTransportAvailabilityChanged?.();
       deps.updateStatus(ctx);
       const staleSuffix = acquired.replacedStale ? " Replaced stale lock." : "";
@@ -1362,6 +1406,42 @@ export function createTelegramLockedPollingRuntime<
       return "Telegram bridge disconnected.";
     },
     suspend: suspendPolling,
+    onPersistentConflict: async (ctx, count) => {
+      if (activeContext === undefined || ownershipStop) return;
+      if (!(deps.isContextCurrent?.(ctx) ?? activeContext === ctx)) return;
+      activeContext = undefined;
+      pollingGeneration += 1;
+      stopOwnershipWatcher();
+      deps.transportMonitor?.stop();
+      let ownership = "unverifiable";
+      const cleanupErrors: string[] = [];
+      try {
+        ownership = deps.lock.owns(snapshotLockContext(ctx)) ? "owned" : "lost";
+      } catch (error) {
+        cleanupErrors.push(String(error));
+      }
+      try {
+        deps.lock.release();
+      } catch (error) {
+        ownership = "unverifiable";
+        cleanupErrors.push(String(error));
+      }
+      ownershipStop = Promise.resolve()
+        .then(() => deps.stopPolling())
+        .catch((error) => { cleanupErrors.push(String(error)); })
+        .finally(() => {
+          ownershipStop = undefined;
+          deps.recordRuntimeEvent?.("polling", ownership === "lost"
+            ? "Telegram transport stopped: local ownership lost; check for another Pi instance."
+            : "Telegram transport stopped: competing getUpdates client or ownership mismatch.", {
+            phase: "persistent-conflict", count, ownership,
+            ...(cleanupErrors.length ? { cleanupErrors } : {}),
+          });
+          deps.updateStatus(ctx);
+        });
+      deps.onTransportAvailabilityChanged?.();
+      await ownershipStop;
+    },
     onSessionStart: async (_event, ctx) => {
       if (!deps.hasBotToken()) return;
       if (!canStartPolling(ctx)) return;
@@ -1379,15 +1459,18 @@ export function createTelegramLockedPollingRuntime<
       ) {
         return;
       }
-      sessionAutoStartGeneration += 1;
-      const generation = sessionAutoStartGeneration;
+      if (deps.isContextCurrent?.(ctx) === false) return;
+      const generation = ++pollingGeneration;
+      const isCurrent = () => generation === pollingGeneration &&
+        (deps.isContextCurrent?.(ctx) ?? true);
       const startedAtMs = Date.now();
       deps.recordRuntimeEvent?.("lock", "Telegram auto-start scheduled", {
         phase: "auto-start-scheduled",
       });
       const run = (async () => {
         await new Promise((resolve) => setTimeout(resolve, 0));
-        if (generation !== sessionAutoStartGeneration) return;
+        if (ownershipStop) await ownershipStop;
+        if (!isCurrent()) return;
         if (canResumeStaleSameCwd || canHandoffSameProcess) {
           const acquired = deps.lock.acquire(
             ctx,
@@ -1397,9 +1480,9 @@ export function createTelegramLockedPollingRuntime<
           );
           if (!acquired.ok) return;
         }
-        if (generation !== sessionAutoStartGeneration) return;
-        if (!(await runOwnedPollingStart(ctx, {}))) return;
-        if (generation !== sessionAutoStartGeneration) return;
+        if (!isCurrent()) return;
+        if (!(await runOwnedPollingStart(ctx, {}, isCurrent))) return;
+        if (!isCurrent()) return;
         deps.onTransportAvailabilityChanged?.();
         deps.updateStatus(ctx);
         deps.recordRuntimeEvent?.("lock", "Telegram auto-start completed", {

package/node_modules/@llblab/pi-telegram/lib/outbound-attachments.ts

@@ -219,8 +219,9 @@ export function createTelegramRichOutboundAttachmentSender(
   return async (
     turn: TelegramQueuedOutboundAttachmentTurnView,
     markdown: string,
-    options?: { replyMarkup?: unknown },
+    options?: { replyMarkup?: unknown; isDeliveryActive?: () => boolean },
   ): Promise<boolean> => {
+    if (options?.isDeliveryActive?.() === false) return false;
     const plan = planTelegramRichOutboundAttachment({
       turn,
       markdown,
@@ -246,11 +247,13 @@ export function createTelegramRichOutboundAttachmentSender(
           new Error("Successful Rich media upload omitted message_id."),
         );
       }
-      deps.recordOwnership?.({
-        chatId: turn.chatId,
-        messageId,
-        target: turn.target,
-      });
+      if (options?.isDeliveryActive?.() !== false) {
+        deps.recordOwnership?.({
+          chatId: turn.chatId,
+          messageId,
+          target: turn.target,
+        });
+      }
       return true;
     } catch (error) {
       if (isTelegramRichAttachmentCommitUnknownError(error)) throw error;
@@ -580,6 +583,7 @@ export interface TelegramQueuedOutboundAttachmentDeliveryDeps {
   ) => void;
   statPath?: (path: string) => Promise<{ size: number }>;
   maxAttachmentSizeBytes?: number;
+  isDeliveryActive?: () => boolean;
 }
 
 export async function queueTelegramOutboundAttachments(options: {
@@ -925,9 +929,13 @@ export async function sendTelegramOutboundFiles(options: {
 export function createTelegramQueuedOutboundAttachmentSender(
   deps: TelegramQueuedOutboundAttachmentDeliveryDeps,
 ) {
-  return async (turn: TelegramQueuedOutboundAttachmentTurnView): Promise<void> => {
+  return async (
+    turn: TelegramQueuedOutboundAttachmentTurnView,
+    options?: { isDeliveryActive?: () => boolean },
+  ): Promise<void> => {
     await sendQueuedTelegramOutboundAttachments(turn, {
       ...deps,
+      isDeliveryActive: () => deps.isDeliveryActive?.() !== false && options?.isDeliveryActive?.() !== false,
       maxAttachmentSizeBytes:
         deps.maxAttachmentSizeBytes ?? TELEGRAM_OUTBOUND_ATTACHMENT_MAX_BYTES,
     });
@@ -939,9 +947,11 @@ export async function sendQueuedTelegramOutboundAttachments(
   deps: TelegramQueuedOutboundAttachmentDeliveryDeps,
 ): Promise<void> {
   for (const attachment of turn.queuedAttachments) {
+    if (deps.isDeliveryActive?.() === false) return;
     try {
       if (deps.maxAttachmentSizeBytes !== undefined) {
         const stats = await (deps.statPath ?? stat)(attachment.path);
+        if (deps.isDeliveryActive?.() === false) return;
         if (stats.size > deps.maxAttachmentSizeBytes) {
           throw new Error(
             formatTelegramOutboundAttachmentSizeLimitError(
@@ -971,6 +981,7 @@ export async function sendQueuedTelegramOutboundAttachments(
         attachment.fileName,
       );
     } catch (error) {
+      if (deps.isDeliveryActive?.() === false) return;
       const message = error instanceof Error ? error.message : String(error);
       deps.recordRuntimeEvent?.("attachment", error, {
         fileName: attachment.fileName,

package/node_modules/@llblab/pi-telegram/lib/outbound-voice.ts

@@ -14,6 +14,7 @@ import {
   type TelegramTarget,
 } from "./target.ts";
 import { getTelegramVoiceSynthesisProviders } from "./voice.ts";
+import { isTelegramApiCommitUnknownError } from "./telegram-api.ts";
 
 export interface TelegramVoiceReplyTurnView {
   chatId: number;
@@ -47,6 +48,7 @@ export interface TelegramVoiceReplySenderDeps {
   ) => Promise<unknown>;
   sendChatAction?: (chatId: number, action: string) => Promise<unknown>;
   sendRecordVoiceAction?: (chatId: number) => Promise<unknown>;
+  isDeliveryActive?: () => boolean;
   getHandlers?: () => unknown[] | undefined;
   cwd?: string;
   tempDir?: string;
@@ -123,9 +125,12 @@ export function createTelegramVoiceReplySender<THandler = unknown>(
       replyMarkup?: unknown;
     },
   ): Promise<void> => {
+    if (deps.isDeliveryActive?.() === false) return;
     const voiceFilePath = await ensureTelegramVoiceFileFormat(filePath);
     assertTelegramInlineKeyboardCallbackData(options?.replyMarkup);
+    if (deps.isDeliveryActive?.() === false) return;
     await sendVoiceChatAction(deps, turn.chatId);
+    if (deps.isDeliveryActive?.() === false) return;
     const replyParameters = buildVoiceReplyParameters(
       turn.chatId,
       options?.replyToPrompt,
@@ -171,6 +176,7 @@ export function createTelegramVoiceReplySender<THandler = unknown>(
   ): Promise<void> => {
     for (const handler of ports.findVoiceHandlers?.(deps.getHandlers?.()) ??
       []) {
+      if (deps.isDeliveryActive?.() === false) return;
       try {
         const filePath = await ports.generateVoiceFile?.(text, {
           lang: options?.lang,
@@ -187,6 +193,7 @@ export function createTelegramVoiceReplySender<THandler = unknown>(
         });
         return;
       } catch (error) {
+        if (isTelegramApiCommitUnknownError(error)) throw error;
         deps.recordRuntimeEvent?.("voice", error, {
           phase: "template-handler-send",
         });
@@ -194,6 +201,7 @@ export function createTelegramVoiceReplySender<THandler = unknown>(
     }
 
     for (const handler of ports.getProgrammaticVoiceHandlers?.() ?? []) {
+      if (deps.isDeliveryActive?.() === false) return;
       try {
         const filePath = await handler(text, {
           lang: options?.lang,
@@ -206,6 +214,7 @@ export function createTelegramVoiceReplySender<THandler = unknown>(
         });
         return;
       } catch (error) {
+        if (isTelegramApiCommitUnknownError(error)) throw error;
         deps.recordRuntimeEvent?.("voice", error, {
           phase: "programmatic-handler-send",
         });
@@ -215,6 +224,7 @@ export function createTelegramVoiceReplySender<THandler = unknown>(
     const providers = getTelegramVoiceSynthesisProviders();
 
     for (const provider of providers) {
+      if (deps.isDeliveryActive?.() === false) return;
       let voiceFilePath: string | undefined;
       let originalFilePath: string | undefined;
 
@@ -252,6 +262,7 @@ export function createTelegramVoiceReplySender<THandler = unknown>(
         });
         return;
       } catch (error) {
+        if (isTelegramApiCommitUnknownError(error)) throw error;
         deps.recordRuntimeEvent?.("voice", error, { phase: "send" });
       } finally {
         if (voiceFilePath && voiceFilePath !== originalFilePath) {

package/node_modules/@llblab/pi-telegram/lib/outbound.ts

@@ -11,6 +11,7 @@ import { join } from "node:path";
 import type { TelegramAssistantSegmentEvent } from "./activity.ts";
 import { resolveTelegramTempDir } from "./paths.ts";
 import * as Replies from "./replies.ts";
+import { isTelegramApiCommitUnknownError } from "./telegram-api.ts";
 import type {
   TelegramEditMessageTextBody,
   TelegramSendMessageBody,
@@ -137,6 +138,7 @@ export interface TelegramVoiceReplySenderDeps {
   ) => Promise<unknown>;
   sendChatAction?: (chatId: number, action: string) => Promise<unknown>;
   sendRecordVoiceAction?: (chatId: number) => Promise<unknown>;
+  isDeliveryActive?: () => boolean;
   getHandlers?: () => TelegramOutboundHandlerConfig[] | undefined;
   cwd?: string;
   tempDir?: string;
@@ -877,15 +879,17 @@ export function createTelegramOutboundReplyPlanner(
 export function createTelegramOutboundReplyArtifactSender(
   deps: TelegramVoiceReplySenderDeps,
 ) {
-  const sendVoiceReply = createTelegramVoiceReplySender(deps);
   return async (
     turn: TelegramVoiceReplyTurnView,
     plan: Pick<
       TelegramOutboundReplyPlan,
       "voiceText" | "voiceReplies" | "lang" | "rate" | "replyMarkup"
     >,
-    options?: { replyToPrompt?: boolean },
+    options?: { replyToPrompt?: boolean; isDeliveryActive?: () => boolean },
   ): Promise<void> => {
+    const isDeliveryActive = () =>
+      deps.isDeliveryActive?.() !== false && options?.isDeliveryActive?.() !== false;
+    const sendVoiceReply = createTelegramVoiceReplySender({ ...deps, isDeliveryActive });
     // Normalize voice replies: either use explicit voiceReplies array or fall back to voiceText
     const voiceReplies = plan.voiceReplies?.length
       ? plan.voiceReplies
@@ -896,6 +900,7 @@ export function createTelegramOutboundReplyArtifactSender(
     let anyDelivered = false;
 
     for (const reply of voiceReplies) {
+      if (!isDeliveryActive()) return;
       try {
         await sendVoiceReply(turn, reply.text, {
           lang: reply.lang ?? plan.lang,
@@ -905,11 +910,13 @@ export function createTelegramOutboundReplyArtifactSender(
           replyMarkup: !anyDelivered ? plan.replyMarkup : undefined,
         });
         anyDelivered = true;
-      } catch {
+      } catch (error) {
+        if (isTelegramApiCommitUnknownError(error)) throw error;
         // sendVoiceReply already recorded the error; continue to next reply
       }
     }
 
+    if (!isDeliveryActive()) return;
     if (!anyDelivered) {
       throw new Error(
         "Failed to send voice reply: every voice synthesis provider failed.",