@llblab/pi-kit 0.36.1 → 0.36.3

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

@@ -1,10 +1,10 @@
 /**
  * Telegram prompt injection helpers
  * Zones: pi agent prompts, telegram guidance
- * Owns Telegram-specific system prompt suffixes injected into pi agent turns
+ * Owns stable Telegram guidance, turn-scoped context, and compatibility fallback hooks
  */
 
-import type { BeforeAgentStartEvent } from "./pi.ts";
+import type { BeforeAgentStartEvent, BeforeAgentStartEventResult } from "./pi.ts";
 import { TELEGRAM_PREFIX } from "./turns.ts";
 
 export const TELEGRAM_CONNECTED_CONTEXT_MESSAGE =
@@ -164,18 +164,34 @@ type TelegramBeforeAgentStartResult = {
   systemPrompt: TelegramSystemPrompt;
 };
 
+type TelegramProactiveBeforeAgentStartResult = Omit<BeforeAgentStartEventResult, "systemPrompt"> & {
+  systemPrompt?: TelegramSystemPrompt;
+};
+
 type TelegramBeforeAgentStartHook = (
   event: TelegramBeforeAgentStartEvent,
 ) => TelegramBeforeAgentStartResult;
 
-export function buildTelegramBridgeSystemPrompt(options: {
+// Returning any systemPrompt makes Pi replace its prompt, which defeats prompt
+// caching; return an override only when the computed prompt actually differs.
+function overrideSystemPromptIfChanged(
+  incoming: TelegramSystemPrompt | null | undefined,
+  computed: TelegramSystemPrompt,
+): TelegramBeforeAgentStartResult | undefined {
+  const base = incoming ?? "";
+  const unchanged =
+    Array.isArray(base) && Array.isArray(computed)
+      ? base.length === computed.length &&
+        base.every((block, index) => block === computed[index])
+      : base === computed;
+  return unchanged ? undefined : { systemPrompt: computed };
+}
+
+function buildTelegramTurnSuffix(options: {
   prompt?: string;
-  systemPrompt?: TelegramSystemPrompt | null;
   telegramPrefix?: string;
-  localSystemPromptSuffix: string;
   telegramTurnSystemPromptSuffix: string;
-}): TelegramBeforeAgentStartResult {
-  const basePrompt = options.systemPrompt ?? "";
+}): string {
   const telegramPrefix = options.telegramPrefix ?? TELEGRAM_PREFIX;
   const telegramHead = telegramPrefix.endsWith("]")
     ? telegramPrefix.slice(0, -1)
@@ -184,9 +200,20 @@ export function buildTelegramBridgeSystemPrompt(options: {
   const telegramTurn =
     trimmedPrompt.startsWith(`${telegramHead}]`) ||
     trimmedPrompt.startsWith(`${telegramHead}|`);
-  const telegramSuffix = telegramTurn
+  return telegramTurn
     ? `${options.telegramTurnSystemPromptSuffix}\n- The current user message came from Telegram.`
     : "";
+}
+
+export function buildTelegramBridgeSystemPrompt(options: {
+  prompt?: string;
+  systemPrompt?: TelegramSystemPrompt | null;
+  telegramPrefix?: string;
+  localSystemPromptSuffix: string;
+  telegramTurnSystemPromptSuffix: string;
+}): TelegramBeforeAgentStartResult {
+  const basePrompt = options.systemPrompt ?? "";
+  const telegramSuffix = buildTelegramTurnSuffix(options);
   return {
     systemPrompt: Array.isArray(basePrompt)
       ? [...basePrompt, options.localSystemPromptSuffix + telegramSuffix]
@@ -236,22 +263,58 @@ export interface TelegramProactivePromptHookDeps<TContext> {
   isAvailable: (ctx: TContext) => boolean;
 }
 
+const TELEGRAM_TOOL_NAMES = ["telegram_attach", "telegram_message"];
+
+// Sections cannot modify an opaque prompt owned by an earlier handler.
+// Preserve append/strip compatibility there instead of silently losing guidance.
+function applyTelegramPromptSections(
+  event: TelegramBeforeAgentStartEvent,
+  available: boolean,
+): boolean {
+  const options = event.systemPromptOptions as
+    | Partial<TelegramBeforeAgentStartEvent["systemPromptOptions"]>
+    | undefined;
+  const sections = options?.sections;
+  if (typeof sections !== "object" || sections === null || options?.forceSystemPrompt !== undefined) return false;
+  if (available) {
+    sections.telegram = LOCAL_SYSTEM_PROMPT_SUFFIX.trim();
+    return true;
+  }
+  delete sections.telegram;
+  for (const name of TELEGRAM_TOOL_NAMES) {
+    if (options?.toolSnippets) delete options.toolSnippets[name];
+    if (options?.toolGuidelines) delete options.toolGuidelines[name];
+  }
+  return true;
+}
+
 export function createTelegramProactiveBeforeAgentStartHook<TContext>(
   deps: TelegramProactivePromptHookDeps<TContext>,
 ): (
   event: TelegramBeforeAgentStartEvent,
   ctx: TContext,
-) => Promise<TelegramBeforeAgentStartResult> {
+) => Promise<TelegramProactiveBeforeAgentStartResult | undefined> {
   const baseHook = deps.baseHook ?? createTelegramBeforeAgentStartHook();
   return async (event, ctx) => {
     deps.reconcileAvailability?.();
-    if (!deps.isAvailable(ctx)) {
-      return {
-        systemPrompt: stripTelegramToolMetadataFromSystemPrompt(
-          event.systemPrompt,
-        ),
-      };
+    const available = deps.isAvailable(ctx);
+    // A caller-supplied baseHook owns its own prompt text, so it stays on the forced-prompt path.
+    if (!deps.baseHook && applyTelegramPromptSections(event, available)) {
+      const turnSuffix = available ? buildTelegramTurnSuffix({
+        prompt: event.messageType === "custom" ? undefined : event.prompt,
+        telegramTurnSystemPromptSuffix: TELEGRAM_TURN_SYSTEM_PROMPT_SUFFIX,
+      }).trim() : "";
+      return turnSuffix ? { message: { customType: "telegram-turn", content: turnSuffix, display: false } } : undefined;
+    }
+    if (!available) {
+      return overrideSystemPromptIfChanged(
+        event.systemPrompt,
+        stripTelegramToolMetadataFromSystemPrompt(event.systemPrompt),
+      );
     }
-    return baseHook(event);
+    return overrideSystemPromptIfChanged(
+      event.systemPrompt,
+      baseHook(event).systemPrompt,
+    );
   };
 }

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

@@ -1499,6 +1499,8 @@ export interface TelegramInboundRouteRuntimeDeps<
   getCurrentInstanceId?: () => string | undefined;
   getAdmissionScope?: () => string | undefined;
   getAdmissionJournalBinding?: () => string | undefined;
+  getCommandReplyTarget?:
+    Commands.TelegramCommandTargetRuntimeDeps<TContext>["getReplyTarget"];
   getMessageOwnership?: Updates.TelegramMessageOwnershipLookup;
   getTargetOwnership?: Updates.TelegramTargetOwnershipLookup;
   recordMessageOwnership?: Updates.TelegramMessageOwnershipRecorder;
@@ -1640,7 +1642,7 @@ export interface TelegramInboundRouteRuntimeDeps<
   ) => Promise<void>;
   openSettingsMenu?: (
     chatId: number,
-    replyToMessageId: number,
+    replyToMessageId: number | undefined,
     ctx: TContext,
     threadId?: number,
     options?: Pick<TelegramApiCallOptions, "assertAuthority">,
@@ -1728,7 +1730,7 @@ export interface TelegramInboundRouteRuntimeDeps<
   startGuestPlaceholder?: (inlineMessageId: string) => void;
   sendTextReply: (
     chatId: number,
-    replyToMessageId: number,
+    replyToMessageId: number | undefined,
     text: string,
     options?: {
       parseMode?: "HTML";
@@ -2026,6 +2028,8 @@ export function createTelegramInboundRouteRuntime<
   ): boolean =>
     pending.phase.kind !== "waiting" && pending.phase.kind !== "released";
   const pendingUnboundReroutes = new Map<string, PendingUnboundReroute>();
+  // Body-free, bounded warm deduplication: album members can expire through the same chooser.
+  const expiredRoutingViews = new Set<string>();
   const implicitThreadCreations = new Map<
     string,
     {
@@ -2542,6 +2546,20 @@ export function createTelegramInboundRouteRuntime<
                   temporaryDeleteConfirmed = true;
                 return result;
               } catch (error) {
+                const missingTarget = TelegramApi.getTelegramApiErrorRequestTarget(error);
+                if (method === "deleteForumTopic" && missingTarget && error instanceof Error &&
+                    TelegramApi.isTelegramApiRequestRejected(error, method) &&
+                    TelegramApi.isTelegramStaleTargetHttpError(error) &&
+                    ThreadReconciler.isTelegramTopicDeletedErrorMessage(error.message) &&
+                    missingTarget?.chatId === temporaryCleanup.target?.chatId &&
+                    missingTarget?.threadId === temporaryCleanup.target?.threadId &&
+                    missingTarget?.chatId === body.chat_id && missingTarget?.threadId === body.message_thread_id) {
+                  // Only the client's parsed exact-target HTTP 400 absence closes the one-shot grant.
+                  // Closed/denied/foreign/forged responses remain uncertain and never license another request.
+                  assertExecutionCurrent?.();
+                  temporaryDeleteConfirmed = true;
+                  return true as TResponse;
+                }
                 temporaryTransportUncertain = true;
                 throw error;
               }
@@ -8102,7 +8120,11 @@ export function createTelegramInboundRouteRuntime<
     signal: AbortSignal,
   ): Promise<void> => {
     const operator = deps.configStore.getAllowedUserId(),
-      epoch = deps.getCurrentLeaderEpoch?.();
+      epoch = deps.getCurrentLeaderEpoch?.(),
+      generation = deps.getSessionGeneration?.(),
+      instanceId = deps.getCurrentInstanceId?.(),
+      scope = deps.getAdmissionScope?.();
+    const sendTextReply = deps.sendTextReply, editInteractiveMessage = deps.editInteractiveMessage;
     const message = source.original.update.message as
       Partial<TMessage> | undefined;
     const runtimeCurrent = () =>
@@ -8112,6 +8134,9 @@ export function createTelegramInboundRouteRuntime<
       deps.isContextActive?.(ctx) === true &&
       deps.configStore.getAllowedUserId() === operator &&
       deps.getCurrentLeaderEpoch?.() === epoch &&
+      deps.getSessionGeneration?.() === generation &&
+      deps.getCurrentInstanceId?.() === instanceId &&
+      deps.getAdmissionScope?.() === scope &&
       deps.getAdmissionJournalBinding?.() === source.journalBindingKey &&
       source.original.routingInput?.operatorUserId === operator &&
       message?.from?.id === operator &&
@@ -8142,6 +8167,13 @@ export function createTelegramInboundRouteRuntime<
         if (!result) return;
         // Expiry revokes the donor carrier; old controls and late ACKs cannot issue another delivery. No body is archived.
         let movedIntoTab = false;
+        let unissued = source.original.routingInput?.phase === "waiting" &&
+          (!temporary || temporary.forwardProtocol === "one-shot-v1") &&
+          ![...(temporary?.forwardedInputs ?? []), ...(temporary?.completedInputs ?? [])].some(input =>
+            input.journalBindingKey === source.journalBindingKey && input.updateIds.includes(source.original.updateId));
+        const views = new Map<string, { chatId: number; threadId?: number; messageId: number }>();
+        const chooser = source.original.routingInput?.chooser;
+        if (chooser) views.set(`${chooser.chatId}:${chooser.messageId}`, { ...chooser });
         for (const [id, pending] of pendingUnboundReroutes) {
           if (
             !Updates.collectTelegramAdmissionSourceUpdateIds(
@@ -8150,32 +8182,55 @@ export function createTelegramInboundRouteRuntime<
           )
             continue;
           movedIntoTab ||= pending.allTabCopiesForwarded !== undefined;
+          unissued &&= isPendingRerouteUntouched(pending) || pending.phase.kind === "released";
+          if (pending.chooserMessageId !== undefined)
+            views.set(`${pending.sourceTarget.chatId}:${pending.chooserMessageId}`, {
+              ...pending.sourceTarget, messageId: pending.chooserMessageId,
+            });
           removePendingReroute(id);
-          if (
-            signal.aborted ||
-            deps.isContextActive?.(ctx) !== true ||
-            deps.configStore.getAllowedUserId() !== operator ||
-            deps.getCurrentLeaderEpoch?.() !== epoch ||
-            deps.getAdmissionJournalBinding?.() !== source.journalBindingKey
-          )
-            continue;
-          if (
-            deps.editInteractiveMessage &&
-            pending.chooserMessageId !== undefined
-          ) {
+        }
+        const notice = unissued
+          ? "<b>⌛ Routing expired; input was not delivered.</b>"
+          : "<b>⌛ Routing expired; delivery is unconfirmed.</b>\nPreviously accepted work may continue.";
+        const noticeKey = `${source.journalBindingKey}:${source.original.routingInput?.expiresAtMs}:${chooser ? `${chooser.chatId}:${chooser.messageId}` : source.original.updateId}`;
+        if (runtimeCurrent() && !expiredRoutingViews.has(noticeKey)) {
+          if (expiredRoutingViews.size >= 100) expiredRoutingViews.delete(expiredRoutingViews.values().next().value!);
+          expiredRoutingViews.add(noticeKey);
+          let visible = false;
+          const assertNoticeAuthority = () => {
+            if (!runtimeCurrent()) throw new Error("Routing expiry notice authority changed.");
+          };
+          for (const view of views.values()) {
+            if (!runtimeCurrent() || !editInteractiveMessage || deps.editInteractiveMessage !== editInteractiveMessage) break;
+            if (view.chatId !== message!.chat!.id || !Number.isSafeInteger(view.threadId) || view.threadId! <= 0) continue;
             try {
-              await deps.editInteractiveMessage(
-                pending.sourceTarget.chatId,
-                pending.chooserMessageId,
-                "<b>⌛ Routing choice expired.</b>",
-                "html",
-                { inline_keyboard: [] },
-              );
-            } catch (error) {
-              deps.recordRuntimeEvent?.("routing", error, {
-                phase: "routing-input-expiry-view",
+              await editInteractiveMessage(view.chatId, view.messageId, notice, "html", { inline_keyboard: [] }, {
+                target: { chatId: view.chatId, threadId: view.threadId }, assertAuthority: assertNoticeAuthority,
               });
+              visible = true;
+            } catch (error) {
+              deps.recordRuntimeEvent?.("routing", error, { phase: "routing-input-expiry-view" });
+            }
+          }
+          // A temporary tab is about to disappear; a cold/missing chooser also needs an independent owned destination.
+          const leader = instanceId ? deps.threadStore?.getActiveByInstanceId(instanceId) : undefined;
+          if ((!visible || temporary?.target) && runtimeCurrent() && leader &&
+              leader.target.chatId === message!.chat!.id && Number.isSafeInteger(leader.target.threadId) && leader.target.threadId! > 0) {
+            const target = { chatId: leader.target.chatId, threadId: leader.target.threadId };
+            try {
+              const assertFallback = () => {
+                assertNoticeAuthority();
+                const active = deps.threadStore?.getActiveByInstanceId(instanceId!);
+                if (deps.sendTextReply !== sendTextReply || active?.target.chatId !== target.chatId || active.target.threadId !== target.threadId)
+                  throw new Error("Routing expiry notice destination changed.");
+              };
+              assertFallback();
+              await sendTextReply(target.chatId, 0, notice, { parseMode: "HTML", target, assertAuthority: assertFallback });
+            } catch (error) {
+              deps.recordRuntimeEvent?.("routing", error, { phase: "routing-input-expiry-notice" });
             }
+          } else if (!visible && runtimeCurrent()) {
+            deps.recordRuntimeEvent?.("routing", "Routing expiry notice has no current owned Thread.", { phase: "routing-input-expiry-notice-unavailable" });
           }
         }
         // The scheduled stage captures only context/epoch and a tab token. It reconstructs disposition from body-free proof,
@@ -8434,7 +8489,12 @@ export function createTelegramInboundRouteRuntime<
               )
                 continue;
               try {
-                await retireCancellationChooser(id, pending, isCurrent);
+                if (await retireCancellationChooser(id, pending, isCurrent))
+                  await deleteCancelledOrphanTab(
+                    pending,
+                    pending.abandonment!,
+                    isCurrent,
+                  );
               } catch (error) {
                 deps.recordRuntimeEvent?.("routing", error, {
                   phase: "recovered-chooser-cleanup",
@@ -8463,6 +8523,60 @@ export function createTelegramInboundRouteRuntime<
     }
     return true;
   };
+  /**
+   * A cancelled input in an unbound (non-temporary) tab leaves nothing to route: once no chooser, queue, live owner,
+   * Workspace/Restore record or retained journal arrival still names the tab, it is deleted like a routing tab. Any
+   * missing proof or failure keeps the tab; this never retries and never blocks the Cancel outcome.
+   */
+  const deleteCancelledOrphanTab = async (
+    pending: PendingUnboundReroute,
+    cancellation: NonNullable<PendingUnboundReroute["abandonment"]>,
+    isAuthorityCurrent: () => boolean,
+  ): Promise<void> => {
+    const { chatId, threadId } = pending.sourceTarget;
+    if (
+      threadId === undefined ||
+      pending.temporaryThread ||
+      isTemporaryTabTarget({ chatId, threadId }) ||
+      hasPendingRerouteForTarget({ chatId, threadId }) ||
+      !deps.inspectTemporaryThreadSources
+    )
+      return;
+    const target = { chatId, threadId };
+    try {
+      const own = {
+        journalBindingKey: cancellation.journalBindingKey,
+        updateIds: Updates.collectTelegramAdmissionSourceUpdateIds(
+          pending.messages,
+        ),
+      };
+      const assertCurrent = (): void => {
+        if (!isAuthorityCurrent())
+          throw new Error("Unbound tab cleanup authority changed.");
+      };
+      assertCurrent();
+      if (
+        deps.inspectTemporaryThreadSources(
+          target,
+          [cancellation.journalBindingKey],
+          [own],
+        )?.length !== 0
+      )
+        return;
+      assertCurrent();
+      await closeReroutedUnboundTopic(
+        target,
+        pending.chooserMessageId,
+        assertCurrent,
+      );
+    } catch (error) {
+      deps.recordRuntimeEvent?.("routing", error, {
+        phase: "unbound-cancel-tab-cleanup",
+        chatId: target.chatId,
+        threadId: target.threadId,
+      });
+    }
+  };
   const handleUnboundRerouteCancelCallback = async (
     query: TCallbackQuery,
     ctx: TContext,
@@ -8580,6 +8694,7 @@ export function createTelegramInboundRouteRuntime<
         await Promise.all([
           deps.answerCallbackQuery(query.id, "Routing cancelled"),
           deleteAllTabCopies(pending!),
+          deleteCancelledOrphanTab(pending!, cancellation!, isAuthorityCurrent),
         ]);
     } catch (error) {
       deps.recordRuntimeEvent?.("routing", error, {
@@ -10068,6 +10183,7 @@ export function createTelegramInboundRouteRuntime<
     appendControlItem: deps.queueMutationRuntime.append,
     getAdmissionScope: deps.getAdmissionScope,
     getAdmissionJournalBinding: deps.getAdmissionJournalBinding,
+    getReplyTarget: deps.getCommandReplyTarget,
     onControlQueued: (message, receipt) =>
       reportQueueAdmission([message], [receipt]),
     showStatus: deps.menuActions.sendStatusMessage,

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

@@ -1049,6 +1049,24 @@ export class TelegramApiStaleTargetError extends Error {
   }
 }
 
+/** A follower API refusal; legacy text alone does not prove the request was rejected before execution. */
+export class TelegramApiFollowerNotAllowedError extends Error {
+  readonly requestTarget: { chatId: number; threadId: number } | undefined;
+  /** Present only after a structured pre-execution refusal matches the requested API method. */
+  readonly rejectedRequestMethod: string | undefined;
+
+  constructor(
+    message: string,
+    requestTarget?: { chatId: number; threadId: number },
+    rejectedRequestMethod?: string,
+  ) {
+    super(message);
+    this.name = "TelegramApiFollowerNotAllowedError";
+    this.requestTarget = requestTarget ? { ...requestTarget } : undefined;
+    this.rejectedRequestMethod = rejectedRequestMethod;
+  }
+}
+
 export function getTelegramApiErrorRequestTarget(
   error: unknown,
 ): { chatId: number; threadId: number } | undefined {