@llblab/pi-telegram 0.11.2 → 0.13.0

package/lib/polling.ts

@@ -1,5 +1,5 @@
 /**
- * Telegram polling domain helpers
+ * Telegram polling runtime domain helpers
  * Zones: telegram transport, polling runtime
  * Owns polling request builders, stop conditions, and the long-poll loop runtime for Telegram updates
  */
@@ -91,8 +91,9 @@ export function createTelegramPollingActivityReader(
   return () => isTelegramPollingControllerActive(state);
 }
 
-export interface TelegramPollingRuntimeDeps<TContext>
-  extends TelegramRuntimeEventRecorderPort {
+export interface TelegramPollingRuntimeDeps<
+  TContext,
+> extends TelegramRuntimeEventRecorderPort {
   hasBotToken: () => boolean;
   getPollingPromise: () => Promise<void> | undefined;
   setPollingPromise: (promise: Promise<void> | undefined) => void;

package/lib/preview.ts

@@ -9,7 +9,7 @@ import type {
   TelegramReplyParameters,
   TelegramSendMessageBody,
   TelegramSentMessage,
-} from "./api.ts";
+} from "./telegram-api.ts";
 import {
   buildTelegramPreviewSnapshot,
   MAX_MESSAGE_LENGTH,
@@ -22,7 +22,7 @@ import {
 } from "./rendering.ts";
 
 import { buildTelegramReplyParameters } from "./replies.ts";
-import { stripTelegramCommentMarkupForPreview } from "./outbound-handlers.ts";
+import { stripTelegramCommentMarkupForPreview } from "./outbound.ts";
 import { shouldSuppressPreviewForVoice } from "./voice.ts";
 
 const TELEGRAM_PREVIEW_THROTTLE_MS = 750;

package/lib/queue.ts

@@ -44,6 +44,9 @@ export interface TelegramQueueLaneContract {
 
 export const TELEGRAM_QUEUE_LANE_CONTRACTS: readonly TelegramQueueLaneContract[] =
   [
+    // Control lane intentionally accepts both direct controls and resume prompts.
+    // Model-switch continuations need prompt semantics but must run before queued user work.
+    // Do not admit ordinary user prompts here without an explicit control-flow reason.
     {
       lane: "control",
       admissionMode: "control-queue",

package/lib/replies.ts

@@ -4,7 +4,10 @@
  * Owns rendered-message delivery, reply transport wiring, and plain or markdown final replies
  */
 
-import type { TelegramReplyParameters, TelegramSentMessage } from "./api.ts";
+import type {
+  TelegramReplyParameters,
+  TelegramSentMessage,
+} from "./telegram-api.ts";
 import {
   renderTelegramMessage,
   type TelegramRenderedChunk,

package/lib/routing.ts

@@ -7,12 +7,12 @@
 import { readFile } from "node:fs/promises";
 import * as Commands from "./commands.ts";
 import type { TelegramConfigStore } from "./config.ts";
-import type { TelegramSectionRegistry } from "./extension-sections.ts";
-import type { TelegramInboundHandlerRuntime } from "./inbound-handlers.ts";
+import type { TelegramSectionRegistry } from "./sections.ts";
+import type { TelegramInboundHandlerRuntime } from "./inbound.ts";
 import * as Media from "./media.ts";
 import * as Menu from "./menu.ts";
 import * as Model from "./model.ts";
-import * as OutboundHandlers from "./outbound-handlers.ts";
+import * as OutboundHandlers from "./outbound.ts";
 import * as PromptTemplates from "./prompt-templates.ts";
 import * as Queue from "./queue.ts";
 import type { TelegramBridgeRuntime } from "./runtime.ts";
@@ -138,6 +138,7 @@ export interface TelegramInboundRouteRuntimeDeps<
 }
 
 const TELEGRAM_OWNED_CALLBACK_PREFIXES = [
+  "compact:",
   "menu:",
   "model:",
   "queue:",
@@ -262,6 +263,45 @@ export function createTelegramInboundRouteRuntime<
       );
       if (handled) return;
     }
+    const handledByCompact =
+      await Commands.handleTelegramCompactConfirmationCallback(query, {
+        ctx,
+        answerCallbackQuery: deps.answerCallbackQuery,
+        editInteractiveMessage: deps.editInteractiveMessage ?? (async () => {}),
+        runCompact: async (compactCtx, chatId, replyToMessageId) => {
+          await Commands.handleTelegramCompactCommand({
+            isIdle: () => deps.isIdle(compactCtx),
+            hasPendingMessages: () => deps.hasPendingMessages(compactCtx),
+            hasActiveTelegramTurn: deps.activeTurnRuntime.has,
+            hasDispatchPending: deps.bridgeRuntime.lifecycle.hasDispatchPending,
+            hasQueuedTelegramItems: deps.telegramQueueStore.hasQueuedItems,
+            isCompactionInProgress:
+              deps.bridgeRuntime.lifecycle.isCompactionInProgress,
+            setCompactionInProgress:
+              deps.bridgeRuntime.lifecycle.setCompactionInProgress,
+            updateStatus: () => deps.updateStatus(compactCtx),
+            dispatchNextQueuedTelegramTurn: () =>
+              deps.dispatchNextQueuedTelegramTurn(compactCtx),
+            requestDeferredDispatchNextQueuedTelegramTurn:
+              deps.requestDeferredDispatchNextQueuedTelegramTurn
+                ? (dispatch) =>
+                    deps.requestDeferredDispatchNextQueuedTelegramTurn?.(() =>
+                      dispatch(),
+                    )
+                : undefined,
+            compact: (callbacks) => deps.compact(compactCtx, callbacks),
+            startTypingLoop: deps.startTypingLoop
+              ? () => deps.startTypingLoop?.(compactCtx, chatId)
+              : undefined,
+            stopTypingLoop: deps.stopTypingLoop,
+            sendTextReply: (text) =>
+              deps.sendTextReply(chatId, replyToMessageId, text).then(() => {}),
+            suppressStartNotice: true,
+            recordRuntimeEvent: deps.recordRuntimeEvent,
+          });
+        },
+      });
+    if (handledByCompact) return;
     const handledByQueue = await deps.queueMenuCallbackHandler(query, ctx);
     if (handledByQueue) return;
     const handledBySettings = await deps.settingsMenuCallbackHandler?.(
@@ -372,6 +412,7 @@ export function createTelegramInboundRouteRuntime<
     getPromptTemplateCommands,
     persistConfig: deps.configStore.persist,
     sendTextReply: deps.sendTextReply,
+    sendInteractiveMessage: deps.sendInteractiveMessage,
     recordRuntimeEvent: deps.recordRuntimeEvent,
   });
   const promptEnqueue = Queue.createTelegramPromptEnqueueController<

package/lib/{extension-sections.ts → sections.ts}

@@ -1,12 +1,13 @@
 /**
  * Telegram Extension Sections registry and callback routing
  * Zones: telegram ui, extension platform, callback routing
- * Owns section registration, token mapping, main-menu/settings row injection, and section callback dispatch
+ * Owns section registration, global registry binding, token mapping, main-menu/settings row injection, and section callback dispatch
  */
 
 import type { TelegramInlineKeyboardMarkup } from "./keyboard.ts";
 
 const SECTION_REGISTRY_KEY = "__piTelegramSectionRegistry__";
+const TELEGRAM_CALLBACK_DATA_MAX_BYTES = 64;
 
 // --- Core Types ---
 
@@ -181,9 +182,7 @@ function buildTelegramSectionContext(
         .then(() => {}),
     enqueuePrompt: deps.enqueuePrompt,
     callbackData: (action, payload) =>
-      payload
-        ? `section:${token}:${action}:${payload}`
-        : `section:${token}:${action}`,
+      buildTelegramSectionCallbackData(token, action, payload),
     deleteMessage: () =>
       messageId !== undefined
         ? deps.deleteMessage(chatId, messageId)
@@ -231,9 +230,7 @@ function buildTelegramSectionCallbackContext(
         .then(() => {}),
     enqueuePrompt: deps.enqueuePrompt,
     callbackData: (action, payload) =>
-      payload
-        ? `section:${token}:${action}:${payload}`
-        : `section:${token}:${action}`,
+      buildTelegramSectionCallbackData(token, action, payload),
     deleteMessage: () =>
       messageId !== undefined
         ? deps.deleteMessage(chatId, messageId)
@@ -250,6 +247,13 @@ export function setGlobalTelegramSectionRegistry(
   (globalThis as Record<string, unknown>)[SECTION_REGISTRY_KEY] = registry;
 }
 
+/** @internal */
+export function createAndBindTelegramSectionRegistry(): TelegramSectionRegistry {
+  const registry = createTelegramExtensionSectionRegistry();
+  setGlobalTelegramSectionRegistry(registry);
+  return registry;
+}
+
 /**
  * Register a Telegram Extension Section from any pi extension.
  * Returns a disposer. Throws if no section registry is active.
@@ -271,8 +275,8 @@ export function registerTelegramSection(
 
 /**
  * Get current section diagnostics. Returns empty array when registry is absent.
+ * @internal
  */
-/** @internal */
 export function getTelegramSectionDiagnostics(): TelegramSectionDiagnostic[] {
   const registry = (globalThis as Record<string, unknown>)[
     SECTION_REGISTRY_KEY
@@ -291,6 +295,27 @@ const BACK_NAV_ROW = {
   text: "⬆️ Back",
 } as const;
 
+function getUtf8ByteLength(value: string): number {
+  return new TextEncoder().encode(value).byteLength;
+}
+
+function buildTelegramSectionCallbackData(
+  token: TelegramSectionToken,
+  action: string,
+  payload?: string,
+): string {
+  const data = payload
+    ? `section:${token}:${action}:${payload}`
+    : `section:${token}:${action}`;
+  const byteLength = getUtf8ByteLength(data);
+  if (byteLength > TELEGRAM_CALLBACK_DATA_MAX_BYTES) {
+    throw new Error(
+      `Telegram section callback_data exceeds ${TELEGRAM_CALLBACK_DATA_MAX_BYTES} bytes (${byteLength}). Use a shorter action/payload or store state behind a compact key.`,
+    );
+  }
+  return data;
+}
+
 function prependBackRow(
   replyMarkup: TelegramInlineKeyboardMarkup | undefined,
   backCallback: string,
@@ -319,6 +344,10 @@ export function createTelegramExtensionSectionRegistry(): TelegramSectionRegistr
   let nextToken = 0;
 
   function register(section: TelegramSectionRegistration): () => void {
+    const duplicate = [...sections.values()].find((s) => s.id === section.id);
+    if (duplicate) {
+      throw new Error(`Telegram section id already registered: ${section.id}`);
+    }
     const token = String(nextToken++);
     const registered: RegisteredTelegramSection = {
       id: section.id,

package/lib/status.ts

@@ -289,12 +289,25 @@ function formatTelegramRuntimeEvent(event: TelegramRuntimeEvent): string {
   return `${new Date(event.at).toISOString()} ${formatTelegramRuntimeEventSummary(event)}`;
 }
 
+function buildTelegramRuntimeEventSummary(events: TelegramRuntimeEvent[]): string {
+  const counts = new Map<string, number>();
+  for (const event of events) {
+    const category = formatTelegramRuntimeEventCategory(event);
+    counts.set(category, (counts.get(category) ?? 0) + 1);
+  }
+  return Array.from(counts.entries())
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([category, count]) => `${category}=${count}`)
+    .join(", ");
+}
+
 export function buildTelegramRuntimeEventLines(
   events: TelegramRuntimeEvent[],
 ): string[] {
   if (events.length === 0) return ["recent runtime events: none"];
   return [
     "recent runtime events:",
+    `- summary: ${buildTelegramRuntimeEventSummary(events)}`,
     ...events
       .slice()
       .reverse()

package/lib/{api.ts → telegram-api.ts}

@@ -416,13 +416,13 @@ async function writeTelegramDownloadResponse(
   if (!response.body) {
     const buffer = Buffer.from(await response.arrayBuffer());
     assertTelegramFileSizeWithinLimit(buffer.byteLength, maxFileSizeBytes);
-    await writeFile(targetPath, buffer);
+    await writeFile(targetPath, buffer, { mode: 0o600 });
     return;
   }
   await pipeline(
     Readable.from(response.body, { objectMode: false }),
     createTelegramDownloadLimitTransform(maxFileSizeBytes),
-    createWriteStream(targetPath),
+    createWriteStream(targetPath, { mode: 0o600 }),
   );
 }
 
@@ -536,7 +536,7 @@ export async function prepareTelegramTempDir(
   tempDir: string,
   maxAgeMs: number,
 ): Promise<number> {
-  await mkdir(tempDir, { recursive: true });
+  await mkdir(tempDir, { recursive: true, mode: 0o700 });
   return cleanupTelegramTempFiles(tempDir, maxAgeMs);
 }
 
@@ -630,7 +630,7 @@ export async function downloadTelegramFile(
     { signal: options?.signal },
   );
   assertTelegramFileSizeWithinLimit(file.file_size, options?.maxFileSizeBytes);
-  await mkdir(tempDir, { recursive: true });
+  await mkdir(tempDir, { recursive: true, mode: 0o700 });
   const targetPath = join(
     tempDir,
     `${randomUUID()}-${sanitizeFileName(suggestedName)}`,

package/lib/text-groups.ts

@@ -6,7 +6,7 @@
 
 const TELEGRAM_TEXT_GROUP_DEBOUNCE_MS = 1000;
 const TELEGRAM_TEXT_GROUP_MIN_SPLIT_LENGTH = 3600;
-const TELEGRAM_TEXT_GROUP_MAX_MESSAGE_ID_GAP = 10;
+const TELEGRAM_TEXT_GROUP_MAX_MESSAGE_ID_GAP = 12;
 
 export interface TelegramTextGroupMessage {
   message_id: number;
@@ -92,7 +92,8 @@ function canAppendTelegramTextGroupMessage<
   return (
     !!previous &&
     message.message_id > previous.message_id &&
-    message.message_id <= previous.message_id + TELEGRAM_TEXT_GROUP_MAX_MESSAGE_ID_GAP &&
+    message.message_id <=
+      previous.message_id + TELEGRAM_TEXT_GROUP_MAX_MESSAGE_ID_GAP &&
     text.length > 0 &&
     !isTelegramTextGroupCommand(text)
   );

package/lib/updates.ts

@@ -1,7 +1,7 @@
 /**
  * Telegram updates domain helpers
  * Zones: telegram inbound, authorization, routing plans
- * Owns update extraction, authorization, classification, execution planning, and runtime execution for Telegram updates
+ * Owns update extraction, authorization, classification, execution planning, runtime execution, and the public update-handler registry
  */
 
 import {
@@ -851,3 +851,123 @@ export async function executeTelegramUpdatePlan<
     if (!isTelegramStaleContextError(error)) throw error;
   }
 }
+
+// --- Public update handler registry ---
+
+/**
+ * Verdict returned by a public Telegram update handler.
+ *
+ * - `"consume"` — the handler processed this update; pi-telegram skips default routing.
+ * - `"pass"` (or `void`/`undefined`) — pi-telegram routes the update normally.
+ */
+export type TelegramUpdateHandlerVerdict = "consume" | "pass";
+
+export type TelegramUpdateHandler = (
+  update: unknown,
+) =>
+  | TelegramUpdateHandlerVerdict
+  | void
+  | Promise<TelegramUpdateHandlerVerdict | void>;
+
+export interface TelegramUpdateHandlerRegistry {
+  /** Schema version of this registry shape. */
+  readonly version: 1;
+  /**
+   * Register an update handler. Returns a disposer that removes it.
+   *
+   * Handlers are invoked in registration order on every Telegram update,
+   * before pi-telegram's own routing. The first handler that returns
+   * `"consume"` wins and stops the chain for that update.
+   */
+  add: (handler: TelegramUpdateHandler) => () => void;
+  /**
+   * Run all registered handlers against an update.
+   *
+   * Used by pi-telegram's polling runtime; companion extensions should call
+   * {@link registerTelegramUpdateHandler} or `add` instead of dispatching directly.
+   */
+  dispatch: (update: unknown) => Promise<TelegramUpdateHandlerVerdict>;
+}
+
+const UPDATE_HANDLER_REGISTRY_KEY = "__piTelegramUpdateHandlerRegistry__";
+
+function isValidV1UpdateHandlerRegistry(
+  candidate: unknown,
+): candidate is TelegramUpdateHandlerRegistry {
+  if (!candidate || typeof candidate !== "object") return false;
+  const r = candidate as Partial<TelegramUpdateHandlerRegistry>;
+  return (
+    r.version === 1 &&
+    typeof r.add === "function" &&
+    typeof r.dispatch === "function"
+  );
+}
+
+function getOrCreateUpdateHandlerRegistry(): TelegramUpdateHandlerRegistry {
+  const g = globalThis as Record<string, unknown>;
+  const existing = g[UPDATE_HANDLER_REGISTRY_KEY];
+  if (isValidV1UpdateHandlerRegistry(existing)) return existing;
+  const handlers = new Set<TelegramUpdateHandler>();
+  const registry: TelegramUpdateHandlerRegistry = {
+    version: 1,
+    add(handler) {
+      handlers.add(handler);
+      return () => handlers.delete(handler);
+    },
+    async dispatch(update) {
+      for (const handler of handlers) {
+        try {
+          const result = await handler(update);
+          if (result === "consume") return "consume";
+        } catch {
+          // Update handler errors must not break polling.
+        }
+      }
+      return "pass";
+    },
+  };
+  g[UPDATE_HANDLER_REGISTRY_KEY] = registry;
+  return registry;
+}
+
+/**
+ * Called by pi-telegram's own runtime to obtain the registry it dispatches
+ * through. Companion extensions should not call this; use
+ * {@link registerTelegramUpdateHandler} instead.
+ */
+export function getTelegramUpdateHandlerRegistry(): TelegramUpdateHandlerRegistry {
+  return getOrCreateUpdateHandlerRegistry();
+}
+
+export interface TelegramUpdateHandlerWrapDeps<TUpdate, TContext> {
+  defaultHandle: (update: TUpdate, ctx: TContext) => Promise<void>;
+  registry?: TelegramUpdateHandlerRegistry;
+}
+
+/**
+ * Wrap a default polling `handleUpdate` with the public update handler registry.
+ */
+export function createTelegramUpdateHandle<TUpdate, TContext>(
+  deps: TelegramUpdateHandlerWrapDeps<TUpdate, TContext>,
+): (update: TUpdate, ctx: TContext) => Promise<void> {
+  const registry = deps.registry ?? getOrCreateUpdateHandlerRegistry();
+  const { defaultHandle } = deps;
+  return async function handleTelegramUpdate(update, ctx) {
+    const verdict = await registry.dispatch(update);
+    if (verdict === "consume") return;
+    await defaultHandle(update, ctx);
+  };
+}
+
+/**
+ * Register a handler that runs before pi-telegram routes a Telegram update
+ * through its built-in handlers.
+ *
+ * This is the low-level public surface for companion extensions that share
+ * the same bot and pi process with pi-telegram.
+ */
+export function registerTelegramUpdateHandler(
+  handler: TelegramUpdateHandler,
+): () => void {
+  return getOrCreateUpdateHandlerRegistry().add(handler);
+}

package/lib/voice.ts

@@ -12,16 +12,32 @@
  *
  * Separation of concerns:
  * - All decision logic and domain rules live here.
- * - Actual delivery (sending the audio via Telegram) stays in outbound-handlers.ts.
+ * - Actual delivery (sending the audio via Telegram) stays in outbound.ts.
  *
  * Keeps voice policy, turn tagging, prompt contributions, and markup helpers
  * out of the queue, preview, turn-building, and delivery domains.
  */
 
-const VOICE_SYNTHESIS_PROVIDER_REGISTRY_KEY = "__piTelegramVoiceSynthesisProviders__";
+const VOICE_SYNTHESIS_PROVIDER_REGISTRY_KEY =
+  "__piTelegramVoiceSynthesisProviders__";
 const VOICE_TRANSCRIPTION_PROVIDER_REGISTRY_KEY =
   "__piTelegramVoiceTranscriptionProviders__";
 
+let nextGeneratedVoiceSynthesisProviderId = 0;
+let nextGeneratedVoiceTranscriptionProviderId = 0;
+
+function getNextAvailableProviderId<T>(
+  registry: Map<string, T>,
+  prefix: string,
+  nextId: () => number,
+): string {
+  let id: string;
+  do {
+    id = `${prefix}-${nextId()}`;
+  } while (registry.has(id));
+  return id;
+}
+
 export type TelegramVoiceReplyMode = "mirror" | "always" | "manual";
 
 export type TelegramVoiceSynthesisProviderResult =
@@ -81,11 +97,20 @@ function getOrCreateVoiceSynthesisProviderRegistry(): Map<
   if (existing instanceof Map)
     return existing as Map<string, TelegramVoiceSynthesisProvider>;
   const registry = new Map<string, TelegramVoiceSynthesisProvider>();
-  (globalThis as Record<string, unknown>)[VOICE_SYNTHESIS_PROVIDER_REGISTRY_KEY] =
-    registry;
+  (globalThis as Record<string, unknown>)[
+    VOICE_SYNTHESIS_PROVIDER_REGISTRY_KEY
+  ] = registry;
   return registry;
 }
 
+/**
+ * Register a high-level Telegram voice synthesis provider.
+ *
+ * Stable public API callers must pass a stable `options.id` so diagnostics,
+ * replacement, and cleanup can identify the provider. Omitted ids remain a
+ * compatibility path for pre-matrix callers and receive generated session-local
+ * ids.
+ */
 export function registerTelegramVoiceSynthesisProvider(
   provider:
     | TelegramVoiceSynthesisProvider
@@ -96,22 +121,30 @@ export function registerTelegramVoiceSynthesisProvider(
   options?: { id?: string },
 ): () => void {
   const registry = getOrCreateVoiceSynthesisProviderRegistry();
-  const id = options?.id ?? `voice-synthesis-provider-${registry.size}`;
+  const id =
+    options?.id ??
+    getNextAvailableProviderId(
+      registry,
+      "voice-synthesis-provider",
+      () => nextGeneratedVoiceSynthesisProviderId++,
+    );
   const normalized =
     typeof provider === "function"
       ? (Object.assign(
           (text: string, options?: { lang?: string; rate?: string }) =>
             provider(text, options),
           {
-            getVoicePolicy: (provider as TelegramVoiceSynthesisProvider).getVoicePolicy,
-            getVoicePromptContribution: (provider as TelegramVoiceSynthesisProvider)
-              .getVoicePromptContribution,
+            getVoicePolicy: (provider as TelegramVoiceSynthesisProvider)
+              .getVoicePolicy,
+            getVoicePromptContribution: (
+              provider as TelegramVoiceSynthesisProvider
+            ).getVoicePromptContribution,
           },
         ) as TelegramVoiceSynthesisProvider)
       : provider;
   registry.set(id, normalized);
   return () => {
-    registry.delete(id);
+    if (registry.get(id) === normalized) registry.delete(id);
   };
 }
 
@@ -144,15 +177,28 @@ function getOrCreateVoiceTranscriptionProviderRegistry(): Map<
   return registry;
 }
 
+/**
+ * Register a high-level Telegram voice transcription provider.
+ *
+ * Stable public API callers must pass a stable `options.id`. Omitted ids remain
+ * a compatibility path for pre-matrix callers and receive generated
+ * session-local ids.
+ */
 export function registerTelegramVoiceTranscriptionProvider(
   provider: TelegramVoiceTranscriptionProvider,
   options?: { id?: string },
 ): () => void {
   const registry = getOrCreateVoiceTranscriptionProviderRegistry();
-  const id = options?.id ?? `voice-transcription-provider-${registry.size}`;
+  const id =
+    options?.id ??
+    getNextAvailableProviderId(
+      registry,
+      "voice-transcription-provider",
+      () => nextGeneratedVoiceTranscriptionProviderId++,
+    );
   registry.set(id, provider);
   return () => {
-    registry.delete(id);
+    if (registry.get(id) === provider) registry.delete(id);
   };
 }
 
@@ -182,9 +228,9 @@ export const TELEGRAM_VOICE_REPLY_MODES = [
  * Pi-telegram owns reply-mode policy through telegram.json. If
  * config.voice.replyMode is missing or invalid, the safe default is manual.
  */
-export function getTelegramVoiceReplyMode(
-  config?: { voice?: { replyMode?: string } },
-): TelegramVoiceReplyMode {
+export function getTelegramVoiceReplyMode(config?: {
+  voice?: { replyMode?: string };
+}): TelegramVoiceReplyMode {
   const configMode = config?.voice?.replyMode;
   if (
     configMode &&
@@ -202,9 +248,9 @@ export function getTelegramVoiceReplyMode(
  * Reads from `config.voice.sendTranscript`.
  * Default: false (no transcript text sent at all).
  */
-export function getTelegramVoiceSendTranscript(
-  config?: { voice?: { sendTranscript?: boolean } },
-): boolean {
+export function getTelegramVoiceSendTranscript(config?: {
+  voice?: { sendTranscript?: boolean };
+}): boolean {
   return !!config?.voice?.sendTranscript;
 }
 
@@ -284,12 +330,12 @@ export function shouldSuppressPreviewForVoice(
   return !!(turn?.voiceReplyPreferred || turn?.voiceReplyRequired);
 }
 
-// --- Outbound Handler Re-Exports ---
+// --- Outbound Markup Re-Exports ---
 
 export {
+  normalizeMarkdownAfterVoiceExtraction,
   planTelegramVoiceReply,
-  stripTelegramCommentMarkupForPreview,
   stripTelegramCommentMarkupForDelivery,
+  stripTelegramCommentMarkupForPreview,
   stripTelegramVoiceMarkupForPreview,
-  normalizeMarkdownAfterVoiceExtraction,
-} from "./outbound-handlers.ts";
+} from "./outbound-markup.ts";

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.11.2",
+  "version": "0.13.0",
   "private": false,
   "publishConfig": {
     "access": "public"
   },
   "description": "Telegram runtime adapter for π",
-  "type": "module",
   "keywords": [
     "pi-package",
     "pi",
@@ -14,6 +13,7 @@
     "bot",
     "extension"
   ],
+  "type": "module",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -24,7 +24,7 @@
     "url": "https://github.com/llblab/pi-telegram/issues"
   },
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.19.0"
   },
   "scripts": {
     "test": "node --experimental-strip-types --test tests/*.test.ts",
@@ -35,6 +35,7 @@
   },
   "files": [
     "index.ts",
+    "api/",
     "lib/",
     "README.md",
     "AGENTS.md",
@@ -43,6 +44,15 @@
     "docs/",
     "screenshot.png"
   ],
+  "exports": {
+    ".": "./index.ts",
+    "./inbound": "./api/inbound.ts",
+    "./outbound": "./api/outbound.ts",
+    "./updates": "./api/updates.ts",
+    "./sections": "./api/sections.ts",
+    "./voice": "./api/voice.ts",
+    "./keyboard": "./api/keyboard.ts"
+  },
   "pi": {
     "extensions": [
       "./index.ts"