@llblab/pi-kit 0.7.0 → 0.8.0

package/node_modules/@llblab/pi-telegram/lib/channel-posts.ts

@@ -4,10 +4,11 @@
  * Owns publication intent, outcome-unknown fencing, confirmed post identity, and bounded local listing
  */
 
-import { chmodSync, closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync,
+import { chmodSync, closeSync, constants, createReadStream, fstatSync, lstatSync, mkdirSync, openSync,
   readFileSync, unlinkSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
-import { randomUUID } from "node:crypto";
+import { lstat } from "node:fs/promises";
+import { basename, dirname } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
 
 import { Type } from "@sinclair/typebox";
 
@@ -21,6 +22,125 @@ const MAX_ID_LENGTH = 256;
 const MAX_MARKDOWN_LENGTH = 100_000;
 const MAX_CHANNEL_TITLE_LENGTH = 255;
 
+export type TelegramChannelPostMediaKind = "photo" | "video";
+
+export interface TelegramChannelPostMediaIntent {
+  kind: TelegramChannelPostMediaKind;
+  fileName: string;
+  sizeBytes: number;
+  sha256: string;
+}
+
+export const TELEGRAM_CHANNEL_POST_MEDIA_MAX_BYTES: Record<TelegramChannelPostMediaKind, number> = {
+  photo: 10 * 1024 * 1024,
+  video: 50 * 1024 * 1024,
+};
+export const TELEGRAM_CHANNEL_POST_CAPTION_MAX_LENGTH = 1024;
+export const TELEGRAM_CHANNEL_POST_MEDIA_FILE_NAME_MAX_LENGTH = 255;
+
+/** Safe, content-free local validation failure for channel media publication intent. */
+export class TelegramChannelPostValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "TelegramChannelPostValidationError";
+  }
+}
+
+export function isTelegramChannelPostValidationError(
+  error: unknown,
+): error is TelegramChannelPostValidationError {
+  return error instanceof TelegramChannelPostValidationError;
+}
+
+const TELEGRAM_CHANNEL_POST_PHOTO_EXTENSIONS = new Set([".jpg", ".jpeg", ".png", ".webp"]);
+const TELEGRAM_CHANNEL_POST_VIDEO_EXTENSIONS = new Set([".mp4"]);
+
+export function resolveTelegramChannelPostMediaKind(
+  path: string,
+): TelegramChannelPostMediaKind | undefined {
+  if (typeof path !== "string" || path.length === 0) return undefined;
+  const name = basename(path).toLowerCase();
+  const dot = name.lastIndexOf(".");
+  if (dot <= 0) return undefined;
+  const extension = name.slice(dot);
+  if (TELEGRAM_CHANNEL_POST_PHOTO_EXTENSIONS.has(extension)) return "photo";
+  if (TELEGRAM_CHANNEL_POST_VIDEO_EXTENSIONS.has(extension)) return "video";
+  return undefined;
+}
+
+export function assertTelegramChannelPostMediaSize(
+  kind: TelegramChannelPostMediaKind,
+  sizeBytes: number,
+): void {
+  if (!Number.isSafeInteger(sizeBytes) || sizeBytes <= 0) {
+    throw new TelegramChannelPostValidationError("Channel media file is empty or unreadable.");
+  }
+  const limit = TELEGRAM_CHANNEL_POST_MEDIA_MAX_BYTES[kind];
+  if (sizeBytes > limit) {
+    throw new TelegramChannelPostValidationError(
+      `Channel ${kind} exceeds the Telegram ${kind} upload limit of ${limit} bytes.`,
+    );
+  }
+}
+
+async function hashTelegramChannelPostMedia(path: string): Promise<string> {
+  return await new Promise<string>((resolve, reject) => {
+    const hash = createHash("sha256");
+    const stream = createReadStream(path);
+    stream.on("data", (chunk: Buffer) => hash.update(chunk));
+    stream.on("error", reject);
+    stream.on("end", () => resolve(hash.digest("hex")));
+  });
+}
+
+export async function inspectTelegramChannelPostMedia(
+  path: string,
+): Promise<TelegramChannelPostMediaIntent> {
+  const kind = resolveTelegramChannelPostMediaKind(path);
+  if (!kind) {
+    throw new TelegramChannelPostValidationError(
+      "Unsupported channel media type. Supported single files: .jpg, .jpeg, .png, .webp photos and .mp4 videos; albums are not supported.",
+    );
+  }
+  let stats;
+  try {
+    stats = await lstat(path);
+  } catch {
+    throw new TelegramChannelPostValidationError(
+      "Channel media upload requires one readable regular local file.",
+    );
+  }
+  if (!stats.isFile() || stats.isSymbolicLink()) {
+    throw new TelegramChannelPostValidationError(
+      "Channel media upload requires one regular local file without symbolic links.",
+    );
+  }
+  assertTelegramChannelPostMediaSize(kind, stats.size);
+  return { kind, fileName: basename(path), sizeBytes: stats.size,
+    sha256: await hashTelegramChannelPostMedia(path) };
+}
+
+export function getTelegramChannelPostCaptionLength(caption: string): number {
+  const visible = caption
+    .replace(/<br\s*\/?>/giu, "\n")
+    .replace(/<[^>]*>/gu, "")
+    .replace(/&lt;/gu, "<")
+    .replace(/&gt;/gu, ">")
+    .replace(/&quot;/gu, "\"")
+    .replace(/&#39;/gu, "'")
+    .replace(/&amp;/gu, "&");
+  return visible.length;
+}
+
+export function assertTelegramChannelPostCaptionWithinLimit(caption: string): void {
+  if (getTelegramChannelPostCaptionLength(caption) >
+      TELEGRAM_CHANNEL_POST_CAPTION_MAX_LENGTH) {
+    throw new TelegramChannelPostValidationError(
+      `Channel media caption exceeds the Telegram limit of ${TELEGRAM_CHANNEL_POST_CAPTION_MAX_LENGTH} characters.`,
+    );
+  }
+}
+
 type ChannelPostJournalCode = "invalid" | "conflict" | "capacity" | "io";
 
 export class TelegramChannelPostJournalError extends Error {
@@ -39,6 +159,7 @@ interface TelegramChannelPostRecordBase {
   operationId: string;
   requestedChannel: TelegramChannelPostAddress;
   markdown: string;
+  media?: TelegramChannelPostMediaIntent;
   createdAtMs: number;
   updatedAtMs: number;
 }
@@ -82,8 +203,10 @@ export interface TelegramChannelPostJournalStoreOptions {
 }
 
 export interface TelegramChannelPostJournalStore {
-  prepare(input: { operationId: string; channel: TelegramChannelPostAddress; markdown: string }):
+  prepare(input: { operationId: string; channel: TelegramChannelPostAddress; markdown: string;
+    media?: TelegramChannelPostMediaIntent }):
     { prepared: boolean; record: TelegramChannelPostRecord };
+  get(operationId: string): TelegramChannelPostRecord | undefined;
   beginPublication(operationId: string): { began: boolean; record: TelegramChannelPostRecord };
   confirmPublished(input: { operationId: string; channelId: number; messageId: number;
     channelUsername?: `@${string}`; channelTitle?: string }):
@@ -104,6 +227,7 @@ export async function publishTelegramChannelPost(input: {
   operationId: string;
   channel: TelegramChannelPostAddress;
   markdown: string;
+  media?: TelegramChannelPostMediaIntent;
   observeChannel(channel: TelegramChannelPostAddress): Promise<{
     id: number; type: string; username?: string; title?: string;
   }>;
@@ -119,7 +243,8 @@ export async function publishTelegramChannelPost(input: {
         observed.title.length > MAX_CHANNEL_TITLE_LENGTH))) {
     throw new Error("Telegram channel delivery requires bounded exact getChat channel identity.");
   }
-  input.store.prepare({ operationId: input.operationId, channel: input.channel, markdown: input.markdown });
+  input.store.prepare({ operationId: input.operationId, channel: input.channel,
+    markdown: input.markdown, ...(input.media === undefined ? {} : { media: input.media }) });
   const issuance = input.store.beginPublication(input.operationId);
   if (!issuance.began) {
     if (issuance.record.state === "published") return issuance.record;
@@ -135,6 +260,16 @@ export async function publishTelegramChannelPost(input: {
     ...(observed.title ? { channelTitle: observed.title } : {}) }).record;
 }
 
+function formatTelegramChannelPostToolOutput(value: unknown): string {
+  // Pi's compact tool rows need one leading newline to separate call and result.
+  return `\n${JSON.stringify(value, null, 2)}`;
+}
+
+function formatTelegramChannelPostToolError(error: unknown): Error {
+  const message = error instanceof Error ? error.message : String(error);
+  return new Error(`\n${message.replace(/^\n+/u, "") || "Telegram channel post operation failed."}`);
+}
+
 export function registerTelegramChannelPostMutationTool(
   pi: ExtensionAPI,
   deps: { mutate(input: { action: "edit" | "delete"; operationId: string;
@@ -143,7 +278,7 @@ export function registerTelegramChannelPostMutationTool(
   pi.registerTool({
     name: "telegram_channel_post",
     label: "Edit or Delete Telegram Channel Post",
-    description: "Edit or delete one exact published post retained by telegram_channel_posts. Unknown outcomes are never replayed.",
+    description: "Edit or delete one exact published post retained by telegram_channel_posts; a media post edit replaces its caption. Unknown outcomes are never replayed.",
     parameters: Type.Object({
       action: Type.Union([Type.Literal("edit"), Type.Literal("delete")]),
       operation_id: Type.String({ minLength: 1, maxLength: MAX_ID_LENGTH }),
@@ -153,10 +288,13 @@ export function registerTelegramChannelPostMutationTool(
       try {
         const record = await deps.mutate({ action: params.action, operationId: params.operation_id,
           mutationId: toolCallId, ...(params.markdown === undefined ? {} : { markdown: params.markdown }) });
-        return { content: [{ type: "text" as const, text: JSON.stringify(record, null, 2) }],
+        return { content: [{ type: "text" as const, text: formatTelegramChannelPostToolOutput(record) }],
           details: { record } };
-      } catch {
-        throw new Error("Telegram channel post mutation failed; inspect the retained local record before retrying.");
+      } catch (error) {
+        if (isTelegramChannelPostValidationError(error)) {
+          throw formatTelegramChannelPostToolError(error);
+        }
+        throw new Error("\nTelegram channel post mutation failed; inspect the retained local record before retrying.");
       }
     },
   });
@@ -182,10 +320,10 @@ export function registerTelegramChannelPostListTool(
           channel: params.chat_id as TelegramChannelPostAddress | undefined,
           limit: params.limit,
         });
-        return { content: [{ type: "text" as const, text: JSON.stringify(records, null, 2) }],
+        return { content: [{ type: "text" as const, text: formatTelegramChannelPostToolOutput(records) }],
           details: { records } };
       } catch {
-        throw new Error("Telegram channel post listing failed without exposing retained content or storage details.");
+        throw new Error("\nTelegram channel post listing failed without exposing retained content or storage details.");
       }
     },
   });
@@ -212,9 +350,33 @@ function normalizeChannel(value: unknown): TelegramChannelPostAddress {
   throw new TelegramChannelPostJournalError("invalid", "Telegram channel post requires an exact negative channel ID or public @username.");
 }
 
+function validateTelegramChannelPostMedia(value: unknown): TelegramChannelPostMediaIntent {
+  if (!isRecord(value) || !hasOnlyKeys(value, ["kind", "fileName", "sizeBytes", "sha256"]) ||
+      (value.kind !== "photo" && value.kind !== "video") ||
+      typeof value.fileName !== "string" || value.fileName.length === 0 ||
+      value.fileName.length > TELEGRAM_CHANNEL_POST_MEDIA_FILE_NAME_MAX_LENGTH ||
+      !Number.isSafeInteger(value.sizeBytes) || (value.sizeBytes as number) <= 0 ||
+      (value.sizeBytes as number) > TELEGRAM_CHANNEL_POST_MEDIA_MAX_BYTES[value.kind] ||
+      typeof value.sha256 !== "string" || !/^[a-f0-9]{64}$/u.test(value.sha256)) {
+    throw new TelegramChannelPostJournalError("invalid",
+      "Telegram channel post journal contains an invalid media intent.");
+  }
+  return { kind: value.kind, fileName: value.fileName,
+    sizeBytes: value.sizeBytes as number, sha256: value.sha256 };
+}
+
+function sameTelegramChannelPostMedia(
+  left: TelegramChannelPostMediaIntent | undefined,
+  right: TelegramChannelPostMediaIntent | undefined,
+): boolean {
+  if (left === undefined || right === undefined) return left === right;
+  return left.kind === right.kind && left.fileName === right.fileName &&
+    left.sizeBytes === right.sizeBytes && left.sha256 === right.sha256;
+}
+
 function validateRecord(value: unknown): TelegramChannelPostRecord {
   if (!isRecord(value) || !hasOnlyKeys(value, ["operationId", "requestedChannel", "markdown",
-    "createdAtMs", "updatedAtMs", "state", "issuedAtMs", "publishedAtMs", "channelId",
+    "media", "createdAtMs", "updatedAtMs", "state", "issuedAtMs", "publishedAtMs", "channelId",
     "messageId", "channelUsername", "mutationId", "attemptedMarkdown",
     "mutationIssuedAtMs", "deletedAtMs", "lastMutationId", "channelTitle"]) || typeof value.operationId !== "string" ||
     value.operationId.length === 0 || value.operationId.length > MAX_ID_LENGTH ||
@@ -225,7 +387,8 @@ function validateRecord(value: unknown): TelegramChannelPostRecord {
   }
   const base: TelegramChannelPostRecordBase = { operationId: value.operationId,
     requestedChannel: normalizeChannel(value.requestedChannel), markdown: value.markdown,
-    createdAtMs: value.createdAtMs, updatedAtMs: value.updatedAtMs };
+    createdAtMs: value.createdAtMs, updatedAtMs: value.updatedAtMs,
+    ...(value.media === undefined ? {} : { media: validateTelegramChannelPostMedia(value.media) }) };
   if (value.state === "prepared" && value.issuedAtMs === undefined && value.publishedAtMs === undefined &&
       value.channelId === undefined && value.messageId === undefined && value.channelUsername === undefined &&
       value.mutationId === undefined && value.attemptedMarkdown === undefined &&
@@ -379,6 +542,8 @@ export function createTelegramChannelPostJournalStore(
     prepare(input) {
       const operationId = input.operationId;
       const channel = normalizeChannel(input.channel);
+      const media = input.media === undefined ? undefined
+        : validateTelegramChannelPostMedia(input.media);
       if (typeof operationId !== "string" || operationId.length === 0 || operationId.length > MAX_ID_LENGTH ||
           typeof input.markdown !== "string" || input.markdown.length === 0 ||
           input.markdown.length > MAX_MARKDOWN_LENGTH) {
@@ -387,7 +552,8 @@ export function createTelegramChannelPostJournalStore(
       return mutate(file => {
         const existing = file.records.find(record => record.operationId === operationId);
         if (existing) {
-          if (existing.requestedChannel !== channel || existing.markdown !== input.markdown) {
+          if (existing.requestedChannel !== channel || existing.markdown !== input.markdown ||
+              !sameTelegramChannelPostMedia(existing.media, media)) {
             throw new TelegramChannelPostJournalError("conflict", "Telegram channel post operation conflicts with retained intent.");
           }
           return { prepared: false, record: structuredClone(existing) };
@@ -395,7 +561,8 @@ export function createTelegramChannelPostJournalStore(
         const atMs = now();
         if (!isSafeTime(atMs)) throw new TelegramChannelPostJournalError("invalid", "Telegram channel post clock is invalid.");
         const record: TelegramChannelPostRecord = { operationId, requestedChannel: channel,
-          markdown: input.markdown, createdAtMs: atMs, updatedAtMs: atMs, state: "prepared" };
+          markdown: input.markdown, createdAtMs: atMs, updatedAtMs: atMs, state: "prepared",
+          ...(media === undefined ? {} : { media }) };
         publish({ ...file, records: [...file.records, record] });
         return { prepared: true, record: structuredClone(record) };
       });
@@ -531,6 +698,13 @@ export function createTelegramChannelPostJournalStore(
         return { confirmed: true, record: structuredClone(record) };
       });
     },
+    get(operationId) {
+      if (typeof operationId !== "string" || operationId.length === 0 || operationId.length > MAX_ID_LENGTH) {
+        throw new TelegramChannelPostJournalError("invalid", "Telegram channel post operation ID is invalid.");
+      }
+      const record = read().records.find(candidate => candidate.operationId === operationId);
+      return record === undefined ? undefined : structuredClone(record);
+    },
     list(input = {}) {
       const limit = input.limit ?? 20;
       if (!Number.isSafeInteger(limit) || limit <= 0 || limit > maxRecords) {

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

@@ -383,6 +383,7 @@ export interface TelegramBridgeCommandRegistrationDeps {
   getStatusLines: (options?: TelegramBridgeStatusLineOptions) => string[];
   reloadConfig: () => Promise<void>;
   hasBotToken: () => boolean;
+  getBotTokenDiagnostic?: () => string | undefined;
   startPolling: (
     ctx: ExtensionCommandContext,
     options?: TelegramBridgeCommandStartPollingOptions,
@@ -543,6 +544,8 @@ export function registerTelegramBridgeCommands(
         await (deps.activateDefaultProfileConfig?.(ctx) ?? deps.reloadConfig());
       }
       if (!deps.hasBotToken()) {
+        const botTokenDiagnostic = deps.getBotTokenDiagnostic?.();
+        if (botTokenDiagnostic) ctx.ui.notify(botTokenDiagnostic, "error");
         const profileNames = deps.getProfileNames?.() ?? [];
         if (!profileName && profileNames.length > 0) {
           ctx.ui.notify(

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

@@ -62,6 +62,59 @@ function getConfigPath(): string {
   return resolveTelegramConfigPath();
 }
 
+const TELEGRAM_BOT_TOKEN_ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** Parsed stored bot-token form: a literal secret or one environment-variable reference. */
+export type TelegramBotTokenReference =
+  | { kind: "literal"; token: string }
+  | { kind: "environment"; variable: string }
+  | { kind: "malformed" };
+
+/**
+ * Parse a persisted bot-token value. `$NAME` and `${NAME}` are exact
+ * environment-variable references. Any other `$`-prefixed value is malformed
+ * rather than a literal secret so a broken reference fails closed.
+ */
+export function getTelegramBotTokenReference(
+  value: string | undefined,
+): TelegramBotTokenReference | undefined {
+  const trimmed = value?.trim();
+  if (!trimmed) return undefined;
+  if (!trimmed.startsWith("$")) return { kind: "literal", token: trimmed };
+  const body =
+    trimmed.startsWith("${") && trimmed.endsWith("}")
+      ? trimmed.slice(2, -1)
+      : trimmed.slice(1);
+  return TELEGRAM_BOT_TOKEN_ENV_NAME_PATTERN.test(body)
+    ? { kind: "environment", variable: body }
+    : { kind: "malformed" };
+}
+
+/** Resolve a persisted token at a validation/activation boundary. */
+export function resolveTelegramBotToken(
+  value: string | undefined,
+  env: NodeJS.ProcessEnv = process.env,
+): string | undefined {
+  const reference = getTelegramBotTokenReference(value);
+  if (reference?.kind === "literal") return reference.token;
+  if (reference?.kind !== "environment") return undefined;
+  return env[reference.variable]?.trim() || undefined;
+}
+
+/** Redacted diagnostic for an unresolved or malformed token reference. */
+export function getTelegramBotTokenDiagnostic(
+  value: string | undefined,
+  env: NodeJS.ProcessEnv = process.env,
+): string | undefined {
+  const reference = getTelegramBotTokenReference(value);
+  if (reference?.kind === "malformed") {
+    return "Telegram bot token environment reference is malformed; use $NAME or ${NAME}.";
+  }
+  if (reference?.kind !== "environment") return undefined;
+  if (resolveTelegramBotToken(value, env)) return undefined;
+  return `Telegram bot token environment variable ${reference.variable} is not set.`;
+}
+
 export type TelegramOutboundCommandTemplateConfig =
   string | CommandTemplateObjectConfig;
 export interface TelegramOutboundHandlerConfig extends CommandTemplateObjectConfig {
@@ -206,6 +259,7 @@ export interface TelegramConfigStore {
   activateProfile: (profileName: string | undefined) => boolean;
   getActiveProfileName: () => string | undefined;
   getBotToken: () => string | undefined;
+  getBotTokenDiagnostic: () => string | undefined;
   hasBotToken: () => boolean;
   getAllowedUserId: () => number | undefined;
   getLegacyPollingCursor: () => number | undefined;
@@ -261,6 +315,8 @@ export interface TelegramConfigStoreOptions {
   initialConfig?: TelegramConfig;
   agentDir?: string;
   configPath?: string;
+  /** Environment used to resolve `$NAME` token references; defaults to process.env. */
+  env?: NodeJS.ProcessEnv;
   recordRuntimeEvent?: (
     category: string,
     error: unknown,
@@ -653,6 +709,7 @@ export function createTelegramConfigStore(
   let lastLoadRecoveredInvalidConfig = false;
   const agentDir = options.agentDir ?? resolveAgentDir();
   const configPath = options.configPath ?? getConfigPath();
+  const env = options.env ?? process.env;
   const getEffectiveConfig = () =>
     applyTelegramProfile(config, activeProfileName);
   const setEffectiveConfig = (nextConfig: TelegramConfig) => {
@@ -683,8 +740,12 @@ export function createTelegramConfigStore(
     return withTelegramFileTransaction(`${configPath}.transaction`, () => {
       const latest = readTelegramConfigForTransaction(configPath);
       const profile = latest.profiles?.[profileName];
-      if (typeof profile?.botToken !== "string" || !profile.botToken ||
-          createHash("sha256").update(profile.botToken).digest("hex") !== tokenSha256 ||
+      const resolvedToken =
+        typeof profile?.botToken === "string"
+          ? resolveTelegramBotToken(profile.botToken, env)
+          : undefined;
+      if (!profile || !resolvedToken ||
+          createHash("sha256").update(resolvedToken).digest("hex") !== tokenSha256 ||
           (profile.allowedUserId !== undefined &&
             (!Number.isSafeInteger(profile.allowedUserId) || profile.allowedUserId <= 0))) {
         throw new Error("Telegram pairing admission authority is unavailable or changed.");
@@ -723,8 +784,10 @@ export function createTelegramConfigStore(
       return true;
     },
     getActiveProfileName: () => activeProfileName,
-    getBotToken: () => getEffectiveConfig().botToken,
-    hasBotToken: () => !!getEffectiveConfig().botToken,
+    getBotToken: () => resolveTelegramBotToken(getEffectiveConfig().botToken, env),
+    getBotTokenDiagnostic: () =>
+      getTelegramBotTokenDiagnostic(getEffectiveConfig().botToken, env),
+    hasBotToken: () => !!resolveTelegramBotToken(getEffectiveConfig().botToken, env),
     getAllowedUserId: () => getEffectiveConfig().allowedUserId,
     getLegacyPollingCursor: () =>
       (getEffectiveConfig() as TelegramConfig & TelegramLegacyCursorCarrier)

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

@@ -21,7 +21,7 @@ import * as Inbound from "./inbound.ts";
 import * as Journal from "./journal.ts";
 import * as Lifecycle from "./lifecycle.ts";
 import * as Locks from "./locks.ts";
-import * as Logs from "./logs.ts";
+import * as Logging from "./logging.ts";
 import * as Media from "./media.ts";
 import * as MenuQueue from "./menu-queue.ts";
 import * as MenuSettings from "./menu-settings.ts";
@@ -82,7 +82,7 @@ export default function (pi: Pi.ExtensionAPI) {
   } = piRuntime;
   const bridgeRuntime = Runtime.createTelegramBridgeRuntime();
   const runtimeDiagnostics =
-    Logs.createTelegramRuntimeDiagnosticsRuntime<Pi.ExtensionContext>();
+    Logging.createTelegramRuntimeDiagnosticsRuntime<Pi.ExtensionContext>();
   const runtimeEvents = runtimeDiagnostics.events;
   const recordRuntimeEvent = runtimeDiagnostics.recordRuntimeEvent;
   const configStore = Config.createTelegramConfigStore({ recordRuntimeEvent });
@@ -443,7 +443,7 @@ export default function (pi: Pi.ExtensionAPI) {
     Pi.ExtensionContext,
     Queue.TelegramQueueItem<Pi.ExtensionContext>
   >({
-    getConfig: configStore.get,
+    getConfig: Status.createTelegramBridgeStatusConfigGetter(configStore),
     getActiveProfileName: configStore.getActiveProfileName,
     getDiagnosticPaths: Paths.getTelegramDiagnosticsDisplayPaths,
     isPollingActive: Polling.createTelegramPollingActivityReader(
@@ -582,6 +582,13 @@ export default function (pi: Pi.ExtensionAPI) {
     answerGuestQuery,
   });
 
+  // Answer guest queries immediately and replace the ACK with the final text.
+  const answerGuestQueryForInlineMessage =
+    telegramApiRuntime.answerGuestQueryForInlineMessage;
+  const editGuestReply = Replies.createGuestMarkdownReplyEditor({
+    editGuestInlineMessage: telegramApiRuntime.editGuestInlineMessage,
+  });
+
   const promptDispatchRuntime = Runtime.createTelegramPromptDispatchRuntime({
     lifecycle,
     typing,
@@ -970,6 +977,7 @@ export default function (pi: Pi.ExtensionAPI) {
     sendInteractiveMessage,
     deleteMessage: deleteTelegramMessage,
     answerGuestQuery,
+    answerGuestQueryForInlineMessage,
     sendTextReply,
     setMyCommands,
     validateThreadName(threadName) {
@@ -1408,6 +1416,7 @@ export default function (pi: Pi.ExtensionAPI) {
     lock: lockRuntime,
     transportMonitor: telegramThreadCapabilityMonitor,
     hasBotToken: configStore.hasBotToken,
+    getBotTokenDiagnostic: configStore.getBotTokenDiagnostic,
     canStartPolling: Pi.canStartPollingInExtensionContext,
     isContextCurrent: telegramSessionContextStore.isCurrent,
     formatStartBlockedMessage: Pi.formatPollingStartBlockedByRunMode,
@@ -1675,6 +1684,41 @@ export default function (pi: Pi.ExtensionAPI) {
       });
       return record.state === "published" ? record.messageId : undefined;
     },
+    async sendChannelMediaMessage(channel, mediaPath, markdown, options) {
+      if (!lockRuntime.owns()) {
+        throw new Error("Telegram channel media delivery requires direct leader transport ownership.");
+      }
+      const profileName = configStore.getActiveProfileName() ?? "default";
+      const botToken = configStore.getBotToken();
+      if (!botToken) throw new Error("Telegram channel media delivery requires an active bot token.");
+      const media = await ChannelPosts.inspectTelegramChannelPostMedia(mediaPath);
+      const caption = Replies.renderTelegramMarkdownToHtmlDraft(markdown);
+      ChannelPosts.assertTelegramChannelPostCaptionWithinLimit(caption);
+      const store = ChannelPosts.createTelegramChannelPostJournalStore({
+        path: Paths.resolveTelegramChannelPostJournalPath(undefined, profileName),
+        profileName,
+        tokenSha256: Journal.createTelegramUpdateJournalBotIdentity({ botToken }).tokenSha256,
+      });
+      const record = await ChannelPosts.publishTelegramChannelPost({
+        store, operationId: options.operationId,
+        channel: channel as ChannelPosts.TelegramChannelPostAddress, markdown, media,
+        async observeChannel(channelAddress) {
+          return telegramApiRuntime.call("getChat", { chat_id: channelAddress });
+        },
+        async send(channelAddress) {
+          const sent = await telegramApiRuntime.callMultipart<TelegramApi.TelegramSentMessage & {
+            chat: { id: number; type: string };
+          }>(media.kind === "photo" ? "sendPhoto" : "sendVideo", {
+            chat_id: String(channelAddress),
+            caption,
+            parse_mode: "HTML",
+            ...(options.replyMarkup ? { reply_markup: JSON.stringify(options.replyMarkup) } : {}),
+          }, media.kind === "photo" ? "photo" : "video", mediaPath, media.fileName);
+          return { messageId: sent.message_id, chat: sent.chat };
+        },
+      });
+      return record.state === "published" ? record.messageId : undefined;
+    },
     listChannelPosts(input) {
       const profileName = configStore.getActiveProfileName() ?? "default";
       const botToken = configStore.getBotToken();
@@ -1696,6 +1740,12 @@ export default function (pi: Pi.ExtensionAPI) {
       });
       if (input.action === "edit") {
         if (!input.markdown) throw new Error("Telegram channel post edit requires markdown.");
+        const current = store.get(input.operationId);
+        const caption = current?.media
+          ? Replies.renderTelegramMarkdownToHtmlDraft(input.markdown) : undefined;
+        if (caption !== undefined) {
+          ChannelPosts.assertTelegramChannelPostCaptionWithinLimit(caption);
+        }
         const begun = store.beginEdit({ operationId: input.operationId,
           mutationId: input.mutationId, markdown: input.markdown });
         if (!begun.began) {
@@ -1704,9 +1754,17 @@ export default function (pi: Pi.ExtensionAPI) {
           throw new Error("Telegram channel post edit outcome is unknown; refusing automatic replay.");
         }
         if (begun.record.state !== "edit-outcome-unknown") throw new Error("Telegram channel post edit authority is invalid.");
-        await telegramApiRuntime.call("editMessageText", { chat_id: begun.record.channelId,
-          message_id: begun.record.messageId,
-          text: Replies.renderTelegramMarkdownToHtmlDraft(input.markdown), parse_mode: "HTML" });
+        if (begun.record.media) {
+          if (caption === undefined) {
+            throw new Error("Telegram channel post media caption edit requires retained media identity.");
+          }
+          await telegramApiRuntime.call("editMessageCaption", { chat_id: begun.record.channelId,
+            message_id: begun.record.messageId, caption, parse_mode: "HTML" });
+        } else {
+          await telegramApiRuntime.call("editMessageText", { chat_id: begun.record.channelId,
+            message_id: begun.record.messageId,
+            text: Replies.renderTelegramMarkdownToHtmlDraft(input.markdown), parse_mode: "HTML" });
+        }
         return store.confirmEdited({ operationId: input.operationId, mutationId: input.mutationId }).record;
       }
       if (input.markdown !== undefined) throw new Error("Telegram channel post deletion does not accept markdown.");
@@ -1769,6 +1827,7 @@ export default function (pi: Pi.ExtensionAPI) {
     answerGuestQuery,
     deleteMessage: deleteTelegramMessage,
     sendGuestReply,
+    editGuestReply,
     finalizeMarkdownPreview,
     preparePreviewDelivery,
     proactivePushTargetGetter,

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

@@ -1144,6 +1144,7 @@ export interface TelegramLockedPollingRuntimeDeps<
 > {
   lock: TelegramLockRuntime<TContext>;
   hasBotToken: () => boolean;
+  getBotTokenDiagnostic?: () => string | undefined;
   canStartPolling?: (ctx: TContext) => boolean;
   isContextCurrent?: (ctx: TContext) => boolean;
   formatStartBlockedMessage?: (ctx: TContext) => string;
@@ -1305,7 +1306,11 @@ export function createTelegramLockedPollingRuntime<
   return {
     start: async (ctx, options = {}) => {
       if (!deps.hasBotToken()) {
-        return { ok: false, message: "Telegram bot is not configured." };
+        return {
+          ok: false,
+          message:
+            deps.getBotTokenDiagnostic?.() ?? "Telegram bot is not configured.",
+        };
       }
       if (!canStartPolling(ctx)) {
         return { ok: false, message: formatStartBlockedMessage(ctx) };