@bli-cockpit/mcp 0.1.85 → 0.1.86

package/dist/mail-attachments.d.ts

@@ -0,0 +1,57 @@
+export declare const MAIL_ATTACHMENT_MAX_COUNT = 10;
+export declare const MAIL_ATTACHMENTS_MAX_TOTAL_BYTES = 3000000;
+/** The whole JSON request, under Vercel's 4.5 MB function-body cap with room for the headers. */
+export declare const MAIL_REQUEST_MAX_BYTES = 4400000;
+export declare const MAIL_ATTACHMENT_CONTENT_TYPES: Readonly<Record<string, string>>;
+/**
+ * A name a person almost never means to email: the repo's own secret-name rule
+ * (`isSecretLikePathSegment`, the one `notes upload` uses: `.env*`, anything with
+ * secret, credential, private_key or service_role in it), with `.env.example`
+ * let through (a template, no values), plus the private-key names that rule does
+ * not know: id_rsa and its siblings, `*.pem`, `*.key`.
+ */
+export declare function attachmentLooksSecret(fileName: string): boolean;
+/** The type a file name's extension says it is. Case-insensitive; anything unknown is octet-stream. */
+export declare function mailAttachmentContentType(fileName: string): string;
+/** One file as the send and draft doors take it. */
+export interface WireMailAttachment {
+    filename: string;
+    content_type: string;
+    content_base64: string;
+}
+/** What may be said about the files in a result or a log: counts, sizes and types. Never a name. */
+export interface MailAttachmentSummary {
+    count: number;
+    bytes: number;
+    sizes: number[];
+    content_types: string[];
+}
+export type MailAttachmentRefusal = "too_many_attachments" | "attachment_unreadable" | "attachment_too_large" | "attachment_secret_like" | "attachments_unavailable_hosted";
+export type ReadMailAttachmentsResult = {
+    ok: true;
+    attachments: WireMailAttachment[];
+    summary: MailAttachmentSummary;
+} | {
+    ok: false;
+    reason: MailAttachmentRefusal;
+    detail: string;
+};
+/**
+ * Reads every `{ path }`, or says which one cannot go and why. Never throws.
+ * Hosted first (no disk, no stat), then the count, each file's `stat`, the
+ * total, and only then the bytes.
+ */
+export declare function readMailAttachments(entries: ReadonlyArray<{
+    path: string;
+}> | undefined): Promise<ReadMailAttachmentsResult>;
+/** The second check: the whole request, not just the files. Called with the JSON about to be posted. */
+export declare function mailRequestFits(body: unknown): {
+    ok: true;
+    bytes: number;
+} | {
+    ok: false;
+    reason: MailAttachmentRefusal;
+    detail: string;
+};
+/** The sentence a result adds after a send or a draft that carried files. */
+export declare function attachmentSentence(summary: MailAttachmentSummary): string;

package/dist/mail-attachments.js

