@llblab/pi-telegram 0.46.0 → 0.47.0

package/dist/lib/outbound-voice.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Telegram outbound voice delivery helpers
+ * Zones: telegram outbound, voice delivery
+ * Owns native Telegram voice upload orchestration across configured voice handlers, programmatic outbound voice handlers, and registered synthesis providers
+ */
+import { type TelegramTarget } from "./target.ts";
+export interface TelegramVoiceReplyTurnView {
+    chatId: number;
+    replyToMessageId: number;
+    target?: TelegramTarget;
+}
+export interface TelegramVoiceReplySenderDeps {
+    execCommand: (command: string, args: string[], options?: {
+        cwd?: string;
+        timeout?: number;
+        signal?: AbortSignal;
+        stdin?: string;
+        retry?: number;
+    }) => Promise<{
+        stdout: string;
+        stderr: string;
+        code: number;
+        killed: boolean;
+    }>;
+    sendMultipart: (method: string, fields: Record<string, string>, fileField: string, filePath: string, fileName: string) => Promise<unknown>;
+    sendChatAction?: (chatId: number, action: string) => Promise<unknown>;
+    sendRecordVoiceAction?: (chatId: number) => Promise<unknown>;
+    isDeliveryActive?: () => boolean;
+    getHandlers?: () => unknown[] | undefined;
+    cwd?: string;
+    tempDir?: string;
+    recordRuntimeEvent?: (category: string, error: unknown, details?: Record<string, unknown>) => void;
+}
+export type TelegramOutboundProgrammaticVoiceHandler = (text: string, options?: {
+    lang?: string;
+    rate?: string;
+}) => Promise<string>;
+export interface TelegramVoiceReplySenderPorts<THandler = unknown> {
+    findVoiceHandlers?: (handlers: unknown[] | undefined) => THandler[];
+    generateVoiceFile?: (text: string, options: {
+        lang?: string;
+        rate?: string;
+        handler: THandler;
+        tempDir?: string;
+        cwd?: string;
+        execCommand: TelegramVoiceReplySenderDeps["execCommand"];
+    }) => Promise<string | undefined>;
+    getProgrammaticVoiceHandlers?: () => TelegramOutboundProgrammaticVoiceHandler[];
+}
+export declare function createTelegramVoiceReplySender<THandler = unknown>(deps: TelegramVoiceReplySenderDeps, ports?: TelegramVoiceReplySenderPorts<THandler>): (turn: TelegramVoiceReplyTurnView, text: string, options?: {
+    lang?: string;
+    rate?: string;
+    replyToPrompt?: boolean;
+    replyMarkup?: unknown;
+}) => Promise<void>;

package/dist/lib/outbound-voice.js

