@markmnl/fmsg-mcp 1.0.0 → 1.1.1

package/dist/tools/draft.js

@@ -0,0 +1,151 @@
+import * as z from "zod/v4";
+import { downloadBaseUrl } from "../download.js";
+import { toolError } from "../errors.js";
+import { addressList, headerValue, isoTime } from "../render.js";
+import { CHECKSUM_HEADER, UPLOAD_ENCODINGS, draftUploadUrlTemplate } from "../upload.js";
+import { attachmentInput, base64Hint, draftWithAttachments, fileRoutes, prepareAttachments } from "./attachments.js";
+import { SENDS, attachmentItem, idSchema, ok, openEnum, outputObject, resolverFor, withCaller } from "./common.js";
+import { rootTopic } from "./read.js";
+import { IMMUTABLE, IMPORTANT, NO_REPLY, UPLOAD_STEPS, hintOutput, redactionNote, replyRecipients, resolveRecipients, resolvedNote, resolvedOutput, sendWarnings, sentAttachments, sentOutput, withHint, } from "./send.js";
+export const registerDraftTools = (server, deps) => {
+    const baseUrl = downloadBaseUrl(deps.config);
+    const routes = fileRoutes(deps.config);
+    server.registerTool("create_draft", {
+        title: "Create fmsg draft",
+        description: "Create an unsent draft: a new message, or a reply when reply_to is given (reply rules and reply-all apply). " +
+            "Nothing is sent until send_draft; delete_draft discards it. The draft is visible in the user's other fmsg clients. " +
+            (routes.uploadUrl ? `Use it for large files: ${UPLOAD_STEPS}. ` : "") +
+            "Secrets in the body and topic are redacted.",
+        inputSchema: z.strictObject({
+            to: z.array(z.string()).min(1).optional().describe("recipient addresses (@user@domain) or short names; for a reply, overrides reply-all"),
+            topic: z.string().max(256).optional().describe("thread topic for a new message; not allowed with reply_to"),
+            reply_to: idSchema.optional().describe("message this draft replies to"),
+            body: z.string().describe("message body; Markdown unless type says otherwise"),
+            type: z.string().default("text/markdown; charset=utf-8").describe("body media type"),
+            important: z.boolean().default(false).describe(IMPORTANT),
+            no_reply: z.boolean().default(false).describe(NO_REPLY),
+            allow_no_reply: z.boolean().default(false).describe("draft a reply even though the parent asked for no replies"),
+            attachments: z.array(attachmentInput(deps.config)).optional().describe("files to attach now"),
+        }),
+        outputSchema: outputObject({
+            draft_id: z.string(),
+            to: z.array(z.string()),
+            topic: z.string(),
+            parent_id: z.string().nullable(),
+            attachments: z.array(attachmentItem).describe("sorted by filename, the same order in every tool"),
+            redactions: z.number().describe("secrets replaced with placeholders in the draft"),
+            redacted: z.array(z.string()).describe("the kinds of secret replaced; empty when none"),
+            resolved: resolvedOutput,
+            warnings: z.array(z.string()).describe("things to tell the user, such as redacted secrets or resolved short names"),
+            upload: outputObject({
+                url_template: z.string().describe("replace {filename} with the attachment's file name (letters, digits, dot, underscore, hyphen)"),
+                method: openEnum(["PUT"]),
+                authentication: openEnum(["bearer"], "bearer: send this MCP connection's Authorization header"),
+                checksum_header: z.string().describe("optional request header carrying the file's hex sha256; a mismatch is refused and the file not kept"),
+                accepts_encoding: z.array(z.string()).describe("Content-Encoding values accepted; the server decodes them before storing"),
+            }).optional().describe("where to upload more attachments; present when this server has a public URL"),
+            next: z.string(),
+            hint: hintOutput,
+        }),
+        annotations: { ...SENDS, destructiveHint: false },
+    }, async ({ to, topic, reply_to, body, type, important, no_reply, allow_no_reply, attachments }, ctx) => {
+        if (reply_to && topic)
+            return toolError("a reply has no topic: pass topic only for a new message");
+        if (!reply_to && !to?.length)
+            return toolError("pass to: the recipients (or reply_to to draft a reply)");
+        return withCaller(deps, ctx, async (caller, signal) => {
+            let recipients;
+            let resolved;
+            let pid;
+            if (reply_to) {
+                const parent = await caller.client.getMessage(reply_to, signal);
+                const target = replyRecipients(deps, caller, parent, to, allow_no_reply);
+                if ("content" in target)
+                    return target;
+                ({ to: recipients, resolved } = target);
+                pid = parent.id;
+            }
+            else {
+                ({ to: recipients, resolved } = resolveRecipients(to, resolverFor(deps, caller)));
+            }
+            const outbound = await prepareAttachments(attachments, deps.config);
+            const hint = base64Hint(attachments, routes);
+            const draft = await draftWithAttachments(caller.client, {
+                to: recipients, body, type, important, noReply: no_reply, ...(pid ? { pid } : { topic: topic ?? "" }),
+            }, outbound, signal);
+            const upload = baseUrl ? {
+                url_template: draftUploadUrlTemplate(baseUrl, draft.id),
+                method: "PUT",
+                authentication: "bearer",
+                checksum_header: CHECKSUM_HEADER,
+                accepts_encoding: [...UPLOAD_ENCODINGS],
+            } : undefined;
+            const next = (upload ? `Upload files with PUT to ${upload.url_template} using this MCP connection's Authorization header, then call send_draft. ` : "Call send_draft to send it. ") +
+                "Call delete_draft to discard it.";
+            const structured = {
+                draft_id: draft.id,
+                to: recipients,
+                topic: draft.topic,
+                parent_id: pid ?? null,
+                attachments: sentAttachments(draft.attachments, outbound),
+                redactions: draft.redactions,
+                redacted: draft.redacted,
+                ...(resolved.length ? { resolved } : {}),
+                warnings: sendWarnings(draft.redactions, draft.redacted, resolved),
+                ...(upload ? { upload } : {}),
+                next,
+                ...(hint ? { hint } : {}),
+            };
+            const what = pid ? `reply to message ${pid}` : `"${headerValue(draft.topic)}"`;
+            const text = `Created draft ${draft.id} (${what}) for ${addressList(recipients)}; not sent` +
+                (structured.attachments.length ? `, with ${structured.attachments.map((a) => a.filename).join(", ")}` : "") +
+                redactionNote(draft.redactions, draft.redacted) + resolvedNote(resolved) + `\n\n${next}`;
+            return ok(withHint(text, hint), structured);
+        });
+    });
+    server.registerTool("send_draft", {
+        title: "Send fmsg draft",
+        description: `Send a draft made with create_draft, with its attachments, immediately. ${IMMUTABLE} ` +
+            "If the host refuses it, its reason is returned verbatim and the message stays a draft.",
+        inputSchema: z.strictObject({ id: idSchema.describe("the draft to send") }),
+        outputSchema: sentOutput,
+        annotations: SENDS,
+    }, async ({ id }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
+        const draft = await caller.client.getMessage(id, signal);
+        if (draft.time !== null && draft.time !== undefined)
+            return toolError(`message ${id} was already sent; send_draft sends only drafts`);
+        const sent = await caller.client.sendDraft(draft.id, signal);
+        const topic = draft.pid ? "" : (draft.topic ?? "");
+        const structured = {
+            id: sent.id,
+            time: isoTime(sent.time),
+            from: caller.address,
+            to: draft.to,
+            topic,
+            parent_id: draft.pid ?? null,
+            attachments: sentAttachments(draft.attachments ?? []),
+            redactions: 0,
+            redacted: [],
+            warnings: [],
+            // The message is already sent: a failed topic lookup only leaves the topic unknown.
+            thread_topic: draft.pid ? await rootTopic(caller.client, { ...draft, id: sent.id }, signal).catch(() => null) : topic,
+        };
+        const where = draft.pid ? `reply to message ${draft.pid}` : `"${headerValue(topic)}"`;
+        const text = `Sent draft ${sent.id} (${where}) to ${addressList(draft.to)} at ${structured.time ?? "?"}` +
+            (structured.attachments.length ? ` with ${structured.attachments.map((a) => a.filename).join(", ")}` : "") + ".";
+        return ok(text, structured);
+    }));
+    server.registerTool("delete_draft", {
+        title: "Delete fmsg draft",
+        description: "Delete an unsent draft and its attachments. Sent messages cannot be deleted.",
+        inputSchema: z.strictObject({ id: idSchema.describe("the draft to delete") }),
+        outputSchema: outputObject({ id: z.string(), deleted: z.boolean() }),
+        annotations: { ...SENDS, idempotentHint: true },
+    }, async ({ id }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
+        const draft = await caller.client.getMessage(id, signal);
+        if (draft.time !== null && draft.time !== undefined)
+            return toolError(`message ${id} was already sent and cannot be deleted`);
+        await caller.client.deleteMessage(draft.id, signal);
+        return ok(`Deleted draft ${draft.id}.`, { id: draft.id, deleted: true });
+    }));
+};

