@inceptionstack/roundhouse 0.3.20 → 0.3.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inceptionstack/roundhouse",
-  "version": "0.3.20",
+  "version": "0.3.22",
   "type": "module",
   "description": "Multi-platform chat gateway that routes messages through a configured AI agent",
   "license": "MIT",

package/src/gateway.ts

@@ -9,6 +9,7 @@ import { Chat } from "chat";
 import { createMemoryState } from "@chat-adapter/state-memory";
 import type { AgentAdapter, AgentMessage, AgentRouter, AgentStreamEvent, GatewayConfig, MessageAttachment } from "./types";
 import { splitMessage, isAllowed, startTypingLoop, threadIdToDir, generateAttachmentId, DEBUG_STREAM } from "./util";
+import { isTelegramThread, postTelegramHtml, handleTelegramHtmlStream } from "./telegram-html";
 import { SttService, enrichAttachmentsWithTranscripts, DEFAULT_STT_CONFIG } from "./voice/stt-service";
 import { sendTelegramToMany } from "./notify/telegram";
 import { runDoctor, formatDoctorTelegram, createDoctorContext } from "./cli/doctor/runner";
@@ -602,7 +603,7 @@ export class Gateway {
           lines.push(`📝 Context: no usage data yet (${windowK}K window)`);
         }
 
-        await thread.post({ markdown: lines.join("\n") });
+        await this.postWithFallback(thread, lines.join("\n"));
         console.log(`[roundhouse] /status for thread=${thread.id} agentThread=${agentThreadId}`);
         return;
       }
@@ -985,14 +986,20 @@ export class Gateway {
       currentPromise = null;
     };
 
+    const useTelegramHtml = isTelegramThread(thread);
+
     const ensureStream = () => {
       if (!currentPromise) {
         const ts = createTextStream();
         currentPush = ts.push;
         currentFinish = ts.finish;
-        currentPromise = thread.handleStream(ts.iterable).catch((err: Error) => {
-          console.warn(`[roundhouse] handleStream error:`, err.message);
-        });
+        currentPromise = useTelegramHtml
+          ? handleTelegramHtmlStream(thread, ts.iterable).catch((err: Error) => {
+              console.warn(`[roundhouse] telegram html stream error:`, err.message);
+            })
+          : thread.handleStream(ts.iterable).catch((err: Error) => {
+              console.warn(`[roundhouse] handleStream error:`, err.message);
+            });
       }
     };
 
