switchroom 0.16.23 → 0.16.27

package/telegram-plugin/format.ts

@@ -1,649 +1,467 @@
 /**
- * Telegram-flavored markdown→HTML rendering and chunking.
+ * Telegram rich-message formatting helpers.
  *
- * Extracted from server.ts so tests can import these helpers without
- * triggering the bot startup side effects (env loading, token check,
- * grammy instantiation). server.ts re-exports the public API for
- * backwards compatibility with any external callers.
+ * Since the Bot API 10.1 migration (#2669) every outbound message goes
+ * through `sendRichMessage` / `editMessageText({ markdown })` with raw GFM
+ * markdown. The old markdown→HTML engine, the HTML sanitizer, and the
+ * MarkdownV2 escaper are all gone — there is exactly ONE rendering path.
  *
- * Three pieces:
- *   - markdownToHtml + isLikelyTelegramHtml: convert model output to
- *     Telegram-safe HTML, preserving any embedded whitelisted Telegram
- *     HTML tags so the model can mix markdown bold with raw <b>/<i>/<a>.
- *   - splitHtmlChunks: split a long HTML message into <=4096-char chunks
- *     that preserve open/close tag balance and don't bisect HTML entities.
- *   - escapeHtml: the three-char escape used everywhere.
+ * What lives here now:
+ *   - repairEscapedWhitespace: format-agnostic repair of LLM-side JSON
+ *     escape bungles (literal `\n` etc.). Applied to raw text BEFORE it is
+ *     handed to the rich-message path.
+ *   - escapeMarkdown: escape GFM-special characters in DYNAMIC content
+ *     (filenames, user input, ids) so they render literally inside a
+ *     hand-built markdown card instead of being interpreted as formatting.
+ *   - splitMarkdownChunks: split a long markdown body into <=maxLen chunks
+ *     at safe boundaries (never mid code-fence, never mid table row),
+ *     defaulting maxLen to the rich-message cap of 32768.
+ *   - normalizeParagraphBreaks: promote a LONE prose `\n` into a GFM hard
+ *     break (`  \n`) so paragraph separation survives the rich GFM path,
+ *     while leaving lists / tables / code / `\n\n` untouched.
+ *   - RICH_MESSAGE_MAX_CHARS: the rich-text wire cap (32768).
  */
 
 /**
- * Telegram-supported HTML tags. Anything outside this set is either
- * unrecognized (Telegram strips it) or actively dangerous (the API
- * rejects the message). Source: https://core.telegram.org/bots/api#html-style
+ * Rich-message wire cap. Bot API 10.1 rich messages allow up to 32768
+ * UTF-8 characters (JSDoc-only in @grammyjs/types; no exported constant,
+ * so we hard-code it). The legacy plain-text `sendMessage`/`editMessageText`
+ * cap of 4096 does NOT apply on the rich path.
  */
-export const TELEGRAM_HTML_TAGS = new Set([
-  'b', 'strong',
-  'i', 'em',
-  'u', 'ins',
-  's', 'strike', 'del',
-  'span', // requires class="tg-spoiler"
-  'tg-spoiler',
-  'a',
-  'tg-emoji',
-  'code',
-  'pre',
-  'blockquote',
-])
+export const RICH_MESSAGE_MAX_CHARS = 32768
 
 /**
- * Heuristic: does this look like already-rendered Telegram HTML rather
- * than markdown waiting to be converted?
+ * Escape the GFM-markdown special characters so a dynamic value
+ * (a filename, an id, arbitrary user text) renders LITERALLY inside a
+ * hand-built markdown card instead of being parsed as formatting.
  *
- * Returns true when ALL the tags we find are recognized Telegram HTML
- * tags AND there's at least one of them AND the text doesn't also have
- * markdown-only syntax (** for bold, [text](url) for links). This is
- * conservative: if the model wrote `<div>foo</div>` (not Telegram HTML),
- * we treat it as markdown and escape it. If the model wrote `<b>foo</b>`,
- * we trust it.
+ * Used wherever the old HTML cards called `escapeHtml(value)` while
+ * interpolating into `<b>…</b>` / `<code>…</code>`. The markdown
+ * equivalent is `**${escapeMarkdown(value)}**` / `` `${value}` `` (code
+ * spans don't need escaping — backtick content is literal).
  *
- * Critical: we strip markdown code spans and fenced code blocks BEFORE
- * scanning for tags, because the model frequently writes things like
- * `\`<b>tag</b>\`` (an inline code example showing literal HTML). Without
- * the strip, the heuristic would see `<b>` inside the code span and
- * misclassify the whole text as raw HTML.
+ * Escapes only the characters that trigger INLINE formatting in
+ * rich-markdown — backslash, `` ` ``, `*`, `_`, `~`, `=`, `[`, `]`, `|`.
+ * Deliberately does NOT escape `.` `-` `+` `#` `(` `)` `{` `}` `!` `>`:
+ * those are only meaningful at line-start (headings, lists, quotes) or in
+ * link/structure context, and escaping them mid-word (filenames like
+ * `foo.ts`, versions like `v1.2-rc`, URLs) would litter the output with
+ * visible backslashes. The backslash is escaped first so we never
+ * double-escape.
  */
-export function isLikelyTelegramHtml(text: string): boolean {
-  // Strip fenced code blocks first (greedy, cross-line)
-  let scanText = text.replace(/```[\s\S]*?```/g, '')
-  // Then strip inline code spans (single backticks, no newlines)
-  scanText = scanText.replace(/`[^`\n]+`/g, '')
-
-  // If the stripped text contains markdown-only syntax (**bold**,
-  // [text](url), or markdown headings), the caller is writing markdown
-  // even if they ALSO sprinkled some <b> tags in. Treat as markdown.
-  if (/\*\*[^\n*]+\*\*/.test(scanText)) return false
-  if (/\[[^\]]+\]\([^)]+\)/.test(scanText)) return false
-  if (/^#{1,6}\s+/m.test(scanText)) return false
-
-  // Now count remaining HTML tags
-  const tagMatches = scanText.matchAll(/<\/?([a-z][a-z0-9-]*)\b[^>]*>/gi)
-  let count = 0
-  for (const m of tagMatches) {
-    const tag = m[1].toLowerCase()
-    if (!TELEGRAM_HTML_TAGS.has(tag)) {
-      // Found an unsupported tag — caller didn't intend Telegram HTML
-      return false
-    }
-    count++
-  }
-  return count > 0
+export function escapeMarkdown(text: string): string {
+  return text.replace(/([\\`*_~=\[\]|])/g, '\\$1')
 }
 
-// ---------------------------------------------------------------------------
-// Markdown table → Telegram HTML
-// ---------------------------------------------------------------------------
-
 /**
- * Parse a contiguous block of lines as a markdown table.
+ * Repair LLM-side JSON escape bungles.
  *
- * A valid markdown table requires:
- *   - A header row:    | col | col |   (leading/trailing pipes optional)
- *   - A separator row: | --- | --- |   (cells are only dashes, colons, spaces)
- *   - At least one data row.
+ * Some MCP clients (and some LLM tool-call generators) occasionally emit a
+ * tool-argument string whose whitespace has been double-escaped — real
+ * newlines become the two-character sequence `\n`, tabs become `\t`, etc.
+ * The message then ships to Telegram intact and the user sees literal
+ * `\n\n` in the chat instead of paragraph breaks.
  *
- * The separator row is the discriminating signal — it prevents plain prose
- * lines that happen to contain a pipe (e.g. `echo foo | bar`) from being
- * mistaken for tables.
+ * Unescape literal `\n`, `\r`, `\t`, and `\"` sequences everywhere EXCEPT
+ * inside code spans (inline backtick spans and fenced ``` blocks). Those
+ * regions are masked with placeholders before the unescape pass so that a
+ * literal `\n` a user typed inside a shell snippet or regex is preserved
+ * verbatim. The genuine escaped-backslash sequence `\\n` (which the user
+ * intended as a literal backslash + n, not a newline) is handled by
+ * protecting `\\` before touching `\n`.
  *
- * Returns null when the block is not a valid table.
+ * This deliberately fires even when the message contains real newlines —
+ * the old whole-message heuristic ("bail if any real newline exists") was
+ * too broad and prevented repair of mixed messages that had both real
+ * newlines and stray literal `\n` escape sequences outside code spans.
  */
