@llblab/pi-telegram 0.12.0 → 0.13.1

package/lib/outbound-markup.ts

@@ -0,0 +1,357 @@
+/**
+ * Telegram outbound markup parsing helpers
+ * Zones: telegram outbound, assistant markup
+ * Owns top-level assistant action comment extraction, attribute parsing, and markup stripping shared by voice and outbound delivery
+ */
+
+export interface TelegramTopLevelHtmlComment {
+  raw: string;
+  content: string;
+  start: number;
+  end: number;
+}
+
+interface TelegramTopLevelFenceState {
+  marker: "`" | "~";
+  length: number;
+}
+
+function isTelegramActionCommentContent(content: string): boolean {
+  const normalizedContent = content.replace(/^\s+/, "");
+  const [head = ""] = normalizedContent.split(/\r?\n/, 1);
+  return ["telegram_voice", "telegram_button"].some((command) => {
+    if (!head.startsWith(command)) return false;
+    const nextChar = head[command.length];
+    return nextChar === undefined || /\s|:/.test(nextChar);
+  });
+}
+
+function getMarkdownLineEnd(markdown: string, offset: number): number {
+  const newlineIndex = markdown.indexOf("\n", offset);
+  return newlineIndex === -1 ? markdown.length : newlineIndex + 1;
+}
+
+function getMarkdownLineText(
+  markdown: string,
+  offset: number,
+  end: number,
+): string {
+  return markdown.slice(offset, end).replace(/\r?\n$/, "");
+}
+
+function getTopLevelOpeningFence(
+  line: string,
+): TelegramTopLevelFenceState | undefined {
+  const match = line.match(/^(?: {0,3})(`{3,}|~{3,})/);
+  const sequence = match?.[1];
+  if (!sequence) return undefined;
+  return {
+    marker: sequence[0] as "`" | "~",
+    length: sequence.length,
+  };
+}
+
+function isTopLevelClosingFence(
+  line: string,
+  fence: TelegramTopLevelFenceState,
+): boolean {
+  const match = line.match(/^(?: {0,3})(`{3,}|~{3,})([ \t]*)$/);
+  const sequence = match?.[1];
+  return (
+    !!sequence &&
+    sequence[0] === fence.marker &&
+    sequence.length >= fence.length
+  );
+}
+
+function collectInlineClosedTelegramActionBody(
+  markdown: string,
+  bodyStart: number,
+  commentContent: string,
+): { content: string; end: number } | undefined {
+  const bodyLineEnd = getMarkdownLineEnd(markdown, bodyStart);
+  const bodyLine = getMarkdownLineText(markdown, bodyStart, bodyLineEnd);
+  const closeLineEnd = getMarkdownLineEnd(markdown, bodyLineEnd);
+  const closeLine = getMarkdownLineText(markdown, bodyLineEnd, closeLineEnd);
+  const hasRecoverableBody =
+    isTelegramActionCommentContent(commentContent) &&
+    bodyLine.trim() !== "" &&
+    !bodyLine.startsWith("<!--") &&
+    !bodyLine.startsWith("-->") &&
+    closeLine === "-->";
+  if (!hasRecoverableBody) return undefined;
+  return {
+    content: `${commentContent.trimEnd()}\n${bodyLine}`,
+    end: bodyLineEnd + 3,
+  };
+}
+
+export function collectTopLevelHtmlComments(markdown: string): {
+  comments: TelegramTopLevelHtmlComment[];
+  openCommentStart?: number;
+} {
+  const comments: TelegramTopLevelHtmlComment[] = [];
+  let offset = 0;
+  let fence: TelegramTopLevelFenceState | undefined;
+  while (offset < markdown.length) {
+    const lineEnd = getMarkdownLineEnd(markdown, offset);
+    const line = getMarkdownLineText(markdown, offset, lineEnd);
+    if (fence) {
+      if (isTopLevelClosingFence(line, fence)) fence = undefined;
+      offset = lineEnd;
+      continue;
+    }
+    const nextFence = getTopLevelOpeningFence(line);
+    if (nextFence) {
+      fence = nextFence;
+      offset = lineEnd;
+      continue;
+    }
+    if (line.startsWith("<!--")) {
+      const closeIndex = markdown.indexOf("-->", offset + 4);
+      if (closeIndex === -1) return { comments, openCommentStart: offset };
+      let end = closeIndex + 3;
+      let raw = markdown.slice(offset, end);
+      let content = raw.slice(4, -3);
+      const closeColumn = closeIndex - offset;
+      const closesOnOpeningLine = closeIndex < lineEnd;
+      const hasOnlyWhitespaceAfterClose =
+        line.slice(closeColumn + 3).trim() === "";
+      const inlineBody =
+        closesOnOpeningLine && hasOnlyWhitespaceAfterClose
+          ? collectInlineClosedTelegramActionBody(markdown, lineEnd, content)
+          : undefined;
+      if (inlineBody) {
+        end = inlineBody.end;
+        raw = markdown.slice(offset, end);
+        content = inlineBody.content;
+      }
+      comments.push({ raw, content, start: offset, end });
+      offset = getMarkdownLineEnd(markdown, end);
+      continue;
+    }
+    offset = lineEnd;
+  }
+  return { comments };
+}
+
+export function replaceTopLevelHtmlComments(
+  markdown: string,
+  replacer: (comment: TelegramTopLevelHtmlComment) => string,
+): string {
+  const { comments } = collectTopLevelHtmlComments(markdown);
+  if (comments.length === 0) return markdown;
+  let result = "";
+  let offset = 0;
+  for (const comment of comments) {
+    result += markdown.slice(offset, comment.start);
+    result += replacer(comment);
+    offset = comment.end;
+  }
+  return result + markdown.slice(offset);
+}
+
+export function findTopLevelOpenOrPartialHtmlCommentIndex(
+  markdown: string,
+): number {
+  const { openCommentStart } = collectTopLevelHtmlComments(markdown);
+  if (openCommentStart !== undefined) return openCommentStart;
+  let offset = 0;
+  let fence: TelegramTopLevelFenceState | undefined;
+  while (offset < markdown.length) {
+    const lineEnd = getMarkdownLineEnd(markdown, offset);
+    const line = getMarkdownLineText(markdown, offset, lineEnd);
+    const isLastLine = lineEnd >= markdown.length;
+    if (fence) {
+      if (isTopLevelClosingFence(line, fence)) fence = undefined;
+      offset = lineEnd;
+      continue;
+    }
+    const nextFence = getTopLevelOpeningFence(line);
+    if (nextFence) {
+      fence = nextFence;
+      offset = lineEnd;
+      continue;
+    }
+    if (isLastLine && (line === "<" || line === "<!" || line === "<!-")) {
+      return offset;
+    }
+    offset = lineEnd;
+  }
+  return -1;
+}
+
+export function parseTopLevelTelegramComment(
+  comment: TelegramTopLevelHtmlComment,
+  command: string,
+): { head: string; body?: string } | undefined {
+  let normalizedContent = comment.content.replace(/^\s+/, "");
+  normalizedContent = normalizedContent.replace(/^!/, "");
+  const [rawHead = "", ...bodyLines] = normalizedContent.split(/\r?\n/);
+  let head = rawHead.trimStart();
+  if (!head.startsWith(command)) return undefined;
+  const nextChar = head[command.length];
+  if (nextChar !== undefined && !/\s|:/.test(nextChar)) return undefined;
+  return {
+    head: head.slice(command.length),
+    ...(bodyLines.length > 0 ? { body: bodyLines.join("\n") } : {}),
+  };
+}
+
+export function parseTelegramCommentAttributes(
+  input: string,
+): Record<string, string> {
+  const attributes: Record<string, string> = {};
+  for (const match of input.matchAll(
+    /([A-Za-z_][A-Za-z0-9_-]*)=(?:"([^"]*)"|'([^']*)'|(\S+))/g,
+  )) {
+    const key = match[1];
+    const value = (match[2] ?? match[3] ?? match[4] ?? "").trim();
+    if (value) attributes[key] = value;
+  }
+  return attributes;
+}
+
+export function normalizeMarkdownAfterVoiceExtraction(
+  markdown: string,
+): string {
+  return markdown.replace(/\n{3,}/g, "\n\n").trim();
+}
+
+export function stripTelegramCommentMarkupForPreview(markdown: string): string {
+  const withoutClosedBlocks = replaceTopLevelHtmlComments(markdown, () => "");
+  const openBlockIndex =
+    findTopLevelOpenOrPartialHtmlCommentIndex(withoutClosedBlocks);
+  const previewMarkdown =
+    openBlockIndex >= 0
+      ? withoutClosedBlocks.slice(0, openBlockIndex)
+      : withoutClosedBlocks;
+  return normalizeMarkdownAfterVoiceExtraction(previewMarkdown);
+}
+
+export function stripTelegramCommentMarkupForDelivery(
+  markdown: string,
+): string {
+  const withoutClosedBlocks = replaceTopLevelHtmlComments(markdown, () => "");
+  const openBlockIndex =
+    findTopLevelOpenOrPartialHtmlCommentIndex(withoutClosedBlocks);
+  const deliveryMarkdown =
+    openBlockIndex >= 0
+      ? withoutClosedBlocks.slice(0, openBlockIndex)
+      : withoutClosedBlocks;
+  return normalizeMarkdownAfterVoiceExtraction(deliveryMarkdown);
+}
+
+export function stripTelegramVoiceMarkupForPreview(markdown: string): string {
+  return stripTelegramCommentMarkupForPreview(markdown);
+}
+
+export interface TelegramVoiceReplyItem {
+  text: string;
+  lang?: string;
+  rate?: string;
+}
+
+export interface TelegramVoiceReplyPlan {
+  markdown: string;
+  voiceText?: string;
+  voiceReplies?: TelegramVoiceReplyItem[];
+  lang?: string;
+  rate?: string;
+}
+
+function parseVoiceReplyAttributes(input: string): {
+  lang?: string;
+  rate?: string;
+  text?: string;
+} {
+  const attributes = parseTelegramCommentAttributes(input);
+  return {
+    ...(attributes.lang ? { lang: attributes.lang } : {}),
+    ...(attributes.rate ? { rate: attributes.rate } : {}),
+    ...(attributes.text ? { text: attributes.text } : {}),
+  };
+}
+
+function parseVoiceCommentBody(
+  head: string,
+  body: string | undefined,
+): {
+  attrs: string;
+  text: string;
+} {
+  const trimmedHead = head.trim();
+  if (body !== undefined) {
+    return { attrs: trimmedHead.replace(/^:/, "").trim(), text: body.trim() };
+  }
+  let colonIndex = -1;
+  let inQuote = false;
+  let quoteChar = "";
+  for (let i = 0; i < trimmedHead.length; i++) {
+    const char = trimmedHead[i];
+    if (inQuote) {
+      if (char === quoteChar) inQuote = false;
+    } else {
+      if (char === '"' || char === "'") {
+        inQuote = true;
+        quoteChar = char;
+      } else if (char === ":") {
+        colonIndex = i;
+        break;
+      }
+    }
+  }
+  if (colonIndex > 0) {
+    const attrsPart = trimmedHead.slice(0, colonIndex).trim();
+    const textPart = trimmedHead.slice(colonIndex + 1).trim();
+    const attrs = parseVoiceReplyAttributes(attrsPart);
+    return { attrs: attrsPart, text: textPart || attrs.text || "", ...attrs };
+  }
+  if (trimmedHead.startsWith(":")) {
+    return { attrs: "", text: trimmedHead.slice(1).trim() };
+  }
+  const attrs = parseVoiceReplyAttributes(trimmedHead);
+  return { attrs: trimmedHead, text: attrs.text ?? "" };
+}
+
+export function planTelegramVoiceReply(
+  markdown: string,
+): TelegramVoiceReplyPlan {
+  const voiceReplies: TelegramVoiceReplyItem[] = [];
+  let lang: string | undefined;
+  let rate: string | undefined;
+  const stripped = replaceTopLevelHtmlComments(markdown, (comment) => {
+    let command = parseTopLevelTelegramComment(comment, "telegram_voice");
+    if (!command) {
+      let content = comment.content.replace(/^\s+/, "").replace(/^!/, "");
+      if (content.startsWith("telegram_voice")) {
+        const headPart = content.slice("telegram_voice".length).trim();
+        command = { head: headPart, body: undefined };
+      }
+    }
+    if (!command) return "";
+    const parsed = parseVoiceCommentBody(command.head, command.body);
+    const attrs = parseVoiceReplyAttributes(parsed.attrs);
+    if (parsed.text) {
+      voiceReplies.push({
+        text: parsed.text,
+        ...(attrs.lang ? { lang: attrs.lang } : {}),
+        ...(attrs.rate ? { rate: attrs.rate } : {}),
+      });
+    }
+    if (attrs.lang) lang = attrs.lang;
+    if (attrs.rate) rate = attrs.rate;
+    return "";
+  });
+  const voiceText = voiceReplies
+    .map((reply) => reply.text)
+    .join("\n\n")
+    .trim();
+  return {
+    markdown: stripTelegramCommentMarkupForDelivery(stripped),
+    ...(voiceText ? { voiceText } : {}),
+    ...(voiceReplies.length > 0 ? { voiceReplies } : {}),
+    ...(lang ? { lang } : {}),
+    ...(rate ? { rate } : {}),
+  };
+}

package/lib/outbound-voice.ts

@@ -0,0 +1,263 @@
+/**
+ * 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 { getTelegramVoiceSynthesisProviders } from "./voice.ts";
+
+export interface TelegramVoiceReplyTurnView {
+  chatId: number;
+  replyToMessageId: number;
+}
+
+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>;
+  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[];
+}
+
+function buildVoiceReplyParameters(
+  replyToPrompt: boolean | undefined,
+  replyToMessageId: number | undefined,
+): string | undefined {
+  if (replyToPrompt === false || replyToMessageId === undefined)
+    return undefined;
+  return JSON.stringify({
+    message_id: replyToMessageId,
+    allow_sending_without_reply: true,
+  });
+}
+
+async function ensureTelegramVoiceFileFormat(
+  filePath: string,
+): Promise<string> {
+  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.`,
+  );
+}
+
+function extractVoiceResult(result: any): {
+  filePath: string;
+  transcriptText?: string;
+} {
+  if (typeof result === "string") return { filePath: result };
+  return {
+    filePath: result.audioPath,
+    transcriptText: result.transcriptText,
+  };
+}
+
+async function sendVoiceChatAction(
+  deps: TelegramVoiceReplySenderDeps,
+  chatId: number,
+) {
+  if (deps.sendRecordVoiceAction) {
+    await deps.sendRecordVoiceAction(chatId).catch(() => {});
+  } else {
+    await deps.sendChatAction?.(chatId, "record_voice").catch(() => {});
+  }
+}
+
+export function createTelegramVoiceReplySender<THandler = unknown>(
+  deps: TelegramVoiceReplySenderDeps,
+  ports: TelegramVoiceReplySenderPorts<THandler> = {},
+) {
+  async function uploadVoiceFile(
+    turn: TelegramVoiceReplyTurnView,
+    filePath: string,
+    options?: {
+      replyToPrompt?: boolean;
+      replyMarkup?: unknown;
+      transcriptText?: string;
+    },
+  ): Promise<void> {
+    const voiceFilePath = await ensureTelegramVoiceFileFormat(filePath);
+    await sendVoiceChatAction(deps, turn.chatId);
+    const replyParameters = buildVoiceReplyParameters(
+      options?.replyToPrompt,
+      turn.replyToMessageId,
+    );
+    await deps.sendMultipart(
+      "sendVoice",
+      {
+        chat_id: String(turn.chatId),
+        ...(options?.transcriptText ? { caption: options.transcriptText } : {}),
+        ...(replyParameters ? { reply_parameters: replyParameters } : {}),
+        ...(options?.replyMarkup !== undefined && options.replyMarkup !== null
+          ? {
+              reply_markup:
+                typeof options.replyMarkup === "string"
+                  ? options.replyMarkup
+                  : JSON.stringify(options.replyMarkup),
+            }
+          : {}),
+      },
+      "voice",
+      voiceFilePath,
+      basename(voiceFilePath),
+    );
+  }
+
+  return async function sendVoiceReply(
+    turn: TelegramVoiceReplyTurnView,
+    text: string,
+    options?: {
+      lang?: string;
+      rate?: string;
+      replyToPrompt?: boolean;
+      replyMarkup?: unknown;
+    },
+  ): Promise<void> {
+    for (const handler of ports.findVoiceHandlers?.(deps.getHandlers?.()) ?? []) {
+      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) {
+        deps.recordRuntimeEvent?.("voice", error, {
+          phase: "template-handler-send",
+        });
+      }
+    }
+
+    for (const handler of ports.getProgrammaticVoiceHandlers?.() ?? []) {
+      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) {
+        deps.recordRuntimeEvent?.("voice", error, {
+          phase: "programmatic-handler-send",
+        });
+      }
+    }
+
+    const providers = getTelegramVoiceSynthesisProviders();
+
+    for (const provider of providers) {
+      let voiceFilePath: string | undefined;
+      let originalFilePath: string | undefined;
+
+      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;
+        }
+
+        const { filePath, transcriptText } = extractVoiceResult(providerResult);
+        voiceFilePath = filePath;
+        originalFilePath = filePath;
+        await uploadVoiceFile(turn, filePath, {
+          replyToPrompt: options?.replyToPrompt,
+          replyMarkup: options?.replyMarkup,
+          transcriptText,
+        });
+        return;
+      } catch (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);
+  };
+}