@dumbmice/pi-mailbridge 0.0.0-stage → 0.1.1

package/dist/core/inline-images.js

@@ -0,0 +1,355 @@
+// Attach local files that a notification links to.
+//
+// Two shapes, both resolved from the agent's working directory:
+//
+//   ![shot](./shot.png)     an <img> - inlined as a CID part so it renders in place
+//   [report](./report.pdf)  an <a>   - attached with its real filename, and the link text
+//                                      says so, because a mail client cannot follow a
+//                                      relative path and a cid: anchor is unreliable
+//
+// The result is mailed, so the safety rules are the point: an image must sniff as an image
+// (magic bytes, not an extension), a non-image must have an allowlisted extension, every
+// file is size- and count-capped, and anything unreadable degrades to a sentence instead of
+// a broken link. Content is hashed, so one file referenced twice rides once.
+//
+// A Markdown image pointing at a local path renders as `<img src="./shot.png">`, which a
+// mail client cannot resolve - the reader sees a broken image. The standard fix is a
+// `multipart/related` attachment referenced by `cid:`, which is what this does.
+//
+// Safety, because the src comes from model output and the result is emailed:
+//
+//   - the file must actually **sniff** as an image (magic bytes), not merely have an
+//     image extension, so a renamed text file or key is never attached;
+//   - a size cap and a count cap, so a mail cannot become a file transfer;
+//   - a path that cannot be read or does not sniff degrades to a short note instead of
+//     a broken image.
+//
+// Images are also addressed by content hash, so the same image referenced twice is
+// attached once.
+import { createHash } from "node:crypto";
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import { basename, dirname, isAbsolute, relative, resolve } from "node:path";
+import { homedir } from "node:os";
+import { configDir, stateDir } from "../store/paths.js";
+/**
+ * Provider ceilings, which is what these numbers are derived from:
+ *
+ *   Gmail        25 MB send (50 MB receive)
+ *   Outlook.com  25 MB per message
+ *   M365 work    35 MB send / 36 MB receive (Exchange default 10 MB)
+ *   QQ Mail      50 MB attachments, 55 MB with the body, 200 MB/day
+ *
+ * Base64 inflates by about a third, so 18 MB of files is roughly 24 MB on the wire - under the
+ * smallest ceiling. `notify.maxAttachmentMb` raises the budget for a provider that allows more.
+ */
+export const MAX_INLINE_BYTES = 5 * 1024 * 1024;
+/** Per-file cap for an attached (non-inline) file. */
+export const MAX_FILE_BYTES = 15 * 1024 * 1024;
+/** Default total payload cap; a caller may pass `maxTotalBytes` instead. */
+export const MAX_INLINE_TOTAL_BYTES = 18 * 1024 * 1024;
+export const MAX_INLINE_COUNT = 10;
+/**
+ * Extensions we will attach from a link.
+ *
+ * An allowlist rather than "anything readable": the path comes from model output, and the
+ * one thing that must never happen is mailing a private key because a prompt said so. Add
+ * to this list deliberately.
+ */
+const ALLOWED_FILE_EXTENSIONS = {
+    pdf: "application/pdf",
+    txt: "text/plain",
+    log: "text/plain",
+    md: "text/markdown",
+    csv: "text/csv",
+    tsv: "text/tab-separated-values",
+    json: "application/json",
+    yml: "application/yaml",
+    yaml: "application/yaml",
+    xml: "application/xml",
+    html: "text/html",
+    zip: "application/zip",
+    gz: "application/gzip",
+    tar: "application/x-tar",
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    webp: "image/webp",
+    svg: "image/svg+xml",
+    docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+};
+/**
+ * Identify an image from its magic bytes rather than trusting the extension.
+ *
+ * SVG is deliberately absent. Not because email cannot carry it - a linked SVG file
+ * (`<img src="x.svg">` or a cid attachment) is supported by roughly 97% of clients, and
+ * Gmail rasterises it to PNG server-side - but because **Outlook on Windows (2007-2019)
+ * renders nothing at all** for it, with no fallback. Inline `<svg>` markup is the truly
+ * dead form at ~40%, since Gmail deletes the element while sanitising.
+ *
+ * PNG is therefore the one format that renders everywhere, which matters more for a
+ * notification than vector sharpness. SVG could be added behind a flag with an explicit
+ * "invisible in Outlook desktop" caveat.
+ */
+export function sniffImage(buffer) {
+    if (buffer.length >= 8 && buffer.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) {
+        return { contentType: "image/png", ext: "png" };
+    }
+    if (buffer.length >= 3 && buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) {
+        return { contentType: "image/jpeg", ext: "jpg" };
+    }
+    if (buffer.length >= 6) {
+        const head = buffer.subarray(0, 6).toString("latin1");
+        if (head === "GIF87a" || head === "GIF89a")
+            return { contentType: "image/gif", ext: "gif" };
+    }
+    if (buffer.length >= 12 && buffer.subarray(0, 4).toString("latin1") === "RIFF" && buffer.subarray(8, 12).toString("latin1") === "WEBP") {
+        return { contentType: "image/webp", ext: "webp" };
+    }
+    return undefined;
+}
+const IMG_TAG = /<img\b[^>]*>/gi;
+const SRC_ATTR = /\bsrc\s*=\s*"([^"]*)"/i;
+const ALT_ATTR = /\balt\s*=\s*"([^"]*)"/i;
+/** Markdown links become anchors; the text between them is already rendered HTML. */
+const LINK_TAG = /<a\s+href="([^"]*)"[^>]*>([\s\S]*?)<\/a>/gi;
+/** realpath, or the input when it cannot be resolved (tests use paths that may not exist). */
+function safeRealpath(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** stat that follows symlinks; undefined when the path does not resolve. */
+function safeStat(path) {
+    try {
+        return statSync(path);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Is this resolved file safe to attach?
+ *
+ * Three rules, all fail-closed:
+ *   - it must resolve, and it must land inside the project directory (a symlink out is refused);
+ *   - the project directory itself must be a real project, not `/` or your home - with cwd = ~
+ *     the config file is "inside the project" and the allowlist would happily mail the password;
+ *   - the daemon's own config and state directories are never attached, whatever the cwd.
+ *
+ * The comparison goes through `relative()`, not a `/`-joined prefix: on Windows the separator is
+ * `\`, so a prefix test silently refused every attachment there.
+ */
+function insideRoot(path, rootReal) {
+    if (!rootReal)
+        return "root-refused";
+    // A path that does not resolve yet (a missing file, a dangling link) is compared by its
+    // parent's real location plus its own name, so a project reached through a symlinked path
+    // (macOS /var -> /private/var, a symlinked checkout) still reports "not found" rather than
+    // "outside the project"; a path that resolves elsewhere - `ln -s /proc/self/fd/0` - is
+    // compared at its real location and refused.
+    const target = safeRealpath(path) ?? joinResolved(dirname(path), basename(path));
+    const home = safeRealpath(homedir());
+    // Exact equality: a project *inside* home is the normal case and must still attach.
+    if (rootReal === "/" || (home !== undefined && rootReal === home))
+        return "root-refused";
+    for (const dir of [configDir(), stateDir()]) {
+        const real = safeRealpath(dir);
+        if (real && contains(real, target))
+            return "root-refused";
+    }
+    return contains(rootReal, target) ? "ok" : "outside-root";
+}
+/** Does `parent` contain `child`? Separator-agnostic and not fooled by a shared prefix. */
+function contains(parent, child) {
+    const rel = relative(parent, child);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+/** realpath of a directory plus one unresolved name. */
+function joinResolved(dir, name) {
+    return `${safeRealpath(dir) ?? dir}/${name}`;
+}
+/** A filename a mail client will accept: no separators, no control characters, bounded. */
+function safeFilename(path, fallback) {
+    const base = path.split(/[\\/]/).pop() ?? fallback;
+    const cleaned = base
+        .normalize("NFKC")
+        .replace(/[\u0000-\u001f\u007f"<>|:*?]+/g, "-")
+        .replace(/^[.]+/, "")
+        .trim();
+    return (cleaned || fallback).slice(0, 120);
+}
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+function note(label, detail) {
+    return `<span style="opacity:.7">[${escapeHtml(label)}${detail ? `: ${escapeHtml(detail)}` : ""}]</span>`;
+}
+function resolvePath(src, root) {
+    let value = src.trim();
+    if (value.startsWith("file://"))
+        value = value.slice("file://".length);
+    if (value.startsWith("~/"))
+        value = `${homedir()}${value.slice(1)}`;
+    return isAbsolute(value) ? value : resolve(root, value);
+}
+export function inlineLocalImages(html, options = {}) {
+    const root = options.root ?? process.cwd();
+    const maxBytes = options.maxBytes ?? MAX_INLINE_BYTES;
+    const maxCount = options.maxCount ?? MAX_INLINE_COUNT;
+    const maxTotal = options.maxTotalBytes ?? MAX_INLINE_TOTAL_BYTES;
+    const read = options.readFile ?? ((path) => readFileSync(path));
+    const size = options.sizeOf ?? ((path) => statSync(path).size);
+    // Resolve the project directory once. Attachments are limited to it: a symlink inside the
+    // project pointing at `~/.config/pi-mailbridge/config.json` would otherwise mail the
+    // mailbox password, and the allowlist says nothing about where a file came from.
+    const rootReal = safeRealpath(root);
+    const attachments = [];
+    const skipped = [];
+    const byCid = new Map();
+    let total = 0;
+    const replaced = html.replace(IMG_TAG, (tag) => {
+        const src = SRC_ATTR.exec(tag)?.[1] ?? "";
+        const alt = ALT_ATTR.exec(tag)?.[1] ?? "";
+        // Remote, protocol-relative and already-inlined sources are left alone.
+        if (!src || /^(?:https?:)?\/\//i.test(src) || src.startsWith("cid:") || src.startsWith("data:"))
+            return tag;
+        if (attachments.length >= maxCount) {
+            skipped.push({ src, reason: "too-many" });
+            return note(alt || "image", "not attached, too many images");
+        }
+        const path = resolvePath(src, root);
+        const verdict = insideRoot(path, rootReal);
+        if (verdict !== "ok") {
+            skipped.push({ src, reason: verdict });
+            return note(alt || "image", verdict === "root-refused"
+                ? "not attached, start pi in a project directory"
+                : "not attached, outside the project");
+        }
+        let bytes;
+        try {
+            // Existence first, so the note says "not found" rather than "unreadable"; then the
+            // type, because a FIFO or a device reports size 0 and blocks the read forever, which
+            // would hang the send (and the poll tick that awaits it).
+            const st = safeStat(path);
+            if (!st) {
+                skipped.push({ src, reason: "not-found" });
+                return note(alt || "image", "not attached, file not found");
+            }
+            if (!st.isFile()) {
+                skipped.push({ src, reason: "unreadable" });
+                return note(alt || "image", "not attached, not a regular file");
+            }
+            if (size(path) > maxBytes) {
+                skipped.push({ src, reason: "too-large" });
+                return note(alt || "image", `${Math.round(size(path) / 1024)} KB, over the ${Math.round(maxBytes / 1024)} KB limit`);
+            }
+            bytes = read(path);
+        }
+        catch {
+            skipped.push({ src, reason: "not-found" });
+            return note(alt || "image", "not attached, file not found");
+        }
+        const kind = sniffImage(bytes);
+        if (!kind) {
+            skipped.push({ src, reason: "not-an-image" });
+            return note(alt || "image", "not attached, not an image");
+        }
+        if (bytes.length > maxBytes || total + bytes.length > maxTotal) {
+            skipped.push({ src, reason: "too-large" });
+            return note(alt || "image", "not attached, too large");
+        }
+        const digest = createHash("sha256").update(bytes).digest("hex").slice(0, 16);
+        const cid = `pi-${digest}@pi.local`;
+        const existing = byCid.get(cid);
+        if (!existing) {
+            const base = (alt || "image").replace(/[^A-Za-z0-9._-]+/g, "-").slice(0, 40) || "image";
+            const attachment = {
+                filename: `${base}.${kind.ext}`,
+                content: bytes,
+                contentType: kind.contentType,
+                cid,
+            };
+            byCid.set(cid, attachment);
+            attachments.push(attachment);
+            total += bytes.length;
+        }
+        return `<img src="cid:${cid}" alt="${escapeHtml(alt)}" style="max-width:100%;height:auto">`;
+    });
+    // Links to local files become ordinary attachments. Their anchors cannot work in a mail
+    // client - a relative path does not exist there and `cid:` in an <a href> is unreliable -
+    // so the text stays and the filename is named beside it.
+    const withLinks = replaced.replace(LINK_TAG, (_tag, href, inner) => {
+        if (!href || /^(?:https?:|mailto:|tel:|cid:|data:|#)/i.test(href))
+            return _tag;
+        const path = resolvePath(href, root);
+        // The skipped reason is a stable code (tests and diagnostics match on it); the note is
+        // what the reader sees.
+        const refuse = (reason, text) => {
+            skipped.push({ src: href, reason });
+            return `${inner} ${note("not attached", text)}`;
+        };
+        if (attachments.length >= maxCount)
+            return refuse("too-many", "too many attachments");
+        const verdict = insideRoot(path, rootReal);
+        if (verdict !== "ok") {
+            return refuse(verdict, verdict === "root-refused" ? "start pi in a project directory" : "outside the project");
+        }
+        const filename = safeFilename(href, "file");
+        const ext = filename.includes(".") ? filename.split(".").pop().toLowerCase() : "";
+        const contentType = ALLOWED_FILE_EXTENSIONS[ext];
+        if (!contentType)
+            return refuse("not-allowed", "this file type is not attached");
+        let bytes;
+        try {
+            const st = safeStat(path);
+            if (!st)
+                return refuse("not-found", "file not found");
+            if (!st.isFile())
+                return refuse("unreadable", "not a regular file");
+            // Per-file cap before reading; the *total* is charged after the dedupe below, so a
+            // file that is already attached does not fail as "over the limit" for zero new bytes.
+            if (size(path) > MAX_FILE_BYTES) {
+                return refuse("too-large", `${Math.round(size(path) / 1024)} KB, over the limit`);
+            }
+            bytes = read(path);
+            // The file can grow between stat and read.
+            if (bytes.length > MAX_FILE_BYTES) {
+                return refuse("too-large", `${Math.round(bytes.length / 1024)} KB, over the limit`);
+            }
+        }
+        catch {
+            skipped.push({ src: href, reason: "not-found" });
+            return `${inner} ${note("not attached", "file not found")}`;
+        }
+        // Same content, same part: a report linked from two places is attached once.
+        const digest = createHash("sha256").update(bytes).digest("hex").slice(0, 16);
+        const existing = byCid.get(`file-${digest}`);
+        const name = existing?.filename ?? filename;
+        if (!existing) {
+            if (total + bytes.length > maxTotal) {
+                return refuse("too-large", `${Math.round(bytes.length / 1024)} KB, over the limit`);
+            }
+            const attachment = {
+                filename,
+                content: bytes,
+                contentType,
+                contentDisposition: "attachment",
+            };
+            byCid.set(`file-${digest}`, attachment);
+            attachments.push(attachment);
+            total += bytes.length;
+        }
+        return `${inner} <span style="opacity:.7">[attached: ${escapeHtml(name)}]</span>`;
+    });
+    return { html: withLinks, attachments, skipped };
+}

package/dist/core/mail-command.js

@@ -0,0 +1,62 @@
+// Commands arriving as a reply.
+//
+// Why this exists instead of pi's own dispatcher: `sendUserMessage(..., { expandPromptTemplates:
+// true })` hands any text starting with "/" to `_tryExecuteExtensionCommand`, which runs the
+// command and returns *without a turn* - and returns `void` to the caller, so a caller cannot
+// tell a command that ran from a prompt that pi rejected (no model, expired credentials,
+// compaction). This package acks and marks `\Seen` after that call returns, so a silent
+// rejection would consume the mail. Dispatching here means we know what happened, and we can
+// refuse the commands that must never be triggered by mail.
+//
+// The parse is deliberately strict: the *entire* body must be one command line. A reply that
+// says "please run this" and quotes `/mailbridge off` underneath is a message, not an instruction.
+/** Subcommands a mail reply may run. Everything else stays text for the agent to read. */
+export const MAIL_SAFE_SUBCOMMANDS = [
+    "on",
+    "off",
+    "status",
+    "check",
+    "smoke",
+    "help",
+];
+/** Subcommands that change the machine, the credentials or the queue - never by mail. */
+export const MAIL_REFUSED_SUBCOMMANDS = ["setup", "auth", "restart", "prime"];
+/**
+ * Parse a reply body as a command, or return undefined if it is ordinary text.
+ *
+ * `\r\n` is normalised because mail bodies carry it. Leading and trailing blank lines are
+ * ignored, but any second non-blank line makes this text: a command must be the whole message.
+ */
+export function parseMailCommand(body) {
+    const lines = body
+        .replace(/\r\n/g, "\n")
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    if (lines.length !== 1)
+        return undefined;
+    const line = lines[0];
+    if (!line.startsWith("/"))
+        return undefined;
+    const space = line.indexOf(" ");
+    const name = (space === -1 ? line.slice(1) : line.slice(1, space)).toLowerCase();
+    const args = space === -1 ? "" : line.slice(space + 1).trim();
+    if (name !== "mailbridge")
+        return undefined;
+    // Bare `/mailbridge` prints status, exactly as it does at the prompt.
+    // Every safe subcommand takes no arguments, so any leftover word means this is a message that
+    // happens to start with a command: `/mailbridge off thanks, the deploy is still broken` must
+    // reach the agent, not flip the mode and drop the sentence. Splitting on /\s+/ also catches
+    // U+2028/U+2029, which a body can contain without a newline - though the whitelist below
+    // would reject a token carrying them anyway.
+    const words = args.split(/\s+/).filter(Boolean);
+    if (words.length > 1)
+        return undefined;
+    const sub = (words[0] ?? "").toLowerCase() || "status";
+    if (!MAIL_SAFE_SUBCOMMANDS.includes(sub)) {
+        // `setup`, `auth`, `restart`, `prime` and unknown words stay text, so the agent sees the
+        // request and nothing reconfigures itself because someone's address was spoofed.
+        return undefined;
+    }
+    return { name, args, sub: sub };
+}

package/dist/core/mailer.js

@@ -0,0 +1,126 @@
+import { randomUUID } from "node:crypto";
+// SMTP send path.
+//
+// Deliberately tiny: build transport options, hand the message to the transport,
+// let failures propagate. Callers decide how to degrade (release a reservation,
+// surface an error to the tool) — this module never pretends a send succeeded.
+//
+// Two auth modes, because Outlook has no third option:
+//   LOGIN    — provider app password. Works for Gmail, Fastmail, QQ, 163, …
+//   XOAUTH2  — access token. Use for outlook.com/hotmail: Microsoft retired SMTP basic
+//              auth on 2024-09-16, and IMAP rejects app passwords outright.
+//
+// Subject stamping is NOT done here. It belongs to core/token so there is exactly
+// one place that mints routing tokens.
+import nodemailer from "nodemailer";
+import { withFreshToken } from "./oauth.js";
+import { renderMessage } from "./html.js";
+const _nodemailerShapeOk = true;
+void _nodemailerShapeOk;
+/** Default: nodemailer. Tests inject a fake so no socket is ever opened. */
+export const defaultTransportFactory = (options) => nodemailer.createTransport(options);
+/**
+ * Transport options for this account.
+ * Exported so `--check` can validate the shape without sending anything.
+ */
+export async function buildTransportOptions(config, deps = {}) {
+    const smtp = config.mail.smtp;
+    const base = { host: smtp.host, port: smtp.port, secure: smtp.secure };
+    if (smtp.authType === "XOAUTH2") {
+        // A provider is enough on its own: that is the path withFreshToken retries through.
+        const getToken = deps.getAccessToken ?? (deps.provider ? () => deps.provider.getToken() : undefined);
+        if (!getToken) {
+            throw new Error("pi-mailbridge: smtp.authType is XOAUTH2 but no token provider is configured — set mail.smtp.tokenCommand (see docs/OAUTH.md)");
+        }
+        const accessToken = await getToken();
+        if (!accessToken)
+            throw new Error("pi-mailbridge: OAuth2 token provider returned an empty token");
+        return { ...base, auth: { type: "OAuth2", user: smtp.user, accessToken } };
+    }
+    return { ...base, auth: { user: smtp.user, pass: smtp.password } };
+}
+/**
+ * Send one plain-text message.
+ * Throws on any transport failure — there is no partial-success path.
+ *
+ * Returns the Message-ID WE stamped (minted here if the caller did not pass one), so the
+ * caller can record the id it actually sent - threading and the self-echo guard both
+ * depend on that value matching the header.
+ */
+export async function sendMail(config, message, deps = {}) {
+    if (!config.mail.smtp.host)
+        throw new Error("pi-mailbridge: mail.smtp.host is not configured");
+    if (!message.to)
+        throw new Error("pi-mailbridge: no recipient (mail.to)");
+    const factory = deps.transportFactory ?? defaultTransportFactory;
+    const rendered = renderMessage(message.text, {
+        ...(message.cwd ? { root: message.cwd } : {}),
+        // The user's cap, so a QQ account can use 45 MB and a Gmail account is not left with a
+        // send that fails at the provider.
+        maxTotalBytes: Math.round(config.notify.maxAttachmentMb * 1024 * 1024),
+    });
+    // withFreshToken hands each attempt its token; use it directly rather than fetching a
+    // second one, or the provider is called twice per attempt and the counts drift.
+    // One id for the header and the return value. Minting twice meant callers that did not
+    // pass one got back an id that was not the one in the message.
+    const stampedId = message.messageId ?? generateMessageId(config.mail.smtp.user);
+    const dispatch = async (accessToken) => {
+        const transportOptions = await buildTransportOptions(config, accessToken ? { ...deps, getAccessToken: async () => accessToken } : deps);
+        const transporter = factory(transportOptions);
+        return (await transporter.sendMail({
+            from: message.from ?? config.mail.smtp.user,
+            // Minted here at the latest, so the id is known to the caller before the transport
+            // has spoken. A notification must be recognisable as ours even if the send races an
+            // IMAP exists event.
+            messageId: stampedId,
+            // Belt and braces for single-mailbox mode: the scan refuses any message carrying it.
+            // The second header carries the id we minted: providers may replace Message-ID (QQ
+            // does), and this is how the just-sent copy is identified afterwards.
+            headers: { "X-Pi-Mailbridge": "notification", "X-Pi-Mailbridge-Id": stampedId },
+            to: message.to,
+            // The subject carries model-controlled text. A CR/LF would fold a new header into
+            // the message (the classic header-injection shape), and an unbounded subject is
+            // rejected by some MTAs, so both are flattened at the single choke point.
+            subject: sanitizeSubject(message.subject),
+            // multipart/alternative: clients fold quoted history only for HTML mail, so
+            // plain-text-only notifications produced reply threads of raw repeated text.
+            text: message.text,
+            html: rendered.html,
+            // Thread every notification for a session into one conversation. Subject alone is
+            // enough for Outlook's conversation topic; these headers are what Gmail uses.
+            ...(message.inReplyTo ? { inReplyTo: message.inReplyTo } : {}),
+            ...(message.references?.length ? { references: message.references.join(" ") } : {}),
+            // Local images become cid: attachments; a bare file path would arrive broken.
+            ...(rendered.attachments.length > 0 ? { attachments: rendered.attachments } : {}),
+        }));
+    };
+    // A revoked or expired grant surfaces as an auth error on the first attempt. With a
+    // provider, drop the cached token, mint a new one and retry once (OAUTH.md promises
+    // this); without one, the failure propagates as before.
+    // The transport's own result is deliberately ignored: the id we care about is ours.
+    if (deps.provider && config.mail.smtp.authType === "XOAUTH2") {
+        await withFreshToken(deps.provider, dispatch);
+    }
+    else {
+        await dispatch();
+    }
+    // Ours, not the transport's: it is what was recorded and what threading references.
+    return { messageId: stampedId };
+}
+/**
+ * A Message-ID we control, on the sender's domain where possible.
+ * Domain is cosmetic; uniqueness is randomUUID's job.
+ */
+export function generateMessageId(from) {
+    const domain = /@([^@>\s]+)/.exec(from)?.[1] ?? "pi-mailbridge.invalid";
+    return `<${randomUUID()}@${domain}>`;
+}
+/** RFC 5322 caps a header line at 998 octets; keep well inside it. */
+const MAX_SUBJECT = 200;
+export function sanitizeSubject(subject) {
+    return subject
+        .replace(/[\r\n\u0000]+/g, " ")
+        .replace(/\s{2,}/g, " ")
+        .trim()
+        .slice(0, MAX_SUBJECT);
+}

package/dist/core/markdown.js

@@ -0,0 +1,96 @@
+// Markdown → HTML for the mail body.
+//
+// The agent answers in Markdown. Sending it escaped means the reader sees `**bold**`,
+// `| a | b |` and ``` fences in a client that could have rendered them.
+//
+// Rendering is delegated to **markdown-it**, configured to be safe by default rather
+// than trusted:
+//
+//   - `html: false` — raw HTML in the model output is escaped, not passed through, so
+//     there is no sanitiser to get wrong and nothing to lose on a library upgrade.
+//   - `linkify: true` — bare URLs become links, which is most of the value of an email.
+//   - markdown-it's own `validateLink` refuses `javascript:`, `vbscript:` and `data:`
+//     hrefs, so a link in model output cannot become script in the reader's client.
+//   - `breaks: true` — single newlines are `<br>`, matching how the body is written
+//     (answer, then our fixed footer) instead of reflowing it into one paragraph.
+//
+// Dependency cost is markdown-it plus six small transitive packages (entities,
+// linkify-it, mdurl, argparse, uc.micro, punycode.js), all from the same maintainers.
+import MarkdownIt from "markdown-it";
+const md = new MarkdownIt({
+    html: false,
+    linkify: true,
+    breaks: true,
+    typographer: false,
+});
+// --- email-safe styling ------------------------------------------------------
+//
+// markdown-it emits bare tags. Mail clients default to *no* table borders, so a table
+// arrived as loose text; and a `<style>` block is stripped by several clients. Inline
+// styles on each cell are what survive that, so the rendering rules are overridden
+// rather than the output being post-processed.
+const CELL_BORDER = "border:1px solid #c8ccd1";
+/**
+ * Merge our style with any attributes markdown-it already set (alignment, mostly).
+ * `attrs` is typed loosely because @types/markdown-it uses its own TokenAttribute
+ * shape; it is always a list of name/value pairs at runtime.
+ */
+function styledTag(name, rawAttrs, extra) {
+    const pairs = Array.isArray(rawAttrs) ? rawAttrs : [];
+    const attrs = new Map(pairs);
+    const existing = attrs.get("style");
+    attrs.set("style", existing ? `${existing};${extra}` : extra);
+    // cellspacing/cellpadding are attributes, not CSS, and survive sanitising better.
+    const rendered = [...attrs].map(([key, value]) => ` ${key}="${md.utils.escapeHtml(value)}"`).join("");
+    return `<${name}${rendered}>`;
+}
+md.renderer.rules.table_open = () => '<table cellspacing="0" cellpadding="0" style="border-collapse:collapse;margin:10px 0;font-size:13px">';
+md.renderer.rules.th_open = (tokens, idx) => styledTag("th", tokens[idx]?.attrs, `${CELL_BORDER};padding:6px 10px;background:#f2f4f7;text-align:left`);
+md.renderer.rules.td_open = (tokens, idx) => styledTag("td", tokens[idx]?.attrs, `${CELL_BORDER};padding:6px 10px`);
+const MONO = "font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace";
+md.renderer.rules.fence = (tokens, idx) => {
+    const token = tokens[idx];
+    const language = token.info.trim().split(/\s+/)[0] ?? "";
+    const cls = language ? ` class="language-${md.utils.escapeHtml(language)}"` : "";
+    return (`<pre style="background:#f6f8fa;${CELL_BORDER};border-radius:4px;padding:10px;overflow:auto;${MONO};font-size:13px">` +
+        `<code${cls}>${md.utils.escapeHtml(token.content)}</code></pre>`);
+};
+md.renderer.rules.code_inline = (tokens, idx) => `<code style="background:#f2f4f7;border-radius:3px;padding:1px 4px;${MONO};font-size:13px">${md.utils.escapeHtml(tokens[idx].content)}</code>`;
+/** Inline Markdown (no block structure). */
+export function renderInline(text) {
+    return md.renderInline(text);
+}
+/** Block Markdown as HTML, trimmed so callers can concatenate it. */
+export function renderMarkdown(text) {
+    return md.render(text).trim();
+}
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
+/** The RFC 3676 signature delimiter, which our own body uses before its metadata. */
+const FOOTER_SPLIT = /^--$/m;
+/**
+ * Render an outbound body: Markdown above the `--` delimiter, literal text below it.
+ *
+ * The footer is deliberately not Markdown. A line of `--` after a text line is a setext
+ * heading underline, so rendering it would swallow our metadata into an `<h2>`.
+ */
+export function renderBody(text) {
+    const index = text.search(FOOTER_SPLIT);
+    if (index === -1)
+        return renderMarkdown(text);
+    const head = text.slice(0, index);
+    const tailLines = text.slice(index).split("\n");
+    // The `--` line itself is dropped in HTML: the top border is the divider there. It
+    // stays in the text part, where RFC 3676 needs it and quote stripping relies on it.
+    const tail = (tailLines[0]?.trim() === "--" ? tailLines.slice(1) : tailLines).join("\n");
+    // A visible divider, but literal text: rendering `--` as Markdown would make it a
+    // setext heading underline and swallow the body above it.
+    const signatureStyle = "font:inherit;opacity:.75;margin:18px 0 0;padding-top:10px;border-top:1px solid #d8dee4";
+    return `${renderMarkdown(head)}\n<pre class="signature" style="${signatureStyle}">${escapeHtml(tail)}</pre>`;
+}