@markmnl/fmsg-mcp 0.2.6 → 0.2.8

package/CHANGELOG.md

@@ -2,6 +2,56 @@
 
 ## Unreleased
 
+- `wait_for_message` no longer lets a model step past an unread message silently. Messages on other
+  threads that arrive while a batch settles are not returned and `after_id` moves past them, as
+  before; now `next` (and the text) names each one first ("Also new and not included here: message
+  40 in another thread … read it with get_thread (or get_message) "40" … before waiting again"),
+  and results add `pending_ids`. The cursor is not held back, which would replay the returned batch.
+- `get_thread` says it returns one lineage: results add `scope: "lineage"`, the description and
+  `next` say other replies in the thread (siblings and other branches) are not included and that
+  `list_messages` shows newer messages, and `complete` is described as the lineage being complete.
+  The Web API's thread routes return only the lineage, so other replies are not listed.
+- Thread messages add `no_reply`, `terminal`, `important`, `added` and `compressed`, and results add
+  the target's `no_reply`. `next` never suggests replying to a terminal message (no replies are
+  possible) or a no-reply one (the sender asked for none; `reply` refuses unless `allow_no_reply`).
+- Addresses in text results are code spans instead of Markdown-escaped text, so a model copying
+  `@bob_mcp@example.com` no longer gets `@bob\_mcp@example.com`. Address validation follows the
+  fmsg specification's user-part rule (letters and digits with single `.`, `_` or `-` between them)
+  and rejects backslashes, spaces and control characters, with a hint about Markdown escaping.
+- `size` is described as the size on the wire (the compressed length when `compressed` is true), and
+  message items add `compressed`.
+- Redaction covers more credential formats: cloud access key ids (`AKIA…`, `ASIA…`, including the
+  widely published documentation example) and 40-character secret access keys next to their usual
+  label, `gho_`/`ghs_`/`ghu_` and other source-hosting tokens (`glpat-…`), chat-platform tokens
+  (`xox…`, `xapp-…`), `AIza…` API keys, payment-platform keys (`sk_live_…`, `rk_live_…`,
+  `sk_test_…`, `whsec_…`) and `PGP PRIVATE KEY BLOCK`s. Ordinary text is left alone.
+- `download_attachment` and `save_attachment` add `type` (the same value as `content_type`). A
+  filename the message does not have now says so and lists the message's attachments instead of
+  suggesting the message may not be visible.
+- Attachments are listed in one order (by filename) by every tool, including send results.
+- `delivery_status` describes received messages (the host's own receipt records, often with code
+  null) and what `via` means.
+- `get_message` adds `thread_topic` (one thread lookup, only for replies) and shows it in the text;
+  `send_message` and `reply` results add `thread_topic` when it is known without another request.
+
+- Tool output schemas are open and additive, so hosts that cache a tool's `outputSchema` when the
+  connector is added keep validating results after upgrades. Every output object, at every depth,
+  accepts unknown properties (no `additionalProperties: false`); values that may grow (statuses,
+  transports, resolutions, delivery `status` and `via`, skip reasons, `authentication`) are strings
+  with their current values in the description instead of enums; and only fields present since
+  0.2.5 are required, so fields added later are optional in the schema though still returned.
+  Schemas published by 0.2.6 and earlier were closed, so hosts that cached one reject results with
+  newer fields ("must NOT have additional properties") until the connector is reconnected once;
+  no server change can fix an already-cached closed schema.
+- `whoami` again matches its 0.2.5 shape: `transport` is `stdio` or `http` (0.2.6 reported
+  `streamable-http`; the text still says Streamable HTTP) and `directory_names` is always present,
+  empty when there is no directory. Hosts holding 0.2.5 schemas validate `whoami`,
+  `resolve_address`, `mark_read` and `react` again. Hosts that cached 0.2.6 schemas validate every
+  tool except `whoami` over HTTP, which needs the one-time reconnect.
+- Tests check that no published output schema is closed or uses `enum`/`const`, that required
+  fields match 0.2.5, and that representative results of every tool validate against the
+  published schemas and against the 0.2.5 schemas apart from unknown properties.
+
 - Graceful shutdown. On SIGINT/SIGTERM or `HttpServerHandle.close()`, in-flight `wait_for_message`
   calls return at once with the new status `interrupted`, the caller's `after_id` and a `next`
   step ("call again with the same after_id; no messages are lost") instead of hanging until the
@@ -34,9 +84,8 @@
   count as pending rather than failed.
 - List items add `reaction` (the emoji when the item is itself a reaction). Hidden reactions never
   count as unread; `mark_read` accepts listed ones.
