@llblab/pi-kit 0.35.0 → 0.35.2

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

@@ -3741,6 +3741,86 @@ export function isTelegramThreadCleanupJournalNamespaceClear(
   );
 }
 
+/** Demand-driven recovery only; caller holds temporary-cleanup admission. Never a deletion grant. */
+export function recoverTelegramThreadCleanupDeadQueueOwners(
+  input: Parameters<typeof isTelegramThreadCleanupJournalNamespaceClear>[0] & {
+    recoveryOwner: TelegramUpdateJournalQueueOwnerIdentity;
+    isCurrent: () => boolean;
+    withSourceSerialization: NonNullable<TelegramUpdateJournalStoreOptions["withSourceSerialization"]>;
+    getQueueProcessLiveness?: TelegramUpdateJournalStoreOptions["getQueueProcessLiveness"];
+  },
+): number {
+  return input.withSourceSerialization(() => {
+    const assertCurrent = () => {
+      if (!input.isCurrent()) throw new Error("Temporary cleanup queue recovery lost authority.");
+    };
+    assertCurrent();
+    if (!input.cleanup) return 0;
+    // Validate exact references and complete namespace coverage before considering any mutation.
+    if (isTelegramThreadCleanupJournalNamespaceClear(input)) return 0;
+    const namespace = inspectTelegramSessionJournalNamespace(input);
+    if (namespace.retainedInputs?.some(value => value.state !== "committed") ||
+        input.requiredJournalBindingKeys.some(key => !namespace.sources.some(source =>
+          source.path === getTelegramUpdateJournalBindingPath(key) && source.evidence.kind === "present"))) return 0;
+    const plans: Array<{ path: string; recovery: TelegramUpdateJournalDeadQueueOwnerRecoveryInput }> = [];
+    for (const source of namespace.sources) {
+      if (source.evidence.kind !== "present") continue;
+      const file = source.evidence.file;
+      if (file.version !== TELEGRAM_UPDATE_JOURNAL_VERSION) continue;
+      const groups = new Map<string, TelegramUpdateJournalEntry[]>();
+      for (const entry of file.entries) {
+        if (!entry.queueReceiptId) continue;
+        const group = groups.get(entry.queueReceiptId) ?? [];
+        group.push(entry);
+        groups.set(entry.queueReceiptId, group);
+      }
+      for (const group of groups.values()) {
+        const entry = group[0]!;
+        if (entry.state !== "queued" || !entry.queueReceiptId || !entry.queueOwner ||
+            !entry.queueKind || entry.queueHandoff || entry.inputClaim) continue;
+        if (group.some(value => value.state !== "queued" || value.queueHandoff || value.inputClaim ||
+            value.queueKind !== entry.queueKind || !isDeepStrictEqual(value.queueOwner, entry.queueOwner))) continue;
+        plans.push({ path: source.path, recovery: {
+          queueKind: entry.queueKind, receiptId: entry.queueReceiptId,
+          sourceUpdateIds: group.map(value => value.updateId).sort((a, b) => a - b),
+          deadOwner: cloneJournalQueueOwner(entry.queueOwner), recoveryOwner: { ...input.recoveryOwner },
+        } });
+      }
+    }
+    const liveness = input.getQueueProcessLiveness ?? getTelegramProcessLiveness;
+    const dead = plans.filter(plan => {
+      assertCurrent();
+      const result = liveness(plan.recovery.deadOwner);
+      assertCurrent();
+      return result === "dead";
+    });
+    let removed = 0;
+    for (const plan of dead) {
+      assertCurrent();
+      removed += input.withSourceReference(plan.path, () => {
+        const journal = createTelegramUpdateJournalStore({
+          path: plan.path, profileName: input.profile, botIdentity: input.botIdentity,
+          queueRuntimeIdentity: input.recoveryOwner,
+          // This private synchronous store stays inside the cross-family serializer already held above.
+          withSourceSerialization(operation) { assertCurrent(); return operation(); },
+          sourceAccess: { directory: dirname(plan.path), limits: input.limits },
+          getQueueProcessLiveness(owner) {
+            assertCurrent();
+            const result = liveness(owner);
+            assertCurrent();
+            return result;
+          },
+          withWriterAdmission(operation) { assertCurrent(); return operation(); },
+        });
+        // The journal transaction rechecks whole-group identity, absence of handoff and fresh process-death proof.
+        return journal.recoverDeadQueueOwner(plan.recovery).recoveredUpdateIds.length;
+      });
+    }
+    assertCurrent();
+    return removed;
+  });
+}
+
 function cloneEntry(
   entry: TelegramUpdateJournalEntry,
 ): TelegramUpdateJournalEntry {

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

@@ -23,6 +23,118 @@ import {
 } from "./paths.ts";
 import * as Status from "./status.ts";
 
+/** Sink shape shared with the runtime event recorder this domain already owns. */
+export type TelegramFailureRecordSink = (
+  category: string,
+  errorOrMessage: unknown,
+  details: Record<string, unknown>,
+) => void;
+
+export interface TelegramFailureRunSummary {
+  signature: string;
+  failedAttempts: number;
+  suppressedFailures: number;
+  failedForMs: number;
+}
+
+export interface TelegramFailureRunLog {
+  /** Records one failure; a repeated identical failure only extends the current run and returns false. */
+  record: (error: unknown, details?: Record<string, unknown>) => boolean;
+  /** Closes the run after a success, emitting its single outcome record. */
+  settled: () => TelegramFailureRunSummary | undefined;
+  /** Ends the run without an outcome record, for a stop or replacement that reports its own outcome. */
+  reset: () => void;
+}
+
+export interface TelegramFailureRunLogInput {
+  category: string;
+  failurePhase: string;
+  outcomePhase: string;
+  /** Human-readable subject for the outcome record, e.g. `follower heartbeat`. */
+  label: string;
+  record?: TelegramFailureRecordSink;
+  /** Static context reapplied to every record of this phase, e.g. a session or profile key. */
+  context?: () => Record<string, unknown>;
+  getNowMs?: () => number;
+}
+
+/** Stable identity of one failure kind: errno when present, otherwise the failure text. */
+export function getTelegramFailureSignature(error: unknown): string {
+  const code = (error as NodeJS.ErrnoException | undefined)?.code;
+  if (typeof code === "string" && code) return code;
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Consecutive identical failure runs for one diagnostic phase: a repeat extends the run instead of logging again,
+ * and a closing success or reset emits at most one outcome record. This never gates detection or recovery.
+ */
+export function createTelegramFailureRunLog(
+  input: TelegramFailureRunLogInput,
+): TelegramFailureRunLog {
+  const getNowMs = input.getNowMs ?? Date.now;
+  let run: { signature: string; suppressed: number; startedAtMs: number; details: Record<string, unknown> } | undefined;
+  const emit = (errorOrMessage: unknown, details: Record<string, unknown>): void => {
+    try {
+      input.record?.(input.category, errorOrMessage, {
+        ...(input.context?.() ?? {}),
+        ...details,
+      });
+    } catch {
+      // A diagnostic sink never converts a recorded failure into another failure.
+    }
+  };
+  return {
+    record(error, details) {
+      const signature = getTelegramFailureSignature(error);
+      const admitted = { ...(details ?? {}) };
+      if (run?.signature === signature) {
+        run.suppressed += 1;
+        Object.assign(run.details, admitted);
+        return false;
+      }
+      const previous = run;
+      run = { signature, suppressed: 0, startedAtMs: getNowMs(), details: admitted };
+      emit(error, {
+        ...admitted,
+        phase: input.failurePhase,
+        failureSignature: signature,
+        ...(previous
+          ? {
+              previousFailureSignature: previous.signature,
+              previousFailedAttempts: previous.suppressed + 1,
+              previousFailedForMs: getNowMs() - previous.startedAtMs,
+            }
+          : {}),
+      });
+      return true;
+    },
+    settled() {
+      const closed = run;
+      if (!closed) return undefined;
+      run = undefined;
+      const summary: TelegramFailureRunSummary = {
+        signature: closed.signature,
+        failedAttempts: closed.suppressed + 1,
+        suppressedFailures: closed.suppressed,
+        failedForMs: getNowMs() - closed.startedAtMs,
+      };
+      emit(`Telegram ${input.label} recovered after ${summary.failedAttempts} failed attempts.`, {
+        ...closed.details,
+        phase: input.outcomePhase,
+        failureSignature: summary.signature,
+        failedAttempts: summary.failedAttempts,
+        suppressedFailures: summary.suppressedFailures,
+        failedForMs: summary.failedForMs,
+      });
+      return summary;
+    },
+    reset() {
+      run = undefined;
+    },
+  };
+}
+
 type TelegramLogPathInput = string | (() => string);
 
 interface TelegramRuntimeJsonlEvent {
@@ -391,6 +503,10 @@ interface TelegramRuntimeDiagnosticsRuntime<TContext> {
     error: unknown,
     details?: Record<string, unknown>,
   ): void;
+  /** A phase-scoped failure log whose records travel through this runtime's own event pipeline. */
+  createFailureLog(
+    input: Omit<TelegramFailureRunLogInput, "record">,
+  ): TelegramFailureRunLog;
   bindStorage(ports: {
     getBotToken(): string | undefined;
     getProfileName(): string | undefined;
@@ -498,6 +614,12 @@ export function createTelegramRuntimeDiagnosticsRuntime<TContext>(
   };
   return {
     events,
+    createFailureLog: (input) =>
+      createTelegramFailureRunLog({
+        ...input,
+        record: (category, errorOrMessage, details) =>
+          recordRuntimeEvent(category, errorOrMessage, details),
+      }),
     recordRuntimeEvent,
     bindStorage(ports) {
       getBotToken = ports.getBotToken;

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

@@ -130,6 +130,7 @@ export interface TelegramQueuedOutboundAttachmentView {
 export interface TelegramOutboundAttachmentQueueTargetView {
   queuedAttachments: TelegramQueuedOutboundAttachmentView[];
   guestQueryId?: string;
+  guestInlineMessageId?: string;
 }
 
 export interface TelegramQueuedOutboundAttachmentTurnView extends TelegramOutboundAttachmentQueueTargetView {
@@ -718,6 +719,11 @@ export async function queueTelegramOutboundAttachments(options: {
     maxAttachmentSizeBytes: options.maxAttachmentSizeBytes,
     statPath: options.statPath,
   });
+  if (options.activeTurn.guestInlineMessageId && pendingAttachments.some(
+    (attachment) => getTelegramGuestAttachmentTransport(attachment.path).fileField === "voice",
+  )) {
+    throw new Error("Telegram Guest Mode cannot replace an inline placeholder with a voice note; no attachment was queued. Use MP3 audio or a normal bot chat.");
+  }
   options.activeTurn.queuedAttachments.push(...pendingAttachments);
   const added = pendingAttachments.map((attachment) => attachment.path);
   return {
@@ -733,6 +739,13 @@ export async function queueTelegramOutboundAttachments(options: {
 
 export async function deliverTelegramGuestCachedAttachment(options: {
   guestQueryId: string;
+  guestInlineMessageId?: string;
+  editGuestInlineMessage?: (
+    inlineMessageId: string,
+    content: { media: { type: "photo" | "document" | "audio"; media: string; caption?: string } },
+    options: { assertAuthority: () => void },
+  ) => Promise<void>;
+  isDeliveryActive?: () => boolean;
   stagingChatId: number;
   stagingTarget?: TelegramTarget;
   attachment: TelegramQueuedOutboundAttachmentView;
@@ -750,6 +763,14 @@ export async function deliverTelegramGuestCachedAttachment(options: {
   const transport = getTelegramGuestAttachmentTransport(
     options.attachment.path,
   );
+  const isActive = () => options.isDeliveryActive?.() !== false;
+  const assertActive = () => {
+    if (!isActive()) throw new Error("Guest attachment delivery lost authority.");
+  };
+  if (!isActive()) return;
+  if (options.guestInlineMessageId && (!options.editGuestInlineMessage || transport.fileField === "voice")) {
+    throw new Error("Guest inline attachment editing is unavailable for this media.");
+  }
   let stagingMessageId: number | undefined;
   let answerAttempted = false;
   try {
@@ -764,6 +785,7 @@ export async function deliverTelegramGuestCachedAttachment(options: {
       options.attachment.fileName,
     )) as TelegramGuestStagingMessage;
     stagingMessageId = message.message_id;
+    if (!isActive()) return;
     const caption = options.caption
       ? Array.from(options.caption).slice(0, 1024).join("")
       : undefined;
@@ -810,17 +832,28 @@ export async function deliverTelegramGuestCachedAttachment(options: {
         ...(caption ? { caption } : {}),
       };
     }
+    if (!isActive()) return;
     answerAttempted = true;
-    await options.answerGuestQuery(options.guestQueryId, result);
+    if (options.guestInlineMessageId && options.editGuestInlineMessage) {
+      if (result.type === "voice") throw new Error("Voice notes cannot replace inline placeholders.");
+      const media = result.type === "photo" ? result.photo_file_id
+        : result.type === "audio" ? result.audio_file_id : result.document_file_id;
+      await options.editGuestInlineMessage(options.guestInlineMessageId, {
+        media: { type: result.type, media, ...(caption ? { caption } : {}) },
+      }, { assertAuthority: assertActive });
+    } else {
+      await options.answerGuestQuery(options.guestQueryId, result);
+    }
   } catch (error) {
-    if (!answerAttempted && options.answerGuestText && options.fallbackText) {
+    if (!isActive()) return;
+    if (!options.guestInlineMessageId && !answerAttempted && options.answerGuestText && options.fallbackText) {
       answerAttempted = true;
       await options.answerGuestText(options.guestQueryId, options.fallbackText);
     } else {
       throw error;
     }
   } finally {
-    if (stagingMessageId !== undefined) {
+    if (stagingMessageId !== undefined && isActive()) {
       try {
         await options.deleteMessage(options.stagingChatId, stagingMessageId);
       } catch (error) {

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

@@ -167,13 +167,32 @@ export function resolveTelegramProfileTempFilePath(
   );
 }
 
-export function getTelegramDiagnosticsDisplayPaths(_profileName?: string): {
+/** Shared state/log paths for every profile, under the resolved agent dir (honors `PI_CODING_AGENT_DIR`). */
+export function getTelegramDiagnosticsDisplayPaths(
+  _profileName?: string,
+  agentDir = resolveAgentDir(),
+): {
   state: string;
   logs: string;
 } {
+  // Storage paths are canonical, so also match a canonical home (e.g. /home -> /var/home).
+  const homes = [homedir()];
+  try {
+    homes.push(realpathSync(homes[0]!));
+  } catch {
+    /* An unreadable home only loses the ~ abbreviation. */
+  }
+  const display = (path: string): string => {
+    const home = homes.find(
+      (candidate) => path === candidate || path.startsWith(`${candidate}${sep}`),
+    );
+    return home
+      ? `~${path.slice(home.length).split(sep).join("/")}`
+      : path;
+  };
   return {
-    state: "~/.pi/agent/tmp/pi-telegram/state.json",
-    logs: "~/.pi/agent/tmp/pi-telegram/logs.jsonl",
+    state: display(resolveTelegramStatePath(agentDir)),
+    logs: display(resolveTelegramRuntimeLogPath(agentDir)),
   };
 }
 

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

@@ -6,6 +6,16 @@
 
 type MaybePromise<T> = T | Promise<T>;
 
+/**
+ * Structural port for run-collapsing diagnostics: a repeated identical failure extends its run instead of logging
+ * again, and the closing success records one outcome. The composition root owns the collapsed implementation.
+ */
+export interface TelegramRepeatedFailureLogPort {
+  record: (error: unknown, details?: Record<string, unknown>) => void;
+  settled: () => void;
+  reset: () => void;
+}
+
 export interface TelegramPollingConfig {
   botToken?: string;
 }
@@ -682,6 +692,8 @@ export interface TelegramStartupThreadCapabilityProbeDeps extends TelegramThread
 export interface TelegramThreadCapabilityRuntimeDeps<
   TContext,
 > extends TelegramThreadCapabilityReaderDeps {
+  /** Collapses one sustained probe failure run; the caller supplies its owner. */
+  failureLog: TelegramRepeatedFailureLogPort;
   lifecycle?: TelegramThreadCapabilityLifecycle;
   topicTargetStore: TelegramThreadCapabilityStore;
   ownsLock: (ctx: TContext) => boolean;
@@ -803,6 +815,8 @@ export interface TelegramThreadCapabilityOrchestrationDeps<TContext, TOwner>
   extends
     TelegramThreadCapabilityReaderDeps,
     TelegramThreadAwarePollingControls<TContext, TOwner> {
+  /** Collapses one sustained probe failure run; the composition root supplies its owner. */
+  failureLog: TelegramRepeatedFailureLogPort;
   state: TelegramThreadCapabilityStateRuntime;
   topicTargetStore: TelegramThreadCapabilityStore;
   ownsLock: (ctx: TContext) => boolean;
@@ -882,6 +896,7 @@ export function createTelegramThreadCapabilityOrchestration<TContext, TOwner>(
     isTopicModeUnavailableError: deps.isTopicModeUnavailableError,
     updateStatus: deps.updateStatus,
     recordEvent: deps.recordEvent,
+    failureLog: deps.failureLog,
   };
   return {
     monitor: createTelegramThreadCapabilityMonitor(capabilityDeps),
@@ -1269,8 +1284,34 @@ export function createTelegramThreadCapabilityMonitor<TContext>(
   let generation = 0;
   let transitionPromise: Promise<void> | undefined;
   let consecutiveDisabledProbes = 0;
+  // An absent leader endpoint repeats one identical probe failure every interval; the port collapses the run.
+  // Running it through one guard keeps a faulty diagnostics port from breaking probes or the interval callback.
+  const capabilityFailureLog: TelegramRepeatedFailureLogPort = {
+    record(error, details) {
+      try {
+        deps.failureLog.record(error, details);
+      } catch {
+        // Monitor diagnostics cannot create an uncaught interval exception.
+      }
+    },
+    settled() {
+      try {
+        deps.failureLog.settled();
+      } catch {
+        // Monitor diagnostics cannot fail a completed probe.
+      }
+    },
+    reset() {
+      try {
+        deps.failureLog.reset();
+      } catch {
+        // Monitor diagnostics cannot fail a monitor stop.
+      }
+    },
+  };
   const stop = (): void => {
     generation += 1;
+    capabilityFailureLog.reset();
     if (interval) clearInterval(interval);
     interval = undefined;
     deps.lifecycle?.invalidate();
@@ -1287,6 +1328,7 @@ export function createTelegramThreadCapabilityMonitor<TContext>(
     tracked = readTelegramThreadCapability(deps)
       .then(async (threadModeEnabled) => {
         if (!isCurrent()) return;
+        capabilityFailureLog.settled();
         if (threadModeEnabled === undefined) {
           if (
             deps.topicTargetStore.getBotState().threadMode !== "enabled" &&
@@ -1357,11 +1399,7 @@ export function createTelegramThreadCapabilityMonitor<TContext>(
       })
       .catch((error) => {
         if (!isCurrent()) return;
-        try {
-          deps.recordEvent("bus", error, { phase: "capability-monitor" });
-        } catch {
-          // Monitor diagnostics cannot create an unhandled interval rejection.
-        }
+        capabilityFailureLog.record(error);
       })
       .finally(() => {
         if (transitionPromise === tracked) transitionPromise = undefined;
@@ -1384,11 +1422,7 @@ export function createTelegramThreadCapabilityMonitor<TContext>(
           } catch {
             /* Timer shutdown must not escape the callback. */
           }
-          try {
-            deps.recordEvent("bus", error, { phase: "capability-monitor" });
-          } catch {
-            // Monitor diagnostics cannot create an uncaught interval exception.
-          }
+          capabilityFailureLog.record(error);
         }
       }, intervalMs);
       interval.unref?.();

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

@@ -1983,13 +1983,18 @@ export interface TelegramAgentEndRuntimeDeps<
   ) => Promise<void>;
   sendGuestReply?: (guestQueryId: string, markdown: string) => Promise<void>;
   /** Replaces the early guest ACK with the final text. */
-  editGuestReply?: (inlineMessageId: string, markdown: string) => Promise<void>;
+  editGuestReply?: (
+    inlineMessageId: string,
+    markdown: string,
+    options?: { assertAuthority?: () => void },
+  ) => Promise<void>;
   /** Cancels the animated guest placeholder before the final edit. */
   stopGuestPlaceholder?: (inlineMessageId: string) => Promise<void>;
   sendGuestAttachment?: (
     turn: TTurn,
     attachment: QueuedAttachment,
     caption?: string,
+    options?: { isDeliveryActive?: () => boolean },
   ) => Promise<void>;
   sendGuestVoiceReply?: (
     turn: TTurn,
@@ -2350,13 +2355,46 @@ export async function handleTelegramAgentEndRuntime<
         });
       }
     }
-    if (turn.guestInlineMessageId && deps.editGuestReply) {
-      const experimentText = assistant.errorMessage
+    if (!isDeliveryActive()) return;
+    if (turn.guestInlineMessageId) {
+      let experimentText = assistant.errorMessage
         ? "Telegram bridge: Pi failed while processing the request."
         : finalText;
+      const [attachment] = turn.queuedAttachments;
+      if (!assistant.errorMessage && attachment) {
+        try {
+          if (!deps.sendGuestAttachment) throw new Error("Guest attachment delivery is unavailable.");
+          await deps.sendGuestAttachment(turn, attachment, finalText || undefined, { isDeliveryActive });
+          if (isDeliveryActive() && endPlan.shouldDispatchNext) deps.dispatchNextQueuedTelegramTurn();
+          return;
+        } catch (error) {
+          deps.recordRuntimeEvent?.("delivery", error, {
+            phase: "guest-attachment", guestQueryId: turn.guestQueryId,
+          });
+          if (!isDeliveryActive()) return;
+          if (isTelegramApiCommitUnknownError(error)) {
+            if (endPlan.shouldDispatchNext) deps.dispatchNextQueuedTelegramTurn();
+            return;
+          }
+          experimentText = "Telegram bridge could not deliver the requested attachment. Please retry in a normal bot chat.";
+        }
+      } else if (!assistant.errorMessage && hasOutboundArtifacts) {
+        experimentText = [finalText, "Telegram Guest Mode cannot replace an inline placeholder with a voice note. Please request MP3 audio or use a normal bot chat."].filter(Boolean).join("\n\n");
+      }
+      if (!deps.editGuestReply) {
+        deps.recordRuntimeEvent?.("delivery", new Error("Guest inline reply editing is unavailable."), {
+          phase: "guest-ack-edit", guestQueryId: turn.guestQueryId,
+        });
+        if (endPlan.shouldDispatchNext) deps.dispatchNextQueuedTelegramTurn();
+        return;
+      }
       if (experimentText) {
         try {
-          await deps.editGuestReply(turn.guestInlineMessageId, experimentText);
+          await deps.editGuestReply(turn.guestInlineMessageId, experimentText, {
+            assertAuthority() {
+              if (!isDeliveryActive()) throw new Error("Guest reply edit lost authority.");
+            },
+          });
           deps.recordRuntimeEvent?.(
             "guest",
             new Error("Guest ACK edited the guest answer"),
@@ -2401,6 +2439,7 @@ export async function handleTelegramAgentEndRuntime<
           turn,
           guestAttachment,
           finalText || undefined,
+          { isDeliveryActive },
         );
       } catch (error) {
         deps.recordRuntimeEvent?.("delivery", error, {

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

@@ -1033,13 +1033,14 @@ export function createGuestMarkdownReplyEditor(deps: {
   editGuestInlineMessage: (
     inlineMessageId: string,
     content: { richMessage?: TelegramInputRichMessage; text?: string },
+    options?: { assertAuthority?: () => void },
   ) => Promise<void>;
 }) {
-  return async (inlineMessageId: string, markdown: string) => {
+  return async (inlineMessageId: string, markdown: string, options?: { assertAuthority?: () => void }) => {
     const [richMarkdown = markdown] = splitTelegramNativeMarkdown(markdown);
     await deps.editGuestInlineMessage(inlineMessageId, {
       richMessage: { markdown: richMarkdown },
-    });
+    }, options);
   };
 }