@llblab/pi-telegram 0.10.7 → 0.11.0

package/docs/voice.md

@@ -0,0 +1,210 @@
+# Voice Integration
+
+Voice messages flow through an **inbound transcription → outbound voice reply** pipeline. This document describes the bridge's role in that pipeline; provider-specific mechanics (TTS/STT backends, voice IDs, languages) are owned by voice provider extensions. In `0.11.0`, this is a first-class extension surface: one companion extension can provide STT fallbacks for inbound voice/audio files and TTS fallbacks for outbound Telegram voice replies without owning a second bot poller.
+
+## Overview
+
+1. **Inbound:** A voice message arrives via Telegram. Inbound handlers transcribe it to text.
+2. **Processing:** The transcription becomes the agent prompt. The bridge tags the turn if it originated from voice.
+3. **Outbound:** If voice replies are enabled, the agent's text response is converted to voice and sent back. No text draft appears in Telegram during generation.
+
+The bridge owns Telegram transport, queue integration, reply-mode policy, preview suppression, fallback text delivery, and Settings UI. Provider extensions own STT/TTS calls, speech rewriting, provider-specific menus, transcript preference, and OGG/Opus conversion.
+
+## Voice Detection
+
+Voice messages arrive as `message.voice` in Telegram updates. The bridge's media processing detects these and sets `kind: "voice"` on the downloaded file. Regular audio files (`message.audio`) get `kind: "audio"`; `mirror` mode treats both voice notes and audio uploads as voice input for reply-policy tagging.
+
+Inbound handlers match `kind: "voice"` or `mime: "audio/*"` to run a transcription command:
+
+```json
+{
+  "inboundHandlers": [
+    {
+      "mime": "audio/*",
+      "template": ["/path/to/stt", "--file={file}", "--mime={mime}"]
+    }
+  ]
+}
+```
+
+The transcription output becomes the raw text of the prompt.
+
+Voice provider extensions can also register STT backends with `registerTelegramVoiceTranscriptionProvider()` from `@llblab/pi-telegram/lib/voice.ts`. Inbound command-template handlers and programmatic inbound handlers remain the stronger generic paths and run first; if no matching handler produces output for a voice/audio file, registered transcription providers are tried as fallback in registration order. The first provider that returns non-empty text wins; providers that return `undefined` pass to the next provider, and provider failures are recorded before trying the next provider. This lets a full voice extension provide both TTS and STT without requiring `telegram.json` handler templates, while still preserving operator-configured inbound handlers as the stronger choice.
+
+## Voice Reply Policy
+
+The bridge decides **when** to reply with voice from `voice.replyMode` in `TelegramConfig` (stored in `telegram.json`). If config does not set a valid mode, the bridge uses the `hidden` default: manual behavior without adding voice policy text to the prompt context.
+
+### Modes
+
+- **`hidden` (default):** no `voice.replyMode` is stored; same behavior as manual, no prompt voice context.
+- **`manual`:** only reply with voice when the agent authors `<!-- telegram_voice -->` markup; explicit prompt context is added.
+- **`mirror`:** reply with voice when the inbound message was a voice note or audio file. Text input stays on the manual path where explicit `telegram_voice` markup still works.
+- **`always`:** always reply with voice.
+
+**Warning:** In `always` mode, the bridge transparently intercepts ALL text replies and converts them to voice on success. Users will only receive voice messages when voice generation succeeds. If voice generation fails, the bridge falls back to sending the planned text reply.
+
+When a message is received, the bridge resolves the active voice reply mode and tags the turn:
+
+- `voiceReplyPreferred`: `true` when mode is `mirror` and the turn has a voice file
+- `voiceReplyRequired`: `true` when mode is `always`
+
+At `agent_end`, if the turn is voice-tagged and the agent response has no explicit `telegram_voice` markup, the bridge transparently intercepts the text reply and converts it to voice. If the agent uses multiple `telegram_voice` blocks, each becomes a separate voice message. The same reply-mode decision applies to both registered voice synthesis providers and configured outbound voice handlers.
+
+### Preview Suppression
+
+When a turn is voice-tagged, the bridge suppresses text preview streaming during LLM generation. This prevents draft text from appearing in Telegram before the voice message is delivered.
+
+## Voice Provider Extension Surface
+
+A voice extension may combine three public seams:
+
+- `registerTelegramVoiceTranscriptionProvider()` for inbound STT fallback on voice/audio files
+- `registerTelegramVoiceSynthesisProvider()` for outbound TTS/synthesis fallback to Telegram voice messages
+- `registerTelegramSection()` for provider-specific Telegram UI such as voice, language, style, transcript, or provider on/off controls
+
+The reply policy itself remains a built-in pi-telegram setting (`voice.replyMode`) rather than a provider-owned menu.
+
+## Outbound Voice Synthesis Provider Registration
+
+Voice synthesis provider extensions (such as `pi-xai-voice`) register themselves through `registerTelegramVoiceSynthesisProvider()`. The bridge only provides the registration seam and the actual delivery to Telegram. **The provider is fully responsible for**:
+
+- Text optimisation / speech-style rewriting
+- Adding speech tags (when desired)
+- Running TTS + ffmpeg conversion to OGG/Opus
+- Deciding whether to return `transcriptText` at all (based on the user's "Send Transcript" toggle)
+- `transcriptText` (when returned) is attached by the bridge as the voice message **caption** only. Separate transcript messages are no longer sent.
+
+The bridge shows a `record_voice` action while delivering and sends the final audio with Telegram `sendVoice`. When a provider returns `transcriptText`, the bridge attaches it as the voice caption.
+
+Providers can implement `getVoicePromptContribution(view)` to inject voice-specific instructions into voice-tagged prompts (for example: "Reply only with the spoken text"). The bridge appends the first non-empty provider contribution when `mirror` or `always` mode tags the turn.
+
+See the TSDoc on `registerTelegramVoiceSynthesisProvider` and `TelegramVoiceSynthesisProviderResult` in `lib/voice.ts` for the exact interface.
+
+The provider receives the raw agent text plus optional `{ lang?, rate? }`.
+
+It must return one of:
+
+- `string` — path to a ready `.ogg` or `.opus` file
+- `{ audioPath: string, transcriptText?: string }` — `audioPath` must be OGG/Opus. When `transcriptText` is present it is attached as the voice message **caption**. A provider UI can expose a "Send Transcript" toggle by returning `transcriptText` only when that toggle is enabled.
+- `undefined` — skip this text block
+
+**Important:** Providers are fully responsible for producing a clean, TTS-optimised native voice file. The bridge may also run configured outbound voice command templates for users who prefer process-boundary handlers instead of provider extensions.
+
+**File format:** Telegram `sendVoice` requires **OGG/Opus** to display the message as a native voice note (waveform, inline playback). MP3 and other formats are accepted by the API but render as regular audio attachments (music note icon, filename visible). **Providers and outbound voice handlers must return `.ogg` or `.opus` files.** Returning non-OGG files causes the bridge to throw and fall back to text delivery.
+
+Registration returns a disposer function for cleanup. Extensions should call it on shutdown or re-register safely on session start when their runtime is recreated.
+
+## Outbound Voice Handlers
+
+Users can also configure `outboundHandlers` with `type: "voice"` in `telegram.json`. This is the command-template path for TTS without a provider extension. Reply modes (`manual`, `mirror`, `always`) affect these handlers the same way they affect providers: explicit `telegram_voice` blocks and automatic mirror/always interception both produce a voice reply plan, then delivery tries configured outbound voice handlers first and registered synthesis providers as progressive fallbacks.
+
+Voice handlers receive the text on stdin in composed pipelines and can use `{text}`, `{lang}`, `{rate}`, `{mp3}`, and `{ogg}` placeholders. Set `output` to `"ogg"` or another placeholder name when the template writes to a known path:
+
+```json
+{
+  "voice": { "replyMode": "mirror" },
+  "outboundHandlers": [
+    {
+      "type": "voice",
+      "template": [
+        "/path/to/tts --write-media {mp3}",
+        "ffmpeg -y -i {mp3} -c:a libopus -b:a 32k -ar 16000 -ac 1 {ogg}"
+      ],
+      "output": "ogg"
+    }
+  ]
+}
+```
+
+Priority for outbound voice delivery is: configured `outboundHandlers` with `type: "voice"` in their `telegram.json` order, then programmatic `voice` outbound handlers, then registered voice synthesis providers. Provider extensions are the zero-config tail of the same pipeline: they handle voice when no explicit configured handler succeeds, but they do not override operator-configured handlers. If multiple providers are registered, only one handles a given voice reply: the first provider that returns a valid `.ogg`/`.opus` artifact wins. Providers that return `undefined` explicitly pass to the next provider; providers that throw or return invalid output are recorded and the next fallback is tried.
+
+### Provider with transcript caption (controlled by user toggle)
+
+When the user's "Send Transcript" toggle is ON, return the clean spoken text as `transcriptText`. The bridge attaches it as the caption on the voice message. When the toggle is OFF, return only the audio path (no `transcriptText`).
+
+```typescript
+import { registerTelegramVoiceSynthesisProvider } from "@llblab/pi-telegram/lib/voice.ts";
+
+registerTelegramVoiceSynthesisProvider(async (text, options) => {
+  const rewritten = rewriteWithSpeechTags(text);
+  const audioPath = await myTTS(rewritten, { language: options?.lang });
+  const sendTranscript = getUserSendTranscriptPreference(); // from your UI + telegram.json
+  return sendTranscript ? { audioPath, transcriptText: text } : { audioPath };
+});
+```
+
+The bridge never sends a separate transcript message. Caption-only is the "ON" behavior.
+
+### Surfacing provider diagnostics
+
+Voice provider extensions can record runtime events that appear in `/telegram-status` alongside pi-telegram's own events:
+
+```typescript
+import { recordTelegramRuntimeEvent } from "@llblab/pi-telegram/lib/outbound-handlers.ts";
+
+recordTelegramRuntimeEvent("xai-voice", new Error("TTS failed"), {
+  phase: "tts",
+  text: text.slice(0, 50),
+});
+```
+
+`recordTelegramRuntimeEvent` writes to the same event ring that pi-telegram uses. Events are visible via `/telegram-status` in Telegram. Calls are silently dropped if pi-telegram is not loaded.
+
+## Voice Extension Section
+
+Voice provider extensions can register a Voice Extension Section (settings UI) via `registerTelegramSection`. The section can expose provider-specific controls such as TTS voice, language, speech style, transcript behavior, or STT/TTS enablement. Reply mode is a core pi-telegram setting and belongs in the built-in Settings menu.
+
+**Note on resume:** Because the previous automatic persistent re-registration system has been removed, extensions are responsible for re-registering their Voice Extension Section on `session_start` if they want the menu to survive a `pi resume`. See `registerTelegramSection` in `lib/extension-sections.ts`.
+
+## Prompt Guidance
+
+The bridge keeps voice prompt context compact and policy-owned. It adds `[voice] reply mode: ...` only when `telegram.json` explicitly contains a valid `voice.replyMode`. `hidden`/no configured mode behaves like manual, but prompts stay silent. When explicit, voice-originated `manual` turns add `[voice] reply mode: manual`, voice-originated `mirror` turns add `[voice] reply mode: mirror`, and `always` mode adds `[voice] reply mode: always` for every turn. If voice context later contains multiple fields, the bridge renders it as a `[voice]` list. The marker is appended after `[outputs]` when handler output exists, otherwise after `[attachments]`. Voice inputs also appear in `[attachments]` with their downloaded file names, MIME data, and handler output, so agents can infer concrete voice-file context from attachment metadata.
+
+Voice synthesis providers can supply prompt guidance through `getVoicePromptContribution(view)`, but provider text should stay optional and provider-specific. Reply-mode context belongs to pi-telegram.
+
+## Fallback Behavior
+
+### If voice generation fails
+
+1. The bridge records the failure via `recordRuntimeEvent`
+2. The voice sender throws an error, which the runtime catches
+3. The runtime falls back to sending the planned text reply (outbound markup stripped, `replyMarkup` preserved)
+
+### If no voice synthesis provider is registered
+
+- The voice sender throws because no configured handler or synthesis provider can deliver the voice reply
+- The runtime catches the error and falls back to text delivery
+
+### If the provider returns a non-OGG file
+
+- `ensureTelegramVoiceFileFormat` rejects the file (only `.ogg` and `.opus` are accepted)
+- The voice sender throws and the runtime falls back to text delivery
+- The provider should handle format conversion internally before returning the path
+
+## Telegram Voice Limits
+
+- **Duration:** Up to ~60 minutes per voice message
+- **File size:** Up to 20 MB for voice uploads via `sendVoice`
+- **Format:** OGG Opus is native; MP3 and other formats render as regular audio attachments
+- **Splitting:** The bridge does not split long responses into multiple voice messages. Chunking is the provider's responsibility
+
+## Configuration
+
+### Bridge config (`telegram.json`)
+
+```json
+{
+  "voice": {
+    "replyMode": "manual"
+  }
+}
+```
+
+Valid stored values: `"manual"`, `"mirror"`, `"always"`. Missing or invalid values are shown in Settings as `hidden`, behave like manual, and stay silent in prompt context.
+
+The bridge reads `voice.replyMode` from the config when building a turn.
+
+### Provider config
+
+Provider-specific settings (voice ID, language, speech style, transcript behavior, STT/TTS enablement) are owned by the voice provider extension. Reply mode is owned by pi-telegram's `voice.replyMode` and configured from the built-in pi-telegram Settings menu, not duplicated in provider UIs.

package/index.ts

@@ -11,6 +11,7 @@ import * as Config from "./lib/config.ts";
 import {
   createTelegramExtensionSectionRegistry,
   setGlobalTelegramSectionRegistry,
+  registerTelegramSection,
   type TelegramSectionRegistry,
 } from "./lib/extension-sections.ts";
 import { createTelegramExternalHandleUpdate } from "./lib/external-handlers.ts";
@@ -37,10 +38,49 @@ import * as Runtime from "./lib/runtime.ts";
 import * as Setup from "./lib/setup.ts";
 import * as Status from "./lib/status.ts";
 import * as TextGroups from "./lib/text-groups.ts";
+import * as Voice from "./lib/voice.ts";
+
+const VOICE_EVENT_RECORDER_KEY = "__piTelegramVoiceEventRecorder__";
 
 type ActivePiModel = NonNullable<Pi.ExtensionContext["model"]>;
 type RuntimeTelegramQueueItem = Queue.TelegramQueueItem<Pi.ExtensionContext>;
 
+export {
+  registerTelegramOutboundHandler,
+  hasTelegramOutboundHandler,
+  getTelegramOutboundProgrammaticHandlers,
+  recordTelegramRuntimeEvent,
+} from "./lib/outbound-handlers.ts";
+
+// --- Voice Integration Exports ---
+// Prefer domain imports from ./lib/voice.ts; root exports stay for compatibility.
+export {
+  registerTelegramVoiceSynthesisProvider,
+  getTelegramVoiceSynthesisProviders,
+  hasTelegramVoiceSynthesisProvider,
+  clearTelegramVoiceSynthesisProviders,
+  planTelegramVoiceReply,
+  getTelegramVoiceReplyMode,
+  computeVoiceTurnFlags,
+  isVoiceTurn,
+  shouldSuppressPreviewForVoice,
+  computeVoicePromptContribution,
+  type TelegramVoiceSynthesisProvider,
+  type TelegramVoiceTurnView,
+  type TelegramVoiceSynthesisProviderResult,
+  type TelegramVoiceReplyMode,
+} from "./lib/voice.ts";
+
+// --- Extension Section Exports ---
+export {
+  registerTelegramSection,
+  type TelegramSectionRegistration,
+  type TelegramSectionContext,
+  type TelegramSectionCallbackContext,
+  type TelegramSectionView,
+  type TelegramSectionSettingsRegistration,
+} from "./lib/extension-sections.ts";
+
 // --- Extension Runtime ---
 
 export default function (pi: Pi.ExtensionAPI) {
@@ -55,10 +95,24 @@ export default function (pi: Pi.ExtensionAPI) {
   const bridgeRuntime = Runtime.createTelegramBridgeRuntime();
   const { abort, lifecycle, queue, setup, typing } = bridgeRuntime;
   const configStore = Config.createTelegramConfigStore();
+  Config.setGlobalTelegramConfigRuntime({
+    updateVoiceConfig(voice) {
+      const current = configStore.get();
+      const next = { ...current, voice: { ...(current.voice ?? {}), ...voice } };
+      configStore.set(next);
+      void configStore.persist(next);
+    },
+  });
   const isProactivePushEnabled =
     Config.createTelegramProactivePushChecker(configStore);
   const setProactivePushEnabled =
     Config.createTelegramProactivePushSetter(configStore);
+  const getVoiceReplyMode =
+    Config.createTelegramVoiceReplyModeGetter(configStore);
+  const isVoiceReplyModeConfigured =
+    Config.createTelegramVoiceReplyModeConfiguredChecker(configStore);
+  const setVoiceReplyMode =
+    Config.createTelegramVoiceReplyModeSetter(configStore);
   const lockRuntime = Locks.createTelegramLockRuntime<Pi.ExtensionContext>();
   const lockOwnershipGuard =
     Locks.createTelegramLockOwnershipGuard(lockRuntime);
@@ -77,10 +131,15 @@ export default function (pi: Pi.ExtensionAPI) {
   const sectionRegistry: TelegramSectionRegistry =
     createTelegramExtensionSectionRegistry();
   setGlobalTelegramSectionRegistry(sectionRegistry);
+
+
   const runtimeEvents = Status.createTelegramRuntimeEventRecorder({
     getBotToken: configStore.getBotToken,
   });
   const recordRuntimeEvent = runtimeEvents.record;
+  (globalThis as Record<string, unknown>)[
+    VOICE_EVENT_RECORDER_KEY
+  ] = recordRuntimeEvent;
   const getContextModel = Pi.getExtensionContextModel;
   const isIdle = Pi.isExtensionContextIdle;
   const hasPendingMessages = Pi.hasExtensionContextPendingMessages;
@@ -151,6 +210,8 @@ export default function (pi: Pi.ExtensionAPI) {
     getUpdates,
     setMyCommands,
     sendTypingAction,
+    sendChatAction,
+    sendRecordVoiceAction,
     sendMessageDraft,
     sendMessage,
     downloadFile: downloadTelegramBridgeFile,
@@ -287,6 +348,12 @@ export default function (pi: Pi.ExtensionAPI) {
     editInteractiveMessage,
     sendInteractiveMessage,
     sectionRegistry,
+
+    // Used by the menu/status system to know whether the current turn is a voice reply
+    isVoiceReplyActive: function () {
+      const turn = activeTurnRuntime.get();
+      return Voice.isVoiceTurn(turn);
+    },
   });
 
   // --- Queue Menu ---
@@ -317,7 +384,10 @@ export default function (pi: Pi.ExtensionAPI) {
       sendInteractiveMessage,
       answerCallbackQuery,
       isProactivePushEnabled,
+      getVoiceReplyMode,
+      isVoiceReplyModeConfigured,
       setProactivePushEnabled,
+      setVoiceReplyMode,
     },
     sectionRegistry,
   );
@@ -354,6 +424,8 @@ export default function (pi: Pi.ExtensionAPI) {
     dispatchNextQueuedTelegramTurn,
     requestDeferredDispatchNextQueuedTelegramTurn:
       deferredQueueDispatchRuntime.request,
+    startTypingLoop: promptDispatchRuntime.startTypingLoop,
+    stopTypingLoop: typing.stop,
     answerCallbackQuery,
     editInteractiveMessage,
     sendInteractiveMessage,
@@ -431,7 +503,9 @@ export default function (pi: Pi.ExtensionAPI) {
   });
   const sessionLifecycleRuntime = Lifecycle.appendTelegramLifecycleHooks(
     queueSessionLifecycle,
-    { onSessionStart: lockedPollingRuntime.onSessionStart },
+    {
+      onSessionStart: lockedPollingRuntime.onSessionStart,
+    },
   );
 
   // --- Extension API Bindings ---
@@ -483,6 +557,8 @@ export default function (pi: Pi.ExtensionAPI) {
       execCommand: CommandTemplates.execCommandTemplate,
       sendMultipart: callMultipart,
       sendTextReply,
+      sendChatAction,
+      sendRecordVoiceAction,
       getHandlers: configStore.getOutboundHandlers,
       recordRuntimeEvent,
     });

package/lib/api.ts

@@ -1,7 +1,9 @@
 /**
  * Telegram API transport helpers
  * Zones: telegram transport, filesystem, runtime diagnostics
- * Wraps bot API calls, file downloads, runtime transport binding, and Telegram temp-file cleanup
+ *
+ * Wraps bot API calls, file uploads/downloads (including voice messages),
+ * multipart sending, runtime transport binding, and Telegram temp-file lifecycle.
  */
 
 import { randomUUID } from "node:crypto";
@@ -298,8 +300,9 @@ export interface TelegramBridgeApiRuntime {
   setMyCommands: (
     commands: readonly { command: string; description: string }[],
   ) => Promise<boolean>;
-  sendChatAction: (chatId: number, action: "typing") => Promise<boolean>;
+  sendChatAction: (chatId: number, action: string) => Promise<boolean>;
   sendTypingAction: (chatId: number) => Promise<unknown>;
+  sendRecordVoiceAction: (chatId: number) => Promise<unknown>;
   sendMessageDraft: (
     chatId: number,
     draftId: number,
@@ -577,6 +580,12 @@ export async function fetchTelegramBotIdentity(
   return response.json() as Promise<TelegramBotIdentityResponse>;
 }
 
+/**
+ * Low-level helper to send a multipart/form-data request to the Telegram Bot API.
+ * This is the core implementation used for uploading voice messages, photos,
+ * documents, animations, etc. It handles FormData construction, retry logic
+ * (via callTelegramWithRetry), and error recording under the "multipart" category.
+ */
 export async function callTelegramMultipart<TResponse>(
   botToken: string | undefined,
   method: string,
@@ -721,6 +730,12 @@ export function createTelegramBridgeApiRuntime(
   };
   return {
     call: callRecorded,
+
+    /**
+     * Sends a multipart/form-data request (used for sending voice messages,
+     * photos, documents, animations, etc.).
+     * Errors are recorded under the "multipart" category for diagnostics.
+     */
     callMultipart: async (
       method,
       fields,
@@ -743,6 +758,11 @@ export function createTelegramBridgeApiRuntime(
         throw error;
       }
     },
+
+    /**
+     * Downloads a file from the Telegram servers into the local temp directory.
+     * Used for inbound voice messages, photos, documents, etc.
+     */
     downloadFile: async (fileId, suggestedName) => {
       try {
         return await deps.client.downloadFile(
@@ -781,6 +801,14 @@ export function createTelegramBridgeApiRuntime(
         }),
       "typing",
     ),
+    sendRecordVoiceAction: createTelegramChatActionSender(
+      (chatId, action) =>
+        callRecorded<boolean>("sendChatAction", {
+          chat_id: chatId,
+          action,
+        }),
+      "record_voice",
+    ),
     sendMessageDraft: (chatId, draftId, text, options) => {
       const body: Record<string, unknown> = {
         chat_id: chatId,
@@ -841,6 +869,11 @@ export function createTelegramBridgeApiRuntime(
   };
 }
 
+/**
+ * Creates a low-level Telegram Bot API client.
+ * This is the main entry point for all direct Bot API communication
+ * (both JSON calls and multipart uploads for files/voice).
+ */
 export function createTelegramApiClient(
   getBotToken: () => string | undefined,
 ): TelegramApiClient {

package/lib/commands.ts

@@ -320,6 +320,8 @@ export interface TelegramCompactCommandDeps extends TelegramRuntimeEventRecorder
   requestDeferredDispatchNextQueuedTelegramTurn?: (
     dispatch: () => void,
   ) => void;
+  startTypingLoop?: () => void;
+  stopTypingLoop?: () => void;
   compact: (callbacks: {
     onComplete: () => void;
     onError: (error: unknown) => void;
@@ -553,6 +555,8 @@ export interface TelegramCommandRuntimeDeps<
   requestDeferredDispatchNextQueuedTelegramTurn?: (
     dispatch: (ctx: TContext) => void,
   ) => void;
+  startTypingLoop?: (ctx: TContext, chatId?: number) => void;
+  stopTypingLoop?: () => void;
   enqueueContinueTurn: (message: TMessage, ctx: TContext) => Promise<void>;
   compact: (
     ctx: TContext,
@@ -798,15 +802,20 @@ export async function handleTelegramCompactCommand(
   }
   deps.setCompactionInProgress(true);
   deps.updateStatus();
+  let compactionStillInProgress = true;
   try {
     deps.compact({
       onComplete: () => {
+        compactionStillInProgress = false;
+        deps.stopTypingLoop?.();
         deps.setCompactionInProgress(false);
         deps.updateStatus();
         dispatchNextQueuedTelegramTurnAfterCompact(deps);
         void deps.sendTextReply("Compaction completed.");
       },
       onError: (error) => {
+        compactionStillInProgress = false;
+        deps.stopTypingLoop?.();
         deps.setCompactionInProgress(false);
         deps.updateStatus();
         dispatchNextQueuedTelegramTurnAfterCompact(deps);
@@ -816,6 +825,8 @@ export async function handleTelegramCompactCommand(
       },
     });
   } catch (error) {
+    compactionStillInProgress = false;
+    deps.stopTypingLoop?.();
     deps.setCompactionInProgress(false);
     deps.updateStatus();
     deps.recordRuntimeEvent?.("compact", error);
@@ -824,6 +835,7 @@ export async function handleTelegramCompactCommand(
     return;
   }
   await deps.sendTextReply("Compaction started.");
+  if (compactionStillInProgress) deps.startTypingLoop?.();
 }
 
 function isTelegramStaleContextError(error: unknown): boolean {
@@ -962,6 +974,8 @@ export function createTelegramCommandHandlerTargetRuntime<
     setCompactionInProgress: deps.setCompactionInProgress,
     updateStatus: deps.updateStatus,
     dispatchNextQueuedTelegramTurn: deps.dispatchNextQueuedTelegramTurn,
+    startTypingLoop: deps.startTypingLoop,
+    stopTypingLoop: deps.stopTypingLoop,
     enqueueContinueTurn: deps.enqueueContinueTurn,
     compact: deps.compact,
     enqueueControlItem: commandTargetRuntime.enqueueControlItem,
@@ -1115,6 +1129,10 @@ async function handleTelegramCommandRuntime<
                   )
               : undefined,
           compact: (callbacks) => deps.compact(commandCtx, callbacks),
+          startTypingLoop: deps.startTypingLoop
+            ? () => deps.startTypingLoop?.(commandCtx, nextMessage.chat.id)
+            : undefined,
+          stopTypingLoop: deps.stopTypingLoop,
           sendTextReply: sendReplyFor(nextMessage),
           recordRuntimeEvent: deps.recordRuntimeEvent,
         });

package/lib/config.ts

@@ -12,6 +12,8 @@ import { join, resolve } from "node:path";
 import type { TelegramInboundHandlerConfig } from "./inbound-handlers.ts";
 import type { CommandTemplateObjectConfig } from "./command-templates.ts";
 
+const CONFIG_RUNTIME_KEY = "__piTelegramConfigRuntime__";
+
 function getAgentDir(): string {
   return process.env.PI_CODING_AGENT_DIR
     ? resolve(process.env.PI_CODING_AGENT_DIR)
@@ -43,6 +45,11 @@ export interface TelegramConfig {
   attachmentHandlers?: TelegramInboundHandlerConfig[];
   outboundHandlers?: TelegramOutboundHandlerConfig[];
   proactivePush?: boolean;
+  voice?: {
+    replyMode?: "manual" | "mirror" | "always";
+    /** Whether to attach the provider's transcriptText as caption on voice messages */
+    sendTranscript?: boolean;
+  };
 }
 
 export interface TelegramConfigStore {
@@ -66,6 +73,29 @@ export interface TelegramConfigStoreOptions {
   configPath?: string;
 }
 
+export interface TelegramConfigRuntime {
+  updateVoiceConfig: (voice: NonNullable<TelegramConfig["voice"]>) => void;
+}
+
+export function setGlobalTelegramConfigRuntime(
+  runtime: TelegramConfigRuntime | undefined,
+): void {
+  const globals = globalThis as Record<string, unknown>;
+  if (runtime) globals[CONFIG_RUNTIME_KEY] = runtime;
+  else delete globals[CONFIG_RUNTIME_KEY];
+}
+
+export function updateTelegramVoiceConfig(
+  voice: NonNullable<TelegramConfig["voice"]>,
+): boolean {
+  const runtime = (globalThis as Record<string, unknown>)[
+    CONFIG_RUNTIME_KEY
+  ] as TelegramConfigRuntime | undefined;
+  if (!runtime || typeof runtime.updateVoiceConfig !== "function") return false;
+  runtime.updateVoiceConfig(voice);
+  return true;
+}
+
 export async function readTelegramConfig(
   configPath: string,
 ): Promise<TelegramConfig> {
@@ -141,6 +171,46 @@ export function createTelegramProactivePushSetter(
   };
 }
 
+export function createTelegramVoiceReplyModeGetter(
+  configStore: Pick<TelegramConfigStore, "get">,
+): () => "manual" | "mirror" | "always" {
+  return () => {
+    const mode = configStore.get().voice?.replyMode;
+    return mode === "mirror" || mode === "always" || mode === "manual"
+      ? mode
+      : "manual";
+  };
+}
+
+export function createTelegramVoiceReplyModeConfiguredChecker(
+  configStore: Pick<TelegramConfigStore, "get">,
+): () => boolean {
+  return () => {
+    const mode = configStore.get().voice?.replyMode;
+    return mode === "mirror" || mode === "always" || mode === "manual";
+  };
+}
+
+export function createTelegramVoiceReplyModeSetter(
+  configStore: Pick<TelegramConfigStore, "get" | "set" | "persist">,
+): (replyMode: "manual" | "mirror" | "always" | undefined) => Promise<void> {
+  return async (replyMode) => {
+    const current = configStore.get();
+    if (replyMode === undefined) {
+      const { replyMode: _replyMode, ...remainingVoice } = current.voice ?? {};
+      const next = { ...current };
+      if (Object.keys(remainingVoice).length > 0) next.voice = remainingVoice;
+      else delete next.voice;
+      configStore.set(next);
+      await configStore.persist(next);
+      return;
+    }
+    const next = { ...current, voice: { ...(current.voice ?? {}), replyMode } };
+    configStore.set(next);
+    await configStore.persist(next);
+  };
+}
+
 export function createTelegramProactivePushChatIdGetter(deps: {
   getActiveTurnChatId: () => number | undefined;
   getAllowedUserId: () => number | undefined;