@llblab/pi-telegram 0.37.2 → 0.38.0

package/BACKLOG.md

@@ -2,6 +2,7 @@
 
 _This file owns unresolved project work only. Completed behavior belongs in `CHANGELOG.md`; durable contracts belong in `AGENTS.md` and `/docs`._
 
+- [ ] `Coherent voice reply policy`: Release the validated `manual`, `mirror`, and `always` policy cleanup as `0.38.0`, then reconcile issue #235 and open exact migration issues for `johnlam1968/pi-voice-telegram` and `luxus/pi-xai-voice`, whose TTS providers still consume the removed transcript-caption API.
 - [ ] `Operator-confirmed pairing`: Replace first-contact automatic ownership with an explicit pending request that the trusted Pi interface can allow or reject before `allowedUserId` is persisted or any Telegram prompt executes; retain manual preconfiguration, bound pending-request lifetime and multiplicity, fail closed across session/transport replacement, and cover unauthorized-first-contact races.
 - [ ] `Environment-backed bot tokens`: Let each profile store an exact Pi-native `$ENV_VAR` or `${ENV_VAR}` reference in `telegram.json` instead of copying the resolved secret; preserve the originating alias when `/telegram-setup` prefills from a supported environment variable, resolve only at validation/activation boundaries, fail closed with a redacted named-variable diagnostic when unresolved, retain literal-token compatibility, and cover named profiles, reload, persistence, status, and secret-redaction paths.
 - [ ] [`Inference bypass Generative Apps`](./docs/generative-apps.md): Let the agent install and bind one managed JavaScript app owner for a generated-prompt prefix so deterministic controls can bypass model inference without creating another button grammar.

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## 0.38.0: Coherent Voice Reply Policy
+
+- `Voice Reply Policy`: Renames the default user-facing `hidden` mode to `manual` while retaining `hidden` as a read-only configuration and callback compatibility alias. `manual`, `mirror`, and `always` remain the complete policy set: explicit `telegram_voice`, modality mirroring, or automatic voice replacement.
+- `Voice Provider Contract`: Removes the redundant `voice.sendTranscript` configuration, `getTelegramVoiceSendTranscript()` public helper, provider-returned `transcriptText`, and voice-caption path. Synthesis providers now return only an OGG/Opus path or `undefined`; text-plus-voice remains an explicit agent composition rather than a parallel automatic policy.
+
 ## 0.37.2: Follower Recovery Delivery Hotfix
 
 - `Follower Recovery Delivery`: Holds follower Bot API calls behind a bounded registration wait when heartbeat recovery temporarily clears local authority, then sends once with the restored exact generation. Calls still fail closed if registration is not restored, and acknowledgement ambiguity remains non-retryable.

package/README.md

