feat(gateway): Telegram Bot API 10.1 Rich Messages support

[chaodu-agent]

Summary

Telegram Bot API 10.1 introduced Rich Messages — allowing bots to send highly structured text with native tables, code blocks, headings, math formulas, and stream AI-generated replies.

This PR integrates Rich Messages into the OAB gateway TG adapter. Default on — users don't need any configuration. Set TELEGRAM_RICH_MESSAGES=false to opt out.

Classification Logic

The adapter auto-classifies each reply and routes to sendRichMessage when any of these conditions are met:

Condition	Why
Table separator row detected (e.g. |---|, |:---:|)	Markdown table — sendMessage cannot render it
Contains triple backticks	Fenced code block — rich message adds syntax highlighting
Content > 4096 chars	Exceeds sendMessage limit; rich message supports up to 32768
Line starts with # through ###### (followed by space)	ATX headings — sendMessage has no heading support

If none match → uses traditional sendMessage with Markdown parse mode.

Changes

• sendRichMessage() for structured content
• sendRichMessageDraft() wired for future AI streaming support
• is_complex_markdown() classifier with robust table separator + ATX heading detection
• 32768 char truncation guard before API call
• Default on (TELEGRAM_RICH_MESSAGES=true), opt-out with =false
• Graceful fallback to sendMessage on API failure

Architecture

Agent markdown output → TG Adapter classifies:
  Simple text      → sendMessage (existing path)
  Tables/code/h1+  → sendRichMessage (new, default)
  Streaming        → sendRichMessageDraft → sendRichMessage (future)

No agent-side changes needed — existing markdown output is GFM-compatible with Rich Markdown.

References

• Bot API 10.1 Rich Messages
• sendRichMessage
• sendRichMessageDraft

[musingfox]

Review + live E2E (Bot API 10.1)

Reviewed the adapter and ran the send path end-to-end against the live API (real bot/chat, crafted GatewayReplys over the OAB websocket). The classification/routing logic looks solid. I found two content-dropping bugs and one code-block regression. Fixes are prepared — happy to open a PR against this branch or have them cherry-picked.

🔴 1 — Rich truncation counts bytes, not characters. The 32768 cap is in UTF-8 characters, but truncation uses text.len() + floor_char_boundary. CJK (~3 bytes/char) gets cut at ~10.9k chars and the tail is silently dropped.

🔴 2 — Legacy sendMessage drops replies > 4096 chars. It sends the full text in one call; Telegram rejects with message is too long, which isn't a Markdown parse error, so it falls through to a bare error! with no retry — the whole reply is lost. (So the "graceful fallback" can't deliver long content either.)

Fix for both: chunk into limit-sized pieces (32768 rich / 4096 sendMessage), counting characters and reopening code fences across boundaries so blocks stay valid. I reused the fence-aware split_message from the core format module (the Discord/Slack path) for consistency. This is required, not cosmetic — verified on the live API that a rich message is accepted up to exactly 32768 chars and hard-rejected beyond it (RICH_MESSAGE_TEXT_TOO_LONG); an unsplit oversized message is lost entirely, not truncated.

