@llblab/pi-telegram 0.22.1 → 0.23.1

package/lib/threads.ts

@@ -44,7 +44,13 @@ export interface TelegramThreadNameInput {
 }
 
 export type TelegramTopicTargetStatus =
-  "active" | "offline" | "stale" | "pending" | "starting" | "failed";
+  | "active"
+  | "offline"
+  | "stale"
+  | "pending"
+  | "starting"
+  | "probe-required"
+  | "failed";
 
 export type TelegramTopicSyncStatus = "open" | "closed" | "deleted" | "unknown";
 
@@ -231,7 +237,6 @@ export interface TelegramTopicTargetStore {
     target: TelegramTarget & { threadId: number },
   ) => Promise<boolean>;
   removePendingProvision: (id: string) => boolean;
-  removeReservationByTarget: (target: TelegramTarget) => boolean;
   getBotState: () => TelegramBotStateSnapshot;
   setBotState: (state: Partial<TelegramBotStateSnapshot>) => void;
   setStatusSnapshot: (snapshot: {
@@ -438,6 +443,60 @@ export function getTelegramTopicTargetsPath(
   return getTelegramStatePath(agentDir, profileName);
 }
 
+const TELEGRAM_LEADER_SESSION_HANDOFF_KEY =
+  "__piTelegramLeaderSessionHandoff";
+export const TELEGRAM_LEADER_SESSION_HANDOFF_TTL_MS = 30_000;
+
+export interface TelegramLeaderSessionHandoff {
+  pid: number;
+  instanceId: string;
+  createdAtMs: number;
+  profileKey: string;
+  target: TelegramTarget & { threadId: number };
+  slot?: string;
+  threadName?: string;
+}
+
+export function getTelegramLeaderSessionHandoff():
+  | TelegramLeaderSessionHandoff
+  | undefined {
+  const value = (globalThis as Record<string, unknown>)[
+    TELEGRAM_LEADER_SESSION_HANDOFF_KEY
+  ];
+  if (!value || typeof value !== "object") return undefined;
+  const handoff = value as Partial<TelegramLeaderSessionHandoff>;
+  if (
+    typeof handoff.pid !== "number" ||
+    typeof handoff.instanceId !== "string" ||
+    typeof handoff.createdAtMs !== "number" ||
+    typeof handoff.profileKey !== "string" ||
+    typeof handoff.target?.chatId !== "number" ||
+    typeof handoff.target.threadId !== "number"
+  ) {
+    return undefined;
+  }
+  return handoff as TelegramLeaderSessionHandoff;
+}
+
+export function setTelegramLeaderSessionHandoff(
+  handoff: TelegramLeaderSessionHandoff | undefined,
+): void {
+  const store = globalThis as Record<string, unknown>;
+  if (!handoff) delete store[TELEGRAM_LEADER_SESSION_HANDOFF_KEY];
+  else store[TELEGRAM_LEADER_SESSION_HANDOFF_KEY] = handoff;
+}
+
+export function isTelegramLeaderSessionHandoffFresh(
+  handoff: TelegramLeaderSessionHandoff | undefined,
+  options: { pid?: number; nowMs?: number; ttlMs?: number } = {},
+): handoff is TelegramLeaderSessionHandoff {
+  if (!handoff) return false;
+  const pid = options.pid ?? process.pid;
+  const nowMs = options.nowMs ?? Date.now();
+  const ttlMs = options.ttlMs ?? TELEGRAM_LEADER_SESSION_HANDOFF_TTL_MS;
+  return handoff.pid === pid && nowMs - handoff.createdAtMs <= ttlMs;
+}
+
 export function getTelegramThreadOwnerKey(owner: TelegramThreadOwner): string {
   switch (owner.kind) {
     case "leader": {
@@ -593,6 +652,7 @@ function normalizeRecord(
     status !== "stale" &&
     status !== "pending" &&
     status !== "starting" &&
+    status !== "probe-required" &&
     status !== "failed"
   )
     return undefined;
@@ -655,6 +715,10 @@ function isCurrentThreadRecord(record: TelegramTopicTargetRecord): boolean {
   );
 }
 
+function isPersistedThreadRecord(record: TelegramTopicTargetRecord): boolean {
+  return isCurrentThreadRecord(record) || record.status === "probe-required";
+}
+
 function normalizeIdentityRecord(
   value: unknown,
 ): TelegramThreadIdentityRecord | undefined {
@@ -882,7 +946,7 @@ function parseTopicTargetFile(value: unknown): TelegramTopicTargetFile {
     .map((record) => normalizeRecord(record))
     .filter(
       (record): record is TelegramTopicTargetRecord =>
-        !!record && isCurrentThreadRecord(record),
+        !!record && isPersistedThreadRecord(record),
     );
   return {
     version: 1,
@@ -1172,7 +1236,7 @@ export function createTelegramTopicTargetStore(
           isPendingProvisionLiveOrTargeted(provision, nowMs),
         );
         const currentRecords = Array.from(records.values())
-          .filter(isCurrentThreadRecord)
+          .filter(isPersistedThreadRecord)
           .map(cloneRecord);
         records = new Map(
           currentRecords.map((record) => [
@@ -1331,15 +1395,6 @@ export function createTelegramTopicTargetStore(
       if (changed) markDirty();
       return changed;
     },
-    removeReservationByTarget(target) {
-      const before = reservations.length;
-      reservations = reservations.filter(
-        (reservation) => !targetMatches(reservation.target, target),
-      );
-      const changed = reservations.length !== before;
-      if (changed) markDirty();
-      return changed;
-    },
     getBotState() {
       return Object.fromEntries(
         Object.entries(botState).filter(([, value]) => value !== undefined),
@@ -1411,7 +1466,7 @@ export function createTelegramTopicTargetStore(
           records.delete(getRecordOwnerKey(existing));
         }
       }
-      if (!isCurrentThreadRecord(next)) {
+      if (!isPersistedThreadRecord(next)) {
         rememberIdentity(next);
         records.delete(nextOwnerKey);
         markDirty();
@@ -1918,9 +1973,6 @@ export async function provisionOwnBusTopic(
       syncStatus?: "closed" | "deleted",
       lastSyncError?: string,
     ) => deps.store.markStaleByTarget(target, syncStatus, lastSyncError),
-    removeReservationByTarget: (
-      target: TelegramTarget & { threadId: number },
-    ) => deps.store.removeReservationByTarget(target),
     removePendingProvisionById: (id: string) =>
       deps.store.removePendingProvision(id),
     persist: () => deps.store.persist(),
@@ -1959,36 +2011,6 @@ export async function provisionOwnBusTopic(
     durationMs: Date.now() - reservationCleanupApplyStartedAtMs,
     actions: reservationCleanupPlan.actions.length,
   });
-  const reservationProbeResults: ThreadReconciler.ThreadReservationProbeResult[] =
-    [];
-  deps.recordEvent("bus", "Bus leader reservation probes skipped", {
-    phase: "leader-topic-reservation-probe-skipped",
-    reservations: reservationsBeforeCleanup.length,
-  });
-  const reservationProbePlan = ThreadReconciler.planThreadReconciliation({
-    nowMs: Date.now(),
-    currentLeaderEpoch: deps.getCurrentLeaderEpoch?.(),
-    previousState: deps.getThreadReconciliationMachineState?.(),
-    records: deps.store.list(),
-    reservations: deps.store.listReservations(),
-    pendingProvisions: deps.store.listPendingProvisions(),
-    reservationProbeResults,
-  });
-  deps.recordThreadReconciliationPlan?.(reservationProbePlan);
-  const reservationProbeApplyStartedAtMs = Date.now();
-  await ThreadReconciler.applyThreadReconciliationPlan(
-    reservationProbePlan,
-    reservationCleanupPorts,
-  );
-  deps.recordEvent(
-    "bus",
-    "Bus leader reservation probe reconciliation applied",
-    {
-      phase: "leader-topic-reservation-probe-apply-duration",
-      durationMs: Date.now() - reservationProbeApplyStartedAtMs,
-      actions: reservationProbePlan.actions.length,
-    },
-  );
   const nowMs = Date.now();
   const currentLeaderOwner: TelegramThreadOwner = {
     kind: "leader",
@@ -1996,6 +2018,51 @@ export async function provisionOwnBusTopic(
     instanceId: deps.instanceId,
     ...(deps.telegramProfile ? { telegramProfile: deps.telegramProfile } : {}),
   };
+  const leaderSessionHandoff = getTelegramLeaderSessionHandoff();
+  if (
+    isTelegramLeaderSessionHandoffFresh(leaderSessionHandoff) &&
+    leaderSessionHandoff.profileKey === profileKey
+  ) {
+    const existingHandoffRecord = deps.store
+      .list()
+      .find((record) => targetMatches(record.target, leaderSessionHandoff.target));
+    deps.store.upsert({
+      profileKey,
+      owner: currentLeaderOwner,
+      target: { ...leaderSessionHandoff.target },
+      status: "active",
+      createdAtMs: existingHandoffRecord?.createdAtMs ?? leaderSessionHandoff.createdAtMs,
+      updatedAtMs: nowMs,
+      threadName:
+        existingHandoffRecord?.threadName ?? leaderSessionHandoff.threadName,
+      instanceId: deps.instanceId,
+      slot: existingHandoffRecord?.slot ?? leaderSessionHandoff.slot,
+      ...(existingHandoffRecord?.syncStatus
+        ? { syncStatus: existingHandoffRecord.syncStatus }
+        : {}),
+      ...(existingHandoffRecord?.lastSyncObservedAtMs !== undefined
+        ? {
+            lastSyncObservedAtMs:
+              existingHandoffRecord.lastSyncObservedAtMs,
+          }
+        : {}),
+      lastReconcileAction: "leader-session-handoff-restored",
+    });
+    await deps.store.persist();
+    setTelegramLeaderSessionHandoff(undefined);
+    deps.recordEvent("bus", "Bus leader session handoff restored", {
+      phase: "leader-session-handoff-restore",
+      chatId: leaderSessionHandoff.target.chatId,
+      threadId: leaderSessionHandoff.target.threadId,
+      slot: existingHandoffRecord?.slot ?? leaderSessionHandoff.slot,
+      threadName:
+        existingHandoffRecord?.threadName ?? leaderSessionHandoff.threadName,
+      previousInstanceId: leaderSessionHandoff.instanceId,
+      instanceId: deps.instanceId,
+    });
+  } else if (leaderSessionHandoff) {
+    setTelegramLeaderSessionHandoff(undefined);
+  }
   const recordsBeforePreviousLeaderCleanup = deps.store.list();
   const previousLeaderCleanupPlan = ThreadReconciler.planThreadReconciliation({
     nowMs,
@@ -2051,7 +2118,7 @@ export async function provisionOwnBusTopic(
       continue;
     }
     const previousLeaderCleanupStartedAtMs = Date.now();
-    await ThreadReconciler.applyThreadReconciliationPlan(
+    const cleanup = await ThreadReconciler.applyThreadReconciliationPlan(
       { actions: [action] },
       {
         callApi: deps.callApi,
@@ -2097,6 +2164,11 @@ export async function provisionOwnBusTopic(
         "Telegram leader ownership changed during topic reconciliation.",
       );
     }
+    if (cleanup.incompleteActions?.length) {
+      throw new Error(
+        "Previous Telegram leader topic deletion was not confirmed.",
+      );
+    }
     deps.store.markStaleByTarget(record.target);
     deps.store.reserveThread({
       target: record.target,
@@ -2256,6 +2328,7 @@ export interface TelegramCurrentInstanceThreadRuntime {
   findRecord(): TelegramTopicTargetRecord | undefined;
   getRecord(): TelegramTopicTargetRecord | undefined;
   getIdentity(target?: TelegramTarget): TelegramInstanceThreadIdentityCandidate;
+  getRestorationIdentity(): TelegramInstanceThreadIdentityCandidate;
 }
 
 export function createTelegramCurrentInstanceThreadRuntime(deps: {
@@ -2301,6 +2374,14 @@ export function createTelegramCurrentInstanceThreadRuntime(deps: {
         record,
       });
     },
+    getRestorationIdentity() {
+      const follower = deps.getFollower();
+      return resolveTelegramInstanceThreadIdentity({
+        follower: follower?.registered ? follower : undefined,
+        leader: deps.getLeader(),
+        record: findRecord(),
+      });
+    },
   };
 }
 
@@ -2657,25 +2738,9 @@ export function createTelegramTopicTargetProvisioner(
     };
     assertLeaderEpoch("start");
     normalizeCurrentThreadNameSlots(deps.store);
-    let existing = deps.store.getByProfileKey(request.profileKey);
+    const existing = deps.store.getByProfileKey(request.profileKey);
     const isManualFollowerRequest = request.owner?.kind === "manual-follower";
-    if (
-      isManualFollowerRequest &&
-      existing &&
-      isCurrentThreadRecord(existing)
-    ) {
-      deps.store.markStaleByTarget(
-        existing.target,
-        "unknown",
-        "Manual follower runtime was replaced before reconnect.",
-      );
-      deps.store.forgetIdentityByProfileKey(request.profileKey);
-      existing = undefined;
-    }
-    const identity =
-      isManualFollowerRequest && !existing
-        ? undefined
-        : deps.store.getIdentityByProfileKey(request.profileKey);
+    const identity = deps.store.getIdentityByProfileKey(request.profileKey);
     const nowMs = getNowMs();
     if (existing && isCurrentThreadRecord(existing)) {
       const slot = existing.slot ?? deps.store.allocateSlot(request.profileKey);

package/lib/turns.ts

@@ -9,9 +9,11 @@ import { basename, dirname, join } from "node:path";
 
 import {
   buildTelegramReplyContextBlock,
+  collectTelegramFileInfos,
   collectTelegramMessageIds,
   downloadTelegramMessageFiles,
   extractTelegramForwardContextText,
+  extractTelegramMessageText,
   extractTelegramMessagesPromptText,
   extractTelegramMessagesText,
   formatTelegramHistoryText,
@@ -132,11 +134,36 @@ function appendTelegramAttachmentSection(
   return `${prefix}${header}\n${items.map((item) => `- ${item}`).join("\n")}`;
 }
 
-function appendTelegramSourceContext(text: string, sourceContext: string | undefined): string {
+function appendTelegramSourceContext(
+  text: string,
+  sourceContext: string | undefined,
+): string {
   if (!sourceContext) return text;
   return text ? `${text}\n\n${sourceContext}` : sourceContext;
 }
 
+
+function buildTelegramForwardContextBlock(options: {
+  context: string;
+  text: string;
+  files: DownloadedTelegramTurnFile[];
+}): string {
+  const metadata = options.context.replace(/:\s+/g, ":");
+  const from = metadata.match(/^from:(.+)$/)?.[1];
+  let block = `[forward|${metadata}]${options.text ? ` ${options.text}` : ""}`;
+  if (options.files.length === 0) return block;
+  const dirs = [...new Set(options.files.map((file) => dirname(file.path)))];
+  const sameDir = dirs.length === 1;
+  const header = `[attachments${from ? `|from:${from}` : ""}]${
+    sameDir ? ` ${dirs[0]}` : ""
+  }`;
+  const items = sameDir
+    ? options.files.map((file) => `/${basename(file.path)}`)
+    : options.files.map((file) => file.path);
+  block += `\n\n${header}\n${items.map((item) => `- ${item}`).join("\n")}`;
+  return block;
+}
+
 function appendTelegramPromptText(prompt: string, rawText: string): string {
   if (!rawText) return prompt;
   if (rawText.startsWith("\n")) return `${prompt}${rawText}`;
@@ -165,6 +192,7 @@ export function buildTelegramTurnPrompt(options: {
   rawText: string;
   files: DownloadedTelegramTurnFile[];
   promptFiles?: DownloadedTelegramTurnFile[];
+  displayFiles?: DownloadedTelegramTurnFile[];
   handlerOutputs?: string[];
   sourceContext?: string;
   historyTurns?: Pick<PendingTelegramTurn, "historyText">[];
@@ -186,14 +214,15 @@ export function buildTelegramTurnPrompt(options: {
         ? `${prompt}\n${options.rawText}`
         : appendTelegramPromptText(prompt, options.rawText);
   }
-  const promptFiles = options.promptFiles ?? options.files;
-  prompt = appendTelegramAttachmentSection(prompt, promptFiles);
-  prompt = appendTelegramSourceContext(prompt, options.sourceContext);
+  const displayFiles =
+    options.displayFiles ?? options.promptFiles ?? options.files;
+  prompt = appendTelegramAttachmentSection(prompt, displayFiles);
   prompt = appendTelegramListSection(
     prompt,
     "outputs",
     options.handlerOutputs ?? [],
   );
+  prompt = appendTelegramSourceContext(prompt, options.sourceContext);
   if (options.voiceContext) {
     prompt = appendTelegramVoiceContext(prompt, options.voiceContext);
   }
@@ -375,6 +404,7 @@ export interface BuildTelegramPromptTurnOptions {
   statusText?: string;
   files: DownloadedTelegramTurnFile[];
   promptFiles?: DownloadedTelegramTurnFile[];
+  displayFiles?: DownloadedTelegramTurnFile[];
   handlerOutputs?: string[];
   sourceContext?: string;
   timeLine?: string | null;
@@ -433,9 +463,26 @@ export function createTelegramPromptTurnRuntimeBuilder<
     const replyContext = firstMessage
       ? buildTelegramReplyContextBlock(firstMessage, replyFiles)
       : "";
-    const forwardContext = firstMessage
-      ? extractTelegramForwardContextText(firstMessage, deps.getAllowedUserId?.())
-      : "";
+    const forwardEntries = messages.flatMap((message) => {
+      const context = extractTelegramForwardContextText(
+        message,
+        deps.getAllowedUserId?.(),
+      );
+      return context
+        ? [
+            {
+              context,
+              text: extractTelegramMessageText(message),
+              message,
+              fileNames: new Set(
+                collectTelegramFileInfos(message.rich_message ? [message] : []).map(
+                  (file) => file.fileName,
+                ),
+              ),
+            },
+          ]
+        : [];
+    });
     const files = await downloadTelegramMessageFiles(messages, {
       downloadFile: deps.downloadFile,
     });
@@ -444,13 +491,51 @@ export function createTelegramPromptTurnRuntimeBuilder<
       : { rawText, promptFiles: files };
     const sourceBlocks: string[] = [];
     let promptRawText = processed.rawText;
-    if (forwardContext) {
+    const forwardedFilePaths = new Set<string>();
+    const getForwardFiles = (entry: (typeof forwardEntries)[number]) =>
+      (processed.promptFiles ?? files).filter((file) => {
+        if (!entry.fileNames.has(file.fileName)) return false;
+        forwardedFilePaths.add(file.path);
+        return true;
+      });
+    if (forwardEntries.length === 1 && messages.length === 1) {
+      const [forward] = forwardEntries;
       sourceBlocks.push(
-        `[forward|${forwardContext.replace(/:\s+/g, ":")}]${
-          processed.rawText ? ` ${processed.rawText}` : ""
-        }`,
+        buildTelegramForwardContextBlock({
+          context: forward!.context,
+          text: processed.rawText,
+          files: getForwardFiles(forward!),
+        }),
       );
       promptRawText = "";
+    } else if (forwardEntries.length > 0 && processed.rawText === rawText) {
+      const forwardedMessages = new Set(
+        forwardEntries.map((entry) => entry.message),
+      );
+      promptRawText = messages
+        .filter((message) => !forwardedMessages.has(message))
+        .map(extractTelegramMessageText)
+        .filter(Boolean)
+        .join("\n\n");
+      sourceBlocks.push(
+        ...forwardEntries.map((entry) =>
+          buildTelegramForwardContextBlock({
+            context: entry.context,
+            text: entry.text,
+            files: getForwardFiles(entry),
+          }),
+        ),
+      );
+    } else if (forwardEntries.length > 0) {
+      sourceBlocks.push(
+        ...forwardEntries.map((entry) =>
+          buildTelegramForwardContextBlock({
+            context: entry.context,
+            text: "",
+            files: getForwardFiles(entry),
+          }),
+        ),
+      );
     }
     if (replyContext) sourceBlocks.push(replyContext);
     const sourceContext = sourceBlocks.join("\n\n");
@@ -475,6 +560,9 @@ export function createTelegramPromptTurnRuntimeBuilder<
       statusText: processed.rawText,
       files,
       promptFiles: processed.promptFiles,
+      displayFiles: (processed.promptFiles ?? files).filter(
+        (file) => !forwardedFilePaths.has(file.path),
+      ),
       handlerOutputs: processed.handlerOutputs,
       timeLine,
       inferImageMimeType: guessMediaType,
@@ -522,6 +610,7 @@ export async function buildTelegramPromptTurn(
         rawText: options.rawText,
         files: options.files,
         promptFiles: options.promptFiles,
+        displayFiles: options.displayFiles,
         handlerOutputs: options.handlerOutputs,
         sourceContext: options.sourceContext,
         historyTurns: options.historyTurns,
@@ -566,14 +655,14 @@ export async function buildTelegramPromptTurn(
     historyText: appendTelegramSourceContext(
       formatTelegramHistoryText(
         options.rawText,
-        options.promptFiles ?? options.files,
+        options.displayFiles ?? options.promptFiles ?? options.files,
         options.handlerOutputs,
       ),
       options.sourceContext,
     ),
     statusSummary: formatTelegramTurnStatusSummary(
       options.statusText ?? options.rawText,
-      options.promptFiles ?? options.files,
+      options.displayFiles ?? options.promptFiles ?? options.files,
       options.handlerOutputs,
     ),
     // Voice tagging (used for preview suppression and prompt guidance)

package/lib/updates.ts

@@ -249,6 +249,7 @@ export function getAuthorizedTelegramGuestMessage(
 
 export interface TelegramMessageOwnershipView {
   instanceId: string;
+  ownerGeneration?: string;
 }
 
 export type TelegramMessageOwnershipLookup = (
@@ -258,6 +259,7 @@ export type TelegramMessageOwnershipLookup = (
 
 export interface TelegramTargetOwnershipView {
   instanceId: string;
+  ownerGeneration?: string;
 }
 
 export type TelegramTargetOwnershipLookup = (

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.22.1",
+  "version": "0.23.1",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -27,7 +27,8 @@
     "node": ">=22.19.0"
   },
   "scripts": {
-    "test": "node --experimental-strip-types --test tests/*.test.ts",
+    "test": "node --experimental-strip-types --test --test-reporter=dot tests/*.test.ts",
+    "test:verbose": "node --experimental-strip-types --test --test-reporter=spec tests/*.test.ts",
     "typecheck": "tsc --noEmit",
     "audit": "npm audit",
     "pack:check": "npm pack --dry-run",