-- `whoami` reports `transport` as `stdio` or `streamable-http` (was `http`), says "connected over
-  Streamable HTTP", and no longer states the token expiry in its text; `token_expires_at` stays in
-  the structured result, described as internal. `directory_names` is omitted when empty.
+- `whoami` says "connected over Streamable HTTP" and no longer states the token expiry in its
+  text; `token_expires_at` stays in the structured result, described as internal.
   `resolve_address`'s description names only the resolution steps the operator configured.
 - Descriptions and errors mention `save_attachment` and `get_attachment_download_url` only where
   those tools are registered. The server instructions now state that other fmsg tools or local

package/README.md

@@ -128,28 +128,42 @@ See the [TLS reverse-proxy example](docs/http-deployment.md) for a loopback depl
 
 | Tool | What it does |
 |---|---|
-| `whoami` | The address this server acts as, the public API URL (when known), the transport (`stdio` or `streamable-http`) and short-name defaults |
+| `whoami` | The address this server acts as, the public API URL (when known), the transport (`stdio` or `http`, which is Streamable HTTP) and short-name defaults |
 | `resolve_address` | Turn a short name into `@user@domain` (directory, then default domain) |
-| `list_messages` | Inbox, newest first, with previews and attachment types; reactions hidden and never counted as unread unless `include_reactions` |
+| `list_messages` | Inbox, newest first, with previews, attachment types and wire `size` (`compressed` marks a deflated body); reactions hidden and never counted as unread unless `include_reactions` |
 | `list_sent` | Sent messages with per-recipient delivery state |
-| `get_message` | One message with headers, full text body, attachments and reactions |
-| `get_thread` | The lineage from the thread root to a message, with gaps for messages you cannot see, and the root's `thread_topic` |
+| `get_message` | One message with headers, full text body, attachments, reactions and, for a reply, the root's `thread_topic` |
+| `get_thread` | The lineage from the thread root to a message (`scope: "lineage"`; other replies in the thread are not included), with gaps for messages you cannot see, per-message flags and added recipients, the root's `thread_topic`, and a `next` step that never suggests replying to a terminal or no-reply message |
 | `send_message` | Start a new thread; sends immediately (fmsg messages are immutable) |
 | `reply` | Reply into a thread; reply-all by default, refuses terminal and no-reply parents |
 | `add_recipients` | Add `recipients` to a sent message (`add_to` is a deprecated alias) |
 | `react` | Set or clear your emoji reaction |
 | `mark_read` | Mark received messages read |
-| `download_attachment` | Fetch a small attachment inline: text as text, images as image blocks, other files as base64 resources |
+| `download_attachment` | Fetch a small attachment inline: text as text, images as image blocks, other files as base64 resources; a wrong filename lists the names the message has |
 | `get_attachment_download_url` | Get a credential-free URL and resource link for an authenticated binary download; HTTP only, requires a public MCP URL; hosts that cannot send the connection's Authorization header use `download_attachment` |
 | `save_attachment` | Stream an attachment to the configured local folder; stdio only, enabled by `FMSG_MCP_DOWNLOAD_DIR` |
-| `delivery_status` | Per-recipient delivery times and fmsg response codes (`200` accepted; `null` when not recorded) |
-| `wait_for_message` | Block until the next inbound message (WebSocket push), batched per thread, with thread context, skipped reactions and a `next` step |
+| `delivery_status` | Per-recipient delivery times and fmsg response codes (`200` accepted; `null` when not recorded); for a received message, the host's own receipt records; `via` is `to` or `add_to` (added later) |
+| `wait_for_message` | Block until the next inbound message (WebSocket push), batched per thread, with thread context, skipped reactions and a `next` step that names messages from other threads (`pending_ids`) the cursor moved past |
 
 Every tool returns readable Markdown plus `structuredContent`. Ids are decimal strings. Message
 bodies are labelled as data from other parties, not instructions; structured results that carry
 other parties' words repeat that in `untrusted_content_notice`, since some hosts show the
 structured result instead of the text. Attachment types come from the host when it recorded one,
-otherwise from the filename extension, so every tool reports the same type.
+otherwise from the filename extension, so every tool reports the same type, and every tool lists
+attachments in the same order (by filename). Addresses in the text are code spans, so they copy
+exactly (`@bob_mcp@example.com`, never with a Markdown escape); a backslash in an address is
+rejected. A message's `size` is the body's size on the wire: the compressed length when
+`compressed` is true.
+
+### Output schema compatibility
+
+Some MCP hosts cache each tool's `outputSchema` when the connector is added and validate every later
+result against that copy. Output schemas are therefore open and additive: objects accept unknown
+properties, values that may grow (statuses, transports, resolutions, delivery state) are strings
+whose current values are listed in their descriptions, and only fields present since 0.2.5 are
+required. Releases add fields and values; they do not remove or rename them. Schemas published by
+0.2.6 and earlier were closed, so a host that cached one rejects results with newer fields (for
+example "must NOT have additional properties"); remove and re-add the connector once to refresh it.
 
 Resources `fmsg://message/{id}` and `fmsg://thread/{id}` expose the same content to hosts that
 attach resources; prompts `chat` and `reply` script the wait → reply loop and a guided reply.
