@llblab/pi-telegram 0.10.8 → 0.11.1

package/lib/config.ts

@@ -12,6 +12,8 @@ import { join, resolve } from "node:path";
 import type { TelegramInboundHandlerConfig } from "./inbound-handlers.ts";
 import type { CommandTemplateObjectConfig } from "./command-templates.ts";
 
+const CONFIG_RUNTIME_KEY = "__piTelegramConfigRuntime__";
+
 function getAgentDir(): string {
   return process.env.PI_CODING_AGENT_DIR
     ? resolve(process.env.PI_CODING_AGENT_DIR)
@@ -33,6 +35,19 @@ export interface TelegramOutboundHandlerConfig extends CommandTemplateObjectConf
   timeout?: number;
 }
 
+export type TelegramTimeMode = "off" | "always" | "interval";
+
+export interface TelegramTimeConfig {
+  injectionMode?: TelegramTimeMode;
+  interval?: number;
+}
+
+export interface ResolvedTelegramTimeConfig {
+  injectionMode: TelegramTimeMode;
+  interval: number;
+  timezone: string;
+}
+
 export interface TelegramConfig {
   botToken?: string;
   botUsername?: string;
@@ -43,6 +58,12 @@ export interface TelegramConfig {
   attachmentHandlers?: TelegramInboundHandlerConfig[];
   outboundHandlers?: TelegramOutboundHandlerConfig[];
   proactivePush?: boolean;
+  voice?: {
+    replyMode?: "manual" | "mirror" | "always";
+    /** Whether to attach the provider's transcriptText as caption on voice messages */
+    sendTranscript?: boolean;
+  };
+  time?: TelegramTimeConfig;
 }
 
 export interface TelegramConfigStore {
@@ -66,6 +87,29 @@ export interface TelegramConfigStoreOptions {
   configPath?: string;
 }
 
+export interface TelegramConfigRuntime {
+  updateVoiceConfig: (voice: NonNullable<TelegramConfig["voice"]>) => void;
+}
+
+export function setGlobalTelegramConfigRuntime(
+  runtime: TelegramConfigRuntime | undefined,
+): void {
+  const globals = globalThis as Record<string, unknown>;
+  if (runtime) globals[CONFIG_RUNTIME_KEY] = runtime;
+  else delete globals[CONFIG_RUNTIME_KEY];
+}
+
+export function updateTelegramVoiceConfig(
+  voice: NonNullable<TelegramConfig["voice"]>,
+): boolean {
+  const runtime = (globalThis as Record<string, unknown>)[
+    CONFIG_RUNTIME_KEY
+  ] as TelegramConfigRuntime | undefined;
+  if (!runtime || typeof runtime.updateVoiceConfig !== "function") return false;
+  runtime.updateVoiceConfig(voice);
+  return true;
+}
+
 export async function readTelegramConfig(
   configPath: string,
 ): Promise<TelegramConfig> {
@@ -141,6 +185,96 @@ export function createTelegramProactivePushSetter(
   };
 }
 
+export function createTelegramVoiceReplyModeGetter(
+  configStore: Pick<TelegramConfigStore, "get">,
+): () => "manual" | "mirror" | "always" {
+  return () => {
+    const mode = configStore.get().voice?.replyMode;
+    return mode === "mirror" || mode === "always" || mode === "manual"
+      ? mode
+      : "manual";
+  };
+}
+
+export function createTelegramVoiceReplyModeConfiguredChecker(
+  configStore: Pick<TelegramConfigStore, "get">,
+): () => boolean {
+  return () => {
+    const mode = configStore.get().voice?.replyMode;
+    return mode === "mirror" || mode === "always" || mode === "manual";
+  };
+}
+
+export function createTelegramVoiceReplyModeSetter(
+  configStore: Pick<TelegramConfigStore, "get" | "set" | "persist">,
+): (replyMode: "manual" | "mirror" | "always" | undefined) => Promise<void> {
+  return async (replyMode) => {
+    const current = configStore.get();
+    if (replyMode === undefined) {
+      const { replyMode: _replyMode, ...remainingVoice } = current.voice ?? {};
+      const next = { ...current };
+      if (Object.keys(remainingVoice).length > 0) next.voice = remainingVoice;
+      else delete next.voice;
+      configStore.set(next);
+      await configStore.persist(next);
+      return;
+    }
+    const next = { ...current, voice: { ...(current.voice ?? {}), replyMode } };
+    configStore.set(next);
+    await configStore.persist(next);
+  };
+}
+
+function getSystemTimezone(): string {
+  try {
+    const tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    return tz && tz.length > 0 ? tz : "UTC";
+  } catch {
+    return "UTC";
+  }
+}
+
+export function resolveTelegramTimeConfig(
+  raw: TelegramTimeConfig | undefined,
+): ResolvedTelegramTimeConfig {
+  const injectionMode: TelegramTimeMode =
+    raw?.injectionMode === "always" || raw?.injectionMode === "interval"
+      ? raw.injectionMode
+      : "off";
+  const interval =
+    typeof raw?.interval === "number" && raw.interval > 0
+      ? raw.interval
+      : 60 * 60 * 1000;
+  const timezone = getSystemTimezone();
+  return { injectionMode, interval, timezone };
+}
+
+export function createTelegramTimeConfigGetter(
+  configStore: Pick<TelegramConfigStore, "get">,
+): () => ResolvedTelegramTimeConfig {
+  return () => resolveTelegramTimeConfig(configStore.get().time);
+}
+
+export function createTelegramTimeInjectionModeGetter(
+  configStore: Pick<TelegramConfigStore, "get">,
+): () => TelegramTimeMode {
+  return () => resolveTelegramTimeConfig(configStore.get().time).injectionMode;
+}
+
+export function createTelegramTimeInjectionModeSetter(
+  configStore: Pick<TelegramConfigStore, "get" | "set" | "persist">,
+): (injectionMode: TelegramTimeMode) => Promise<void> {
+  return async (injectionMode) => {
+    const current = configStore.get();
+    const next = {
+      ...current,
+      time: { ...(current.time ?? {}), injectionMode },
+    };
+    configStore.set(next);
+    await configStore.persist(next);
+  };
+}
+
 export function createTelegramProactivePushChatIdGetter(deps: {
   getActiveTurnChatId: () => number | undefined;
   getAllowedUserId: () => number | undefined;

package/lib/extension-sections.ts

@@ -6,10 +6,17 @@
 
 import type { TelegramInlineKeyboardMarkup } from "./keyboard.ts";
 
+const SECTION_REGISTRY_KEY = "__piTelegramSectionRegistry__";
+
 // --- Core Types ---
 
+/** @internal */
 export type TelegramSectionId = string;
+
+/** @internal */
 export type TelegramSectionToken = string;
+
+/** @internal */
 export type TelegramSectionCallbackResult = "handled" | "pass";
 
 export interface TelegramSectionView {
@@ -34,6 +41,7 @@ export interface TelegramSectionRegistration {
   id: TelegramSectionId;
   label: string;
   order?: number;
+  getLabel?: () => string;
   render: (
     ctx: TelegramSectionContext,
   ) => TelegramSectionView | Promise<TelegramSectionView>;
@@ -71,6 +79,7 @@ export interface TelegramSectionCallbackContext {
   deleteMessage(): Promise<void>;
 }
 
+/** @internal */
 export interface RegisteredTelegramSection {
   id: TelegramSectionId;
   token: TelegramSectionToken;
@@ -79,6 +88,7 @@ export interface RegisteredTelegramSection {
   registration: TelegramSectionRegistration;
 }
 
+/** @internal */
 export interface TelegramSectionDiagnostic {
   id: TelegramSectionId;
   token: TelegramSectionToken;
@@ -87,6 +97,7 @@ export interface TelegramSectionDiagnostic {
   lastError?: string;
 }
 
+/** @internal */
 export interface TelegramSectionRegistry {
   register(section: TelegramSectionRegistration): () => void;
   getSections(): RegisteredTelegramSection[];
@@ -97,11 +108,13 @@ export interface TelegramSectionRegistry {
   clear(): void;
 }
 
+/** @internal */
 export interface TelegramSectionMainMenuRow {
   text: string;
   callback_data: string;
 }
 
+/** @internal */
 export interface TelegramSectionSettingsRow {
   label: string;
   callback_data: string;
@@ -109,6 +122,7 @@ export interface TelegramSectionSettingsRow {
 
 // --- Runtime Port Builders ---
 
+/** @internal */
 export interface TelegramSectionRuntimeDeps {
   answerCallbackQuery: (id: string, text?: string) => Promise<void>;
   editInteractiveMessage: (
@@ -229,17 +243,11 @@ function buildTelegramSectionCallbackContext(
 
 // --- GlobalThis Bridge ---
 
-const GLOBAL_SECTION_REGISTRY_KEY = "__piTelegramSectionRegistry__" as const;
-
-declare global {
-  // eslint-disable-next-line no-var
-  var __piTelegramSectionRegistry__: TelegramSectionRegistry | undefined;
-}
-
+/** @internal */
 export function setGlobalTelegramSectionRegistry(
   registry: TelegramSectionRegistry,
 ): void {
-  globalThis[GLOBAL_SECTION_REGISTRY_KEY] = registry;
+  (globalThis as Record<string, unknown>)[SECTION_REGISTRY_KEY] = registry;
 }
 
 /**
@@ -249,20 +257,26 @@ export function setGlobalTelegramSectionRegistry(
 export function registerTelegramSection(
   section: TelegramSectionRegistration,
 ): () => void {
-  const registry = globalThis[GLOBAL_SECTION_REGISTRY_KEY];
+  const registry = (globalThis as Record<string, unknown>)[
+    SECTION_REGISTRY_KEY
+  ] as TelegramSectionRegistry | undefined;
   if (!registry) {
     throw new Error(
-      "Telegram section registry not available. Is pi-telegram loaded?",
+      "Telegram section registry not available. Is pi-telegram loaded and initialized?",
     );
   }
+
   return registry.register(section);
 }
 
 /**
  * Get current section diagnostics. Returns empty array when registry is absent.
  */
+/** @internal */
 export function getTelegramSectionDiagnostics(): TelegramSectionDiagnostic[] {
-  const registry = globalThis[GLOBAL_SECTION_REGISTRY_KEY];
+  const registry = (globalThis as Record<string, unknown>)[
+    SECTION_REGISTRY_KEY
+  ] as TelegramSectionRegistry | undefined;
   return registry ? registry.getDiagnostics() : [];
 }
 
@@ -298,6 +312,7 @@ function prependBackRow(
   };
 }
 
+/** @internal */
 export function createTelegramExtensionSectionRegistry(): TelegramSectionRegistry {
   const sections = new Map<TelegramSectionToken, RegisteredTelegramSection>();
   const errors = new Map<TelegramSectionToken, string>();
@@ -351,15 +366,7 @@ export function createTelegramExtensionSectionRegistry(): TelegramSectionRegistr
   return { register, getSections, getByToken, getDiagnostics, clear };
 }
 
-export function getTelegramSectionMainMenuRows(
-  registry: TelegramSectionRegistry,
-): TelegramSectionMainMenuRow[] {
-  return registry.getSections().map((s) => ({
-    text: s.label,
-    callback_data: `section:${s.token}:open`,
-  }));
-}
-
+/** @internal */
 export function getTelegramExtensionSettingsRows(
   registry: TelegramSectionRegistry,
 ): TelegramSectionSettingsRow[] {
@@ -379,6 +386,17 @@ export function getTelegramExtensionSettingsRows(
     }));
 }
 
+/** @internal */
+export function getTelegramSectionMainMenuRows(
+  registry: TelegramSectionRegistry,
+): TelegramSectionMainMenuRow[] {
+  return registry.getSections().map((s) => ({
+    text: s.registration.getLabel?.() ?? s.label,
+    callback_data: `section:${s.token}:open`,
+  }));
+}
+
+/** @internal */
 export function parseTelegramSectionCallback(
   data: string,
 ): { token: string; action: string; payload: string } | undefined {
@@ -399,6 +417,7 @@ export function parseTelegramSectionCallback(
   };
 }
 
+/** @internal */
 export interface TelegramSectionCallbackHandlerDeps {
   answerCallbackQuery: (id: string, text?: string) => Promise<void>;
   editInteractiveMessage: (

package/lib/external-handlers.ts

@@ -155,10 +155,9 @@ export function createTelegramExternalHandleUpdate<TUpdate, TContext>(
  * off();
  * ```
  *
- * Extensions that prefer zero coupling can also reach the registry directly
- * via `globalThis.__piTelegramExternalHandlerRegistry__` (versioned object,
- * see {@link TelegramExternalHandlerRegistry}). This avoids importing
- * `@llblab/pi-telegram` and tolerates either install order.
+ * Extensions that prefer zero coupling can also reach the versioned registry
+ * directly on `globalThis`. This avoids importing `@llblab/pi-telegram` and
+ * tolerates either install order.
  */
 export function onTelegramExternalUpdate(
   handler: TelegramExternalHandler,

package/lib/inbound-handlers.ts

@@ -14,8 +14,10 @@ import {
   type CommandTemplateConfig,
   type CommandTemplateObjectConfig,
 } from "./command-templates.ts";
+import { getTelegramVoiceTranscriptionProviders } from "./voice.ts";
 
 const DEFAULT_INBOUND_HANDLER_TIMEOUT_MS = 120_000;
+const INBOUND_HANDLER_REGISTRY_KEY = "__piTelegramInboundHandlers__";
 
 type TelegramInboundCommandTemplateConfig =
   | string
@@ -96,6 +98,27 @@ export interface TelegramInboundHandlerRuntime<TContext> {
   ) => Promise<TelegramInboundHandlerProcessResult<TFile>>;
 }
 
+export type TelegramInboundProgrammaticHandlerResult =
+  | string
+  | { text: string }
+  | undefined;
+
+export interface TelegramInboundProgrammaticHandlerInput {
+  kind: string;
+  text?: string;
+  file?: TelegramInboundHandlerFile;
+  mimeType?: string;
+}
+
+export type TelegramInboundProgrammaticHandler = (
+  input: TelegramInboundProgrammaticHandlerInput,
+  options?: { cwd?: string },
+) => Promise<TelegramInboundProgrammaticHandlerResult>;
+
+export interface TelegramInboundHandlerRegistry {
+  handlers: Map<string, TelegramInboundProgrammaticHandler[]>;
+}
+
 interface InboundHandlerInvocation {
   command: string;
   args: string[];
@@ -103,6 +126,74 @@ interface InboundHandlerInvocation {
 
 const BUILT_IN_TEXT_ATTACHMENT_MAX_BYTES = 1_000_000;
 
+function getOrCreateInboundHandlerRegistry(): TelegramInboundHandlerRegistry {
+  const existing = (globalThis as Record<string, unknown>)[
+    INBOUND_HANDLER_REGISTRY_KEY
+  ];
+  if (
+    existing &&
+    typeof existing === "object" &&
+    existing !== null &&
+    "handlers" in existing &&
+    existing.handlers instanceof Map
+  ) {
+    return existing as TelegramInboundHandlerRegistry;
+  }
+  const registry: TelegramInboundHandlerRegistry = {
+    handlers: new Map(),
+  };
+  (globalThis as Record<string, unknown>)[INBOUND_HANDLER_REGISTRY_KEY] =
+    registry;
+  return registry;
+}
+
+export function registerTelegramInboundHandler(
+  kind: string,
+  handler: TelegramInboundProgrammaticHandler,
+): () => void {
+  const normalizedKind = kind.trim() || "*";
+  const registry = getOrCreateInboundHandlerRegistry();
+  const list = registry.handlers.get(normalizedKind) ?? [];
+  list.push(handler);
+  registry.handlers.set(normalizedKind, list);
+  return () => {
+    const updated = registry.handlers.get(normalizedKind) ?? [];
+    const index = updated.indexOf(handler);
+    if (index !== -1) {
+      updated.splice(index, 1);
+      registry.handlers.set(normalizedKind, updated);
+    }
+  };
+}
+
+export function getTelegramInboundProgrammaticHandlers(
+  kind: string,
+): TelegramInboundProgrammaticHandler[] {
+  const registry = getOrCreateInboundHandlerRegistry();
+  return [
+    ...(registry.handlers.get(kind) ?? []),
+    ...(kind === "*" ? [] : (registry.handlers.get("*") ?? [])),
+  ];
+}
+
+export function hasTelegramInboundHandler(kind?: string): boolean {
+  const registry = getOrCreateInboundHandlerRegistry();
+  if (kind !== undefined) return (registry.handlers.get(kind)?.length ?? 0) > 0;
+  return Array.from(registry.handlers.values()).some((list) => list.length > 0);
+}
+
+export function clearTelegramInboundHandlers(): void {
+  getOrCreateInboundHandlerRegistry().handlers.clear();
+}
+
+function normalizeInboundProgrammaticHandlerText(
+  result: TelegramInboundProgrammaticHandlerResult,
+): string | undefined {
+  const text = typeof result === "string" ? result : result?.text;
+  const normalized = text?.trim();
+  return normalized || undefined;
+}
+
 function normalizeStringList(value: string | string[] | undefined): string[] {
   if (Array.isArray(value)) {
     return value
@@ -467,9 +558,84 @@ async function processTelegramTextHandlers(options: {
       });
     }
   }
+  for (const handler of getTelegramInboundProgrammaticHandlers("text")) {
+    try {
+      const output = normalizeInboundProgrammaticHandlerText(
+        await handler(
+          { kind: "text", text, mimeType: "text/plain" },
+          { cwd: options.cwd },
+        ),
+      );
+      if (output) text = output;
+    } catch (error) {
+      options.recordRuntimeEvent?.("inbound-programmatic-handler", error, {
+        kind: "text",
+      });
+    }
+  }
   return text;
 }
 
+function isTelegramVoiceLikeFile(file: TelegramInboundHandlerFile): boolean {
+  return (
+    file.kind === "voice" ||
+    file.kind === "audio" ||
+    matchesWildcard("audio/*", file.mimeType)
+  );
+}
+
+async function processTelegramFileWithProgrammaticHandlers(
+  file: TelegramInboundHandlerFile,
+  options: {
+    cwd: string;
+    recordRuntimeEvent?: TelegramInboundHandlerRuntimeDeps<unknown>["recordRuntimeEvent"];
+  },
+): Promise<string | undefined> {
+  const kind = file.kind || "*";
+  for (const handler of getTelegramInboundProgrammaticHandlers(kind)) {
+    try {
+      const output = normalizeInboundProgrammaticHandlerText(
+        await handler(
+          {
+            kind,
+            file,
+            mimeType: file.mimeType,
+          },
+          { cwd: options.cwd },
+        ),
+      );
+      if (output) return output;
+    } catch (error) {
+      options.recordRuntimeEvent?.("inbound-programmatic-handler", error, {
+        fileName: file.fileName || basename(file.path),
+        kind,
+      });
+    }
+  }
+  return undefined;
+}
+
+async function transcribeTelegramVoiceFileWithProviders(
+  file: TelegramInboundHandlerFile,
+  options: {
+    recordRuntimeEvent?: TelegramInboundHandlerRuntimeDeps<unknown>["recordRuntimeEvent"];
+  },
+): Promise<string | undefined> {
+  if (!isTelegramVoiceLikeFile(file)) return undefined;
+  for (const provider of getTelegramVoiceTranscriptionProviders()) {
+    try {
+      const result = await provider(file, {});
+      const text = typeof result === "string" ? result : result?.text;
+      if (text?.trim()) return text.trim();
+    } catch (error) {
+      options.recordRuntimeEvent?.("voice-transcription-provider", error, {
+        fileName: file.fileName || basename(file.path),
+      });
+    }
+  }
+  return undefined;
+}
+
 async function readBuiltInTelegramTextAttachment(
   file: TelegramInboundHandlerFile,
 ): Promise<string | undefined> {
@@ -564,6 +730,37 @@ export async function processTelegramInboundHandlers<
         });
       }
     }
+    if (!hasOutput) {
+      try {
+        const output = await processTelegramFileWithProgrammaticHandlers(file, {
+          cwd: options.cwd,
+          recordRuntimeEvent: options.recordRuntimeEvent,
+        });
+        if (output) {
+          outputs.push({ file, output, handler: { type: "programmatic" } });
+          hasOutput = true;
+        }
+      } catch (error) {
+        options.recordRuntimeEvent?.("inbound-programmatic-handler", error, {
+          fileName: file.fileName || basename(file.path),
+        });
+      }
+    }
+    if (!hasOutput) {
+      try {
+        const output = await transcribeTelegramVoiceFileWithProviders(file, {
+          recordRuntimeEvent: options.recordRuntimeEvent,
+        });
+        if (output) {
+          outputs.push({ file, output, handler: { type: "voice-provider" } });
+          hasOutput = true;
+        }
+      } catch (error) {
+        options.recordRuntimeEvent?.("voice-transcription-provider", error, {
+          fileName: file.fileName || basename(file.path),
+        });
+      }
+    }
     if (!hasOutput) {
       try {
         const output = await readBuiltInTelegramTextAttachment(file);

package/lib/media.ts

@@ -463,6 +463,7 @@ export function collectTelegramFileInfos(
         isImage: false,
       });
     }
+    // Generic audio files (e.g. MP3 uploads) — can also trigger voice replies in "mirror" mode
     if (message.audio) {
       const fileName =
         message.audio.file_name ||
@@ -478,6 +479,8 @@ export function collectTelegramFileInfos(
         isImage: false,
       });
     }
+
+    // Voice messages (recorded via microphone) — primary trigger for "mirror" voice reply mode
     if (message.voice) {
       files.push({
         file_id: message.voice.file_id,