@markmnl/fmsg-mcp 1.2.3 → 1.4.0

package/dist/tools/download.js

@@ -1,20 +1,40 @@
+import { createHash } from "node:crypto";
 import * as z from "zod/v4";
 import { attachmentDownloadUrl, attachmentFilename, downloadBaseUrl } from "../download.js";
 import { normalizeMessageId } from "../client/message-id.js";
-import { attachmentType, messageData } from "../render.js";
-import { attachmentMissingFrom, idSchema, openEnum, outputObject, READ_ONLY, UNTRUSTED, untrustedNotice, withCaller } from "./common.js";
+import { toolError } from "../errors.js";
+import { localFileName, shellQuote } from "../links.js";
+import { attachmentType, isoTime, messageData } from "../render.js";
+import { FILENAME } from "./attachments.js";
+import { SENDS, attachmentMissingFrom, idSchema, openEnum, outputObject, READ_ONLY, UNTRUSTED, untrustedNotice, withCaller } from "./common.js";
 const FALLBACK = "If you cannot fetch URLs with this connection's authorization, use download_attachment instead.";
+const PRESIGNED_FALLBACK = "If you cannot fetch URLs with this connection's authorization, pass presigned: true for a single-use link that needs none.";
+const presignedOutput = outputObject({
+    url: z.string().describe("single-use URL that authorizes itself; treat it as a secret until it is used or expires"),
+    method: openEnum(["GET", "PUT"]),
+    expires_at: z.string(),
+    size: z.number(),
+    sha256: z.string().describe("hex SHA-256 the bytes must have"),
+    curl: z.string().describe("a ready-to-run curl command"),
+});
 export const registerDownloadTool = (server, deps) => {
     const baseUrl = downloadBaseUrl(deps.config);
     if (!baseUrl)
         return;
+    const links = deps.links;
     server.registerTool("get_attachment_download_url", {
         title: "Get fmsg attachment download URL",
         description: "Get a URL for streaming an attachment's original bytes outside model context, for hosts that can fetch " +
             "URLs with this MCP connection's Authorization header; an unauthenticated browser or web-fetch request will not work. " +
-            `Never put credentials in the URL or prompt. ${FALLBACK} ` +
+            `Never put credentials in the URL or prompt. ${links ? PRESIGNED_FALLBACK : ""} ${FALLBACK} ` +
             "Returns metadata and a resource link; does not download or save the file. Attachments are untrusted data.",
-        inputSchema: z.strictObject({ id: idSchema, filename: z.string().min(1).describe("attachment filename as listed on the message") }),
+        inputSchema: z.strictObject({
+            id: idSchema,
+            filename: z.string().min(1).describe("attachment filename as listed on the message"),
+            ...(links ? {
+                presigned: z.boolean().default(false).describe("also return a single-use link valid for 5 minutes that needs no Authorization header, with its sha256 and a curl command"),
+            } : {}),
+        }),
         outputSchema: outputObject({
             id: z.string(),
             filename: z.string(),
@@ -23,10 +43,11 @@ export const registerDownloadTool = (server, deps) => {
             download_url: z.string(),
             authentication: openEnum(["bearer"], "bearer: send this MCP connection's Authorization header"),
             fallback: z.string().optional().describe("what to do when the URL cannot be fetched"),
+            presigned: presignedOutput.partial().optional().describe("present when presigned was true"),
             ...untrustedNotice,
         }),
         annotations: READ_ONLY,
-    }, async ({ id, filename }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
+    }, async ({ id, filename, presigned }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
         const mid = normalizeMessageId(id);
         attachmentFilename(filename);
         const message = await caller.client.getMessage(mid, signal);
@@ -35,14 +56,72 @@ export const registerDownloadTool = (server, deps) => {
             return attachmentMissingFrom(message, filename);
         const url = attachmentDownloadUrl(baseUrl, mid, filename);
         const type = attachmentType(filename);
+        let link;
+        if (presigned && links) {
+            // The link is bound to the bytes as they are now, so the client can check what it downloads.
+            const { stream } = await caller.client.streamAttachment(mid, filename, signal);
+            const hash = createHash("sha256");
+            let size = 0;
+            for await (const chunk of stream) {
+                hash.update(chunk);
+                size += chunk.byteLength;
+            }
+            const sha256 = hash.digest("hex");
+            const minted = links.mint(caller, { k: "get", m: mid, n: filename, s: size, h: sha256 });
+            link = {
+                url: minted.url, method: "GET", expires_at: isoTime(minted.expiresAt), size, sha256,
+                curl: `curl -fsS -o ${shellQuote(localFileName(filename))} ${shellQuote(minted.url)}`,
+            };
+        }
+        const linkText = link
+            ? `\n\nSingle-use link (GET, no Authorization header, expires ${link.expires_at}; sha256 ${link.sha256}):\n${link.curl}`
+            : "";
         return {
             content: [
                 { type: "text", text: "Download with your host's authenticated HTTP/file tools using this MCP connection's Authorization header. " +
                         `The URL contains no credentials and access is checked again when fetched. ${FALLBACK}\n\n` +
-                        messageData(`${filename} (${attachment.size} bytes, ${type}) from message ${mid}\n${url}`) },
+                        messageData(`${filename} (${attachment.size} bytes, ${type}) from message ${mid}\n${url}`) + linkText },
                 { type: "resource_link", uri: url, name: filename, size: attachment.size, mimeType: type },
             ],
-            structuredContent: { id: mid, filename, size: attachment.size, type, download_url: url, authentication: "bearer", fallback: FALLBACK, ...UNTRUSTED },
+            structuredContent: {
+                id: mid, filename, size: attachment.size, type, download_url: url, authentication: "bearer", fallback: FALLBACK,
+                ...(link ? { presigned: link } : {}), ...UNTRUSTED,
+            },
+        };
+    }));
+    if (!links)
+        return;
+    server.registerTool("get_attachment_upload_url", {
+        title: "Get fmsg draft upload URL",
+        description: "Get a single-use URL, valid for 5 minutes, that PUTs one file into a draft from create_draft without " +
+            "this connection's Authorization header, for hosts that cannot send it. The URL accepts only a file of exactly the " +
+            "given size and sha256; then call send_draft. Returns a ready-to-run curl command. The URL authorizes itself: keep it " +
+            "out of messages and share it with nobody.",
+        inputSchema: z.strictObject({
+            id: idSchema.describe("the draft"),
+            filename: z.string().regex(FILENAME, "letters, digits, dot, underscore, hyphen only").describe("attachment file name"),
+            size: z.number().int().nonnegative().describe("file size in bytes"),
+            sha256: z.string().regex(/^[0-9A-Fa-f]{64}$/u, "64 hexadecimal characters").describe("hex SHA-256 of the file"),
+            content_type: z.string().regex(/^[\x20-\x7e]+$/u).optional().describe("inferred from the filename when omitted"),
+        }),
+        outputSchema: outputObject({ draft_id: z.string(), filename: z.string(), ...presignedOutput.shape }),
+        annotations: { ...SENDS, destructiveHint: false },
+    }, async ({ id, filename, size, sha256, content_type }, 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 ${draft.id} was already sent; files can be added only to drafts`);
+        if (draft.from.toLowerCase() !== caller.address.toLowerCase())
+            return toolError(`message ${draft.id} is not your draft`);
+        if ((draft.attachments ?? []).some((a) => a.filename === filename))
+            return toolError(`draft ${draft.id} already has an attachment named ${filename}`);
+        const hex = sha256.toLowerCase();
+        const minted = links.mint(caller, { k: "put", m: draft.id, n: filename, s: size, h: hex, t: content_type ?? attachmentType(filename) });
+        const curl = `curl -fsS -X PUT --data-binary @${shellQuote(filename)} ${shellQuote(minted.url)}`;
+        const structured = { draft_id: draft.id, filename, url: minted.url, method: "PUT", expires_at: isoTime(minted.expiresAt), size, sha256: hex, curl };
+        return {
+            content: [{ type: "text", text: `Upload ${filename} (${size} bytes, sha256 ${hex}) into draft ${draft.id} before ${structured.expires_at}, ` +
+                        `then call send_draft. The link takes one upload of exactly these bytes and needs no Authorization header:\n${curl}` }],
+            structuredContent: structured,
         };
     }));
 };

package/dist/tools/draft.js

@@ -6,17 +6,18 @@ 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";
+import { parentReference, replyParent } from "./parent.js";
+import { threadRoot } from "./read.js";
+import { IMMUTABLE, IMPORTANT, NO_REPLY, hintOutput, uploadSteps, 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);
+    const routes = fileRoutes(deps.config, Boolean(deps.links));
     const includeOwner = deps.includeOwner ? { include_owner: deps.includeOwner } : {};
     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}. ` : "") +
+            (routes.uploadUrl ? `Use it for large files: ${uploadSteps(routes)}. ` : "") +
             "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"),
@@ -59,14 +60,16 @@ export const registerDraftTools = (server, deps) => {
         return withCaller(deps, ctx, async (caller, signal) => {
             let recipients;
             let resolved;
-            let pid;
+            let parentRef;
             if (reply_to) {
-                const parent = await caller.client.getMessage(reply_to, signal);
+                const parent = await replyParent(caller, reply_to, signal);
+                if ("content" in parent)
+                    return parent;
                 const target = replyRecipients(deps, caller, parent, to, allow_no_reply);
                 if ("content" in target)
                     return target;
                 ({ to: recipients, resolved } = target);
-                pid = parent.id;
+                parentRef = parentReference(caller, parent);
             }
             else {
                 ({ to: recipients, resolved } = resolveRecipients(to, resolverFor(deps, caller)));
@@ -75,8 +78,9 @@ export const registerDraftTools = (server, deps) => {
             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 ?? "" }),
+                to: recipients, body, type, important, noReply: no_reply, ...(parentRef ?? { topic: topic ?? "" }),
             }, outbound, signal);
+            const pid = parentRef?.pid;
             const upload = baseUrl ? {
                 url_template: draftUploadUrlTemplate(baseUrl, draft.id),
                 method: "PUT",
@@ -120,6 +124,10 @@ export const registerDraftTools = (server, deps) => {
             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 ?? "");
+        // The message is already sent: a failed root lookup only leaves the topic unknown.
+        const root = draft.pid ? await threadRoot(caller.client, { ...draft, id: sent.id }, signal).catch(() => ({ id: null, topic: null })) : null;
+        if (draft.pid)
+            deps.indicators.replied(caller, draft.pid, root?.id ?? null);
         const structured = {
             id: sent.id,
             time: isoTime(sent.time),
@@ -131,8 +139,7 @@ export const registerDraftTools = (server, deps) => {
             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,
+            thread_topic: root ? root.topic : 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 ?? "?"}` +

package/dist/tools/identity.js

@@ -3,14 +3,14 @@ import { CALLER_DOMAIN, effectiveDefaultDomain, resolveAddress } from "../addres
 import { addressText, isoTime } from "../render.js";
 import { READ_ONLY, ok, openEnum, outputObject, resolverFor, withCaller } from "./common.js";
 import { toolError } from "../errors.js";
-import { VERSION } from "../version.js";
+import { BUILD, VERSION, VERSION_LABEL } from "../version.js";
 /** Structured output keeps the transport ids published since 0.2.5; only the text uses the friendlier label. */
 const TRANSPORT_LABELS = { stdio: "stdio", http: "Streamable HTTP" };
 export const registerIdentityTools = (server, deps) => {
     server.registerTool("whoami", {
         title: "Show fmsg identity",
         description: "Report the fmsg address this server acts as, its owner if it is a sub-address, the fmsg Web API URL and how " +
-            "short names resolve; the text also gives the server version. Call this first if unsure who you are sending as.",
+            "short names resolve, and this server's version and build. Call this first if unsure who you are sending as.",
         outputSchema: outputObject({
             address: z.string(),
             owner: z.string().optional().describe("owner of this sub-address, included as a recipient of messages you send unless include_owner is false; absent for an owner's own address"),
@@ -19,6 +19,9 @@ export const registerIdentityTools = (server, deps) => {
             transport: openEnum(["stdio", "http"], "http is Streamable HTTP"),
             default_domain: z.string().nullable(),
             directory_names: z.array(z.string()).describe("short names in the operator-configured directory; empty when there are none"),
+            server_version: z.string().optional().describe("this fmsg-mcp server's release version"),
+            server_commit: z.string().optional().describe("the git commit this server was built from, when the build recorded it"),
+            server_build: z.string().optional().describe("git describe of the build, such as v1.2.3-4-g80e0418, when recorded"),
         }),
         annotations: { ...READ_ONLY, openWorldHint: false },
     }, async (ctx) => withCaller(deps, ctx, async (caller) => {
@@ -34,12 +37,15 @@ export const registerIdentityTools = (server, deps) => {
             transport: deps.config.transport,
             default_domain: defaultDomain ?? null,
             directory_names: directoryNames,
+            server_version: VERSION,
+            ...(BUILD.commit ? { server_commit: BUILD.commit } : {}),
+            ...(BUILD.describe ? { server_build: BUILD.describe } : {}),
         };
         const lines = [
             deps.config.apiPublicUrl
                 ? `You are ${addressText(caller.address)} on ${deps.config.apiPublicUrl}, connected over ${transport}.`
                 : `You are ${addressText(caller.address)}, connected over ${transport}.`,
-            `Access is renewed automatically. Server version ${VERSION}.`,
+            `Access is renewed automatically. Server version ${VERSION_LABEL}.`,
         ];
         if (caller.owner)
             lines.push(`Sub-address of ${addressText(caller.owner)}, who is a recipient of messages you send unless include_owner is false.`);

package/dist/tools/parent.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The parent of a reply. A recipient added to a message after it was sent (add-to) is a participant of that
+ * message only through the batch that added them, so the Web API takes their reply only with that batch's hash
+ * as the parent. They are not a participant of the rest of the thread and cannot reply there.
+ */
+import type { CallToolResult } from "@modelcontextprotocol/server";
+import type { FmsgMessage } from "../client/types.js";
+import type { Caller } from "../context.js";
+/** How a draft names its parent: the parent's id, plus the hash to reply through when the caller was added later. */
+export type ParentReference = {
+    pid: string;
+    parentSha256?: string;
+};
+/** Whether the caller was added to `message` after it was sent, rather than being its sender or a recipient. */
+export declare function addedOnly(caller: Pick<Caller, "address">, message: FmsgMessage): boolean;
+/**
+ * The parent reference for a reply from `caller` to `parent`. An added recipient replies through the hash of the
+ * batch that added them. A host that gives no batch hash predates the rule, so the id alone is sent there.
+ */
+export declare function parentReference(caller: Pick<Caller, "address">, parent: FmsgMessage): ParentReference;
+/**
+ * The message the caller was added to in the thread above `target`, when `target` is an earlier message there that
+ * the caller cannot reply to. Searches the caller's recent inbox for messages it was added to whose thread contains
+ * `target`. Returns undefined when none is found.
+ */
+export declare function addedMessageBelow(caller: Caller, target: string, signal: AbortSignal): Promise<string | undefined>;
+/** The error for a reply to a message in a thread the caller can reply to only lower down, at `added`. */
+export declare function notParticipantError(target: string, added: string): CallToolResult;
+/**
+ * Fetch the message a reply goes to. When it cannot be read because the caller is not a participant of it, but the
+ * caller was added to a later message in its thread, return an error naming that message.
+ */
+export declare function replyParent(caller: Caller, id: string, signal: AbortSignal): Promise<FmsgMessage | CallToolResult>;

package/dist/tools/parent.js

@@ -0,0 +1,77 @@
+import { sameAddress } from "../address.js";
+import { FmsgHttpError } from "../client/client.js";
+import { toolError } from "../errors.js";
+const SHA256_HEX = /^[0-9a-f]{64}$/iu;
+/** Whether the caller was added to `message` after it was sent, rather than being its sender or a recipient. */
+export function addedOnly(caller, message) {
+    if (sameAddress(message.from, caller.address) || message.to.some((a) => sameAddress(a, caller.address)))
+        return false;
+    return (message.add_to ?? []).some((b) => (b.to ?? []).some((a) => sameAddress(a, caller.address)));
+}
+/**
+ * The parent reference for a reply from `caller` to `parent`. An added recipient replies through the hash of the
+ * batch that added them. A host that gives no batch hash predates the rule, so the id alone is sent there.
+ */
+export function parentReference(caller, parent) {
+    if (!addedOnly(caller, parent))
+        return { pid: parent.id };
+    const batch = (parent.add_to ?? []).find((b) => (b.to ?? []).some((a) => sameAddress(a, caller.address)));
+    const hash = batch?.sha256;
+    return typeof hash === "string" && SHA256_HEX.test(hash) ? { pid: parent.id, parentSha256: hash.toLowerCase() } : { pid: parent.id };
+}
+/** Inbox pages searched for the message the caller was added to; only on the error path. */
+const SEARCH_PAGES = 5;
+const PAGE_SIZE = 100;
+/** Threads fetched while searching, so a large inbox cannot turn one failed reply into many requests. */
+const SEARCH_THREADS = 20;
+/**
+ * The message the caller was added to in the thread above `target`, when `target` is an earlier message there that
+ * the caller cannot reply to. Searches the caller's recent inbox for messages it was added to whose thread contains
+ * `target`. Returns undefined when none is found.
+ */
+export async function addedMessageBelow(caller, target, signal) {
+    const candidates = [];
+    for (let page = 0; page < SEARCH_PAGES; page++) {
+        const items = await caller.client.listInbox(PAGE_SIZE, page * PAGE_SIZE, signal);
+        candidates.push(...items.filter((m) => m.id !== target && addedOnly(caller, m)));
+        if (items.length < PAGE_SIZE)
+            break;
+    }
+    const direct = candidates.find((m) => m.pid === target);
+    if (direct)
+        return direct.id;
+    for (const m of candidates.filter((c) => c.pid).slice(0, SEARCH_THREADS)) {
+        try {
+            const thread = await caller.client.getThreadMessages(m.id, signal);
+            if (thread.messages.some((x) => x.id === target))
+                return m.id;
+        }
+        catch (error) {
+            if (!(error instanceof FmsgHttpError) || error.status === 401)
+                throw error;
+        }
+    }
+    return undefined;
+}
+/** The error for a reply to a message in a thread the caller can reply to only lower down, at `added`. */
+export function notParticipantError(target, added) {
+    return toolError(`You cannot reply to message ${target}: you are not a participant of it. You were added to message ${added} ` +
+        `in the same thread after it was sent, so you can reply to message ${added} instead (pass id ${added}).`);
+}
+/**
+ * Fetch the message a reply goes to. When it cannot be read because the caller is not a participant of it, but the
+ * caller was added to a later message in its thread, return an error naming that message.
+ */
+export async function replyParent(caller, id, signal) {
+    try {
+        return await caller.client.getMessage(id, signal);
+    }
+    catch (error) {
+        if (!(error instanceof FmsgHttpError) || ![403, 404].includes(error.status))
+            throw error;
+        const added = await addedMessageBelow(caller, id, signal).catch(() => undefined);
+        if (added)
+            return notParticipantError(id, added);
+        throw error;
+    }
+}

package/dist/tools/read.d.ts

@@ -2,8 +2,12 @@ import type { FmsgClient } from "../client/client.js";
 import type { FmsgMessage } from "../client/types.js";
 import { type Register } from "./common.js";
 /**
- * The topic of a reply's thread root (fmsg topics live only on the root): one thread lookup, made only for replies.
- * Null when the root is not visible or the lookup fails; a failure here never fails the read itself.
+ * A message's thread root and its topic (fmsg topics live only on the root): one thread lookup, made only for replies.
+ * The topic is null when the root is not visible, and both are null when the lookup fails; a failure here never
+ * fails the read itself.
  */
-export declare function rootTopic(client: FmsgClient, message: FmsgMessage, signal: AbortSignal): Promise<string | null>;
+export declare function threadRoot(client: FmsgClient, message: FmsgMessage, signal: AbortSignal): Promise<{
+    id: string | null;
+    topic: string | null;
+}>;
 export declare const registerReadTools: Register;

package/dist/tools/read.js

@@ -28,20 +28,21 @@ const assembledMessage = outputObject({
     attachments: z.array(attachmentItem).describe("sorted by filename, the same order in every tool"),
 });
 /**
- * The topic of a reply's thread root (fmsg topics live only on the root): one thread lookup, made only for replies.
- * Null when the root is not visible or the lookup fails; a failure here never fails the read itself.
+ * A message's thread root and its topic (fmsg topics live only on the root): one thread lookup, made only for replies.
+ * The topic is null when the root is not visible, and both are null when the lookup fails; a failure here never
+ * fails the read itself.
  */
-export async function rootTopic(client, message, signal) {
+export async function threadRoot(client, message, signal) {
     if (!message.pid)
-        return message.topic ?? "";
+        return { id: message.id, topic: message.topic ?? "" };
     try {
         const thread = await client.getThreadMessages(message.id, signal);
         const root = thread.messages[0];
-        return root?.visible && root.id === thread.root_id ? (root.topic ?? "") : null;
+        return { id: thread.root_id, topic: root?.visible && root.id === thread.root_id ? (root.topic ?? "") : null };
     }
     catch (error) {
         if (error instanceof FmsgHttpError && error.status !== 401 && !error.insufficientScope)
-            return null;
+            return { id: null, topic: null };
         throw error;
     }
 }
@@ -78,7 +79,7 @@ export const registerReadTools = (server, deps) => {
         const message = await caller.client.getMessage(id, signal);
         const text = await caller.client.getText(message, signal);
         const t = text === null ? null : truncateUtf8(text, max_body_bytes);
-        const threadTopic = await rootTopic(caller.client, message, signal);
+        const { topic: threadTopic } = await threadRoot(caller.client, message, signal);
         const structured = {
             message: toItem(message, caller.address),
             body: t?.text ?? null,
@@ -159,7 +160,7 @@ export const registerReadTools = (server, deps) => {
     server.registerTool("mark_read", {
         title: "Mark fmsg messages read",
         description: "Mark received messages as read, including reaction messages listed with include_reactions. " +
-            "Reading a message with get_message does not mark it read.",
+            "Reading a message with get_message does not mark it read. Marking a message read clears an indicator you set on it.",
         inputSchema: z.strictObject({ ids: z.array(idSchema).min(1).max(100).describe("ids of the messages to mark read (up to 100)") }),
         outputSchema: outputObject({
             marked: z.array(outputObject({ id: z.string(), time_read: z.string().nullable() })),
@@ -167,6 +168,7 @@ export const registerReadTools = (server, deps) => {
         }),
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     }, async ({ ids }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
+        deps.indicators.handled(caller, ids);
         const marked = [];
         const failed = [];
         for (const id of ids) {

package/dist/tools/send.d.ts

@@ -4,15 +4,18 @@ 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 FileRoutes, 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;
+/** UPLOAD_STEPS where get_attachment_upload_url is registered. */
+export declare const UPLOAD_STEPS_PRESIGNED: string;
+export declare function uploadSteps(routes: FileRoutes): string;
 /** How to send files without the model writing their bytes, naming only what this server registered. */
-export declare function attachmentGuidance(config: Config): string;
+export declare function attachmentGuidance(config: Config, routes?: FileRoutes): 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.

package/dist/tools/send.js

@@ -5,21 +5,29 @@ import { withOwner } from "../owner.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";
+import { parentReference, replyParent } from "./parent.js";
+import { WORKING_EMOJI } from "../indicators.js";
+import { threadRoot } from "./read.js";
 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";
+/** UPLOAD_STEPS where get_attachment_upload_url is registered. */
+export const UPLOAD_STEPS_PRESIGNED = "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, get a single-use link per file from get_attachment_upload_url " +
+    "instead; never look for or copy credentials";
+export function uploadSteps(routes) {
+    return routes.presigned ? UPLOAD_STEPS_PRESIGNED : UPLOAD_STEPS;
+}
 /** How to send files without the model writing their bytes, naming only what this server registered. */
-export function attachmentGuidance(config) {
-    const routes = fileRoutes(config);
+export function attachmentGuidance(config, routes = fileRoutes(config)) {
     const large = [
-        ...(routes.uploadUrl ? [`use create_draft instead: ${UPLOAD_STEPS}`] : []),
+        ...(routes.uploadUrl ? [`use create_draft instead: ${uploadSteps(routes)}`] : []),
         ...(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. " +
+    return "Files: data_text for text; data_base64 for small files, best effort, always with sha256. " +
         (large.length ? `For large files, ${large.join(". Or ")}. ` : "") +
         "Send files as they are; fmsg compresses them.";
 }
@@ -98,10 +106,10 @@ 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, Boolean(deps.links));
+    const attachments = z.array(attachmentInput(deps.config, routes)).optional().describe("files");
+    const guidance = attachmentGuidance(deps.config, routes);
     const includeOwner = deps.includeOwner ? { include_owner: deps.includeOwner } : {};
-    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} ` +
@@ -150,7 +158,8 @@ export const registerSendTools = (server, deps) => {
         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); " +
+            "except you; pass recipients to narrow or widen that. If you were added to the message after it was sent, you can " +
+            "reply to it but not to earlier messages in its thread. 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. ${guidance}`,
         inputSchema: z.strictObject({
             id: idSchema.describe("message to reply to"),
@@ -166,7 +175,9 @@ export const registerSendTools = (server, deps) => {
         outputSchema: sentOutput,
         annotations: SENDS,
     }, async ({ id, body, recipients, type, important, no_reply, allow_no_reply, include_owner, attachments }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
-        const parent = await caller.client.getMessage(id, signal);
+        const parent = await replyParent(caller, id, signal);
+        if ("content" in parent)
+            return parent;
         const target = replyRecipients(deps, caller, parent, recipients, allow_no_reply);
         if ("content" in target)
             return target;
@@ -174,7 +185,10 @@ export const registerSendTools = (server, deps) => {
         const to = withOwner(caller, target.to, include_owner);
         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 sent = await sendWithAttachments(caller.client, { to, ...parentReference(caller, parent), body, type, important, noReply: no_reply }, outbound, signal);
+        // The reply is already sent: a failed root lookup only leaves the topic unknown.
+        const root = await threadRoot(caller.client, parent, signal).catch(() => ({ id: null, topic: null }));
+        deps.indicators.replied(caller, parent.id, root.id);
         const structured = {
             id: sent.id,
             time: isoTime(sent.time),
@@ -187,8 +201,7 @@ export const registerSendTools = (server, deps) => {
             redacted: sent.redacted,
             ...(resolved.length ? { resolved } : {}),
             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),
+            thread_topic: root.topic,
             ...(hint ? { hint } : {}),
         };
         const topic = structured.thread_topic ? ` in "${headerValue(structured.thread_topic)}"` : "";
@@ -236,7 +249,34 @@ export const registerSendTools = (server, deps) => {
     }, async ({ id, emoji }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
         const value = emoji && emoji.trim() ? emoji.trim() : null;
         const result = await caller.client.react(id, value, signal);
+        deps.indicators.handled(caller, [id]);
         const structured = { id, reaction_id: result.id, time: isoTime(result.time), cleared: value === null };
         return ok(value ? `Reacted ${value} to message ${id}` : `Cleared your reaction on message ${id}`, structured);
     }));
+    server.registerTool("indicate", {
+        title: "Show fmsg indicator",
+        description: "Show the other participants of a message a short-lived status, such as ⏳ while you work on a reply or ✍️ while " +
+            "composing. Nothing is shown unless you call this. It is kept up while you work (up to 5 minutes) and expires on " +
+            "its own; reply, react and mark_read clear it, and an empty emoji clears it now.",
+        inputSchema: z.strictObject({
+            id: idSchema,
+            emoji: z.string().max(32).default(WORKING_EMOJI).describe("a single emoji such as ⏳ or ✍️; empty clears"),
+            ttl: z.number().int().min(1).max(120).default(60).describe("seconds it lasts unless refreshed"),
+        }),
+        outputSchema: outputObject({
+            id: z.string(),
+            emoji: z.string().describe("the emoji shown; empty when cleared"),
+            ttl: z.number().describe("seconds; 0 when cleared"),
+            cleared: z.boolean(),
+        }),
+        annotations: { ...SENDS, destructiveHint: false, idempotentHint: true },
+    }, async ({ id, emoji, ttl }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
+        const value = emoji.trim();
+        // The thread root lets a reply anywhere in the thread clear it; a failed lookup only means it is not known.
+        const rootId = value ? await caller.client.getThreadMessages(id, signal).then((thread) => thread.root_id, () => null) : null;
+        await deps.indicators.indicate(caller, id, value, ttl, rootId);
+        const structured = { id, emoji: value, ttl: value ? ttl : 0, cleared: !value };
+        return ok(value ? `Showing ${value} on message ${id} until you reply, react, mark it read or clear it (up to 5 minutes)`
+            : `Cleared your indicator on message ${id}`, structured);
+    }));
 };

package/dist/upload.d.ts

@@ -1,3 +1,4 @@
+import type { Caller } from "./context.js";
 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"];
@@ -26,3 +27,24 @@ export declare function drainableBody(body: ReadableStream<Uint8Array>, idleMs:
 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;
+/** Who keeps track of uploads to one kind of link: one at a time per file, and which were verified. */
+export type UploadTracker = {
+    begin(key: string): boolean;
+    end(key: string): void;
+    recordVerified(key: string, sha256: string): void;
+    verifiedSha256(key: string): string | undefined;
+};
+/** One file a link accepts: into which draft, under which name, and exactly which bytes. */
+export type UploadSlot = {
+    draft: string;
+    filename: string;
+    size: number;
+    sha256: string;
+    mimeType: string;
+    fileId?: string;
+};
+/**
+ * Stream one upload into a draft, refusing any body that is not exactly the slot's size and SHA-256, and a second
+ * upload after one succeeded. `noun` names the link in messages ("target", "link").
+ */
+export declare function streamIntoDraft(tracker: UploadTracker, caller: Caller, slot: UploadSlot, request: Request, encoding: string | undefined, signal: AbortSignal, noun: string): Promise<Response>;