@@ -0,0 +1,181 @@
+/**
+ * `attachments: [{ path }]` for `mail_send` and `mail_draft` (BLI-12661): read
+ * the files on the machine THIS server runs on, screen them, and turn them into
+ * the `attachments` the two doors take. The twin of the CLI's
+ * `commands/mail-attachments.ts` in `@bli-cockpit/local-collector`, copied here
+ * because this package depends on neither that one nor the CLI (the same call
+ * `agent-door-session.ts` and `notes-write-tools.ts` made for the session file
+ * and the note reader). `mail-attachment-parity.test.ts` fails when the caps or
+ * the content-type table drift from the CLI's copy.
+ *
+ * **A hosted server never reads a path.** The same `createServer` answers the
+ * stdio bin on a person's laptop AND the hosted `/api/mcp` for ChatGPT, dot and
+ * claude.ai, and on the hosted one a path names a file on the HOST, not on the
+ * caller's computer: reading it would mail the host's own files to whoever was
+ * asked for. `notes_upload` and `sources_check` are left out of the hosted list
+ * for exactly this (`REMOTE_EXCLUDED_TOOLS`); `mail_send` and `mail_draft` must
+ * stay on it, so the one argument that names a path is refused there, by name,
+ * BEFORE the disk is touched: `attachments_unavailable_hosted`. Detected the way
+ * everything hosted is, by the request scope (`inRemoteAgentDoorScope`), so a
+ * future hosted entry point cannot forget to switch it on. The caller is told
+ * where to attach a file instead (the laptop server, or `cockpit mail ... --attach`).
+ *
+ * Everything else is the CLI's rule, in the same words (a refusal names a file
+ * by position and an error code, never by path or name): the count, then each
+ * file's `stat`, then the total, and only then a byte read; a refusal is a named
+ * reason with its numbers; the server holds the same caps again. See the CLI
+ * module for why 3,000,000 bytes (Vercel's 4.5 MB request cap, base64 a third
+ * bigger than the file).
+ */
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { isSecretLikePathSegment } from "@bli-cockpit/telemetry-core";
+import { inRemoteAgentDoorScope } from "./agent-door-session.js";
+export const MAIL_ATTACHMENT_MAX_COUNT = 10;
+export const MAIL_ATTACHMENTS_MAX_TOTAL_BYTES = 3_000_000;
+/** The whole JSON request, under Vercel's 4.5 MB function-body cap with room for the headers. */
+export const MAIL_REQUEST_MAX_BYTES = 4_400_000;
+// BEGIN content types: identical in packages/cockpit-local-collector/src/commands/mail-attachments.ts
+export const MAIL_ATTACHMENT_CONTENT_TYPES = {
+    docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    doc: "application/msword",
+    xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    xls: "application/vnd.ms-excel",
+    pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    ppt: "application/vnd.ms-powerpoint",
+    pdf: "application/pdf",
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    webp: "image/webp",
+    txt: "text/plain",
+    csv: "text/csv",
+    md: "text/markdown",
+    json: "application/json",
+    html: "text/html",
+    rtf: "application/rtf",
+    zip: "application/zip",
+};
+// END content types
+// BEGIN secret-like names: identical in the CLI and MCP mail-attachments.ts
+/**
+ * A name a person almost never means to email: the repo's own secret-name rule
+ * (`isSecretLikePathSegment`, the one `notes upload` uses: `.env*`, anything with
+ * secret, credential, private_key or service_role in it), with `.env.example`
+ * let through (a template, no values), plus the private-key names that rule does
+ * not know: id_rsa and its siblings, `*.pem`, `*.key`.
+ */
+export function attachmentLooksSecret(fileName) {
+    if (/^\.env\.example$/i.test(fileName))
+        return false;
+    return isSecretLikePathSegment(fileName) || /^id_(rsa|dsa|ecdsa|ed25519)$/i.test(fileName) || /\.(pem|key)$/i.test(fileName);
+}
+// END secret-like names
+const FALLBACK_CONTENT_TYPE = "application/octet-stream";
+/** The type a file name's extension says it is. Case-insensitive; anything unknown is octet-stream. */
+export function mailAttachmentContentType(fileName) {
+    const extension = path.extname(fileName).slice(1).toLowerCase();
+    return MAIL_ATTACHMENT_CONTENT_TYPES[extension] ?? FALLBACK_CONTENT_TYPE;
+}
+const NOTHING_SENT = "Nothing was sent.";
+function refuse(reason, detail) {
+    return { ok: false, reason, detail };
+}
+function bytesLabel(count) {
+    return `${count.toLocaleString("en-US")} byte${count === 1 ? "" : "s"}`;
+}
+function totalTooLarge(total) {
+    if (total <= MAIL_ATTACHMENTS_MAX_TOTAL_BYTES)
+        return null;
+    return refuse("attachment_too_large", `The attachments come to ${bytesLabel(total)} and one message carries at most ${bytesLabel(MAIL_ATTACHMENTS_MAX_TOTAL_BYTES)} `
+        + "(about 3 MB: the most one request to Tower holds once the files are encoded). "
+        + `Share a link for anything bigger. ${NOTHING_SENT}`);
+}
+/**
+ * Reads every `{ path }`, or says which one cannot go and why. Never throws.
+ * Hosted first (no disk, no stat), then the count, each file's `stat`, the
+ * total, and only then the bytes.
+ */
+export async function readMailAttachments(entries) {
+    const paths = (entries ?? []).map((entry) => entry.path);
+    if (paths.length === 0)
+        return { ok: true, attachments: [], summary: { count: 0, bytes: 0, sizes: [], content_types: [] } };
+    if (inRemoteAgentDoorScope()) {
+        return refuse("attachments_unavailable_hosted", "This is the hosted Tower server: a path would name a file on the server, not on your computer, so no file was read and nothing was attached. "
+            + "Attach files with the local bli-tower server (`cockpit doctor` registers it) or with `cockpit mail send|draft --attach <path>`. "
+            + NOTHING_SENT);
+    }
+    if (paths.length > MAIL_ATTACHMENT_MAX_COUNT) {
+        return refuse("too_many_attachments", `${paths.length} files were attached and one message carries at most ${MAIL_ATTACHMENT_MAX_COUNT}. ${NOTHING_SENT}`);
+    }
+    // Names first, before a single stat or read: a secret-looking file is never opened.
+    const secret = paths.findIndex((filePath) => attachmentLooksSecret(path.basename(filePath)));
+    if (secret !== -1) {
+        return refuse("attachment_secret_like", `Attachment ${secret + 1} has a name that looks like a key or credential file, so it was not opened. ${NOTHING_SENT}`);
+    }
+    const sizes = [];
+    for (const [index, filePath] of paths.entries()) {
+        const label = `Attachment ${index + 1}`;
+        let size;
+        try {
+            const info = await stat(filePath);
+            if (!info.isFile())
+                return refuse("attachment_unreadable", `${label} is not a regular file: a folder or a device cannot be attached. ${NOTHING_SENT}`);
+            size = info.size;
+        }
+        catch (error) {
+            const code = error.code;
+            return refuse("attachment_unreadable", code === "ENOENT"
+                ? `${label} does not exist. ${NOTHING_SENT}`
+                : `${label} could not be read (${code ?? "unknown error"}). ${NOTHING_SENT}`);
+        }
+        if (size === 0)
+            return refuse("attachment_unreadable", `${label} is empty, and an empty file is not worth sending. ${NOTHING_SENT}`);
+        sizes.push(size);
+    }
+    const tooLarge = totalTooLarge(sizes.reduce((sum, size) => sum + size, 0));
+    if (tooLarge)
+        return tooLarge;
+    const attachments = [];
+    const actual = [];
+    for (const [index, filePath] of paths.entries()) {
+        let bytes;
+        try {
+            bytes = await readFile(filePath);
+        }
+        catch (error) {
+            const code = error.code;
+            return refuse("attachment_unreadable", `Attachment ${index + 1} could not be read (${code ?? "unknown error"}). ${NOTHING_SENT}`);
+        }
+        actual.push(bytes.length);
+        const filename = path.basename(filePath);
+        attachments.push({ filename, content_type: mailAttachmentContentType(filename), content_base64: bytes.toString("base64") });
+    }
+    // A file that grew between the stat and the read is the file as it is now.
+    const total = actual.reduce((sum, size) => sum + size, 0);
+    const grew = totalTooLarge(total);
+    if (grew)
+        return grew;
+    if (actual.includes(0)) {
+        return refuse("attachment_unreadable", `Attachment ${actual.indexOf(0) + 1} is empty, and an empty file is not worth sending. ${NOTHING_SENT}`);
+    }
+    return {
+        ok: true,
+        attachments,
+        summary: { count: attachments.length, bytes: total, sizes: actual, content_types: attachments.map((entry) => entry.content_type) },
+    };
+}
+/** The second check: the whole request, not just the files. Called with the JSON about to be posted. */
+export function mailRequestFits(body) {
+    const bytes = Buffer.byteLength(JSON.stringify(body), "utf8");
+    if (bytes <= MAIL_REQUEST_MAX_BYTES)
+        return { ok: true, bytes };
+    return refuse("attachment_too_large", `The whole request would be ${bytesLabel(bytes)} (the message, the files encoded as base64, and the JSON around them) `
+        + `and Tower takes at most ${bytesLabel(MAIL_REQUEST_MAX_BYTES)}: a request over 4.5 MB is refused by the platform before Tower sees it. `
+        + `Shorten the message or send fewer or smaller files. ${NOTHING_SENT}`);
+}
+/** The sentence a result adds after a send or a draft that carried files. */
+export function attachmentSentence(summary) {
+    return `${summary.count} attachment${summary.count === 1 ? "" : "s"} went with it (${bytesLabel(summary.bytes)}).`;
+}

