@markmnl/fmsg-mcp 0.2.5 → 0.2.7

package/dist/tools/read.js

@@ -1,10 +1,11 @@
 import * as z from "zod/v4";
 import { ResponseLimitError } from "../client/stream.js";
 import { describeError, toolError } from "../errors.js";
+import { downloadBaseUrl } from "../download.js";
 import { messageData, isoTime, renderMessage, truncateUtf8, truncationNote } from "../render.js";
-import { assembleThread, renderThread } from "../thread.js";
-import { READ_ONLY, deliveryItem, deliveryOf, idSchema, messageItem, ok, toItem, withCaller } from "./common.js";
-const assembledMessage = z.object({
+import { assembleThread, renderThread, threadNext } from "../thread.js";
+import { READ_ONLY, UNTRUSTED, attachmentItem, deliveryItem, deliveryOf, idSchema, messageItem, ok, openEnum, outputObject, toItem, untrustedNotice, withCaller, } from "./common.js";
+const assembledMessage = outputObject({
     id: z.string(),
     pid: z.string().nullable(),
     visible: z.boolean(),
@@ -17,8 +18,17 @@ const assembledMessage = z.object({
     size: z.number().optional(),
     body: z.string().nullable(),
     body_truncated: z.boolean(),
-    attachments: z.array(z.object({ filename: z.string(), size: z.number(), type: z.string().optional() })),
+    body_bytes: z.number().optional().describe("decoded body length when the body text was read"),
+    attachments: z.array(attachmentItem),
 });
+/** Where larger attachments can go, naming only the tools this server registered. */
+function largerAttachmentRoute(deps) {
+    if (downloadBaseUrl(deps.config))
+        return "get_attachment_download_url (when your host can fetch URLs with this connection's authorization)";
+    if (deps.config.transport === "stdio" && deps.config.downloadDir)
+        return "save_attachment";
+    return "";
+}
 export const registerReadTools = (server, deps) => {
     server.registerTool("get_message", {
         title: "Get fmsg message",
@@ -30,12 +40,13 @@ export const registerReadTools = (server, deps) => {
             id: idSchema,
             max_body_bytes: z.number().int().min(0).max(1_048_576).default(65_536).describe("truncate the body beyond this many bytes"),
         }),
-        outputSchema: z.object({
+        outputSchema: outputObject({
             message: messageItem,
             body: z.string().nullable().describe("null for non-text bodies"),
             body_truncated: z.boolean(),
-            body_bytes: z.number(),
+            body_bytes: z.number().describe("decoded body length for text bodies; otherwise the size stored by the host"),
             delivery: z.array(deliveryItem),
+            ...untrustedNotice,
         }),
         annotations: READ_ONLY,
     }, async ({ id, max_body_bytes }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
@@ -46,8 +57,9 @@ export const registerReadTools = (server, deps) => {
             message: toItem(message, caller.address),
             body: t?.text ?? null,
             body_truncated: t?.truncated ?? false,
-            body_bytes: message.size ?? (t?.total ?? 0),
+            body_bytes: t?.total ?? message.size ?? 0,
             delivery: deliveryOf(message),
+            ...UNTRUSTED,
         };
         return ok(renderMessage(message, t?.text ?? null) + (t ? truncationNote(t) : ""), structured);
     }));
@@ -63,16 +75,19 @@ export const registerReadTools = (server, deps) => {
             max_body_bytes_per_message: z.number().int().min(0).max(1_048_576).default(16_384),
             max_total_bytes: z.number().int().min(0).max(8_388_608).default(262_144),
         }),
-        outputSchema: z.object({
+        outputSchema: outputObject({
             root_id: z.string(),
             trigger_id: z.string(),
             complete: z.boolean(),
-            source: z.enum(["thread_messages", "pid_walk"]),
+            source: openEnum(["thread_messages", "pid_walk"]),
+            thread_topic: z.string().nullable().optional().describe("the thread root's topic (replies carry none); null when the root is not visible"),
             participants: z.array(z.string()).describe("everyone on the target message except you (reply-all default)"),
             reply_target_id: z.string(),
             terminal: z.boolean(),
             omitted: z.number(),
             messages: z.array(assembledMessage),
+            next: z.string().optional().describe("how to continue the thread"),
+            ...untrustedNotice,
         }),
         annotations: READ_ONLY,
     }, async ({ id, max_messages, max_body_bytes_per_message, max_total_bytes }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
@@ -81,15 +96,17 @@ export const registerReadTools = (server, deps) => {
             maxBodyBytesPerMessage: max_body_bytes_per_message,
             maxTotalBytes: max_total_bytes,
         }, signal);
-        return ok(renderThread(thread), thread);
+        return ok(renderThread(thread), { ...thread, next: threadNext(thread), ...UNTRUSTED });
     }));
     server.registerTool("delivery_status", {
         title: "Check fmsg delivery",
-        description: "Per-recipient delivery state for a message this address sent: delivered time and the receiving host's " +
-            "response code, including recipients added later. Delivery to other hosts is asynchronous, so pending " +
-            "recipients may still be delivered; a non-zero code is the remote host's rejection and is reported verbatim.",
+        description: "Per-recipient delivery state for a message this address sent, including recipients added later: the " +
+            "delivered time and the receiving host's fmsg response code when known (200 means accepted; other codes, " +
+            "such as 100 user unknown or 101 user full, are rejections reported verbatim; null when not recorded, " +
+            "including some successful deliveries). Delivery to other hosts is asynchronous, so pending recipients may " +
+            "still be delivered and the host may retry temporary failures.",
         inputSchema: z.object({ id: idSchema }),
-        outputSchema: z.object({
+        outputSchema: outputObject({
             id: z.string(),
             sent_at: z.string().nullable(),
             recipients: z.array(deliveryItem),
@@ -101,7 +118,8 @@ export const registerReadTools = (server, deps) => {
         const structured = { id: message.id, sent_at: isoTime(message.time), recipients };
         const lines = [`Message ${message.id} sent ${structured.sent_at ?? "(draft, not sent)"}:`];
         for (const r of recipients) {
-            lines.push(`- ${r.addr}: ${r.status}${r.time ? ` at ${r.time}` : ""}${r.code !== null ? ` (code ${r.code})` : ""}${r.via === "add_to" ? " [added]" : ""}`);
+            const code = r.code === null ? "" : ` (code ${r.code}${r.code_meaning ? ` ${r.code_meaning}` : ""})`;
+            lines.push(`- ${r.addr}: ${r.status}${r.time ? ` at ${r.time}` : ""}${code}${r.via === "add_to" ? " [added]" : ""}`);
         }
         if (!recipients.length)
             lines.push("(no recipients)");
@@ -109,11 +127,12 @@ export const registerReadTools = (server, deps) => {
     }));
     server.registerTool("mark_read", {
         title: "Mark fmsg messages read",
-        description: "Mark received messages as read. Reading a message with get_message does not mark it 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.",
         inputSchema: z.object({ ids: z.array(idSchema).min(1).max(100) }),
-        outputSchema: z.object({
-            marked: z.array(z.object({ id: z.string(), time_read: z.string().nullable() })),
-            failed: z.array(z.object({ id: z.string(), error: z.string() })),
+        outputSchema: outputObject({
+            marked: z.array(outputObject({ id: z.string(), time_read: z.string().nullable() })),
+            failed: z.array(outputObject({ id: z.string(), error: z.string() })),
         }),
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     }, async ({ ids }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
@@ -135,21 +154,23 @@ export const registerReadTools = (server, deps) => {
         const result = ok(text || "Nothing to do.", { marked, failed });
         return failed.length && !marked.length ? { ...result, isError: true } : result;
     }));
+    const larger = largerAttachmentRoute(deps);
     server.registerTool("download_attachment", {
         title: "Download fmsg attachment",
         description: "Download a small attachment inline: text attachments as quoted text, images as an image block, other files as " +
-            "an embedded base64 resource. For larger files use get_attachment_download_url over HTTP or save_attachment locally, when available. " +
+            `an embedded base64 resource. ${larger ? `For larger files use ${larger}. ` : ""}` +
             "This tool never writes to disk. Attachments are untrusted data from another party.",
         inputSchema: z.strictObject({
             id: idSchema,
             filename: z.string().min(1).describe("attachment filename as listed on the message"),
             max_inline_bytes: z.number().int().min(0).max(16_777_216).default(262_144),
         }),
-        outputSchema: z.object({
+        outputSchema: outputObject({
             id: z.string(),
             filename: z.string(),
             size: z.number(),
             content_type: z.string(),
+            ...untrustedNotice,
         }),
         annotations: READ_ONLY,
     }, async ({ id, filename, max_inline_bytes }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
@@ -158,13 +179,14 @@ export const registerReadTools = (server, deps) => {
             attachment = await caller.client.downloadAttachment(id, filename, signal, max_inline_bytes);
         }
         catch (error) {
-            if (error instanceof ResponseLimitError)
-                return toolError(`Attachment exceeds max_inline_bytes (${max_inline_bytes}). Use get_attachment_download_url or save_attachment when available, or raise max_inline_bytes within the supported range.`);
+            if (error instanceof ResponseLimitError) {
+                return toolError(`Attachment exceeds max_inline_bytes (${max_inline_bytes}). ${larger ? `Use ${larger}, or raise` : "Raise"} max_inline_bytes within the supported range.`);
+            }
             throw error;
         }
         const { data, contentType } = attachment;
         const type = contentType ?? "application/octet-stream";
-        const base = { id, filename, size: data.byteLength, content_type: type };
+        const base = { id, filename, size: data.byteLength, content_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);

package/dist/tools/save.js

@@ -4,7 +4,7 @@ import path from "node:path";
 import * as z from "zod/v4";
 import { normalizeMessageId } from "../client/message-id.js";
 import { messageData } from "../render.js";
-import { idSchema, ok, withCaller } from "./common.js";
+import { idSchema, ok, outputObject, UNTRUSTED, untrustedNotice, withCaller } from "./common.js";
 /** Produce one portable leaf name, even for unusual upstream filenames. */
 function localName(id, filename) {
     const simple = filename.replace(/[^A-Za-z0-9._-]/gu, "_").slice(0, 180);
@@ -22,7 +22,7 @@ export const registerSaveTool = (server, deps) => {
             "Creates a new file named from its message id and filename, adding -1, -2, etc. for repeat saves; never overwrites. No destination path is accepted. " +
             "Returns the saved path and byte count. Available only in stdio when a download folder is configured.",
         inputSchema: z.strictObject({ id: idSchema, filename: z.string().min(1).regex(/^[^/\\\u0000]+$/u, "use an attachment filename without directory components") }),
-        outputSchema: z.object({ id: z.string(), filename: z.string(), saved_to: z.string(), size: z.number(), content_type: z.string() }),
+        outputSchema: outputObject({ id: z.string(), filename: z.string(), saved_to: z.string(), size: z.number(), content_type: z.string(), ...untrustedNotice }),
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     }, async ({ id, filename }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
         const mid = normalizeMessageId(id);
@@ -68,7 +68,7 @@ export const registerSaveTool = (server, deps) => {
             await file.close();
             complete = true;
             return ok(`Saved attachment (${size} bytes).\n\n${messageData(`Filename: ${filename}\nSaved to: ${target}`)}`, {
-                id: mid, filename, saved_to: target, size, content_type: contentType ?? "application/octet-stream",
+                id: mid, filename, saved_to: target, size, content_type: contentType ?? "application/octet-stream", ...UNTRUSTED,
             });
         }
         finally {

package/dist/tools/send.js

@@ -1,14 +1,18 @@
 import * as z from "zod/v4";
 import { resolveAddresses, sameAddress } from "../address.js";
 import { toolError } from "../errors.js";
-import { isoTime, participantsOf } from "../render.js";
-import { READ_ONLY, SENDS, idSchema, ok, resolverFor, withCaller } from "./common.js";
+import { attachmentType, isoTime, participantsOf } from "../render.js";
+import { SENDS, attachmentItem, idSchema, ok, outputObject, resolverFor, withCaller } from "./common.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.object({
     filename: z.string().regex(/^[A-Za-z0-9._-]+$/u, "letters, digits, dot, underscore, hyphen only"),
     data_base64: z.string().min(1),
     content_type: z.string().optional(),
 });
+/** Sent attachments with the type each was given, or the one its filename implies. */
+function sentAttachments(sent, outbound) {
+    return 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");
@@ -17,14 +21,14 @@ function decodeAttachments(items) {
         return { filename: a.filename, data: new Uint8Array(data), ...(a.content_type ? { contentType: a.content_type } : {}) };
     });
 }
-const sentOutput = z.object({
+const sentOutput = outputObject({
     id: z.string(),
     time: z.string().nullable(),
     from: z.string(),
     to: z.array(z.string()),
     topic: z.string(),
     parent_id: z.string().nullable(),
-    attachments: z.array(z.object({ filename: z.string(), size: z.number() })),
+    attachments: z.array(attachmentItem),
     redactions: z.number().describe("secrets replaced with placeholders before sending"),
     warnings: z.array(z.string()),
 });
@@ -48,6 +52,7 @@ export const registerSendTools = (server, deps) => {
         annotations: SENDS,
     }, async ({ to, topic, body, type, important, no_reply, attachments }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
         const recipients = resolveAddresses(to, resolverFor(deps, caller));
+        const outbound = decodeAttachments(attachments);
         const sent = await caller.client.send({
             to: recipients,
             topic,
@@ -55,7 +60,7 @@ export const registerSendTools = (server, deps) => {
             type,
             important,
             noReply: no_reply,
-            attachments: decodeAttachments(attachments),
+            attachments: outbound,
             signal,
         });
         const structured = {
@@ -65,7 +70,7 @@ export const registerSendTools = (server, deps) => {
             to: recipients,
             topic: sent.topic,
             parent_id: null,
-            attachments: sent.attachments,
+            attachments: sentAttachments(sent.attachments, outbound),
             redactions: sent.redactions,
             warnings: [],
         };
@@ -105,6 +110,7 @@ export const registerSendTools = (server, deps) => {
             : participantsOf(parent).filter((a) => !sameAddress(a, caller.address));
         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,
@@ -112,7 +118,7 @@ export const registerSendTools = (server, deps) => {
             type,
             important,
             noReply: no_reply,
-            attachments: decodeAttachments(attachments),
+            attachments: outbound,
             signal,
         });
         const structured = {
@@ -122,7 +128,7 @@ export const registerSendTools = (server, deps) => {
             to,
             topic: "",
             parent_id: parent.id,
-            attachments: sent.attachments,
+            attachments: sentAttachments(sent.attachments, outbound),
             redactions: sent.redactions,
             warnings,
         };
@@ -135,16 +141,26 @@ export const registerSendTools = (server, deps) => {
         description: "Add recipients to a message that was already sent (one you sent or received as a primary recipient). " +
             "They receive the message and become participants of its thread. This cannot be undone. Fails on terminal messages.",
         inputSchema: z.object({
-            id: idSchema,
-            add_to: z.array(z.string()).min(1).describe("addresses or short names to add"),
+            id: idSchema.describe("the sent message to add recipients to"),
+            recipients: z.array(z.string()).min(1).optional().describe("addresses or short names to add"),
+            add_to: z.array(z.string()).min(1).optional().describe("deprecated alias of recipients; pass one or the other"),
+        }),
+        outputSchema: outputObject({
+            id: z.string(),
+            added: z.number(),
+            recipients: z.array(z.string()).optional().describe("the resolved addresses that were added"),
+            add_to: z.array(z.string()).describe("deprecated copy of recipients"),
         }),
-        outputSchema: z.object({ id: z.string(), added: z.number(), add_to: z.array(z.string()) }),
         annotations: { ...SENDS, idempotentHint: true },
-    }, async ({ id, add_to }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
-        const addresses = resolveAddresses(add_to, resolverFor(deps, caller));
-        const result = await caller.client.addRecipients(id, addresses, signal);
-        return ok(`Added ${result.added} recipient(s) to message ${id}: ${addresses.join(", ")}`, { ...result, add_to: addresses });
-    }));
+    }, async ({ id, recipients, add_to }, ctx) => {
+        if ((recipients === undefined) === (add_to === undefined))
+            return toolError("pass recipients: the addresses to add (add_to is its deprecated alias; not both)");
+        return withCaller(deps, ctx, async (caller, signal) => {
+            const addresses = resolveAddresses((recipients ?? add_to), resolverFor(deps, caller));
+            const result = await caller.client.addRecipients(id, addresses, signal);
+            return ok(`Added ${result.added} recipient(s) to message ${id}: ${addresses.join(", ")}`, { ...result, recipients: addresses, add_to: addresses });
+        });
+    });
     server.registerTool("react", {
         title: "React to fmsg message",
         description: "Set or clear your emoji reaction on a message (one reaction per person; a new emoji replaces the previous). " +
@@ -153,7 +169,7 @@ export const registerSendTools = (server, deps) => {
             id: idSchema,
             emoji: z.string().max(32).nullable().describe("a single emoji; null or empty clears your reaction"),
         }),
-        outputSchema: z.object({ id: z.string(), reaction_id: z.string().nullable(), time: z.string().nullable(), cleared: z.boolean() }),
+        outputSchema: outputObject({ id: z.string(), reaction_id: z.string().nullable(), time: z.string().nullable(), cleared: z.boolean() }),
         annotations: { ...SENDS, destructiveHint: false, idempotentHint: true },
     }, async ({ id, emoji }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
         const value = emoji && emoji.trim() ? emoji.trim() : null;
@@ -161,6 +177,4 @@ export const registerSendTools = (server, deps) => {
         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);
     }));
-    // Kept read-only tools' annotation import in use for symmetry with other files.
-    void READ_ONLY;
 };

package/dist/tools/wait.js

@@ -3,7 +3,11 @@ import { resolveAddress } from "../address.js";
 import { assembleThread, renderThread } from "../thread.js";
 import { DATA_NOT_INSTRUCTIONS, fence, headerValue, messageData, messageLine } from "../render.js";
 import { waitForMessage } from "../wait.js";
-import { READ_ONLY, idSchema, messageItem, ok, resolverFor, toItem, withCaller } from "./common.js";
+import { READ_ONLY, UNTRUSTED, idSchema, messageItem, ok, openEnum, outputObject, resolverFor, toItem, untrustedNotice, withCaller, } from "./common.js";
+/** Skipped reactions as one line each, for the data block. */
+function reactionLines(skipped) {
+    return skipped.filter((s) => s.emoji !== undefined).map((s) => `- ${s.id} from ${headerValue(s.from)}: ${s.emoji ? `reacted ${headerValue(s.emoji)}` : "cleared a reaction"}${s.reaction_to ? ` on message ${s.reaction_to}` : ""}`);
+}
 export const registerWaitTools = (server, deps) => {
     const maxWait = deps.config.waitMaxSeconds;
     server.registerTool("wait_for_message", {
@@ -11,10 +15,15 @@ export const registerWaitTools = (server, deps) => {
         description: "Block until the next inbound message arrives (pushed over the fmsg host's WebSocket) and return it with its " +
             "thread context so you can answer with reply. Use this when the user asks you to chat, converse, keep replying, " +
             "auto-reply, or respond to the next message. Loop: wait → reply → wait again passing the after_id from the " +
-            "previous result. On status \"timeout\" simply call again with the same arguments. Messages arriving on the " +
-            "same thread within settle_seconds are batched into ONE result; reply once, to the newest (reply_target_id). " +
-            "Your own messages, reactions and no-reply messages never qualify. Each call blocks at most " +
-            `timeout_seconds (max ${maxWait}); stop looping when the user interrupts or the limits they set are reached.`,
+            "previous result. On status \"timeout\" simply call again with the same arguments and the returned after_id, " +
+            "which is never older than the newest inbox message when the call started, so nothing is replayed (\"0\" means " +
+            "the inbox was empty and is safe to pass). Messages arriving on the same thread within settle_seconds are " +
+            "batched into ONE result; reply once, to the newest (reply_target_id); the result's next field says what to do. " +
+            "Your own messages, reactions and no-reply messages never qualify; they are listed in skipped. Each call blocks " +
+            `at most timeout_seconds (max ${maxWait}); stop looping when the user interrupts or the limits they set are reached. ` +
+            "In chat hosts each wait is a model turn: tell the user you are listening and for how long rather than " +
+            "looping silently for long periods. Status \"interrupted\" means the server is restarting: call again with the " +
+            "returned after_id; no messages are lost.",
         inputSchema: z.object({
             after_id: idSchema.optional().describe("only messages with a greater id qualify; pass the after_id from the previous result. Omit on the first call to wait for messages arriving from now on"),
             thread_of: idSchema.optional().describe("only accept messages in this message's thread"),
@@ -23,17 +32,26 @@ export const registerWaitTools = (server, deps) => {
             settle_seconds: z.number().int().min(0).max(30).default(3).describe("after the first message, keep collecting same-thread messages for this long"),
             include_thread: z.boolean().default(true).describe("include the assembled thread context of the newest message"),
         }),
-        outputSchema: z.object({
-            status: z.enum(["message", "timeout"]),
+        outputSchema: outputObject({
+            status: openEnum(["message", "timeout", "interrupted"], "interrupted: the server is restarting; call again with after_id"),
             after_id: z.string().describe("pass this as after_id on the next call"),
             thread_root_id: z.string().nullable(),
+            thread_topic: z.string().nullable().optional().describe("the thread root's topic (replies carry none); null when unknown"),
             reply_target_id: z.string().nullable().describe("newest message of the batch; reply to this one"),
             messages: z.array(messageItem.extend({ body: z.string().nullable() })),
-            pending_other_threads: z.array(z.object({ id: z.string(), from: z.string(), root_id: z.string().nullable() })),
-            skipped: z.array(z.object({ id: z.string(), reason: z.enum(["own", "reaction", "no_reply", "from_mismatch", "other_thread"]) })).describe("messages deliberately passed over; after_id has advanced past them"),
-            unclassified: z.array(z.object({ id: z.string(), from: z.string(), error: z.string() })).describe("messages whose thread could not be determined; after_id is held before them, call again to retry"),
-            transport: z.enum(["websocket", "poll"]),
+            pending_other_threads: z.array(outputObject({ id: z.string(), from: z.string(), root_id: z.string().nullable() })),
+            skipped: z.array(outputObject({
+                id: z.string(),
+                reason: openEnum(["own", "reaction", "no_reply", "from_mismatch", "other_thread"]),
+                from: z.string().optional(),
+                emoji: z.string().optional().describe("for reactions: the emoji (\"\" clears a reaction)"),
+                reaction_to: z.string().nullable().optional().describe("for reactions: the message reacted to"),
+            })).describe("messages deliberately passed over; after_id has advanced past them"),
+            unclassified: z.array(outputObject({ id: z.string(), from: z.string(), error: z.string() })).describe("messages whose thread could not be determined; after_id is held before them, call again to retry"),
+            transport: openEnum(["websocket", "poll"]),
             note: z.string().nullable(),
+            next: z.string().optional().describe("what to do with this result"),
+            ...untrustedNotice,
         }),
         annotations: { ...READ_ONLY, idempotentHint: false },
     }, async ({ after_id, thread_of, from, timeout_seconds, settle_seconds, include_thread }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
@@ -42,6 +60,7 @@ export const registerWaitTools = (server, deps) => {
             ...(after_id !== undefined ? { afterId: after_id } : {}),
             ...(thread_of !== undefined ? { threadOf: thread_of } : {}),
             ...(from !== undefined ? { from: resolveAddress(from, resolverFor(deps, caller)).address } : {}),
+            ...(deps.shutdown ? { interrupt: deps.shutdown } : {}),
             timeoutMs: timeout_seconds * 1000,
             settleMs: settle_seconds * 1000,
             onTick: (elapsed) => {
@@ -57,10 +76,19 @@ export const registerWaitTools = (server, deps) => {
         }, signal);
         const messages = await Promise.all(result.messages.map(async (m) => ({ ...toItem(m, caller.address), body: await caller.client.getText(m, signal) })));
         const newest = result.messages[result.messages.length - 1];
+        const keepWaiting = `call wait_for_message with after_id "${result.after_id}"${thread_of !== undefined ? ` and thread_of "${thread_of}"` : ""} to keep listening`;
+        const next = result.status === "interrupted"
+            ? `The server is restarting; ${keepWaiting}. No messages are lost.`
+            : !newest
+                ? `No new message yet; ${keepWaiting}, unless the user's time limit is reached.`
+                : newest.terminal
+                    ? `Message ${newest.id} is terminal and cannot be replied to; ${keepWaiting}.`
+                    : `Reply to message ${newest.id} with the reply tool, then ${keepWaiting}.`;
         const structured = {
             status: result.status,
             after_id: result.after_id,
             thread_root_id: result.thread_root_id,
+            thread_topic: result.thread_topic,
             reply_target_id: newest?.id ?? null,
             messages,
             pending_other_threads: result.pending_other_threads,
@@ -68,14 +96,22 @@ export const registerWaitTools = (server, deps) => {
             unclassified: result.unclassified,
             transport: result.transport,
             note: result.note,
+            next,
+            ...UNTRUSTED,
         };
+        const reactions = reactionLines(result.skipped);
+        if (result.status === "interrupted")
+            return ok(`${next} (after_id ${result.after_id})`, structured);
         if (result.status === "timeout") {
-            return ok(`No qualifying message arrived within ${timeout_seconds}s (after_id ${result.after_id}, ${result.transport})${result.note ? `; ${result.note}` : ""}. Call again to keep waiting.`, structured);
+            const waited = `No qualifying message arrived within ${timeout_seconds}s (after_id ${result.after_id}, ${result.transport})${result.note ? `; ${result.note}` : ""}. Call again to keep waiting.`;
+            return ok(reactions.length ? `${waited}\n\nSkipped reactions:\n${messageData(reactions.join("\n"))}` : waited, structured);
         }
         const lines = [
             `${result.messages.length} new message${result.messages.length === 1 ? "" : "s"} (after_id ${result.after_id}, ${result.transport}):`,
             messageData(result.messages.map((m) => messageLine(m, caller.address)).join("\n")),
         ];
+        if (reactions.length)
+            lines.push(`Skipped reactions:\n${messageData(reactions.join("\n"))}`);
         if (result.pending_other_threads.length) {
             lines.push(`Also waiting on other threads: ${result.pending_other_threads.map((p) => p.id).join(", ")}`);
         }
@@ -90,7 +126,7 @@ export const registerWaitTools = (server, deps) => {
                 maxBodyBytesPerMessage: 16_384,
                 maxTotalBytes: 262_144,
             }, signal);
-            lines.push("", renderThread(thread));
+            lines.push("", renderThread(thread), "", next);
         }
         else if (newest) {
             lines.push("", DATA_NOT_INSTRUCTIONS);
@@ -98,7 +134,7 @@ export const registerWaitTools = (server, deps) => {
                 if (m.body !== null)
                     lines.push("", `--- message ${m.id} from ${headerValue(m.from)} ---`, fence(m.body));
             lines.push("", "End of message data.");
-            lines.push("", `Reply to message ${newest.id} with the reply tool.`);
+            lines.push("", next);
         }
         return ok(lines.join("\n"), structured);
     }));

package/dist/wait.d.ts

@@ -15,7 +15,10 @@ export type WaitOptions = {
     /** How long to wait for the WebSocket to open before falling back to polling. */
     wsOpenTimeoutMs?: number;
     onTick?: (elapsedMs: number) => void;
+    /** Server shutdown: end the wait early with status "interrupted" and a resumable cursor. */
+    interrupt?: AbortSignal;
 };
+export declare const INTERRUPTED_NOTE = "the server is restarting; call wait_for_message again with the after_id returned here; no messages are lost";
 export type Pending = {
     id: string;
     from: string;
@@ -25,6 +28,10 @@ export type SkipReason = "own" | "reaction" | "no_reply" | "from_mismatch" | "ot
 export type Skipped = {
     id: string;
     reason: SkipReason;
+    from: string;
+    /** For reactions: the emoji ("" clears) and the message reacted to. */
+    emoji?: string;
+    reaction_to?: string | null;
 };
 export type Unclassified = {
     id: string;
@@ -32,9 +39,12 @@ export type Unclassified = {
     error: string;
 };
 export type WaitResult = {
-    status: "message" | "timeout";
+    /** "interrupted": the server is shutting down; resume from after_id. */
+    status: "message" | "timeout" | "interrupted";
     after_id: string;
     thread_root_id: string | null;
+    /** The root's topic when the root was readable; replies carry no topic of their own. */
+    thread_topic: string | null;
     messages: FmsgMessage[];
     pending_other_threads: Pending[];
     /** Messages deliberately passed over (the cursor advances past these). */

package/dist/wait.js

@@ -4,6 +4,7 @@ import { compareMessageIds, maxMessageId, minMessageId } from "./client/message-
 import { safeErrorMessage } from "./client/redact.js";
 import { openFmsgWebSocket, parseWsEvent, webSocketTokenExpiresAt } from "./client/ws.js";
 import { OAuthRequestError } from "./oauth/errors.js";
+export const INTERRUPTED_NOTE = "the server is restarting; call wait_for_message again with the after_id returned here; no messages are lost";
 /**
  * Block until the next qualifying inbound message (plus any that arrive on the
  * same thread within the settle window), or until the deadline.
@@ -42,9 +43,15 @@ export async function waitForMessage(client, self, options, signal, deps = {}) {
         }
     };
     const rootCache = new Map();
+    /** Root topics seen while resolving roots, so results can name the thread without another request. */
+    const rootTopics = new Map();
     const lookupRoot = async (id) => {
         try {
-            return (await client.getThreadMessages(id, retrySignal)).root_id;
+            const thread = await client.getThreadMessages(id, retrySignal);
+            const root = thread.messages[0];
+            if (root?.visible && root.id === thread.root_id)
+                rootTopics.set(root.id, root.topic ?? "");
+            return thread.root_id;
         }
         catch (error) {
             if (authorizationFailure(error))
@@ -53,8 +60,10 @@ export async function waitForMessage(client, self, options, signal, deps = {}) {
             let cur = id;
             for (let i = 0; i < 100; i++) {
                 const m = await client.getMessage(cur, retrySignal);
-                if (!m.pid)
+                if (!m.pid) {
+                    rootTopics.set(m.id, m.topic ?? "");
                     return m.id;
+                }
                 cur = m.pid;
             }
             throw error;
@@ -122,9 +131,11 @@ export async function waitForMessage(client, self, options, signal, deps = {}) {
             clearInterval(pollTimer);
             clearInterval(tickTimer);
             signal?.removeEventListener("abort", onAbort);
+            options.interrupt?.removeEventListener("abort", onInterrupt);
             if (socket)
                 disposeSocket(socket);
         };
+        let interrupted = false;
         const finish = () => {
             if (finished)
                 return;
@@ -144,9 +155,10 @@ export async function waitForMessage(client, self, options, signal, deps = {}) {
                 note = note ? `${note}; ${held}` : held;
             }
             resolve({
-                status: batch.length ? "message" : "timeout",
+                status: batch.length ? "message" : interrupted ? "interrupted" : "timeout",
                 after_id: afterId,
                 thread_root_id: batchRoot,
+                thread_topic: batchRoot === null ? null : (rootTopics.get(batchRoot) ?? null),
                 messages: [...batch].sort((a, b) => compareMessageIds(a.id, b.id)),
                 pending_other_threads: pending,
                 skipped: [...skipped].sort((a, b) => compareMessageIds(a.id, b.id)),
@@ -165,6 +177,12 @@ export async function waitForMessage(client, self, options, signal, deps = {}) {
             note = "cancelled";
             finish();
         };
+        // Messages already collected are still returned; their cursor covers them.
+        const onInterrupt = () => {
+            interrupted = true;
+            note = batch.length ? "the server is restarting, which cut the settle window short" : INTERRUPTED_NOTE;
+            finish();
+        };
         const deadlineTimer = setTimeout(() => {
             if (batch.length && settleTimer)
                 note = "the time limit cut the settle window short";
@@ -172,8 +190,11 @@ export async function waitForMessage(client, self, options, signal, deps = {}) {
         }, Math.max(0, deadline - Date.now()));
         const tickTimer = setInterval(() => options.onTick?.(Date.now() - start), 20_000);
         signal?.addEventListener("abort", onAbort, { once: true });
+        options.interrupt?.addEventListener("abort", onInterrupt, { once: true });
         if (signal?.aborted)
             return onAbort();
+        if (options.interrupt?.aborted)
+            return onInterrupt();
         const consider = async (m) => {
             if (finished || seen.has(m.id))
                 return;
@@ -184,7 +205,8 @@ export async function waitForMessage(client, self, options, signal, deps = {}) {
             if (compareMessageIds(m.id, floor) <= 0)
                 return;
             const skip = (reason) => {
-                skipped.push({ id: m.id, reason });
+                const reaction = typeof m.reaction === "string" ? { emoji: m.reaction, reaction_to: m.pid ?? null } : {};
+                skipped.push({ id: m.id, reason, from: m.from, ...reaction });
                 if (compareMessageIds(m.id, skippedMax) > 0)
                     skippedMax = m.id;
             };

package/docs/http-deployment.md

@@ -63,13 +63,23 @@ The metadata routes are public in `oauth` and `oauth+api-key` modes and must rea
 MCP authorization discovery. In API-key mode they return 404. When OAuth is configured, its resource URL supplies
 the public same-origin value, so explicitly listing that origin is optional.
 
+## Upgrades and cached tool schemas
+
+Chat hosts may cache each tool's `outputSchema` from when the connector was added and validate
+results against it. Output schemas are open and additive (see "Output schema compatibility" in the
+README), so later upgrades keep validating. Schemas published by 0.2.6 and earlier were closed: after
+upgrading from those releases, users whose host reports that structured content does not match the
+tool's output schema must reconnect (remove and re-add) the connector once.
+
 ## Binary attachment downloads
 
 `get_attachment_download_url` returns a resource link such as
 `https://mcp.example.com/mcp/attachments/123/report.pdf`. The host fetches it with an authenticated
 GET, using the same `Authorization: Bearer ...` header as its MCP connection. OAuth requires
 `fmsg:read`; the server exchanges the incoming token for a Web API token as usual. The Web API
-checks visibility on every download, even when a link was obtained earlier.
+checks visibility on every download, even when a link was obtained earlier. Hosts that cannot send
+the connection's Authorization header with an arbitrary GET (many chat hosts cannot) should use
+`download_attachment` instead; the tool's description and result say so.
 
 Set `FMSG_MCP_PUBLIC_URL` to the exact external MCP endpoint when using API keys. OAuth defaults
 to `FMSG_MCP_OAUTH_RESOURCE_URL`; if both are set, they must match. These URLs require HTTPS outside