@markmnl/fmsg-mcp 0.2.7 → 0.2.9

package/dist/tools/send.js

@@ -1,17 +1,46 @@
 import * as z from "zod/v4";
-import { resolveAddresses, sameAddress } from "../address.js";
+import { resolveAddress, sameAddress } from "../address.js";
 import { toolError } from "../errors.js";
-import { attachmentType, isoTime, participantsOf } from "../render.js";
+import { addressList, addressText, attachmentType, headerValue, isoTime, participantsOf, sortAttachments } from "../render.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.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(),
+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"),
 });
-/** Sent attachments with the type each was given, or the one its filename implies. */
+const IMPORTANT = "mark as important for recipients";
+const NO_REPLY = "ask recipients (and their agents) not to reply";
+/**
+ * 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) {
+    const to = [];
+    const resolved = [];
+    for (const name of names) {
+        const r = resolveAddress(name, resolver);
+        if (r.resolution !== "literal")
+            resolved.push({ input: name, address: r.address });
+        if (!to.some((existing) => sameAddress(existing, r.address)))
+            to.push(r.address);
+    }
+    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");
+/** Warnings for the model to pass on: what was redacted, and short names that were expanded. */
+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.`);
+    if (resolved.length)
+        warnings.push(`Short names were resolved: ${resolved.map((r) => `${r.input} → ${r.address}`).join(", ")}.`);
+    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) {
-    return sent.map((a, i) => ({ ...a, type: attachmentType(a.filename, outbound[i]?.contentType) }));
+    return sortAttachments(sent.map((a, i) => ({ ...a, type: attachmentType(a.filename, outbound[i]?.contentType) })));
 }
 function decodeAttachments(items) {
     return (items ?? []).map((a) => {
@@ -28,30 +57,39 @@ const sentOutput = outputObject({
     to: z.array(z.string()),
     topic: z.string(),
     parent_id: z.string().nullable(),
-    attachments: z.array(attachmentItem),
+    attachments: z.array(attachmentItem).describe("sorted by filename, the same order in every tool"),
     redactions: z.number().describe("secrets replaced with placeholders before sending"),
-    warnings: z.array(z.string()),
+    redacted: z.array(z.string()).optional().describe("the kinds of secret replaced, such as github_token; empty when none"),
+    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"),
 });
+function redactionNote(count, kinds) {
+    return count ? `. ${count} secret(s) were redacted before sending (${kinds.join(", ")}).` : ".";
+}
+function resolvedNote(resolved) {
+    return resolved.length ? ` Short names resolved: ${resolved.map((r) => `${r.input} → ${addressText(r.address)}`).join(", ")}.` : "";
+}
 export const registerSendTools = (server, deps) => {
     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 (API keys, tokens) are redacted and the count reported. If the host rejects the message the host's " +
-            "own reason is returned verbatim. To continue an existing conversation use reply instead.",
-        inputSchema: z.object({
+            "Secrets are redacted. If the host rejects the message its reason is returned verbatim. " +
+            "To continue an existing conversation use reply instead.",
+        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"),
             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),
-            no_reply: z.boolean().default(false).describe("ask recipients (and their agents) not to reply"),
-            attachments: z.array(attachmentInput).optional(),
+            important: z.boolean().default(false).describe(IMPORTANT),
+            no_reply: z.boolean().default(false).describe(NO_REPLY),
+            attachments: z.array(attachmentInput).optional().describe("files"),
         }),
         outputSchema: sentOutput,
         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 { to: recipients, resolved } = resolveRecipients(to, resolverFor(deps, caller));
         const outbound = decodeAttachments(attachments);
         const sent = await caller.client.send({
             to: recipients,
@@ -72,28 +110,31 @@ export const registerSendTools = (server, deps) => {
             parent_id: null,
             attachments: sentAttachments(sent.attachments, outbound),
             redactions: sent.redactions,
-            warnings: [],
+            redacted: sent.redacted,
+            ...(resolved.length ? { resolved } : {}),
+            warnings: sendWarnings(sent.redactions, sent.redacted, resolved),
+            thread_topic: sent.topic,
         };
-        const text = `Sent message ${sent.id} "${sent.topic}" to ${recipients.join(", ")} at ${structured.time ?? "?"}` +
-            (sent.attachments.length ? ` with ${sent.attachments.map((a) => a.filename).join(", ")}` : "") +
-            (structured.redactions ? `. ${structured.redactions} secret(s) were redacted before sending.` : ".");
+        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);
     }));
     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; a parent marked no-reply " +
-            "is refused unless allow_no_reply is true. Secrets are redacted and the count reported.",
-        inputSchema: z.object({
+            "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.",
+        inputSchema: z.strictObject({
             id: idSchema.describe("message to reply to"),
-            body: z.string(),
+            body: z.string().describe("reply body; Markdown unless type says otherwise"),
             recipients: z.array(z.string()).optional().describe("override the reply-all recipient set"),
-            type: z.string().default("text/markdown; charset=utf-8"),
-            important: z.boolean().default(false),
-            no_reply: z.boolean().default(false),
+            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("reply even though the parent asked for no replies"),
-            attachments: z.array(attachmentInput).optional(),
+            attachments: z.array(attachmentInput).optional().describe("files"),
         }),
         outputSchema: sentOutput,
         annotations: SENDS,
@@ -104,10 +145,9 @@ export const registerSendTools = (server, deps) => {
         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 warnings = [];
-        const to = recipients?.length
-            ? resolveAddresses(recipients, resolverFor(deps, caller))
-            : participantsOf(parent).filter((a) => !sameAddress(a, caller.address));
+        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);
@@ -130,17 +170,23 @@ export const registerSendTools = (server, deps) => {
             parent_id: parent.id,
             attachments: sentAttachments(sent.attachments, outbound),
             redactions: sent.redactions,
-            warnings,
+            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),
         };
-        const text = `Sent reply ${sent.id} to message ${parent.id} for ${to.join(", ")} at ${structured.time ?? "?"}` +
-            (structured.redactions ? `. ${structured.redactions} secret(s) were redacted before sending.` : ".");
+        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);
     }));
     server.registerTool("add_recipients", {
         title: "Add fmsg recipients",
         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({
+            "They receive the message and its attachments, can read it and become participants of its thread. " +
+            "This cannot be undone. Fails on terminal messages.",
+        inputSchema: z.strictObject({
             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"),
@@ -149,6 +195,7 @@ export const registerSendTools = (server, deps) => {
             id: z.string(),
             added: z.number(),
             recipients: z.array(z.string()).optional().describe("the resolved addresses that were added"),
+            resolved: resolvedOutput,
             add_to: z.array(z.string()).describe("deprecated copy of recipients"),
         }),
         annotations: { ...SENDS, idempotentHint: true },
@@ -156,16 +203,16 @@ export const registerSendTools = (server, deps) => {
         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 { to: addresses, resolved } = resolveRecipients((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 });
+            return ok(`Added ${result.added} recipient(s) to message ${id}: ${addressList(addresses)}`, { ...result, recipients: addresses, ...(resolved.length ? { resolved } : {}), 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). " +
             "Sends a small reaction message to the other participants. Fails on drafts and terminal messages.",
-        inputSchema: z.object({
+        inputSchema: z.strictObject({
             id: idSchema,
             emoji: z.string().max(32).nullable().describe("a single emoji; null or empty clears your reaction"),
         }),

package/dist/tools/wait.js

@@ -1,34 +1,50 @@
 import * as z from "zod/v4";
+import { compareMessageIds } from "../client/message-id.js";
 import { resolveAddress } from "../address.js";
 import { assembleThread, renderThread } from "../thread.js";
-import { DATA_NOT_INSTRUCTIONS, fence, headerValue, messageData, messageLine } from "../render.js";
+import { DATA_NOT_INSTRUCTIONS, addressText, fence, headerValue, messageData, messageLine } from "../render.js";
 import { waitForMessage } from "../wait.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}` : ""}`);
+    return skipped.filter((s) => s.emoji !== undefined).map((s) => `- ${s.id} from ${addressText(s.from)}: ${s.emoji ? `reacted ${headerValue(s.emoji)}` : "cleared a reaction"}${s.reaction_to ? ` on message ${s.reaction_to}` : ""}`);
+}
+/**
+ * Messages that arrived on other threads (or beyond the batch limit) during the settle window. They are not
+ * returned and after_id moves past them, so the next step must name each one; otherwise a model following `next`
+ * never sees them.
+ */
+function pendingStep(pending, batchRoot) {
+    if (!pending.length)
+        return "";
+    const described = pending.map((p) => {
+        const where = p.root_id === null ? "" : p.root_id === batchRoot ? " in this thread (beyond the batch limit)" : ` in another thread (root ${p.root_id})`;
+        return `message ${p.id}${where}`;
+    });
+    const many = pending.length > 1;
+    return `Also new and not included here: ${described.join(", ")}. after_id has moved past ${many ? "them" : "it"}, so ` +
+        `the next wait will not return ${many ? "them" : "it"}: read ${many ? "each" : "it"} with get_thread (or get_message) ` +
+        `${pending.map((p) => `"${p.id}"`).join(", ")} and reply if appropriate before waiting again.`;
 }
 export const registerWaitTools = (server, deps) => {
     const maxWait = deps.config.waitMaxSeconds;
     server.registerTool("wait_for_message", {
         title: "Wait for next fmsg message",
-        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 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({
+        description: "Block until the next inbound message arrives and return it with its thread context, so you can answer with reply.\n" +
+            "When: the user asks you to chat, keep replying or respond to the next message.\n" +
+            "Loop: wait → reply → wait again, passing each result's after_id. On \"timeout\" or \"interrupted\" (server " +
+            "restart) call again with the returned after_id; nothing is replayed or lost. Same-thread messages arriving " +
+            "within settle_seconds come as ONE result: reply once, to reply_target_id; next says what to do.\n" +
+            "Skipped: your own messages, reactions and no-reply messages (listed in skipped). Messages on other threads " +
+            "are not returned: after_id moves past them and pending_ids lists them; read them with get_thread before " +
+            "waiting again.\n" +
+            `Limits: each call blocks at most timeout_seconds (max ${maxWait}). In chat hosts each wait is a model turn: ` +
+            "tell the user you are listening and for how long, and stop when they interrupt or their limits are reached.",
+        inputSchema: z.strictObject({
             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"),
             from: z.string().optional().describe("only accept messages from this address or short name"),
-            timeout_seconds: z.number().int().min(1).max(maxWait).default(Math.min(90, maxWait)),
+            timeout_seconds: z.number().int().min(1).max(maxWait).default(Math.min(90, maxWait)).describe("longest this call blocks"),
             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"),
         }),
@@ -39,7 +55,8 @@ export const registerWaitTools = (server, deps) => {
             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(outputObject({ id: z.string(), from: z.string(), root_id: z.string().nullable() })),
+            pending_other_threads: z.array(outputObject({ id: z.string(), from: z.string(), root_id: z.string().nullable() })).describe("new messages not returned here (other threads, or beyond the batch limit); after_id has moved past them, so read each with get_thread or get_message"),
+            pending_ids: z.array(z.string()).optional().describe("ids of pending_other_threads, oldest first: read these before waiting again"),
             skipped: z.array(outputObject({
                 id: z.string(),
                 reason: openEnum(["own", "reaction", "no_reply", "from_mismatch", "other_thread"]),
@@ -77,13 +94,16 @@ export const registerWaitTools = (server, deps) => {
         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 pending = [...result.pending_other_threads].sort((a, b) => compareMessageIds(a.id, b.id));
+        const alsoNew = pendingStep(pending, result.thread_root_id);
+        const thenWait = alsoNew ? `${alsoNew} Then ${keepWaiting}.` : "";
         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}.`;
