pi-telegram-plus 0.0.1

package/lib/controller.ts

@@ -0,0 +1,406 @@
+import type { ExtensionCommandContext, ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import { decodeUiCallback } from "./callback-protocol.ts";
+import { parseLeadingCommand, normalizeLeadingCommand } from "./command-parser.ts";
+import type {
+  CapturedAgentSession,
+  TelegramCallbackQuery,
+  TelegramDocument,
+  TelegramMessage,
+  TelegramMessageMode,
+  TelegramPhotoSize,
+  TelegramTransport,
+  TelegramTurn,
+} from "./types.ts";
+import type { TelegramUiRuntime } from "./telegram-ui.ts";
+
+export type TelegramController = {
+  handleMessage(message: TelegramMessage): Promise<void>;
+  handleCallbackQuery(query: TelegramCallbackQuery): Promise<void>;
+};
+
+function getIncomingDocumentName(document?: TelegramDocument): string {
+  if (!document) return "file";
+  return document.file_name || `${document.file_id}`;
+}
+
+type IncomingMediaSummaryEntry = {
+  type: string;
+  fileId: string;
+  fileName?: string;
+};
+
+function extractTelegramMediaEntries(message: TelegramMessage): IncomingMediaSummaryEntry[] {
+  const entries: IncomingMediaSummaryEntry[] = [];
+  if (message.photo && message.photo.length > 0) {
+    const bestPhoto = [...message.photo].reduce<TelegramPhotoSize>((best, current) => {
+      const bestSize = best.file_size ?? -1;
+      const currentSize = current.file_size ?? -1;
+      return currentSize > bestSize ? current : best;
+    }, message.photo[0]);
+    entries.push({ type: "photo", fileId: bestPhoto.file_id, fileName: undefined });
+  }
+
+  const documentAttachments: Array<{ type: string; document?: TelegramDocument }> = [];
+  if (message.document) documentAttachments.push({ type: "document", document: message.document });
+  if (message.video) documentAttachments.push({ type: "video", document: message.video });
+  if (message.audio) documentAttachments.push({ type: "audio", document: message.audio });
+  if (message.voice) documentAttachments.push({ type: "voice", document: message.voice });
+  if (message.animation) documentAttachments.push({ type: "animation", document: message.animation });
+  if (message.sticker) documentAttachments.push({ type: "sticker", document: message.sticker });
+  for (const attachment of documentAttachments) {
+    if (!attachment.document) continue;
+    entries.push({
+      type: attachment.type,
+      fileId: attachment.document.file_id,
+      fileName: attachment.document.file_name,
+    });
+  }
+
+  return entries;
+}
+
+function buildTelegramIncomingMediaSummary(message: TelegramMessage): string {
+  const parts: string[] = [];
+  if (message.photo && message.photo.length > 0) {
+    parts.push(`- photo (${message.photo.length} photo frame(s))`);
+  }
+  const entries: Array<{ type: string; document?: TelegramDocument }> = [];
+  if (message.document) entries.push({ type: "document", document: message.document });
+  if (message.video) entries.push({ type: "video", document: message.video });
+  if (message.audio) entries.push({ type: "audio", document: message.audio });
+  if (message.voice) entries.push({ type: "voice", document: message.voice });
+  if (message.animation) entries.push({ type: "animation", document: message.animation });
+  if (message.sticker) entries.push({ type: "sticker", document: message.sticker });
+  for (const attachment of entries) {
+    if (!attachment.document) continue;
+    parts.push(`- ${attachment.type}: ${getIncomingDocumentName(attachment.document)}`);
+  }
+  return parts.length ? `[telegram attachment]\n${parts.join("\n")}` : "";
+}
+
+function formatSavedIncomingAttachmentLine(kind: string, fileId: string, fileName: string | undefined, path: string): string {
+  const savedName = fileName ? `${fileName} (${fileId})` : fileId;
+  return `- ${kind}: ${savedName} => ${path}`;
+}
+
+function formatIncomingAttachmentErrorLine(kind: string, fileId: string, fileName: string | undefined, reason: string): string {
+  const target = fileName ? `${fileName} (${fileId})` : fileId;
+  return `- ${kind}: ${target} -> failed to save (${reason})`;
+}
+
+function formatIncomingAttachmentReceipt(state: "saved" | "failed", lines: string[]): string {
+  if (lines.length === 0) return "";
+  const title = state === "saved" ? "✅ Saved attachments (local paths):" : "⚠️ Attachments not saved:";
+  return `${title}\n${lines.join("\n")}`;
+}
+
+
+export type TelegramCommandHandler = (args: string, ctx: ExtensionCommandContext) => Promise<void>;
+
+
+async function runWithTelegramUi<T>(deps: {
+  session: CapturedAgentSession;
+  ui: ExtensionUIContext;
+  run: () => Promise<T>;
+}): Promise<T> {
+  const runner = deps.session.extensionRunner;
+  const previousUi = runner.getUIContext();
+  runner.setUIContext(deps.ui);
+  try {
+    return await deps.run();
+  } finally {
+    runner.setUIContext(previousUi);
+  }
+}
+
+export function createTelegramController(deps: {
+  getSession: () => CapturedAgentSession | undefined;
+  transport: TelegramTransport;
+  ui: TelegramUiRuntime;
+  authorizeUser(userId: number | undefined): Promise<boolean>;
+  setActiveChatId(chatId: number): Promise<void>;
+  getBotUsername(): string | undefined;
+  getMessageMode: () => TelegramMessageMode;
+  telegramCommands: Map<string, TelegramCommandHandler>;
+  getActiveTurn(chatId: number): TelegramTurn | undefined;
+  beginTelegramTurn(chatId: number, replaceMessageId?: number): TelegramTurn | undefined;
+  endTelegramTurn(chatId: number, turn: TelegramTurn): void;
+  saveIncomingTelegramAttachment?: (fileId: string, fileName: string | undefined, kind: string) => Promise<string>;
+}): TelegramController {
+  // Per-chat prompt queues: each chat chains its prompts sequentially.
+  const promptTails = new Map<number, Promise<void>>();
+  // Increasing generation per chat lets stop invalidate pending queue items.
+  const interruptGenerationByChat = new Map<number, number>();
+
+  const getOrCreateTail = (chatId: number): Promise<void> => promptTails.get(chatId) ?? Promise.resolve();
+  const setTail = (chatId: number, tail: Promise<void>) => promptTails.set(chatId, tail);
+  const getInterruptGeneration = (chatId: number): number => interruptGenerationByChat.get(chatId) ?? 0;
+  const bumpInterruptGeneration = (chatId: number): void => {
+    const next = getInterruptGeneration(chatId) + 1;
+    interruptGenerationByChat.set(chatId, next);
+  };
+
+  const fastInterrupt = async (chatId: number) => {
+    const session = deps.getSession();
+    if (!session) {
+      await deps.transport.sendText(chatId, "π session is not ready yet.");
+      return;
+    }
+
+    bumpInterruptGeneration(chatId);
+    await deps.transport.sendText(chatId, "⏹️ Interrupt requested.");
+    const abortResult = (session as any).abort?.();
+    void abortResult?.catch?.(() => undefined);
+  };
+
+  const runPrompt = async (text: string, chatId: number, replaceMessageId?: number) => {
+    const session = deps.getSession();
+    if (!session) {
+      if (replaceMessageId !== undefined) await deps.transport.editText(chatId, replaceMessageId, "π session is not ready yet.");
+      else await deps.transport.sendText(chatId, "π session is not ready yet.");
+      return;
+    }
+
+    const mode = deps.getMessageMode();
+    const isSteer = mode === "steer" && session.isStreaming;
+
+    // In steer mode, reuse the existing active turn for this chat.
+    // Steer messages inject into a running stream — they must not acquire a
+    // new turn (which would fail since the chat already has one).
+    if (isSteer) {
+      const existingTurn = deps.getActiveTurn(chatId);
+      if (!existingTurn) {
+        // No active turn to steer into — fall back to a new prompt.
+        const turn = deps.beginTelegramTurn(chatId);
+        if (!turn) {
+          await deps.transport.sendText(chatId, "⏳ π is busy. Try again shortly.");
+          return;
+        }
+        const telegramUi = deps.ui.create(chatId);
+        try {
+          await runWithTelegramUi({
+            session,
+            ui: telegramUi,
+            run: () => session.prompt(text, { source: "interactive" }),
+          });
+        } finally {
+          deps.endTelegramTurn(chatId, turn);
+        }
+        return;
+      }
+      const telegramUi = deps.ui.create(chatId);
+      await runWithTelegramUi({
+        session,
+        ui: telegramUi,
+        run: () => session.prompt(text, { source: "interactive", streamingBehavior: "steer" as const }),
+      });
+      return;
+    }
+
+    const turn = deps.beginTelegramTurn(chatId, replaceMessageId);
+    if (!turn) {
+      // Chat already has an active turn — reject with a busy message.
+      if (replaceMessageId !== undefined) await deps.transport.editText(chatId, replaceMessageId, "⏳ π is busy. Try again shortly.");
+      else await deps.transport.sendText(chatId, "⏳ π is busy. Try again shortly.");
+      return;
+    }
+
+    const telegramUi = deps.ui.create(chatId);
+    try {
+      await runWithTelegramUi({
+        session,
+        ui: telegramUi,
+        run: () => session.prompt(text, { source: "interactive" }),
+      });
+    } finally {
+      deps.endTelegramTurn(chatId, turn);
+    }
+  };
+
+  const submitText = async (text: string, chatId: number, replaceMessageId?: number) => {
+    const mode = deps.getMessageMode();
+    if (mode === "steer") {
+      const task = runPrompt(text, chatId, replaceMessageId);
+      void task.catch(() => undefined);
+      return;
+    }
+
+    const generation = getInterruptGeneration(chatId);
+
+    // In queue mode, chain behind the previous prompt for this chat.
+    const task = getOrCreateTail(chatId)
+      .then(() => {
+        if (generation !== getInterruptGeneration(chatId)) return;
+        return runPrompt(text, chatId, replaceMessageId);
+      })
+      .catch(() => undefined);
+    setTail(chatId, task);
+  };
+
+  const runCommandHandler = (handler: TelegramCommandHandler, args: string, session: CapturedAgentSession, chatId: number) => {
+    // Commands run immediately — they do not acquire a turn and are never
+    // blocked by an active agent prompt.  Fast config / status commands
+    // briefly borrow the UI context; the rendering pipeline still finds the
+    // existing prompt turn via getActiveTurn() and stream output normally.
+    //
+    // Do not await command handlers here: some commands open interactive
+    // prompts (e.g. /new confirmation), and awaiting them would stall the
+    // polling loop and block callback processing for that update.
+    const telegramUi = deps.ui.create(chatId);
+    void runWithTelegramUi({
+      session,
+      ui: telegramUi,
+      run: async () => handler(args, session.extensionRunner.createCommandContext()),
+    }).catch(() => undefined);
+  };
+
+  const tryHandleSlashCommand = async (text: string, chatId: number): Promise<boolean> => {
+    const parsed = parseLeadingCommand(text);
+    if (!parsed) return false;
+    const session = deps.getSession();
+    if (!session) {
+      await deps.transport.sendText(chatId, "π session is not ready yet.");
+      return true;
+    }
+
+    const name = parsed.name.toLowerCase();
+    const handler =
+      deps.telegramCommands.get(name)
+      ?? deps.telegramCommands.get(name.replace(/_/g, "-"))
+      ?? deps.telegramCommands.get(name.replace(/-/g, "_"));
+    if (handler) {
+      await runCommandHandler(handler, parsed.args, session, chatId);
+      return true;
+    }
+    const externalCommand =
+      session.extensionRunner.getCommand(name)
+      ?? session.extensionRunner.getCommand(name.replace(/_/g, "-"))
+      ?? session.extensionRunner.getCommand(name.replace(/-/g, "_"));
+    if (externalCommand) {
+      await runCommandHandler(externalCommand.handler, parsed.args, session, chatId);
+      return true;
+    }
+    return false;
+  };
+
+  return {
+    async handleCallbackQuery(query) {
+      const chatId = query.message?.chat?.id;
+      if (typeof chatId !== "number") return;
+      await deps.transport.answerCallbackQuery(query.id).catch(() => undefined);
+      if (!(await deps.authorizeUser(query.from?.id))) return;
+      await deps.setActiveChatId(chatId);
+
+      const data = query.data ?? "";
+      const uiValue = decodeUiCallback(data);
+      if (uiValue !== undefined) {
+        const result = deps.ui.resolveInput(chatId, uiValue, query.message?.message_id, true);
+        if (!result.handled) {
+          await deps.transport.sendText(chatId, "This prompt is no longer active.");
+        } else {
+          // Remove inline keyboards only for terminal UI callbacks. Select
+          // pagination callbacks continue the same flow and immediately edit the
+          // same message with the next page of buttons; removing the keyboard here
+          // can race after that edit and strip the new page buttons.
+          const isPaginationCallback = /^f:[^:]+:p:\d+$/.test(uiValue);
+          const promptMessageId = result.promptMessageId ?? query.message?.message_id;
+          if (!isPaginationCallback && promptMessageId) void deps.transport.removeInlineKeyboard(chatId, promptMessageId);
+        }
+        return;
+      }
+
+      if (data) {
+        const messageId = query.message?.message_id;
+        await submitText(data, chatId, messageId);
+      }
+    },
+
+    async handleMessage(message) {
+      const chatId = message.chat?.id;
+      if (typeof chatId !== "number") return;
+      if (!(await deps.authorizeUser(message.from?.id))) return;
+      await deps.setActiveChatId(chatId);
+
+      const rawText = message.text ?? message.caption ?? "";
+      const text = normalizeLeadingCommand(rawText, deps.getBotUsername());
+      const trimmed = text.trim();
+      const replyToInput = message.reply_to_message?.message_id;
+      if (trimmed === "/stop") {
+        // /stop cancellation priority: first try canceling a reply-targeted
+        // pending input, then any pending input, then abort the agent turn.
+        const cancelResult = deps.ui.resolveInput(chatId, undefined, replyToInput);
+        const cancelAnyResult = !cancelResult.handled ? deps.ui.resolveInput(chatId, undefined) : cancelResult;
+        if (cancelAnyResult.handled) {
+          if (cancelAnyResult.promptMessageId) void deps.transport.removeInlineKeyboard(chatId, cancelAnyResult.promptMessageId);
+          await deps.transport.sendText(chatId, "Cancelled.");
+          return;
+        }
+        await fastInterrupt(chatId);
+        return;
+      }
+
+      const mediaSummary = buildTelegramIncomingMediaSummary(message);
+      const hasMediaInput = mediaSummary.length > 0;
+      const hasTextInput = message.text !== undefined || message.caption !== undefined;
+      const incomingMedia = hasMediaInput ? extractTelegramMediaEntries(message) : [];
+      const downloadedMediaLines: string[] = [];
+      const failedMediaLines: string[] = [];
+      if (deps.saveIncomingTelegramAttachment && incomingMedia.length > 0) {
+        const mediaSaveResults = await Promise.allSettled(
+          incomingMedia.map((attachment) => deps.saveIncomingTelegramAttachment!(
+            attachment.fileId,
+            attachment.fileName,
+            attachment.type,
+          )),
+        );
+        for (let i = 0; i < incomingMedia.length; i++) {
+          const media = incomingMedia[i];
+          const saveResult = mediaSaveResults[i];
+          if (saveResult.status === "fulfilled") {
+            downloadedMediaLines.push(formatSavedIncomingAttachmentLine(media.type, media.fileId, media.fileName, saveResult.value));
+          } else {
+            const reason = saveResult.reason instanceof Error ? saveResult.reason.message : String(saveResult.reason);
+            failedMediaLines.push(formatIncomingAttachmentErrorLine(media.type, media.fileId, media.fileName, reason));
+          }
+        }
+        if (downloadedMediaLines.length > 0 || failedMediaLines.length > 0) {
+          const lines = [
+            formatIncomingAttachmentReceipt("saved", downloadedMediaLines),
+            formatIncomingAttachmentReceipt("failed", failedMediaLines),
+          ].filter(Boolean);
+          await deps.transport.sendText(chatId, lines.join("\n\n")).catch(() => undefined);
+        }
+      }
+      const hasPromptInput = hasTextInput || hasMediaInput;
+      if (hasTextInput) {
+        const wasSensitive = deps.ui.isSensitiveInput(chatId, replyToInput);
+        const inputResult = deps.ui.resolveInput(chatId, rawText, replyToInput);
+        if (inputResult.handled) {
+          if (wasSensitive) await deps.transport.deleteMessage(chatId, message.message_id);
+          return;
+        }
+      }
+      if (hasPromptInput) {
+        const mediaBlock = (() => {
+          if (!hasMediaInput) return "";
+          const lines = [mediaSummary];
+          const statusLines = [...downloadedMediaLines, ...failedMediaLines];
+          if (statusLines.length > 0) {
+            lines.push(statusLines.join("\n"));
+          }
+          return `\n\n${lines.filter(Boolean).join("\n")}`;
+        })();
+        const handled = trimmed ? await tryHandleSlashCommand(text, chatId) : false;
+        if (!handled) {
+          const parsed = parseLeadingCommand(text);
+          const basePrompt = parsed
+            ? `/${parsed.name.replace(/_/g, "-")}${parsed.args ? ` ${parsed.args}` : ""}`
+            : trimmed || "";
+          const promptText = `${basePrompt}${mediaBlock}`.trim();
+          await submitText(promptText, chatId);
+        }
+      }
+    },
+
+  };
+}

package/lib/heartbeat.ts

@@ -0,0 +1,95 @@
+import { formatTelegramStatusLine } from "./status.ts";
+import type { TelegramConfig, TelegramTurn } from "./types.ts";
+
+const TYPING_REFRESH_MS = 4000;
+const HEARTBEAT_MS = 2000;
+
+export type StatusState = Parameters<typeof formatTelegramStatusLine>[1];
+
+export type HeartbeatDeps = {
+  getConfig: () => TelegramConfig;
+  getActiveTurn: () => TelegramTurn | undefined;
+  sendChatAction: (chatId: number, action: string) => Promise<void>;
+  ensurePollingStarted: () => void;
+};
+
+export function createHeartbeat(deps: HeartbeatDeps) {
+  let statusTimer: ReturnType<typeof setInterval> | undefined;
+  let typingTimer: ReturnType<typeof setInterval> | undefined;
+  let typingInFlight = false;
+  let typingGeneration = 0;
+
+  const sendTypingPulse = async (generation: number): Promise<void> => {
+    const turn = deps.getActiveTurn();
+    if (!turn || typingInFlight || generation !== typingGeneration) return;
+    typingInFlight = true;
+    try {
+      if (generation === typingGeneration && deps.getActiveTurn() === turn) {
+        await deps.sendChatAction(turn.chatId, "typing");
+      }
+    } catch {
+      // Non-critical: the next pulse can retry while the turn is still processing.
+    } finally {
+      typingInFlight = false;
+    }
+  };
+
+  const stopTyping = (): void => {
+    typingGeneration++;
+    if (!typingTimer) return;
+    clearInterval(typingTimer);
+    typingTimer = undefined;
+  };
+
+  const syncTypingWithStatus = (state: StatusState): void => {
+    const turn = deps.getActiveTurn();
+    // Typing strictly mirrors activeTurns.size > 0 — the same condition
+    // that drives the TUI [Working...] status.
+    const shouldType = !!(state.processing && turn);
+    if (!shouldType) {
+      stopTyping();
+      return;
+    }
+    const generation = typingGeneration;
+    void sendTypingPulse(generation);
+    if (!typingTimer) {
+      typingTimer = setInterval(() => void sendTypingPulse(generation), TYPING_REFRESH_MS);
+    }
+  };
+
+  const refreshStatus = (state: StatusState): void => {
+    // Called by the outer module which sets the TUI status line.
+    // We only sync typing from here.
+    syncTypingWithStatus(state);
+  };
+
+  const startStatusHeartbeat = (onHeartbeat: () => void): void => {
+    if (statusTimer) return;
+    statusTimer = setInterval(() => {
+      deps.ensurePollingStarted();
+      onHeartbeat();
+    }, HEARTBEAT_MS);
+  };
+
+  const stopStatusHeartbeat = (): void => {
+    if (!statusTimer) return;
+    clearInterval(statusTimer);
+    statusTimer = undefined;
+  };
+
+  const dispose = (): void => {
+    stopStatusHeartbeat();
+    stopTyping();
+  };
+
+  return {
+    refreshStatus,
+    syncTypingWithStatus,
+    startStatusHeartbeat,
+    stopStatusHeartbeat,
+    stopTyping,
+    dispose,
+    /** Expose for external clearStatus which stops typing then clears the TUI line. */
+    stopTypingOnly: stopTyping,
+  };
+}

package/lib/html.ts

@@ -0,0 +1,6 @@
+export function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}

