@llblab/pi-telegram 0.10.8 → 0.11.1

package/docs/outbound-handlers.md

@@ -2,21 +2,23 @@
 
 `pi-telegram` maps hidden assistant-authored HTML comments to Telegram-native outbound actions.
 
-This is intentionally prompt-driven: the agent writes normal Markdown plus small hidden top-level blocks, and the bridge performs the transport work after `agent_end`. `telegram_voice` and `telegram_button` are not π tools. Outbound behavior is an emergent result of the assistant prompt, configured command-template handlers, generated artifacts, and reply delivery. That avoids extra agent-side tool calls, avoids fragile parameter plumbing inside the conversation, and minimizes latency because text, voice, and buttons are planned in one standard assistant reply.
+This is intentionally prompt-driven: the agent writes normal Markdown plus small hidden top-level blocks, and the bridge performs the transport work after `agent_end`. `telegram_voice` and `telegram_button` are not π tools. Outbound behavior is an emergent result of the assistant prompt, text command-template handlers, registered voice synthesis providers, generated artifacts, and reply delivery. That avoids extra agent-side tool calls, avoids fragile parameter plumbing inside the conversation, and minimizes latency because text, voice, and buttons are planned in one standard assistant reply.
 
-This document is the local outbound adaptation of the portable [Command Template Standard](./command-templates.md).
+Text handlers use the portable [Command Template Standard](./command-templates.md). Programmatic outbound handlers use `registerTelegramOutboundHandler(kind, handler)`. Voice replies can use configured command-template handlers or the provider API described in [Voice Integration](./voice.md).
 
 ## Standard
 
 An outbound handler is selected by `type`. Text replies and assistant markup map to handler types:
 
-| Source | Type | Action |
-| --- | --- | --- |
-| Final text | `text` | Transform before render |
-| `telegram_voice` | `voice` | Generate OGG/Opus |
-| `telegram_button` | Built-in | Attach inline button |
+| Source            | Handler                       | Action                  |
+| ----------------- | ----------------------------- | ----------------------- |
+| Final text        | `outboundHandlers[type=text]` | Transform before render |
+| `telegram_voice`  | Voice pipeline                | OGG/Opus `sendVoice`   |
+| `telegram_button` | Built-in                      | Attach inline button    |
 
-Configured command-template handlers provide `template`. A string is one command; an array is ordered composition. Top-level `args` and `defaults` apply to all composed steps unless a step defines private values. The command-template default timeout applies automatically. `output` selects the primary artifact path when the handler produces a file instead of stdout text. Legacy configs may still use `pipe`, but `template: [...]` is the preferred standard shape.
+The voice pipeline is detailed below: configured `type: "voice"` handlers first, then programmatic handlers, then registered synthesis providers.
+
+Configured text handlers provide `template`. A string is one command; an array is ordered composition. Top-level `args` and `defaults` apply to all composed steps unless a step defines private values. The command-template default timeout applies automatically. Legacy configs may still use `pipe`, but `template: [...]` is the preferred standard shape.
 
 ## Text Handler Config
 
@@ -52,27 +54,30 @@ Stdin-based or subagent-backed translation can omit `{text}` from the template b
 
 A text handler should preserve the full message unless shortening is intentional; for translation prompts, explicitly ask the tool to keep Markdown, line breaks, and details unchanged.
 
-## Voice Handler Config
+## Voice Delivery Priority
 
-`telegram.json` may define `outboundHandlers`:
+Voice replies use one fallback pipeline:
 