@@ -130,7 +130,7 @@ Enable the optional capabilities the bridge needs in the [@BotFather](https://t.
 | Inbound files | Download inbound files to the Pi agent temp directory with size limits. | Screenshots, PDFs, datasets, and artifacts enter Pi as inspectable local files. |
 | Outbound artifacts | Return generated files through `telegram_attach` during active turns or explicit direct delivery. | Agents send real artifacts as files, not pasted blobs. |
 | Voice input | Route audio through configured command-template handlers, programmatic handlers, or STT providers. | Voice notes become usable prompt context. |
-| Voice output | Choose `hidden`, `mirror`, or `always`; active automatic turns carry one compact `[voice] delivery: automatic voice` line, while explicit `telegram_voice` remains available. | Voice policy stays dynamic and model-legible without duplicating the full action contract in every prompt. |
+| Voice output | Choose `manual`, `mirror`, or `always`; active automatic turns carry one compact `[voice] delivery: automatic voice` line, while explicit `telegram_voice` remains available. | Voice policy stays dynamic and model-legible without duplicating the full action contract in every prompt. |
 | Buttons | Turn top-level `telegram_button` comments into inline buttons. | Assistant-authored choices become native Telegram interactions. |
 | Generative Apps | Install or explicitly replace a reviewed `.mjs` application whose generated JSON button view may mix direct `app::method` actions with ordinary model prompts. | Repeated games, controls, tutors, and adapters compile routine interaction without losing selective model interpretation, explanation, or adaptation. |
 | Callback routing | Route known callbacks to the owner extension and unknown callbacks back into Pi. | Companion extensions can build UI without polling Telegram themselves. |
@@ -218,7 +218,7 @@ Inbound files land under `<agent-dir>/tmp/telegram` and default to a 50 MiB limi
 
 ### Voice And Media
 
-Voice notes, audio, images, PDFs, and other media can pass through configured inbound handlers, programmatic handlers, or registered STT providers. Outbound voice can use configured `outboundHandlers` or registered TTS providers; `pi-telegram` owns reply policy and Telegram transport, while providers own synthesis. Configure provider-neutral local/API pipelines and ordered fallbacks through [`telegram.json` command templates](./docs/voice.md#choose-an-integration-path). The default `hidden` reply mode still supports intentional voice delivery through explicit `telegram_voice` actions; `mirror` and `always` add automatic voice policy. Explicit actions accept either a JSON object or compact double-quoted attributes, with equivalent `text` and `value` payload keys and one colon-free action marker.
+Voice notes, audio, images, PDFs, and other media can pass through configured inbound handlers, programmatic handlers, or registered STT providers. Outbound voice can use configured `outboundHandlers` or registered TTS providers; `pi-telegram` owns reply policy and Telegram transport, while providers own synthesis. Configure provider-neutral local/API pipelines and ordered fallbacks through [`telegram.json` command templates](./docs/voice.md#choose-an-integration-path). The default `manual` reply mode still supports intentional voice delivery through explicit `telegram_voice` actions; `mirror` and `always` add automatic voice policy. Explicit actions accept either a JSON object or compact double-quoted attributes, with equivalent `text` and `value` payload keys and one colon-free action marker.
 
 ### Buttons And Callbacks
 

package/api/voice.ts

@@ -9,7 +9,6 @@ export {
   computeVoicePromptContribution,
   computeVoiceTurnFlags,
   getTelegramVoiceReplyMode,
-  getTelegramVoiceSendTranscript,
   isVoiceTurn,
   registerTelegramVoiceSynthesisProvider,
   registerTelegramVoiceTranscriptionProvider,

package/docs/multi-instance-bus.md

@@ -314,7 +314,7 @@ Every outbound request carries its target. The leader injects `message_thread_id
 Threaded Mode should make follower threads behave like normal Telegram instance surfaces, with the leader acting only as transport owner. Any feature in the matrix below that works for the leader must either work for followers or have an explicit documented exception.
 
 | Surface                          | Leader behavior                                                                                                                                                                                                                                       | Follower requirement                                                                                                                                                                                                                                            | Routing/ownership invariant                                                                                                                                                                                                                         | Regression evidence                                                                                                       |
-| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| --- | --- | --- | --- | --- |
 | Prompt intake                    | Thread prompt queues locally                                                                                                                                                                                                                          | Thread prompt is forwarded and queued by the owning follower                                                                                                                                                                                                    | Target ownership routes by `{ chatId, threadId }` before local handling                                                                                                                                                                             | Routing tests for foreign target message forwarding                                                                       |
 | Queued-message removal reactions | 👎/👻/💔/💩/🗑 marks a pending prompt/media turn for deletion when it reaches dispatch                                                                                                                                                                            | Same reaction on a queued follower prompt marks that follower's pending turn for deletion before model dispatch                                                                                                                                                                  | When the leader forwards a prompt to a follower, it records `chatId/messageId -> follower instance` because Bot API reaction updates expose chat/message but not thread id                                                                          | Update runtime regression records forwarded message ownership and forwards the later reaction                             |
 | Queue priority reactions         | 👍/⚡/❤/🕊/🔥 prioritizes queued prompts                                                                                                                                                                                                               | Same reactions prioritize follower queued prompts                                                                                                                                                                                                               | Reaction forwarding uses stored message ownership, then follower mutates its local queue                                                                                                                                                            | Reaction mutation tests plus forwarded-reaction coverage                                                                  |

package/docs/outbound.md

@@ -119,14 +119,13 @@ import { registerTelegramVoiceSynthesisProvider } from "@llblab/pi-telegram/voic
 
 const dispose = registerTelegramVoiceSynthesisProvider(
   async (text, options) => {
-    const audioPath = await synthesizeToOggOpus(text, options);
-    return { audioPath, transcriptText: text };
+    return await synthesizeToOggOpus(text, options);
   },
   { id: "my-extension/tts" },
 );
 ```
 
-Synthesis providers receive the extracted `telegram_voice` text plus optional `lang`/`rate` hints. Stable registrations pass a durable `id`; omitted ids remain a compatibility path for older providers. Providers own translation, TTS, speech rewriting, transcript choice, and OGG/Opus conversion. The bridge validates that the returned file ends in `.ogg` or `.opus`, sends it through Telegram `sendVoice`, and falls back to planned text if delivery fails before any visible text was delivered. Providers run after configured and programmatic voice handlers in the priority chain above.
+Synthesis providers receive the extracted `telegram_voice` text plus optional `lang`/`rate` hints. Stable registrations pass a durable `id`; omitted ids remain a compatibility path for older providers. Providers own translation, TTS, speech rewriting, and OGG/Opus conversion. The bridge validates that the returned file ends in `.ogg` or `.opus`, sends it through Telegram `sendVoice`, and falls back to planned text if delivery fails before any visible text was delivered. Providers run after configured and programmatic voice handlers in the priority chain above.
 
 ## Voice Markup
 

package/docs/public-api.md

@@ -99,8 +99,7 @@ interface TelegramConfig {
     timeInjection?: "hidden" | "always" | "interval";
   };
   voice?: {
-    replyMode?: "hidden" | "mirror" | "always";
-    sendTranscript?: boolean;
+    replyMode?: "manual" | "mirror" | "always";
   };
   time?: {
     interval?: number;
@@ -409,16 +408,13 @@ const offStt = registerTelegramVoiceTranscriptionProvider(
 
 const offTts = registerTelegramVoiceSynthesisProvider(
   async (text, options) => {
-    const audioPath = await synthesizeOggOpus(text, options);
-    return getTelegramVoiceSendTranscript(getCurrentTelegramConfigView())
-      ? { audioPath, transcriptText: text }
-      : { audioPath };
+    return await synthesizeOggOpus(text, options);
   },
   { id: "@scope/my-extension/tts" },
 );
 ```
 
-Stable voice-provider registrations pass a durable `id`. Omitting `id` is a compatibility path for older providers and receives a generated session-local id. Providers return `undefined` to pass. TTS providers must return `.ogg` or `.opus` files for native Telegram voice notes. `voice.sendTranscript` is the bridge-owned transcript preference; providers that expose captions should gate `transcriptText` with `getTelegramVoiceSendTranscript(config)` instead of defining a second reply-policy toggle.
+Stable voice-provider registrations pass a durable `id`. Omitting `id` is a compatibility path for older providers and receives a generated session-local id. Providers return `undefined` to pass. TTS providers must return `.ogg` or `.opus` files for native Telegram voice notes.
 
 Full behavior: [Voice Integration](./voice.md).
 
@@ -525,7 +521,6 @@ export default function demoOutbound(pi: ExtensionAPI) {
 ```ts
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
-  getTelegramVoiceSendTranscript,
   registerTelegramVoiceSynthesisProvider,
   registerTelegramVoiceTranscriptionProvider,
 } from "@llblab/pi-telegram/voice";
@@ -533,16 +528,12 @@ import {
 export default function demoVoice(pi: ExtensionAPI) {
   let unregisterTts: (() => void) | undefined;
   let unregisterStt: (() => void) | undefined;
-  let currentConfig: { voice?: { sendTranscript?: boolean } } = {};
   pi.on("session_start", async () => {
     unregisterTts?.();
     unregisterStt?.();
     unregisterTts = registerTelegramVoiceSynthesisProvider(
       async (text) => {
-        const audioPath = await synthesizeDemoOgg(text);
-        return getTelegramVoiceSendTranscript(currentConfig)
-          ? { audioPath, transcriptText: text }
-          : { audioPath };
+        return await synthesizeDemoOgg(text);
       },
       { id: "demo-voice/tts" },
     );

package/docs/voice.md

@@ -43,12 +43,12 @@ Voice provider extensions can also register STT backends with `registerTelegramV
 
 ## Voice Reply Policy
 
-The bridge decides **when** to reply with voice from `voice.replyMode` in `TelegramConfig` (stored in `telegram.json`). Missing, invalid, `hidden`, and legacy `manual` values resolve to the silent `hidden` default.
+The bridge decides **when** to reply with voice from `voice.replyMode` in `TelegramConfig` (stored in `telegram.json`). Missing and invalid values resolve to the `manual` default; the former `hidden` value remains a read-only compatibility alias for `manual`.
 
 ### Modes
 
-- **`hidden` (default):** no `voice.replyMode` is stored and no automatic voice context is added; explicit agent-authored `telegram_voice` actions still work.
-- **`mirror`:** voice/audio input activates automatic voice delivery. Text input follows `hidden` behavior.
+- **`manual` (default):** no `voice.replyMode` is stored and no automatic voice context is added; explicit agent-authored `telegram_voice` actions still work.
+- **`mirror`:** voice/audio input activates automatic voice delivery. Text input follows `manual` behavior.
 - **`always`:** every Telegram turn activates automatic voice delivery.
 
 **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.
@@ -70,7 +70,7 @@ 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
+- `registerTelegramSection()` for provider-specific Telegram UI such as voice, language, style, or provider on/off controls
 
 The reply policy itself remains a built-in pi-telegram setting (`voice.replyMode`) rather than a provider-owned menu.
 
@@ -81,10 +81,8 @@ Voice synthesis provider extensions register themselves through `registerTelegra
 - 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 bridge-owned `voice.sendTranscript` preference when the provider has access to the current Telegram config
-- `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.
+The bridge shows a `record_voice` action while delivering and sends the final audio with Telegram `sendVoice`.
 
 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.
 
@@ -95,7 +93,6 @@ 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**. Providers should treat pi-telegram's `voice.sendTranscript` as the bridge-owned transcript preference instead of inventing a second reply-policy UI.
 - `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.
@@ -106,7 +103,7 @@ Registration returns a disposer function for cleanup. Stable provider registrati
 
 ## 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 (`hidden`, `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.
+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:
 
@@ -128,31 +125,6 @@ Voice handlers receive the text on stdin in composed pipelines and can use `{tex
 
 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 {
-  getTelegramVoiceSendTranscript,
-  registerTelegramVoiceSynthesisProvider,
-} from "@llblab/pi-telegram/voice";
-
-registerTelegramVoiceSynthesisProvider(
-  async (text, options) => {
-    const rewritten = rewriteWithSpeechTags(text);
-    const audioPath = await myTTS(rewritten, { language: options?.lang });
-    const sendTranscript = getTelegramVoiceSendTranscript(
-      getCurrentTelegramConfigView(),
-    );
-    return sendTranscript ? { audioPath, transcriptText: text } : { audioPath };
-  },
-  { id: "my-voice-provider/tts" },
-);
-```
-
-`getCurrentTelegramConfigView()` represents whatever current `TelegramConfig` view your extension already owns or receives; pi-telegram does not require providers to read config directly. 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:
@@ -170,13 +142,13 @@ recordTelegramRuntimeEvent("voice-provider", new Error("TTS failed"), {
 
 ## 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.
+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, 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` from `@llblab/pi-telegram/sections`.
 
 ## Prompt Guidance
 
-The bridge keeps voice prompt context compact, effective, and policy-owned. `hidden` and text-originated `mirror` turns add no voice line. Voice/audio-originated `mirror` turns and every `always` turn add exactly `[voice] delivery: automatic voice`, describing the current delivery environment without exposing the underlying mode matrix or an instruction 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.
+The bridge keeps voice prompt context compact, effective, and policy-owned. `manual` and text-originated `mirror` turns add no voice line. Voice/audio-originated `mirror` turns and every `always` turn add exactly `[voice] delivery: automatic voice`, describing the current delivery environment without exposing the underlying mode matrix or an instruction 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.
 
@@ -224,4 +196,4 @@ 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.
+Provider-specific settings (voice ID, language, speech style, 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/lib/config.ts

@@ -118,9 +118,8 @@ export interface TelegramConfig {
   /** @deprecated use assistant.rendering */
   assistantRendering?: TelegramAssistantRenderingMode;
   voice?: {
-    replyMode?: "hidden" | "mirror" | "always";
-    /** Whether to attach the provider's transcriptText as caption on voice messages */
-    sendTranscript?: boolean;
+    /** `hidden` is a read-only compatibility alias for the former manual mode. */
+    replyMode?: "manual" | "hidden" | "mirror" | "always";
   };
   time?: TelegramTimeConfig;
   threads?: {
@@ -845,10 +844,10 @@ export function createTelegramActivityVerbositySetter(
 
 export function createTelegramVoiceReplyModeGetter(
   configStore: Pick<TelegramConfigStore, "get">,
-): () => "hidden" | "mirror" | "always" {
+): () => "manual" | "mirror" | "always" {
   return () => {
     const mode = configStore.get().voice?.replyMode;
-    return mode === "mirror" || mode === "always" ? mode : "hidden";
+    return mode === "mirror" || mode === "always" ? mode : "manual";
   };
 }
 
@@ -863,11 +862,15 @@ export function createTelegramVoiceReplyModeConfiguredChecker(
 
 export function createTelegramVoiceReplyModeSetter(
   configStore: TelegramMutableConfigStore,
-): (replyMode: "hidden" | "mirror" | "always" | undefined) => Promise<void> {
+): (replyMode: "manual" | "hidden" | "mirror" | "always" | undefined) => Promise<void> {
   return async (replyMode) => {
     await loadLatestTelegramConfig(configStore);
     const current = configStore.get();
-    if (replyMode === undefined || replyMode === "hidden") {
+    if (
+      replyMode === undefined ||
+      replyMode === "manual" ||
+      replyMode === "hidden"
+    ) {
       const { replyMode: _replyMode, ...remainingVoice } = current.voice ?? {};
       const next = { ...current };
       if (Object.keys(remainingVoice).length > 0) next.voice = remainingVoice;

package/lib/menu-settings.ts

@@ -149,9 +149,7 @@ export const TIME_INJECTION_MODE_SETTINGS_TITLE =
   "<b>🕒 Time injection mode:</b>";
 export const VOICE_REPLY_MODE_SETTINGS_TITLE = "<b>👄 Voice reply mode:</b>";
 
-type TelegramVoiceReplyModeSetting = TelegramVoiceReplyMode | "hidden";
-
-function getVoiceReplyModeLabel(mode: TelegramVoiceReplyModeSetting): string {
+function getVoiceReplyModeLabel(mode: TelegramVoiceReplyMode): string {
   return mode;
 }
 
@@ -162,8 +160,8 @@ function getTelegramSettingsStateValueLabel(value: string): string {
 function getVoiceReplyModeSetting(
   mode: TelegramVoiceReplyMode,
   configured: boolean,
-): TelegramVoiceReplyModeSetting {
-  return configured ? mode : "hidden";
+): TelegramVoiceReplyMode {
+  return configured ? mode : "manual";
 }
 
 export function buildTelegramSettingsMenuText(): string {
@@ -246,8 +244,8 @@ export function buildVoiceReplyModeSettingsText(
     "",
     "Controls when pi-telegram converts assistant text replies into Telegram voice messages.",
     "",
-    "<code>-</code> <code>hidden</code> (default): add no automatic voice context; explicit 'telegram_voice' actions still work.",
-    "<code>-</code> <code>mirror</code>: voice input activates automatic voice delivery; text input follows 'hidden' behavior.",
+    "<code>-</code> <code>manual</code> (default): add no automatic voice context; explicit 'telegram_voice' actions still work.",
+    "<code>-</code> <code>mirror</code>: voice input activates automatic voice delivery; text input follows 'manual' behavior.",
     "<code>-</code> <code>always</code>: activate automatic voice delivery for every reply.",
   ].join("\n");
 }
@@ -502,7 +500,7 @@ export function buildVoiceReplyModeSettingsReplyMarkup(
   configured = true,
 ): TelegramSettingsMenuReplyMarkup {
   const activeMode = getVoiceReplyModeSetting(mode, configured);
-  const modes: TelegramVoiceReplyModeSetting[] = ["hidden", "mirror", "always"];
+  const modes: TelegramVoiceReplyMode[] = ["manual", "mirror", "always"];
   return {
     inline_keyboard: [
       [{ text: "⬆️ Back", callback_data: "settings:list" }],
@@ -661,12 +659,18 @@ export async function handleTelegramSettingsMenuCallbackAction(
   }
   if (data.startsWith("settings:set:voice-reply:")) {
     const mode = data.slice("settings:set:voice-reply:".length);
-    if (mode === "hidden" || mode === "mirror" || mode === "always") {
-      await deps.setVoiceReplyMode(mode === "hidden" ? undefined : mode);
+    if (
+      mode === "manual" ||
+      mode === "hidden" ||
+      mode === "mirror" ||
+      mode === "always"
+    ) {
+      const normalizedMode = mode === "hidden" ? "manual" : mode;
+      await deps.setVoiceReplyMode(normalizedMode);
       await updateVoiceReplyModeSettingsMessage(deps);
       await deps.answerCallbackQuery(
         callbackQueryId,
-        `Voice reply mode: ${mode}`,
+        `Voice reply mode: ${normalizedMode}`,
       );
       return true;
     }

package/lib/outbound-voice.ts

@@ -100,17 +100,6 @@ async function ensureTelegramVoiceFileFormat(
   );
 }
 
-function extractVoiceResult(result: any): {
-  filePath: string;
-  transcriptText?: string;
-} {
-  if (typeof result === "string") return { filePath: result };
-  return {
-    filePath: result.audioPath,
-    transcriptText: result.transcriptText,
-  };
-}
-
 async function sendVoiceChatAction(
   deps: TelegramVoiceReplySenderDeps,
   chatId: number,
@@ -132,7 +121,6 @@ export function createTelegramVoiceReplySender<THandler = unknown>(
     options?: {
       replyToPrompt?: boolean;
       replyMarkup?: unknown;
-      transcriptText?: string;
     },
   ): Promise<void> => {
     const voiceFilePath = await ensureTelegramVoiceFileFormat(filePath);
@@ -148,7 +136,6 @@ export function createTelegramVoiceReplySender<THandler = unknown>(
       "sendVoice",
       {
         chat_id: String(turn.chatId),
-        ...(options?.transcriptText ? { caption: options.transcriptText } : {}),
         ...(replyParameters ? { reply_parameters: replyParameters } : {}),
         ...(turn.target
           ? Object.fromEntries(
@@ -257,13 +244,11 @@ export function createTelegramVoiceReplySender<THandler = unknown>(
           continue;
         }
 
-        const { filePath, transcriptText } = extractVoiceResult(providerResult);
-        voiceFilePath = filePath;
-        originalFilePath = filePath;
-        await uploadVoiceFile(turn, filePath, {
+        voiceFilePath = providerResult;
+        originalFilePath = providerResult;
+        await uploadVoiceFile(turn, providerResult, {
           replyToPrompt: options?.replyToPrompt,
           replyMarkup: options?.replyMarkup,
-          transcriptText,
         });
         return;
       } catch (error) {

package/lib/voice.ts

@@ -38,15 +38,9 @@ function getNextAvailableProviderId<T>(
   return id;
 }
 
-export type TelegramVoiceReplyMode = "hidden" | "mirror" | "always";
+export type TelegramVoiceReplyMode = "manual" | "mirror" | "always";
 
-export type TelegramVoiceSynthesisProviderResult =
-  | string
-  | {
-      audioPath: string;
-      transcriptText?: string;
-    }
-  | undefined;
+export type TelegramVoiceSynthesisProviderResult = string | undefined;
 
 export interface TelegramVoiceTurnView {
   voiceReplyPreferred?: boolean;
@@ -215,7 +209,7 @@ export function clearTelegramVoiceTranscriptionProviders(): void {
 // --- Voice Reply Modes ---
 
 export const TELEGRAM_VOICE_REPLY_MODES = [
-  "hidden",
+  "manual",
   "mirror",
   "always",
 ] as const;
@@ -224,33 +218,15 @@ export const TELEGRAM_VOICE_REPLY_MODES = [
  * Returns the active voice reply mode for the current session.
  *
  * Pi-telegram owns reply-mode policy through telegram.json. If
- * config.voice.replyMode is missing, invalid, or legacy `manual`, the effective
- * mode is hidden.
+ * config.voice.replyMode is missing, invalid, or legacy `hidden`, the effective
+ * mode is manual.
  */
 export function getTelegramVoiceReplyMode(config?: {
   voice?: { replyMode?: string };
 }): TelegramVoiceReplyMode {
   const configMode = config?.voice?.replyMode;
-  if (
-    configMode &&
-    (TELEGRAM_VOICE_REPLY_MODES as readonly string[]).includes(configMode)
-  ) {
-    return configMode as TelegramVoiceReplyMode;
-  }
-  return "hidden";
-}
-
-/**
- * Returns whether the user wants the voice synthesis provider's transcript attached
- * as a caption on the voice message.
- *
- * Reads from `config.voice.sendTranscript`.
- * Default: false (no transcript text sent at all).
- */
-export function getTelegramVoiceSendTranscript(config?: {
-  voice?: { sendTranscript?: boolean };
-}): boolean {
-  return !!config?.voice?.sendTranscript;
+  if (configMode === "mirror" || configMode === "always") return configMode;
+  return "manual";
 }
 
 // --- Voice Turn Helpers ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.37.2",
+  "version": "0.38.0",
   "private": false,
   "publishConfig": {
     "access": "public"

package/skills/telegram-bridge/SKILL.md

@@ -122,7 +122,7 @@ Prefer no-code command-template configuration in `telegram.json` before adding a
 - `outboundHandlers` transforms final replies.
 - Voice transcription handlers can match `type: "voice"` or `mime: "audio/*"`; stdout becomes `[outputs]`.
 
-When asked to configure voice rather than merely operate it, follow the provider-neutral contracts in `docs/voice.md`, `docs/inbound.md`, `docs/outbound.md`, and `docs/command-templates.md` from the pi-telegram package or repository. Inspect the available Skill catalog and trusted local executables for STT, TTS, and media conversion capabilities; check only whether required environment variables exist, never reveal their values. Preserve unrelated `telegram.json` fields, order multiple matching inbound handlers as fallbacks, require OGG/Opus output for native voice delivery, and validate each stage before a live Telegram smoke test. Keep `voice.replyMode` at its existing value unless the user requests a policy change: the default `hidden` mode is fully functional because explicit top-level `telegram_voice` actions still use the configured synthesis pipeline.
+When asked to configure voice rather than merely operate it, follow the provider-neutral contracts in `docs/voice.md`, `docs/inbound.md`, `docs/outbound.md`, and `docs/command-templates.md` from the pi-telegram package or repository. Inspect the available Skill catalog and trusted local executables for STT, TTS, and media conversion capabilities; check only whether required environment variables exist, never reveal their values. Preserve unrelated `telegram.json` fields, order multiple matching inbound handlers as fallbacks, require OGG/Opus output for native voice delivery, and validate each stage before a live Telegram smoke test. Keep `voice.replyMode` at its existing value unless the user requests a policy change: the default `manual` mode is fully functional because explicit top-level `telegram_voice` actions still use the configured synthesis pipeline.
 
 When configuration is insufficient, use documented `@llblab/pi-telegram/*` public API subpaths. Never import package-private `lib/*`, start another polling loop, or bypass bridge ownership with raw Bot API access.