@engenty/wizards-runtime 0.0.0-stage → 0.7.6

package/apps/runtime/dist/tools/connector.js

@@ -0,0 +1,204 @@
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+import { refreshConnector, resolveConnector } from "../connectors/external.js";
+import { connectionContext } from "../connectors/index.js";
+import { attempt, clip } from "./shared.js";
+import { resolveFile } from "./store.js";
+const FILE_NOTE = " File content never passes through you: returned content is kept as a file and you get its path; to send a kept file, give `file:<path>` where an input asks for `*_base64`.";
+/** Above this many actions a connector is offered as "find an action, then call it". */
+const DIRECT_TOOLS = 24;
+const TOOL_NAME = /^[a-zA-Z0-9_-]{1,64}$/;
+/**
+ * The actions of imported connectors a step may use, as tools. Reading is free; anything that
+ * changes the person's account waits for their yes — engenty's default policy for connectors
+ * (read: allow, write and destructive: ask), asked of the person who is running the wizard.
+ */
+export async function connectorTools(step, ctx, files) {
+    const tools = {};
+    const connections = (ctx.def.connections ?? []).filter((c) => c.connector && step.connections?.includes(c.id));
+    for (const connection of connections) {
+        Object.assign(tools, await toolsOf(connection, ctx, files));
+    }
+    return tools;
+}
+const MAGIC = [
+    ["%PDF", "application/pdf", "pdf"],
+    ["\x89PNG", "image/png", "png"],
+    ["\xff\xd8\xff", "image/jpeg", "jpg"],
+    ["GIF8", "image/gif", "gif"],
+    ["PK\x03\x04", "application/zip", "zip"],
+];
+/** What a file is, by its first bytes — connectors often hand over content without a name. */
+function sniff(data) {
+    const head = data.subarray(0, 8).toString("latin1");
+    const hit = MAGIC.find(([magic]) => head.startsWith(magic));
+    return hit ? { mime: hit[1], ext: hit[2] } : null;
+}
+/**
+ * A model cannot carry a file: content an action returns as base64 is kept in the wizard's
+ * files and the result names the path instead.
+ */
+async function keepContent(result, action, service, files) {
+    if (!result || typeof result !== "object" || Array.isArray(result)) {
+        return result;
+    }
+    const out = { ...result };
+    for (const [key, value] of Object.entries(out)) {
+        if (!key.endsWith("_base64") || typeof value !== "string" || !value) {
+            continue;
+        }
+        const data = Buffer.from(value, "base64");
+        const kind = sniff(data);
+        const given = [out.name, out.filename, out.file_name].find((v) => typeof v === "string" && v.length > 0);
+        const name = given ?? `${action.id}-${Date.now().toString(36)}.${kind?.ext ?? "bin"}`;
+        const declared = [out.mime_type, out.mimeType, out.content_type].find((v) => typeof v === "string");
+        const kept = await files.keep(`${service}/${name}`, data, {
+            mime: declared ?? kind?.mime,
+            source: `${service}: ${action.summary || action.id}`,
+        });
+        delete out[key];
+        out.saved = kept.path;
+        out.note = "The content is kept as a file; read it with read_document.";
+    }
+    return out;
+}
+/** The other way round: `file:<path>` in a `*_base64` input sends a kept file or an upload. */
+async function sendContent(input, ctx) {
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+        return input;
+    }
+    const out = { ...input };
+    for (const [key, value] of Object.entries(out)) {
+        if (key.endsWith("_base64") && typeof value === "string" && value.startsWith("file:")) {
+            const file = await resolveFile(ctx, value.slice("file:".length));
+            out[key] = Buffer.from(file.data).toString("base64");
+        }
+    }
+    return out;
+}
+/**
+ * Whether the person is asked before an action runs. The wizard's author can settle it per
+ * action (a server may call a plain lookup a change); deleting is never taken off the person.
+ */
+function asks(connection, action) {
+    if (action.group === "destructive") {
+        return true;
+    }
+    return (connection.policy?.[action.id] ?? (action.group === "read" ? "allow" : "ask")) === "ask";
+}
+async function toolsOf(connection, ctx, files) {
+    const projectId = ctx.project.id;
+    const id = connection.connector ?? "";
+    let resolved = await resolveConnector(projectId, id);
+    if (!resolved) {
+        return {};
+    }
+    const account = () => connectionContext(ctx.store, connection, projectId);
+    // An MCP server that lists its tools only to a signed-in account: ask it now that there is one.
+    if (resolved.imported && !resolved.connector.actions.length) {
+        const found = await account();
+        if (found) {
+            await refreshConnector(projectId, id, found.ctx.accessToken).catch(() => undefined);
+            resolved = (await resolveConnector(projectId, id)) ?? resolved;
+        }
+    }
+    const { connector, inputSchema } = resolved;
+    const usable = connection.actions
+        ? connector.actions.filter((a) => connection.actions?.includes(a.id))
+        : connector.actions.filter((a) => a.group === "read");
+    const service = connection.title ?? connector.name;
+    const call = (action, input) => attempt(async () => {
+        const found = await account();
+        if (!found) {
+            return {
+                error: `The person has not connected ${service}. Go on without it and say so in your result.`,
+            };
+        }
+        const key = `${connection.id}:${action.id}`;
+        if (asks(connection, action) && !ctx.resources.allowed.has(key)) {
+            const answer = await ctx.ask({
+                kind: "confirm",
+                reason: action.summary || action.id,
+                service,
+                action: {
+                    id: action.id,
+                    summary: action.summary,
+                    destructive: action.group === "destructive",
+                },
+                input: JSON.stringify(input ?? {}, null, 2).slice(0, 4000),
+            });
+            if (!answer) {
+                return {
+                    error: "Nobody is there to allow this change, so it was not made. Report it as open in your result.",
+                };
+            }
+            if (answer.type !== "done") {
+                return {
+                    error: "The person did not allow this change. Do not try it again; say in your result that it was not made.",
+                };
+            }
+            if (answer.remember) {
+                ctx.resources.allowed.add(key);
+            }
+        }
+        await ctx.emit("tool", `${service}: ${action.summary || action.id}`.slice(0, 120));
+        const result = await keepContent(await action.handler(await sendContent(input ?? {}, ctx), found.ctx), action, service, files);
+        const text = typeof result === "string" ? result : JSON.stringify(result);
+        return { result: clip(text ?? "", 8000) };
+    });
+    const prefix = connector.toolPrefix;
+    const direct = usable.length <= DIRECT_TOOLS && usable.every((a) => TOOL_NAME.test(`${prefix}_${a.id}`));
+    if (direct) {
+        return Object.fromEntries(usable.map((action) => [
+            `${prefix}_${action.id}`,
+            createTool({
+                id: `${prefix}_${action.id}`,
+                description: `${service}: ${action.description || action.summary}${asks(connection, action) ? " — the person is asked before this runs." : ""}${FILE_NOTE}`.slice(0, 1100),
+                inputSchema: action.inputSchema,
+                execute: (input) => call(action, input),
+            }),
+        ]));
+    }
+    return {
+        [`${prefix}_actions`]: createTool({
+            id: `${prefix}_actions`,
+            description: `${service} offers ${usable.length} actions. Find the ones you need by words from their name or purpose; you get each action's id, what it does and its input. Then call ${prefix}_call.`,
+            inputSchema: z.object({
+                query: z.string().describe("Words to look for, e.g. 'search pages' or 'invoice list'."),
+            }),
+            execute: ({ query }) => attempt(async () => {
+                const words = query.toLowerCase().split(/\s+/).filter(Boolean);
+                const scored = usable
+                    .map((a) => {
+                    const text = `${a.id} ${a.summary} ${a.description}`.toLowerCase();
+                    return { a, score: words.filter((w) => text.includes(w)).length };
+                })
+                    .filter((x) => x.score > 0)
+                    .sort((x, y) => y.score - x.score)
+                    .slice(0, 12);
+                return {
+                    actions: scored.map(({ a }) => ({
+                        id: a.id,
+                        does: a.summary || a.description.slice(0, 200),
+                        asks_person_first: asks(connection, a),
+                        input: inputSchema(a.id),
+                    })),
+                };
+            }),
+        }),
+        [`${prefix}_call`]: createTool({
+            id: `${prefix}_call`,
+            description: `Run one ${service} action found with ${prefix}_actions. Some wait for the person's yes first.${FILE_NOTE}`,
+            inputSchema: z.object({
+                action: z.string(),
+                input: z.record(z.string(), z.unknown()).optional(),
+            }),
+            execute: ({ action: id, input }) => {
+                const action = usable.find((a) => a.id === id);
+                return action
+                    ? call(action, input)
+                    : Promise.resolve({ error: `No action "${id}". Use ${prefix}_actions to find one.` });
+            },
+        }),
+    };
+}