package/lib/markdown.ts

@@ -0,0 +1,132 @@
+import { marked } from "marked";
+import type { Tokens } from "marked";
+import { escapeHtml } from "./html.ts";
+
+interface TelegramRendererContext {
+  parser: {
+    parse(tokens: unknown[]): string;
+    parseInline(tokens: unknown[]): string;
+  };
+}
+
+function inlineFromTokens(this: TelegramRendererContext, tokens?: unknown[], fallback = ""): string {
+  if (Array.isArray(tokens) && tokens.length > 0) {
+    return this.parser.parseInline(tokens as unknown[]);
+  }
+  return escapeHtml(fallback);
+}
+
+function blockFromTokens(this: TelegramRendererContext, tokens?: unknown[], fallback = ""): string {
+  if (Array.isArray(tokens) && tokens.length > 0) {
+    return this.parser.parse(tokens as unknown[]);
+  }
+  return escapeHtml(fallback);
+}
+
+const renderer = {
+  heading(this: TelegramRendererContext, { tokens }: Tokens.Heading): string {
+    return `<b>${inlineFromTokens.call(this, tokens)}</b>\n`;
+  },
+
+  paragraph(this: TelegramRendererContext, { tokens }: Tokens.Paragraph): string {
+    return `${inlineFromTokens.call(this, tokens)}\n`;
+  },
+
+  strong(this: TelegramRendererContext, { tokens }: Tokens.Strong): string {
+    return `<b>${inlineFromTokens.call(this, tokens)}</b>`;
+  },
+
+  em(this: TelegramRendererContext, { tokens }: Tokens.Em): string {
+    return `<i>${inlineFromTokens.call(this, tokens)}</i>`;
+  },
+
+  del(this: TelegramRendererContext, { tokens }: Tokens.Del): string {
+    return `<s>${inlineFromTokens.call(this, tokens)}</s>`;
+  },
+
+  codespan(this: TelegramRendererContext, { text }: Tokens.Codespan): string {
+    return `<code>${escapeHtml(text)}</code>`;
+  },
+
+  code(this: TelegramRendererContext, { text, lang }: Tokens.Code): string {
+    const language = lang ? ` class="language-${escapeHtml(lang)}"` : "";
+    return `<pre><code${language}>${escapeHtml(text)}\n</code></pre>`;
+  },
+
+  table(this: TelegramRendererContext, token: Tokens.Table): string {
+    const rows: string[] = [];
+    if (token.header.length > 0) {
+      rows.push(token.header.map((c) => inlineFromTokens.call(this, c.tokens, c.text)).join(" | "));
+      rows.push(token.header.map(() => "---").join("-+-"));
+    }
+    for (const row of token.rows) {
+      rows.push(row.map((c) => inlineFromTokens.call(this, c.tokens, c.text)).join(" | "));
+    }
+    return `<pre>${rows.join("\n")}</pre>\n`;
+  },
+
+  list(this: TelegramRendererContext, token: Tokens.List): string {
+    const start = typeof token.start === "number" ? token.start : 1;
+    const lines = token.items.map((item, index) => {
+      const bullet = token.ordered ? `${start + index}. ` : "• ";
+      return bullet + blockFromTokens.call(this, item.tokens, item.text);
+    });
+    return lines.join("\n") + "\n";
+  },
+
+  listitem(this: TelegramRendererContext, token: Tokens.ListItem): string {
+    return blockFromTokens.call(this, token.tokens, token.text);
+  },
+
+  blockquote(this: TelegramRendererContext, { tokens }: Tokens.Blockquote): string {
+    return `<blockquote>${this.parser.parse(tokens as unknown[])}</blockquote>`;
+  },
+
+  image(this: TelegramRendererContext, { text, title }: Tokens.Image): string {
+    return title ? `[${text}: ${title}]` : `[${text}]`;
+  },
+};
+
+marked.use({ renderer });
+
+/**
+ * Convert Markdown to Telegram-compatible HTML.
+ * Handles tables, lists, code blocks, blockquotes, and all inline
+ * formatting within the Telegram supported subset.
+ */
+export function markdownToTelegramHtml(markdown: string): string {
+  return (marked.parse(markdown, { async: false }) as string).replace(/\n+$/, "");
+}
+
+export function escapeAttr(text: string): string {
+  return escapeHtml(text).replace(/"/g, "&quot;");
+}
+
+/**
+ * Convert inline Markdown to Telegram HTML.
+ * Kept for backward compatibility with single-line / simple conversions.
+ */
+export function inlineMarkdownToHtml(text: string): string {
+  const links: Array<{ label: string; url: string }> = [];
+  let processed = text.replace(/\[([^\]\n]+)]\((https?:\/\/[^\s)]+)\)/g, (_m, label, url) => {
+    const idx = links.length;
+    links.push({ label, url });
+    return `\x00LINK${idx}\x00`;
+  });
+
+  let html = escapeHtml(processed);
+
+  html = html.replace(/\x00LINK(\d+)\x00/g, (_m, idxStr) => {
+    const idx = parseInt(idxStr, 10);
+    const link = links[idx];
+    if (!link) return "";
+    return `<a href="${escapeAttr(link.url)}">${escapeHtml(link.label)}</a>`;
+  });
+
+  html = html.replace(/`([^`\n]+)`/g, (_m, code) => `<code>${code}</code>`);
+  html = html.replace(/\*\*([^*\n]+)\*\*/g, (_m, bold) => `<b>${bold}</b>`);
+  html = html.replace(/__([^_\n]+)__/g, (_m, bold) => `<b>${bold}</b>`);
+  html = html.replace(/(?<!\*)\*([^*\n]+)\*(?!\*)/g, (_m, italic) => `<i>${italic}</i>`);
+  html = html.replace(/_([^_\n]+)_/g, (_m, italic) => `<i>${italic}</i>`);
+  return html;
+}