@@ -0,0 +1,152 @@
+/**
+ * Telegram outbound voice delivery helpers
+ * Zones: telegram outbound, voice delivery
+ * Owns native Telegram voice upload orchestration across configured voice handlers, programmatic outbound voice handlers, and registered synthesis providers
+ */
+import { unlink } from "node:fs/promises";
+import { basename, extname } from "node:path";
+import { assertTelegramInlineKeyboardCallbackData } from "./keyboard.js";
+import { withTelegramReplyParameters } from "./replies.js";
+import { getTelegramTargetThreadParams, } from "./target.js";
+import { getTelegramVoiceSynthesisProviders } from "./voice.js";
+import { isTelegramApiCommitUnknownError } from "./telegram-api.js";
+async function ensureTelegramVoiceFileFormat(filePath) {
+    const ext = extname(filePath).toLowerCase();
+    if (ext === ".opus" || ext === ".ogg")
+        return filePath;
+    throw new Error(`Voice synthesis provider must return .ogg or .opus files, got ${ext}. ` +
+        `Providers should handle format conversion internally.`);
+}
+async function sendVoiceChatAction(deps, chatId) {
+    if (deps.sendRecordVoiceAction) {
+        await deps.sendRecordVoiceAction(chatId).catch(() => { });
+    }
+    else {
+        await deps.sendChatAction?.(chatId, "record_voice").catch(() => { });
+    }
+}
+export function createTelegramVoiceReplySender(deps, ports = {}) {
+    const uploadVoiceFile = async (turn, filePath, options) => {
+        if (deps.isDeliveryActive?.() === false)
+            return;
+        const voiceFilePath = await ensureTelegramVoiceFileFormat(filePath);
+        assertTelegramInlineKeyboardCallbackData(options?.replyMarkup);
+        if (deps.isDeliveryActive?.() === false)
+            return;
+        await sendVoiceChatAction(deps, turn.chatId);
+        if (deps.isDeliveryActive?.() === false)
+            return;
+        await withTelegramReplyParameters(turn.chatId, options?.replyToPrompt === false ? undefined : turn.replyToMessageId, turn.target, (replyParameters) => deps.sendMultipart("sendVoice", {
+            chat_id: String(turn.chatId),
+            ...(replyParameters ? { reply_parameters: JSON.stringify(replyParameters) } : {}),
+            ...(turn.target
+                ? Object.fromEntries(Object.entries(getTelegramTargetThreadParams(turn.target)).map(([key, value]) => [key, String(value)]))
+                : {}),
+            ...(options?.replyMarkup !== undefined && options.replyMarkup !== null
+                ? {
+                    reply_markup: typeof options.replyMarkup === "string"
+                        ? options.replyMarkup
+                        : JSON.stringify(options.replyMarkup),
+                }
+                : {}),
+        }, "voice", voiceFilePath, basename(voiceFilePath)));
+    };
+    return async (turn, text, options) => {
+        for (const handler of ports.findVoiceHandlers?.(deps.getHandlers?.()) ??
+            []) {
+            if (deps.isDeliveryActive?.() === false)
+                return;
+            try {
+                const filePath = await ports.generateVoiceFile?.(text, {
+                    lang: options?.lang,
+                    rate: options?.rate,
+                    handler,
+                    tempDir: deps.tempDir,
+                    cwd: deps.cwd,
+                    execCommand: deps.execCommand,
+                });
+                if (!filePath)
+                    continue;
+                await uploadVoiceFile(turn, filePath, {
+                    replyToPrompt: options?.replyToPrompt,
+                    replyMarkup: options?.replyMarkup,
+                });
+                return;
+            }
+            catch (error) {
+                if (isTelegramApiCommitUnknownError(error))
+                    throw error;
+                deps.recordRuntimeEvent?.("voice", error, {
+                    phase: "template-handler-send",
+                });
+            }
+        }
+        for (const handler of ports.getProgrammaticVoiceHandlers?.() ?? []) {
+            if (deps.isDeliveryActive?.() === false)
+                return;
+            try {
+                const filePath = await handler(text, {
+                    lang: options?.lang,
+                    rate: options?.rate,
+                });
+                if (!filePath)
+                    continue;
+                await uploadVoiceFile(turn, filePath, {
+                    replyToPrompt: options?.replyToPrompt,
+                    replyMarkup: options?.replyMarkup,
+                });
+                return;
+            }
+            catch (error) {
+                if (isTelegramApiCommitUnknownError(error))
+                    throw error;
+                deps.recordRuntimeEvent?.("voice", error, {
+                    phase: "programmatic-handler-send",
+                });
+            }
+        }
+        const providers = getTelegramVoiceSynthesisProviders();
+        for (const provider of providers) {
+            if (deps.isDeliveryActive?.() === false)
+                return;
+            let voiceFilePath;
+            let originalFilePath;
+            try {
+                if (typeof provider !== "function") {
+                    deps.recordRuntimeEvent?.("voice", new Error("Registered voice synthesis provider is not callable (policy-only object?)"), { phase: "voice-provider-skip" });
+                    continue;
+                }
+                const providerResult = await provider(text, {
+                    lang: options?.lang,
+                    rate: options?.rate,
+                });
+                if (!providerResult) {
+                    deps.recordRuntimeEvent?.("voice", new Error("Voice synthesis provider returned empty path"), { phase: "voice-provider-skip" });
+                    continue;
+                }
+                voiceFilePath = providerResult;
+                originalFilePath = providerResult;
+                await uploadVoiceFile(turn, providerResult, {
+                    replyToPrompt: options?.replyToPrompt,
+                    replyMarkup: options?.replyMarkup,
+                });
+                return;
+            }
+            catch (error) {
+                if (isTelegramApiCommitUnknownError(error))
+                    throw error;
+                deps.recordRuntimeEvent?.("voice", error, { phase: "send" });
+            }
+            finally {
+                if (voiceFilePath && voiceFilePath !== originalFilePath) {
+                    await unlink(voiceFilePath).catch(() => { });
+                }
+            }
+        }
+        const errorMessage = "Failed to send voice reply: every voice synthesis provider and outbound voice handler failed.";
+        deps.recordRuntimeEvent?.("voice", new Error(errorMessage), {
+            phase: "send",
+        });
+        throw new Error(errorMessage);
+    };
+}