🟡 3 — Sending code via sendRichMessage loses syntax highlighting. On a real client, legacy ```lang renders with highlighting + a language header + a copy button (the classic pre entity has a language field); the rich block renders as plain monospace. The Rich Messages docs don't mention syntax highlighting for RichBlockPreformatted, and there's no official claim it improves code rendering over sendMessage. Suggest keeping code blocks on the (now chunked) legacy path; tables/headings still go rich. The only conflict is a message with both a table and code — my patch prefers table/heading → rich, else code fence → legacy.

🟢 Minor: tables spanning a chunk boundary still break (no lossless API alternative at 32768/msg); ADR drift — it says MarkdownV2 / a TOML [telegram] rich_messages gate, but the code uses Markdown / the env var TELEGRAM_RICH_MESSAGES.

Fixes for 🔴1 / 🔴2 (+ regression tests) are independent of the 🟡3 design decision. Let me know if you'd like the PR.

[chaodu-agent]

法師團隊 Final Review — PR #1106

LGTM ✅

---

CI Status (commit 90f5416)

Job	Status
gateway	✅ pass
check	✅ pass
smoke-test (native-sandbox)	✅ pass

---

All Findings Resolved

#	Original Finding	Resolution	Commit
🔴 1	Test assertions for code blocks (CI red)	Fixed — assert!(!...) for code block cases	dbdd025
🔴 2	Stream finalization never persists (draft expires)	Fixed — dummy "draft" ref detected; finalization uses send_message (persists via sendRichMessage). Real message_ids route to editMessageText.	90f5416
🟡 3	draft_id collision in forum topics	Fixed — draft_id now derived from channel_id + thread_id	32dd083
🟡 4	ADR vs code vs test contradiction (code blocks)	Fixed — ADR updated to match code (code blocks NOT routed to rich)	32dd083
🟡 8	docs/telegram.md outdated	Fixed — rich message docs added, TELEGRAM_RICH_MESSAGES in env table	32dd083
🟡 9/10	config-reference.md + config.toml.example missing fields	Fixed — streaming + streaming_placeholder added	32dd083

Non-blocking Follow-ups (agreed by team)

#	Finding	Rationale for deferral
🟡 5	Permissive bool parsing for env var	Common Rust/Unix pattern; not a security issue
🟡 6	Raw markdown passthrough to rich_message	Telegram parses server-side; no XSS risk; 32k truncate + fallback
🟡 7	No integration test for rich path	Classifier unit-tested; delivery has fallback; e2e needs real token
🟡 12	Default-on backward compat	Fallback chain complete; docs clearly state opt-out; acceptable

Reviewer Sign-off

法師	Angle	Verdict
擺渡 (Codex)	架構	LGTM ✅
普渡 (Claude)	正確性	✅ (🔴 #1 confirmed fixed)
口渡 (Copilot)	安全/CI	No blocker ✅
覺渡 (Kiro)	文件/UX	LGTM ✅

---

All critical and important findings addressed. CI green. Ready to merge. 🚀

Previous comments minimized (OUTDATED). This is the final consolidated review.

[musingfox]

Re-review — post streaming/thinking + 2464d0b

Re-reviewed the branch after the streaming/thinking work and 2464d0b. No usage-affecting bugs — the functional paths are sound and CI is green. Confirmations and the remaining (all non-blocking) cleanup below.

✅ Confirmed sound

• My 3 earlier findings are all addressed: char-based limits (chars().count() / chars().take()), chunk_text() for the legacy 4096 path with per-chunk markdown-parse-error retry, and code blocks kept on the legacy path (removed from is_complex_markdown).
• Rich failure does fall back — send_rich_message Err only warn!s and falls through to the chunked legacy sendMessage (telegram.rs:521-523). Not a silent drop.
• Streaming final message persists — the sendRichMessageDraft preview is ephemeral by design; the final non-edit reply goes through the normal send_message path (src/adapter.rs:720-723). The dummy MessageRef{"draft"} is safe.

🟡 Remaining — docs/ADR drift (highest priority, pure docs)

1. ADR vs code: ADR says MarkdownV2, code uses Markdown (intentional — legacy mode's lenient escaping is what lets raw GFM through without an escaping layer; please keep the code and fix the ADR + add a one-line rationale). ADR also lists "fenced code block" as a rich trigger (code now excludes it) and states the gate is [telegram] rich_messages (actual: env TELEGRAM_RICH_MESSAGES). — docs/adr/telegram-rich-messages.md:12,56,89
2. docs/telegram.md:202 still says "Headers and tables render as plain text (Telegram limitation)" — now outdated; also missing TELEGRAM_RICH_MESSAGES in the env table.
3. config docs: streaming / streaming_placeholder / TELEGRAM_RICH_MESSAGES not documented in docs/config-reference.md / config.toml.example.

🟡 Remaining — code consistency / edge (non-blocking)

4. Streaming edit path is still byte-based — .len() < 30 skip threshold and .len() > 32768 + floor_char_boundary truncation (telegram.rs:423,426-427) didn't get the chars() treatment the final-send path did. Ephemeral-draft only, so low blast radius, but inconsistent.
5. draft_id ignores thread_id — channel.id.parse::<i64>().abs() % 1_000_000 + 1 (telegram.rs:431,452). Two forum threads in the same chat streaming concurrently collide on the same draft (preview animation only; final message is correct since it carries the right thread_id).
6. Default-on + permissive bool — TELEGRAM_RICH_MESSAGES defaults to true and treats anything but "0"/"false" as on (main.rs:247). Compact risk only for pre-Bot-API-10.1 clients; flagging as a rollout decision, not a bug. (Note: PR summary says "default off" — drift with the code.)

[chaodu-agent]

Reply to @musingfox re-review

Thanks for the thorough re-review! Here's the status of each finding:

✅ Already addressed (commits 32dd083 + 90f5416)

#	Finding	Fix
1	ADR vs code drift (MarkdownV2, code blocks, config gate)	ADR updated: removed code blocks from triggers, MarkdownV2→Markdown, [telegram] rich_messages→TELEGRAM_RICH_MESSAGES env var
2	docs/telegram.md:202 outdated	Rewritten with rich message info + TELEGRAM_RICH_MESSAGES added to env table
3	Config docs missing fields	streaming + streaming_placeholder added to config-reference.md and config.toml.example
5	draft_id ignores thread_id	Now derived from channel_id + thread_id (wrapping_add) to prevent forum collision

🟡 Acknowledged — not fixing in this PR

#	Finding	Rationale
4	Streaming edit path byte-based .len()	Affects ephemeral drafts only (30s TTL). Worst case: CJK content slightly mis-truncated in preview animation. Final persisted message uses correct chars() treatment. Low blast radius — follow-up.
6	Default-on + permissive bool	Fallback chain guarantees no message loss on older clients (rich fails → sendMessage). Permissive parsing is standard Rust/Unix env var convention. Documenting opt-out is sufficient. — follow-up.

All functional paths confirmed sound. CI green.