Skip to content

feat: render markdown on a proactive telegram send when asked - #31424

Merged
bolichen97 merged 1 commit into
mainfrom
fix/18764-telegram-markdown-format
Nov 7, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/18764-telegram-markdown-format

Conversation

@bolichen97

@bolichen97 bolichen97 commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A cron report or an agent's send_message to 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_message with channel_type or session="telegram", and a cron's ctx.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 a parse_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

  • Changing what an existing caller gets. Plain stays the default on every leg.
  • 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.
  • Rendering on other channels. Discord already renders markdown in a plain send; every other channel and the dashboard notification send the text as written.
  • Buttons on proactive sends (Show [OPTIONS:] buttons on proactive sends (cron, notify, owner DM) #19350).

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.

Layer Change
send_message tool (schema in validation_parts/messaging_session_schemas.py), ctx.notify, POST /api/send-message an optional format, "plain" (default) or "markdown"; any other value is refused with 400 format_unknown
the three channel legs (channel_delivery.py: own conversation, configured target, owner DM) with "markdown", each part goes out through send_markdown instead of send_message, after the same redaction. A long markdown send is split by the fence-aware chunk_for_transport on every leg, so a cut never lands inside a code block; the own-conversation leg's plain send keeps its fixed-width cut
MessagingTransport.send_markdown in messaging/transport.py (new, not abstract) the plain send, so every channel that does not override it is unchanged
TelegramTransport.send_markdown in telegram/transport.py sends the part as Telegram HTML. A part whose render is longer than Telegram's 4096-character cap (escaping and tags grow it past the source budget) is split again by rendered length with the reply renderer's own _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_message gains an optional err_out so the transport can read the error code

ctx.notify already 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-message body whose format is 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 MCP send_message tool could not send format at 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's ctx.notify(..., format=...).
Reader: src/kiro_crew/cron_script_context.py:ScriptContext.notify -- cron -- forwards format verbatim; "plain" and "markdown" deliver, any other value raises RuntimeError from the 400 instead of being dropped; test_cron_script.py::TestScriptContextNotify::test_notify_forwards_the_format
Reader: src/kiro_crew/mcp_tools/messaging.py:send_message -- chat -- format is declared in the descriptor and SEND_MESSAGE_SCHEMA with the same two values; test_proactive_send_markdown_format.py::test_the_tool_forwards_format_to_the_gateway

The three leg functions gained a markdown=False keyword, so every existing call is unchanged.

Tests

  • test_proactive_send_markdown_format.py (new): send_markdown on Telegram sends <b>…</b>/<code>…</code> with parse_mode="HTML" against an autospecced TelegramClient; 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 through send_markdown with format="markdown" and through send_message without it; format="html" is refused before any send; the MCP tool forwards format; 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") puts format in the posted body.
  • test_proactive_send_source_line.py, test_mcp_messaging_discord.py: their stand-ins for the legs take the new keyword, and format is 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 three markdown keywords. test_client_telegram_composition_contract.py: the pinned TelegramClient.send_message signature gains err_out.

Determinism: the 26 new or changed tests passed 20 runs at -n0 and 10 at -n 4 --dist loadgroup --max-worker-restart=2 beside test_proactive_send_options_text.py and test_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-message end 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

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 6, 2026 13:10
@bolichen97
bolichen97 requested a review from Zedmor November 6, 2026 13:10
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 6, 2026
@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision c5ba0aa627b58e61cf99fae048f93eb3cdc2dbc7 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of c5ba0aa627b58e61cf99fae048f93eb3cdc2dbc7 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

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 ships

Inventory (8 items) — 8 justified

Intent: 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.

  1. send_message tool, ctx.notify and POST /api/send-message accept format: "plain" (default) or "markdown" — justified
  2. A format value other than plain or markdown is refused with 400 format_unknown, where main ignored it — justified
  3. With markdown, the three channel legs send each part through send_markdown — justified
  4. Every non-Telegram channel's send_markdown falls back to the plain send, so nothing changes for them — justified
  5. Telegram sends markdown as HTML; an over-long render is re-split, and a refused one falls back to plain — justified
  6. A markdown send on the own-conversation leg is split with the fence-aware splitter — justified
  7. TelegramClient.send_message gains err_out, so a 400 can be told apart from a timeout or 5xx — justified
  8. The renderer's split helpers accept the composed redactor for grading boundaries — justified

[FIRST-PRINCIPLES-REVIEWED] c5ba0aa

Description read

[DESCRIPTION-READ] d269a63e1eddb79e7bb6706ce68569f957076c2a708c6274619d2d5dfae99d1b

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of c5ba0aa627b58e61cf99fae048f93eb3cdc2dbc7 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

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 format) lists its reader.