package/dist/mail-compose.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The compose half of the `mail_*` tools (BLI-12530, BLI-12661): the JSON that
+ * `mail_send` and `mail_draft` post, and the files that ride along. The twin of
+ * `commands/mail-compose.ts` in `@bli-cockpit/local-collector`.
+ *
+ * One shape for both tools, because the two doors take the same fields: a
+ * message that can be sent can be saved unsent, and a field added to one cannot
+ * be forgotten by the other.
+ */
+import { z } from "zod";
+import { type MailAttachmentSummary, type WireMailAttachment } from "./mail-attachments.js";
+/**
+ * The `attachments` argument of `mail_send` and `mail_draft`. The count is
+ * deliberately NOT capped in the schema: an eleventh file is refused by name,
+ * `too_many_attachments`, with the numbers, which a bare validation error would
+ * not say.
+ */
+export declare const ATTACHMENTS_INPUT: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    path: z.ZodString;
+}, z.core.$strip>>>;
+/** The JSON both tools post. `attachments` is present only when there are files. */
+export declare function composedBody(args: Record<string, unknown>, attachments?: readonly WireMailAttachment[]): Record<string, unknown>;
+export type PreparedMessage = {
+    ok: true;
+    body: Record<string, unknown>;
+    summary: MailAttachmentSummary | null;
+} | {
+    ok: false;
+    reason: string;
+    detail: string;
+};
+/**
+ * The request a tool posts: the body, plus the files named in `attachments`,
+ * read and screened HERE before any request is made. A refusal is the named
+ * reason and its numbers (`mail-attachments.ts`); a hosted server refuses the
+ * whole argument without touching a disk.
+ */
+export declare function prepareMessage(args: Record<string, unknown>): Promise<PreparedMessage>;
+/**
+ * Did the door SAY it carried the files that were posted? Claim only what the
+ * receipt shows: a Tower that predates attachments answers an ordinary 201,
+ * because its schema strips the key it does not know, and the message goes out
+ * or is saved WITHOUT its files while a tool that reported from what it posted
+ * would say they went. Only the door's own `attachments` receipt (count and
+ * bytes, both) says they did. Returns the sentence for an `isError` result when
+ * the answer does not say so, else null.
+ */
+export declare function unconfirmedAttachments(summary: MailAttachmentSummary | null, carried: unknown, verb: "send" | "draft"): string | null;
+/** What a result says about the files: a sentence, and the structured half. */
+export declare function attachmentResult(summary: MailAttachmentSummary | null): {
+    sentence: string;
+    structured: Record<string, unknown>;
+};

