@llblab/pi-telegram 0.10.7 → 0.11.0

package/lib/preview.ts

@@ -20,8 +20,10 @@ import {
   type TelegramRenderedChunk,
   type TelegramRenderMode,
 } from "./rendering.ts";
+
 import { buildTelegramReplyParameters } from "./replies.ts";
 import { stripTelegramCommentMarkupForPreview } from "./outbound-handlers.ts";
+import { shouldSuppressPreviewForVoice } from "./voice.ts";
 
 const TELEGRAM_PREVIEW_THROTTLE_MS = 750;
 const TELEGRAM_DRAFT_ID_MAX = 2_147_483_647;
@@ -104,6 +106,8 @@ export interface TelegramPreviewRuntimeDeps<
 
 export interface TelegramPreviewActiveTurn {
   chatId: number;
+  voiceReplyPreferred?: boolean;
+  voiceReplyRequired?: boolean;
 }
 
 export interface TelegramAssistantMessagePreviewStartDeps<
@@ -504,6 +508,10 @@ export async function handleTelegramAssistantMessagePreviewStart<
 ): Promise<void> {
   const turn = deps.getActiveTurn();
   if (!turn || !deps.isAssistantMessage(message)) return;
+  if (shouldSuppressPreviewForVoice(turn)) {
+    deps.setState(undefined);
+    return;
+  }
   const state = deps.getState();
   if (
     state &&
@@ -526,6 +534,7 @@ export async function handleTelegramAssistantMessagePreviewUpdate<TMessage>(
 ): Promise<void> {
   const turn = deps.getActiveTurn();
   if (!turn || !deps.isAssistantMessage(message)) return;
+  if (shouldSuppressPreviewForVoice(turn)) return;
   let state = deps.getState();
   if (!state) {
     state = deps.createPreviewState();

package/lib/prompts.ts

@@ -15,6 +15,7 @@ Inbound context:
 - \`[telegram]\` marks Telegram-originated messages. Suffixes \`|from:user\` (sender) and \`|guest:group\` (guest mode — message from another chat where the bot is not a member) may be present; the bot sees the message as if forwarded from that user/chat.
 - \`[reply]\` is quoted context from the replied-to message, not a new instruction by itself. Suffix \`|from:user\` identifies the original author in guest-mode replies. Use it to resolve references like "this", "it", or "that message"; the actual instruction is before [reply] unless it explicitly asks to act on the quote.
 - \`[attachments]\` gives a base directory plus relative local files; resolve and read them as needed. \`[outputs]\` contains inbound-handler stdout such as transcriptions or extracted text for those attachments.
+- \`[voice]\` describes Telegram voice reply policy for this turn. \`manual\` means answer normally and use explicit \`telegram_voice\` markup only when a spoken reply is useful; \`mirror\` means voice input prefers a voice reply; \`always\` means the final reply is expected to be converted to voice, so keep it TTS-friendly.
 - Unknown \`[callback] ...\` messages may be intended for another extension; if you see one, say the callback was not handled and the environment may be misconfigured.
 
 Telegram-visible output:
@@ -25,7 +26,7 @@ Telegram-visible output:
 
 Native outbound actions:
 - Use top-level column-zero hidden Markdown comments outside code, quotes, and lists; the bridge handles them after agent_end, so do not call or register transport/TTS/text-to-OGG tools.
-- \`telegram_voice\`: text is synthesized through the configured outbound-handler pipeline. Use body text for multiline voice, \`<!-- telegram_voice text="Short summary" -->\` for explicit one-line voice, or \`<!-- telegram_voice: Short summary -->\` for one-line voice with no attributes. A companion summary is optional, no specific summary format is required. Keep it TTS-friendly; avoid raw Markdown, code, formulas, tables, or long lists.
+- \`telegram_voice\`: text is synthesized by the registered voice synthesis provider and delivered by pi-telegram. Use body text for multiline voice, \`<!-- telegram_voice text="Short summary" -->\` for explicit one-line voice, or \`<!-- telegram_voice: Short summary -->\` for one-line voice with no attributes. A companion summary is optional, no specific summary format is required. Keep it TTS-friendly; avoid raw Markdown, code, formulas, tables, or long lists.
 - \`telegram_button\`: callback prompt is routed back as a normal Telegram turn. Use \`<!-- telegram_button: OK -->\` when prompt equals label, \`<!-- telegram_button label=Continue prompt="Continue with the current plan." -->\` for one-line prompts, or body form \`<!-- telegram_button label="Show risks"\nList the main risks first.\n-->\` for multiline prompts.
 - If only hidden action comments would remain, add visible parent text like "Choose one:".
 `;

package/lib/queue.ts

@@ -4,6 +4,8 @@
  * Owns queue item contracts, lane admission, pure queue mutations, and dispatch planning
  */
 
+import { isVoiceTurn } from "./voice.ts";
+
 // --- Queue Items ---
 
 export interface QueuedAttachment {
@@ -80,6 +82,11 @@ export interface PendingTelegramTurn extends TelegramQueueItemBase {
   content: TelegramPromptContent[];
   historyText: string;
   priorityEmoji?: string;
+
+  /** Turn should preferably be delivered as voice (mirror mode + user sent voice) */
+  voiceReplyPreferred?: boolean;
+  /** Turn must be delivered as voice (voice mode) */
+  voiceReplyRequired?: boolean;
 }
 
 export interface PendingTelegramControlItem<
@@ -371,6 +378,24 @@ export function formatQueuedTelegramItemsStatus<TContext = unknown>(
   return items.length === 0 ? "" : ` +${items.length}`;
 }
 
+export function truncateTelegramQueueSummary(
+  text: string,
+  maxWords = 5,
+  maxLength = 40,
+): string {
+  const normalized = text.replace(/\s+/g, " ").trim();
+  if (!normalized) return "";
+  const words = normalized.split(" ");
+  let summary = words.slice(0, maxWords).join(" ");
+  if (summary.length === 0) summary = normalized;
+  if (summary.length > maxLength) {
+    summary = summary.slice(0, maxLength).trimEnd();
+  }
+  return summary.length < normalized.length || words.length > maxWords
+    ? `${summary}…`
+    : summary;
+}
+
 export function canDispatchTelegramTurnState(
   state: TelegramDispatchGuardState,
 ): boolean {
@@ -788,7 +813,11 @@ export interface TelegramAgentEndRuntimeDeps<
     text: string,
   ) => Promise<unknown>;
   sendQueuedAttachments: (turn: TTurn) => Promise<void>;
-  answerGuestQuery?: (guestQueryId: string, text?: string, options?: { parseMode?: string }) => Promise<void>;
+  answerGuestQuery?: (
+    guestQueryId: string,
+    text?: string,
+    options?: { parseMode?: string },
+  ) => Promise<void>;
   sendGuestReply?: (guestQueryId: string, markdown: string) => Promise<void>;
   planOutboundReply?: (
     markdown: string,
@@ -976,9 +1005,32 @@ export async function handleTelegramAgentEndRuntime<
 >(deps: TelegramAgentEndRuntimeDeps<TTurn, TReplyMarkup>): Promise<void> {
   const { turn, assistant } = deps;
   const rawFinalText = assistant.text;
-  const outboundReply = rawFinalText
+  let outboundReply = rawFinalText
     ? deps.planOutboundReply?.(rawFinalText)
     : undefined;
+  // Preserve the planned reply so voice-fallback can use stripped markdown + replyMarkup
+  const plannedReply = outboundReply;
+
+  // Transparent voice interception: when the turn is voice-tagged and the agent
+  // did not explicitly use <!-- telegram_voice --> markup, we automatically
+  // convert the whole response to voice.
+  const voiceInterceptionGuard =
+    turn &&
+    isVoiceTurn(turn) &&
+    rawFinalText?.trim() &&
+    deps.planOutboundReply &&
+    (!outboundReply ||
+      (!outboundReply.voiceText && !outboundReply.voiceReplies?.length));
+  if (voiceInterceptionGuard) {
+    const voiceText =
+      plannedReply !== undefined
+        ? plannedReply.markdown?.trim() || ""
+        : (rawFinalText ?? "");
+    outboundReply = outboundReply
+      ? { ...outboundReply, voiceText, markdown: "" }
+      : { markdown: "", voiceText };
+  }
+
   const finalText = outboundReply ? outboundReply.markdown : rawFinalText;
   const hasOutboundArtifacts =
     !!outboundReply?.voiceText || !!outboundReply?.voiceReplies?.length;
@@ -1080,9 +1132,36 @@ export async function handleTelegramAgentEndRuntime<
     }
   }
   if (outboundReply && deps.sendOutboundReplyArtifacts) {
-    await deps.sendOutboundReplyArtifacts(turn, outboundReply, {
-      replyToPrompt: !finalText,
-    });
+    try {
+      await deps.sendOutboundReplyArtifacts(turn, outboundReply, {
+        replyToPrompt: !finalText,
+      });
+    } catch (error) {
+      deps.recordRuntimeEvent?.("delivery", error, {
+        phase: "voice-artifacts",
+        chatId: turn.chatId,
+      });
+      // Fallback to planned text when voice delivery fails and text wasn't already delivered
+      if (rawFinalText?.trim() && !finalText && hasOutboundArtifacts) {
+        try {
+          const fallbackMarkdown =
+            plannedReply?.markdown || outboundReply?.voiceText || rawFinalText;
+          await deps.sendMarkdownReply(
+            turn.chatId,
+            turn.replyToMessageId,
+            fallbackMarkdown,
+            plannedReply?.replyMarkup
+              ? { replyMarkup: plannedReply.replyMarkup }
+              : undefined,
+          );
+        } catch (fallbackError) {
+          deps.recordRuntimeEvent?.("delivery", fallbackError, {
+            phase: "voice-fallback-text",
+            chatId: turn.chatId,
+          });
+        }
+      }
+    }
   }
   if (endPlan.shouldSendAttachmentNotice) {
     await deps.sendTextReply(

package/lib/routing.ts

@@ -18,6 +18,7 @@ import * as Queue from "./queue.ts";
 import type { TelegramBridgeRuntime } from "./runtime.ts";
 import * as TextGroups from "./text-groups.ts";
 import * as Turns from "./turns.ts";
+import { getTelegramVoiceReplyMode } from "./voice.ts";
 import type { TelegramUser } from "./updates.ts";
 import * as Updates from "./updates.ts";
 
@@ -38,7 +39,7 @@ export interface TelegramInboundRouteRuntimeDeps<
 > {
   configStore: Pick<
     TelegramConfigStore,
-    "getAllowedUserId" | "setAllowedUserId" | "persist"
+    "get" | "getAllowedUserId" | "setAllowedUserId" | "persist"
   >;
   bridgeRuntime: TelegramBridgeRuntime;
   activeTurnRuntime: Queue.TelegramActiveTurnStore;
@@ -82,6 +83,8 @@ export interface TelegramInboundRouteRuntimeDeps<
   requestDeferredDispatchNextQueuedTelegramTurn?: (
     dispatch: (ctx: TContext) => void,
   ) => void;
+  startTypingLoop?: (ctx: TContext, chatId?: number) => void;
+  stopTypingLoop?: () => void;
   answerCallbackQuery: (
     callbackQueryId: string,
     text?: string,
@@ -284,6 +287,14 @@ export function createTelegramInboundRouteRuntime<
     allocateQueueOrder: deps.bridgeRuntime.queue.allocateItemOrder,
     downloadFile: deps.downloadFile,
     processAttachments: deps.inboundHandlerRuntime.process,
+
+    // Voice policy for the current turn. Missing config still behaves as manual,
+    // but only explicit telegram.json voice.replyMode is shown in prompt context.
+    getVoiceReplyMode: () => getTelegramVoiceReplyMode(deps.configStore.get()),
+    isVoiceReplyModeConfigured: () => {
+      const mode = deps.configStore.get().voice?.replyMode;
+      return mode === "manual" || mode === "mirror" || mode === "always";
+    },
   });
   const enqueueContinueTurn = async (
     message: TMessage,
@@ -344,6 +355,8 @@ export function createTelegramInboundRouteRuntime<
     dispatchNextQueuedTelegramTurn: deps.dispatchNextQueuedTelegramTurn,
     requestDeferredDispatchNextQueuedTelegramTurn:
       deps.requestDeferredDispatchNextQueuedTelegramTurn,
+    startTypingLoop: deps.startTypingLoop,
+    stopTypingLoop: deps.stopTypingLoop,
     enqueueContinueTurn,
     compact: deps.compact,
     allocateItemOrder: deps.bridgeRuntime.queue.allocateItemOrder,

package/lib/turns.ts

@@ -8,16 +8,16 @@ import { readFile } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
 
 import {
+  appendTelegramReplyContext,
   collectTelegramMessageIds,
-  type DownloadedTelegramMessageFile,
-  type DownloadTelegramMessageFilesDeps,
   downloadTelegramMessageFiles,
   extractTelegramMessagesPromptText,
   extractTelegramMessagesText,
-  appendTelegramReplyContext,
   extractTelegramReplyContextText,
   formatTelegramHistoryText,
   guessMediaType,
+  type DownloadedTelegramMessageFile,
+  type DownloadTelegramMessageFilesDeps,
   type TelegramMediaMessage,
 } from "./media.ts";
 import type {
@@ -27,6 +27,21 @@ import type {
   TelegramQueueStore,
 } from "./queue.ts";
 
+import {
+  computeVoicePromptContribution,
+  computeVoiceTurnFlags,
+  getTelegramVoiceReplyMode,
+  TELEGRAM_VOICE_REPLY_MODES,
+  type TelegramVoiceReplyMode,
+} from "./voice.ts";
+
+// Re-export for backward compatibility with existing namespace imports (e.g. Turns.getTelegramVoiceReplyMode in routing.ts)
+export {
+  getTelegramVoiceReplyMode,
+  TELEGRAM_VOICE_REPLY_MODES,
+  type TelegramVoiceReplyMode,
+};
+
 export const TELEGRAM_PREFIX = "[telegram]";
 
 export interface TelegramTurnMessage {
@@ -36,23 +51,8 @@ export interface TelegramTurnMessage {
 
 export type DownloadedTelegramTurnFile = DownloadedTelegramMessageFile;
 
-export function truncateTelegramQueueSummary(
-  text: string,
-  maxWords = 5,
-  maxLength = 40,
-): string {
-  const normalized = text.replace(/\s+/g, " ").trim();
-  if (!normalized) return "";
-  const words = normalized.split(" ");
-  let summary = words.slice(0, maxWords).join(" ");
-  if (summary.length === 0) summary = normalized;
-  if (summary.length > maxLength) {
-    summary = summary.slice(0, maxLength).trimEnd();
-  }
-  return summary.length < normalized.length || words.length > maxWords
-    ? `${summary}…`
-    : summary;
-}
+import { truncateTelegramQueueSummary } from "./queue.ts";
+export { truncateTelegramQueueSummary };
 
 export function formatTelegramTurnStatusSummary(
   rawText: string,
@@ -103,6 +103,23 @@ function appendTelegramPromptText(prompt: string, rawText: string): string {
   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;
@@ -110,6 +127,7 @@ export function buildTelegramTurnPrompt(options: {
   promptFiles?: DownloadedTelegramTurnFile[];
   handlerOutputs?: string[];
   historyTurns?: Pick<PendingTelegramTurn, "historyText">[];
+  voiceContext?: Record<string, string>;
 }): string {
   let prompt = options.telegramPrefix;
   if ((options.historyTurns?.length ?? 0) > 0) {
@@ -133,6 +151,9 @@ export function buildTelegramTurnPrompt(options: {
     "outputs",
     options.handlerOutputs ?? [],
   );
+  if (options.voiceContext) {
+    prompt = appendTelegramVoiceContext(prompt, options.voiceContext);
+  }
   return prompt;
 }
 
@@ -311,6 +332,9 @@ export interface BuildTelegramPromptTurnOptions {
   handlerOutputs?: string[];
   readBinaryFile: (path: string) => Promise<Uint8Array>;
   inferImageMimeType: (path: string) => string | undefined;
+  voiceReplyMode?: TelegramVoiceReplyMode;
+  voiceReplyModeConfigured?: boolean;
+  voicePromptContribution?: string;
 }
 
 export type BuildTelegramPromptTurnRuntimeOptions = Omit<
@@ -331,6 +355,8 @@ export interface TelegramPromptTurnRuntimeBuilderDeps<
     promptFiles?: DownloadedTelegramTurnFile[];
     handlerOutputs?: string[];
   }>;
+  getVoiceReplyMode?: () => TelegramVoiceReplyMode;
+  isVoiceReplyModeConfigured?: () => boolean;
 }
 
 export function createTelegramPromptTurnRuntimeBuilder<
@@ -358,6 +384,8 @@ export function createTelegramPromptTurnRuntimeBuilder<
       processed.rawText,
       replyContext,
     );
+    // Compute voice mode once and pass it to both the turn builder and the prompt contribution helper
+    const voiceReplyMode = deps.getVoiceReplyMode?.();
     return buildTelegramPromptTurnRuntime({
       telegramPrefix: TELEGRAM_PREFIX,
       messages,
@@ -369,10 +397,26 @@ export function createTelegramPromptTurnRuntimeBuilder<
       promptFiles: processed.promptFiles,
       handlerOutputs: processed.handlerOutputs,
       inferImageMimeType: guessMediaType,
+      voiceReplyMode,
+      voiceReplyModeConfigured: deps.isVoiceReplyModeConfigured?.(),
+      voicePromptContribution: computeVoicePromptContribution(
+        voiceReplyMode,
+        files,
+        rawText,
+      ),
     });
   };
 }
 
+function getTelegramVoicePromptContext(
+  voiceReplyMode: TelegramVoiceReplyMode,
+  hasVoiceFile: boolean,
+): Record<string, string> | undefined {
+  if (voiceReplyMode === "always") return { "reply mode": "always" };
+  if (!hasVoiceFile) return undefined;
+  return { "reply mode": voiceReplyMode };
+}
+
 export async function buildTelegramPromptTurn(
   options: BuildTelegramPromptTurnOptions,
 ): Promise<PendingTelegramTurn> {
@@ -380,6 +424,12 @@ export async function buildTelegramPromptTurn(
   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 showVoiceContext =
+    options.voiceReplyModeConfigured ?? options.voiceReplyMode !== undefined;
   const content: TelegramPromptContent[] = [
     {
       type: "text",
@@ -390,6 +440,9 @@ export async function buildTelegramPromptTurn(
         promptFiles: options.promptFiles,
         handlerOutputs: options.handlerOutputs,
         historyTurns: options.historyTurns,
+        voiceContext: showVoiceContext
+          ? getTelegramVoicePromptContext(voiceReplyMode, hasVoiceFile)
+          : undefined,
       }),
     },
   ];
@@ -404,6 +457,15 @@ export async function buildTelegramPromptTurn(
       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()}`;
+    }
+  }
+
   return {
     kind: "prompt",
     chatId: firstMessage.chat.id,
@@ -424,6 +486,8 @@ export async function buildTelegramPromptTurn(
       options.promptFiles ?? options.files,
       options.handlerOutputs,
     ),
+    // Voice tagging (used for preview suppression and prompt guidance)
+    ...computeVoiceTurnFlags(voiceReplyMode, hasVoiceFile),
   };
 }