feat(email): Markdown-to-HTML rendering for all 4 send paths by swissly · Pull Request #73294 · NousResearch/hermes-agent

swissly · 2026-07-28T10:40:55Z

What does this PR do?

Adds automatic Markdown-to-HTML rendering for all outbound emails. Sends emails as multipart/alternative with both text/plain (raw body) and text/html (styled HTML with inline CSS), so HTML-capable clients render rich formatting while plain-text clients fall back gracefully.

Addresses: Closes #11941

How it works

_markdown_to_html_email(body) converts Markdown to HTML using the markdown library (tables, fenced code, nl2br), then injects inline CSS per element (because Gmail strips <style> blocks).
All 4 send paths are updated:
- _send_email → MIMEMultipart("alternative") + _attach_body(msg, body)
- _send_email_with_attachment → _create_body_part(body) inside multipart/mixed
- _send_email_with_attachments → _create_body_part(body) inside multipart/mixed
- _standalone_send → MIMEMultipart("alternative") with html_format config check
Config opt-out: platforms.email.html_format: false disables HTML (default: true).
Graceful fallback: if markdown is not installed or conversion fails, plain text is sent as before.
Security: allowlist sanitizer (_EmailHtmlSanitizer) strips event handlers, javascript:/data: URLs, and <script>/<style> blocks on all outbound HTML.
Already-HTML bodies: _is_html() detects them, _trim_html_preamble_postamble() strips cron-wrapper/model commentary before the first HTML tag and trailing prose after </html> or the last block-level tag (ported from fix(email): HTML emails sent as plain text — two critical bugs #36853, commit 592c9b2f), then the sanitizer applies.
Standalone SMTP fix: _standalone_send uses SMTP_SSL on port 465 (implicit TLS) instead of SMTP+STARTTLS, matching _connect_smtp (found by live E2E against smtp.breitband.ch:465).

Supersedes / Overlapping PRs

feat(email): Markdown-to-HTML rendering for outbound emails #46619 — verify-selected best fix, stale branch targeting retired gateway/platforms/email.py
feat(email): HTML rendering for attachment send paths #54107 — bundled with unrelated changes
feat(email): HTML email support with Markdown conversion #46642, fix(email): SMTP SSL + IPv4 + HTML email support (#11941) #46626 — partial fixes, wrong path
fix(email): HTML emails sent as plain text — two critical bugs #36853 — same topic; feature ported (preamble/postamble trimming) into this PR with attribution; original targets retired gateway/platforms/email.py (bundled-plugin migration 5600105)
feat: HTML email delivery for cron jobs and send_message #34603 — closed by author (overlap); fix(email): avoid double-decoding HTML entities #68707 — complementary receive-path fix (decode & last), independently mergeable

Rebase note (2026-08-03)

Branch was 3714 files behind main. Rebuilt fresh from main (commit 9529ee30), carrying the full review history (Copilot + Tecnium rounds on the prior base). Rebased again onto current main (2026-08-03, +149 commits) — only the 4 email commits are in this branch. Test suite: tests/gateway/test_email_html.py (25 tests) + tests/gateway/test_email.py all pass (61 total).

Copilot

Pull request overview

Adds Markdown-to-HTML rendering for outbound emails in the Email platform plugin, aiming to send multipart/alternative messages (plain + HTML) across all outbound send paths, with a platforms.email.html_format opt-out.

Changes:

Introduces a Markdown → styled-HTML renderer using inline CSS suitable for email clients.
Adds shared helpers to attach plain + optional HTML body parts, and wires them into reply + attachment send paths.
Extends the standalone SMTP sender path to optionally send HTML alongside plain text.

Comments suppressed due to low confidence (1)

plugins/platforms/email/adapter.py:1023

With html_format: false, _send_email() still constructs a multipart/alternative message (and attachment paths still nest an alternative part). This diverges from the PR/issue expectation that opting out preserves the prior plain-text-only MIME shape. Consider using a plain MIMEText message when HTML is disabled, and only creating multipart/alternative when html_format is enabled.

        """Send an email via SMTP. Runs in executor thread."""
        msg = MIMEMultipart("alternative")
        msg["From"] = self._address
        msg["To"] = to_addr

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+# Regex to match <code> inside <pre> blocks — override inline code styling
+_PRE_CODE_OVERRIDE = (
+    re.compile(r"(<pre[^>]*>.*?)<code(\s|>)", re.DOTALL),
+    r'\1<code style="background:transparent;padding:0;color:inherit;font-size:13px;font-family:Menlo,Monaco,Consolas,monospace;"\2',
+)
+
+
+def _markdown_to_html_email(body: str) -> str:
+    """Convert Markdown body to styled HTML email content."""
+    import markdown as _md_mod
+    html = _md_mod.markdown(body, extensions=["tables", "fenced_code", "nl2br"])
+    # Inject inline styles per element (Gmail strips <style> blocks)
+    for tag, style in _HERMES_EMAIL_STYLES:
+        html = re.sub(rf"<{tag}(\s|>)", rf"<{tag} {style}\1", html)
+    # Override <code> inside <pre> blocks (two-pass: inline code already styled above)
+    html = _PRE_CODE_OVERRIDE[0].sub(_PRE_CODE_OVERRIDE[1], html)
+    # Use .replace() instead of .format() — body may contain { } braces
+    return _HERMES_EMAIL_HTML_TEMPLATE.replace("{body}", html)


+        container.attach(MIMEText(body, "plain", "utf-8"))
+        if self._html_format:
+            try:
+                html = _markdown_to_html_email(body)
+                container.attach(MIMEText(html, "html", "utf-8"))
+            except Exception as e:
+                logger.warning("[Email] HTML conversion failed, sending plain only: %s", e, exc_info=True)


+        # HTML email formatting — config: platforms.email.html_format (default: true)
+        self._html_format = extra.get("html_format", True)
+


+    def _create_body_part(self, body: str) -> MIMEMultipart:
+        """Create a multipart/alternative body part (for use inside multipart/mixed)."""
+        alt = MIMEMultipart("alternative")
+        self._attach_parts(alt, body)
+        return alt


alt-glitch · 2026-07-28T10:50:43Z

This was generated by AI during triage.

Related: #54107 is the earlier open live-path HTML-email implementation. Its current diff preserves detected existing HTML and has regression coverage, whereas this patch always Markdown-renders the body. These are competing rendering contracts, so a maintainer should choose/consolidate rather than treat them as duplicates.

swissly · 2026-07-28T10:58:40Z

Copilot Review — All 4 findings addressed ✅

1. Duplicate style= in <pre><code> blocks ✅
Replaced two-pass approach with placeholder strategy: extract <pre><code>...\code></pre> blocks into placeholders BEFORE style injection, then restore with properly styled blocks. No duplicate style= attributes possible.

2. ImportError handling ✅
Caught ImportError separately in _attach_parts(). When markdown is not installed (expected opt-in), logs at DEBUG level instead of WARNING. WARNING reserved for real conversion errors.

3. Unit tests ✅ (10 tests, all passing)

test_fenced_code_no_duplicate_style — verifies no duplicate style= in pre/code tags
test_html_enabled/disabled — verifies MIME structure (2 parts vs 1)
test_importerror_falls_back — verifies graceful degradation without markdown
test_create_body_part — verifies return type per html_format

4. _create_body_part plain-only ✅
Now returns simple MIMEText when html_format=False, instead of always building multipart/alternative. Attachment emails stay plain-only shape under opt-out.

teknium1

Thanks for porting the Markdown-to-HTML work to the live email adapter. The feature premise is valid: current main sends only MIMEText(..., "plain") in the primary path (plugins/platforms/email/adapter.py:949), both attachment paths (:1063, :1143), and standalone delivery (:1219).

Problems

plugins/platforms/email/adapter.py:109-126 converts and styles the entire body without a raw-HTML safety step. The existing Matrix rich-output path pre-sanitizes before conversion (plugins/platforms/matrix/adapter.py:4561, :837-854) and allowlist-sanitizes output (:816-823). The original issue discussion also raised disabling raw HTML/JS. Please define and test the email policy before shipping this renderer.
The member discussion correctly identifies a competing contract with #54107: it preserves detected existing HTML, while this patch always Markdown-renders. This needs consolidation rather than an implicit behavior change.
website/docs/user-guide/messaging/email.md:123 still says replies are plain text, but this PR adds a public html_format option without documentation.

Suggested changes

Add an explicit sanitized/raw-HTML policy with security regression tests, reconcile it with #54107, and document html_format plus MIME behavior.
Replace the tautological brace assertion in tests/gateway/test_email_html.py:48 with an exact rendering assertion.

Automated hermes-sweeper review.

teknium1 · 2026-07-30T15:41:27Z

+def _markdown_to_html_email(body: str) -> str:
+    """Convert Markdown body to styled HTML email content."""
+    import markdown as _md_mod
+    html = _md_mod.markdown(body, extensions=["tables", "fenced_code", "nl2br"])


This renderer converts and styles the full body without a raw-HTML safety step. The established Matrix path pre-sanitizes Markdown and allowlist-sanitizes rendered HTML (plugins/platforms/matrix/adapter.py:837-854, :816-823). Please define and test the email policy for raw HTML, event attributes, and unsafe URLs before sending it as text/html.

teknium1 · 2026-07-30T15:41:27Z

+        """Body with { } braces must not break template substitution."""
+        from plugins.platforms.email.adapter import _markdown_to_html_email
+        html = _markdown_to_html_email("Use `{code}` here")
+        assert "{code}" not in html or "code" in html  # braces consumed or preserved


This assertion is tautological: the generated template/styles already contain the substring code, so the right-hand side makes it pass regardless of brace handling. Assert the exact expected rendered code span or verify conversion completes while preserving the intended content.

swissly · 2026-07-30T15:56:53Z

Tecnium Review — All findings addressed ✅

1. HTML sanitization policy ✅
Added _EmailHtmlSanitizer — allowlist-based HTML sanitizer mirroring the Matrix adapter pattern:

Only safe structural tags (p, h1-h6, ul, ol, table, a, code, pre, strong, em, etc.)
Event handlers (onclick, onload, etc.) stripped
Unsafe URLs (javascript:, data:) stripped
<script>/<style> blocks removed entirely
Inline styles preserved (email clients need them)
Sanitization applied AFTER Markdown-to-HTML conversion
8 security regression tests (script, events, javascript URLs, safe URLs, style tags, inline styles, disallowed/allowed tags)

2. HTML detection for pre-existing HTML ✅
Added _is_html() — detects block-level HTML tags in body. When body already contains HTML (e.g. from a skill that generates HTML), sanitizes directly instead of re-rendering through Markdown. Resolves conflict with #54107 behavior.

3. Documentation updated ✅
website/docs/user-guide/messaging/email.md now documents:

multipart/alternative MIME structure
html_format config option (default: true)
MIME structure with/without attachments
Sanitization policy

4. Test fixes ✅

test_braces_not_escaped: replaced tautological assertion with exact rendering check
10 new tests: 8 security + 2 HTML detection
Total: 20 tests, all passing (1.16s)

swissly · 2026-08-03T08:30:56Z

Test comment via gh CLI

swissly · 2026-08-03T14:54:08Z

Rebased onto current main (2026-08-03, +149 commits upstream). Branch was rebuilt clean from origin/main — only the 3 email commits (HTML rendering, 465 SMTP_SSL, tests) are included; prior local patches (tool-call repair, OpenViking) are no longer in this branch. 54/54 email tests green. PR #34603 (overlap) was closed by its author — this PR remains the consolidated HTML-email fix. Note: upstream merged secret-scope fixes (f08f403, 359ff01) which our standalone-send path now composes with cleanly.

Nested escaped text like &lt;APIKEY&gt; was decoded twice in one _strip_html call (& -> &, then < -> <), producing <APIKEY> instead of literal <APIKEY>. Decode </> before & so each entity layer is decoded at most once (issue NousResearch#68704). Same fix as PR NousResearch#68707 (tooiuiiu); applied locally for immediate effect, kept out of PR NousResearch#73294 (send-path scope). Tests: +2 regression cases.

swissly · 2026-08-04T07:12:57Z

Triage update for the needs-decision label: the earlier live-path implementation referenced during triage — #54107 — has been closed without merging, so there is no longer a competing contract to reconcile. This PR (Markdown→HTML for all 4 send paths, allowlist sanitizer, 54/54 tests, rebased onto current main 2026-08-03) is MERGEABLE/CLEAN and ready for review. Happy to adjust scope if a narrower change is preferred.

Resolves the unresolved merge conflict left by hermes update (main had UU state on adapter.py): HEAD kept secret-scope reads, incoming kept the HTML block. Both merged; sanitizer + placeholder strategy ported from 72c960d91a (both Copilot and Tecnium reviews passed). - _markdown_to_html_email: placeholder strategy for <pre><code> blocks (no duplicate style=), allowlist sanitizer (_EmailHtmlSanitizer), _is_html detection for already-HTML bodies - _attach_parts: plain + HTML in multipart/alternative, ImportError separated from general Exception - _create_body_part: returns MIMEText when html_format disabled - _standalone_send: honors html_format (was hardcoded plain), uses _get_secret scope-aware reads (conflict merge, not os.getenv) - tests: 20 new tests (markdown, MIME structure, sanitization, detection) Supersedes prior branch base (3714 files stale); fresh branch off main.

_standalone_send (cron delivery path) used SMTP()+STARTTLS for ALL ports; port 465 requires implicit TLS. Matches _connect_smtp behavior (class path). Found by live E2E test against smtp.breitband.ch:465 (timeout without fix).

Regression tests for the port-selection fix found by live E2E test (smtp.breitband.ch:465 hung with plain SMTP+STARTTLS).

Ported from PR NousResearch#36853 (chtse53): cron wrappers ('Cronjob Response: <name>') and model commentary before the first HTML tag, plus trailing prose after </html> or the last block-level tag, are stripped before sanitizing an already-HTML body. Prevents broken plain-text wrappers from rendering inside HTML emails. NousResearch#36853 targets gateway/platforms/email.py which no longer exists on main (adapters migrated to bundled plugins in 5600105); this ports the feature to plugins/platforms/email/adapter.py. Contributor credit kept. 5 regression tests.

swissly · 2026-08-12T17:17:01Z

Ping @teknium1 — this PR is mergeable/clean, all Copilot+Tecnium findings addressed, 54 email tests green, rebased onto current main. Carries the needs-decision label (the competing #54107 is closed). Requesting a maintainer decision / review.

Copilot AI review requested due to automatic review settings July 28, 2026 10:40

Copilot started reviewing on behalf of swissly July 28, 2026 10:41 View session

Copilot AI reviewed Jul 28, 2026

View reviewed changes

swissly mentioned this pull request Jul 29, 2026

feat(email): HTML rendering for attachment send paths #54107

Closed

teknium1 reviewed Jul 30, 2026

View reviewed changes

teknium1 added sweeper:risk-security-boundary Sweeper risk: may affect sandboxing, auth, credentials, or sensitive data sweeper:blast-moderate Sweeper blast radius: moderate — a subsystem or single platform labels Jul 30, 2026

alt-glitch mentioned this pull request Jul 31, 2026

[Feature]: Configurable multipart HTML formatting for Email delivery #75275

Open

swissly force-pushed the feat/email-html-markdown-rendering branch from 72c960d to 9529ee3 Compare August 3, 2026 08:29

This was referenced Aug 3, 2026

fix(email): HTML emails sent as plain text — two critical bugs #36853

Open

feat: HTML email delivery for cron jobs and send_message #34603

Closed

fix(email): avoid double-decoding HTML entities #68707

Open

GottZ mentioned this pull request Aug 3, 2026

[Bug]: Email HTML fallback double-decodes escaped entities #68704

Open

swissly force-pushed the feat/email-html-markdown-rendering branch from c551867 to 2c5008a Compare August 3, 2026 14:53

swissly mentioned this pull request Aug 11, 2026

feat(agent): tool-call repair observability (port of #62640) #77941

Open

swissly added 4 commits August 12, 2026 09:33

fix(email): standalone send uses SMTP_SSL for port 465

4861bf0

_standalone_send (cron delivery path) used SMTP()+STARTTLS for ALL ports; port 465 requires implicit TLS. Matches _connect_smtp behavior (class path). Found by live E2E test against smtp.breitband.ch:465 (timeout without fix).

test(email): standalone send SMTP_SSL on 465, STARTTLS on 587

34a9164

Regression tests for the port-selection fix found by live E2E test (smtp.breitband.ch:465 hung with plain SMTP+STARTTLS).

swissly force-pushed the feat/email-html-markdown-rendering branch from 919258f to e1a695b Compare August 12, 2026 14:50

Navigation Menu

Uh oh!

feat(email): Markdown-to-HTML rendering for all 4 send paths - #73294

feat(email): Markdown-to-HTML rendering for all 4 send paths#73294
swissly wants to merge 4 commits into
NousResearch:mainfrom
swissly:feat/email-html-markdown-rendering

swissly commented Jul 28, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

alt-glitch commented Jul 28, 2026

Uh oh!

swissly commented Jul 28, 2026

Uh oh!

teknium1 left a comment

Uh oh!

teknium1 Jul 30, 2026

Uh oh!

teknium1 Jul 30, 2026

Uh oh!

swissly commented Jul 30, 2026

Uh oh!

swissly commented Aug 3, 2026

Uh oh!

swissly commented Aug 3, 2026

Uh oh!

swissly commented Aug 4, 2026

Uh oh!

swissly commented Aug 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

		# HTML email formatting — config: platforms.email.html_format (default: true)
		self._html_format = extra.get("html_format", True)

Uh oh!

Conversation

swissly commented Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

How it works

Supersedes / Overlapping PRs

Rebase note (2026-08-03)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

alt-glitch commented Jul 28, 2026

Uh oh!

swissly commented Jul 28, 2026

Copilot Review — All 4 findings addressed ✅

Uh oh!

teknium1 left a comment

Choose a reason for hiding this comment

Problems

Suggested changes

Uh oh!

teknium1 Jul 30, 2026

Choose a reason for hiding this comment

Uh oh!

teknium1 Jul 30, 2026

Choose a reason for hiding this comment

Uh oh!

swissly commented Jul 30, 2026

Tecnium Review — All findings addressed ✅

Uh oh!

swissly commented Aug 3, 2026

Uh oh!

swissly commented Aug 3, 2026

Uh oh!

swissly commented Aug 4, 2026

Uh oh!

swissly commented Aug 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

swissly commented Jul 28, 2026 •

edited

Loading