package/dist/mail-compose.js

@@ -0,0 +1,93 @@
+/**
+ * The compose half of the `mail_*` tools (BLI-12530, BLI-12661): the JSON that
+ * `mail_send` and `mail_draft` post, and the files that ride along. The twin of
+ * `commands/mail-compose.ts` in `@bli-cockpit/local-collector`.
+ *
+ * One shape for both tools, because the two doors take the same fields: a
+ * message that can be sent can be saved unsent, and a field added to one cannot
+ * be forgotten by the other.
+ */
+import { z } from "zod";
+import { MAIL_ATTACHMENT_MAX_COUNT, MAIL_ATTACHMENTS_MAX_TOTAL_BYTES, attachmentSentence, mailRequestFits, readMailAttachments, } from "./mail-attachments.js";
+/**
+ * The `attachments` argument of `mail_send` and `mail_draft`. The count is
+ * deliberately NOT capped in the schema: an eleventh file is refused by name,
+ * `too_many_attachments`, with the numbers, which a bare validation error would
+ * not say.
+ */
+export const ATTACHMENTS_INPUT = z
+    .array(z.object({ path: z.string().min(1).max(4096).describe("A path to a file on THIS machine (absolute, or relative to the server's working directory).") }))
+    .optional()
+    .describe(`Files to attach, as [{ path }], read from THIS machine's disk by the local bli-tower server: up to ${MAIL_ATTACHMENT_MAX_COUNT} and `
+    + `${MAIL_ATTACHMENTS_MAX_TOTAL_BYTES.toLocaleString("en-US")} bytes together (about 3 MB: a request to Tower is capped at 4.5 MB and a file travels as base64). `
+    + "The type comes from the extension (.docx .pdf .png .jpg .txt .csv .md .zip and more, else application/octet-stream). "
+    + "Refused BEFORE anything is sent, by name and with the numbers: too_many_attachments, attachment_unreadable (missing, a folder, empty), attachment_too_large. "
+    + "NOT available on the hosted Tower server, which cannot read your computer: there it answers attachments_unavailable_hosted. "
+    + "The result reports from Tower's own answer: if Tower does not confirm the files (an older Tower), it is an error, attachments_not_confirmed, that says whether the message went. "
+    + "A reply (in_reply_to_message_id) keeps its thread with files in it.");
+/** The JSON both tools post. `attachments` is present only when there are files. */
+export function composedBody(args, attachments = []) {
+    return {
+        account_id: args.account_id,
+        to: args.to.map((address) => ({ address })),
+        ...(Array.isArray(args.cc) && args.cc.length > 0
+            ? { cc: args.cc.map((address) => ({ address })) }
+            : {}),
+        subject: args.subject ?? "",
+        text: args.text,
+        ...(attachments.length > 0 ? { attachments } : {}),
+        ...(args.in_reply_to_message_id ? { in_reply_to_message_id: args.in_reply_to_message_id } : {}),
+    };
+}
+/**
+ * The request a tool posts: the body, plus the files named in `attachments`,
+ * read and screened HERE before any request is made. A refusal is the named
+ * reason and its numbers (`mail-attachments.ts`); a hosted server refuses the
+ * whole argument without touching a disk.
+ */
+export async function prepareMessage(args) {
+    const read = await readMailAttachments(args.attachments);
+    if (!read.ok)
+        return read;
+    if (read.attachments.length === 0)
+        return { ok: true, body: composedBody(args), summary: null };
+    const body = composedBody(args, read.attachments);
+    const fits = mailRequestFits(body);
+    if (!fits.ok)
+        return fits;
+    return { ok: true, body, summary: read.summary };
+}
+/**
+ * Did the door SAY it carried the files that were posted? Claim only what the
+ * receipt shows: a Tower that predates attachments answers an ordinary 201,
+ * because its schema strips the key it does not know, and the message goes out
+ * or is saved WITHOUT its files while a tool that reported from what it posted
+ * would say they went. Only the door's own `attachments` receipt (count and
+ * bytes, both) says they did. Returns the sentence for an `isError` result when
+ * the answer does not say so, else null.
+ */
+export function unconfirmedAttachments(summary, carried, verb) {
+    if (!summary)
+        return null;
+    const said = carried !== null && typeof carried === "object" ? carried : {};
+    if (said.count === summary.count && said.bytes === summary.bytes)
+        return null;
+    const files = `${summary.count} attachment${summary.count === 1 ? "" : "s"}`;
+    const was = summary.count === 1 ? "was" : "were";
+    return verb === "send"
+        ? `The message WAS sent (once), but Tower did not confirm that its ${files} ${was} in it (attachments_not_confirmed). `
+            + "That usually means this Tower deployment predates attachments, in which case it went out WITHOUT them. "
+            + "Do not send it again: look in that mailbox's Sent folder first."
+        : `The draft WAS saved, but Tower did not confirm that its ${files} ${was} in it (attachments_not_confirmed). `
+            + "That usually means this Tower deployment predates attachments, in which case the draft has NO file. "
+            + "Delete it from that mailbox's Drafts and try again once Tower is updated.";
+}
+/** What a result says about the files: a sentence, and the structured half. */
+export function attachmentResult(summary) {
+    if (!summary)
+        return { sentence: "", structured: {} };
+    return {
+        sentence: ` ${attachmentSentence(summary)}`,
+        structured: { attachments: { count: summary.count, bytes: summary.bytes, content_types: summary.content_types } },
+    };
+}