package/dist/lib/outbound.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Telegram outbound surface helpers
+ * Zones: telegram outbound, command templates, voice delivery
+ * Owns configured outbound handler execution, text transforms, public assistant-output reply composition and mutation fencing, voice-file generation/delivery, runtime-event bridge, and compatibility re-exports; assistant markup parsing lives in outbound-markup and button callback actions live in outbound-buttons
+ */
+import type { TelegramAssistantSegmentEvent } from "./activity.ts";
+import * as Replies from "./replies.ts";
+import type { TelegramPreparedPreviewDelivery } from "./preview.ts";
+import type { TelegramEditMessageTextBody, TelegramSendMessageBody, TelegramSendRichMessageBody, TelegramSentMessage } from "./telegram-api.ts";
+import { type TelegramButtonActionStore, type TelegramOutboundButtonBinding, type TelegramOutboundButtonMarkup } from "./outbound-buttons.ts";
+import { type TelegramVoiceReplyItem } from "./outbound-markup.ts";
+import type { TelegramTarget } from "./target.ts";
+import { type CommandTemplateObjectConfig } from "./command-templates.ts";
+/**
+ * Record a runtime event that appears in `/telegram-status`.
+ * Voice synthesis provider extensions can call this to surface diagnostics
+ * alongside pi-telegram's own events. Events are silently dropped
+ * when pi-telegram is not loaded.
+ */
+export type TelegramRuntimeEventRecorder = (category: string, error: unknown, details?: Record<string, unknown>) => void;
+export declare function bindTelegramRuntimeEventRecorder(recorder: TelegramRuntimeEventRecorder): void;
+export declare function recordTelegramRuntimeEvent(category: string, error: unknown, details?: Record<string, unknown>): void;
+export type TelegramOutboundCommandTemplateConfig = string | CommandTemplateObjectConfig;
+export interface TelegramOutboundHandlerConfig extends CommandTemplateObjectConfig {
+    type?: string;
+    match?: string | string[];
+    output?: string;
+    timeout?: number | string;
+}
+export { normalizeMarkdownAfterVoiceExtraction, planTelegramVoiceReply, stripTelegramCommentMarkupForDelivery, stripTelegramCommentMarkupForPreview, stripTelegramVoiceMarkupForPreview, type TelegramVoiceReplyItem, type TelegramVoiceReplyPlan, } from "./outbound-markup.ts";
+export interface TelegramVoiceExecOptions {
+    cwd?: string;
+    timeout?: number;
+    signal?: AbortSignal;
+    stdin?: string;
+    retry?: number;
+}
+export interface TelegramVoiceExecResult {
+    stdout: string;
+    stderr: string;
+    code: number;
+    killed: boolean;
+}
+export interface TelegramVoiceReplyTurnView {
+    chatId: number;
+    replyToMessageId: number;
+    target?: TelegramTarget;
+}
+export interface TelegramVoiceReplySenderDeps {
+    execCommand: (command: string, args: string[], options?: TelegramVoiceExecOptions) => Promise<TelegramVoiceExecResult>;
+    sendMultipart: (method: string, fields: Record<string, string>, fileField: string, filePath: string, fileName: string) => Promise<unknown>;
+    sendTextReply?: (chatId: number, replyToMessageId: number | undefined, text: string, options?: {
+        parseMode?: "HTML";
+    }) => Promise<unknown>;
+    sendChatAction?: (chatId: number, action: string) => Promise<unknown>;
+    sendRecordVoiceAction?: (chatId: number) => Promise<unknown>;
+    isDeliveryActive?: () => boolean;
+    getHandlers?: () => TelegramOutboundHandlerConfig[] | undefined;
+    cwd?: string;
+    tempDir?: string;
+    recordRuntimeEvent?: (category: string, error: unknown, details?: Record<string, unknown>) => void;
+}
+export type TelegramOutboundProgrammaticHandler = (text: string, options?: {
+    lang?: string;
+    rate?: string;
+}) => Promise<string>;
+export interface TelegramOutboundHandlerRegistry {
+    handlers: Map<string, TelegramOutboundProgrammaticHandler[]>;
+}
+export declare function registerTelegramOutboundHandler(kind: string, handler: TelegramOutboundProgrammaticHandler): () => void;
+export declare function getTelegramOutboundProgrammaticHandlers(kind: string): TelegramOutboundProgrammaticHandler[];
+export interface TelegramOutboundTextReplyRuntimeDeps<TReplyMarkup = unknown> {
+    execCommand: TelegramVoiceReplySenderDeps["execCommand"];
+    getHandlers?: () => TelegramOutboundHandlerConfig[] | undefined;
+    sendTextReply: (chatId: number, replyToMessageId: number | undefined, text: string, options?: {
+        parseMode?: "HTML";
+        target?: TelegramTarget;
+    }) => Promise<number | undefined>;
+    sendMarkdownReply: (chatId: number, replyToMessageId: number | undefined, markdown: string, options?: {
+        replyMarkup?: TReplyMarkup;
+        target?: TelegramTarget;
+    }) => Promise<number | undefined>;
+    cwd?: string;
+    recordRuntimeEvent?: TelegramVoiceReplySenderDeps["recordRuntimeEvent"];
+}
+export interface TelegramInlineKeyboardLike {
+    inline_keyboard: Array<Array<{
+        text: string;
+        callback_data: string;
+    }>>;
+}
+export interface TelegramOutboundTextTransformOptions<TReplyMarkup = unknown> {
+    handlers?: TelegramOutboundHandlerConfig[];
+    cwd?: string;
+    execCommand: TelegramVoiceReplySenderDeps["execCommand"];
+    recordRuntimeEvent?: TelegramVoiceReplySenderDeps["recordRuntimeEvent"];
+    replyMarkup?: TReplyMarkup;
+}
+export interface TelegramOutboundTextTransformResult<TReplyMarkup = unknown> {
+    text: string;
+    replyMarkup?: TReplyMarkup;
+}
+export interface TelegramOutboundTextPreviewRuntimeDeps<TReplyMarkup = unknown> {
+    execCommand: TelegramVoiceReplySenderDeps["execCommand"];
+    getHandlers?: () => TelegramOutboundHandlerConfig[] | undefined;
+    finalizeMarkdownPreview: TelegramPreparedPreviewDelivery<TReplyMarkup>["finalizeMarkdownPreview"];
+    preparePreviewDelivery?: (isDeliveryActive: () => boolean) => TelegramPreparedPreviewDelivery<TReplyMarkup>;
+    cwd?: string;
+    recordRuntimeEvent?: TelegramVoiceReplySenderDeps["recordRuntimeEvent"];
+}
+export declare function findTelegramOutboundHandlers(handlers: TelegramOutboundHandlerConfig[] | undefined, type: string): TelegramOutboundHandlerConfig[];
+export declare function generateTelegramVoiceReplyFile(text: string, options: {
+    lang?: string;
+    rate?: string;
+    handler?: TelegramOutboundHandlerConfig;
+    tempDir?: string;
+    cwd?: string;
+    execCommand: TelegramVoiceReplySenderDeps["execCommand"];
+}): Promise<string | undefined>;
+export declare function transformTelegramOutboundText(text: string, options: {
+    handlers?: TelegramOutboundHandlerConfig[];
+    cwd?: string;
+    execCommand: TelegramVoiceReplySenderDeps["execCommand"];
+    recordRuntimeEvent?: TelegramVoiceReplySenderDeps["recordRuntimeEvent"];
+}): Promise<string>;
+export declare function transformTelegramOutboundTextReply<TReplyMarkup = unknown>(text: string, options: TelegramOutboundTextTransformOptions<TReplyMarkup>): Promise<TelegramOutboundTextTransformResult<TReplyMarkup>>;
+export declare function createTelegramOutboundTextReplyRuntime<TReplyMarkup = unknown>(deps: TelegramOutboundTextReplyRuntimeDeps<TReplyMarkup>): Pick<TelegramOutboundTextReplyRuntimeDeps<TReplyMarkup>, "sendTextReply" | "sendMarkdownReply">;
+export declare function createTelegramOutboundTextPreviewRuntime<TReplyMarkup = unknown>(deps: TelegramOutboundTextPreviewRuntimeDeps<TReplyMarkup>): {
+    finalizeMarkdownPreview: TelegramPreparedPreviewDelivery<TReplyMarkup>["finalizeMarkdownPreview"];
+    preparePreviewDelivery: (isDeliveryActive: () => boolean) => TelegramPreparedPreviewDelivery<TReplyMarkup> | undefined;
+};
+export interface TelegramOutboundReplyPlan<TReplyMarkup = unknown> {
+    markdown: string;
+    replyMarkup?: TReplyMarkup;
+    voiceText?: string;
+    voiceReplies?: TelegramVoiceReplyItem[];
+    lang?: string;
+    rate?: string;
+}
+export { clearTelegramVoiceSynthesisProviders, clearTelegramVoiceTranscriptionProviders, computeVoicePromptContribution, computeVoiceTurnFlags, getTelegramVoiceReplyMode, getTelegramVoiceSynthesisProviders, getTelegramVoiceTranscriptionProviders, hasTelegramVoiceSynthesisProvider, hasTelegramVoiceTranscriptionProvider, isVoiceTurn, registerTelegramVoiceSynthesisProvider, registerTelegramVoiceTranscriptionProvider, shouldSuppressPreviewForVoice, type TelegramVoiceReplyMode, type TelegramVoiceSynthesisProvider, type TelegramVoiceSynthesisProviderResult, type TelegramVoiceTranscriptionFile, type TelegramVoiceTranscriptionProvider, type TelegramVoiceTranscriptionProviderResult, type TelegramVoiceTurnView, } from "./voice.ts";
+export declare function createTelegramVoiceReplySender(deps: TelegramVoiceReplySenderDeps): (turn: import("./outbound-voice.ts").TelegramVoiceReplyTurnView, text: string, options?: {
+    lang?: string;
+    rate?: string;
+    replyToPrompt?: boolean;
+    replyMarkup?: unknown;
+} | undefined) => Promise<void>;
+export { createTelegramButtonActionStore, createTelegramButtonPromptTurn, createTelegramButtonReplyPlanner, handleTelegramButtonCallbackQuery, markTelegramButtonSelected, planTelegramButtonReply, type TelegramButtonActionStore, type TelegramButtonCallbackHandlerDeps, type TelegramButtonCallbackQuery, type TelegramButtonReplyPlan, type TelegramOutboundButtonAction, type TelegramOutboundButtonBinding, type TelegramOutboundButtonMarkup, type TelegramOutboundButtonStoredAction, } from "./outbound-buttons.ts";
+export declare function createTelegramOutboundReplyPlanner(store: Pick<TelegramButtonActionStore, "register">, getRenderingMode?: () => "rich" | "html"): (markdown: string, options?: {
+    binding?: TelegramOutboundButtonBinding;
+}) => TelegramOutboundReplyPlan<TelegramOutboundButtonMarkup>;
+/**
+ * Create an artifact sender that delivers planned voice replies for a turn.
+ * Iterates over `voiceReplies` (or a single `voiceText`) and sends each as
+ * a Telegram voice message via the voice reply sender. Throws if no voice
+ * reply could be delivered.
+ */
+export declare function createTelegramOutboundReplyArtifactSender(deps: TelegramVoiceReplySenderDeps): (turn: TelegramVoiceReplyTurnView, plan: Pick<TelegramOutboundReplyPlan, "voiceText" | "voiceReplies" | "lang" | "rate" | "replyMarkup">, options?: {
+    replyToPrompt?: boolean;
+    isDeliveryActive?: () => boolean;
+}) => Promise<void>;
+export interface TelegramAssistantOutputMutationFence {
+    run: <TArgs extends unknown[], TResult>(mutation: (...args: TArgs) => Promise<TResult>, ...args: TArgs) => Promise<TResult>;
+}
+export interface TelegramAssistantOutputDeliveryAuthority<TTransportStamp> {
+    transportStamp: TTransportStamp;
+    route: "direct" | "follower" | "none";
+    directEpoch?: number | string;
+    followerGeneration?: string;
+    target?: TelegramTarget;
+}
+export declare function createTelegramAssistantOutputMutationFence(isAuthorityActive: () => boolean): TelegramAssistantOutputMutationFence;
+export declare function createTelegramAssistantOutputSender<TTransportStamp, TReplyMarkup = unknown>(deps: {
+    recordOwnership?: Replies.TelegramReplyOwnershipRecorder["record"];
+    sendMessage: (body: TelegramSendMessageBody) => Promise<TelegramSentMessage>;
+    sendRichMessage: (body: TelegramSendRichMessageBody) => Promise<TelegramSentMessage>;
+    editMessage: (body: TelegramEditMessageTextBody) => Promise<unknown>;
+    getAssistantRenderingMode: () => "rich" | "html";
+    planButtonReply?: (markdown: string) => {
+        markdown: string;
+        replyMarkup?: TReplyMarkup;
+    };
+    execCommand: TelegramOutboundTextReplyRuntimeDeps<TReplyMarkup>["execCommand"];
+    getHandlers?: TelegramOutboundTextReplyRuntimeDeps<TReplyMarkup>["getHandlers"];
+    recordRuntimeEvent?: TelegramOutboundTextReplyRuntimeDeps<TReplyMarkup>["recordRuntimeEvent"];
+}): (event: TelegramAssistantSegmentEvent, authority: TelegramAssistantOutputDeliveryAuthority<TTransportStamp>, isAuthorityActive: () => boolean) => Promise<void>;