@s0nderlabs/anima-plugin-telegram 0.19.11 → 0.19.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s0nderlabs/anima-plugin-telegram",
-  "version": "0.19.11",
+  "version": "0.19.13",
   "type": "module",
   "description": "Telegram gateway plugin for anima — long-poll bot, debounced dispatch, reactions, allowlist",
   "license": "MIT",
@@ -28,7 +28,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@s0nderlabs/anima-core": "0.19.11",
+    "@s0nderlabs/anima-core": "0.19.13",
     "grammy": "^1.42.0",
     "zod": "^3.23.8"
   }

package/src/index.ts

@@ -48,7 +48,12 @@ export {
   type ParsedCallback,
   type ResolveOutcome,
 } from './approval-keyboard'
-export { escapeMarkdownV2, isMarkdownParseError, stripMarkdownV2 } from './markdown'
+export {
+  escapeMarkdownV2,
+  formatMarkdownV2,
+  isMarkdownParseError,
+  stripMarkdownV2,
+} from './markdown'
 export { escapeChunkSuffixForMarkdownV2, splitMessage, type SplitOpts } from './chunking'
 export type { TelegramApprovalBridge, ApprovalChoiceKind } from './types'
 export { DebounceBuffer } from './debounce'

package/src/listener.ts

@@ -4,7 +4,7 @@ import { escapeChunkSuffixForMarkdownV2, splitMessage } from './chunking'
 import { DebounceBuffer, type FlushedBatch } from './debounce'
 import { formatTelegramChannel } from './format'
 import { RateLimiter } from './limits'