Notes

  • "Manual verification: N/A — Not run against a live bot" leaves one question open: does Telegram accept the HTML this renderer produces as a proactive send? The reply path already sends the same render with parse_mode="HTML", so the risk is small. One live format="markdown" cron notify would settle it.
  • In send_markdown, if a later piece of a re-split part fails, it returns "" and the leg reports the whole send as undelivered, even though the earlier pieces are already in the chat. The other legs' partial-send paths behave the same way, so this matches existing behaviour, but it is worth stating in the messaging spec.

[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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@bolichen97
bolichen97 enabled auto-merge (squash) November 6, 2026 13:13
@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed c5ba0aa627b58e61cf99fae048f93eb3cdc2dbc7 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] c5ba0aa

Verdict parsed from the review's SHA-scoped output markers for commit c5ba0aa627b58e61cf99fae048f93eb3cdc2dbc7.

False positive or not applicable? A repository writer can comment:
/ai-review override fable c5ba0aa627b58e61cf99fae048f93eb3cdc2dbc7 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of c5ba0aa627b58e61cf99fae048f93eb3cdc2dbc7 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] c5ba0aa

False positive or not applicable? A repository writer can comment:
/ai-review override gpt c5ba0aa627b58e61cf99fae048f93eb3cdc2dbc7 false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running labels Nov 6, 2026
@bolichen97
bolichen97 force-pushed the fix/18764-telegram-markdown-format branch from ed6db6c to 3863af2 Compare November 6, 2026 18:06
@bolichen97

bolichen97 commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor Author
  • span=9225d91670db Preserve code fences when chunking markdown sends

fixed in 3863af2: _deliver_to_channel now splits a markdown send with the fence-aware chunk_for_transport off the loop; a plain send keeps chunk_text.
The other two legs already used chunk_for_transport. New test test_a_long_markdown_send_never_splits_inside_a_code_fence runs all three legs and was red on the own-conversation leg before this head.

@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 6, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

Backend Tests shard 2 (Linux and Windows) is red on test/test_security_gate_liveness.py::test_the_package_stays_within_its_line_budget. This PR does not touch src/kiro_crew/security/; main itself is over the budget after #30774 (tracked in #31648, fix in #31625). This PR waits for that fix and rebases onto it, with no push or override for this red.

@bolichen97
bolichen97 force-pushed the fix/18764-telegram-markdown-format branch from 3863af2 to 60fb6f8 Compare November 6, 2026 19:24
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=b78c443b806e send_markdown re-sends a message that may already be in the chat

fixed in 60fb6f8: send_markdown falls back to the plain send only when Telegram answered 400; a timeout or 5xx returns "" so the leg reports the part unconfirmed. TelegramClient.send_message gains an optional err_out for the code.
New test test_a_failed_html_send_that_telegram_did_not_refuse_is_not_sent_again; the 400 case keeps its plain fallback test.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 6, 2026
@bolichen97
bolichen97 force-pushed the fix/18764-telegram-markdown-format branch from 60fb6f8 to 423602f Compare November 6, 2026 20:08
@bolichen97

Copy link
Copy Markdown
Contributor Author

Backend Tests shard 7 (Linux and Windows) is red on test/test_pull_request_target_allowlist.py::test_only_the_allowed_workflows_use_pull_request_target. This PR does not touch .github/; main itself fails it after #31396 (fix open in #31803). The earlier shard 2 red (security line budget) is fixed on main by #31625. This PR waits for #31803, then rebases onto it.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 6, 2026
@bolichen97
bolichen97 force-pushed the fix/18764-telegram-markdown-format branch from 423602f to 93d2177 Compare November 6, 2026 23:22
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 6, 2026
@bolichen97
bolichen97 force-pushed the fix/18764-telegram-markdown-format branch from 93d2177 to 14ed498 Compare November 7, 2026 00:21
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=b78c443b806e A part whose render outgrows the cap goes out as raw markup

fixed in 14ed498: send_markdown splits a part whose HTML render passes 4096 characters again by rendered length (_split_markdown_bounded, the reply renderer's own bound) and sends each piece rendered; only a piece that cannot be made smaller, or a 400 refusal, goes out plain.
New test test_a_part_whose_render_outgrows_the_cap_is_split_and_still_rendered: every piece is sent with parse_mode="HTML", within the cap, with no raw **.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 7, 2026
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
@bolichen97
bolichen97 force-pushed the fix/18764-telegram-markdown-format branch from 14ed498 to c5ba0aa Compare November 7, 2026 01:21
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 7, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved for the on-call. Review lanes pass on c5ba0aa, no conflict, no open change request.

@bolichen97
bolichen97 merged commit 826712f into main Nov 7, 2026
97 of 98 checks passed
@bolichen97
bolichen97 deleted the fix/18764-telegram-markdown-format branch November 7, 2026 03:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

readiness: passed Eligible automated validation passed for the current revision

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Optional Markdown/HTML parse_mode for Telegram message delivery (send_message / ctx.notify)

2 participants