@llblab/pi-telegram 0.11.2 → 0.12.0

package/docs/{external-handlers.md → updates.md}

@@ -1,10 +1,12 @@
-# External Handlers
+# Updates
 
-`pi-telegram` owns a single `getUpdates` long-poll connection per bot. Other pi extensions cannot open a competing poller against the same bot — the Telegram Bot API uses a per-bot `offset` cursor, and two pollers race each other and lose updates.
+`updates` owns Telegram update classification, default-routing plans, and the public update-handler registry. The internal `polling` domain owns the actual `getUpdates` loop, offsets, and abort/controller state.
+
+`pi-telegram` owns a single `getUpdates` long-poll connection per bot. Other pi extensions cannot open a competing polling connection against the same bot — the Telegram Bot API uses a per-bot `offset` cursor, and two loops race each other and lose updates.
 
 This document describes the registry that lets layered pi extensions running in the same pi process hook into `pi-telegram`'s polling loop and react to inbound Telegram updates **before** `pi-telegram`'s default routing fires.
 
-It is the runtime counterpart to [Callback Namespaces](./callback-namespaces.md): callback namespaces define how to share `callback_data` cleanly; external handlers define how to observe and optionally short-circuit the dispatch of those updates.
+It is the runtime counterpart to [Callback Namespaces](./callback-namespaces.md): callback namespaces define how to share `callback_data` cleanly; update handlers define how to observe and optionally short-circuit the dispatch of those updates.
 
 ## When to use it
 
@@ -16,34 +18,34 @@ Use it when a layered extension needs to:
 
 If the layered extension only needs to read assistant-visible callbacks, the existing `[callback] <data>` fallback documented in [Callback Namespaces](./callback-namespaces.md) is enough.
 
-If the extension needs a durable top-level Telegram menu section with managed rendering, callback routing, authorization, and diagnostics, use the higher-level [Telegram Extension Sections](./extension-sections.md) contract instead of a raw external handler.
+If the extension needs a durable top-level Telegram menu section with managed rendering, callback routing, authorization, and diagnostics, use the higher-level [Telegram Extension Sections](./sections.md) contract instead of a raw update handler.
 
 ## Constraints
 
-- One bot, one pi process, one `getUpdates` poller. This registry does **not** enable running multiple pi instances against the same bot.
-- Interceptors run in the polling loop. They must return quickly; long awaits delay subsequent updates.
-- Interceptor errors are caught and logged silently so polling never breaks. If you need durable error reporting, do it inside your interceptor.
+- One bot, one pi process, one `getUpdates` loop. This registry does **not** enable running multiple pi instances against the same bot.
+- Handlers run in the polling loop. They must return quickly; long awaits delay subsequent updates.
+- Handler errors are caught and logged silently so polling never breaks. If you need durable error reporting, do it inside your handler.
 - The registry lives on `globalThis`. Module instance identity is not required, so layered extensions can reach it without importing `@llblab/pi-telegram`.
 
 ## Verdicts
 
-Each interceptor returns one of:
+Each handler returns one of:
 
 - `"consume"` — `pi-telegram` skips its default routing for this update.
-- `"pass"` or `void` / `undefined` — `pi-telegram` routes the update normally. Other interceptors registered after this one still run for the same update.
+- `"pass"` or `void` / `undefined` — `pi-telegram` routes the update normally. Other handlers registered after this one still run for the same update.
 
-The first interceptor that returns `"consume"` wins; later interceptors are not called for that update.
+The first handler that returns `"consume"` wins; later handlers are not called for that update.
 
