@llblab/pi-kit 0.1.0

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

@@ -0,0 +1,753 @@
+/**
+ * Telegram turn-building helpers
+ * Zones: telegram inbound, pi agent prompt content, queue
+ * Owns prompt-turn summary and content construction so queued Telegram turns are assembled consistently
+ */
+
+import { readFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+
+import {
+  buildTelegramReplyContextBlock,
+  collectTelegramFileInfos,
+  collectTelegramMessageIds,
+  downloadTelegramMessageFiles,
+  extractTelegramForwardContextText,
+  extractTelegramMessagesPromptText,
+  extractTelegramMessagesText,
+  extractTelegramMessageText,
+  formatTelegramHistoryText,
+  guessMediaType,
+  type DownloadedTelegramMessageFile,
+  type DownloadTelegramMessageFilesDeps,
+  type TelegramMediaMessage,
+} from "./media.ts";
+import {
+  createTelegramQueueAdmissionReceipt,
+  truncateTelegramQueueSummary,
+  type PendingTelegramTurn,
+  type TelegramPromptContent,
+  type TelegramQueueAdmissionReceipt,
+  type TelegramQueueItem,
+  type TelegramQueueStore,
+} from "./queue.ts";
+
+import {
+  computeVoicePromptContribution,
+  computeVoiceTurnFlags,
+  getTelegramVoiceReplyMode,
+  type TelegramVoiceReplyMode,
+} from "./voice.ts";
+
+export const TELEGRAM_PREFIX = "[telegram]";
+
+export interface TelegramTurnTarget {
+  chatId: number;
+  threadId?: number;
+}
+
+export interface TelegramTurnMessage {
+  message_id: number;
+  message_thread_id?: number;
+  pi_telegram_agent_source_thread?: string;
+  pi_telegram_source_update_id?: number;
+  chat: { id: number; type?: string };
+}
+
+export type DownloadedTelegramTurnFile = DownloadedTelegramMessageFile;
+
+function getTelegramTurnTarget(
+  message: TelegramTurnMessage,
+): TelegramTurnTarget {
+  return Number.isInteger(message.message_thread_id)
+    ? { chatId: message.chat.id, threadId: message.message_thread_id }
+    : { chatId: message.chat.id };
+}
+
+function formatTelegramPrefixAttributeValue(value: string): string {
+  return value
+    .replace(/[\]\n\r|]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+export function createTelegramTurnPrefix(
+  attributes: Record<string, string | undefined> = {},
+): string {
+  const parts = [TELEGRAM_PREFIX.slice(1, -1)];
+  for (const [key, value] of Object.entries(attributes)) {
+    const normalized = value ? formatTelegramPrefixAttributeValue(value) : "";
+    if (normalized) parts.push(`${key}:${normalized}`);
+  }
+  return `[${parts.join("|")}]`;
+}
+
+export function formatTelegramTurnPrefix(
+  _message: TelegramTurnMessage,
+  basePrefix = TELEGRAM_PREFIX,
+): string {
+  return basePrefix;
+}
+
+export { truncateTelegramQueueSummary };
+
+export function formatTelegramTurnStatusSummary(
+  rawText: string,
+  files: DownloadedTelegramTurnFile[],
+  handlerOutputs: string[] = [],
+): string {
+  const textSummary = truncateTelegramQueueSummary(rawText);
+  if (textSummary) return textSummary;
+  const handlerSummary = truncateTelegramQueueSummary(handlerOutputs.join(" "));
+  if (handlerSummary) return handlerSummary;
+  if (files.length === 1) {
+    const fileName = basename(
+      files[0]?.fileName || files[0]?.path || "attachment",
+    );
+    return `📎 ${truncateTelegramQueueSummary(fileName, 4, 32) || "attachment"}`;
+  }
+  if (files.length > 1) return `📎 ${files.length} attachments`;
+  return "(empty message)";
+}
+
+function appendTelegramListSection(
+  text: string,
+  title: string,
+  items: string[],
+): string {
+  if (items.length === 0) return text;
+  const prefix = text.length > 0 ? `${text}\n\n` : "";
+  return `${prefix}[${title}]\n${items.map((item) => `- ${item}`).join("\n")}`;
+}
+
+function appendTelegramAttachmentSection(
+  text: string,
+  files: Pick<DownloadedTelegramTurnFile, "path">[],
+): string {
+  if (files.length === 0) return text;
+  const dirs = [...new Set(files.map((file) => dirname(file.path)))];
+  const sameDir = dirs.length === 1;
+  const header = sameDir ? `[attachments] ${dirs[0]}` : "[attachments]";
+  const items = sameDir
+    ? files.map((file) => `/${basename(file.path)}`)
+    : files.map((file) => file.path);
+  const prefix = text.length > 0 ? `${text}\n\n` : "";
+  return `${prefix}${header}\n${items.map((item) => `- ${item}`).join("\n")}`;
+}
+
+function appendTelegramSourceContext(
+  text: string,
+  sourceContext: string | undefined,
+): string {
+  if (!sourceContext) return text;
+  return text ? `${text}\n\n${sourceContext}` : sourceContext;
+}
+
+function buildTelegramForwardContextBlock(options: {
+  context: string;
+  text: string;
+  files: DownloadedTelegramTurnFile[];
+}): string {
+  const metadata = options.context.replace(/:\s+/g, ":");
+  const from = metadata.match(/^from:(.+)$/)?.[1];
+  let block = `[forward|${metadata}]${options.text ? ` ${options.text}` : ""}`;
+  if (options.files.length === 0) return block;
+  const dirs = [...new Set(options.files.map((file) => dirname(file.path)))];
+  const sameDir = dirs.length === 1;
+  const header = `[attachments${from ? `|from:${from}` : ""}]${
+    sameDir ? ` ${dirs[0]}` : ""
+  }`;
+  const items = sameDir
+    ? options.files.map((file) => `/${basename(file.path)}`)
+    : options.files.map((file) => file.path);
+  block += `\n\n${header}\n${items.map((item) => `- ${item}`).join("\n")}`;
+  return block;
+}
+
+function appendTelegramPromptText(prompt: string, rawText: string): string {
+  if (!rawText) return prompt;
+  if (rawText.startsWith("\n")) return `${prompt}${rawText}`;
+  return `${prompt} ${rawText}`;
+}
+
+function appendTelegramVoiceContext(
+  prompt: string,
+  entries: Record<string, string>,
+): string {
+  const prefix = prompt.length > 0 ? `${prompt}\n\n` : "";
+  const pairs = Object.entries(entries);
+  if (pairs.length === 1) {
+    const [key, value] = pairs[0];
+    return `${prefix}[voice] ${key}: ${value}`;
+  }
+  return `${prefix}[voice]\n${pairs
+    .map(([key, value]) => `- ${key}: ${value}`)
+    .join("\n")}`;
+}
+
+// --- Voice Policy And Tagging ---
+
+export function buildTelegramTurnPrompt(options: {
+  telegramPrefix: string;
+  rawText: string;
+  files: DownloadedTelegramTurnFile[];
+  promptFiles?: DownloadedTelegramTurnFile[];
+  displayFiles?: DownloadedTelegramTurnFile[];
+  handlerOutputs?: string[];
+  sourceContext?: string;
+  historyTurns?: Pick<PendingTelegramTurn, "historyText">[];
+  timeLine?: string | null;
+  voiceContext?: Record<string, string>;
+}): string {
+  let prompt = options.telegramPrefix;
+  if ((options.historyTurns?.length ?? 0) > 0) {
+    prompt +=
+      "\n\nEarlier Telegram messages arrived after an aborted turn. Treat them as prior user messages, in order:";
+    for (const [index, turn] of (options.historyTurns ?? []).entries()) {
+      prompt += `\n\n${index + 1}. ${turn.historyText}`;
+    }
+    prompt += "\n\nCurrent Telegram message:";
+  }
+  if (options.rawText.length > 0) {
+    prompt =
+      (options.historyTurns?.length ?? 0) > 0
+        ? `${prompt}\n${options.rawText}`
+        : appendTelegramPromptText(prompt, options.rawText);
+  }
+  const displayFiles =
+    options.displayFiles ?? options.promptFiles ?? options.files;
+  prompt = appendTelegramAttachmentSection(prompt, displayFiles);
+  prompt = appendTelegramListSection(
+    prompt,
+    "outputs",
+    options.handlerOutputs ?? [],
+  );
+  prompt = appendTelegramSourceContext(prompt, options.sourceContext);
+  if (options.voiceContext) {
+    prompt = appendTelegramVoiceContext(prompt, options.voiceContext);
+  }
+  if (options.timeLine) {
+    prompt = `${prompt}\n\n[time] ${options.timeLine}`;
+  }
+  return prompt;
+}
+
+function splitTelegramPromptAttachmentSuffix(prompt: string): {
+  promptWithoutAttachments: string;
+  attachmentSuffix: string;
+  attachmentFiles: DownloadedTelegramTurnFile[];
+} {
+  const marker = "\n\n[attachments]";
+  const markerIndex = prompt.indexOf(marker);
+  if (markerIndex === -1) {
+    return {
+      promptWithoutAttachments: prompt,
+      attachmentSuffix: "",
+      attachmentFiles: [],
+    };
+  }
+  const promptWithoutAttachments = prompt.slice(0, markerIndex);
+  const attachmentSuffix = prompt.slice(markerIndex);
+  const attachmentLines: string[] = [];
+  let readingAttachments = false;
+  let attachmentDir: string | undefined;
+  for (const line of attachmentSuffix.split("\n")) {
+    const trimmed = line.trim();
+    const attachmentMatch = trimmed.match(/^\[attachments\](?:\s+(.+))?$/);
+    if (attachmentMatch) {
+      readingAttachments = true;
+      attachmentDir = attachmentMatch[1]?.trim();
+      continue;
+    }
+    if (readingAttachments && /^\[[^\]]+\](?:\s+.*)?$/.test(trimmed)) break;
+    if (readingAttachments) attachmentLines.push(line);
+  }
+  const attachmentFiles = attachmentLines
+    .map((line) => line.match(/^- (.+)$/)?.[1]?.trim())
+    .filter((path): path is string => !!path)
+    .map((path) =>
+      attachmentDir ? join(attachmentDir, path.replace(/^\/+/, "")) : path,
+    )
+    .map((path) => ({
+      path,
+      fileName: basename(path),
+      isImage: false,
+      kind: "document" as const,
+    }));
+  return { promptWithoutAttachments, attachmentSuffix, attachmentFiles };
+}
+
+function buildEditedTelegramPromptText(options: {
+  existingPrompt: string;
+  telegramPrefix: string;
+  rawText: string;
+}): { text: string; attachmentFiles: DownloadedTelegramTurnFile[] } {
+  const { promptWithoutAttachments, attachmentSuffix, attachmentFiles } =
+    splitTelegramPromptAttachmentSuffix(options.existingPrompt);
+  const currentMessageMarker = "Current Telegram message:";
+  const currentMessageIndex =
+    promptWithoutAttachments.lastIndexOf(currentMessageMarker);
+  if (currentMessageIndex !== -1) {
+    const prefix = promptWithoutAttachments.slice(
+      0,
+      currentMessageIndex + currentMessageMarker.length,
+    );
+    const separator = options.rawText.length > 0 ? "\n" : "";
+    return {
+      text: `${prefix}${separator}${options.rawText}${attachmentSuffix}`,
+      attachmentFiles,
+    };
+  }
+  return {
+    text: `${appendTelegramPromptText(
+      options.telegramPrefix,
+      options.rawText,
+    )}${attachmentSuffix}`,
+    attachmentFiles,
+  };
+}
+
+export function updateTelegramPromptTurnText(options: {
+  turn: PendingTelegramTurn;
+  telegramPrefix: string;
+  rawText: string;
+  statusText?: string;
+}): PendingTelegramTurn {
+  let attachmentFiles: DownloadedTelegramTurnFile[] = [];
+  const nextContent = options.turn.content.map((block, index) => {
+    if (index !== 0 || block.type !== "text") return block;
+    const updated = buildEditedTelegramPromptText({
+      existingPrompt: block.text,
+      telegramPrefix: options.telegramPrefix,
+      rawText: options.rawText,
+    });
+    attachmentFiles = updated.attachmentFiles;
+    return {
+      ...block,
+      text: updated.text,
+    };
+  });
+  return {
+    ...options.turn,
+    content: nextContent,
+    historyText: formatTelegramHistoryText(options.rawText, attachmentFiles),
+    statusSummary: formatTelegramTurnStatusSummary(
+      options.statusText ?? options.rawText,
+      attachmentFiles,
+    ),
+  };
+}
+
+export function updateQueuedTelegramPromptTurnText<
+  TContext = unknown,
+>(options: {
+  items: TelegramQueueItem<TContext>[];
+  sourceMessageId: number | undefined;
+  telegramPrefix: string;
+  rawText: string;
+  statusText?: string;
+}): { items: TelegramQueueItem<TContext>[]; changed: boolean } {
+  if (options.sourceMessageId === undefined) {
+    return { items: options.items, changed: false };
+  }
+  let changed = false;
+  const items = options.items.map((item) => {
+    if (
+      item.kind !== "prompt" ||
+      !item.sourceMessageIds.includes(options.sourceMessageId as number)
+    ) {
+      return item;
+    }
+    changed = true;
+    return updateTelegramPromptTurnText({
+      turn: item,
+      telegramPrefix: options.telegramPrefix,
+      rawText: options.rawText,
+      statusText: options.statusText,
+    });
+  });
+  return { items, changed };
+}
+
+export interface TelegramQueuedPromptEditRuntimeDeps<
+  TContext = unknown,
+> extends TelegramQueueStore<TContext> {
+  updateStatus: (ctx: TContext) => void;
+}
+
+export function createTelegramQueuedPromptEditRuntime<
+  TMessage extends TelegramMediaMessage,
+  TContext = unknown,
+>(deps: TelegramQueuedPromptEditRuntimeDeps<TContext>) {
+  return {
+    updateFromEditedMessage: (message: TMessage, ctx: TContext): boolean => {
+      const { changed, items } = updateQueuedTelegramPromptTurnText({
+        items: deps.getQueuedItems(),
+        sourceMessageId: message.message_id,
+        telegramPrefix: TELEGRAM_PREFIX,
+        rawText: extractTelegramMessagesPromptText([message]),
+        statusText: extractTelegramMessagesText([message]),
+      });
+      deps.setQueuedItems(items);
+      if (changed) deps.updateStatus(ctx);
+      return changed;
+    },
+  };
+}
+
+export interface BuildTelegramPromptTurnOptions {
+  telegramPrefix: string;
+  messages: TelegramTurnMessage[];
+  historyTurns?: PendingTelegramTurn[];
+  queueOrder: number;
+  rawText: string;
+  statusText?: string;
+  files: DownloadedTelegramTurnFile[];
+  promptFiles?: DownloadedTelegramTurnFile[];
+  displayFiles?: DownloadedTelegramTurnFile[];
+  handlerOutputs?: string[];
+  sourceContext?: string;
+  timeLine?: string | null;
+  readBinaryFile: (path: string) => Promise<Uint8Array>;
+  inferImageMimeType: (path: string) => string | undefined;
+  voiceReplyMode?: TelegramVoiceReplyMode;
+  voicePromptContribution?: string;
+  admissionScope?: string;
+  admissionJournalBinding?: string;
+}
+
+export type BuildTelegramPromptTurnRuntimeOptions = Omit<
+  BuildTelegramPromptTurnOptions,
+  "readBinaryFile"
+>;
+
+export interface TelegramPromptTurnRuntimeBuilderDeps<
+  TContext = unknown,
+> extends DownloadTelegramMessageFilesDeps {
+  allocateQueueOrder: () => number;
+  processAttachments?: (
+    files: DownloadedTelegramTurnFile[],
+    rawText: string,
+    ctx: TContext,
+  ) => Promise<{
+    rawText: string;
+    promptFiles?: DownloadedTelegramTurnFile[];
+    handlerOutputs?: string[];
+  }>;
+  resolveTimeLine?: (chatId: number) => string | null;
+  getVoiceReplyMode?: () => TelegramVoiceReplyMode;
+  /** Returns the visible thread label for a message target, used to add thread context to the prompt prefix. */
+  getTelegramThreadLabel?: (message: {
+    chat: { id: number };
+    message_thread_id?: number;
+  }) => string | undefined;
+  getAllowedUserId?: () => number | undefined;
+  getAdmissionScope?: () => string | undefined;
+  getAdmissionJournalBinding?: () => string | undefined;
+  assertExecutionCurrent?: (message: TelegramTurnMessage) => void;
+}
+
+export function createTelegramPromptTurnRuntimeBuilder<
+  TMessage extends TelegramTurnMessage & TelegramMediaMessage,
+  TContext = unknown,
+>(
+  deps: TelegramPromptTurnRuntimeBuilderDeps<TContext>,
+): (
+  messages: TMessage[],
+  historyTurns?: PendingTelegramTurn[],
+  ctx?: TContext,
+) => Promise<PendingTelegramTurn> {
+  return async (messages, historyTurns = [], ctx) => {
+    const rawText = extractTelegramMessagesText(messages);
+    const firstMessage = messages[0];
+    if (firstMessage) deps.assertExecutionCurrent?.(firstMessage);
+    const replyFiles = firstMessage?.reply_to_message
+      ? await downloadTelegramMessageFiles(
+          [firstMessage.reply_to_message as typeof firstMessage],
+          { downloadFile: deps.downloadFile },
+        )
+      : [];
+    if (firstMessage) deps.assertExecutionCurrent?.(firstMessage);
+    const replyContext = firstMessage
+      ? buildTelegramReplyContextBlock(firstMessage, replyFiles)
+      : "";
+    const forwardEntries = messages.flatMap((message) => {
+      const context = extractTelegramForwardContextText(
+        message,
+        deps.getAllowedUserId?.(),
+      );
+      return context
+        ? [
+            {
+              context,
+              text: extractTelegramMessageText(message),
+              message,
+              fileNames: new Set(
+                collectTelegramFileInfos([message]).map((file) => file.fileName),
+              ),
+            },
+          ]
+        : [];
+    });
+    const files = await downloadTelegramMessageFiles(messages, {
+      downloadFile: deps.downloadFile,
+    });
+    if (firstMessage) deps.assertExecutionCurrent?.(firstMessage);
+    const processed = deps.processAttachments
+      ? await deps.processAttachments(files, rawText, ctx as TContext)
+      : { rawText, promptFiles: files };
+    if (firstMessage) deps.assertExecutionCurrent?.(firstMessage);
+    const sourceBlocks: string[] = [];
+    let promptRawText = processed.rawText;
+    const forwardedFilePaths = new Set<string>();
+    const getForwardFiles = (entry: (typeof forwardEntries)[number]) =>
+      (processed.promptFiles ?? files).filter((file) => {
+        if (!entry.fileNames.has(file.fileName)) return false;
+        forwardedFilePaths.add(file.path);
+        return true;
+      });
+    if (forwardEntries.length === 1 && messages.length === 1) {
+      const [forward] = forwardEntries;
+      sourceBlocks.push(
+        buildTelegramForwardContextBlock({
+          context: forward!.context,
+          text: processed.rawText,
+          files: getForwardFiles(forward!),
+        }),
+      );
+      promptRawText = "";
+    } else if (forwardEntries.length > 0 && processed.rawText === rawText) {
+      const forwardedMessages = new Set(
+        forwardEntries.map((entry) => entry.message),
+      );
+      promptRawText = messages
+        .filter((message) => !forwardedMessages.has(message))
+        .map(extractTelegramMessageText)
+        .filter(Boolean)
+        .join("\n\n");
+      sourceBlocks.push(
+        ...forwardEntries.map((entry) =>
+          buildTelegramForwardContextBlock({
+            context: entry.context,
+            text: entry.text,
+            files: getForwardFiles(entry),
+          }),
+        ),
+      );
+    } else if (forwardEntries.length > 0) {
+      sourceBlocks.push(
+        ...forwardEntries.map((entry) =>
+          buildTelegramForwardContextBlock({
+            context: entry.context,
+            text: "",
+            files: getForwardFiles(entry),
+          }),
+        ),
+      );
+    }
+    if (replyContext) sourceBlocks.push(replyContext);
+    const sourceContext = sourceBlocks.join("\n\n");
+    // Compute voice mode once and pass it to both the turn builder and the prompt contribution helper
+    const voiceReplyMode = deps.getVoiceReplyMode?.();
+    const chatId = messages[0]?.chat.id;
+    const timeLine =
+      deps.resolveTimeLine && chatId !== undefined
+        ? deps.resolveTimeLine(chatId)
+        : null;
+    const threadLabel = firstMessage
+      ? deps.getTelegramThreadLabel?.(firstMessage)
+      : undefined;
+    const telegramPrefix = createTelegramTurnPrefix({
+      thread: threadLabel,
+      "from-thread": firstMessage?.pi_telegram_agent_source_thread,
+    });
+    return buildTelegramPromptTurnRuntime({
+      telegramPrefix,
+      messages,
+      historyTurns,
+      queueOrder: deps.allocateQueueOrder(),
+      rawText: promptRawText,
+      sourceContext,
+      statusText: processed.rawText,
+      files,
+      promptFiles: processed.promptFiles,
+      displayFiles: (processed.promptFiles ?? files).filter(
+        (file) => !forwardedFilePaths.has(file.path),
+      ),
+      handlerOutputs: processed.handlerOutputs,
+      timeLine,
+      inferImageMimeType: guessMediaType,
+      voiceReplyMode,
+      voicePromptContribution: computeVoicePromptContribution(
+        voiceReplyMode,
+        files,
+        rawText,
+      ),
+      admissionScope: deps.getAdmissionScope?.(),
+      admissionJournalBinding: deps.getAdmissionJournalBinding?.(),
+    });
+  };
+}
+
+function getTelegramVoicePromptContext(
+  voiceReplyMode: TelegramVoiceReplyMode,
+  hasVoiceFile: boolean,
+): Record<string, string> | undefined {
+  if (
+    voiceReplyMode !== "always" &&
+    !(voiceReplyMode === "mirror" && hasVoiceFile)
+  ) {
+    return undefined;
+  }
+  return { delivery: "automatic voice" };
+}
+
+function collectTelegramTurnAdmissionReceipts(
+  messages: TelegramTurnMessage[],
+  historyTurns: PendingTelegramTurn[],
+  admissionScope: string | undefined,
+  admissionJournalBinding: string | undefined,
+): TelegramQueueAdmissionReceipt[] {
+  const receipts = new Map<string, TelegramQueueAdmissionReceipt>();
+  const addReceipt = (receipt: TelegramQueueAdmissionReceipt): void => {
+    const existing = receipts.get(receipt.receiptId);
+    if (existing) {
+      if (
+        existing.queueKind !== receipt.queueKind ||
+        existing.journalBindingKey !== receipt.journalBindingKey ||
+        existing.sourceUpdateIds.length !== receipt.sourceUpdateIds.length ||
+        existing.sourceUpdateIds.some(
+          (updateId, index) => updateId !== receipt.sourceUpdateIds[index],
+        )
+      ) {
+        throw new Error(
+          `Conflicting Telegram turn receipt: ${receipt.receiptId}`,
+        );
+      }
+      return;
+    }
+    receipts.set(receipt.receiptId, structuredClone(receipt));
+  };
+  for (const turn of historyTurns) {
+    for (const receipt of turn.admissionReceipts ?? []) addReceipt(receipt);
+  }
+  const sourceUpdateIds = messages.flatMap((message) =>
+    typeof message.pi_telegram_source_update_id === "number"
+      ? [message.pi_telegram_source_update_id]
+      : [],
+  );
+  if (sourceUpdateIds.length > 0) {
+    const currentReceipt = createTelegramQueueAdmissionReceipt({
+      queueKind: "prompt",
+      scope: admissionScope ?? "",
+      sourceUpdateIds,
+    });
+    if (currentReceipt) {
+      addReceipt({
+        ...currentReceipt,
+        ...(admissionJournalBinding
+          ? { journalBindingKey: admissionJournalBinding }
+          : {}),
+      });
+    }
+  }
+  return [...receipts.values()];
+}
+
+export async function buildTelegramPromptTurn(
+  options: BuildTelegramPromptTurnOptions,
+): Promise<PendingTelegramTurn> {
+  const firstMessage = options.messages[0];
+  if (!firstMessage) {
+    throw new Error("Missing Telegram message for turn creation");
+  }
+  const hasVoiceFile = options.files.some(
+    (f) => f.kind === "voice" || f.kind === "audio",
+  );
+  const voiceReplyMode = options.voiceReplyMode ?? getTelegramVoiceReplyMode();
+  const content: TelegramPromptContent[] = [
+    {
+      type: "text",
+      text: buildTelegramTurnPrompt({
+        telegramPrefix: formatTelegramTurnPrefix(
+          firstMessage,
+          options.telegramPrefix,
+        ),
+        rawText: options.rawText,
+        files: options.files,
+        promptFiles: options.promptFiles,
+        displayFiles: options.displayFiles,
+        handlerOutputs: options.handlerOutputs,
+        sourceContext: options.sourceContext,
+        historyTurns: options.historyTurns,
+        timeLine: options.timeLine,
+        voiceContext: getTelegramVoicePromptContext(
+          voiceReplyMode,
+          hasVoiceFile,
+        ),
+      }),
+    },
+  ];
+  for (const file of options.files) {
+    if (!file.isImage) continue;
+    const mediaType = file.mimeType || options.inferImageMimeType(file.path);
+    if (!mediaType) continue;
+    const buffer = await options.readBinaryFile(file.path);
+    content.push({
+      type: "image",
+      data: Buffer.from(buffer).toString("base64"),
+      mimeType: mediaType,
+    });
+  }
+  if (options.voicePromptContribution?.trim()) {
+    const textItem = content.find((c) => c.type === "text") as
+      { type: "text"; text: string } | undefined;
+    if (textItem) {
+      textItem.text = `${textItem.text}\n\n${options.voicePromptContribution.trim()}`;
+    }
+  }
+  const admissionReceipts = collectTelegramTurnAdmissionReceipts(
+    options.messages,
+    options.historyTurns ?? [],
+    options.admissionScope,
+    options.admissionJournalBinding,
+  );
+
+  return {
+    kind: "prompt",
+    chatId: firstMessage.chat.id,
+    target: getTelegramTurnTarget(firstMessage),
+    replyToMessageId: firstMessage.message_id,
+    sourceMessageIds: collectTelegramMessageIds(options.messages),
+    queueOrder: options.queueOrder,
+    queueLane: "default",
+    laneOrder: options.queueOrder,
+    queuedAttachments: [],
+    content,
+    historyText: appendTelegramSourceContext(
+      formatTelegramHistoryText(
+        options.rawText,
+        options.displayFiles ?? options.promptFiles ?? options.files,
+        options.handlerOutputs,
+      ),
+      options.sourceContext,
+    ),
+    statusSummary: formatTelegramTurnStatusSummary(
+      options.statusText ?? options.rawText,
+      options.displayFiles ?? options.promptFiles ?? options.files,
+      options.handlerOutputs,
+    ),
+    ...(admissionReceipts.length > 0 ? { admissionReceipts } : {}),
+    // Voice tagging (used for preview suppression and prompt guidance)
+    ...computeVoiceTurnFlags(voiceReplyMode, hasVoiceFile),
+  };
+}
+
+export async function buildTelegramPromptTurnRuntime(
+  options: BuildTelegramPromptTurnRuntimeOptions,
+): Promise<PendingTelegramTurn> {
+  return buildTelegramPromptTurn({
+    ...options,
+    readBinaryFile: readFile,
+  });
+}