package/apps/runtime/dist/tools/index.js

@@ -0,0 +1,291 @@
+import { anthropic } from "@ai-sdk/anthropic";
+import { isTextMime } from "@engenty-wizards/shared/workspace";
+import { createTool } from "@mastra/core/tools";
+import { MCPClient } from "@mastra/mcp";
+import { z } from "zod";
+import { documentMime, parseDocument } from "../documents/parse.js";
+import { generateImageMedia } from "../media/generate.js";
+import { markMedia } from "../media/marking.js";
+import { gatewayTools, isHarnessVendor } from "../models.js";
+import { htmlToMarkdown } from "../render/convert.js";
+import { sandboxCapabilities, shellToolDescription } from "../sandbox/index.js";
+import { snapshotFile } from "../services/files.js";
+import { hasStoreFiles } from "../store/index.js";
+import { browserTools } from "./browser.js";
+import { connectorTools } from "./connector.js";
+import { mailTools } from "./mail.js";
+import { assertPublicUrl, safeFetch } from "./net-guard.js";
+import { pageTools } from "./pages.js";
+import { pluginTools, spaceContextOf } from "./plugin.js";
+import { projectTools } from "./project.js";
+import { clip, FileKeeper } from "./shared.js";
+import { storeTools } from "./store.js";
+/**
+ * Whether a fetched body is text a model can read: a text type, or no type and next to no
+ * bytes that only decode as replacement or control characters.
+ */
+function isReadable(type, body) {
+    if (isTextMime(type) ||
+        type.includes("html") ||
+        type.includes("xml") ||
+        type.includes("json") ||
+        type.includes("javascript")) {
+        return true;
+    }
+    if (type && type !== "application/octet-stream") {
+        return false;
+    }
+    const sample = body.slice(0, 4000);
+    let odd = 0;
+    for (let i = 0; i < sample.length; i++) {
+        const code = sample.charCodeAt(i);
+        if (code === 0xfffd || code < 0x09 || (code > 0x0d && code < 0x20)) {
+            odd++;
+        }
+    }
+    return odd <= sample.length * 0.01;
+}
+/**
+ * Whether a step has no use for the wizard's store: it declares no tools and no connections,
+ * got no uploads, and the wizard keeps no lists. Its files may still be there (`buildStepTools`).
+ */
+export function storeIdle(step, lists, uploads) {
+    return step.tools.length === 0 && !step.connections?.length && lists === 0 && uploads === 0;
+}
+/** The tools an agent step may use: exactly what its definition allowlists. */
+export async function buildStepTools(step, ctx, resolved, uploads) {
+    const tools = {};
+    const assets = [];
+    const allowed = new Set(step.tools);
+    let mcp = null;
+    if (allowed.has("web_search")) {
+        // Anthropic models search natively; other models search through the AI Gateway's tool.
+        if (resolved.vendor === "anthropic") {
+            tools.web_search = anthropic.tools.webSearch_20250305({ maxUses: 8 });
+        }
+        else if (isHarnessVendor(resolved.vendor)) {
+            // An installed client searches with its own tool; naming it here switches it on.
+            tools.web_search = createTool({
+                id: "web_search",
+                description: "Search the web.",
+                inputSchema: z.object({ query: z.string() }),
+                execute: async () => ({ error: "The client searches itself." }),
+            });
+        }
+        else if (resolved.gateway) {
+            tools.web_search = gatewayTools.perplexitySearch({ maxResults: 8 });
+        }
+    }
+    if (allowed.has("web_fetch") || allowed.has("web_search")) {
+        tools.web_fetch = createTool({
+            id: "web_fetch",
+            description: "Fetch a public web page or file and return its readable text (Markdown).",
+            inputSchema: z.object({ url: z.string().describe("Absolute http(s) URL") }),
+            execute: async ({ url }) => {
+                const safe = await assertPublicUrl(url);
+                await ctx.emit("tool", { code: "reads", params: { name: safe.hostname } });
+                const res = await safeFetch(safe.toString(), {
+                    signal: AbortSignal.any([ctx.signal, AbortSignal.timeout(20_000)]),
+                    headers: { "user-agent": "Mozilla/5.0 (compatible; engenty-wizards/0.1)" },
+                });
+                const type = (res.headers.get("content-type") ?? "").split(";")[0].trim().toLowerCase();
+                const data = new Uint8Array(await res.arrayBuffer());
+                const name = new URL(res.url || safe.toString()).pathname.split("/").pop() || "download";
+                const mime = documentMime(name, type);
+                // A PDF or Word file is read by its own text; an image or other bytes are not text at all.
+                if (mime === "application/pdf" || mime.includes("word")) {
+                    const doc = await parseDocument({ data, name, mime }, { charge: (usd) => ctx.chargeUsd(usd), signal: ctx.signal, call: ctx.call }).catch(() => null);
+                    return doc
+                        ? { status: res.status, url: res.url, content: clip(doc.markdown) }
+                        : { status: res.status, url: res.url, error: `The ${mime} file could not be read.` };
+                }
+                const body = new TextDecoder().decode(data);
+                if (!isReadable(type, body)) {
+                    return {
+                        status: res.status,
+                        url: res.url,
+                        type: type || "unknown",
+                        bytes: data.length,
+                        note: type.startsWith("image/")
+                            ? "An image, not a page: the address works. Its bytes are not text and are not shown."
+                            : "Not a text page: its bytes are not shown.",
+                    };
+                }
+                const text = type.includes("html") ? htmlToMarkdown(body) : body;
+                return { status: res.status, url: res.url, content: clip(text) };
+            },
+        });
+    }
+    if (allowed.has("http")) {
+        tools.http_request = createTool({
+            id: "http_request",
+            description: "Call a public HTTP API. Use for REST endpoints the instructions name.",
+            inputSchema: z.object({
+                method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]).default("GET"),
+                url: z.string(),
+                headers: z.record(z.string(), z.string()).optional(),
+                json: z.unknown().optional().describe("JSON body"),
+            }),
+            execute: async ({ method, url, headers, json }) => {
+                const safe = await assertPublicUrl(url);
+                await ctx.emit("tool", `${method} ${safe.hostname}${safe.pathname}`);
+                const res = await safeFetch(safe.toString(), {
+                    method,
+                    signal: AbortSignal.any([ctx.signal, AbortSignal.timeout(30_000)]),
+                    headers: {
+                        ...(json !== undefined ? { "content-type": "application/json" } : {}),
+                        ...headers,
+                    },
+                    body: json !== undefined ? JSON.stringify(json) : undefined,
+                });
+                return { status: res.status, body: clip(await res.text(), 8000) };
+            },
+        });
+    }
+    const files = new FileKeeper(ctx, assets);
+    if (allowed.has("browser")) {
+        Object.assign(tools, await browserTools(ctx, assets, files));
+    }
+    // The wizard's lists and files, the documents the person gave and the project's documents are
+    // always at hand. An installed client gets tools over an MCP bridge its CLI starts for every
+    // call, seconds of its own: a step with no use for the store goes without its tools, and
+    // without others (Knowledge, a workspace file) the client answers without the bridge.
+    const idle = isHarnessVendor(resolved.vendor) &&
+        storeIdle(step, ctx.def.lists?.length ?? 0, uploads.length) &&
+        !(await hasStoreFiles(ctx.store));
+    if (!idle) {
+        Object.assign(tools, storeTools(ctx, uploads, files));
+    }
+    Object.assign(tools, await projectTools(ctx));
+    Object.assign(tools, mailTools(step, ctx, files));
+    Object.assign(tools, await connectorTools(step, ctx, files));
+    Object.assign(tools, await pluginTools(step, ctx));
+    Object.assign(tools, (await spaceContextOf(ctx)).tools);
+    if (allowed.has("pages")) {
+        Object.assign(tools, pageTools(ctx));
+    }
+    const sandbox = sandboxCapabilities();
+    if (allowed.has("sandbox") && sandbox) {
+        const timeoutMs = (seconds) => Math.min((seconds ?? 120) * 1000, 600_000);
+        const report = (result) => ({
+            exitCode: result.exitCode,
+            stdout: clip(result.stdout, 8000),
+            stderr: clip(result.stderr, 4000),
+        });
+        tools.run_command = createTool({
+            id: "run_command",
+            description: shellToolDescription(sandbox),
+            inputSchema: z.object({ command: z.string(), timeoutSeconds: z.number().optional() }),
+            execute: async ({ command, timeoutSeconds }) => {
+                await ctx.emit("tool", { code: "runs", params: { command: command.slice(0, 80) } });
+                return report(await ctx.resources
+                    .sandboxHandle()
+                    .exec(command, { timeoutMs: timeoutMs(timeoutSeconds) }));
+            },
+        });
+        tools.export_file = createTool({
+            id: "export_file",
+            description: "Hand a file from the sandbox to the person as a result (e.g. a chart PNG, a CSV).",
+            inputSchema: z.object({
+                path: z.string(),
+                mime: z.string().describe("e.g. image/png, text/csv"),
+            }),
+            execute: async ({ path, mime }) => {
+                let bytes;
+                try {
+                    bytes = await ctx.resources.sandboxHandle().readFile(path);
+                }
+                catch (err) {
+                    return { error: err.message || "file not found" };
+                }
+                const ref = await ctx.saveAsset({
+                    kind: mime.startsWith("image/") ? "image" : "file",
+                    mime,
+                    name: path.split("/").pop() ?? "file",
+                    data: Buffer.from(bytes),
+                });
+                assets.push(ref);
+                return { saved: true, assetId: ref.id };
+            },
+        });
+    }
+    if (allowed.has("image")) {
+        tools.generate_image = createTool({
+            id: "generate_image",
+            description: "Draw an image from a detailed visual prompt. The image is shown to the person.",
+            inputSchema: z.object({
+                prompt: z.string(),
+                aspectRatio: z.enum(["1:1", "16:9", "9:16", "4:5", "3:2", "2:3"]).optional(),
+            }),
+            execute: async ({ prompt, aspectRatio }) => {
+                await ctx.emit("tool", { code: "drawing" });
+                const media = await generateImageMedia({
+                    call: ctx.call,
+                    prompt,
+                    aspectRatio,
+                    abortSignal: ctx.signal,
+                });
+                await ctx.chargeUsd(media.costUsd);
+                const ref = await ctx.saveAsset({
+                    kind: "image",
+                    mime: media.mime,
+                    name: "image.png",
+                    data: markMedia(media.bytes, media.mime, { origin: "generated", system: media.system }),
+                    ai: "generated",
+                });
+                assets.push(ref);
+                return { saved: true, assetId: ref.id };
+            },
+        });
+    }
+    // The wizard's workspace (reference data, price lists, templates) is always readable.
+    if (ctx.files.length) {
+        tools.read_workspace_file = createTool({
+            id: "read_workspace_file",
+            description: `Read a file from the wizard's workspace. Files: ${ctx.files
+                .slice(0, 60)
+                .map((f) => f.path)
+                .join(", ")}`,
+            inputSchema: z.object({ path: z.string() }),
+            execute: async ({ path }) => {
+                const found = await snapshotFile(ctx.files, path);
+                if (!found) {
+                    return { error: `No file ${path}` };
+                }
+                return isTextMime(found.file.mime)
+                    ? { path, text: clip(found.data.toString("utf8"), 40_000) }
+                    : { path, mime: found.file.mime, size: found.file.size, note: "binary file" };
+            },
+        });
+    }
+    const servers = ctx.project.mcpServers.filter((s) => step.mcp?.includes(s.id));
+    if (servers.length) {
+        mcp = new MCPClient({
+            id: `run-${ctx.runId}-${step.id}`,
+            servers: Object.fromEntries(servers.map((s) => [
+                s.id,
+                { url: new URL(s.url), requestInit: { headers: s.headers ?? {} }, timeout: 60_000 },
+            ])),
+        });
+        try {
+            Object.assign(tools, await mcp.listTools());
+            await ctx.emit("tool", {
+                code: "mcpConnected",
+                params: { names: servers.map((s) => s.name).join(", ") },
+            });
+        }
+        catch (err) {
+            await ctx.emit("info", {
+                code: "mcpUnreachable",
+                params: { detail: err.message },
+            });
+        }
+    }
+    return {
+        tools,
+        assets,
+        close: async () => {
+            await mcp?.disconnect().catch(() => undefined);
+        },
+    };
+}