-import { escapeMarkdownV2, isMarkdownParseError, stripMarkdownV2 } from './markdown'
+import { formatMarkdownV2, isMarkdownParseError, stripMarkdownV2 } from './markdown'
 import { formatPairingMessage } from './pairing-flow'
 import { reactError, reactProcessing, reactSuccess } from './reactions'
 import {
@@ -368,7 +368,7 @@ export class TelegramListener {
     const chunks = splitMessage(body)
     let firstSend = true
     for (const chunk of chunks) {
-      const md = escapeChunkSuffixForMarkdownV2(escapeMarkdownV2(chunk))
+      const md = escapeChunkSuffixForMarkdownV2(formatMarkdownV2(chunk))
       try {
         await sendWithRetry(() =>
           this.bot.api.sendMessage(chatId, md, {

package/src/markdown.test.ts

@@ -1,5 +1,10 @@
 import { describe, expect, it } from 'bun:test'
-import { escapeMarkdownV2, isMarkdownParseError, stripMarkdownV2 } from './markdown'
+import {
+  escapeMarkdownV2,
+  formatMarkdownV2,
+  isMarkdownParseError,
+  stripMarkdownV2,
+} from './markdown'
 
 describe('escapeMarkdownV2', () => {
   it('escapes all reserved characters', () => {
@@ -48,6 +53,98 @@ describe('stripMarkdownV2', () => {
   })
 })
 
+describe('formatMarkdownV2', () => {
+  it('passes through plain text but escapes reserved chars', () => {
+    expect(formatMarkdownV2('your balance is 0.0819 0G.')).toBe('your balance is 0\\.0819 0G\\.')
+  })
+
+  it('translates **bold** into MarkdownV2 *bold*', () => {
+    expect(formatMarkdownV2('**balance**: 0.08 0G')).toBe('*balance*: 0\\.08 0G')
+  })
+
+  it('translates *italic* into MarkdownV2 _italic_', () => {
+    expect(formatMarkdownV2('see *details* below.')).toBe('see _details_ below\\.')
+  })
+
+  it('keeps ** bold-with-inner-text translated', () => {
+    expect(formatMarkdownV2('**Your balance**: 0.0819 0G')).toBe('*Your balance*: 0\\.0819 0G')
+  })
+
+  it('translates headers into bold', () => {
+    expect(formatMarkdownV2('# Title\nbody.')).toBe('*Title*\nbody\\.')
+    expect(formatMarkdownV2('## Sub Title\nmore.')).toBe('*Sub Title*\nmore\\.')
+  })
+
+  it('strips redundant bold markers inside headers', () => {
+    expect(formatMarkdownV2('# **Hello**')).toBe('*Hello*')
+  })
+
+  it('preserves inline code, escaping only backslashes inside', () => {
+    expect(formatMarkdownV2('use `0.5 0G` as the threshold')).toBe('use `0.5 0G` as the threshold')
+  })
+
+  it('preserves fenced code blocks, escaping backticks and backslashes inside', () => {
+    expect(formatMarkdownV2('```\nfoo()\nbar\n```')).toBe('```\nfoo()\nbar\n```')
+  })
+
+  it('preserves fenced code blocks with language hint', () => {
+    expect(formatMarkdownV2('```js\nconst x = 1;\n```')).toBe('```js\nconst x = 1;\n```')
+  })
+
+  it('escapes backslashes inside fenced code', () => {
+    expect(formatMarkdownV2('```\npath\\to\nfile\n```')).toBe('```\npath\\\\to\nfile\n```')
+  })
+
+  it('translates links with escaped display + URL', () => {
+    expect(formatMarkdownV2('[example](https://example.com/path)')).toBe(
+      '[example](https://example.com/path)',
+    )
+  })
+
+  it('escapes display text but not URL parens-friendly chars', () => {
+    expect(formatMarkdownV2('see [the docs](https://example.com)')).toBe(
+      'see [the docs](https://example.com)',
+    )
+  })
+
+  it('translates ~~strike~~ into MarkdownV2 ~strike~', () => {
+    expect(formatMarkdownV2('~~done~~')).toBe('~done~')
+  })
+
+  it('preserves ||spoiler||', () => {
+    expect(formatMarkdownV2('||hidden||')).toBe('||hidden||')
+  })
+
+  it('preserves blockquote markers', () => {
+    expect(formatMarkdownV2('> a quote here.')).toBe('> a quote here\\.')
+  })
+
+  it('escapes stray parens and braces in plain text', () => {
+    expect(formatMarkdownV2('foo (bar) baz')).toBe('foo \\(bar\\) baz')
+    expect(formatMarkdownV2('use {x} for substitution')).toBe('use \\{x\\} for substitution')
+  })
+
+  it('does not escape parens that belong to a translated link', () => {
+    expect(formatMarkdownV2('see [docs](https://example.com/foo)')).toBe(
+      'see [docs](https://example.com/foo)',
+    )
+  })
+
+  it('handles real brain reply with mixed formatting', () => {
+    const input = 'Your balance: **0.0819 0G**. Wallet `0xd56b...9683`.'
+    const expected = 'Your balance: *0\\.0819 0G*\\. Wallet `0xd56b...9683`\\.'
+    expect(formatMarkdownV2(input)).toBe(expected)
+  })
+
+  it('handles empty input', () => {
+    expect(formatMarkdownV2('')).toBe('')
+  })
+
+  it('escapes backslashes inside inline code', () => {
+    expect(formatMarkdownV2('see `a\\b` for the regex')).toBe('see `a\\\\b` for the regex')
+  })
+})
+
 describe('isMarkdownParseError', () => {
   it('matches the canonical TG parse error string', () => {
     expect(isMarkdownParseError(new Error("Bad Request: can't parse entities: ..."))).toBe(true)

package/src/markdown.ts

@@ -1,10 +1,19 @@
-// MarkdownV2 escape + plain-text fallback.
+// MarkdownV2 escape + plain-text fallback + standard-markdown translator.
 //
-// Pattern from hermes telegram.py:84. The Bot API requires every reserved
-// character in MarkdownV2 entity ranges to be escaped with backslash, even
-// inside code blocks for some characters. This module exposes a single
-// `escapeMarkdownV2` function for the safe path and `stripMarkdownV2` for
-// the plain-text fallback when parse_error fires on send.
+// The brain emits standard CommonMark (`**bold**`, `*italic*`, `` `code` ``,
+// `# heading`, `[text](url)`, lists, blockquotes). Telegram MarkdownV2 has
+// different syntax AND requires every reserved character outside formatting
+// markers to be backslash-escaped. Sending the brain's text directly with
+// `parse_mode: 'MarkdownV2'` either parse-errors or renders escape characters
+// literally.
+//
+// `formatMarkdownV2(text)` is the canonical translator: protect code blocks
+// and links behind placeholders, convert markdown structures to MarkdownV2
+// equivalents, escape remaining reserved chars, restore placeholders. Ported
+// from hermes telegram.py:format_message.
+//
+// `escapeMarkdownV2(text)` and `stripMarkdownV2(text)` remain available for
+// callers that need raw escaping or a plain-text fallback when send fails.
 
 const MARKDOWN_V2_ESCAPE_REGEX = /([_*[\]()~`>#+\-=|{}.!\\])/g
 
@@ -21,15 +30,10 @@ export function escapeMarkdownV2(text: string): string {
  */
 export function stripMarkdownV2(text: string): string {
   let out = text
-  // Drop escape backslashes that were applied by escapeMarkdownV2
   out = out.replace(/\\([_*[\]()~`>#+\-=|{}.!\\])/g, '$1')
-  // Strip ||spoiler|| (must run before * and _ since `||` shares chars)
   out = out.replace(/\|\|([^|]+)\|\|/g, '$1')
-  // Strip *bold* (greedy-safe since markdown only allows single-line *bold*)
   out = out.replace(/\*([^*]+)\*/g, '$1')
-  // Strip _italic_
   out = out.replace(/(?:^|[\s])_([^_]+)_(?=[\s]|$)/g, ' $1')
-  // Strip ~strike~
   out = out.replace(/~([^~]+)~/g, '$1')
   return out
 }
@@ -48,3 +52,111 @@ export function isMarkdownParseError(err: unknown): boolean {
     (lower.includes('bad request') && (lower.includes('parse') || lower.includes('entities')))
   )
 }
+
+/**
+ * Translate standard CommonMark (what the brain emits) into Telegram MarkdownV2.
+ * Ports hermes `format_message` (telegram.py:1838-1993). Strategy: stash code
+ * spans and links behind NUL-bracketed placeholders, rewrite formatting
+ * markers, then escape every reserved char in the remaining plain text and
+ * restore placeholders. The trailing safety pass catches stray `( ) { }` that
+ * survived the dance, while leaving link parens intact.
+ */
+export function formatMarkdownV2(content: string): string {
+  if (!content) return content
+
+  const placeholders: string[] = []
+  const ph = (value: string): string => {
+    const key = `\x00PH${placeholders.length}\x00`
+    placeholders.push(value)
+    return key
+  }
+
+  let text = content
+
+  text = text.replace(/```(?:[^\n]*\n)?[\s\S]*?```/g, raw => {
+    const newlineIdx = raw.indexOf('\n', 3)
+    const headerEnd = newlineIdx === -1 ? 3 : newlineIdx + 1
+    const header = raw.slice(0, headerEnd)
+    const body = raw.slice(headerEnd, raw.length - 3)
+    const escaped = body.replace(/\\/g, '\\\\').replace(/`/g, '\\`')
+    return ph(`${header}${escaped}\`\`\``)
+  })
+
+  text = text.replace(/`[^`\n]+`/g, raw => ph(raw.replace(/\\/g, '\\\\')))
+
+  text = text.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_match, display: string, url: string) => {
+    const safeDisplay = escapeMarkdownV2(display)
+    const safeUrl = url.replace(/\\/g, '\\\\').replace(/\)/g, '\\)')
+    return ph(`[${safeDisplay}](${safeUrl})`)
+  })
+
+  text = text.replace(/^(#{1,6})\s+(.+)$/gm, (_match, _hashes, inner: string) => {
+    const cleaned = inner.trim().replace(/\*\*(.+?)\*\*/g, '$1')
+    return ph(`*${escapeMarkdownV2(cleaned)}*`)
+  })
+
+  text = text.replace(/\*\*(.+?)\*\*/g, (_match, inner: string) =>
+    ph(`*${escapeMarkdownV2(inner)}*`),
+  )
+
+  text = text.replace(/\*([^*\n]+)\*/g, (_match, inner: string) =>
+    ph(`_${escapeMarkdownV2(inner)}_`),
+  )
+
+  text = text.replace(/~~(.+?)~~/g, (_match, inner: string) => ph(`~${escapeMarkdownV2(inner)}~`))
+
+  text = text.replace(/\|\|(.+?)\|\|/g, (_match, inner: string) =>
+    ph(`||${escapeMarkdownV2(inner)}||`),
+  )
+
+  text = text.replace(/^(>{1,3}) (.+)$/gm, (_match, marker: string, body: string) =>
+    ph(`${marker} ${escapeMarkdownV2(body)}`),
+  )
+
+  text = escapeMarkdownV2(text)
+
+  for (let i = placeholders.length - 1; i >= 0; i--) {
+    const value = placeholders[i] ?? ''
+    text = text.replace(`\x00PH${i}\x00`, value)
+  }
+
+  text = escapeStrayParens(text)
+
+  return text
+}
+
+/**
+ * Last-ditch pass over `( ) { }` that survived the placeholder dance. Runs
+ * outside code spans only — anything inside `` `…` `` or ``` ```…``` ``` is
+ * preserved verbatim. Mirrors hermes safety net at telegram.py:1957-1991.
+ */
+function escapeStrayParens(text: string): string {
+  const segments = text.split(/(```[\s\S]*?```|`[^`]+`)/g)
+  return segments
+    .map((seg, idx) => {
+      if (idx % 2 === 1) return seg
+      return seg.replace(/[(){}]/g, (ch, offset: number) => {
+        if (offset > 0 && seg[offset - 1] === '\\') return ch
+        if (ch === '(' && offset > 0 && seg[offset - 1] === ']') return ch
+        if (ch === ')' && isInsideLinkUrl(seg, offset)) return ch
+        return `\\${ch}`
+      })
+    })
+    .join('')
+}
+
+function isInsideLinkUrl(seg: string, closeIdx: number): boolean {
+  let depth = 0
+  for (let j = closeIdx - 1; j >= Math.max(closeIdx - 2000, 0); j--) {
+    const ch = seg[j]
+    if (ch === ')') {
+      depth += 1
+      continue
+    }
+    if (ch !== '(') continue
+    depth -= 1
+    if (depth >= 0) continue
+    return j > 0 && seg[j - 1] === ']'
+  }
+  return false
+}