@@ -218,7 +232,10 @@ explain the configuration error and how to fix it; restart the MCP server after
   annotated `destructiveHint` to describe their effects. Approval behavior belongs to the AI host;
   fmsg-mcp has no additional confirmation gate.
 - Selected API-key/token formats are redacted from outbound bodies, topics and error text; the
-  send tools report the count. This is not general data-loss prevention or binary attachment scanning.
+  send tools report the count. They include fmsg API keys, JWTs, private key blocks, source-hosting
+  tokens (`ghp_…`, `github_pat_…`, `glpat-…`), cloud access key ids (`AKIA…`, `ASIA…`) and labelled
+  secret access keys, `AIza…` API keys, chat-platform tokens (`xox…`), payment-platform keys
+  (`sk_live_…`, `rk_live_…`, `sk_test_…`, `whsec_…`) and `sk-…` API keys. This is not general data-loss prevention or binary attachment scanning.
 - Nothing about message size or acceptance is assumed: the fmsg host's own responses and delivery
   codes are surfaced verbatim.
 - The server publishes MCP `instructions` (shown to the model at session start) telling agents to use

package/SECURITY.md

@@ -19,7 +19,8 @@ rather than a public issue.
   WebSocket announcements trigger protected message reads before their content reaches the host.
   The upstream contract authenticates sockets at handshake; it does not promise immediate closure
   of existing sockets on revocation. MCP does not infer ongoing authorization from a socket alone.
-- Selected key/JWT/private-key patterns are redacted from outbound message bodies, topics and errors.
+- Selected credential formats (API keys and tokens with distinctive prefixes, labelled secret access
+  keys, JWTs and private key blocks) are redacted from outbound message bodies, topics and errors.
   This does not detect arbitrary sensitive information or scan binary attachments.
 - Message bodies and upstream error text are fenced as untrusted data. Each message body has its own
   fence; server-built headers stay outside it, with external header values escaped onto one line.

package/dist/address.d.ts

@@ -2,7 +2,7 @@
  * Validate an fmsg address and normalise it to `@user@domain`. The user part keeps
  * its case: the Web API compares `from` to the token's address byte for byte, and
  * hosts may treat user names case-sensitively. Only the domain is lower-cased.
- * Returns undefined when malformed.
+ * Returns undefined when malformed, including Markdown-escaped copies such as `@bob\_x@example.com`.
  */
 export declare function normalizeFmsgAddress(value: string): string | undefined;
 /** Case-insensitive address equality. */

package/dist/address.js

@@ -1,16 +1,39 @@
 const ADDRESS = /^@([^@\s/]+)@([^@\s/]+)$/u;
