@llblab/pi-kit 0.10.5 → 0.10.6

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to `@llblab/pi-kit` are documented here.
 
+## 0.10.6 - 2026-09-12
+
+- `Guest Placeholder And Delivery`: Advances the exact Telegram pin to `0.45.6`, so the guest ACK rotates the globe placeholder in whole cycles and holds `🌏 Working on it...`, guest answers are still delivered when a companion extension suppresses the final assistant message, `429` retry waits are recorded as `api` runtime events, the Thread display settings card drops the manual `/name` hint, and empty-queue headings carry no trailing period. The package set, resource inventory, and explicit load order remain unchanged.
+
 ## 0.10.5 - 2026-09-11
 
 - `State Flow Telegram Surface`: Advances the exact State Flow pin to `0.9.6`, so the submenu help line is exactly what State Flow records and when a new session resumes from the last committed point, and the state value (`off` or `#N`) renders in monospace. The package set, resource inventory, and explicit load order remain unchanged.

package/README.md

@@ -15,7 +15,7 @@ Package links lead to the owning repositories for usage, documentation, issues,
 | [`@llblab/pi-codex-usage`](https://github.com/llblab/pi-codex-usage) | `0.9.4` | Compact Codex/Spark subscription-limit status |
 | [`@llblab/pi-grow-loop`](https://github.com/llblab/pi-grow-loop) | `0.8.1` | Visible continuation scheduling and bounded worker Skills |
 | [`@llblab/pi-state-flow`](https://github.com/llblab/pi-state-flow) | `0.9.6` | Atomic scoped state cohorts with final-eligibility resolution |
-| [`@llblab/pi-telegram`](https://github.com/llblab/pi-telegram) | `0.45.5` | Telegram companion, queues, files, voice, controls, and Generative Apps guidance |
+| [`@llblab/pi-telegram`](https://github.com/llblab/pi-telegram) | `0.45.6` | Telegram companion, queues, files, voice, controls, and Generative Apps guidance |
 | [`@llblab/skills`](https://github.com/llblab/skills) | `1.15.0` | Portable workflows for engineering, review, design, context maintenance, and other focused tasks |
 
 Versions are exact by design. An upstream release does not change an installed kit until this repository explicitly advances the dependency and publishes a new kit version. Runtime defects and package-specific feature requests belong in the linked repository; package selection and kit installation issues belong here.

package/node_modules/@llblab/pi-telegram/CHANGELOG.md

@@ -4,6 +4,14 @@
 
 ## Unreleased
 
+## 0.45.6: Guest Placeholder And Delivery Hotfix
+
+- `Guest Placeholder`: The guest ACK answers with the first bold globe frame (`🌎 Working on it.`) and rotates `🌍`/`🌏` once per second with the dots growing every two seconds. Rotation now completes whole 6-frame cycles and stops only after the 20 s minimum, so a pending answer holds the cycle's final frame (`🌏 Working on it...`) instead of cutting mid-step; a 26 s safety bound stays clear of the ~28 s Telegram flood-control wall, and error backoff and pre-replacement cancellation are unchanged.
+- `Guest Answer Delivery`: The guest replacement now falls back to the run's latest completed assistant text when Pi's final assistant message is empty, so an answer preserved by a companion extension's fallback turn (for example State Flow's suppressed final:true patch turn) is still edited into the guest message instead of being skipped as "no editable text".
+- `Rate-Limit Visibility`: A `429` retry wait now records an `api` runtime event with the method, wait duration, attempt, and server `retry_after`, so a silent flood-control pause before the final guest replacement is visible in the runtime log instead of appearing only as a frozen frame.
+- `Thread Display Hint`: The Thread display settings card no longer carries the manual `/name Name` override hint; the current-value line, the three mode descriptions, and the live chooser are unchanged.
+- `Queue Empty Headings`: The default empty-queue line and every rotating refresh title drop the trailing period, so the fully bold queue headings read as headings; wording, emoji, rotation order, callbacks, and refresh behavior are unchanged.
+
 ## 0.45.5: Queue Refresh Icon Hotfix
 
 - `Queue Refresh Icon`: The queue menu's Refresh row now uses `🔄`, the canonical refresh glyph, reserving `🌀` for the State Flow Telegram identity. The button label is the only change; queue refresh behavior, callbacks, and the rotating empty-queue notices are unchanged.

package/node_modules/@llblab/pi-telegram/docs/ui-style.md

@@ -104,7 +104,7 @@ The menu may clear internal Skip but cannot remove a reaction created by the use
 
 ### Decorative Or Local-Example Emoji
 
-Some emoji are intentionally local examples or decorative variants, not global semantics. Empty-queue rotating messages (`🫙`, `🍃`, `🕳`, `🦗`, `🌙`, `🧘`, `🪐`, `🧺`, `🔭`, `🫧`, `🛸`) are copy flavor only and must not become controls. Example extension icons such as `🧪`, `🔧`, and `🗂` are documentation fixtures for companion extensions, not built-in pi-telegram meanings.
+Some emoji are intentionally local examples or decorative variants, not global semantics. Empty-queue rotating messages (`🫙`, `🍃`, `🕳`, `🦗`, `🌙`, `🧘`, `🪐`, `🧺`, `🔭`, `🫧`, `🛸`) are copy flavor only and must not become controls. The Guest Mode placeholder frames (`🌎`, `🌍`, `🌏` stepping every second with dots growing once every two seconds) are the same kind of decorative copy: they complete whole 6-frame cycles over at least a ~20 s rotation while a guest answer is pending and then hold the cycle's final frame (a 26 s safety bound caps slow streams), never become controls, and must not carry another meaning. Example extension icons such as `🧪`, `🔧`, and `🗂` are documentation fixtures for companion extensions, not built-in pi-telegram meanings.
 
 Thread UI rule: when a message heading, chooser, or status line is specifically about Telegram/Pi threads or target thread selection, start the heading with `🧵`. Button labels for concrete thread targets should stay clean (`threadName` or slot fallback) and should not add `🧵` to every target button unless the row would otherwise be ambiguous.
 
@@ -224,7 +224,7 @@ Message cards and standalone informational notices sent by the bot should start
 Rules:
 
 - Start with a bold heading or, for dialogs, a bold question.
-- Format standalone notices as one fully bold line: relevant emoji, one space, concise sentence, and terminal period. Menu or chooser headings use the same fully bold form but end in a colon when controls or detail follow.
+- Format standalone notices as one fully bold line: relevant emoji, one space, concise sentence, and terminal period. Menu or chooser headings use the same fully bold form but end in a colon when controls or detail follow. Empty-queue headings are the deliberate exception: fully bold, with no trailing period or colon.
 - Keep the emoji and complete sentence or heading inside the single bold span; do not bold only a fragment. A material name or phrase may receive nested italic emphasis without breaking the outer bold hierarchy—for example `<b>📡 Instance <i>Cedar</i> connected.</b>`.
 - Apply the same hierarchy to success, progress, empty, busy, unavailable, cancellation, and failure notices.
 - Callback alerts remain plain text because Telegram does not support rich text there, but still keep the relevant emoji and concise sentence.

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

@@ -823,6 +823,12 @@ interface TelegramLifecycleBindingDeps {
     Pi.AgentEndEvent["messages"][number],
     Keyboard.TelegramInlineKeyboardMarkup
   >["editGuestReply"];
+  stopGuestPlaceholder?: Queue.TelegramAgentEndHookRuntimeDeps<
+    Queue.PendingTelegramTurn,
+    Pi.ExtensionContext,
+    Pi.AgentEndEvent["messages"][number],
+    Keyboard.TelegramInlineKeyboardMarkup
+  >["stopGuestPlaceholder"];
   preparePreviewDelivery?: Queue.TelegramAgentEndRuntimeDeps<Queue.PendingTelegramTurn>["preparePreviewDelivery"];
   finalizeMarkdownPreview: Queue.TelegramAgentEndHookRuntimeDeps<
     Queue.PendingTelegramTurn,
@@ -876,6 +882,7 @@ export function registerTelegramLifecycleRuntimeHooks({
   deleteMessage,
   sendGuestReply,
   editGuestReply,
+  stopGuestPlaceholder,
   preparePreviewDelivery,
   finalizeMarkdownPreview,
   proactivePushTargetGetter,
@@ -1056,7 +1063,7 @@ export function registerTelegramLifecycleRuntimeHooks({
     updateStatus,
     getActiveTurn: activeTurnRuntime.get,
     loadConfig: configStore.load,
-    extractAssistant: Replies.extractLatestAssistantMessageText,
+    extractAssistant: Replies.extractRunAssistantMessage,
     getFoldQueuedPromptsIntoHistory:
       lifecycle.shouldFoldQueuedPromptsIntoHistory,
     resetRuntimeState: agentEndResetter,
@@ -1090,6 +1097,7 @@ export function registerTelegramLifecycleRuntimeHooks({
     answerGuestQuery,
     sendGuestReply,
     editGuestReply,
+    stopGuestPlaceholder,
     sendGuestAttachment,
     sendGuestVoiceReply,
     planOutboundReply: outboundReplyPlanner,

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

@@ -1429,7 +1429,7 @@ export async function handleTelegramNextCommand(deps: {
   deps.clearPendingModelSwitch();
   if (!deps.hasQueuedItems()) {
     await deps.sendTextReply(
-      formatTelegramInformationHeading("⌛", "Queue is empty."),
+      formatTelegramInformationHeading("⌛", "Queue is empty"),
       { parseMode: "HTML" },
     );
     return;

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

@@ -588,6 +588,12 @@ export default function (pi: Pi.ExtensionAPI) {
   const editGuestReply = Replies.createGuestMarkdownReplyEditor({
     editGuestInlineMessage: telegramApiRuntime.editGuestInlineMessage,
   });
+  // Rotate the guest placeholder frames until the final replacement stops them.
+  const guestPlaceholderRuntime =
+    Replies.createTelegramGuestPlaceholderRuntime({
+      editGuestInlineMessage: telegramApiRuntime.editGuestInlineMessage,
+      recordRuntimeEvent,
+    });
 
   const promptDispatchRuntime = Runtime.createTelegramPromptDispatchRuntime({
     lifecycle,
@@ -978,6 +984,7 @@ export default function (pi: Pi.ExtensionAPI) {
     deleteMessage: deleteTelegramMessage,
     answerGuestQuery,
     answerGuestQueryForInlineMessage,
+    startGuestPlaceholder: guestPlaceholderRuntime.start,
     sendTextReply,
     setMyCommands,
     validateThreadName(threadName) {
@@ -1508,6 +1515,7 @@ export default function (pi: Pi.ExtensionAPI) {
         },
         capabilityMonitor: telegramThreadCapabilityMonitor,
         queueWatchdog: queueDispatchWatchdogRuntime,
+        guestPlaceholder: { stopAll: guestPlaceholderRuntime.stopAll },
       },
     });
   const sessionLifecycleRuntime =
@@ -1828,6 +1836,7 @@ export default function (pi: Pi.ExtensionAPI) {
     deleteMessage: deleteTelegramMessage,
     sendGuestReply,
     editGuestReply,
+    stopGuestPlaceholder: guestPlaceholderRuntime.stop,
     finalizeMarkdownPreview,
     preparePreviewDelivery,
     proactivePushTargetGetter,

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

@@ -265,6 +265,7 @@ export interface TelegramBridgeSessionServiceRuntime {
   inboundWorker: { onSessionShutdown(): Promise<void> };
   capabilityMonitor: { start(ctx: ExtensionContext): void; stop(): void };
   queueWatchdog: { start(ctx: ExtensionContext): void; stop(): void };
+  guestPlaceholder?: { stopAll(): void };
 }
 
 export interface TelegramBridgeSessionLifecycleAssemblyDeps<
@@ -320,6 +321,7 @@ export interface TelegramBridgeSessionLifecyclePorts<
     inboundWorker: TelegramBridgeSessionServiceRuntime["inboundWorker"];
     capabilityMonitor: TelegramBridgeSessionServiceRuntime["capabilityMonitor"];
     queueWatchdog: TelegramBridgeSessionServiceRuntime["queueWatchdog"];
+    guestPlaceholder?: TelegramBridgeSessionServiceRuntime["guestPlaceholder"];
   };
 }
 
@@ -347,6 +349,7 @@ export function createTelegramBridgeSessionLifecycleDeps<
       inboundWorker: ports.services.inboundWorker,
       capabilityMonitor: ports.services.capabilityMonitor,
       queueWatchdog: ports.services.queueWatchdog,
+      guestPlaceholder: ports.services.guestPlaceholder,
     },
   };
 }
@@ -383,6 +386,7 @@ export function createTelegramBridgeSessionLifecycleAssembly<
     },
     async onSessionShutdown(event, ctx) {
       if (!isSessionActive(ctx)) return;
+      deps.services.guestPlaceholder?.stopAll();
       await deps.services.delivery.onSessionShutdown();
       if (!isSessionActive(ctx)) return;
       deps.services.queueWatchdog.stop();

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

@@ -14,18 +14,18 @@ import * as Queue from "./queue.ts";
 const QUEUE_ITEM_PROMPT_HTML_LIMIT = 3600;
 const QUEUE_ITEM_PROMPT_TRUNCATION_SUFFIX = "\n… [truncated]";
 const EMPTY_QUEUE_REFRESH_TITLES = [
-  "<b>⌛ Queue is still empty.</b>",
-  "<b>🫙 Still nothing in queue.</b>",
-  "<b>🍃 Queue remains empty.</b>",
-  "<b>🕳 Nothing queued yet.</b>",
-  "<b>🦗 Queue crickets continue.</b>",
-  "<b>🌙 Queue is peacefully idle.</b>",
-  "<b>🧘 Nothing waiting. Very zen.</b>",
-  "<b>🪐 Queue orbit is clear.</b>",
-  "<b>🧺 Basket is empty.</b>",
-  "<b>🔭 No prompts on the horizon.</b>",
-  "<b>🫧 Queue bubbles: none.</b>",
-  "<b>🛸 No queued signals detected.</b>",
+  "<b>⌛ Queue is still empty</b>",
+  "<b>🫙 Still nothing in queue</b>",
+  "<b>🍃 Queue remains empty</b>",
+  "<b>🕳 Nothing queued yet</b>",
+  "<b>🦗 Queue crickets continue</b>",
+  "<b>🌙 Queue is peacefully idle</b>",
+  "<b>🧘 Nothing waiting. Very zen</b>",
+  "<b>🪐 Queue orbit is clear</b>",
+  "<b>🧺 Basket is empty</b>",
+  "<b>🔭 No prompts on the horizon</b>",
+  "<b>🫧 Queue bubbles: none</b>",
+  "<b>🛸 No queued signals detected</b>",
 ] as const;
 type TelegramQueueMenuReplyMarkup = TelegramInlineKeyboardMarkup;
 interface TelegramQueueMenuItem {
@@ -340,7 +340,7 @@ function getTelegramQueueMenuListText(
   emptyRefreshIndex?: number,
 ): string {
   if (items.length > 0) return "<b>⏳ Queue:</b>";
-  if (emptyRefreshIndex === undefined) return "<b>⌛ Queue is empty.</b>";
+  if (emptyRefreshIndex === undefined) return "<b>⌛ Queue is empty</b>";
   return EMPTY_QUEUE_REFRESH_TITLES[
     emptyRefreshIndex % EMPTY_QUEUE_REFRESH_TITLES.length
   ];

package/node_modules/@llblab/pi-telegram/lib/menu-settings.ts

@@ -184,7 +184,6 @@ export function buildThreadDisplaySettingsText(mode: TelegramThreadDisplayMode):
     "<code>-</code> <code>letters</code> (default): show the unique slot, such as <b><i>A</i></b> or <b><i>B</i></b>.",
     "<code>-</code> <code>names</code>: show the generated dictionary name for the slot, such as <b><i>Anchor</i></b> or <b><i>Briar</i></b>.",
     "<code>-</code> <code>directories</code>: show the directory, such as <b><i>extensions</i></b>; shared Workspaces keep slot suffixes, such as <b><i>extensions_a</i></b> and <b><i>extensions_c</i></b>.",
-    "A manual <code>/name Name</code> overrides this Thread display name until reset.",
   ].join("\n");
 }
 

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

@@ -1554,6 +1554,8 @@ export interface TelegramAgentEndRuntimeDeps<
   sendGuestReply?: (guestQueryId: string, markdown: string) => Promise<void>;
   /** Replaces the early guest ACK with the final text. */
   editGuestReply?: (inlineMessageId: string, markdown: string) => Promise<void>;
+  /** Cancels the animated guest placeholder before the final edit. */
+  stopGuestPlaceholder?: (inlineMessageId: string) => Promise<void>;
   sendGuestAttachment?: (
     turn: TTurn,
     attachment: QueuedAttachment,
@@ -1633,6 +1635,7 @@ export interface TelegramAgentEndHookRuntimeDeps<
   answerGuestQuery?: TelegramAgentEndRuntimeDeps<TTurn>["answerGuestQuery"];
   sendGuestReply?: TelegramAgentEndRuntimeDeps<TTurn>["sendGuestReply"];
   editGuestReply?: TelegramAgentEndRuntimeDeps<TTurn>["editGuestReply"];
+  stopGuestPlaceholder?: TelegramAgentEndRuntimeDeps<TTurn>["stopGuestPlaceholder"];
   sendGuestAttachment?: TelegramAgentEndRuntimeDeps<TTurn>["sendGuestAttachment"];
   sendGuestVoiceReply?: TelegramAgentEndRuntimeDeps<TTurn>["sendGuestVoiceReply"];
   planOutboundReply?: TelegramAgentEndRuntimeDeps<
@@ -1774,6 +1777,7 @@ export function createTelegramAgentEndHook<
         answerGuestQuery: deps.answerGuestQuery,
         sendGuestReply: deps.sendGuestReply,
         editGuestReply: deps.editGuestReply,
+        stopGuestPlaceholder: deps.stopGuestPlaceholder,
         sendGuestAttachment: deps.sendGuestAttachment,
         sendGuestVoiceReply: deps.sendGuestVoiceReply,
         planOutboundReply: deps.planOutboundReply,
@@ -1866,6 +1870,16 @@ export async function handleTelegramAgentEndRuntime<
     return;
   }
   if (turn.guestQueryId) {
+    if (turn.guestInlineMessageId && deps.stopGuestPlaceholder) {
+      try {
+        await deps.stopGuestPlaceholder(turn.guestInlineMessageId);
+      } catch (error) {
+        deps.recordRuntimeEvent?.("delivery", error, {
+          phase: "guest-placeholder-stop",
+          guestQueryId: turn.guestQueryId,
+        });
+      }
+    }
     if (turn.guestInlineMessageId && deps.editGuestReply) {
       const experimentText = assistant.errorMessage
         ? "Telegram bridge: Pi failed while processing the request."
@@ -1875,7 +1889,7 @@ export async function handleTelegramAgentEndRuntime<
           await deps.editGuestReply(turn.guestInlineMessageId, experimentText);
           deps.recordRuntimeEvent?.(
             "guest",
-            new Error("Guest ACK experiment edited the guest answer"),
+            new Error("Guest ACK edited the guest answer"),
             { phase: "guest-ack-edited", guestQueryId: turn.guestQueryId },
           );
         } catch (error) {
@@ -1887,7 +1901,7 @@ export async function handleTelegramAgentEndRuntime<
       } else {
         deps.recordRuntimeEvent?.(
           "delivery",
-          new Error("Guest ACK experiment turn produced no editable text"),
+          new Error("Guest ACK turn produced no editable text"),
           { phase: "guest-ack-edit-empty", guestQueryId: turn.guestQueryId },
         );
       }

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

@@ -1,7 +1,7 @@
 /**
  * Telegram reply delivery helpers
  * Zones: telegram outbound, native rich markdown, UI/compat rendering transport
- * Owns native assistant replies, rendered UI delivery, reply transport wiring, and plain text replies
+ * Owns native assistant replies, rendered UI delivery, guest placeholder rotation, reply transport wiring, and plain text replies
  */
 
 import { assertTelegramInlineKeyboardCallbackData } from "./keyboard.ts";
@@ -177,6 +177,47 @@ export function extractLatestAssistantMessageText(
   return {};
 }
 
+/**
+ * Extract the run's answer without trusting an empty final assistant message.
+ * A low-level run may end with a completed assistant message whose content was
+ * suppressed (a companion extension preserving an earlier draft, for example
+ * State Flow's fallback final:true patch turn). In that case the run's answer
+ * is the latest earlier completed assistant message that carries text;
+ * tool-use prefaces, errors, and aborts stay excluded.
+ */
+export function extractRunAssistantMessage(
+  messages: readonly unknown[],
+): {
+  text?: string;
+  stopReason?: string;
+  errorMessage?: string;
+} {
+  const latest = extractLatestAssistantMessageText(messages);
+  if (latest.text || latest.stopReason !== "stop") return latest;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (!message || !isAssistantAgentMessage(message)) continue;
+    const rawStopReason = getAgentMessageField(message, "stopReason");
+    if (
+      rawStopReason === "toolUse" ||
+      rawStopReason === "error" ||
+      rawStopReason === "aborted"
+    ) {
+      continue;
+    }
+    const text = getAgentMessageText(message);
+    if (!text) continue;
+    const rawErrorMessage = getAgentMessageField(message, "errorMessage");
+    return {
+      text,
+      stopReason: typeof rawStopReason === "string" ? rawStopReason : undefined,
+      errorMessage:
+        typeof rawErrorMessage === "string" ? rawErrorMessage : undefined,
+    };
+  }
+  return latest;
+}
+
 export interface TelegramReplyOwnershipRecorder {
   record: (input: {
     chatId: number;
@@ -900,9 +941,9 @@ export function createGuestMarkdownReplySender(deps: {
 }
 
 /**
- * Guest reply editor: replaces an early Guest Mode answer (the temporary ACK
- * experiment) with native Rich Markdown content addressed by
- * `inline_message_id` instead of a chat/message pair.
+ * Guest reply editor: replaces the early Guest Mode placeholder ACK with
+ * native Rich Markdown content addressed by `inline_message_id` instead of a
+ * chat/message pair.
  */
 export function createGuestMarkdownReplyEditor(deps: {
   editGuestInlineMessage: (
@@ -917,3 +958,219 @@ export function createGuestMarkdownReplyEditor(deps: {
     });
   };
 }
+
+/**
+ * Guest Mode placeholder rotation: the early ACK is the first placeholder
+ * frame and the runtime steps the remaining frames once per interval, moving
+ * the globe every second while the trailing dots grow once every two seconds.
+ *
+ * Rotation completes whole six-frame cycles and only stops once at least
+ * `TELEGRAM_GUEST_PLACEHOLDER_MIN_MS` has elapsed, so a pending answer holds
+ * the finished cycle's last frame (`🌏 Working on it...`) instead of whatever
+ * step a hard time cap happens to cut. The `TELEGRAM_GUEST_PLACEHOLDER_MAX_MS`
+ * safety bound keeps the edit stream clear of the first flood-control
+ * rejections measured in live guest runs (+26.5 s at ~53 edits, +27.8 s at
+ * ~28 edits): rotation caps at 23 edits and never starts a frame after 26 s.
+ */
+
+export const TELEGRAM_GUEST_PLACEHOLDER_FRAME_MS = 1_000;
+
+export const TELEGRAM_GUEST_PLACEHOLDER_MIN_MS = 20_000;
+
+export const TELEGRAM_GUEST_PLACEHOLDER_MAX_MS = 26_000;
+
+export const TELEGRAM_GUEST_PLACEHOLDER_FRAMES = [
+  "<b>🌎 Working on it.</b>",
+  "<b>🌍 Working on it.</b>",
+  "<b>🌏 Working on it..</b>",
+  "<b>🌎 Working on it..</b>",
+  "<b>🌍 Working on it...</b>",
+  "<b>🌏 Working on it...</b>",
+] as const;
+
+export function buildTelegramGuestPlaceholderFrame(step: number): string {
+  const frames: readonly string[] = TELEGRAM_GUEST_PLACEHOLDER_FRAMES;
+  const index = ((step % frames.length) + frames.length) % frames.length;
+  return frames[index]!;
+}
+
+export interface TelegramGuestPlaceholderRuntimeDeps {
+  editGuestInlineMessage: (
+    inlineMessageId: string,
+    content: { text: string; parseMode: "HTML" },
+  ) => Promise<void>;
+  recordRuntimeEvent?: (
+    category: string,
+    error: unknown,
+    details?: Record<string, unknown>,
+  ) => void;
+  intervalMs?: number;
+  minMs?: number;
+  maxMs?: number;
+  now?: () => number;
+  setTimer?: (
+    callback: () => void,
+    ms: number,
+  ) => ReturnType<typeof setTimeout>;
+  clearTimer?: (timer: ReturnType<typeof setTimeout>) => void;
+}
+
+export interface TelegramGuestPlaceholderRuntime {
+  /** Starts the frame loop on an answered guest inline message. */
+  start: (inlineMessageId: string) => void;
+  /** Cancels the loop and waits for any in-flight frame edit before returning. */
+  stop: (inlineMessageId: string) => Promise<void>;
+  /** Cancels every loop without waiting for in-flight edits (session shutdown). */
+  stopAll: () => void;
+}
+
+interface TelegramGuestPlaceholderSession {
+  step: number;
+  stopped: boolean;
+  startedAtMs: number;
+  finished: boolean;
+  timer?: ReturnType<typeof setTimeout>;
+  inflight?: Promise<void>;
+}
+
+function getTelegramGuestPlaceholderRetryDelayMs(
+  error: unknown,
+  fallbackMs: number,
+): number {
+  const retryAfterSeconds = (
+    error as { retryAfterSeconds?: unknown } | undefined
+  )?.retryAfterSeconds;
+  return typeof retryAfterSeconds === "number" && retryAfterSeconds > 0
+    ? Math.max(fallbackMs, retryAfterSeconds * 1_000)
+    : fallbackMs;
+}
+
+export function createTelegramGuestPlaceholderRuntime(
+  deps: TelegramGuestPlaceholderRuntimeDeps,
+): TelegramGuestPlaceholderRuntime {
+  const intervalMs = deps.intervalMs ?? TELEGRAM_GUEST_PLACEHOLDER_FRAME_MS;
+  const minMs = deps.minMs ?? TELEGRAM_GUEST_PLACEHOLDER_MIN_MS;
+  const maxMs = deps.maxMs ?? TELEGRAM_GUEST_PLACEHOLDER_MAX_MS;
+  const now = deps.now ?? Date.now;
+  const setTimer =
+    deps.setTimer ??
+    ((callback: () => void, ms: number): ReturnType<typeof setTimeout> =>
+      setTimeout(callback, ms));
+  const clearTimer =
+    deps.clearTimer ??
+    ((timer: ReturnType<typeof setTimeout>): void => clearTimeout(timer));
+  const sessions = new Map<string, TelegramGuestPlaceholderSession>();
+
+  const finishRotation = (
+    session: TelegramGuestPlaceholderSession,
+    elapsedMs: number,
+  ): void => {
+    if (session.finished) return;
+    session.finished = true;
+    deps.recordRuntimeEvent?.(
+      "guest",
+      "Guest placeholder rotation reached its bound",
+      {
+        phase: "guest-placeholder-capped",
+        minMs,
+        maxMs,
+        elapsedMs,
+        step: session.step,
+      },
+    );
+  };
+
+  const scheduleFrame = (
+    inlineMessageId: string,
+    session: TelegramGuestPlaceholderSession,
+    delayMs: number,
+  ): void => {
+    if (session.stopped) return;
+    const elapsedMs = now() - session.startedAtMs;
+    const frameCount = TELEGRAM_GUEST_PLACEHOLDER_FRAMES.length;
+    const cycleComplete =
+      session.step > 0 && session.step % frameCount === frameCount - 1;
+    if (cycleComplete && elapsedMs >= minMs) {
+      finishRotation(session, elapsedMs);
+      return;
+    }
+    if (elapsedMs + delayMs > maxMs) {
+      finishRotation(session, elapsedMs);
+      return;
+    }
+    const timer = setTimer(() => {
+      session.timer = undefined;
+      runFrame(inlineMessageId, session);
+    }, delayMs);
+    timer.unref?.();
+    session.timer = timer;
+  };
+
+  const runFrame = (
+    inlineMessageId: string,
+    session: TelegramGuestPlaceholderSession,
+  ): void => {
+    if (session.stopped) return;
+    session.step += 1;
+    let nextDelayMs = intervalMs;
+    session.inflight = (async () => {
+      try {
+        await deps.editGuestInlineMessage(inlineMessageId, {
+          text: buildTelegramGuestPlaceholderFrame(session.step),
+          parseMode: "HTML",
+        });
+      } catch (error) {
+        nextDelayMs = getTelegramGuestPlaceholderRetryDelayMs(error, intervalMs);
+        deps.recordRuntimeEvent?.("guest", error, {
+          phase: "guest-placeholder-edit",
+          retryAfterMs: nextDelayMs,
+        });
+      } finally {
+        session.inflight = undefined;
+        scheduleFrame(inlineMessageId, session, nextDelayMs);
+      }
+    })();
+  };
+
+  const stop = async (inlineMessageId: string): Promise<void> => {
+    const session = sessions.get(inlineMessageId);
+    if (!session) return;
+    sessions.delete(inlineMessageId);
+    session.stopped = true;
+    if (session.timer !== undefined) {
+      clearTimer(session.timer);
+      session.timer = undefined;
+    }
+    try {
+      await session.inflight;
+    } catch {
+      // Frame failures are reported as runtime events; stopping stays fail-open.
+    }
+  };
+
+  return {
+    start(inlineMessageId) {
+      const existing = sessions.get(inlineMessageId);
+      if (existing) {
+        existing.stopped = true;
+        if (existing.timer !== undefined) clearTimer(existing.timer);
+      }
+      const session: TelegramGuestPlaceholderSession = {
+        step: 0,
+        stopped: false,
+        startedAtMs: now(),
+        finished: false,
+      };
+      sessions.set(inlineMessageId, session);
+      scheduleFrame(inlineMessageId, session, intervalMs);
+    },
+    stop,
+    stopAll() {
+      for (const session of sessions.values()) {
+        session.stopped = true;
+        if (session.timer !== undefined) clearTimer(session.timer);
+      }
+      sessions.clear();
+    },
+  };
+}

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

@@ -16,6 +16,7 @@ import * as Model from "./model.ts";
 import * as OutboundHandlers from "./outbound.ts";
 import * as PromptTemplates from "./prompt-templates.ts";
 import * as Queue from "./queue.ts";
+import * as Replies from "./replies.ts";
 import type { TelegramBridgeRuntime } from "./runtime.ts";
 import type { TelegramSectionRegistry } from "./sections.ts";
 import * as TextGroups from "./text-groups.ts";
@@ -665,6 +666,8 @@ export interface TelegramInboundRouteRuntimeDeps<
     text: string,
     options?: { parseMode?: "HTML" },
   ) => Promise<string | undefined>;
+  /** Starts the animated placeholder on an answered guest inline message. */
+  startGuestPlaceholder?: (inlineMessageId: string) => void;
   sendTextReply: (
     chatId: number,
     replyToMessageId: number,
@@ -2662,8 +2665,10 @@ export function createTelegramInboundRouteRuntime<
     assertExecutionCurrent();
   };
   // Answer the guest query immediately so the agent-end edit can replace the
-  // early ACK once the turn settles. See BACKLOG.md for live acceptance.
-  const TELEGRAM_GUEST_ACK_HTML = "<b>⚙️ Received. Working on it…</b>";
+  // early ACK once the turn settles. The ACK is the first placeholder frame and
+  // the loop rotates through the remaining frames until the replacement.
+  const TELEGRAM_GUEST_ACK_HTML =
+    Replies.buildTelegramGuestPlaceholderFrame(0);
   const handleAuthorizedTelegramGuestMessage = async (
     guestMessage: Updates.TelegramGuestMessage & { from: TelegramUser },
     ctx: TContext,
@@ -2679,9 +2684,12 @@ export function createTelegramInboundRouteRuntime<
           TELEGRAM_GUEST_ACK_HTML,
           { parseMode: "HTML" },
         );
+        if (guestInlineMessageId) {
+          deps.startGuestPlaceholder?.(guestInlineMessageId);
+        }
         deps.recordRuntimeEvent?.(
           "guest",
-          new Error("Guest ACK experiment answered the guest query"),
+          new Error("Guest ACK answered the guest query"),
           {
             phase: "guest-ack-sent",
             guestQueryId: guestMessage.guest_query_id,

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

@@ -374,6 +374,13 @@ interface TelegramApiResponse<T> {
   parameters?: { retry_after?: number };
 }
 
+export interface TelegramApiRetryWait {
+  method: string;
+  delayMs: number;
+  attempt: number;
+  retryAfterSeconds?: number;
+}
+
 export interface TelegramApiCallOptions {
   signal?: AbortSignal;
   maxAttempts?: number;
@@ -381,6 +388,8 @@ export interface TelegramApiCallOptions {
   retrySafety?: "safe" | "non-idempotent";
   retryBaseDelayMs?: number;
   sleep?: (ms: number) => Promise<void>;
+  /** Observability hook fired before a 429 retry wait, never for 5xx waits. */
+  onRetryWait?: (wait: TelegramApiRetryWait) => void;
 }
 
 interface TelegramGetFileResult {
@@ -434,6 +443,7 @@ export interface TelegramAnswerGuestQueryOptions {
 export interface TelegramEditGuestInlineMessageContent {
   text?: string;
   richMessage?: TelegramInputRichMessage;
+  parseMode?: "HTML";
 }
 
 export interface TelegramAnswerCallbackQueryOptions {
@@ -1380,7 +1390,25 @@ async function callTelegramWithRetry<TResponse>(
       isTelegramApiMethodRetrySafe(method));
   const maxAttempts = Math.max(1, options?.maxAttempts ?? 3);
   const retryBaseDelayMs = options?.retryBaseDelayMs ?? 500;
-  const waitBeforeRetry = async (ms: number): Promise<void> => {
+  const waitBeforeRetry = async (
+    error: unknown,
+    attempt: number,
+  ): Promise<void> => {
+    const ms = getTelegramRetryDelayMs(error, attempt, retryBaseDelayMs);
+    if (
+      !options?.signal?.aborted &&
+      error instanceof TelegramApiHttpError &&
+      error.status === 429
+    ) {
+      options?.onRetryWait?.({
+        method,
+        delayMs: ms,
+        attempt,
+        ...(error.retryAfterSeconds !== undefined
+          ? { retryAfterSeconds: error.retryAfterSeconds }
+          : {}),
+      });
+    }
     if (options?.sleep) await options.sleep(ms);
     else await sleepTelegramRetry(ms, options?.signal);
     throwIfTelegramApiCallAborted(options?.signal);
@@ -1406,9 +1434,7 @@ async function callTelegramWithRetry<TResponse>(
       if (!retrySafe) {
         if (error instanceof TelegramApiHttpError && error.status === 429) {
           if (attempt >= maxAttempts - 1) throw error;
-          await waitBeforeRetry(
-            getTelegramRetryDelayMs(error, attempt, retryBaseDelayMs),
-          );
+          await waitBeforeRetry(error, attempt);
           continue;
         }
         if (
@@ -1423,9 +1449,7 @@ async function callTelegramWithRetry<TResponse>(
         throw error;
       }
       if (attempt >= maxAttempts - 1 || !retryable) throw error;
-      await waitBeforeRetry(
-        getTelegramRetryDelayMs(error, attempt, retryBaseDelayMs),
-      );
+      await waitBeforeRetry(error, attempt);
     }
   }
 }
@@ -2095,6 +2119,7 @@ export function createTelegramBridgeApiRuntime(
         ...(content.richMessage
           ? { rich_message: content.richMessage }
           : { text: content.text }),
+        ...(content.parseMode ? { parse_mode: content.parseMode } : {}),
       });
     },
     prepareTempDir: () =>
@@ -2117,6 +2142,7 @@ export function createTelegramApiClient(
   options: TelegramAnswerCallbackQueryOptions & { now?: () => number } = {},
 ): TelegramApiClient {
   const now = options.now ?? Date.now;
+  const recordRuntimeEvent = options.recordRuntimeEvent;
   const draftRetryNotBeforeByTarget = new Map<string, number>();
   return {
     call: async <TResponse>(
@@ -2140,9 +2166,31 @@ export function createTelegramApiClient(
       }
       try {
         // A draft is a replaceable snapshot, not a body to replay after backoff.
-        return await callTelegram<TResponse>(
-          token, method, body, isDraft ? { ...options, maxAttempts: 1 } : options,
-        );
+        const retryWaitOptions: TelegramApiCallOptions = recordRuntimeEvent
+          ? {
+              onRetryWait: (wait) => {
+                recordRuntimeEvent(
+                  "api",
+                  new Error(
+                    `Telegram API rate limit: waiting ${wait.delayMs} ms before retrying ${wait.method}`,
+                  ),
+                  {
+                    phase: "retry-wait",
+                    method: wait.method,
+                    waitMs: wait.delayMs,
+                    attempt: wait.attempt,
+                    ...(wait.retryAfterSeconds !== undefined
+                      ? { retryAfterSeconds: wait.retryAfterSeconds }
+                      : {}),
+                  },
+                );
+              },
+            }
+          : {};
+        return await callTelegram<TResponse>(token, method, body, {
+          ...(isDraft ? { ...options, maxAttempts: 1 } : options),
+          ...retryWaitOptions,
+        });
       } catch (error) {
         if (draftKey && isRetryableTelegramApiError(error)) {
           draftRetryNotBeforeByTarget.set(draftKey, Math.max(

package/node_modules/@llblab/pi-telegram/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.45.5",
+  "version": "0.45.6",
   "private": false,
   "publishConfig": {
     "access": "public"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-kit",
-  "version": "0.10.5",
+  "version": "0.10.6",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -45,7 +45,7 @@
     "@llblab/pi-codex-usage": "0.9.4",
     "@llblab/pi-grow-loop": "0.8.1",
     "@llblab/pi-state-flow": "0.9.6",
-    "@llblab/pi-telegram": "0.45.5",
+    "@llblab/pi-telegram": "0.45.6",
     "@llblab/skills": "1.15.0"
   },
   "bundledDependencies": [