package/apps/runtime/dist/tools/mail.js

@@ -0,0 +1,104 @@
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+import { connectionContext } from "../connectors/index.js";
+import { mailAction, mailSearchInput, } from "../connectors/mail.js";
+import { escapeHtml, htmlToPdf } from "../render/convert.js";
+import { guardHtml } from "../render/guard.js";
+import { attempt, clip } from "./shared.js";
+const NOT_CONNECTED = "The person has not connected a mailbox. Go on without mail and say in your result that the mailbox is not connected.";
+/**
+ * Read-only mail for a step that names a mail connection. The tools are the same whichever
+ * provider the person connected; attachments never pass through the model — they are saved.
+ */
+export function mailTools(step, ctx, files) {
+    const connection = (ctx.def.connections ?? []).find((c) => c.kind === "mail" && step.connections?.includes(c.id));
+    if (!connection) {
+        return {};
+    }
+    const open = async () => {
+        const found = await connectionContext(ctx.store, connection, ctx.project.id);
+        if (!found) {
+            throw new Error(NOT_CONNECTED);
+        }
+        return found;
+    };
+    const tools = {};
+    tools.mail_search = createTool({
+        id: "mail_search",
+        description: "Search the person's mailbox (read-only), newest first. Returns id, date, sender, subject, snippet and attachments (id, name, size) of each mail. Search broadly with several terms at once rather than one call per word.",
+        inputSchema: mailSearchInput,
+        execute: (input) => attempt(async () => {
+            const { connector, ctx: actionCtx, label } = await open();
+            await ctx.emit("tool", { code: "searchesMail", params: { label } });
+            const { mails } = await mailAction(connector, "search", input, actionCtx);
+            return {
+                mailbox: label,
+                total: mails.length,
+                mails: mails.map((m) => ({ ...m, snippet: m.snippet.slice(0, 200) })),
+            };
+        }),
+    });
+    tools.mail_read = createTool({
+        id: "mail_read",
+        description: "Read one mail in full: sender, recipients, text, attachments.",
+        inputSchema: z.object({ id: z.string() }),
+        execute: ({ id }) => attempt(async () => {
+            const { connector, ctx: actionCtx } = await open();
+            const mail = await mailAction(connector, "read", { id }, actionCtx);
+            const { html: _html, ...rest } = mail;
+            return { ...rest, text: clip(mail.text, 6000) };
+        }),
+    });
+    tools.mail_save = createTool({
+        id: "mail_save",
+        description: "Keep mail attachments (invoice PDFs) as files, several at once: each is stored under `path` in the wizard's files and added to this step's result. Leave attachment_id out to keep the mail itself as a PDF — for receipts that only exist as mail text. Then read them with scan_documents or read_document.",
+        inputSchema: z.object({
+            items: z
+                .array(z.object({
+                id: z.string().describe("Mail id from mail_search."),
+                attachment_id: z.string().optional(),
+                path: z.string().describe("e.g. invoices/2026-09/2026-09-03_Notion_INV-123.pdf"),
+            }))
+                .min(1)
+                .max(40),
+        }),
+        execute: ({ items }) => attempt(async () => {
+            const { connector, ctx: actionCtx, label } = await open();
+            await ctx.emit("tool", {
+                code: "savesReceipts",
+                params: { count: items.length, label },
+            });
+            const saved = [];
+            for (const item of items) {
+                try {
+                    if (item.attachment_id) {
+                        const a = await mailAction(connector, "get_attachment", { id: item.id, attachment_id: item.attachment_id }, actionCtx);
+                        const kept = await files.keep(item.path, Buffer.from(a.data_base64, "base64"), {
+                            mime: a.mime,
+                            source: `E-Mail-Anhang „${a.name}“ aus ${label}`,
+                        });
+                        saved.push({ id: item.id, saved: kept.path, size: kept.size });
+                    }
+                    else {
+                        const mail = await mailAction(connector, "read", { id: item.id }, actionCtx);
+                        const page = mail.html ??
+                            `<pre style="white-space:pre-wrap;font:14px system-ui">${escapeHtml(mail.text)}</pre>`;
+                        const head = `<div style="font:13px system-ui;color:#444;border-bottom:1px solid #ddd;padding-bottom:8px;margin-bottom:12px">${escapeHtml(mail.from ?? "")}<br>${escapeHtml(mail.date ?? "")}<br><b>${escapeHtml(mail.subject ?? "")}</b></div>`;
+                        // The mail's own HTML is rendered offline: its remote images and scripts never load.
+                        const pdf = await htmlToPdf(guardHtml(`<!doctype html><html><body>${head}${page}</body></html>`));
+                        const kept = await files.keep(item.path.replace(/(\.pdf)?$/i, ".pdf"), pdf, {
+                            mime: "application/pdf",
+                            source: `E-Mail „${mail.subject ?? ""}“ aus ${label}`,
+                        });
+                        saved.push({ id: item.id, saved: kept.path, size: kept.size });
+                    }
+                }
+                catch (err) {
+                    saved.push({ id: item.id, error: String(err.message).slice(0, 200) });
+                }
+            }
+            return { saved };
+        }),
+    });
+    return tools;
+}