@@ -1098,6 +1105,11 @@ export class Gateway {
 
   /** Post text with markdown, falling back to plain text */
   private async postWithFallback(thread: any, text: string) {
+    // Telegram: send as HTML for proper markdown rendering
+    if (isTelegramThread(thread)) {
+      await postTelegramHtml(thread, text);
+      return;
+    }
     for (const chunk of splitMessage(text, 4000)) {
       try {
         await thread.post({ markdown: chunk });

package/src/telegram-format.ts

@@ -0,0 +1,256 @@
+/**
+ * telegram-format.ts — Convert markdown to Telegram-compatible HTML
+ *
+ * Telegram's Bot API supports a subset of HTML:
+ *   <b>, <i>, <u>, <s>, <code>, <pre>, <a href="...">, <blockquote>
+ *
+ * This converter handles common agent output patterns:
+ *   - Headers (#, ##, ###) → bold text
+ *   - ***bold italic*** → <b><i>text</i></b>
+ *   - **bold** / __bold__ → <b>
+ *   - *italic* / _italic_ → <i>
+ *   - ~~strikethrough~~ → <s>
+ *   - `inline code` → <code>
+ *   - ```code blocks``` → <pre>
+ *   - [text](url) → <a href="url">text</a>  (supports parens in URLs)
+ *   - Bullet/numbered lists preserved as-is
+ *   - HTML entities escaped (&, <, >)
+ */
+
+import { randomBytes } from "node:crypto";
+
+/** Escape HTML special characters */
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+/** Escape HTML attribute value (quotes + entities) */
+function escapeAttr(text: string): string {
+  return escapeHtml(text).replace(/"/g, "&quot;");
+}
+
+/**
+ * Match a markdown link with balanced parentheses in the URL.
+ * Returns [fullMatch, text, url, endIndex] or null.
+ */
+function matchLink(str: string, startIdx: number): { full: string; text: string; url: string; end: number } | null {
+  if (str[startIdx] !== "[") return null;
+  // Find closing ]
+  const closeBracket = str.indexOf("]", startIdx + 1);
+  if (closeBracket === -1 || str[closeBracket + 1] !== "(") return null;
+  const text = str.slice(startIdx + 1, closeBracket);
+  // Match balanced parens for URL
+  let depth = 1;
+  let i = closeBracket + 2;
+  while (i < str.length && depth > 0) {
+    if (str[i] === "(") depth++;
+    else if (str[i] === ")") depth--;
+    if (depth > 0) i++;
+  }
+  if (depth !== 0) return null;
+  const url = str.slice(closeBracket + 2, i);
+  return { full: str.slice(startIdx, i + 1), text, url, end: i + 1 };
+}
+
+/** Extract all markdown links with balanced-paren URL support */
+function extractLinks(str: string, cb: (text: string, url: string) => string): string {
+  let result = "";
+  let i = 0;
+  while (i < str.length) {
+    if (str[i] === "[") {
+      const link = matchLink(str, i);
+      if (link) {
+        result += cb(link.text, link.url);
+        i = link.end;
+        continue;
+      }
+    }
+    result += str[i];
+    i++;
+  }
+  return result;
+}
+
+/**
+ * Truncate HTML safely — avoids cutting inside tags.
+ * Finds the last '>' before the limit, or falls back to the limit itself.
+ */
+export function truncateHtmlSafe(html: string, limit: number): string {
+  if (html.length <= limit) return html;
+  if (limit <= 3) return "...";
+  const cutoff = limit - 3; // room for "..."
+  // Find the last '>' at or before cutoff to avoid splitting a tag
+  let safeEnd = cutoff;
+  for (let i = cutoff - 1; i >= Math.max(0, cutoff - 200); i--) {
+    if (html[i] === ">") {
+      safeEnd = i + 1;
+      break;
+    }
+  }
+  return html.slice(0, safeEnd) + "...";
+}
+
+/**
+ * Convert a markdown table into a <pre>-wrapped, column-aligned monospace table.
+ * Parses the header row, skips the separator row, and pads all columns to uniform width.
+ */
+function formatTable(tableMd: string): string {
+  const lines = tableMd.trim().split("\n");
+  if (lines.length < 2) return `<pre>${escapeHtml(tableMd)}</pre>`;
+
+  // Parse rows: split by | and trim each cell
+  const parseRow = (line: string): string[] =>
+    line.replace(/^\|/, "").replace(/\|$/, "").split("|").map(c => c.trim());
+
+  const headerCells = parseRow(lines[0]);
+  // lines[1] is the separator row (|---|---|) — skip it
+  const dataRows = lines.slice(2).map(parseRow);
+  const colCount = headerCells.length;
+
+  // Normalize rows to exactly colCount columns
+  const normalize = (cells: string[]): string[] =>
+    Array.from({ length: colCount }, (_, i) => cells[i] ?? "");
+
+  const rawHeader = normalize(headerCells);
+  const rawDataRows = dataRows.map(normalize);
+  const allRows = [rawHeader, ...rawDataRows];
+
+  // Visual length of a string (grapheme count via Intl.Segmenter)
+  const segmenter = new Intl.Segmenter();
+  const visualLen = (s: string): number => [...segmenter.segment(s)].length;
+
+  // Calculate max *visual* width for each column (on unescaped text,
+  // since Telegram renders entities back to their visual form in <pre>)
+  const colWidths: number[] = [];
+  for (let c = 0; c < colCount; c++) {
+    let max = 0;
+    for (const row of allRows) {
+      max = Math.max(max, visualLen(row[c]));
+    }
+    colWidths.push(max);
+  }
+
+  // Pad an escaped cell so it visually aligns to `width` rendered characters.
+  // We add (targetVisualWidth - actualVisualWidth) spaces, since spaces are
+  // 1 char both in HTML source and visually.
+  const padCell = (rawText: string, width: number): string => {
+    const escaped = escapeHtml(rawText);
+    const vLen = visualLen(rawText);
+    return escaped + " ".repeat(Math.max(0, width - vLen));
+  };
+
+  // Build formatted rows
+  const formatRow = (cells: string[]): string =>
+    "│ " + cells.map((cell, i) => padCell(cell, colWidths[i])).join(" │ ") + " │";
+
+  const separator = "├─" + colWidths.map(w => "─".repeat(w)).join("─┼─") + "─┤";
+  const topBorder = "┌─" + colWidths.map(w => "─".repeat(w)).join("─┬─") + "─┐";
+  const bottomBorder = "└─" + colWidths.map(w => "─".repeat(w)).join("─┴─") + "─┘";
+
+  // Cells are escaped inside padCell; box-drawing chars are HTML-safe.
+  const result = [
+    topBorder,
+    formatRow(rawHeader),
+    separator,
+    ...rawDataRows.map(formatRow),
+    bottomBorder,
+  ].join("\n");
+
+  return `<pre>${result}</pre>`;
+}
+
+/**
+ * Convert markdown text to Telegram-compatible HTML.
+ * Handles code blocks first (to avoid processing markdown inside them),
+ * then processes inline formatting.
+ */
+export function markdownToTelegramHtml(md: string): string {
+  // Generate unique sentinel per call to prevent spoofing
+  const sentinel = randomBytes(8).toString("hex");
+  const S = (kind: string, idx: number) => `\x00${sentinel}_${kind}_${idx}\x00`;
+  const RE = (kind: string) => new RegExp(`\\x00${sentinel}_${kind}_(\\d+)\\x00`, "g");
+
+  // Extract fenced code blocks first to protect their contents
+  // (must happen before table extraction to avoid nested <pre> tags)
+  const codeBlocks: string[] = [];
+  let processed = md.replace(/```(\w*)\n?([\s\S]*?)```/g, (_match, _lang, code) => {
+    const idx = codeBlocks.length;
+    codeBlocks.push(`<pre>${escapeHtml(code.replace(/\n$/, ""))}</pre>`);
+    return S("CB", idx);
+  });
+
+  // Extract markdown tables (now safe — code blocks are already sentinelled out)
+  const tables: string[] = [];
+  processed = processed.replace(
+    /(?:^|\n)(\|.+\|\n\|[-| :]+\|\n(?:\|.+\|(?:\n|$))+)/g,
+    (match) => {
+      const idx = tables.length;
+      const leadingNewline = match.startsWith("\n") ? "\n" : "";
+      const trailingNewline = match.endsWith("\n") ? "\n" : "";
+      const tableContent = match.replace(/^\n/, "").replace(/\n$/, "");
+      tables.push(formatTable(tableContent));
+      return leadingNewline + S("TB", idx) + trailingNewline;
+    },
+  );
+
+  // Extract inline code to protect contents
+  const inlineCodes: string[] = [];
+  processed = processed.replace(/`([^`\n]+)`/g, (_match, code) => {
+    const idx = inlineCodes.length;
+    inlineCodes.push(`<code>${escapeHtml(code)}</code>`);
+    return S("IC", idx);
+  });
+
+  // Extract links before HTML-escaping (URLs contain &, = etc. that must be escaped once)
+  const links: string[] = [];
+  processed = extractLinks(processed, (text, url) => {
+    const trimmedUrl = url.trim();
+    if (/^https?:\/\//i.test(trimmedUrl) || /^mailto:/i.test(trimmedUrl)) {
+      const idx = links.length;
+      links.push(`<a href="${escapeAttr(trimmedUrl)}">${escapeHtml(text)}</a>`);
+      return S("LK", idx);
+    }
+    // Unsafe or relative URL — render as text (will be escaped below)
+    return `${text} (${trimmedUrl})`;
+  });
+
+  // Now escape HTML in the rest
+  processed = escapeHtml(processed);
+
+  // Headers: # text → <b>text</b> (Telegram has no header tags)
+  processed = processed.replace(/^#{1,6}\s+(.+)$/gm, "<b>$1</b>");
+
+  // Bold+italic: ***text*** → <b><i>text</i></b> (must come before ** and *)
+  processed = processed.replace(/\*\*\*(.+?)\*\*\*/g, "<b><i>$1</i></b>");
+
+  // Bold: **text** or __text__
+  processed = processed.replace(/\*\*(.+?)\*\*/g, "<b>$1</b>");
+  processed = processed.replace(/__(.+?)__/g, "<b>$1</b>");
+
+  // Italic: *text* (not part of **)
+  processed = processed.replace(/(?<!\*)\*(?!\*)(.+?)(?<!\*)\*(?!\*)/g, "<i>$1</i>");
+  // _text_ only at word boundaries (avoid matching snake_case)
+  processed = processed.replace(/(?<!\w)_(?!_)(.+?)(?<!_)_(?!\w)/g, "<i>$1</i>");
+
+  // Strikethrough: ~~text~~
+  processed = processed.replace(/~~(.+?)~~/g, "<s>$1</s>");
+
+  // Blockquotes: > text (after HTML escaping, > becomes &gt;)
+  processed = processed.replace(/^&gt;\s?(.+)$/gm, "<blockquote>$1</blockquote>");
+  // Merge adjacent blockquotes
+  processed = processed.replace(/<\/blockquote>\n<blockquote>/g, "\n");
+
+  // Horizontal rules: --- or ***
+  processed = processed.replace(/^[-*]{3,}$/gm, "───────────────");
+
+  // Restore placeholders
+  processed = processed.replace(RE("LK"), (_match, idx) => links[parseInt(idx, 10)]);
+  processed = processed.replace(RE("IC"), (_match, idx) => inlineCodes[parseInt(idx, 10)]);
+  processed = processed.replace(RE("CB"), (_match, idx) => codeBlocks[parseInt(idx, 10)]);
+  processed = processed.replace(RE("TB"), (_match, idx) => tables[parseInt(idx, 10)]);
+
+  return processed;
+}

package/src/telegram-html.ts

@@ -0,0 +1,246 @@
+/**
+ * telegram-html.ts — Direct Telegram HTML posting for rich agent responses
+ *
+ * Bypasses Chat SDK's legacy parse_mode:"Markdown" (v1) by calling the
+ * Telegram Bot API directly with parse_mode:"HTML" for agent content.
+ *
+ * Chat SDK remains responsible for: incoming messages, subscriptions,
+ * typing indicators, command handling, authorization, message history.
+ */
+
+import { markdownToTelegramHtml, truncateHtmlSafe } from "./telegram-format";
+import { splitMessage } from "./util";
+
+/** Max Telegram message length */
+const TELEGRAM_LIMIT = 4096;
+
+/** Streaming edit interval (ms) */
+const STREAM_EDIT_INTERVAL_MS = 600;
+
+/** Check if a Chat SDK thread is backed by the Telegram adapter */
+export function isTelegramThread(thread: any): boolean {
+  return (
+    typeof thread?.adapter?.telegramFetch === "function" &&
+    typeof thread?.id === "string" &&
+    thread.id.startsWith("telegram:")
+  );
+}
+
+/** Parse Telegram chat_id and optional message_thread_id from a Chat SDK thread ID */
+function parseTelegramThreadId(threadId: string): { chatId: string; messageThreadId?: number } {
+  const parts = threadId.split(":");
+  const chatId = parts[1];
+  const topicPart = parts[2];
+  const result: { chatId: string; messageThreadId?: number } = { chatId };
+  if (topicPart) {
+    const parsed = parseInt(topicPart, 10);
+    if (Number.isFinite(parsed)) result.messageThreadId = parsed;
+  }
+  return result;
+}
+
+/** Common payload fields for Telegram API calls */
+function basePayload(chatId: string, messageThreadId?: number) {
+  return {
+    chat_id: chatId,
+    ...(messageThreadId !== undefined && { message_thread_id: messageThreadId }),
+    disable_web_page_preview: true,
+  };
+}
+
+/** Send one HTML message, falling back to plain text on parse error */
+async function sendHtmlOrPlain(
+  adapter: any,
+  chatId: string,
+  messageThreadId: number | undefined,
+  html: string,
+  plainFallback: string,
+): Promise<void> {
+  try {
+    await adapter.telegramFetch("sendMessage", {
+      ...basePayload(chatId, messageThreadId),
+      text: html,
+      parse_mode: "HTML",
+    });
+  } catch {
+    try {
+      await adapter.telegramFetch("sendMessage", {
+        ...basePayload(chatId, messageThreadId),
+        text: plainFallback,
+      });
+    } catch (err) {
+      console.error(`[roundhouse] Telegram sendMessage failed:`, (err as Error).message);
+    }
+  }
+}
+
+/**
+ * Post markdown as Telegram HTML, with chunking and fallback.
+ * Splits markdown into chunks before conversion so each chunk's HTML stays within limits.
+ */
+export async function postTelegramHtml(thread: any, markdown: string): Promise<void> {
+  const { chatId, messageThreadId } = parseTelegramThreadId(thread.id);
+
+  // Split before conversion — HTML expansion is usually modest
+  for (const chunk of splitMessage(markdown, 3800)) {
+    const html = markdownToTelegramHtml(chunk);
+    const safeHtml = truncateHtmlSafe(html, TELEGRAM_LIMIT);
+    await sendHtmlOrPlain(thread.adapter, chatId, messageThreadId, safeHtml, chunk);
+  }
+}
+
+/**
+ * Stream agent text as Telegram HTML using sendMessage + editMessageText.
+ *
+ * For responses under 4096 chars: single message with progressive edits.
+ * For longer responses: finalize current message and start new ones via postTelegramHtml.
+ */
+export async function handleTelegramHtmlStream(
+  thread: any,
+  stream: AsyncIterable<string>,
+): Promise<void> {
+  const { chatId, messageThreadId } = parseTelegramThreadId(thread.id);
+
+  let accumulated = "";
+  let messageId: number | null = null;
+  let lastEditContent = "";
+  let lastEditTime = 0;
+  /** Content already committed to sent messages (for overflow handling) */
+  let committedLength = 0;
+
+  const sendInitial = async (html: string): Promise<number> => {
+    const result = await thread.adapter.telegramFetch("sendMessage", {
+      ...basePayload(chatId, messageThreadId),
+      text: html,
+      parse_mode: "HTML",
+    });
+    return result.message_id;
+  };
+
+  const editMessage = async (html: string): Promise<boolean> => {
+    if (!messageId || html === lastEditContent) return true;
+    try {
+      await thread.adapter.telegramFetch("editMessageText", {
+        ...basePayload(chatId, messageThreadId),
+        message_id: messageId,
+        text: html,
+        parse_mode: "HTML",
+      });
+      lastEditContent = html;
+      lastEditTime = Date.now();
+      return true;
+    } catch {
+      // Telegram may reject if content hasn't changed or HTML is temporarily invalid
+      return false;
+    }
+  };
+
+  /** Get the current uncommitted portion of accumulated text */
+  const currentText = () => accumulated.slice(committedLength);
+
+  const renderCurrent = (): string => {
+    return markdownToTelegramHtml(currentText());
+  };
+
+  /**
+   * Check if current content exceeds the Telegram limit.
+   * If so, finalize the current message and start overflow handling.
+   */
+  const handleOverflow = async (): Promise<void> => {
+    const html = renderCurrent();
+    if (html.length <= TELEGRAM_LIMIT) return;
+
+    // Finalize current streaming message with tag-safe truncation
+    if (messageId) {
+      const truncated = truncateHtmlSafe(html, TELEGRAM_LIMIT);
+      await editMessage(truncated);
+      // Estimate how many source chars were consumed using the expansion ratio
+      const sourceLen = currentText().length;
+      const ratio = sourceLen > 0 ? html.length / sourceLen : 1;
+      const consumed = Math.min(sourceLen, Math.floor((TELEGRAM_LIMIT - 10) / Math.max(ratio, 1)));
+      committedLength += consumed;
+      messageId = null;
+      lastEditContent = "";
+    }
+  };
+
+  for await (const chunk of stream) {
+    accumulated += chunk;
+
+    if (!messageId) {
+      // First chunk (or after overflow) — send initial message
+      const html = renderCurrent();
+      if (html.trim()) {
+        const safeHtml = truncateHtmlSafe(html, TELEGRAM_LIMIT);
+        try {
+          messageId = await sendInitial(safeHtml);
+          lastEditContent = safeHtml;
+          lastEditTime = Date.now();
+        } catch {
+          try {
+            const result = await thread.adapter.telegramFetch("sendMessage", {
+              ...basePayload(chatId, messageThreadId),
+              text: currentText(),
+            });
+            messageId = result.message_id;
+            lastEditContent = currentText();
+            lastEditTime = Date.now();
+          } catch (err) {
+            console.error(`[roundhouse] Telegram stream initial send failed:`, (err as Error).message);
+          }
+        }
+      }
+      continue;
+    }
+
+    // Check for overflow before editing
+    await handleOverflow();
+
+    // Throttled edit (only if we still have an active message)
+    if (messageId) {
+      const now = Date.now();
+      if (now - lastEditTime >= STREAM_EDIT_INTERVAL_MS) {
+        const html = renderCurrent();
+        const safeHtml = truncateHtmlSafe(html, TELEGRAM_LIMIT);
+        await editMessage(safeHtml);
+      }
+    }
+  }
+
+  // Final: handle any remaining content
+  const remaining = currentText();
+  if (!remaining.trim()) return;
+
+  if (messageId) {
+    // Try final edit
+    const finalHtml = renderCurrent();
+    if (finalHtml.length <= TELEGRAM_LIMIT) {
+      const ok = await editMessage(finalHtml);
+      if (!ok) {
+        // Fallback to plain text edit
+        try {
+          await thread.adapter.telegramFetch("editMessageText", {
+            ...basePayload(chatId, messageThreadId),
+            message_id: messageId,
+            text: remaining,
+          });
+        } catch { /* at least some content was sent */ }
+      }
+    } else {
+      // Content exceeds limit — finalize current message and post remainder
+      const truncated = truncateHtmlSafe(finalHtml, TELEGRAM_LIMIT);
+      await editMessage(truncated);
+      // Estimate consumed source chars using expansion ratio
+      const remLen = remaining.length;
+      const ratio = remLen > 0 ? finalHtml.length / remLen : 1;
+      const overflowStart = Math.min(remLen, Math.floor((TELEGRAM_LIMIT - 10) / Math.max(ratio, 1)));
+      const overflow = remaining.slice(overflowStart);
+      if (overflow.trim()) {
+        await postTelegramHtml(thread, overflow);
+      }
+    }
+  } else {
+    // No active message — post everything remaining
+    await postTelegramHtml(thread, remaining);
+  }
+}