+                    ? `Message ${newest.id} is terminal and cannot be replied to.${thenWait ? ` ${thenWait}` : ` Next, ${keepWaiting}.`}`
+                    : `Reply to message ${newest.id} with the reply tool.${thenWait ? ` ${thenWait}` : ` Then ${keepWaiting}.`}`;
         const structured = {
             status: result.status,
             after_id: result.after_id,
@@ -91,7 +111,8 @@ export const registerWaitTools = (server, deps) => {
             thread_topic: result.thread_topic,
             reply_target_id: newest?.id ?? null,
             messages,
-            pending_other_threads: result.pending_other_threads,
+            pending_other_threads: pending,
+            pending_ids: pending.map((p) => p.id),
             skipped: result.skipped,
             unclassified: result.unclassified,
             transport: result.transport,
@@ -112,9 +133,6 @@ export const registerWaitTools = (server, deps) => {
         ];
         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(", ")}`);
-        }
         if (result.unclassified.length) {
             lines.push(`Could not classify ${result.unclassified.map((u) => u.id).join(", ")}; after_id is held before them, call again to retry.`);
         }
@@ -132,7 +150,7 @@ export const registerWaitTools = (server, deps) => {
             lines.push("", DATA_NOT_INSTRUCTIONS);
             for (const m of messages)
                 if (m.body !== null)
-                    lines.push("", `--- message ${m.id} from ${headerValue(m.from)} ---`, fence(m.body));
+                    lines.push("", `--- message ${m.id} from ${addressText(m.from)} ---`, fence(m.body));
             lines.push("", "End of message data.");
             lines.push("", next);
         }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@markmnl/fmsg-mcp",
   "mcpName": "io.github.markmnl/fmsg-mcp",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "MCP server for fmsg: send and receive federated messages from any AI agent via a deployed fmsg Web API",
   "type": "module",
   "license": "MIT",

package/server.json

@@ -8,13 +8,13 @@
     "url": "https://github.com/markmnl/fmsg-mcp",
     "source": "github"
   },
-  "version": "0.2.7",
+  "version": "0.2.9",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@markmnl/fmsg-mcp",
-      "version": "0.2.7",
+      "version": "0.2.9",
       "transport": {
         "type": "stdio"
       },