@llblab/pi-kit 0.7.0 → 0.8.0

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

@@ -13,6 +13,10 @@ import type {
   TelegramBusAgentMessage,
   TelegramBusAgentTargetSelector,
 } from "./bus.ts";
+import {
+  isTelegramChannelPostValidationError,
+  TelegramChannelPostValidationError,
+} from "./channel-posts.ts";
 import type { ExtensionAPI } from "./pi.ts";
 import {
   TELEGRAM_ATTACH_PROMPT_GUIDELINES,
@@ -104,6 +108,12 @@ export interface TelegramOutboundMessageToolRegistrationDeps extends TelegramOut
     markdown: string,
     options: { operationId: string; replyMarkup?: unknown },
   ) => Promise<number | undefined>;
+  sendChannelMediaMessage?: (
+    channel: number | string,
+    mediaPath: string,
+    markdown: string,
+    options: { operationId: string; replyMarkup?: unknown },
+  ) => Promise<number | undefined>;
 }
 
 export interface TelegramQueuedOutboundAttachmentView {
@@ -517,11 +527,18 @@ export function registerTelegramOutboundMessageTool(
     name: "telegram_message",
     label: "Telegram Message",
     description:
-      "Send Markdown text directly to the paired/default Telegram chat, an exact channel chat_id, or an explicit live target. Channel posting requires Telegram-granted bot permission. Hidden telegram_button comments become inline prompt buttons.",
+      "Send Markdown text directly to the paired/default Telegram chat, an exact channel chat_id, or an explicit live target. Channel delivery supports one optional local photo or video upload with the text as its caption. Channel posting requires Telegram-granted bot permission. Hidden telegram_button comments become inline prompt buttons.",
     promptSnippet: TELEGRAM_MESSAGE_PROMPT_SNIPPET,
     promptGuidelines: [...TELEGRAM_MESSAGE_PROMPT_GUIDELINES],
     parameters: Type.Object({
       text: Type.String({ description: "Message text to send" }),
+      media: Type.Optional(
+        Type.String({
+          minLength: 1,
+          description:
+            "Local single-file channel upload: .jpg/.jpeg/.png/.webp photo or .mp4 video; the text becomes its caption (max 1024 characters). Albums and other media types are rejected.",
+        }),
+      ),
       chat_id: Type.Optional(
         Type.Union([
           Type.Number(),
@@ -547,6 +564,7 @@ export function registerTelegramOutboundMessageTool(
       try {
         return await sendTelegramOutboundMessage({
           text: params.text,
+          media: params.media,
           operationId: toolCallId,
           channel: params.channel,
           chatId: params.chat_id,
@@ -561,9 +579,12 @@ export function registerTelegramOutboundMessageTool(
           planMessage: deps.planMessage,
           sendMarkdownMessage: deps.sendMarkdownMessage,
           sendChannelMarkdownMessage: deps.sendChannelMarkdownMessage,
+          sendChannelMediaMessage: deps.sendChannelMediaMessage,
         });
       } catch (error) {
-        const reportableError = typeof params.chat_id === "string" || params.channel === true
+        const isChannelTarget = typeof params.chat_id === "string" || params.channel === true;
+        const reportableError = isChannelTarget &&
+            !isTelegramChannelPostValidationError(error)
           ? new Error("Telegram channel publication failed; inspect the retained local record before retrying.")
           : error;
         deps.recordRuntimeEvent?.("message", reportableError, { phase: "direct" });
@@ -771,6 +792,7 @@ export async function deliverTelegramGuestCachedAttachment(options: {
 
 export async function sendTelegramOutboundMessage(options: {
   text: string;
+  media?: string;
   operationId?: string;
   channel?: boolean;
   chatId?: number | string;
@@ -798,6 +820,12 @@ export async function sendTelegramOutboundMessage(options: {
     markdown: string,
     options: { operationId: string; replyMarkup?: unknown },
   ) => Promise<number | undefined>;
+  sendChannelMediaMessage?: (
+    channel: number | string,
+    mediaPath: string,
+    markdown: string,
+    options: { operationId: string; replyMarkup?: unknown },
+  ) => Promise<number | undefined>;
 }): Promise<{
   content: Array<{ type: "text"; text: string }>;
   details: { chatId: number | string; messageId?: number };
@@ -811,10 +839,23 @@ export async function sendTelegramOutboundMessage(options: {
         options.target !== undefined || options.agentThread !== undefined) {
       throw new Error("Telegram channel delivery requires one exact @username or negative numeric channel ID without a thread target.");
     }
+    const plan = options.planMessage(options.text);
+    if (options.media !== undefined) {
+      if (!options.sendChannelMediaMessage || !options.operationId) {
+        throw new TelegramChannelPostValidationError(
+          "Telegram channel media delivery requires direct leader transport ownership and operation identity.",
+        );
+      }
+      const messageId = await options.sendChannelMediaMessage(
+        options.chatId, options.media, plan.markdown,
+        { operationId: options.operationId, replyMarkup: plan.replyMarkup });
+      return { content: [{ type: "text",
+        text: formatTelegramOutboundMessageToolResultText(options.chatId) }],
+      details: { chatId: options.chatId, messageId } };
+    }
     if (!options.sendChannelMarkdownMessage || !options.operationId) {
       throw new Error("Telegram channel delivery requires direct leader transport ownership and operation identity.");
     }
-    const plan = options.planMessage(options.text);
     const messageId = await options.sendChannelMarkdownMessage(
       options.chatId, plan.markdown, { operationId: options.operationId,
         replyMarkup: plan.replyMarkup });
@@ -822,6 +863,11 @@ export async function sendTelegramOutboundMessage(options: {
       text: formatTelegramOutboundMessageToolResultText(options.chatId) }],
     details: { chatId: options.chatId, messageId } };
   }
+  if (options.media !== undefined) {
+    throw new TelegramChannelPostValidationError(
+      "telegram_message media uploads require channel delivery with an exact @username or negative numeric channel ID and channel: true.",
+    );
+  }
   const requestedAgentSelector: TelegramBusAgentTargetSelector | undefined =
     options.agentThread !== undefined
       ? typeof options.agentThread === "number"

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

@@ -70,6 +70,7 @@ export interface TelegramPreviewActiveTurn {
   target?: TelegramTarget;
   voiceReplyPreferred?: boolean;
   voiceReplyRequired?: boolean;
+  guestQueryId?: string;
 }
 
 export interface TelegramAssistantMessagePreviewStartDeps<TMessage> {
@@ -408,6 +409,17 @@ export function createTelegramAssistantMessagePreviewHooks<TMessage>(
   };
 }
 
+/**
+ * Returns true when the active turn is a Telegram Guest Mode query. A guest
+ * query allows exactly one answer within a limited Telegram response window,
+ * so it must never emit streaming draft previews.
+ */
+export function shouldSuppressPreviewForGuestTurn(
+  turn: { guestQueryId?: string } | null | undefined,
+): boolean {
+  return !!turn?.guestQueryId;
+}
+
 export async function handleTelegramAssistantMessagePreviewStart<TMessage>(
   message: TMessage,
   deps: TelegramAssistantMessagePreviewStartDeps<TMessage>,
@@ -422,6 +434,10 @@ export async function handleTelegramAssistantMessagePreviewStart<TMessage>(
     deps.setState(undefined);
     return;
   }
+  if (shouldSuppressPreviewForGuestTurn(turn)) {
+    deps.setState(undefined);
+    return;
+  }
   const state = deps.getState();
   sealTelegramPreviewState(state);
   const next = deps.createPreviewState();
@@ -443,6 +459,7 @@ export async function handleTelegramAssistantMessagePreviewUpdate<TMessage>(
     return;
   }
   if (shouldSuppressPreviewForVoice(turn)) return;
+  if (shouldSuppressPreviewForGuestTurn(turn)) return;
   let state = deps.getState();
   if (!state) {
     state = deps.createPreviewState();

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

@@ -32,6 +32,7 @@ export const TELEGRAM_MESSAGE_PROMPT_SNIPPET =
 export const TELEGRAM_MESSAGE_PROMPT_GUIDELINES = [
   "Use telegram_message only when the user explicitly asks to send a message to Telegram from the local/TUI side, or names a concrete Telegram delivery target.",
   "For an explicitly requested channel post, pass its exact numeric id or public @username as chat_id; no local channel registry is required, and Telegram remains the authority on the bot's posting permission.",
+  "For an explicitly requested channel media post, pass one local .jpg/.jpeg/.png/.webp photo or .mp4 video as media; the text becomes its caption (max 1024 characters), and albums or other media types are rejected.",
   "For a live Pi thread target, provide thread as its case-insensitive name or numeric id; the bridge sends visibly and admits one attributed turn to that live instance. Unknown, ambiguous, same, or offline targets fail before sending.",
   "Add buttons by embedding the same top-level telegram_button HTML comments used in normal Telegram replies; Telegram does not support standalone buttons.",
   "During an active Telegram turn, omit telegram_message for the current target and answer normally; use thread only when the user requests delivery to a different live Pi thread.",

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

@@ -110,6 +110,7 @@ export interface TelegramQueueItemBase {
   transportStamp?: TelegramTransportStamp;
   replyToMessageId: number;
   guestQueryId?: string;
+  guestInlineMessageId?: string;
   queueOrder: number;
   queueLane: TelegramQueueLane;
   laneOrder: number;
@@ -152,6 +153,7 @@ export interface TelegramQueueHandoffBase {
   transportStamp?: TelegramTransportStamp;
   replyToMessageId: number;
   guestQueryId?: string;
+  guestInlineMessageId?: string;
   queueOrder: number;
   queueLane: TelegramQueueLane;
   laneOrder: number;
@@ -612,6 +614,9 @@ export function createTelegramQueueHandoffPayload<TContext>(
       ...(item.transportStamp ? { transportStamp: item.transportStamp } : {}),
       replyToMessageId: item.replyToMessageId,
       ...(item.guestQueryId ? { guestQueryId: item.guestQueryId } : {}),
+      ...(item.guestInlineMessageId
+        ? { guestInlineMessageId: item.guestInlineMessageId }
+        : {}),
       queueOrder: item.queueOrder,
       queueLane: item.queueLane,
       laneOrder: item.laneOrder,
@@ -626,6 +631,9 @@ export function createTelegramQueueHandoffPayload<TContext>(
     ...(item.transportStamp ? { transportStamp: item.transportStamp } : {}),
     replyToMessageId: item.replyToMessageId,
     ...(item.guestQueryId ? { guestQueryId: item.guestQueryId } : {}),
+    ...(item.guestInlineMessageId
+      ? { guestInlineMessageId: item.guestInlineMessageId }
+      : {}),
     queueOrder: item.queueOrder,
     queueLane: item.queueLane,
     laneOrder: item.laneOrder,
@@ -1544,6 +1552,8 @@ export interface TelegramAgentEndRuntimeDeps<
     options?: { parseMode?: string },
   ) => 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>;
   sendGuestAttachment?: (
     turn: TTurn,
     attachment: QueuedAttachment,
@@ -1622,6 +1632,7 @@ export interface TelegramAgentEndHookRuntimeDeps<
   >["sendRichAttachmentReply"];
   answerGuestQuery?: TelegramAgentEndRuntimeDeps<TTurn>["answerGuestQuery"];
   sendGuestReply?: TelegramAgentEndRuntimeDeps<TTurn>["sendGuestReply"];
+  editGuestReply?: TelegramAgentEndRuntimeDeps<TTurn>["editGuestReply"];
   sendGuestAttachment?: TelegramAgentEndRuntimeDeps<TTurn>["sendGuestAttachment"];
   sendGuestVoiceReply?: TelegramAgentEndRuntimeDeps<TTurn>["sendGuestVoiceReply"];
   planOutboundReply?: TelegramAgentEndRuntimeDeps<
@@ -1762,6 +1773,7 @@ export function createTelegramAgentEndHook<
         sendRichAttachmentReply: deps.sendRichAttachmentReply,
         answerGuestQuery: deps.answerGuestQuery,
         sendGuestReply: deps.sendGuestReply,
+        editGuestReply: deps.editGuestReply,
         sendGuestAttachment: deps.sendGuestAttachment,
         sendGuestVoiceReply: deps.sendGuestVoiceReply,
         planOutboundReply: deps.planOutboundReply,
@@ -1854,11 +1866,47 @@ export async function handleTelegramAgentEndRuntime<
     return;
   }
   if (turn.guestQueryId) {
+    if (turn.guestInlineMessageId && deps.editGuestReply) {
+      const experimentText = assistant.errorMessage
+        ? "Telegram bridge: Pi failed while processing the request."
+        : finalText;
+      if (experimentText) {
+        try {
+          await deps.editGuestReply(turn.guestInlineMessageId, experimentText);
+          deps.recordRuntimeEvent?.(
+            "guest",
+            new Error("Guest ACK experiment edited the guest answer"),
+            { phase: "guest-ack-edited", guestQueryId: turn.guestQueryId },
+          );
+        } catch (error) {
+          deps.recordRuntimeEvent?.("delivery", error, {
+            phase: "guest-ack-edit",
+            guestQueryId: turn.guestQueryId,
+          });
+        }
+      } else {
+        deps.recordRuntimeEvent?.(
+          "delivery",
+          new Error("Guest ACK experiment turn produced no editable text"),
+          { phase: "guest-ack-edit-empty", guestQueryId: turn.guestQueryId },
+        );
+      }
+      if (!isDeliveryActive()) return;
+      if (endPlan.shouldDispatchNext) deps.dispatchNextQueuedTelegramTurn();
+      return;
+    }
     if (assistant.errorMessage) {
-      await deps.answerGuestQuery?.(
-        turn.guestQueryId,
-        "Telegram bridge: Pi failed while processing the request.",
-      );
+      try {
+        await deps.answerGuestQuery?.(
+          turn.guestQueryId,
+          "Telegram bridge: Pi failed while processing the request.",
+        );
+      } catch (error) {
+        deps.recordRuntimeEvent?.("delivery", error, {
+          phase: "guest-error-reply",
+          guestQueryId: turn.guestQueryId,
+        });
+      }
       if (endPlan.shouldDispatchNext) deps.dispatchNextQueuedTelegramTurn();
       return;
     }
@@ -1894,10 +1942,20 @@ export async function handleTelegramAgentEndRuntime<
         });
       }
     } else if (finalText) {
-      if (deps.sendGuestReply) {
-        await deps.sendGuestReply(turn.guestQueryId, finalText);
-      } else {
-        await deps.answerGuestQuery?.(turn.guestQueryId, finalText);
+      try {
+        if (deps.sendGuestReply) {
+          await deps.sendGuestReply(turn.guestQueryId, finalText);
+        } else {
+          await deps.answerGuestQuery?.(turn.guestQueryId, finalText);
+        }
+      } catch (error) {
+        // Guest queries expire after Telegram's response timeout, so a slow
+        // turn can fail the only delivery attempt. Record and continue the
+        // agent-end lifecycle instead of rejecting the extension hook.
+        deps.recordRuntimeEvent?.("delivery", error, {
+          phase: "guest-reply",
+          guestQueryId: turn.guestQueryId,
+        });
       }
     }
     if (!isDeliveryActive()) return;

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

@@ -551,9 +551,12 @@ function applyInlineMarkdownStyles(text: string): string {
   result = renderDelimitedInlineStyle(result, "*", (content) => {
     return `<i>${content}</i>`;
   });
-  return renderDelimitedInlineStyle(result, "_", (content) => {
+  result = renderDelimitedInlineStyle(result, "_", (content) => {
     return `<i>${content}</i>`;
   });
+  return renderDelimitedInlineStyle(result, "||", (content) => {
+    return `<tg-spoiler>${content}</tg-spoiler>`;
+  });
 }
 
 function restoreInlineMarkdownTokens(

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

@@ -898,3 +898,22 @@ 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.
+ */
+export function createGuestMarkdownReplyEditor(deps: {
+  editGuestInlineMessage: (
+    inlineMessageId: string,
+    content: { richMessage?: TelegramInputRichMessage; text?: string },
+  ) => Promise<void>;
+}) {
+  return async (inlineMessageId: string, markdown: string) => {
+    const [richMarkdown = markdown] = splitTelegramNativeMarkdown(markdown);
+    await deps.editGuestInlineMessage(inlineMessageId, {
+      richMessage: { markdown: richMarkdown },
+    });
+  };
+}

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

@@ -659,6 +659,12 @@ export interface TelegramInboundRouteRuntimeDeps<
   ) => Promise<number | undefined>;
   deleteMessage?: (chatId: number, messageId: number) => Promise<void>;
   answerGuestQuery: (guestQueryId: string, text?: string) => Promise<void>;
+  /** Answers the guest query immediately and returns its inline message id. */
+  answerGuestQueryForInlineMessage?: (
+    guestQueryId: string,
+    text: string,
+    options?: { parseMode?: "HTML" },
+  ) => Promise<string | undefined>;
   sendTextReply: (
     chatId: number,
     replyToMessageId: number,
@@ -2655,6 +2661,9 @@ export function createTelegramInboundRouteRuntime<
     await deps.threadStore.load();
     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>";
   const handleAuthorizedTelegramGuestMessage = async (
     guestMessage: Updates.TelegramGuestMessage & { from: TelegramUser },
     ctx: TContext,
@@ -2662,6 +2671,31 @@ export function createTelegramInboundRouteRuntime<
     const assertExecutionCurrent =
       Updates.createTelegramUpdateExecutionFenceGuard(guestMessage);
     assertExecutionCurrent();
+    let guestInlineMessageId: string | undefined;
+    if (deps.answerGuestQueryForInlineMessage) {
+      try {
+        guestInlineMessageId = await deps.answerGuestQueryForInlineMessage(
+          guestMessage.guest_query_id,
+          TELEGRAM_GUEST_ACK_HTML,
+          { parseMode: "HTML" },
+        );
+        deps.recordRuntimeEvent?.(
+          "guest",
+          new Error("Guest ACK experiment answered the guest query"),
+          {
+            phase: "guest-ack-sent",
+            guestQueryId: guestMessage.guest_query_id,
+            hasInlineMessageId: !!guestInlineMessageId,
+          },
+        );
+      } catch (error) {
+        deps.recordRuntimeEvent?.("guest", error, {
+          phase: "guest-ack-failed",
+          guestQueryId: guestMessage.guest_query_id,
+        });
+      }
+      assertExecutionCurrent();
+    }
     const text = guestMessage.text ?? "";
     const gm = guestMessage as unknown as Record<string, unknown>;
     // Build telegram prefix with guest context
@@ -2752,6 +2786,10 @@ export function createTelegramInboundRouteRuntime<
       promptFiles: processed.promptFiles,
       handlerOutputs: processed.handlerOutputs,
       sourceContext,
+      // Guest Mode allows exactly one reply within Telegram's limited response
+      // window; the note travels with the turn text so the agent sees it at
+      // execution time without a guest-specific system prompt variant.
+      guestTurn: true,
     });
     const order = deps.bridgeRuntime.queue.allocateItemOrder();
     const content: Queue.TelegramPromptContent[] = [
@@ -2778,6 +2816,7 @@ export function createTelegramInboundRouteRuntime<
       chatId: 0,
       replyToMessageId: 0,
       guestQueryId: guestMessage.guest_query_id,
+      ...(guestInlineMessageId ? { guestInlineMessageId } : {}),
       sourceMessageIds: [],
       queueOrder: order,
       queueLane: "default",

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

@@ -42,6 +42,10 @@ export interface TelegramSetupDeps {
     result?: TelegramSetupUser;
     description?: string;
   }>;
+  /** Resolve a submitted literal token or `$NAME`/`${NAME}` reference. */
+  resolveBotToken?: (value: string) => string | undefined;
+  /** Redacted diagnostic for an unresolved or malformed token reference. */
+  describeBotToken?: (value: string) => string | undefined;
   persistConfig: (config: TelegramSetupConfig) => Promise<void>;
   notify: (message: string, level: "info" | "error") => void;
   startPolling: () => unknown | Promise<unknown>;
@@ -70,6 +74,8 @@ export interface TelegramSetupPromptRuntimeDeps<
   setConfig: (config: TelegramSetupConfig) => void;
   setupGuard: TelegramSetupGuard;
   getMe: TelegramSetupDeps["getMe"];
+  resolveBotToken?: TelegramSetupDeps["resolveBotToken"];
+  describeBotToken?: TelegramSetupDeps["describeBotToken"];
   persistConfig: (config: TelegramSetupConfig) => Promise<void>;
   startPolling: (ctx: TContext) => unknown | Promise<unknown>;
   updateStatus: (ctx: TContext) => void;
@@ -88,6 +94,25 @@ const TELEGRAM_BOT_TOKEN_ENV_VARS = [
   "TELEGRAM_KEY",
 ] as const;
 
+/**
+ * Default submitted-token handling for structural callers that inject no
+ * reference port: plain literals pass through, while `$`-prefixed values fail
+ * closed instead of being sent to the Bot API as a literal token.
+ */
+function resolveSubmittedTelegramBotToken(value: string): string | undefined {
+  const trimmed = value.trim();
+  if (!trimmed || trimmed.startsWith("$")) return undefined;
+  return trimmed;
+}
+
+function describeSubmittedTelegramBotToken(
+  value: string,
+): string | undefined {
+  return value.trim().startsWith("$")
+    ? "Telegram bot token environment reference is unavailable in this setup environment."
+    : undefined;
+}
+
 function isTelegramPollingStartResult(
   value: unknown,
 ): value is TelegramPollingStartResult {
@@ -105,8 +130,8 @@ export function getTelegramBotTokenInputDefault(
   const trimmedConfigToken = configToken?.trim();
   if (trimmedConfigToken) return trimmedConfigToken;
   for (const key of TELEGRAM_BOT_TOKEN_ENV_VARS) {
-    const value = env[key]?.trim();
-    if (value) return value;
+    // Persist the originating alias rather than copying the resolved secret.
+    if (env[key]?.trim()) return `$${key}`;
   }
   return TELEGRAM_BOT_TOKEN_INPUT_PLACEHOLDER;
 }
@@ -135,13 +160,26 @@ export async function runTelegramSetup(
       ? await deps.promptEditor("Telegram bot token", tokenPrompt.value)
       : await deps.promptInput("Telegram bot token", tokenPrompt.value);
   if (!token) return { status: "cancelled" };
+  const submittedToken = token.trim();
+  const resolveBotToken =
+    deps.resolveBotToken ?? resolveSubmittedTelegramBotToken;
+  const describeBotToken =
+    deps.describeBotToken ?? describeSubmittedTelegramBotToken;
+  const resolvedToken = resolveBotToken(submittedToken);
   const nextConfig: TelegramSetupConfig = {
     ...deps.config,
-    botToken: token.trim(),
+    botToken: submittedToken,
   };
+  if (!resolvedToken) {
+    deps.notify(
+      describeBotToken(submittedToken) ?? "Invalid Telegram bot token",
+      "error",
+    );
+    return { status: "validation-failed" };
+  }
   let data: Awaited<ReturnType<TelegramSetupDeps["getMe"]>>;
   try {
-    data = await deps.getMe(nextConfig.botToken ?? "");
+    data = await deps.getMe(resolvedToken);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     deps.notify(`Telegram API check failed: ${message}`, "error");
@@ -195,6 +233,8 @@ export function createTelegramSetupPromptRuntime<
         promptInput: (label, value) => ctx.ui.input(label, value),
         promptEditor: (label, value) => ctx.ui.editor(label, value),
         getMe: deps.getMe,
+        resolveBotToken: deps.resolveBotToken,
+        describeBotToken: deps.describeBotToken,
         persistConfig: async (config) => {
           const previousConfig = deps.getConfig();
           deps.setConfig(config);

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

@@ -245,6 +245,8 @@ export interface TelegramBridgeInboundWorkerState {
 export interface TelegramBridgeStatusLineState {
   hasBotToken?: boolean;
   botUsername?: string;
+  /** Redacted named-variable diagnostic when the stored token reference cannot resolve. */
+  botTokenDiagnostic?: string;
   activeProfileName?: string;
   diagnosticPaths?: { state: string; logs: string };
   allowedUserId?: number;
@@ -323,10 +325,40 @@ export interface TelegramStatusRuntimeDeps<
 
 export interface TelegramBridgeStatusConfig {
   botToken?: string;
+  /** Caller-resolved token availability; falls back to raw presence. */
+  botHasToken?: boolean;
+  /** Caller-supplied redacted diagnostic for an unresolved token reference. */
+  botTokenDiagnostic?: string;
   botUsername?: string;
   allowedUserId?: number;
 }
 
+/** Narrow config-store view used to project resolved bot-token availability. */
+export interface TelegramBridgeStatusConfigSource {
+  get: () => TelegramBridgeStatusConfig;
+  hasBotToken?: () => boolean;
+  getBotTokenDiagnostic?: () => string | undefined;
+}
+
+/**
+ * Project a config store into the status view without moving token-reference
+ * resolution into this structural leaf domain.
+ */
+export function createTelegramBridgeStatusConfigGetter(
+  source: TelegramBridgeStatusConfigSource,
+): () => TelegramBridgeStatusConfig {
+  return () => {
+    const config = source.get();
+    return {
+      ...config,
+      ...(source.hasBotToken ? { botHasToken: source.hasBotToken() } : {}),
+      ...(source.getBotTokenDiagnostic
+        ? { botTokenDiagnostic: source.getBotTokenDiagnostic() }
+        : {}),
+    };
+  };
+}
+
 export interface TelegramBridgeStatusRuntimeDeps<
   TQueueItem extends { queueLane: TelegramStatusQueueLane },
 > {
@@ -681,7 +713,7 @@ export function createTelegramBridgeStatusRuntime<
       const compactionInProgress = deps.isCompactionInProgress();
       const localBus = deps.getLocalBus?.();
       return {
-        hasBotToken: !!config.botToken,
+        hasBotToken: config.botHasToken ?? Boolean(config.botToken),
         pollingActive: deps.isPollingActive(),
         paired: !!config.allowedUserId,
         busRole: deps.getBusRole?.(),
@@ -715,8 +747,9 @@ export function createTelegramBridgeStatusRuntime<
         ? (deps.getActiveProfileName() ?? TELEGRAM_STATUS_DEFAULT_PROFILE_NAME)
         : undefined;
       return {
-        hasBotToken: Boolean(config.botToken),
+        hasBotToken: config.botHasToken ?? Boolean(config.botToken),
         botUsername: config.botUsername,
+        botTokenDiagnostic: config.botTokenDiagnostic,
         activeProfileName,
         diagnosticPaths: deps.getDiagnosticPaths?.(activeProfileName),
         allowedUserId: config.allowedUserId,
@@ -925,10 +958,14 @@ export function buildTelegramStatusBarText(
 }
 
 function formatTelegramBridgeBotStatus(
-  state: Pick<TelegramBridgeStatusLineState, "hasBotToken" | "botUsername">,
+  state: Pick<
+    TelegramBridgeStatusLineState,
+    "hasBotToken" | "botUsername" | "botTokenDiagnostic"
+  >,
 ): string {
   if (state.botUsername) return `@${state.botUsername}`;
-  return state.hasBotToken ? "unknown" : "not configured";
+  if (state.hasBotToken) return "unknown";
+  return state.botTokenDiagnostic ?? "not configured";
 }
 
 function formatTelegramStatusTarget(