Repository navigation
feat: render markdown on a proactive telegram send when asked - #31424
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Opt-in flag, off by default. It reuses the reply renderer's existing markdown→Telegram-HTML conversion and redaction, has one real override (Telegram) and closes #18764. What this change shipsInventory (8 items) — 8 justifiedIntent: let a cron report or an agent's proactive Telegram send opt into rendered bold, italics, code and links, with plain text staying the default. ADDITION.
[FIRST-PRINCIPLES-REVIEWED] c5ba0aa Description read[DESCRIPTION-READ] d269a63e1eddb79e7bb6706ce68569f957076c2a708c6274619d2d5dfae99d1b That sha256 names the PR description this verdict read. Recompute it with |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: the formatting is opt-in, plain stays the default on every leg, and the only take-away (a 400 on an unknown Notes
[DESIGN-REVIEWED] c5ba0aa Description read[DESCRIPTION-READ] 382cc8de39b12861bee12c1367a1418dac3fe28ab2175eaa622a9a2319c26568 That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
ed6db6c to
3863af2
Compare
|
|
Backend Tests shard 2 (Linux and Windows) is red on |
3863af2 to
60fb6f8
Compare
|
60fb6f8 to
423602f
Compare
|
Backend Tests shard 7 (Linux and Windows) is red on |
423602f to
93d2177
Compare
93d2177 to
14ed498
Compare
|
A cron report or an agent's send_message reaching Telegram is plain text, so **bold**, `code` and links arrive with their markup showing. send_message and ctx.notify take an optional format, "plain" (the default, unchanged) or "markdown". With "markdown" the three channel legs send each part through a new transport verb, send_markdown, whose default is the plain send; Telegram overrides it to send Telegram HTML and falls back to the plain send when the render is too long or is refused. An unknown format is refused with 400 format_unknown. Closes #18764
14ed498 to
c5ba0aa
Compare
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Approved for the on-call. Review lanes pass on c5ba0aa, no conflict, no open change request.
Problem / Motivation
Goal: A cron report or an agent's
send_messageto Telegram can ask for markdown and arrive with bold, italics, code and links rendered, while plain text stays the default.Proactive sends to Telegram (
send_messagewithchannel_typeorsession="telegram", and a cron'sctx.notify) go out as plain text.*Title*,**41.4 kWh**,`code`and[label](url)arrive with the markup showing, and no caller can opt one message into formatting. The Bot API client already accepts aparse_mode; nothing above it could reach it.Why it matters
Scheduled digests and status reports are the main thing a Telegram operator reads from the agent. Today they either carry literal asterisks and brackets or give up emphasis, which makes the key figure in a report harder to spot.
Not a goal
format="html"or MarkdownV2. Converting markdown to escaped Telegram HTML means a caller never escapes anything and a stray.or!cannot make the Bot API reject the message.What changed (motivation → approach → change)
The rendering already exists for replies: the Telegram renderer turns markdown into Telegram HTML, redacting against the rendered form first. Proactive sends never reached it, because the transport verb they use takes no formatting at all.
send_messagetool (schema invalidation_parts/messaging_session_schemas.py),ctx.notify,POST /api/send-messageformat,"plain"(default) or"markdown"; any other value is refused with 400format_unknownchannel_delivery.py: own conversation, configured target, owner DM)"markdown", each part goes out throughsend_markdowninstead ofsend_message, after the same redaction. A long markdown send is split by the fence-awarechunk_for_transporton every leg, so a cut never lands inside a code block; the own-conversation leg's plain send keeps its fixed-width cutMessagingTransport.send_markdowninmessaging/transport.py(new, not abstract)TelegramTransport.send_markdownintelegram/transport.py_split_markdown_bounded, and each piece goes out rendered; a piece that cannot be made smaller, or one Telegram refuses (a 400), goes out plain instead, never raw tags or a cut-off tail. Any other failure (a timeout, a 5xx) reports the part as undelivered rather than sending a second, plain copy of a message that may already be in the chat;TelegramClient.send_messagegains an optionalerr_outso the transport can read the error codectx.notifyalready forwards its keyword arguments to the gateway, so it needs no code change. The messaging spec and the Telegram guide (telegram-integration.md) describe the option, including that in markdown mode a literal*or_in the text is read as markup too.Backwards compatibility
Breaking: a
POST /api/send-messagebody whoseformatis anything other than"plain","markdown", empty or null is now refused with 400, where main ignored the key. Writer sweep on origin/main @ 07ab5da: the MCPsend_messagetool could not sendformatat all (its validator rejects an undeclared field), and the route is internal-only (server_internal_paths.py), so the one writer that could carry it is a cron script'sctx.notify(..., format=...).Reader: src/kiro_crew/cron_script_context.py:ScriptContext.notify -- cron -- forwards
formatverbatim;"plain"and"markdown"deliver, any other value raisesRuntimeErrorfrom the 400 instead of being dropped;test_cron_script.py::TestScriptContextNotify::test_notify_forwards_the_formatReader: src/kiro_crew/mcp_tools/messaging.py:send_message -- chat --
formatis declared in the descriptor andSEND_MESSAGE_SCHEMAwith the same two values;test_proactive_send_markdown_format.py::test_the_tool_forwards_format_to_the_gatewayThe three leg functions gained a
markdown=Falsekeyword, so every existing call is unchanged.Tests
test_proactive_send_markdown_format.py(new):send_markdownon Telegram sends<b>…</b>/<code>…</code>withparse_mode="HTML"against an autospeccedTelegramClient; a refused (400) HTML send and a render over the cap both go out as the plain text, and an HTML send that failed without a 400 is not sent again; a part whose render outgrows the cap is split again by rendered length and every piece still goes out as HTML; on each of the three legs the route sends throughsend_markdownwithformat="markdown"and throughsend_messagewithout it;format="html"is refused before any send; the MCP tool forwardsformat; a markdown send longer than the cap with one big code block arrives on each leg as parts whose fences are all closed (red on the own-conversation leg before this head).test_cron_script.py:ctx.notify(..., format="markdown")putsformatin the posted body.test_proactive_send_source_line.py,test_mcp_messaging_discord.py: their stand-ins for the legs take the new keyword, andformatis listed with the fields that apply to every channel.test_handlers_messaging_composition_contract.py: the shape digest is re-captured; the only difference is the threemarkdownkeywords.test_client_telegram_composition_contract.py: the pinnedTelegramClient.send_messagesignature gainserr_out.Determinism: the 26 new or changed tests passed 20 runs at
-n0and 10 at-n 4 --dist loadgroup --max-worker-restart=2besidetest_proactive_send_options_text.pyandtest_channel_send_target.py, and in a shuffled order (seed 24641).Manual verification
N/A — unit coverage sufficient: the route tests drive
POST /api/send-messageend to end down to the transport verb, and the Telegram tests pin the exact Bot API call. Not run against a live bot.Screenshots / video
N/A — no frontend file changes.
Related Issues
Closes #18764
Sibling sweep
N/A — a
feat:PR.Pattern harvest
N/A — a
feat:PR.Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)