-## Registering an interceptor
+## Registering a handler
 
 Two equivalent paths.
 
 ### Typed import (recommended when you can depend on `@llblab/pi-telegram`)
 
 ```ts
-import { onTelegramExternalUpdate } from "@llblab/pi-telegram/lib/external-handlers.ts";
+import { registerTelegramUpdateHandler } from "@llblab/pi-telegram/updates";
 
-const off = onTelegramExternalUpdate(async (update) => {
+const off = registerTelegramUpdateHandler(async (update) => {
   const cb = (update as { callback_query?: { id?: string; data?: string } })
     .callback_query;
   if (!cb?.data?.startsWith("myext:")) return "pass";
@@ -57,7 +59,7 @@ off();
 
 ### Zero-coupling globalThis lookup
 
-When the layered extension prefers no `import` from `@llblab/pi-telegram`, so load order between the two extensions does not matter and either can be installed first, it must implement the **full v1 registry contract**, not just `version` and `add`. pi-telegram's polling runtime calls `dispatch` on whatever object it finds at `globalThis.__piTelegramExternalHandlerRegistry__`, so a partial object would silently break the first update.
+When the layered extension prefers no `import` from `@llblab/pi-telegram`, so load order between the two extensions does not matter and either can be installed first, it must implement the **full v1 registry contract**, not just `version` and `add`. pi-telegram's polling runtime calls `dispatch` on whatever object it finds at `globalThis.__piTelegramUpdateHandlerRegistry__`, so a partial object would silently break the first update.
 
 pi-telegram defensively re-creates the registry if the object on `globalThis` is missing `add` or `dispatch`, validated as `version === 1`, `typeof add === "function"`, and `typeof dispatch === "function"`. Handlers registered against a malformed object are dropped — make sure your bootstrap implements all three fields.
 
@@ -67,21 +69,21 @@ type PiTelegramVerdict =
   | "pass"
   | void
   | Promise<"consume" | "pass" | void>;
-type PiTelegramInterceptor = (update: unknown) => PiTelegramVerdict;
+type PiTelegramUpdateHandler = (update: unknown) => PiTelegramVerdict;
 
-interface PiTelegramExternalHandlerRegistry {
+interface PiTelegramUpdateHandlerRegistry {
   readonly version: 1;
-  add: (handler: PiTelegramInterceptor) => () => void;
+  add: (handler: PiTelegramUpdateHandler) => () => void;
   // Required: pi-telegram's polling loop calls this on every update.
   dispatch: (update: unknown) => Promise<"consume" | "pass">;
 }
 
-const REGISTRY_KEY = "__piTelegramExternalHandlerRegistry__";
+const REGISTRY_KEY = "__piTelegramUpdateHandlerRegistry__";
 
-function getOrCreateRegistry(): PiTelegramExternalHandlerRegistry {
+function getOrCreateRegistry(): PiTelegramUpdateHandlerRegistry {
   const g = globalThis as Record<string, unknown>;
   const existing = g[REGISTRY_KEY] as
-    | PiTelegramExternalHandlerRegistry
+    | PiTelegramUpdateHandlerRegistry
     | undefined;
   if (
     existing &&
@@ -91,8 +93,8 @@ function getOrCreateRegistry(): PiTelegramExternalHandlerRegistry {
   ) {
     return existing;
   }
-  const handlers = new Set<PiTelegramInterceptor>();
-  const registry: PiTelegramExternalHandlerRegistry = {
+  const handlers = new Set<PiTelegramUpdateHandler>();
+  const registry: PiTelegramUpdateHandlerRegistry = {
     version: 1,
     add(handler) {
       handlers.add(handler);
@@ -104,7 +106,7 @@ function getOrCreateRegistry(): PiTelegramExternalHandlerRegistry {
           const result = await handler(update);
           if (result === "consume") return "consume";
         } catch {
-          // Never break polling because of an interceptor error.
+          // Never break polling because of a handler error.
         }
       }
       return "pass";
@@ -120,32 +122,32 @@ const off = getOrCreateRegistry().add((update) => {
 });
 ```
 
-The registry object on `globalThis.__piTelegramExternalHandlerRegistry__` is versioned (`version: 1`) and stable across pi-telegram releases; future breaking changes will use a new schema version and a new key.
+The registry object on `globalThis.__piTelegramUpdateHandlerRegistry__` is versioned (`version: 1`) and stable across pi-telegram releases; future breaking changes will use a new schema version and a new key.
 
 ## Interaction with built-in routing
 
-`pi-telegram` invokes registered interceptors first, then routes the update through its own handlers: commands, app menu, queue menu, model menu, default prompt routing, and callback namespace fallback. If any interceptor returns `"consume"`, `pi-telegram` skips the rest of routing for that update.
+`pi-telegram` invokes registered handlers first, then routes the update through its own handlers: commands, app menu, queue menu, model menu, default prompt routing, and callback namespace fallback. If any handler returns `"consume"`, `pi-telegram` skips the rest of routing for that update.
 
 This means:
 
 - Extensions can claim callback namespaces that `pi-telegram` would otherwise forward as `[callback] <data>` text.
 - Extensions can observe updates by always returning `"pass"`.
-- Extensions must not consume updates that belong to `pi-telegram`'s own prefixes (`tgbtn:`, `menu:`, `model:`, `thinking:`, `status:`, `queue:`) unless they are deliberately replacing that behavior.
+- Extensions must not consume updates that belong to `pi-telegram`'s own prefixes (`compact:`, `tgbtn:`, `menu:`, `model:`, `thinking:`, `status:`, `queue:`, `settings:`, `section:`) unless they are deliberately replacing that behavior.
 
 ## Ownership semantics
 