-```json
-{
-  "outboundHandlers": [
-    {
-      "type": "voice",
-      "template": [
-        "/path/to/translate-stdin --lang {lang=ru}",
-        "/path/to/tts-from-stdin --lang {lang=ru} --rate {rate=+30%} --write-media {mp3}",
-        "ffmpeg -y -i {mp3} -c:a libopus -b:a 32k -ar 16000 -ac 1 -vbr on {ogg}"
-      ],
-      "output": "ogg"
-    }
-  ]
-}
+1. configured `outboundHandlers` with `type: "voice"` in `telegram.json` order
+2. programmatic `registerTelegramOutboundHandler("voice", ...)` handlers
+3. registered voice synthesis providers from `@llblab/pi-telegram/lib/voice.ts`
+
+This makes provider extensions a zero-config convenience without overriding explicit operator-owned `telegram.json` handlers. If several synthesis providers are registered, they are tried in registration order; the first provider that returns a valid `.ogg`/`.opus` artifact handles the reply. Returning `undefined` passes to the next provider, while thrown errors or invalid files are recorded before the next fallback is tried.
+
+## Voice Synthesis Provider API
+
+Voice replies can be delivered by synthesis providers registered through `@llblab/pi-telegram/lib/voice.ts`:
+
+```ts
+import { registerTelegramVoiceSynthesisProvider } from "@llblab/pi-telegram/lib/voice.ts";
+
+const dispose = registerTelegramVoiceSynthesisProvider(async (text, options) => {
+  const audioPath = await synthesizeToOggOpus(text, options);
+  return { audioPath, transcriptText: text };
+});
 ```
 
-In this example, the first step receives the `telegram_voice` text on stdin and returns translated text; the second step reads that translated text from stdin and writes `{mp3}`; the final step converts `{mp3}` to Telegram-ready `{ogg}`. If you do not need voice translation, omit the first step and call a TTS command that accepts `{text}` directly. If a matching voice handler fails, the bridge tries the next matching `type: "voice"` handler.
+Synthesis providers receive the extracted `telegram_voice` text plus optional `lang`/`rate` hints. They 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.
 
 ## Voice Markup
 
@@ -90,29 +95,7 @@ Text to synthesize as a Telegram voice message.
 <!-- telegram_voice: Short spoken companion summary. -->
 ```
 
-The bridge strips the comment from Telegram text. On `agent_end`, it maps each `telegram_voice` block to `type: "voice"`, generates one file per block, and sends each file as an independent Telegram-native voice message. The opening `<!-- telegram_voice` marker must start at column zero on a top-level line outside fenced code, quotes, and lists; otherwise it is rendered as literal Markdown. Body-form comments leave the opening line unclosed until the body-ending `-->`; closed heads can use `text="..."` for explicit one-line spoken text.
-
-## Built-In Voice Placeholders
-
-Voice outbound handlers receive these runtime placeholders:
-
-| Placeholder | Value |
-| --- | --- |
-| `{text}` | Voice text from body, attr, or colon form |
-| `{lang}` | Optional override, e.g. `lang=ru` |
-| `{rate}` | Optional override, e.g. `rate=+30%` |
-| `{mp3}` | Temp MP3 path under agent temp |
-| `{ogg}` | Temp OGG path under agent temp |
-
-Temp artifacts use unique flat names such as `<uuid>-voice.mp3` and `<uuid>-voice.ogg`. The bridge does not create per-handler directory trees.
-
-## Output
-
-For composed handlers, `output` selects the primary artifact after the composition completes. Omitted `output` means `"stdout"`, so the final step should print the generated OGG/Opus path. `"output": "ogg"` means the generated file path comes from `{ogg}`. A value such as `"{ogg}"` is equivalent. Composition also follows the command-template standard where each step's stdout is provided as stdin to the next step by default.
-
-For one-step `template` handlers, stdout remains the default result channel: the command should print the generated OGG/Opus path.
-
-**Critical steps:** voice synthesis is often a multi-step transform → TTS → conversion pipeline. The final audio conversion step is inherently critical — if it fails, the voice output is invalid. Mark conversion steps as `"critical": true` when a composed handler must abort after conversion failure instead of continuing to later non-critical steps. Use multiple matching `type: "voice"` handlers when you need provider or command fallbacks. See [Command Template Standard](./command-templates.md) for semantics.
+The bridge strips the comment from Telegram text. On `agent_end`, it maps each `telegram_voice` block to a provider call, generates one file per block, and sends each file as an independent Telegram-native voice message. The opening `<!-- telegram_voice` marker must start at column zero on a top-level line outside fenced code, quotes, and lists; otherwise it is rendered as literal Markdown. Body-form comments leave the opening line unclosed until the body-ending `-->`; closed heads can use `text="..."` for explicit one-line spoken text.
 
 ## Buttons Markup
 
