Embed an image in the body, not just beside it

[rutgerhofste]

Rebased onto #7. This branch originally defined its own attachments seam, because the Graph provider in the admin package needed one to exist. #7 merged first with a better one — source_uid forwarding that never routes bytes through the model, supports_outgoing_attachments so a silent backend cannot swallow a file, a size limit read from SMTP's own SIZE extension. All of that is kept; my duplicate is gone. What remains is the one thing #7 deliberately left out.

From OutgoingAttachment's docstring as merged:

There is no content_id and no inline flag. Inline only means anything against an HTML body that references the part with cid:, and the tool layer composes plain text — a multipart/related holding an image nothing points at renders differently in every client, which is worse than an honest attachment. Inline sending waits for an HTML compose path.

This is that path. The caution is not dropped, it is enforced.

What it adds

body_html, as an alternative — body stays the text a plain-text client shows, and both halves are the same message. And inline / content_id on OutgoingAttachment, where inline is only placed inline when there is HTML that could carry the reference, and degrades to an ordinary attachment when there is not, keeping its Content-ID for a client that wants it anyway.

The placement is the feature

mime._add_parts. An inline part goes inside multipart/related next to the HTML, because a client resolves cid: within that group and nowhere else — the same image parked in the outer multipart/mixed beside the paperclips renders in some clients and arrives as a second paperclip in the rest.

case	structure
no html, no files	text/plain — unchanged
html only	alternative[text, html]
html + inline	alternative[text, related[html, image]]
html + inline + file	mixed[alternative[text, related[html, image]], file]
inline, no html	mixed[text, image] — degraded, honestly

Every inline part ends up with a content_id whether the caller gave one or not, since a part nothing can name is a part nothing can show, and the three spellings a model reaches for (logo, cid:logo, <logo>) reduce to one. source_uid and inline are orthogonal, so a signature image already in the mailbox can be re-embedded without routing the bytes through the model.

Testing

• tests/test_attachments_inline.py (new, 17 tests): the trees above, the content-id handling, and the tool seam. Only what inline adds — test_attachments_outgoing.py still owns the argument forms and the refusal rules.
• GreenMail e2e (1 new): reads the delivered multipart/related back off a real server, Content-ID and both bodies included. Not run locally (no Docker daemon here); the integration-greenmail CI job covers it.
• make test 155 passed (Send attachments over SMTP, not just read them #7's suite included), make lint clean.

Sibling: pantalytics/squirrel-mcp-admin#58 does the same for Outlook over Graph, and needs this branch for body_html.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Ssg4B9jnGCrYKNK9DbqKbv