+/**
+ * fmsg specification, Addresses: the user part is Unicode letters and numbers, with `-`, `_` or `.`
+ * between them (never consecutive, never first or last).
+ */
+const USER_PART = /^[\p{L}\p{N}]+(?:[-_.][\p{L}\p{N}]+)*$/u;
+/** Host names (including internationalised ones) and an optional port; no backslashes, spaces or controls. */
+const DOMAIN_PART = /^[\p{L}\p{N}\p{M}](?:[\p{L}\p{N}\p{M}._:-]*[\p{L}\p{N}\p{M}])?$/u;
+/** The specification limits a whole address to under 256 bytes. */
+const MAX_ADDRESS_BYTES = 255;
 /**
  * Validate an fmsg address and normalise it to `@user@domain`. The user part keeps
  * its case: the Web API compares `from` to the token's address byte for byte, and
  * hosts may treat user names case-sensitively. Only the domain is lower-cased.
- * Returns undefined when malformed.
+ * Returns undefined when malformed, including Markdown-escaped copies such as `@bob\_x@example.com`.
  */
 export function normalizeFmsgAddress(value) {
     const trimmed = value.trim();
     const match = ADDRESS.exec(trimmed);
-    if (!match)
+    if (!match || !USER_PART.test(match[1]) || !DOMAIN_PART.test(match[2]))
         return undefined;
-    return `@${match[1]}@${match[2].toLowerCase()}`;
+    const address = `@${match[1]}@${match[2].toLowerCase()}`;
+    return Buffer.byteLength(address, "utf8") <= MAX_ADDRESS_BYTES ? address : undefined;
+}
+/** Why a value shaped like `@user@domain` is still not a valid address. */
+function invalidAddressReason(value) {
+    const match = ADDRESS.exec(value);
+    if (!match)
+        return /^@[^@]*@[^@]*$/u.test(value) ? "it contains spaces, slashes or control characters" : undefined;
+    if (value.includes("\\"))
+        return "it contains a backslash; remove any Markdown escaping copied from formatted text";
+    if (!USER_PART.test(match[1]))
+        return "the user part may contain only letters and digits, with single . _ or - between them";
+    if (!DOMAIN_PART.test(match[2]))
+        return "the domain is not a valid host name";
+    return "it is longer than 255 bytes";
 }
 /** Case-insensitive address equality. */
 export function sameAddress(a, b) {
@@ -42,7 +65,13 @@ export function resolveAddress(name, resolver = {}) {
     const literal = normalizeFmsgAddress(trimmed);
     if (literal)
         return { address: literal, resolution: "literal" };
-    if (trimmed === "" || /[@\s/]/u.test(trimmed)) {
+    const invalid = invalidAddressReason(trimmed);
+    if (invalid)
+        throw new Error(`"${name}" is not a valid fmsg address: ${invalid}`);
+    if (trimmed.includes("\\")) {
+        throw new Error(`"${name}" contains a backslash, which no fmsg address or short name has; remove any Markdown escaping copied from formatted text`);
+    }
+    if (trimmed === "" || /[@\s/\\\p{Cc}]/u.test(trimmed)) {
         throw new Error(`"${name}" is not an fmsg address (@user@domain) or a resolvable short name`);
     }
     const key = trimmed.toLowerCase();

package/dist/client/redact.js

@@ -1,19 +1,39 @@
-/** Patterns for secrets that must never leave the process in message bodies or logs. */
+/** Not preceded or followed by another key character, so a match is a whole token. */
+const START = String.raw `(?<![A-Za-z0-9_-])`;
+const END = String.raw `(?![A-Za-z0-9_-])`;
+/**
+ * Patterns for secrets that must never leave the process in message bodies or logs. Each is a credential format
+ * with a distinctive prefix (or, for secret access keys, a distinctive label), so ordinary text is not touched.
+ */
 const PATTERNS = [
     [/\bfmsgk_[A-Za-z0-9+/=._~-]{6,}\b/gu, "[REDACTED_FMSG_API_KEY]"],
     [/\beyJ[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{4,}\b/gu, "[REDACTED_JWT]"],
     [/\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,}\b|\bgithub_pat_[A-Za-z0-9_]{22,}\b/gu, "[REDACTED_GITHUB_TOKEN]"],
+    [new RegExp(`${START}glpat-[A-Za-z0-9_-]{20,}${END}`, "gu"), "[REDACTED_ACCESS_TOKEN]"],
     [/\bsk-[A-Za-z0-9_-]{20,}\b/gu, "[REDACTED_API_KEY]"],
-    [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/gu, "[REDACTED_PRIVATE_KEY]"],
+    // Payment-platform secret, restricted and webhook-signing keys (sk_live_…, rk_test_…, whsec_…).
+    [/\b(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{16,}\b|\bwhsec_[A-Za-z0-9+/=]{24,}/gu, "[REDACTED_API_KEY]"],
+    // Cloud API keys with the AIza prefix: 39 characters in all.
+    [new RegExp(`${START}AIza[0-9A-Za-z_-]{35}${END}`, "gu"), "[REDACTED_API_KEY]"],
+    // Chat-platform bot, user, app and refresh tokens (xoxb-…, xoxp-…, xapp-…).
+    [/\bxox[abposr]-[A-Za-z0-9-]{10,}|\bxapp-[0-9]-[A-Za-z0-9-]{10,}/gu, "[REDACTED_CHAT_TOKEN]"],
+    // Cloud access key ids: long-term (AKIA…) and temporary (ASIA…), always 20 upper-case letters and digits.
+    [/\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/gu, "[REDACTED_ACCESS_KEY_ID]"],
+    // A 40-character secret access key next to its usual label (aws_secret_access_key = …, "SecretAccessKey": "…").
+    [
+        /\b((?:aws_?)?secret_?access_?key|aws_?secret_?key)(["']?\s*[:=]\s*["']?)([A-Za-z0-9/+]{40})(?![A-Za-z0-9/+=])/giu,
+        (_match, label, separator) => `${label}${separator}[REDACTED_SECRET_ACCESS_KEY]`,
+    ],
+    [/-----BEGIN [A-Z0-9 ]*PRIVATE KEY(?: BLOCK)?-----[\s\S]*?-----END [A-Z0-9 ]*PRIVATE KEY(?: BLOCK)?-----/gu, "[REDACTED_PRIVATE_KEY]"],
 ];
 /** Replace secrets with placeholders and report how many were replaced. */
 export function redactSecrets(text) {
     let count = 0;
     let out = text;
     for (const [pattern, replacement] of PATTERNS) {
-        out = out.replace(pattern, () => {
+        out = out.replace(pattern, (match, ...groups) => {
             count += 1;
-            return replacement;
+            return typeof replacement === "string" ? replacement : replacement(match, ...groups);
         });
     }
     return { text: out, count };

package/dist/client/types.d.ts

@@ -76,12 +76,17 @@ export type ThreadMessage = {
     visible: boolean;
     version?: number;
     pid?: string | null;
+    /** Flags are omitted when false. */
+    no_reply?: boolean;
+    important?: boolean;
+    terminal?: boolean;
     from?: string;
     to?: string[];
     add_to?: AddToBatch[];
     time?: number | null;
     topic?: string;
     type?: string;
+    /** Body size on the wire: the compressed size when `deflate` is true. */
     size?: number;
     deflate?: boolean;
     message_sha256?: string;

package/dist/prompts.js

@@ -16,7 +16,8 @@ export function registerPrompts(server) {
         const text = [
             `Chat over fmsg on my behalf (${mode === "keep" ? "keep replying within the thread" : "reply once to the next message"}).`,
             `1. Call wait_for_message${thread ? ` with thread_of "${thread}"` : ""}${from ? ` and from "${from}"` : ""}. On status "timeout" call it again with the same arguments; stop after ${minutes} minutes with nothing arriving.`,
-            "2. When messages arrive, tell me in one line who wrote what, then compose a reply and send it with the reply tool to reply_target_id.",
+            "2. When messages arrive, tell me in one line who wrote what, then compose a reply and send it with the reply tool to reply_target_id. " +
+                "Follow the result's next step: it also names new messages on other threads (pending_ids) that the next wait will not return.",
             mode === "keep"
                 ? `3. Call wait_for_message again with the returned after_id and the same thread_of, and repeat. Stop after ${replies} replies, when I interrupt, or when the other party says goodbye.`
                 : "3. Then stop and report back.",

package/dist/render.d.ts

@@ -23,7 +23,25 @@ export declare function attachmentType(filename: string, recorded?: string): str
 export declare function messageData(text: string): string;
 /** Keep external header values on one line and unable to introduce Markdown structure. */
 export declare function headerValue(value: string): string;
-export declare function renderMessage(message: FmsgMessage, body: string | null): string;
+/**
+ * An address for Markdown text: in a code span, so nothing inside is escaped and a model can copy it exactly
+ * (`@bob_x@example.com`, never `@bob\_x@example.com`). Values a code span cannot hold safely fall back to
+ * escaped header text.
+ */
+export declare function addressText(address: string): string;
+/** Addresses as a comma-separated list for Markdown text. */
+export declare function addressList(addresses: readonly string[]): string;
+/**
+ * Attachments in one order everywhere (by filename). The Web API reports the wire position only on thread
+ * entries, and messages sent through it share one position, so filename order is the order its hosts send in.
+ */
+export declare function sortAttachments<T extends {
+    filename: string;
+}>(attachments: readonly T[] | undefined): T[];
+/** "N bytes", noting when that is the compressed wire size. */
+export declare function sizeText(size: number | undefined, compressed: boolean | undefined): string;
+/** `threadTopic`: for a reply, its thread root's topic, shown after the parent id. */
+export declare function renderMessage(message: FmsgMessage, body: string | null, threadTopic?: string | null): string;
 /** All addresses that participate in a message (sender, recipients, add-to batches). */
 export declare function participantsOf(message: {
     from?: string;
@@ -36,5 +54,5 @@ export declare function participantsOf(message: {
 export declare function preview(message: FmsgMessage, maxChars?: number): string;
 /** One list line per message. */
 export declare function messageLine(message: FmsgMessage, self?: string): string;
-export declare function messageHeader(message: FmsgMessage): string;
+export declare function messageHeader(message: FmsgMessage, threadTopic?: string | null): string;
 export declare function fence(body: string): string;

package/dist/render.js

@@ -51,11 +51,37 @@ export function headerValue(value) {
         .replace(/\u2028/gu, "\\u2028").replace(/\u2029/gu, "\\u2029")
         .replace(/[\\`*_{}\[\]()<>|]/gu, "\\$&");
 }
-export function renderMessage(message, body) {
+/**
+ * An address for Markdown text: in a code span, so nothing inside is escaped and a model can copy it exactly
+ * (`@bob_x@example.com`, never `@bob\_x@example.com`). Values a code span cannot hold safely fall back to
+ * escaped header text.
+ */
+export function addressText(address) {
+    return /^@[^\s`\\@]+@[^\s`\\@]+$/u.test(address) && !/[\p{Cc}\p{Cf}\u2028\u2029]/u.test(address)
+        ? `\`${address}\``
+        : headerValue(address);
+}
+/** Addresses as a comma-separated list for Markdown text. */
+export function addressList(addresses) {
+    return addresses.map(addressText).join(", ");
+}
+/**
+ * Attachments in one order everywhere (by filename). The Web API reports the wire position only on thread
+ * entries, and messages sent through it share one position, so filename order is the order its hosts send in.
+ */
+export function sortAttachments(attachments) {
+    return [...(attachments ?? [])].sort((a, b) => (a.filename < b.filename ? -1 : a.filename > b.filename ? 1 : 0));
+}
+/** "N bytes", noting when that is the compressed wire size. */
+export function sizeText(size, compressed) {
+    return `${size ?? 0} bytes${compressed ? " compressed" : ""}`;
+}
+/** `threadTopic`: for a reply, its thread root's topic, shown after the parent id. */
+export function renderMessage(message, body, threadTopic) {
     const content = body === null
-        ? `[non-text body: ${headerValue(message.type ?? "?")}, ${message.size ?? 0} bytes${message.deflate ? " compressed" : ""}]`
+        ? `[non-text body: ${headerValue(message.type ?? "?")}, ${sizeText(message.size, message.deflate)}]`
         : `Body:\n${fence(body)}`;
-    return `${DATA_NOT_INSTRUCTIONS}\n\n${messageHeader(message)}\n\n${content}\n\nEnd of message data.`;
+    return `${DATA_NOT_INSTRUCTIONS}\n\n${messageHeader(message, threadTopic)}\n\n${content}\n\nEnd of message data.`;
 }
 /** All addresses that participate in a message (sender, recipients, add-to batches). */
 export function participantsOf(message) {
@@ -81,7 +107,7 @@ export function preview(message, maxChars = 200) {
 }
 /** One list line per message. */
 export function messageLine(message, self) {
-    const who = message.from.toLowerCase() === self?.toLowerCase() ? `to ${message.to.join(", ")}` : `from ${message.from}`;
+    const who = message.from.toLowerCase() === self?.toLowerCase() ? `to ${addressList(message.to)}` : `from ${addressText(message.from)}`;
     const parts = [`**${message.id}** ${who}`];
     const time = isoTime(message.time);
     parts.push(time ?? "draft");
@@ -110,21 +136,23 @@ export function messageLine(message, self) {
     const p = preview(message, 120);
     return `- ${parts.join(" · ")}${p ? `\n  ${p}` : ""}`;
 }
-export function messageHeader(message) {
+export function messageHeader(message, threadTopic) {
     const lines = [
         `**Message ${message.id}**`,
-        `From: ${headerValue(message.from)}`,
-        `To: ${message.to.map(headerValue).join(", ") || "(none)"}`,
+        `From: ${addressText(message.from)}`,
+        `To: ${addressList(message.to) || "(none)"}`,
     ];
     for (const batch of message.add_to ?? []) {
-        lines.push(`Added by ${headerValue(batch.add_to_from ?? "?")}: ${(batch.to ?? []).map(headerValue).join(", ")}`);
+        lines.push(`Added by ${batch.add_to_from ? addressText(batch.add_to_from) : "?"}: ${addressList(batch.to ?? [])}`);
     }
     lines.push(`Time: ${isoTime(message.time) ?? "draft"}`);
     if (message.topic)
         lines.push(`Topic: ${headerValue(message.topic)}`);
     if (message.pid)
         lines.push(`Reply to: ${message.pid}`);
-    lines.push(`Type: ${headerValue(message.type ?? "?")} (${message.size ?? 0} bytes${message.deflate ? " compressed" : ""})`);
+    if (message.pid && threadTopic)
+        lines.push(`Thread topic: ${headerValue(threadTopic)}`);
+    lines.push(`Type: ${headerValue(message.type ?? "?")} (${sizeText(message.size, message.deflate)})`);
     const flags = [];
     if (message.important)
         flags.push("important");
@@ -135,10 +163,10 @@ export function messageHeader(message) {
     if (flags.length)
         lines.push(`Flags: ${flags.join(", ")}`);
     if (message.attachments?.length) {
-        lines.push(`Attachments: ${message.attachments.map((a) => `${headerValue(a.filename)} (${a.size} bytes, ${headerValue(attachmentType(a.filename))})`).join(", ")}`);
+        lines.push(`Attachments: ${sortAttachments(message.attachments).map((a) => `${headerValue(a.filename)} (${a.size} bytes, ${headerValue(attachmentType(a.filename))})`).join(", ")}`);
     }
     if (message.reactions?.length) {
-        lines.push(`Reactions: ${message.reactions.map((r) => `${headerValue(r.emoji)} ${r.from.map(headerValue).join(", ")}`).join("; ")}`);
+        lines.push(`Reactions: ${message.reactions.map((r) => `${headerValue(r.emoji)} ${addressList(r.from)}`).join("; ")}`);
     }
     return lines.join("\n");
 }

package/dist/thread.d.ts

@@ -14,7 +14,14 @@ export type AssembledMessage = {
     time_posix: number | null;
     topic?: string;
     type?: string;
+    /** Wire size: the compressed length when `compressed` is true. */
     size?: number;
+    compressed?: boolean;
+    /** Flags and add-to recipients; absent for messages you cannot see. */
+    no_reply?: boolean;
+    terminal?: boolean;
+    important?: boolean;
+    added?: string[];
     body: string | null;
     body_truncated: boolean;
     /** Decoded body length when the body text was read; `size` is the wire size. */
@@ -35,6 +42,10 @@ export type AssembledThread = {
     participants: string[];
     reply_target_id: string;
     terminal: boolean;
+    /** The reply target asked for no replies. */
+    no_reply: boolean;
+    /** Always "lineage": the root down to the given message, never sibling replies or later branches. */
+    scope: "lineage";
     messages: AssembledMessage[];
     omitted: number;
 };
@@ -44,5 +55,7 @@ export type AssembledThread = {
  */
 export declare function assembleThread(client: FmsgClient, self: string, triggerId: string, caps: ThreadCaps, signal?: AbortSignal): Promise<AssembledThread>;
 export declare function renderThread(thread: AssembledThread): string;
+/** get_thread returns one lineage; say so wherever the thread is shown. */
+export declare const LINEAGE_ONLY = "Only this lineage (the root down to this message) is shown: other replies in the thread are not included; list_messages shows newer messages.";
 /** Server guidance for continuing a thread; also returned as a structured `next` field. */
-export declare function threadNext(thread: Pick<AssembledThread, "terminal" | "reply_target_id">): string;
+export declare function threadNext(thread: Pick<AssembledThread, "terminal" | "no_reply" | "reply_target_id">): string;

package/dist/thread.js

@@ -1,6 +1,18 @@
 import { sameAddress } from "./address.js";
 import { FmsgClient, FmsgHttpError } from "./client/client.js";
-import { DATA_NOT_INSTRUCTIONS, attachmentType, fence, headerValue, isoTime, participantsOf, truncateUtf8, truncationNote } from "./render.js";
+import { DATA_NOT_INSTRUCTIONS, addressList, addressText, attachmentType, fence, headerValue, isoTime, participantsOf, sizeText, sortAttachments, truncateUtf8, truncationNote, } from "./render.js";
+/** Flags, add-to recipients and wire size of a visible message, as thread entries carry them. */
+function details(m) {
+    return {
+        ...(m.type ? { type: m.type } : {}),
+        ...(typeof m.size === "number" ? { size: m.size } : {}),
+        compressed: m.deflate === true,
+        no_reply: m.no_reply === true,
+        terminal: m.terminal === true,
+        important: m.important === true,
+        added: (m.add_to ?? []).flatMap((b) => b.to ?? []),
+    };
+}
 function nonReactions(messages) {
     // Reactions are terminal no-reply leaves; they never appear on a lineage, so nothing to filter here.
     return messages;
@@ -42,12 +54,11 @@ async function fromThreadMessages(client, thread, caps, signal) {
             time: isoTime(m.time),
             time_posix: typeof m.time === "number" ? m.time : null,
             ...(m.topic ? { topic: m.topic } : {}),
-            ...(m.type ? { type: m.type } : {}),
-            ...(typeof m.size === "number" ? { size: m.size } : {}),
+            ...(m.visible ? details(m) : {}),
             body,
             body_truncated: truncated,
             ...(bodyBytes !== undefined ? { body_bytes: bodyBytes } : {}),
-            attachments: (m.attachments ?? []).map((a) => ({ filename: a.filename, size: a.size, type: attachmentType(a.filename, a.type) })),
+            attachments: sortAttachments(m.attachments).map((a) => ({ filename: a.filename, size: a.size, type: attachmentType(a.filename, a.type) })),
         });
     }
     return { messages: out, omitted, topic: root?.visible && root.id === thread.root_id ? (root.topic ?? "") : null };
@@ -97,12 +108,11 @@ async function fromPidWalk(client, triggerId, caps, signal) {
             time: isoTime(m.time),
             time_posix: typeof m.time === "number" ? m.time : null,
             ...(m.topic ? { topic: m.topic } : {}),
-            ...(m.type ? { type: m.type } : {}),
-            ...(typeof m.size === "number" ? { size: m.size } : {}),
+            ...details(m),
             body,
             body_truncated: truncated,
             ...(bodyBytes !== undefined ? { body_bytes: bodyBytes } : {}),
-            attachments: (m.attachments ?? []).map((a) => ({ filename: a.filename, size: a.size, type: attachmentType(a.filename) })),
+            attachments: sortAttachments(m.attachments).map((a) => ({ filename: a.filename, size: a.size, type: attachmentType(a.filename) })),
         });
     }
     const last = chain[chain.length - 1];
@@ -128,6 +138,8 @@ export async function assembleThread(client, self, triggerId, caps, signal) {
             participants,
             reply_target_id: trigger.id,
             terminal: trigger.terminal === true,
+            no_reply: trigger.no_reply === true,
+            scope: "lineage",
             messages,
             omitted,
         };
@@ -146,6 +158,8 @@ export async function assembleThread(client, self, triggerId, caps, signal) {
             participants,
             reply_target_id: trigger.id,
             terminal: trigger.terminal === true,
+            no_reply: trigger.no_reply === true,
+            scope: "lineage",
             messages: walk.messages,
             omitted: 0,
         };
@@ -159,7 +173,7 @@ export function renderThread(thread) {
         lines.push(`Topic: ${headerValue(thread.thread_topic)}`);
     if (thread.omitted > 0)
         lines.push(`(${thread.omitted} earlier message${thread.omitted === 1 ? "" : "s"} omitted)`);
-    lines.push(`Participants (reply-all default): ${thread.participants.map(headerValue).join(", ") || "(none)"}`);
+    lines.push(`Participants (reply-all default): ${addressList(thread.participants) || "(none)"}`);
     lines.push("");
     for (const m of thread.messages) {
         lines.push("");
@@ -167,11 +181,14 @@ export function renderThread(thread) {
             lines.push(`--- message ${m.id} [not visible to you] ---`);
             continue;
         }
-        lines.push(`--- message ${m.id} from ${headerValue(m.from ?? "?")} · ${m.time ?? "draft"}${m.pid ? ` · reply to ${m.pid}` : ""} ---`);
+        const flags = [m.important ? "important" : "", m.no_reply ? "no-reply" : "", m.terminal ? "terminal" : ""].filter(Boolean);
+        lines.push(`--- message ${m.id} from ${m.from ? addressText(m.from) : "?"} · ${m.time ?? "draft"}${m.pid ? ` · reply to ${m.pid}` : ""}${flags.length ? ` · ${flags.join(" ")}` : ""} ---`);
+        if (m.added?.length)
+            lines.push(`added: ${addressList(m.added)}`);
         if (m.attachments.length)
             lines.push(`attachments: ${m.attachments.map((a) => `${headerValue(a.filename)} (${a.size} bytes, ${headerValue(a.type)})`).join(", ")}`);
         if (m.body === null) {
-            lines.push(`[non-text body: ${headerValue(m.type ?? "?")}, ${m.size ?? 0} bytes]`);
+            lines.push(`[non-text body: ${headerValue(m.type ?? "?")}, ${sizeText(m.size, m.compressed)}]`);
             guidance.push(`Use get_message / download_attachment for message ${m.id}.`);
         }
         else {
@@ -183,9 +200,16 @@ export function renderThread(thread) {
     guidance.push(threadNext(thread));
     return [DATA_NOT_INSTRUCTIONS, lines.join("\n"), "End of message data.", ...guidance].join("\n\n");
 }
+/** get_thread returns one lineage; say so wherever the thread is shown. */
+export const LINEAGE_ONLY = "Only this lineage (the root down to this message) is shown: other replies in the thread are not included; list_messages shows newer messages.";
 /** Server guidance for continuing a thread; also returned as a structured `next` field. */
 export function threadNext(thread) {
-    return thread.terminal
-        ? `Message ${thread.reply_target_id} is terminal: it cannot be replied to.`
-        : `To continue this thread, reply to message ${thread.reply_target_id} (the reply tool).`;
+    const id = thread.reply_target_id;
+    const step = thread.terminal
+        ? `Message ${id} is terminal: no replies are possible (the host refuses them), so do not reply to it.`
+        : thread.no_reply
+            ? `Message ${id} is marked no-reply: its sender asked for no replies, and the reply tool refuses unless allow_no_reply is true. ` +
+                "Do not reply unless the user explicitly asks to."
+            : `To continue this thread, reply to message ${id} (the reply tool).`;
+    return `${step} ${LINEAGE_ONLY}`;
 }