-The interceptor registry is ownership-agnostic and does not interact with the `locks.json` singleton lock documented in [Locks](./locks.md). When the locked polling runtime stops `pi-telegram`'s poller, for example after ownership is moved to another pi process, interceptors stop receiving updates because no updates are being fetched. They are not unregistered.
+The handler registry is ownership-agnostic and does not interact with the `locks.json` singleton lock documented in [Locks](./locks.md). When the locked polling runtime stops `pi-telegram`'s `getUpdates` loop, for example after ownership is moved to another pi process, handlers stop receiving updates because no updates are being fetched. They are not unregistered.
 
-If a layered extension needs to react to ownership changes, it should observe `pi-telegram` lifecycle events through the standard pi extension hooks rather than through the interceptor registry.
+If a layered extension needs to react to ownership changes, it should observe `pi-telegram` lifecycle events through the standard pi extension hooks rather than through the handler registry.
 
 ## Not a multiplexer
 
-This registry does not multiplex one bot across multiple pi processes, and it does not bypass Telegram's single-poller-per-bot constraint. To run multiple pi instances on Telegram, give each instance its own bot and its own `~/.pi/agent` directory; the registry is for layered extensions inside **one** pi process.
+This registry does not multiplex one bot across multiple pi processes, and it does not bypass Telegram's single-polling-connection-per-bot constraint. To run multiple pi instances on Telegram, give each instance its own bot and its own `~/.pi/agent` directory; the registry is for layered extensions inside **one** pi process.
 
 ## Relationship to extension sections
 
-External handlers are the raw update primitive. Extension sections are the structured Telegram UI layer above that primitive.
+Update handlers are the raw update primitive. Extension sections are the structured Telegram UI layer above that primitive.
 
-Use external handlers for immediate update interception, custom callback namespaces, out-of-band Promise resolution, and update types that should not become a Telegram menu surface.
+Use update handlers for immediate update interception, custom callback namespaces, out-of-band Promise resolution, and update types that should not become a Telegram menu surface.
 
 Use extension sections when the desired behavior is a menu-integrated UI: `render(ctx)`, managed callback dispatch, safe runtime ports, stale-callback handling, and diagnostics owned by `pi-telegram`.

package/docs/voice.md

@@ -1,6 +1,6 @@
 # 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.
+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 polling loop.
 
 ## Overview
 
@@ -29,7 +29,7 @@ Inbound handlers match `kind: "voice"` or `mime: "audio/*"` to run a transcripti
 
 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 provider extensions can also register STT backends with `registerTelegramVoiceTranscriptionProvider()` from `@llblab/pi-telegram/voice`. 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
 
@@ -79,7 +79,7 @@ The bridge shows a `record_voice` action while delivering and sends the final au
 
 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.
+Import provider APIs from `@llblab/pi-telegram/voice`; see the TSDoc on `registerTelegramVoiceSynthesisProvider` and `TelegramVoiceSynthesisProviderResult` there for the exact interface.
 
 The provider receives the raw agent text plus optional `{ lang?, rate? }`.
 
@@ -93,7 +93,7 @@ It must return one of:
 
 **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.
+Registration returns a disposer function for cleanup. Stable provider registrations pass a durable `id` in options; omitted ids remain a compatibility path for older providers and receive generated session-local ids. Extensions should call disposers on shutdown or re-register safely on session start when their runtime is recreated.
 
 ## Outbound Voice Handlers
 
@@ -124,14 +124,17 @@ Priority for outbound voice delivery is: configured `outboundHandlers` with `typ
 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 };
-});
+import { registerTelegramVoiceSynthesisProvider } from "@llblab/pi-telegram/voice";
+
+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 };
+  },
+  { id: "my-voice-provider/tts" },
+);
 ```
 
 The bridge never sends a separate transcript message. Caption-only is the "ON" behavior.
@@ -141,7 +144,7 @@ The bridge never sends a separate transcript message. Caption-only is the "ON" b
 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";
+import { recordTelegramRuntimeEvent } from "@llblab/pi-telegram/outbound";
 
 recordTelegramRuntimeEvent("xai-voice", new Error("TTS failed"), {
   phase: "tts",
@@ -155,7 +158,7 @@ recordTelegramRuntimeEvent("xai-voice", new Error("TTS failed"), {
 
 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`.
+**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