package/dist/mail-tools.d.ts

@@ -22,6 +22,14 @@
  *   conversation. It returns the same `?meta=1` read the CLI uses to describe
  *   a file before downloading it, and names the command that fetches it.
  *
+ * **Files (BLI-12661).** `mail_send` and `mail_draft` take `attachments:
+ * [{ path }]`, the twin of `--attach <path>`: this server runs on the person's
+ * machine, so it reads the paths (`mail-attachments.ts`) and posts name, type
+ * and base64 to the same doors. The one thing it must never do is read a path
+ * on the HOSTED server, where the path would name a file on the host:
+ * `/api/mcp` serves these same tools, so there the argument is refused by name
+ * (`attachments_unavailable_hosted`) before any disk is touched.
+ *
  * Same session discipline as `work-tools.ts`: the session is loaded fresh per
  * call, so a machine with no `cockpit login` pairing still serves this
  * server's other tools and only a `mail_` call fails, by name.

package/dist/mail-tools.js

@@ -22,35 +22,27 @@
  *   conversation. It returns the same `?meta=1` read the CLI uses to describe
  *   a file before downloading it, and names the command that fetches it.
  *
+ * **Files (BLI-12661).** `mail_send` and `mail_draft` take `attachments:
+ * [{ path }]`, the twin of `--attach <path>`: this server runs on the person's
+ * machine, so it reads the paths (`mail-attachments.ts`) and posts name, type
+ * and base64 to the same doors. The one thing it must never do is read a path
+ * on the HOSTED server, where the path would name a file on the host:
+ * `/api/mcp` serves these same tools, so there the argument is refused by name
+ * (`attachments_unavailable_hosted`) before any disk is touched.
+ *
  * Same session discipline as `work-tools.ts`: the session is loaded fresh per
  * call, so a machine with no `cockpit login` pairing still serves this
  * server's other tools and only a `mail_` call fails, by name.
  */
 import { z } from "zod";
 import { callAgentDoor } from "./agent-door.js";