package/dist/tools/read.js

@@ -202,6 +202,7 @@ export const registerReadTools = (server, deps) => {
             size: z.number(),
             content_type: z.string().describe("media type; the same value as type"),
             type: z.string().optional().describe("media type, named as on message attachment lists"),
+            text: z.string().optional().describe("the file's contents, for text attachments"),
             ...untrustedNotice,
         }),
         annotations: READ_ONLY,
@@ -223,8 +224,11 @@ export const registerReadTools = (server, deps) => {
         const type = contentType ?? "application/octet-stream";
         const base = { id, filename, size: data.byteLength, content_type: type, type, ...UNTRUSTED };
         const metadata = `${filename} (${data.byteLength} bytes, ${type}) from message ${id}`;
-        if (type.toLowerCase().startsWith("text/"))
-            return ok(messageData(`${metadata}\n\n${Buffer.from(data).toString("utf8")}`), base);
+        if (type.toLowerCase().startsWith("text/")) {
+            // Some hosts show models only structured content, so the text is there too.
+            const text = Buffer.from(data).toString("utf8");
+            return ok(messageData(`${metadata}\n\n${text}`), { ...base, text });
+        }
         const b64 = Buffer.from(data).toString("base64");
         const uri = `fmsg://message/${id}/attachment/${encodeURIComponent(filename)}`;
         const result = {

package/dist/tools/send.d.ts

@@ -1,2 +1,86 @@
-import { type Register } from "./common.js";
+import type { CallToolResult } from "@modelcontextprotocol/server";
+import * as z from "zod/v4";
+import { type AddressResolver } from "../address.js";
+import type { FmsgMessage } from "../client/types.js";
+import type { Config } from "../config.js";
+import type { Caller } from "../context.js";
+import { type PreparedAttachment } from "./attachments.js";
+import { type Register, type ToolDeps } from "./common.js";
+export declare const IMMUTABLE = "fmsg messages are immutable: once sent they cannot be edited or recalled. Send within the user's requested task or authorized automation.";
+export declare const IMPORTANT = "mark as important for recipients";
+export declare const NO_REPLY = "ask recipients (and their agents) not to reply";
+/** The upload-URL route, stated in full wherever a model may read about it. */
+export declare const UPLOAD_STEPS: string;
+/** How to send files without the model writing their bytes, naming only what this server registered. */
+export declare function attachmentGuidance(config: Config): string;
+/**
+ * Resolve recipients, dropping duplicates, and report each name that was not already a full address, so the model
+ * can confirm a guessed address with the user.
+ */
+export declare function resolveRecipients(names: string[], resolver: AddressResolver): {
+    to: string[];
+    resolved: Array<{
+        input: string;
+        address: string;
+    }>;
+};
+export declare const resolvedOutput: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    input: z.ZodOptional<z.ZodString>;
+    address: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>>>;
+/** Warnings for the model to pass on: what was redacted, and short names that were expanded. */
+export declare function sendWarnings(redactions: number, kinds: string[], resolved: Array<{
+    input: string;
+    address: string;
+}>): string[];
+/** Sent attachments with the type each was given, or the one its filename implies, in the order every tool lists them. */
+export declare function sentAttachments(sent: Array<{
+    filename: string;
+    size: number;
+}>, outbound?: Array<Pick<PreparedAttachment, "contentType">>): {
+    type: string;
+    filename: string;
+    size: number;
+}[];
+/**
+ * Who a reply goes to: the given recipients, or everyone on the parent except the caller. Returns an error result
+ * when the parent is terminal, asked for no replies (unless allowed) or has nobody else to reply to.
+ */
+export declare function replyRecipients(deps: ToolDeps, caller: Caller, parent: FmsgMessage, recipients: string[] | undefined, allowNoReply: boolean): CallToolResult | {
+    to: string[];
+    resolved: Array<{
+        input: string;
+        address: string;
+    }>;
+};
+export declare const hintOutput: z.ZodOptional<z.ZodString>;
+export declare const sentOutput: z.ZodObject<{
+    id: z.ZodString;
+    time: z.ZodNullable<z.ZodString>;
+    from: z.ZodString;
+    to: z.ZodArray<z.ZodString>;
+    topic: z.ZodString;
+    parent_id: z.ZodNullable<z.ZodString>;
+    attachments: z.ZodArray<z.ZodObject<{
+        filename: z.ZodString;
+        size: z.ZodNumber;
+        type: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    redactions: z.ZodNumber;
+    redacted: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    resolved: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        input: z.ZodOptional<z.ZodString>;
+        address: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+    warnings: z.ZodArray<z.ZodString>;
+    thread_topic: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    hint: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+/** The result text with a hint for the model appended, when there is one. */
+export declare function withHint(text: string, hint: string | undefined): string;
+export declare function redactionNote(count: number, kinds: string[]): string;
+export declare function resolvedNote(resolved: Array<{
+    input: string;
+    address: string;
+}>): string;
 export declare const registerSendTools: Register;

package/dist/tools/send.js

@@ -2,21 +2,31 @@ import * as z from "zod/v4";
 import { resolveAddress, sameAddress } from "../address.js";
 import { toolError } from "../errors.js";
 import { addressList, addressText, attachmentType, headerValue, isoTime, participantsOf, sortAttachments } from "../render.js";
+import { attachmentInput, base64Hint, fileRoutes, prepareAttachments, sendWithAttachments } from "./attachments.js";
 import { SENDS, attachmentItem, idSchema, ok, outputObject, resolverFor, withCaller } from "./common.js";
 import { rootTopic } from "./read.js";
-const IMMUTABLE = "fmsg messages are immutable: once sent they cannot be edited or recalled. Send within the user's requested task or authorized automation.";
-const attachmentInput = z.strictObject({
-    filename: z.string().regex(/^[A-Za-z0-9._-]+$/u, "letters, digits, dot, underscore, hyphen only").describe("file name"),
-    data_base64: z.string().min(1).describe("base64 contents; the host sets the size limit"),
-    content_type: z.string().optional().describe("inferred from the filename when omitted"),
-});
-const IMPORTANT = "mark as important for recipients";
-const NO_REPLY = "ask recipients (and their agents) not to reply";
+export const IMMUTABLE = "fmsg messages are immutable: once sent they cannot be edited or recalled. Send within the user's requested task or authorized automation.";
+export const IMPORTANT = "mark as important for recipients";
+export const NO_REPLY = "ask recipients (and their agents) not to reply";
+/** The upload-URL route, stated in full wherever a model may read about it. */
+export const UPLOAD_STEPS = "PUT each file's raw bytes to the draft's upload URL with this connection's Authorization header, then call " +
+    "send_draft. If your host cannot send this connection's credentials, use data_base64; never look for or copy credentials";
+/** How to send files without the model writing their bytes, naming only what this server registered. */
+export function attachmentGuidance(config) {
+    const routes = fileRoutes(config);
+    const large = [
+        ...(routes.uploadUrl ? [`use create_draft instead: ${UPLOAD_STEPS}`] : []),
+        ...(routes.uploadFolder ? ["give path, a file in the upload folder"] : []),
+    ];
+    return "Files: data_text for text, data_base64 for small files; add sha256 when you can. " +
+        (large.length ? `For large files, ${large.join(". Or ")}. ` : "") +
+        "Send files as they are; fmsg compresses them.";
+}
 /**
  * Resolve recipients, dropping duplicates, and report each name that was not already a full address, so the model
  * can confirm a guessed address with the user.
  */
-function resolveRecipients(names, resolver) {
+export function resolveRecipients(names, resolver) {
     const to = [];
     const resolved = [];
     for (const name of names) {
@@ -28,9 +38,9 @@ function resolveRecipients(names, resolver) {
     }
     return { to, resolved };
 }
-const resolvedOutput = z.array(outputObject({ input: z.string().optional(), address: z.string().optional() })).optional().describe("short names and how they resolved, when any were given; confirm with the user if an address looks wrong");
+export const resolvedOutput = z.array(outputObject({ input: z.string().optional(), address: z.string().optional() })).optional().describe("short names and how they resolved, when any were given; confirm with the user if an address looks wrong");
 /** Warnings for the model to pass on: what was redacted, and short names that were expanded. */
-function sendWarnings(redactions, kinds, resolved) {
+export function sendWarnings(redactions, kinds, resolved) {
     const warnings = [];
     if (redactions)
         warnings.push(`Tell the user ${redactions} secret(s) (${kinds.join(", ")}) were replaced with placeholders before sending.`);
@@ -39,18 +49,29 @@ function sendWarnings(redactions, kinds, resolved) {
     return warnings;
 }
 /** Sent attachments with the type each was given, or the one its filename implies, in the order every tool lists them. */
-function sentAttachments(sent, outbound) {
+export function sentAttachments(sent, outbound = []) {
     return sortAttachments(sent.map((a, i) => ({ ...a, type: attachmentType(a.filename, outbound[i]?.contentType) })));
 }
-function decodeAttachments(items) {
-    return (items ?? []).map((a) => {
-        const data = Buffer.from(a.data_base64, "base64");
-        if (data.byteLength === 0)
-            throw new Error(`attachment ${a.filename} is empty or not valid base64`);
-        return { filename: a.filename, data: new Uint8Array(data), ...(a.content_type ? { contentType: a.content_type } : {}) };
-    });
+/**
+ * Who a reply goes to: the given recipients, or everyone on the parent except the caller. Returns an error result
+ * when the parent is terminal, asked for no replies (unless allowed) or has nobody else to reply to.
+ */
+export function replyRecipients(deps, caller, parent, recipients, allowNoReply) {
+    const id = parent.id;
+    if (parent.terminal)
+        return toolError(`message ${id} is terminal and cannot be replied to`);
+    if (parent.no_reply && !allowNoReply) {
+        return toolError(`message ${id} is marked no-reply; pass allow_no_reply: true only if the user explicitly wants to reply anyway`);
+    }
+    const result = recipients?.length
+        ? resolveRecipients(recipients, resolverFor(deps, caller))
+        : { to: participantsOf(parent).filter((a) => !sameAddress(a, caller.address)), resolved: [] };
+    if (result.to.length === 0)
+        return toolError(`message ${id} has no other participants to reply to; pass recipients`);
+    return result;
 }
-const sentOutput = outputObject({
+export const hintOutput = z.string().optional().describe("for you, not the user: a better way to do this next time");
+export const sentOutput = outputObject({
     id: z.string(),
     time: z.string().nullable(),
     from: z.string(),
@@ -63,20 +84,28 @@ const sentOutput = outputObject({
     resolved: resolvedOutput,
     warnings: z.array(z.string()).describe("things to tell the user, such as redacted secrets or resolved short names"),
     thread_topic: z.string().nullable().optional().describe("the thread's topic: the topic sent for a new message; for a reply, the thread root's topic, or null when the root is not visible"),
+    hint: hintOutput,
 });
-function redactionNote(count, kinds) {
+/** The result text with a hint for the model appended, when there is one. */
+export function withHint(text, hint) {
+    return hint ? `${text}\n\n${hint}` : text;
+}
+export function redactionNote(count, kinds) {
     return count ? `. ${count} secret(s) were redacted before sending (${kinds.join(", ")}).` : ".";
 }
-function resolvedNote(resolved) {
+export function resolvedNote(resolved) {
     return resolved.length ? ` Short names resolved: ${resolved.map((r) => `${r.input} → ${addressText(r.address)}`).join(", ")}.` : "";
 }
 export const registerSendTools = (server, deps) => {
+    const attachments = z.array(attachmentInput(deps.config)).optional().describe("files");
+    const guidance = attachmentGuidance(deps.config);
+    const routes = fileRoutes(deps.config);
     server.registerTool("send_message", {
         title: "Send new fmsg message",
         description: `Send a new message immediately, starting a new thread. ${IMMUTABLE} ` +
             "Recipients may be full @user@domain addresses or resolvable short names. The body is Markdown by default. " +
             "Secrets are redacted. If the host rejects the message its reason is returned verbatim. " +
-            "To continue an existing conversation use reply instead.",
+            `To continue an existing conversation use reply instead. ${guidance}`,
         inputSchema: z.strictObject({
             to: z.array(z.string()).min(1).describe("recipient addresses (@user@domain) or short names"),
             topic: z.string().max(256).describe("thread topic (subject) — immutable once sent"),
@@ -84,23 +113,15 @@ export const registerSendTools = (server, deps) => {
             type: z.string().default("text/markdown; charset=utf-8").describe("body media type"),
             important: z.boolean().default(false).describe(IMPORTANT),
             no_reply: z.boolean().default(false).describe(NO_REPLY),
-            attachments: z.array(attachmentInput).optional().describe("files"),
+            attachments,
         }),
         outputSchema: sentOutput,
         annotations: SENDS,
     }, async ({ to, topic, body, type, important, no_reply, attachments }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
         const { to: recipients, resolved } = resolveRecipients(to, resolverFor(deps, caller));
-        const outbound = decodeAttachments(attachments);
-        const sent = await caller.client.send({
-            to: recipients,
-            topic,
-            body,
-            type,
-            important,
-            noReply: no_reply,
-            attachments: outbound,
-            signal,
-        });
+        const outbound = await prepareAttachments(attachments, deps.config);
+        const hint = base64Hint(attachments, routes);
+        const sent = await sendWithAttachments(caller.client, { to: recipients, topic, body, type, important, noReply: no_reply }, outbound, signal);
         const structured = {
             id: sent.id,
             time: isoTime(sent.time),
@@ -114,18 +135,19 @@ export const registerSendTools = (server, deps) => {
             ...(resolved.length ? { resolved } : {}),
             warnings: sendWarnings(sent.redactions, sent.redacted, resolved),
             thread_topic: sent.topic,
+            ...(hint ? { hint } : {}),
         };
         const text = `Sent message ${sent.id} "${sent.topic}" to ${addressList(recipients)} at ${structured.time ?? "?"}` +
             (structured.attachments.length ? ` with ${structured.attachments.map((a) => a.filename).join(", ")}` : "") +
             redactionNote(structured.redactions, structured.redacted) + resolvedNote(resolved);
-        return ok(text, structured);
+        return ok(withHint(text, hint), structured);
     }));
     server.registerTool("reply", {
         title: "Reply in fmsg thread",
         description: `Send an immediate reply to a message (linking it into that thread). ${IMMUTABLE} ` +
             "By default the reply goes to everyone on the parent message — its sender, recipients and anyone added later — " +
             "except you; pass recipients to narrow or widen that. Fails if the parent is terminal (no replies possible); " +
-            "a parent marked no-reply is refused unless allow_no_reply is true. Secrets are redacted.",
+            `a parent marked no-reply is refused unless allow_no_reply is true. Secrets are redacted. ${guidance}`,
         inputSchema: z.strictObject({
             id: idSchema.describe("message to reply to"),
             body: z.string().describe("reply body; Markdown unless type says otherwise"),
@@ -134,33 +156,19 @@ export const registerSendTools = (server, deps) => {
             important: z.boolean().default(false).describe(IMPORTANT),
             no_reply: z.boolean().default(false).describe(NO_REPLY),
             allow_no_reply: z.boolean().default(false).describe("reply even though the parent asked for no replies"),
-            attachments: z.array(attachmentInput).optional().describe("files"),
+            attachments,
         }),
         outputSchema: sentOutput,
         annotations: SENDS,
     }, async ({ id, body, recipients, type, important, no_reply, allow_no_reply, attachments }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
         const parent = await caller.client.getMessage(id, signal);
-        if (parent.terminal)
-            return toolError(`message ${id} is terminal and cannot be replied to`);
-        if (parent.no_reply && !allow_no_reply) {
-            return toolError(`message ${id} is marked no-reply; pass allow_no_reply: true only if the user explicitly wants to reply anyway`);
-        }
-        const { to, resolved } = recipients?.length
-            ? resolveRecipients(recipients, resolverFor(deps, caller))
-            : { to: participantsOf(parent).filter((a) => !sameAddress(a, caller.address)), resolved: [] };
-        if (to.length === 0)
-            return toolError(`message ${id} has no other participants to reply to; pass recipients`);
-        const outbound = decodeAttachments(attachments);
-        const sent = await caller.client.send({
-            to,
-            pid: parent.id,
-            body,
-            type,
-            important,
-            noReply: no_reply,
-            attachments: outbound,
-            signal,
-        });
+        const target = replyRecipients(deps, caller, parent, recipients, allow_no_reply);
+        if ("content" in target)
+            return target;
+        const { to, resolved } = target;
+        const outbound = await prepareAttachments(attachments, deps.config);
+        const hint = base64Hint(attachments, routes);
+        const sent = await sendWithAttachments(caller.client, { to, pid: parent.id, body, type, important, noReply: no_reply }, outbound, signal);
         const structured = {
             id: sent.id,
             time: isoTime(sent.time),
@@ -175,11 +183,12 @@ export const registerSendTools = (server, deps) => {
             warnings: sendWarnings(sent.redactions, sent.redacted, resolved),
             // The reply is already sent: a failed topic lookup only leaves the topic unknown.
             thread_topic: await rootTopic(caller.client, parent, signal).catch(() => null),
+            ...(hint ? { hint } : {}),
         };
         const topic = structured.thread_topic ? ` in "${headerValue(structured.thread_topic)}"` : "";
         const text = `Sent reply ${sent.id} to message ${parent.id}${topic} for ${addressList(to)} at ${structured.time ?? "?"}` +
             redactionNote(structured.redactions, structured.redacted) + resolvedNote(resolved);
-        return ok(text, structured);
+        return ok(withHint(text, hint), structured);
     }));
     server.registerTool("add_recipients", {
         title: "Add fmsg recipients",

package/dist/upload.d.ts

@@ -0,0 +1,28 @@
+export declare const UPLOAD_PATH = "/mcp/drafts";
+/** Content-Encoding values accepted on uploads; decoded before the bytes reach fmsg. */
+export declare const UPLOAD_ENCODINGS: readonly ["gzip", "deflate"];
+export declare const CHECKSUM_HEADER = "x-content-sha256";
+/** The PUT target for one draft's attachments, with `{filename}` left for the host to fill in. */
+export declare function draftUploadUrlTemplate(baseUrl: string, id: string): string;
+export declare function parseUploadPath(pathname: string): {
+    id: string;
+    filename: string;
+};
+/** The upload request's own body was unusable (such as invalid compressed data); answered with 400. */
+export declare class UploadBodyError extends Error {
+    constructor(message: string);
+}
+/** How long draining a failed upload's remaining body may wait for more data before the connection is closed. */
+export declare const UPLOAD_DRAIN_IDLE_MS = 10000;
+/**
+ * The upload body as a stream whose cancellation leaves the request open, plus `drain()`, which discards what the
+ * upload did not read so the answer can follow. drain() resolves false if the client goes idle first.
+ */
+export declare function drainableBody(body: ReadableStream<Uint8Array>, idleMs: number): {
+    stream: ReadableStream<Uint8Array>;
+    drain: () => Promise<boolean>;
+};
+/** Decode a Content-Encoding while streaming, reporting corrupt data as UploadBodyError. */
+export declare function decodedUploadBody(body: ReadableStream<Uint8Array>, encoding: string | undefined): ReadableStream<Uint8Array>;
+/** The upload's Content-Encoding, lowercased; "identity" or none means undecoded. Throws for an unsupported one. */
+export declare function uploadEncoding(header: string | null): string | undefined;

package/dist/upload.js

@@ -0,0 +1,95 @@
+import { normalizeMessageId } from "./client/message-id.js";
+import { FILENAME } from "./tools/attachments.js";
+export const UPLOAD_PATH = "/mcp/drafts";
+/** Content-Encoding values accepted on uploads; decoded before the bytes reach fmsg. */
+export const UPLOAD_ENCODINGS = ["gzip", "deflate"];
+export const CHECKSUM_HEADER = "x-content-sha256";
+/** The PUT target for one draft's attachments, with `{filename}` left for the host to fill in. */
+export function draftUploadUrlTemplate(baseUrl, id) {
+    return `${baseUrl.replace(/\/$/u, "")}/drafts/${normalizeMessageId(id)}/attachments/{filename}`;
+}
+export function parseUploadPath(pathname) {
+    const parts = pathname.slice(UPLOAD_PATH.length + 1).split("/");
+    if (parts.length !== 3 || parts[1] !== "attachments")
+        throw new Error("invalid attachment upload path");
+    const filename = decodeURIComponent(parts[2]);
+    if (!FILENAME.test(filename) || /^\.+$/u.test(filename))
+        throw new Error("invalid attachment upload filename");
+    return { id: normalizeMessageId(parts[0]), filename };
+}
+/** The upload request's own body was unusable (such as invalid compressed data); answered with 400. */
+export class UploadBodyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UploadBodyError";
+    }
+}
+/** How long draining a failed upload's remaining body may wait for more data before the connection is closed. */
+export const UPLOAD_DRAIN_IDLE_MS = 10_000;
+/**
+ * The upload body as a stream whose cancellation leaves the request open, plus `drain()`, which discards what the
+ * upload did not read so the answer can follow. drain() resolves false if the client goes idle first.
+ */
+export function drainableBody(body, idleMs) {
+    const reader = body.getReader();
+    let stopped = false;
+    const stream = new ReadableStream({
+        async pull(controller) {
+            const chunk = await reader.read();
+            if (stopped)
+                return;
+            if (chunk.done)
+                controller.close();
+            else
+                controller.enqueue(chunk.value);
+        },
+        cancel: () => { stopped = true; },
+    });
+    const drain = async () => {
+        stopped = true;
+        for (;;) {
+            let timer;
+            const idle = new Promise((resolve) => { timer = setTimeout(() => resolve("idle"), idleMs); });
+            const next = await Promise.race([reader.read().catch(() => ({ done: true })), idle]);
+            clearTimeout(timer);
+            if (next === "idle")
+                return false;
+            if (next.done)
+                return true;
+        }
+    };
+    return { stream, drain };
+}
+/** Decode a Content-Encoding while streaming, reporting corrupt data as UploadBodyError. */
+export function decodedUploadBody(body, encoding) {
+    if (!encoding)
+        return body;
+    const reader = body.pipeThrough(new DecompressionStream(encoding)).getReader();
+    return new ReadableStream({
+        async pull(controller) {
+            let chunk;
+            try {
+                chunk = await reader.read();
+            }
+            catch (error) {
+                const code = error?.code;
+                const detail = code === "Z_BUF_ERROR" ? "the data ends early" : error instanceof Error ? error.message || code : String(error);
+                throw new UploadBodyError(`the ${encoding} request body is invalid or truncated${detail ? ` (${detail})` : ""}`);
+            }
+            if (chunk.done)
+                controller.close();
+            else
+                controller.enqueue(chunk.value);
+        },
+        cancel: (reason) => reader.cancel(reason),
+    });
+}
+/** The upload's Content-Encoding, lowercased; "identity" or none means undecoded. Throws for an unsupported one. */
+export function uploadEncoding(header) {
+    const value = header?.trim().toLowerCase();
+    if (!value || value === "identity")
+        return undefined;
+    if (!UPLOAD_ENCODINGS.includes(value))
+        throw new Error(`unsupported Content-Encoding ${JSON.stringify(header)}; use ${UPLOAD_ENCODINGS.join(" or ")}, or none`);
+    return value;
+}