@@ -149,6 +132,6 @@ The extension injects Telegram-specific system prompt guidance so agents know th
 - Write the full technical answer as normal Markdown.
 - Add `telegram_voice` when a Telegram-native voice message is useful; use body text, `text="..."`, or colon shorthand for the text to synthesize. A companion summary is optional, no specific summary format is required.
 - Add `telegram_button: ...` when label equals prompt, `telegram_button label="..." prompt="..."` for one-line prompts, or `telegram_button label="..."` with a body for multiline prompts. If the reply contains only button/voice comment blocks, add a short visible marker (for example `Choose one:`) before them so Telegram always has a visible parent message for attachment.
-- Do not call or register TTS/text-to-OGG/Telegram transport tools for voice or buttons; the bridge owns the configured outbound-handler pipeline and delivery.
+- Do not call Telegram transport tools for voice or buttons; the bridge owns delivery, while registered voice synthesis providers own TTS and OGG/Opus conversion.
 
 This keeps the agent focused on semantics and lets the bridge handle low-latency Telegram adaptation.

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,50 @@ 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 TimeInjection from "./lib/time-injection.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 +96,28 @@ 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 getTimeInjectionMode =
+    Config.createTelegramTimeInjectionModeGetter(configStore);
+  const setTimeInjectionMode =
+    Config.createTelegramTimeInjectionModeSetter(configStore);
   const lockRuntime = Locks.createTelegramLockRuntime<Pi.ExtensionContext>();
   const lockOwnershipGuard =
     Locks.createTelegramLockOwnershipGuard(lockRuntime);
@@ -77,10 +136,19 @@ export default function (pi: Pi.ExtensionAPI) {
   const sectionRegistry: TelegramSectionRegistry =
     createTelegramExtensionSectionRegistry();
   setGlobalTelegramSectionRegistry(sectionRegistry);
+
+
   const runtimeEvents = Status.createTelegramRuntimeEventRecorder({
     getBotToken: configStore.getBotToken,
   });
   const recordRuntimeEvent = runtimeEvents.record;
+  const timeInjectionRuntime = TimeInjection.createTimeInjectionRuntime({
+    getConfig: Config.createTelegramTimeConfigGetter(configStore),
+    recordRuntimeEvent,
+  });
+  (globalThis as Record<string, unknown>)[
+    VOICE_EVENT_RECORDER_KEY
+  ] = recordRuntimeEvent;
   const getContextModel = Pi.getExtensionContextModel;
   const isIdle = Pi.isExtensionContextIdle;
   const hasPendingMessages = Pi.hasExtensionContextPendingMessages;
@@ -151,6 +219,8 @@ export default function (pi: Pi.ExtensionAPI) {
     getUpdates,
     setMyCommands,
     sendTypingAction,
+    sendChatAction,
+    sendRecordVoiceAction,
     sendMessageDraft,
     sendMessage,
     downloadFile: downloadTelegramBridgeFile,
@@ -287,6 +357,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 +393,12 @@ export default function (pi: Pi.ExtensionAPI) {
       sendInteractiveMessage,
       answerCallbackQuery,
       isProactivePushEnabled,
+      getVoiceReplyMode,
+      isVoiceReplyModeConfigured,
+      getTimeInjectionMode,
       setProactivePushEnabled,
+      setVoiceReplyMode,
+      setTimeInjectionMode,
     },
     sectionRegistry,
   );
@@ -365,6 +446,7 @@ export default function (pi: Pi.ExtensionAPI) {
     setMyCommands,
     getCommands,
     downloadFile: downloadTelegramBridgeFile,
+    resolveTimeLine: timeInjectionRuntime.resolveLine,
     getThinkingLevel,
     setThinkingLevel,
     persistScopedModelPatterns: Pi.createScopedModelPatternPersister({
@@ -433,7 +515,9 @@ export default function (pi: Pi.ExtensionAPI) {
   });
   const sessionLifecycleRuntime = Lifecycle.appendTelegramLifecycleHooks(
     queueSessionLifecycle,
-    { onSessionStart: lockedPollingRuntime.onSessionStart },
+    {
+      onSessionStart: lockedPollingRuntime.onSessionStart,
+    },
   );
 
   // --- Extension API Bindings ---
@@ -485,6 +569,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 {