+import { ATTACHMENTS_INPUT, attachmentResult, prepareMessage, unconfirmedAttachments } from "./mail-compose.js";
 import { CONFIRM_INPUT, EMAIL_INPUT, doorFailureText, errorResult, queryString, registrarFor, textResult, unconfirmed, withSession, } from "./tool-result.js";
 function messageLine(message) {
     const from = message.from_address?.address ?? "(no sender)";
     return `${message.is_unread ? "*" : " "} ${message.internal_date.slice(0, 16)}  ${from}  ${message.subject ?? "(no subject)"}  [thread ${message.thread_id ?? "?"}]`;
 }
 const ADDRESS = EMAIL_INPUT.describe("An email address.");
-/**
- * The JSON `mail_send` and `mail_draft` post. One shape, because the two doors
- * take the same fields: a message that can be sent can be saved unsent, and a
- * field added to one cannot be forgotten by the other.
- */
-function composedBody(args) {
-    return {
-        account_id: args.account_id,
-        to: args.to.map((address) => ({ address })),
-        ...(Array.isArray(args.cc) && args.cc.length > 0
-            ? { cc: args.cc.map((address) => ({ address })) }
-            : {}),
-        subject: args.subject ?? "",
-        text: args.text,
-        ...(args.in_reply_to_message_id ? { in_reply_to_message_id: args.in_reply_to_message_id } : {}),
-    };
-}
 export function registerMailTools(server, deps) {
     const register = registrarFor(server);
     register("mail_accounts", {
@@ -191,6 +183,8 @@ export function registerMailTools(server, deps) {
         title: "Send mail from one mailbox",
         description: "Sends a message. `account_id` is REQUIRED and is the address it goes out from — with several mailboxes attached, "
             + "that is never something to guess. `in_reply_to_message_id` (a message id from mail_read) threads the reply. "
+            + "`attachments` ([{ path }]) puts files from this machine in the message, up to 10 and 3,000,000 bytes together; "
+            + "see that argument for what it refuses. "
             + "This actually sends mail to real people: confirm must be true.",
         inputSchema: {
             account_id: z.string().uuid().describe("The mailbox it goes out from (mail_accounts). Never guessed."),
@@ -198,6 +192,7 @@ export function registerMailTools(server, deps) {
             cc: z.array(ADDRESS).max(50).optional().describe("Copied email addresses."),
             subject: z.string().max(998).describe("The subject line."),
             text: z.string().min(1).max(500_000).describe("The plain-text body."),
+            attachments: ATTACHMENTS_INPUT,
             in_reply_to_message_id: z.string().uuid().optional().describe("A message id from mail_read: send this as a reply in that thread."),
             confirm: CONFIRM_INPUT,
         },
@@ -205,11 +200,20 @@ export function registerMailTools(server, deps) {
         const refusal = unconfirmed(args, "Sending mail reaches real people and cannot be recalled.");
         if (refusal)
             return refusal;
-        const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/mail/send", composedBody(args));
+        // BLI-12661: the files are read and refused here, by name, before the door is asked.
+        const message = await prepareMessage(args);
+        if (!message.ok)
+            return errorResult(`Refused (${message.reason}): ${message.detail}`);
+        const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/mail/send", message.body);
         if (!response.ok)
             return errorResult(doorFailureText("mail_send", response));
         const sent = response.body.sent;
-        return textResult(`Sent from ${sent?.address ?? "that mailbox"} to ${args.to.join(", ")}${sent?.threaded ? " (as a reply)" : ""}.`, { sent });
+        // Report only what the door's receipt shows (BLI-12661), never what was posted.
+        const notConfirmed = unconfirmedAttachments(message.summary, sent?.attachments, "send");
+        if (notConfirmed)
+            return errorResult(notConfirmed);
+        const files = attachmentResult(message.summary);
+        return textResult(`Sent from ${sent?.address ?? "that mailbox"} to ${args.to.join(", ")}${sent?.threaded ? " (as a reply)" : ""}.${files.sentence}`, { sent, ...files.structured });
     }));
     register("mail_draft", {
         title: "Save a draft in one mailbox",
@@ -219,27 +223,40 @@ export function registerMailTools(server, deps) {
             + "draft is saved in (mail_accounts) — with several attached, that is never something to guess. "
             + "`in_reply_to_message_id` (a message id from mail_read) threads the draft into that conversation the way mail_send "
             + "threads a reply; Gmail files it there only when the subject matches the original's, and the answer says whether it "
-            + "did (`threaded`). Only the mailbox's OWNER can draft into it, and only Gmail mailboxes can take one: an IMAP "
-            + "mailbox is refused as imap_drafts_unsupported. Answers the provider draft id, the thread id and the account id.",
+            + "did (`threaded`). `attachments` ([{ path }]) puts files from this machine in the draft, up to 10 and 3,000,000 bytes "
+            + "together; see that argument for what it refuses. Only the mailbox's OWNER can draft into it, and only Gmail "
+            + "mailboxes can take one: an IMAP mailbox is refused as imap_drafts_unsupported. Answers the provider draft id, "
+            + "the thread id and the account id.",
         inputSchema: {
             account_id: z.string().uuid().describe("The mailbox the draft is saved in (mail_accounts). Never guessed."),
             to: z.array(ADDRESS).min(1).max(50).describe("Recipient email addresses, so the draft is ready to send as it is."),
             cc: z.array(ADDRESS).max(50).optional().describe("Copied email addresses."),
             subject: z.string().max(998).describe("The subject line. For a reply, keep the original's subject or Gmail will not thread it."),
             text: z.string().min(1).max(500_000).describe("The plain-text body."),
+            attachments: ATTACHMENTS_INPUT,
             in_reply_to_message_id: z.string().uuid().optional().describe("A message id from mail_read: save this as a reply in that thread."),
         },
     }, async (args) => withSession(deps, async (session) => {
-        const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/mail/drafts", composedBody(args));
+        // BLI-12661: the files are read and refused here, by name, before the door is asked.
+        const message = await prepareMessage(args);
+        if (!message.ok)
+            return errorResult(`Refused (${message.reason}): ${message.detail}`);
+        const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/mail/drafts", message.body);
         if (!response.ok)
             return errorResult(doorFailureText("mail_draft", response));
         const draft = response.body.draft;
+        // Report only what the door's receipt shows (BLI-12661), never what was posted.
+        const notConfirmed = unconfirmedAttachments(message.summary, draft?.attachments, "draft");
+        if (notConfirmed)
+            return errorResult(notConfirmed);
+        const files = attachmentResult(message.summary);
         // Both halves carry the ids (BLI-10432): a client that hands the model only
         // `content`, or only `structuredContent`, must still learn where the draft is.
         return textResult(`Saved a draft in ${draft?.address ?? "that mailbox"} for ${args.to.join(", ")}`
             + `${draft?.threaded ? " (in the reply's thread)" : args.in_reply_to_message_id ? " (Gmail did NOT file it in that thread: its subject has to match the original's)" : ""}. `
-            + "Nothing was sent: it waits in Drafts for a person to read, edit and send. "
-            + `draft_id=${draft?.provider_draft_id ?? "(none returned)"} thread_id=${draft?.provider_thread_id ?? "(none)"} account_id=${draft?.account_id ?? String(args.account_id)}`, { draft });
+            + "Nothing was sent: it waits in Drafts for a person to read, edit and send."
+            + `${files.sentence} `
+            + `draft_id=${draft?.provider_draft_id ?? "(none returned)"} thread_id=${draft?.provider_thread_id ?? "(none)"} account_id=${draft?.account_id ?? String(args.account_id)}`, { draft, ...files.structured });
     }));
     register("mail_attachment", {
         title: "Describe an attachment",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/mcp",
-  "version": "0.1.85",
+  "version": "0.1.86",
   "private": false,
   "description": "bli-tower: an MCP server over BLI Cockpit's agent doors: JARVIS (jarvis_*), documents (docs_*), channels (msg_*), issues (work_*), the daily page (brief_*), meeting notes (notes_*), the ops board (ops_status/slack_*), settings/team/model, Scout and the workbook, plus the legacy event-stream tools (emit_event, get_ticket_timeline, get_active_tickets).",
   "type": "module",