-function parseMarkdownTable(lines: string[]): { headers: string[]; rows: string[][] } | null {
-  if (lines.length < 3) return null
-
-  // Separator line: cells contain only dashes, colons, and spaces.
-  const sepRe = /^\|?(?:[ \t]*:?-+:?[ \t]*\|)+[ \t]*:?-*:?[ \t]*\|?$/
-  // A pipe-delimited row: must contain at least one |
-  const rowRe = /\|/
-
-  // Find the separator line index (must be index 1 in this block)
-  if (!sepRe.test(lines[1].trim())) return null
-  // Double-check: the header row must also look like a table row
-  if (!rowRe.test(lines[0])) return null
-  // Must have at least one data row
-  if (lines.length < 3 || !rowRe.test(lines[2])) return null
-
-  const splitRow = (line: string): string[] =>
-    line
-      .replace(/^\|/, '')
-      .replace(/\|$/, '')
-      .split('|')
-      .map(c => c.trim())
-
-  const headers = splitRow(lines[0])
-  const rows: string[][] = []
-  for (let i = 2; i < lines.length; i++) {
-    if (!rowRe.test(lines[i])) break
-    rows.push(splitRow(lines[i]))
-  }
+export function repairEscapedWhitespace(text: string): string {
+  if (!/\\[nrt"\\]/.test(text)) return text
+
+  // Per-call random nonce prevents sentinel collision: if user text happens to
+  // contain our placeholder bytes, the restore step would look up an out-of-range
+  // index and produce "undefined" in the Telegram output. A nonce that is unique
+  // per invocation makes the sentinel statistically impossible to collide with.
+  const nonce = Math.random().toString(36).slice(2)
+  const BACKSLASH_PH = `\x00BK${nonce}_`
 
-  if (rows.length === 0) return null
-  return { headers, rows }
+  // Mask fenced code blocks and inline code spans so the unescape pass never
+  // touches their content (shared masker — see maskCodeRegions for the exact
+  // closed-fence / inline-span definitions).
+  const { masked, restore } = maskCodeRegions(text, nonce)
+
+  // Order matters: protect existing `\\` first so `\\n` stays as a literal
+  // backslash + n and doesn't become a newline.
+  const unescaped = masked
+    .replace(/\\\\/g, BACKSLASH_PH)
+    .replace(/\\n/g, '\n')
+    .replace(/\\r/g, '\r')
+    .replace(/\\t/g, '\t')
+    .replace(/\\"/g, '"')
+    .replace(new RegExp(BACKSLASH_PH.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g'), '\\')
+
+  // Restore masked code spans verbatim.
+  return restore(unescaped)
+}
+
+// ---------------------------------------------------------------------------
+// Shared code-region masking (used by repairEscapedWhitespace AND
+// normalizeParagraphBreaks). Closed fenced blocks (``` … ```) and inline
+// code spans (` … `) are replaced with unique placeholders so neither pass
+// ever rewrites their interior; `restore` puts them back verbatim.
+// ---------------------------------------------------------------------------
+
+interface MaskedCode {
+  masked: string
+  restore: (s: string) => string
+  /** The placeholder prefix injected for each masked region (fence or span). */
+  placeholder: string
 }
 
 /**
- * Render a parsed markdown table as Telegram-compatible HTML.
+ * Mask fenced code blocks and inline code spans with collision-resistant
+ * placeholders. `nonce` is a per-call random string the caller already holds
+ * (so two maskers in one function share one nonce namespace cleanly).
  *
- * Branch rules:
- *   - ≤3 columns AND ≤6 rows → bullet list:
- *       Each row is one bullet. First column in <b>; subsequent columns
- *       appended as " — value".
- *   - otherwise → <pre> block with padded columns.
+ * Fenced blocks are extracted FIRST and only when CLOSED (matching ```), so an
+ * unclosed fence is left intact rather than misparsed by the inline pass. Inline
+ * spans use `[^\`\n]+` — the same definition the chunker treats as code.
  */
-function renderTable(headers: string[], rows: string[][]): string {
-  const colCount = headers.length
-  const rowCount = rows.length
-
-  if (colCount <= 3 && rowCount <= 6) {
-    // Bullet list rendering
-    const bullets = rows.map(row => {
-      // Normalise row length to match header count (guard empty cells)
-      const cells = headers.map((_, i) => (row[i] ?? '').trim())
-      const key = escapeHtml(cells[0] || '—')
-      const rest = cells
-        .slice(1)
-        .filter(v => v !== '')
-        .map(v => ` — ${escapeHtml(v)}`)
-        .join('')
-      return `• <b>${key}</b>${rest}`
+function maskCodeRegions(text: string, nonce: string): MaskedCode {
+  const CODE_MASK_PH = `\x00RM${nonce}_`
+  const codeMasks: string[] = []
+
+  const masked = text
+    .replace(/```[\s\S]*?```/g, (m) => {
+      const idx = codeMasks.length
+      codeMasks.push(m)
+      return `${CODE_MASK_PH}${idx}\x00`
+    })
+    .replace(/`[^`\n]+`/g, (m) => {
+      const idx = codeMasks.length
+      codeMasks.push(m)
+      return `${CODE_MASK_PH}${idx}\x00`
     })
-    // Prepend header names as a label line when there are 2+ columns
-    const headerLine =
-      colCount >= 2
-        ? `<b>${headers.map(h => escapeHtml(h)).join(' / ')}</b>\n`
-        : ''
-    return headerLine + bullets.join('\n')
-  }
 
-  // Pre-block with padded columns
-  // Compute column widths across headers + all rows
-  const allRows = [headers, ...rows]
-  const widths = headers.map((_, ci) =>
-    Math.max(...allRows.map(r => (r[ci] ?? '').length))
+  const restoreRe = new RegExp(
+    `${CODE_MASK_PH.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(\\d+)\x00`,
+    'g',
   )
-  const pad = (s: string, w: number) => s + ' '.repeat(Math.max(0, w - s.length))
-
-  const formatRow = (r: string[]) =>
-    headers.map((_, ci) => pad(r[ci] ?? '', widths[ci])).join('  ')
+  const restore = (s: string): string =>
+    s.replace(restoreRe, (_m, idx) => codeMasks[Number(idx)] ?? _m)
 
-  const sepLine = widths.map(w => '-'.repeat(w)).join('  ')
-
-  const lines = [
-    formatRow(headers),
-    sepLine,
-    ...rows.map(r => formatRow(r)),
-  ]
-  return `<pre>${escapeHtml(lines.join('\n'))}</pre>`
+  return { masked, restore, placeholder: CODE_MASK_PH }
 }
 
+// ---------------------------------------------------------------------------
+// Paragraph-break normalizer — make lone prose newlines survive the GFM path
+// ---------------------------------------------------------------------------
+
 /**
- * Replace markdown table blocks in `text` with rendered HTML, storing the
- * rendered output in `store` and emitting `placeholderPrefix<n>\x00` tokens
- * so the rest of the pipeline does not re-process them.
+ * GFM (the rich-message render path) treats a LONE `\n` as a *soft* break: the
+ * two lines collapse onto the same visual line, so a model that separates its
+ * paragraphs with a single newline produces a cramped wall of text. The old
+ * markdown→HTML path rendered every `\n` as a hard break, which masked the
+ * habit; the rich path no longer does.
+ *
+ * This normalizer fixes that DETERMINISTICALLY without breaking GFM block
+ * syntax. It does exactly two things, on code-masked text:
  *
- * Tables are identified by their separator line (`| --- |`) which prevents
- * plain prose containing a pipe (e.g. `echo foo | bar`) from being mistaken
- * for a table. Fenced code blocks are extracted before this runs, so
- * table-looking rows inside ``` blocks are already protected.
+ *   1. Collapse runs of 3+ newlines down to exactly `\n\n` (never collapse a
+ *      genuine `\n\n` paragraph gap).
+ *   2. Promote a LONE `\n` (one not adjacent to another `\n`) into a GFM hard
+ *      break (`  \n`, two trailing spaces) — but ONLY when it is a genuine
+ *      prose paragraph break.
+ *
+ * The promotion heuristic is deliberately CONSERVATIVE — it prefers a false
+ * negative (leaving a break un-promoted, so two prose lines stay cramped) over
+ * a false positive (double-spacing a tight list or table). A break is promoted
+ * only when ALL of these hold:
+ *
+ *   - The preceding line ends in sentence-terminal punctuation: `.`, `!`, `?`,
+ *     `:`, or a closing `)` / `"` / `'` / `’` / `”` that itself follows such a
+ *     terminator (e.g. `...done.")`).
+ *   - The preceding line is NOT itself a marker line (list / table / quote /
+ *     heading).
+ *   - The NEXT line starts with a non-marker character: not a list bullet
+ *     (`-`/`*`/`+`/`\d+.`/`\d+)`, incl. indented), not a table row (`|` or
+ *     ` | `), not a blockquote (`>`), not a heading (`#`), not blank.
+ *
+ * Code fences and inline code are masked out before any of this runs, so their
+ * interior `\n`s are never touched.
  */
-function extractMarkdownTables(
-  text: string,
-  store: string[],
-  placeholderPrefix: string,
-): string {
-  const inputLines = text.split('\n')
-  const outputLines: string[] = []
-  let i = 0
-
-  while (i < inputLines.length) {
-    const line = inputLines[i]
-    if (!line.includes('|')) {
-      outputLines.push(line)
-      i++
-      continue
-    }
+export function normalizeParagraphBreaks(text: string): string {
+  if (!text.includes('\n')) return text
 
-    // Collect a run of pipe-containing lines as a candidate block
-    let j = i
-    while (j < inputLines.length && inputLines[j].includes('|')) {
-      j++
-    }
-    const block = inputLines.slice(i, j)
-
-    const parsed = parseMarkdownTable(block)
-    if (parsed) {
-      const tableLineCount = 2 + parsed.rows.length
-      const remainder = block.slice(tableLineCount)
-      const idx = store.length
-      store.push(renderTable(parsed.headers, parsed.rows))
-      outputLines.push(`${placeholderPrefix}${idx}\x00`)
-      for (const r of remainder) outputLines.push(r)
-      i = j
-    } else {
-      for (const b of block) outputLines.push(b)
-      i = j
+  const nonce = Math.random().toString(36).slice(2)
+  const { masked, restore, placeholder } = maskCodeRegions(text, nonce)
+
+  // Step 1: collapse 3+ newlines to exactly two. This also normalizes runs that
+  // contain interleaved spaces only between the newlines is NOT done here —
+  // we only touch pure newline runs so we never eat meaningful whitespace.
+  let out = masked.replace(/\n{3,}/g, '\n\n')
+
+  // Step 2: walk lines and promote lone prose breaks. We rebuild the string by
+  // joining lines with the right separator. A separator is "hard" (`  \n`) only
+  // when the break between this line and the next is a genuine prose paragraph
+  // break per the heuristic; otherwise it stays a plain `\n`. Blank lines (the
+  // `\n\n` gaps) are preserved as empty entries in the split, so we never
+  // promote a break that is adjacent to a blank line.
+  const lines = out.split('\n')
+  const pieces: string[] = []
+  for (let i = 0; i < lines.length; i++) {
+    let line = lines[i]
+    const isLast = i === lines.length - 1
+    const next = isLast ? '' : lines[i + 1]
+    // A blank current or next line means this is part of a `\n\n` gap — leave
+    // the separator as a plain newline (the blank entry reconstructs the gap).
+    const promote =
+      !isLast &&
+      line.trim() !== '' &&
+      next.trim() !== '' &&
+      shouldPromoteBreak(line, next, placeholder)
+    if (promote) {
+      // Strip any trailing whitespace the line already carried so we emit
+      // exactly one `  \n` hard break (never accumulate spaces on a re-run).
+      // Include `\r` so a CRLF source ("Alpha.\r\nBravo.") doesn't strand a
+      // lone carriage return before the injected `  \n`.
+      line = line.replace(/[ \t\r]+$/, '')
     }
+    pieces.push(line)
+    if (isLast) break
+    pieces.push(promote ? '  \n' : '\n')
   }
-
-  return outputLines.join('\n')
+  out = pieces.join('')
+
+  // Step 3: guarantee a blank line (`\n\n`) at BLOCK BOUNDARIES. The
+  // prose-promotion above keeps lists/tables tight by leaving their single
+  // `\n` separators alone — but GFM's rich renderer needs a blank line to
+  // START a new block, so a block that is glued to the previous line by a
+  // single `\n` fails to render (a table prints as literal pipe text, prose
+  // after a list is absorbed as a lazy list continuation). This pass inserts
+  // the missing blank line at those transitions only, on the same masked text,
+  // never touching code interiors, never collapsing/expanding existing `\n\n`,
+  // and never splitting a table's header/delimiter/body rows apart.
+  out = ensureBlockBoundaries(out, placeholder)
+
+  return restore(out)
 }
 
-/**
- * Convert markdown to Telegram-compatible HTML.
- * Handles bold, italic, code, code blocks, strikethrough, links.
- * Escapes HTML entities in plain text. Wraps file references in <code>.
- * Preserves embedded whitelisted Telegram HTML tags so the model can
- * mix markdown and raw HTML in the same message.
- */
-export function markdownToHtml(text: string): string {
-  // Smart pass-through: if the input is already valid Telegram HTML
-  // (every tag is in the supported list), trust the caller and return
-  // it unchanged.
-  if (isLikelyTelegramHtml(text)) {
-    return text
-  }
+// ---------------------------------------------------------------------------
+// Block-boundary blank-line guarantee (Step 3 of normalizeParagraphBreaks)
+// ---------------------------------------------------------------------------
 
-  // First, extract code blocks and inline code to protect them from other transforms.
-  const codeBlocks: string[] = []
-  const BLOCK_PH = '\x00CODEBLOCK'
-  const INLINE_PH = '\x00CODEINLINE'
-
-  // Tables are extracted after code blocks so that table-looking rows inside
-  // fenced code blocks are already parked in codeBlocks placeholders and
-  // won't be touched. Rendered table HTML is stored alongside codeBlocks and
-  // uses the same placeholder so restoration happens in a single pass.
-  const TABLE_PH = '\x00TABLEBLOCK'
-
-  // Code blocks: ```lang\ncode\n```
-  let result = text.replace(/```(\w*)\n([\s\S]*?)```/g, (_m, lang: string, code: string) => {
-    const escaped = escapeHtml(code.replace(/\n$/, ''))
-    const cls = lang ? ` class="language-${lang}"` : ''
-    const idx = codeBlocks.length
-    codeBlocks.push(`<pre><code${cls}>${escaped}</code></pre>`)
-    return `${BLOCK_PH}${idx}\x00`
-  })
-
-  // Extract markdown tables after fenced code blocks are parked. Rendered
-  // HTML is stored in codeBlocks (shared store); TABLE_PH is a distinct
-  // prefix so the two restore regexes below can target each independently.
-  result = extractMarkdownTables(result, codeBlocks, TABLE_PH)
-
-  // Convert markdown headings (# / ## / ### ...) to bold lines on their
-  // own. Telegram has no <h1> tag, and rendering ## as plain text leaves
-  // ugly hash marks in the message.
-  result = result.replace(/^(#{1,6})\s+(.+?)\s*$/gm, (_m, _hashes, title: string) => {
-    return `**${title}**`
-  })
-
-  // Inline code: `code`
-  const inlineCodes: string[] = []
-  result = result.replace(/`([^`\n]+)`/g, (_m, code: string) => {
-    const idx = inlineCodes.length
-    inlineCodes.push(`<code>${escapeHtml(code)}</code>`)
-    return `${INLINE_PH}${idx}\x00`
-  })
-
-  // Telegram HTML tag pass-through. Extract any opening/closing tag
-  // whose name is in the whitelist into placeholders. The TEXT BETWEEN
-  // tags still flows through escapeHtml and the markdown conversions
-  // below, so `<b>**bold**</b>` and `<b>plain</b>` both work. Tags are
-  // restored verbatim at the very end.
-  const htmlTags: string[] = []
-  const HTMLTAG_PH = '\x00HTMLTAG'
-  const tagNamePattern = Array.from(TELEGRAM_HTML_TAGS).join('|')
-  const htmlTagRe = new RegExp(`</?(?:${tagNamePattern})\\b[^>]*>`, 'gi')
-  result = result.replace(htmlTagRe, (match: string) => {
-    const idx = htmlTags.length
-    htmlTags.push(match)
-    return `${HTMLTAG_PH}${idx}\x00`
-  })
-
-  // Escape HTML entities in remaining plain text
-  result = escapeHtml(result)
-
-  // Bold: **text** (must come before italic)
-  result = result.replace(/\*\*(.+?)\*\*/g, '<b>$1</b>')
-
-  // Italic: *text* (single asterisk, not preceded by another *)
-  result = result.replace(/(?<!\*)\*(?!\*)(.+?)(?<!\*)\*(?!\*)/g, '<i>$1</i>')
-
-  // Italic: _text_ (underscore form). Lookarounds guard snake_case,
-  // __double__, and word-internal underscores. Emoji codepoints are not
-  // \w, so emoji-leading/trailing italics like `_📥 queued_` work correctly.
-  result = result.replace(/(?<![\w_])_(?!_)([^_\n]+?)_(?![\w_])/g, '<i>$1</i>')
-
-  // Strikethrough: ~~text~~
-  result = result.replace(/~~(.+?)~~/g, '<s>$1</s>')
-
-  // Restore inline-code, code-block, and table-block placeholders ONLY
-  // AFTER bold/italic/strike have run. If the inline-code placeholder
-  // is restored before italic, an inline-code span containing asterisks
-  // (e.g. `\`size_t *p\``) gets matched by the italic regex on the
-  // restored `<code>...*p</code>` buffer and produces invalid HTML
-  // that Telegram rejects with 400 Bad Request — sending the caller
-  // into a `format: text` fallback for the rest of the chunk. Same
-  // fault class for code blocks containing `**` literals. See #415.
-  result = result.replace(new RegExp(`${escapeHtml(BLOCK_PH)}(\\d+)${escapeHtml('\x00')}`, 'g'), (_m, idx) => codeBlocks[Number(idx)])
-  result = result.replace(new RegExp(`${escapeHtml(TABLE_PH)}(\\d+)${escapeHtml('\x00')}`, 'g'), (_m, idx) => codeBlocks[Number(idx)])
-  result = result.replace(new RegExp(`${escapeHtml(INLINE_PH)}(\\d+)${escapeHtml('\x00')}`, 'g'), (_m, idx) => inlineCodes[Number(idx)])
-
-  // Links: [text](url). Two safety requirements here:
-  //
-  //  1. URL scheme allowlist. Unrestricted href accepts `javascript:` and
-  //     `data:` URIs; Telegram historically renders tg:// links directly
-  //     (opening another bot) which is a phishing primitive. Anything not
-  //     in the allowlist falls back to `#`.
-  //
-  //  2. Escape the URL before interpolating into the attribute. The HTML
-  //     tag extraction above parks whitelisted tags in \x00HTMLTAG<n>\x00
-  //     placeholders that get restored AFTER this replace. Without escaping
-  //     the href value, an adversarial `[text](x"></a><a href="evil">)` in
-  //     model output produces two <a> tags after placeholder restoration —
-  //     the second hijacks the visible link target. escapeAttr covers both
-  //     the placeholder-restoration attack and plain `"` breakout.
-  const ALLOWED_LINK_SCHEMES = /^(?:https?|mailto|tel|tg):/i
-  result = result.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_m, linkText: string, url: string) => {
-    const safe = ALLOWED_LINK_SCHEMES.test(url.trim()) ? url.trim() : '#'
-    return `<a href="${escapeHtml(safe)}">${linkText}</a>`
-  })
-
-  // File references: wrap filename.ext patterns in <code> tags.
-  // Lookbehind excludes `>` so we don't double-wrap filenames that are
-  // already inside a restored inline-code placeholder like
-  // `<code>settings.json</code>`. Without this, the regex matched the
-  // filename character immediately after the `>` of the opening <code>
-  // tag and re-wrapped it, producing `<code><code>settings.json</code></code>`.
-  result = result.replace(/(?<![<\/\w>])(\b[\w][\w.-]*\.(?:ts|js|py|rs|go|json|yaml|yml|toml|md|txt|sh|bash|zsh|css|html|xml|sql|env|cfg|conf|ini|log|csv|tsx|jsx|vue|svelte|rb|java|kt|swift|c|cpp|h|hpp|zig|asm|wasm|lock|mod|sum)\b)(?![^<]*>)/g, '<code>$1</code>')
-
-  // Restore preserved Telegram HTML tags (must run last so the file-ref
-  // regex above doesn't accidentally match characters inside our placeholders).
-  result = result.replace(new RegExp(`${escapeHtml(HTMLTAG_PH)}(\\d+)${escapeHtml('\x00')}`, 'g'), (_m, idx) => htmlTags[Number(idx)])
-
-  return result
+/** A line that begins a GFM list item (bullet or ordered), incl. leading indent. */
+function isListItemLine(line: string): boolean {
+  const t = line.trimStart()
+  return /^[-*+]\s/.test(t) || /^\d+[.)]\s/.test(t)
 }
 
-export function escapeHtml(text: string): string {
-  // Also escape `"` so callers that interpolate into HTML attribute values
-  // don't need a second helper. Safe for tag-content use too.
-  return text
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
+/** A GFM table body/header row: a line whose first non-space char is `|`. */
+function isTableRowLine(line: string): boolean {
+  return /^\s*\|/.test(line)
 }
 
 /**
- * Last-resort renderer: turn (possibly malformed) Telegram HTML into
- * readable plain text. Used by the gateway's send/edit path when
- * Telegram rejects a chunk with a 400 "can't parse entities" /
- * "unsupported start tag" — i.e. our HTML prevention (markdownToHtml +
- * sanitizeForTelegram + splitHtmlChunks) let something through anyway.
- *
- * The caller resends the result with `parse_mode` UNSET, so the output
- * is literal text — we intentionally do NOT re-escape `< > &`. The goal
- * is "the agent's answer lands unformatted" instead of "the answer
- * silently vanishes" (visibility + always-on).
- *
- * Transforms, in order:
- *  1. `<a href="u">label</a>` → `label (u)` (or just `u` when label is
- *     empty or equals the href). href/label are themselves stripped +
- *     entity-decoded so we never emit nested markup.
- *  2. Block / break boundaries → newline: `<br>`, `</p>`, `</div>`,
- *     `</li>`, `</blockquote>`, `</pre>`. (These aren't Telegram-
- *     supported tags, but a markdown→HTML slip that emits one is a
- *     prime cause of the parse reject we're recovering from.)
- *  3. Strip every remaining tag.
- *  4. Decode the standard HTML entities Telegram uses.
- *  5. Collapse 3+ blank lines to 2; trim trailing per-line whitespace.
+ * A GFM table delimiter row: optional leading pipe, then one or more
+ * `:?-{1,}:?` cells separated by pipes (e.g. `|---|---|`, `---|:--:`,
+ * `| :-- | --: |`). This is what turns the line ABOVE it into a table header.
  */
-export function telegramHtmlToPlainText(html: string): string {
-  const decodeEntities = (s: string): string =>
-    s
-      .replace(/&amp;/g, '&')
-      .replace(/&lt;/g, '<')
-      .replace(/&gt;/g, '>')
-      .replace(/&quot;/g, '"')
-      .replace(/&#0*39;|&#x0*27;|&apos;/gi, "'")
-      .replace(/&nbsp;/g, ' ')
-      .replace(/&#(\d+);/g, (_m, d: string) => {
-        const cp = Number(d)
-        return Number.isFinite(cp) && cp > 0 && cp <= 0x10ffff
-          ? String.fromCodePoint(cp)
-          : _m
-      })
-      .replace(/&#x([0-9a-fA-F]+);/g, (_m, h: string) => {
-        const cp = parseInt(h, 16)
-        return Number.isFinite(cp) && cp > 0 && cp <= 0x10ffff
-          ? String.fromCodePoint(cp)
-          : _m
-      })
-
-  const stripTags = (s: string): string =>
-    decodeEntities(
-      s
-        .replace(/<\s*br\s*\/?\s*>/gi, '\n')
-        .replace(/<\/\s*(?:p|div|li|blockquote|pre|h[1-6])\s*>/gi, '\n')
-        .replace(/<[^>]*>/g, ''),
-    )
-
-  // 1. Anchors → "label (href)". Handle double/single/unquoted href.
-  const withPlainLinks = html.replace(
-    /<a\b[^>]*\bhref\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))[^>]*>([\s\S]*?)<\/a>/gi,
-    (_m, dq: string | undefined, sq: string | undefined, uq: string | undefined, label: string) => {
-      const href = decodeEntities((dq ?? sq ?? uq ?? '').trim())
-      const text = stripTags(label).trim()
-      if (!href) return text
-      return !text || text === href ? href : `${text} (${href})`
-    },
-  )
+function isTableDelimiterLine(line: string): boolean {
+  return /^\s*\|?\s*:?-{1,}:?\s*(\|\s*:?-{1,}:?\s*)*\|?\s*$/.test(line)
+}
 
-  return stripTags(withPlainLinks)
-    .replace(/[ \t]+$/gm, '')
-    .replace(/\n{3,}/g, '\n\n')
-    .trim()
+/** A fenced-code OPEN line — either a literal ``` fence or a masked block. */
+function isFenceOpenLine(line: string, placeholder?: string): boolean {
+  const t = line.trimStart()
+  if (placeholder != null && placeholder.length > 0 && t.startsWith(placeholder)) return true
+  return t.startsWith('```')
 }
 
-// ---------------------------------------------------------------------------
-// Output sanitizer — enforces fleet-wide Telegram formatting invariants
-// ---------------------------------------------------------------------------
+/** A blockquote line. */
+function isBlockquoteLine(line: string): boolean {
+  return line.trimStart().startsWith('>')
+}
+
+/** An ATX heading line. */
+function isHeadingLine(line: string): boolean {
+  return /^#{1,6}\s/.test(line.trimStart())
+}
 
 /**
- * Normalize outbound Telegram HTML text against well-known invariants.
- *
- * Runs AFTER markdownToHtml, just before the text is sent to the Bot API.
- * Conservative by design: only rewrites things that are universally wrong;
- * leaves semantic decisions (where to bold, link choice, list-vs-prose) to
- * the agent.
+ * Insert a blank line at block boundaries that are currently separated by
+ * exactly one `\n`. Operates line-by-line on already-code-masked text.
  *
- * Rules applied (in order):
- *  1. Strip markdown heading markers (`## Foo` → `<b>Foo</b>\n\n`).
- *     Headings that survived the markdown→HTML pass (e.g. when the input
- *     was already HTML and passed through isLikelyTelegramHtml) would render
- *     as ugly `## Foo` plain text. Convert to bold + blank line.
- *  2. Flatten nested bullet indentation: `\n  - sub` → `\n· sub`.
- *  3. Collapse 3+ consecutive blank lines to exactly 2.
- *  4. Strip trailing whitespace on each line.
- *  5. Ensure `<` `>` `&` inside `<code>` and `<pre>` blocks are
- *     HTML-escaped (idempotent: won't double-escape existing `&amp;` etc.).
+ * A blank line is guaranteed:
+ *   - BEFORE the first row of a GFM table (a `|`-leading line that is itself a
+ *     delimiter row, OR a `|`-containing header line immediately followed by a
+ *     delimiter row) when the previous emitted line is non-blank and not part
+ *     of a table — never between a table's own header/delimiter/body rows.
+ *   - BEFORE a fenced-code open, a blockquote, or an ATX heading when the
+ *     previous line is non-blank and of a DIFFERENT block type.
+ *   - AFTER a list block: when a list-item line is followed by a non-blank
+ *     line that is NOT itself a list item and NOT an indented continuation of
+ *     the item (4+ leading spaces / a tab), so the prose breaks out of the list.
  *
- * The function is idempotent: sanitize(sanitize(x)) === sanitize(x).
- * Content inside `<code>` / `<pre>` blocks is excluded from rules 1–4.
+ * Conservative: prefers a false negative (leave glued) over corrupting a valid
+ * block. Existing blank lines (empty entries from a `\n\n` gap) are preserved
+ * and short-circuit every rule — we never double up a gap.
  */
-export function sanitizeForTelegram(text: string): string {
-  // ── Phase 1: extract <code> and <pre> blocks so rules 1-4 don't touch them.
-  //
-  // We capture the full tag with its content so we can round-trip correctly.
-  // Placeholders are non-printing control sequences that cannot appear in
-  // normal text.
-  const CODE_PH = '\x00SANCODE'
-  const PRE_PH = '\x00SANPRE'
-  const codeSegments: string[] = []
-  const preSegments: string[] = []
-
-  // Extract <pre>...</pre> blocks first (they may contain <code> inside).
-  let result = text.replace(/<pre>([\s\S]*?)<\/pre>/gi, (_m, inner: string) => {
-    const idx = preSegments.length
-    // Rule 5: escape unescaped < > & inside pre blocks.
-    preSegments.push(`<pre>${escapeUnescapedEntities(inner)}</pre>`)
-    return `${PRE_PH}${idx}\x00`
-  })
-
-  // Extract standalone <code>...</code> blocks (not nested inside <pre>).
-  result = result.replace(/<code([^>]*)>([\s\S]*?)<\/code>/gi, (_m, attrs: string, inner: string) => {
-    const idx = codeSegments.length
-    // Rule 5: escape unescaped < > & inside code spans.
-    codeSegments.push(`<code${attrs}>${escapeUnescapedEntities(inner)}</code>`)
-    return `${CODE_PH}${idx}\x00`
-  })
-
-  // ── Phase 2: apply text-level rules to the remaining (non-code) content.
-
-  // Rule 1: strip markdown heading markers that survived markdown→HTML pass.
-  // Matches lines starting with one or more `#` followed by a space.
-  // Preserves the heading text as bold + trailing blank line.
-  result = result.replace(/^(#{1,6}) +(.+?)\s*$/gm, (_m, _hashes, title: string) => {
-    return `<b>${title}</b>\n`
-  })
-
-  // Rule 2: flatten nested bullet indentation.
-  // Matches lines with a tab OR 2+ spaces at the start followed by - or *.
-  // A single tab is treated as sufficient indentation (standard 4-space equiv).
-  // Converts to a middle-dot bullet so the sub-detail survives as readable text.
-  result = result.replace(/^(?:\t+[ \t]*|[ \t]{2,})[*-] /gm, '· ')
-
-  // Rule 4: strip trailing whitespace on each line.
-  result = result.replace(/[ \t]+$/gm, '')
-
-  // Rule 3: collapse 3+ consecutive blank lines to exactly 2.
-  // A "blank line" is a line that contains only optional whitespace (already
-  // stripped above, but let's be safe).
-  result = result.replace(/(\n[ \t]*){3,}/g, '\n\n')
-
-  // ── Phase 3: restore placeholders.
-  result = result.replace(new RegExp(`${CODE_PH}(\\d+)\x00`, 'g'), (_m, idx) => codeSegments[Number(idx)])
-  result = result.replace(new RegExp(`${PRE_PH}(\\d+)\x00`, 'g'), (_m, idx) => preSegments[Number(idx)])
-
-  return result
+function ensureBlockBoundaries(text: string, placeholder?: string): string {
+  if (!text.includes('\n')) return text
+  const lines = text.split('\n')
+  const result: string[] = []
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const prev = result.length > 0 ? result[result.length - 1] : null
+    const prevNonBlank = prev != null && prev.trim() !== ''
+    const curBlank = line.trim() === ''
+
+    // ---- Rule A: blank line BEFORE a block that needs one to start ----
+    if (prevNonBlank && !curBlank) {
+      const next = i + 1 < lines.length ? lines[i + 1] : ''
+
+      // Table first row: either THIS line is a delimiter row (header was the
+      // prev line — but only treat as a table start when prev itself isn't
+      // already a table row), or THIS line is a `|`-bearing header whose NEXT
+      // line is a delimiter. We anchor the blank-line insertion on the HEADER
+      // line so header+delimiter+body stay contiguous.
+      const prevIsTable = isTableRowLine(prev)
+      const startsTableHere =
+        !prevIsTable &&
+        ((line.includes('|') && isTableDelimiterLine(next)) ||
+          (isTableRowLine(line) && isTableDelimiterLine(next)))
+
+      const startsFence = isFenceOpenLine(line, placeholder) && !isFenceOpenLine(prev, placeholder)
+      const startsQuote = isBlockquoteLine(line) && !isBlockquoteLine(prev)
+      const startsHeading = isHeadingLine(line) && !isHeadingLine(prev)
+
+      if (startsTableHere || startsFence || startsQuote || startsHeading) {
+        result.push('')
+      }
+    }
+
+    // ---- Rule B: blank line AFTER a list block, before breakout prose ----
+    if (prevNonBlank && !curBlank && isListItemLine(prev) && !isListItemLine(line)) {
+      // A 4+ space (or tab) indent means `line` is a lazy continuation of the
+      // list item's paragraph, NOT breakout prose — leave it glued.
+      const isIndentedContinuation = /^(\t| {4,})\S/.test(line)
+      // A table/fence/quote/heading start is already handled by Rule A above
+      // (its blank line was just inserted); avoid inserting a second one.
+      const alreadySeparated = result.length > 0 && result[result.length - 1].trim() === ''
+      if (!isIndentedContinuation && !alreadySeparated) {
+        result.push('')
+      }
+    }
+
+    result.push(line)
+  }
+
+  return result.join('\n')
+}
+
+/** Lines that introduce GFM block structure — never reflow around these. */
+function isMarkerLine(line: string, placeholder?: string): boolean {
+  // CommonMark indented code block: 4+ leading spaces then a non-space char.
+  // Checked on the RAW (pre-trim) line — trimming would erase the very indent
+  // that makes it a code block, so we must look before `trimStart()`.
+  if (/^ {4,}\S/.test(line)) return true
+  const t = line.trimStart()
+  // A line that begins with the code-mask placeholder is a standalone masked
+  // fenced block — treat it as a block marker so we never inject a hard break
+  // immediately before/after a code block. (An INLINE code span sits mid-line,
+  // so the line won't START with the placeholder and ordinary prose rules apply.)
+  if (placeholder != null && placeholder.length > 0 && t.startsWith(placeholder)) return true
+  return (
+    // Unordered list bullet: -, *, + followed by a space.
+    /^[-*+]\s/.test(t) ||
+    // Ordered list: `1.` or `1)` followed by a space.
+    /^\d+[.)]\s/.test(t) ||
+    // Blockquote / pull-quote.
+    t.startsWith('>') ||
+    // ATX heading.
+    /^#{1,6}\s/.test(t) ||
+    // Table row (leading pipe) or table-ish line (interior ` | `).
+    t.startsWith('|') ||
+    line.includes(' | ') ||
+    // Fenced code delimiter (defensive — fences are masked, but a lone/odd
+    // fence line can survive masking).
+    t.startsWith('```') ||
+    // Thematic break / divider.
+    /^(-{3,}|\*{3,}|_{3,})\s*$/.test(t)
+  )
 }
 
 /**
- * Escape `<`, `>`, and `&` characters that are NOT already part of an HTML
- * entity or tag. Used inside `<code>` and `<pre>` content to correct
- * unescaped characters without double-escaping existing `&amp;`, `&lt;`, etc.
- *
- * Strategy: we walk the string and escape `&` only when it is not the start
- * of a valid entity (`&name;` or `&#digits;` or `&#xhex;`). We always escape
- * bare `<` and `>` because they cannot appear literally inside code content
- * that is correct Telegram HTML.
+ * Decide whether the lone `\n` between `prev` and `next` is a genuine prose
+ * paragraph break worth promoting to a GFM hard break. Conservative by design
+ * (see normalizeParagraphBreaks doc) — returns false on any doubt.
  */
-function escapeUnescapedEntities(inner: string): string {
-  // Escape bare & first: replace & that is NOT followed by a valid entity
-  // pattern. A valid entity is: &[a-zA-Z][a-zA-Z0-9]*; or &#[0-9]+; or &#x[0-9a-fA-F]+;
-  let out = inner.replace(/&(?!(?:[a-zA-Z][a-zA-Z0-9]*|#[0-9]+|#x[0-9a-fA-F]+);)/g, '&amp;')
-  // Escape bare < and > (they should never appear literally in code content)
-  out = out.replace(/</g, '&lt;')
-  out = out.replace(/>/g, '&gt;')
-  return out
+function shouldPromoteBreak(prev: string, next: string, placeholder?: string): boolean {
+  if (isMarkerLine(prev, placeholder) || isMarkerLine(next, placeholder)) return false
+  // Next line must begin with ordinary prose, not a structural marker char.
+  const nextTrimmed = next.trimStart()
+  if (nextTrimmed.length === 0) return false
+  // The preceding line must read as a finished sentence/clause: it ends in a
+  // sentence-terminal punctuation mark, optionally wrapped by a closing quote
+  // or paren that itself follows such a terminator.
+  const prevTrimmed = prev.trimEnd()
+  // Strip up to one trailing closing-bracket/quote run to look at the real
+  // terminator (e.g. `He said "go."` or `(done.)`).
+  const unwrapped = prevTrimmed.replace(/[)"'’”\]]+$/, '')
+  const terminator = unwrapped.slice(-1)
+  return terminator === '.' || terminator === '!' || terminator === '?' || terminator === ':'
 }
 
 /**
- * Repair LLM-side JSON escape bungles.
- *
- * Some MCP clients (and some LLM tool-call generators) occasionally emit a
- * tool-argument string whose whitespace has been double-escaped — real
- * newlines become the two-character sequence `\n`, tabs become `\t`, etc.
- * The message then ships to Telegram intact and the user sees literal
- * `\n\n` in the chat instead of paragraph breaks.
- *
- * Unescape literal `\n`, `\r`, `\t`, and `\"` sequences everywhere EXCEPT
- * inside code spans (inline backtick spans and fenced ``` blocks). Those
- * regions are masked with placeholders before the unescape pass so that a
- * literal `\n` a user typed inside a shell snippet or regex is preserved
- * verbatim. The genuine escaped-backslash sequence `\\n` (which the user
- * intended as a literal backslash + n, not a newline) is handled by
- * protecting `\\` before touching `\n`.
+ * Last-resort hard slicer for a body that `splitMarkdownChunks` could not break
+ * (a single indivisible region larger than the cap — e.g. a giant fenced block
+ * with no interior boundary). Cuts on raw character count so every emitted
+ * piece is guaranteed `<= cap`, accepting that a cut MAY land inside a fence
+ * (which Telegram renders imperfectly) — a degraded-but-delivered message beats
+ * a hard `RICH_MESSAGE_TEXT_TOO_LONG` reject that drops the answer entirely.
  *
- * This deliberately fires even when the message contains real newlines —
- * the old whole-message heuristic ("bail if any real newline exists") was
- * too broad and prevented repair of mixed messages that had both real
- * newlines and stray literal `\n` escape sequences outside code spans.
+ * Returns the input as a single-element array when it already fits.
  */
-export function repairEscapedWhitespace(text: string): string {
-  if (!/\\[nrt"\\]/.test(text)) return text
-
-  // Per-call random nonce prevents sentinel collision: if user text happens to
-  // contain our placeholder bytes, the restore step would look up an out-of-range
-  // index and produce "undefined" in the Telegram output. A nonce that is unique
-  // per invocation makes the sentinel statistically impossible to collide with.
-  const nonce = Math.random().toString(36).slice(2)
-  const CODE_MASK_PH = `\x00RM${nonce}_`
-  const BACKSLASH_PH = `\x00BK${nonce}_`
-
-  // Mask fenced code blocks (``` ... ```) and inline code spans (` ... `)
-  // so the unescape pass never touches their content.
-  //
-  // Fenced blocks are extracted first. Only CLOSED fenced blocks (with a
-  // matching closing ```) are masked — an unclosed fence is left as-is so the
-  // inline-code pass below won't misparse the two leading backticks as an empty
-  // inline span and expose the block's interior.
-  //
-  // Inline code uses `[^\`\n]+` (one or more non-backtick, non-newline chars)
-  // matching the same definition that markdownToHtml uses, so the masked regions
-  // are consistent with what the downstream pipeline treats as code.
-  const codeMasks: string[] = []
-
-  const masked = text
-    // Closed fenced code blocks only (``` ... ``` with a matching closer).
-    .replace(/```[\s\S]*?```/g, (m) => {
-      const idx = codeMasks.length
-      codeMasks.push(m)
-      return `${CODE_MASK_PH}${idx}\x00`
-    })
-    // Inline code spans: at least one character between backticks, no embedded
-    // backtick or newline (matches markdownToHtml's /`([^`\n]+)`/ definition).
-    .replace(/`[^`\n]+`/g, (m) => {
-      const idx = codeMasks.length
-      codeMasks.push(m)
-      return `${CODE_MASK_PH}${idx}\x00`
-    })
-
-  // Order matters: protect existing `\\` first so `\\n` stays as a literal
-  // backslash + n and doesn't become a newline.
-  const unescaped = masked
-    .replace(/\\\\/g, BACKSLASH_PH)
-    .replace(/\\n/g, '\n')
-    .replace(/\\r/g, '\r')
-    .replace(/\\t/g, '\t')
-    .replace(/\\"/g, '"')
-    .replace(new RegExp(BACKSLASH_PH.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g'), '\\')
-
-  // Restore masked code spans verbatim.
-  const restoreRe = new RegExp(`${CODE_MASK_PH.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(\\d+)\x00`, 'g')
-  return unescaped.replace(restoreRe, (_m, idx) => codeMasks[Number(idx)] ?? _m)
+export function hardSliceToCap(text: string, cap = RICH_MESSAGE_MAX_CHARS): string[] {
+  if (cap <= 0) return [text]
+  if (text.length <= cap) return [text]
+  const out: string[] = []
+  for (let i = 0; i < text.length; i += cap) {
+    out.push(text.slice(i, i + cap))
+  }
+  return out
 }
 
 // ---------------------------------------------------------------------------
-// Smart HTML chunking — preserves open/close tag boundaries
+// Markdown-aware chunking — never bisects a code fence or a table row
 // ---------------------------------------------------------------------------
 
 /**
- * Split HTML text into chunks that fit within maxLen, preserving tag integrity.
- * At split boundaries, open tags are closed and reopened in the next chunk.
- * Prefers splitting at \n\n, then \n, then spaces.
+ * Split a markdown body into chunks that each fit within `maxLen`.
+ *
+ * The rich-message path is raw GFM markdown, so chunk boundaries must not
+ * land inside a fenced code block (``` … ```) or in the middle of a table
+ * row — either produces a chunk Telegram renders wrong (an unterminated
+ * fence swallows the next chunk's text, a half table row drops cells).
+ *
+ * Strategy:
+ *   1. If the whole body fits, return it as one chunk.
+ *   2. Otherwise pick the largest safe cut <= maxLen, preferring a blank
+ *      line, then a single newline, then a space. The cut is then nudged
+ *      so it never falls inside an open fenced block or inside a line that
+ *      is part of a table (a line containing `|`).
+ *   3. An unsplittable region (a single code fence longer than maxLen) is
+ *      emitted whole rather than spun on forever — Telegram will reject an
+ *      oversized message, which is a louder, debuggable failure than an
+ *      infinite loop.
  */
-export function splitHtmlChunks(html: string, maxLen = 4000): string[] {
-  if (html.length <= maxLen) return [html]
+export function splitMarkdownChunks(text: string, maxLen = RICH_MESSAGE_MAX_CHARS): string[] {
+  if (text.length <= maxLen) return [text]
 
   const chunks: string[] = []
-  let rest = html
+  let rest = text
 
   while (rest.length > 0) {
     if (rest.length <= maxLen) {
@@ -651,7 +469,6 @@ export function splitHtmlChunks(html: string, maxLen = 4000): string[] {
       break
     }
 
-    // Find a good split point
     let cut = maxLen
     const paraIdx = rest.lastIndexOf('\n\n', maxLen)
     const lineIdx = rest.lastIndexOf('\n', maxLen)
@@ -665,129 +482,59 @@ export function splitHtmlChunks(html: string, maxLen = 4000): string[] {
       cut = spaceIdx
     }
 
-    // Defense-in-depth: refuse to split inside an HTML entity (&amp;,
-    // &lt;, &#x1f4a9;). If the cut would land mid-entity, back up to
-    // before the `&`. Telegram rejects messages with broken entities.
-    cut = backOffEntity(rest, cut)
-    // Same idea for a bisected tag: if the cut lands inside `<...>` (or
-    // between `<` and its closing `>`), back up to before the `<`.
-    // Otherwise we'd emit a chunk ending in `<a` or `<a href="..` which
-    // Telegram rejects outright.
-    cut = backOffOpenTag(rest, cut)
-    // Pathological: the tag-back-off retreated to 0 because `rest`
-    // begins with a tag and the nearest space we picked landed inside
-    // that tag. Fall back to the hard maxLen cut — that position lives
-    // in content past the opening tag (since the tag itself is at the
-    // start) so it won't bisect anything, and we make forward progress.
+    // Back off so the cut doesn't fall inside an open ``` fence.
+    cut = backOffOpenFence(rest, cut)
+    // Back off so the cut doesn't bisect a table row (a line with `|`).
+    cut = backOffTableRow(rest, cut)
+
     if (cut <= 0) {
-      cut = Math.min(maxLen, rest.length)
-      cut = backOffOpenTag(rest, cut)
-      // If even the maxLen cut bisects a tag, emit the whole remainder
-      // as one chunk rather than spin forever. Telegram will reject
-      // a 4k+ message before it rejects a split one, but this only
-      // fires on genuinely malformed input.
-      if (cut <= 0) cut = rest.length
+      // Could not find a safe boundary below maxLen — the region is one
+      // indivisible block (e.g. a single huge fenced block). Emit the
+      // whole remainder rather than loop forever.
+      chunks.push(rest)
+      break
     }
 
-    let segment = rest.slice(0, cut)
+    chunks.push(rest.slice(0, cut))
     rest = rest.slice(cut).replace(/^\n+/, '')
-
-    // Track open tags in this segment — we keep the FULL opening tag
-    // string (including attributes) so we can reopen `<a href="...">`
-    // in the next chunk without dropping the href.
-    const openTags = getOpenTags(segment)
-
-    // Close any open tags at the end of this chunk (by tag name)
-    for (let i = openTags.length - 1; i >= 0; i--) {
-      segment += `</${openTags[i].name}>`
-    }
-    chunks.push(segment)
-
-    // Reopen tags at the start of the next chunk, preserving attrs
-    if (rest.length > 0 && openTags.length > 0) {
-      const reopenPrefix = openTags.map(t => t.openTag).join('')
-      rest = reopenPrefix + rest
-    }
   }
 
   return chunks
 }
 
 /**
- * If `cut` lies inside an HTML entity (a `&...;` sequence), back it up to
- * just before the `&` so the chunk boundary doesn't bisect the entity.
+ * Count fenced-code delimiters (``` at line start) up to `cut`. If the
+ * count is odd, the cut lands inside an open fence — retreat to just before
+ * the opening fence so the boundary sits between complete blocks.
  */
-function backOffEntity(text: string, cut: number): number {
+function backOffOpenFence(text: string, cut: number): number {
   if (cut <= 0 || cut >= text.length) return cut
-  // Look backward up to 10 chars for an unterminated entity
-  const lookback = Math.max(0, cut - 10)
-  for (let i = cut - 1; i >= lookback; i--) {
-    const ch = text[i]
-    if (ch === ';') return cut // entity already closed before cut → safe
-    if (ch === '&') {
-      const closeIdx = text.indexOf(';', cut)
-      if (closeIdx !== -1 && closeIdx - i <= 10) {
-        // The entity spans the cut — back up to just before the `&`
-        return i
-      }
-      return cut
-    }
+  const before = text.slice(0, cut)
+  const fences = before.match(/^```/gm)
+  if (fences == null || fences.length % 2 === 0) return cut
+  // Odd number of fences → inside an open block. Find the opening fence and
+  // cut just before it (so the whole fenced block goes to the next chunk).
+  const lastFence = before.lastIndexOf('\n```')
+  if (lastFence <= 0) {
+    // Fence opens at the very start of `before` — can't retreat past it.
+    return 0
   }
-  return cut
+  return lastFence
 }
 
 /**
- * If `cut` lands inside an HTML tag (between `<` and the next `>`), back
- * up to before the `<`. Telegram rejects messages that contain a stray
- * `<` without a matching `>` (e.g. chunk ending `<a href="..`).
+ * If the cut lands on a line that contains a `|` (a markdown table row),
+ * retreat to the start of that line so we never emit a half table row.
  */
-function backOffOpenTag(text: string, cut: number): number {
+function backOffTableRow(text: string, cut: number): number {
   if (cut <= 0 || cut >= text.length) return cut
-  // Scan backward for the nearest `<` or `>` before the cut. If we hit
-  // `>` first the cut is outside any tag → safe. If we hit `<` first,
-  // check whether its closing `>` lies at or after the cut → bisected.
-  for (let i = cut - 1; i >= 0; i--) {
-    const ch = text[i]
-    if (ch === '>') return cut
-    if (ch === '<') {
-      const closeIdx = text.indexOf('>', i)
-      if (closeIdx >= cut) return i
-      return cut
-    }
+  const lineStart = text.lastIndexOf('\n', cut - 1) + 1
+  const nextNl = text.indexOf('\n', cut)
+  const lineEnd = nextNl === -1 ? text.length : nextNl
+  const line = text.slice(lineStart, lineEnd)
+  if (line.includes('|')) {
+    // Cut at the line start so the whole row moves to the next chunk.
+    return lineStart > 0 ? lineStart - 1 : 0
   }
   return cut
 }
-
-/** A tag still open at the end of a fragment. */
-interface OpenTag {
-  name: string       // lowercase tag name, e.g. "a", "tg-spoiler"
-  openTag: string    // full opening string with attrs, e.g. `<a href="...">`
-}
-
-/** Parse an HTML fragment and return the list of tags still open at the end. */
-function getOpenTags(html: string): OpenTag[] {
-  const tagStack: OpenTag[] = []
-  // Allow hyphens in tag names so `tg-spoiler` and `tg-emoji` parse as a
-  // single tag rather than `tg` plus stray text.
-  const tagRe = /<(\/?)([a-z][a-z0-9-]*)\b[^>]*>/gi
-  let m: RegExpExecArray | null
-  while ((m = tagRe.exec(html)) !== null) {
-    const full = m[0]
-    const isClosing = m[1] === '/'
-    const tagName = m[2].toLowerCase()
-    if (isClosing) {
-      // Closing tag — pop the most recent matching entry off the stack
-      for (let i = tagStack.length - 1; i >= 0; i--) {
-        if (tagStack[i].name === tagName) {
-          tagStack.splice(i, 1)
-          break
-        }
-      }
-    } else if (!full.endsWith('/>')) {
-      // Opening tag (not self-closing) — remember the full open string
-      // so reopen in the next chunk preserves attributes.
-      tagStack.push({ name: tagName, openTag: full })
-    }
-  }
-  return tagStack
-}