@markmnl/fmsg-mcp 1.2.3 → 1.4.0

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## Unreleased
 
+- FMSG-006 indicators. The new `indicate` tool shows the other participants of a message a short-lived
+  status such as ⏳ or ✍️, refreshed at half its ttl (every 1–30 s) and cleared when the agent replies in
+  that thread, reacts, marks it read, after 5 minutes, or when the session ends; an empty emoji clears it
+  now. Nothing is shown automatically: reading a message never starts one. Refreshes and automatic clears
+  are best effort and never fail a tool. `FmsgClient.indicate()` posts to `/fmsg/{id}/indicate`;
+  `createFmsgMcpServer` takes an optional shared `indicators` registry for per-request HTTP factories.
+- Presigned links for hosts that cannot send the connection's Authorization header with their own HTTP
+  requests: `get_attachment_download_url` with `presigned: true`, and the new `get_attachment_upload_url` for
+  draft files. Each link is single-use, valid for 5 minutes and bound to one file's size and sha256 (`/mcp/links/{token}`),
+  and comes with its `expires_at`, `size`, `sha256` and a ready-to-run `curl` command. A download whose
+  attachment changed since the link was issued is refused or cut off before its last bytes. `FMSG_MCP_STATE_SECRET` (at least 32 bytes)
+  sets the signing key.
+- `data_base64` is described as best effort, because the base64 passes through the model: fine for small
+  files (verified exact up to 16 KB), always with `sha256`, and `path` or a presigned link for anything larger.
+- A recipient added to a message after it was sent can reply to it. The Web API takes such a reply only
+  through the hash of the add-to batch that added them; `reply`, `create_draft` (and so `send_draft`) now
+  send it as the parent, where before the host refused with "not a participant of this parent". A reply
+  from an added recipient to an earlier message in the thread, which they cannot reply to, is refused with
+  an error naming the message they were added to.
+- `whoami` reports the server version in its structured result (`server_version`, plus `server_commit` and
+  `server_build` when recorded), not only in its text, which hosts that show models only the structured
+  result never passed on. `/healthz` adds the commit. `npm run build` records the version and commit from
+  git; the Docker image takes them as build arguments. Builds from source no longer report the stale
+  `package.json` version 0.1.4: it now matches the last release, and a release tag takes precedence.
+
 - Over OAuth, the owner comes from the `owner` claim the IdP puts on the app's access token
   (and on the exchanged Web API token), so agents that sign in (ChatGPT connectors) include
   their owner like API-key callers do. 1.2.0 only read the API-key token's claim, so a

package/README.md

@@ -98,12 +98,16 @@ server exchanges it at the fmsg host and acts as that address. `FMSG_API_KEY` mu
 FMSG_API_URL=https://api.example.com FMSG_MCP_ALLOWED_HOSTS=mcp.example.com \
   npx -y @markmnl/fmsg-mcp --http 0.0.0.0:8765
 # or
-docker build -t fmsg-mcp .
+docker build -t fmsg-mcp --build-arg FMSG_MCP_COMMIT=$(git rev-parse HEAD) \
+  --build-arg FMSG_MCP_VERSION=$(git describe --tags --abbrev=0) .
 docker run -e FMSG_API_URL=https://api.example.com \
   -e FMSG_MCP_ALLOWED_HOSTS=mcp.example.com -p 8765:8765 fmsg-mcp
 ```
 
-The MCP endpoint is `/mcp`; `/healthz` reports liveness. Use a client that supports an explicitly
+The MCP endpoint is `/mcp`; `/healthz` reports liveness, the version and the commit. `whoami` reports the
+same, so a client can confirm which deploy it is talking to: `npm run build` records them from git, and the
+Docker build arguments above do so where the build has no git history (`FMSG_MCP_COMMIT` can also be set at
+run time). Use a client that supports an explicitly
 configured `Authorization: Bearer fmsgk_...` header. Each caller supplies its own key; a shared
 header means a shared fmsg identity. For browser sign-in without user API keys, configure
 [HTTP OAuth](docs/oauth.md): the operator supplies an issuer, resource URI and exchange client.
@@ -133,7 +137,7 @@ 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, its `owner` if it is a sub-address, the public API URL (when known), the transport (`stdio` or `http`, which is Streamable HTTP) and short-name defaults |
+| `whoami` | The address this server acts as, its `owner` if it is a sub-address, the public API URL (when known), the transport (`stdio` or `http`, which is Streamable HTTP), short-name defaults, and this server's version and commit |
 | `resolve_address` | Turn a short name into `@user@domain` (directory, then default domain) |
 | `list_messages` | Inbox, newest first, with previews, attachment types and `size` (`compressed` marks a body sent deflated); reactions hidden and never counted as unread unless `include_reactions` |
 | `list_sent` | Sent messages with per-recipient delivery state |
@@ -146,9 +150,11 @@ See the [TLS reverse-proxy example](docs/http-deployment.md) for a loopback depl
 | `delete_draft` | Discard an unsent draft |
 | `add_recipients` | Add `recipients` to a sent message (`add_to` is a deprecated alias) |
 | `react` | Set or clear your emoji reaction |
+| `indicate` | Show the other participants a short-lived status on a message, such as ⏳ while working on a reply or ✍️ while composing (FMSG-006 indicator; `ttl` 1–120 s, default 60), kept up until you reply, react or mark it read (up to 5 minutes); an empty `emoji` clears it. Reading a message never shows one |
 | `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; 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` |
+| `get_attachment_download_url` | Get a credential-free URL and resource link for an authenticated binary download; with `presigned: true`, also a single-use link valid for 5 minutes that needs no Authorization header, with its size, sha256 and a curl command. HTTP only, requires a public MCP URL |
+| `get_attachment_upload_url` | Get a single-use link valid for 5 minutes that PUTs one file of a given size and sha256 into a draft without the Authorization header, with a curl command; then `send_draft`. HTTP only, requires a public MCP URL |
 | `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); 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 |
@@ -174,6 +180,21 @@ required. Releases add fields and values; they do not remove or rename them. Sch
 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.
 
+### Indicators
+
+`indicate` shows a message's other participants a short-lived status, such as ⏳ while the agent
+works on a reply or ✍️ while composing: an
+[FMSG-006](https://github.com/markmnl/fmsg/blob/main/standards/fmsg-006-indicators.md) indicator.
+Nothing is shown unless the agent calls it; reading a message never does. It is sent at once with
+its `ttl` (default 60 s) and refreshed at half the ttl (every 1–30 s) until the agent replies to
+that message or anywhere in its thread (`reply`, or `send_draft` of a reply), reacts to it, marks it
+read, clears it with an empty `emoji`, or after 5 minutes, and when the session ends or the server
+shuts down. At most 10 are kept up per address, the oldest cleared first. `indicate` returns the
+host's refusal (such as a terminal message, or a host without indicators); refreshes and automatic
+clears are best effort and never fail another tool. Over HTTP each MCP request gets a fresh server
+instance, so indicators are kept per address by the HTTP server; embedders that build one server per
+request pass a shared `IndicatorRegistry` as `indicators`.
+
 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, and
 `send_file` sends files by the most efficient route the server offers.
@@ -193,6 +214,7 @@ attach resources; prompts `chat` and `reply` script the wait → reply loop and
 | `FMSG_MCP_DOWNLOAD_DIR` | — | Enable `save_attachment` in stdio; folder for new files named from message ID and filename |
 | `FMSG_MCP_UPLOAD_DIR` | — | Allow attachment `path` arguments in stdio: files in this folder (or below it) are read by the server instead of written out by the model |
 | `FMSG_MCP_WAIT_MAX_SECONDS` | `230` | Cap on one `wait_for_message` call |
+| `FMSG_MCP_STATE_SECRET` | per-process random | At least 32 bytes; HMAC key for presigned links. Links still work only on the instance that issued them |
 | `FMSG_MCP_HOST` / `FMSG_MCP_PORT` | `127.0.0.1` / `8765` | HTTP bind address (or `--http host:port`) |
 | `FMSG_MCP_ALLOWED_HOSTS` | loopback names | Comma-separated `Host` header allowlist; required for non-loopback binds |
 | `FMSG_MCP_ALLOWED_ORIGINS` | same origin; loopback origins on loopback binds | Comma-separated browser origins including scheme and port; an explicit list replaces the loopback default; hostname-only values are rejected |
@@ -229,7 +251,9 @@ original Content-Type and download filename. No files are stored on the MCP serv
 
 `send_message`, `reply` and `create_draft` take each attachment as exactly one of:
 
-- `data_base64`: base64 written by the model; fine for small files. The standard or URL-safe
+- `data_base64`: base64 written by the model. It passes through the model, so it is best effort: fine
+  for small files (verified exact up to 16 KB). Always pass `sha256` with it, and prefer `path` or a
+  presigned upload link for anything larger. The standard or URL-safe
   alphabet is accepted, but not both in one value. Decoding is strict: any other character, a bad
   length or padding, or a stray ending is refused with the attachment's name, rather than sent as a
   corrupted file.
@@ -244,6 +268,13 @@ with `x-content-sha256`), then `send_draft`; see
 [attachment uploads](docs/http-deployment.md#attachment-uploads). Send files as they are: fmsg
 compresses message bodies and attachments itself when it sends them.
 
+Hosts that cannot attach the connection's credentials to their own HTTP requests can still keep file
+bytes out of the model. `get_attachment_upload_url` returns a single-use, 5-minute link per draft
+file, bound to its size and sha256, with a ready-to-run `curl` command. `get_attachment_download_url`
+with `presigned: true` does the same for downloads. The link itself authorizes that one transfer. It
+holds no API key or access token, but treat it as a secret until it is used or expires. It works only
+on the server instance that issued it.
+
 Models learn the routes from the server instructions and tool descriptions, which name only the
 routes the running server offers. A model that writes a large file as base64 although a better
 route exists gets a `hint` in the result naming it. The `send_file` prompt walks through the best

package/dist/build-info.json

@@ -0,0 +1,5 @@
+{
+  "version": "1.4.0",
+  "commit": "36e8dafb2afbee867f5518c63b662cd500f24ddb",
+  "describe": "v1.4.0"
+}

package/dist/client/client.d.ts

@@ -90,6 +90,12 @@ export declare class FmsgClient {
         added: number;
     }>;
     react(id: string, emoji: string | null, signal?: AbortSignal): Promise<ReactResult>;
+    /**
+     * Show an FMSG-006 indicator, a short-lived emoji such as ⏳, on a message to its other participants for `ttl`
+     * seconds (1 to 120; the host clamps it). An empty emoji or a ttl of 0 clears it. The host answers 202 with no body
+     * and may drop indicators set more than once a second on one message. Hosts without indicators answer 404 or 405.
+     */
+    indicate(id: string, emoji: string, ttl: number, signal?: AbortSignal): Promise<void>;
     downloadAttachment(id: string, filename: string, signal?: AbortSignal, maxBytes?: number): Promise<{
         data: Uint8Array;
         contentType?: string;

package/dist/client/client.js

@@ -307,6 +307,21 @@ export class FmsgClient {
             time: result.time ?? null,
         };
     }
+    /**
+     * Show an FMSG-006 indicator, a short-lived emoji such as ⏳, on a message to its other participants for `ttl`
+     * seconds (1 to 120; the host clamps it). An empty emoji or a ttl of 0 clears it. The host answers 202 with no body
+     * and may drop indicators set more than once a second on one message. Hosts without indicators answer 404 or 405.
+     */
+    async indicate(id, emoji, ttl, signal) {
+        const mid = normalizeMessageId(id);
+        const response = await this.request(`/fmsg/${encodeURIComponent(mid)}/indicate`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ emoji, ttl: emoji ? ttl : 0 }),
+            ...(signal ? { signal } : {}),
+        });
+        await response.body?.cancel();
+    }
     async downloadAttachment(id, filename, signal, maxBytes) {
         const { stream, contentType } = await this.streamAttachment(id, filename, signal);
         const { data } = await readBytes(stream, maxBytes);
@@ -340,7 +355,9 @@ export class FmsgClient {
             ...(input.important ? { important: true } : {}),
             ...(input.noReply ? { no_reply: true } : {}),
         };
-        const serialized = input.pid ? stringifyWithIds(body, { pid: input.pid }) : JSON.stringify(body);
+        // The Web API takes the parent as a numeric id or a hash string; an added recipient must use their batch's hash.
+        const serialized = input.parentSha256 ? JSON.stringify({ ...body, pid: input.parentSha256 })
+            : input.pid ? stringifyWithIds(body, { pid: input.pid }) : JSON.stringify(body);
         const response = await this.request("/fmsg", {
             method: "POST",
             headers: { "content-type": "application/json" },
@@ -361,6 +378,9 @@ export class FmsgClient {
             throw new Error("at least one recipient is required");
         if (input.pid && input.topic)
             throw new Error("a reply (pid) cannot carry a topic");
+        if (input.parentSha256 !== undefined && (!input.pid || !/^[0-9a-f]{64}$/u.test(input.parentSha256))) {
+            throw new Error("parentSha256 must be 64 lowercase hexadecimal characters, given with pid");
+        }
         const from = await this.address(input.signal);
         const body = redactSecrets(input.body);
         const topic = redactSecrets(input.pid ? "" : (input.topic ?? ""));

package/dist/client/types.d.ts

@@ -10,6 +10,8 @@ export type RecipientDelivery = {
     response_code: number | null;
 };
 export type AddToBatch = {
+    /** The batch's protocol hash (lowercase hex). A recipient added only by this batch replies with it as the parent. */
+    sha256?: string | null;
     batch_id?: string;
     add_to_from?: string;
     to?: string[];
@@ -27,6 +29,10 @@ export type ReactionGroup = {
 export type FmsgMessage = {
     /** Present on list items and WebSocket events; absent on GET /fmsg/:id (filled in by the client). */
     id: string;
+    /** Protocol hash (lowercase hex); null for drafts and on hosts that predate message hashes. */
+    sha256?: string | null;
+    /** The exact parent hash: the parent message's, or the add-to batch's a reply was made through. */
+    psha256?: string | null;
     version?: number;
     has_pid?: boolean;
     has_add_to?: boolean;
@@ -121,6 +127,11 @@ export type SendInput = {
     type?: string;
     topic?: string;
     pid?: string;
+    /**
+     * Reply through this hash instead of `pid`: the add-to batch that added the sender to the parent. A recipient
+     * added after a message was sent may reply to it only this way. `pid` must still name the parent.
+     */
+    parentSha256?: string;
     important?: boolean;
     noReply?: boolean;
     attachments?: OutboundAttachment[];

package/dist/config.d.ts

@@ -11,6 +11,11 @@ export type HttpConfig = {
     allowedOrigins: string[];
     keyCacheMax: number;
     keyCacheTtlMs: number;
+    /**
+     * FMSG_MCP_STATE_SECRET: the HMAC key for presigned links, file-upload targets and requestState, so any instance
+     * can verify what another issued. Without it each process makes its own.
+     */
+    stateSecret?: string;
 };
 export type Config = {
     transport: Transport;

package/dist/config.js

@@ -55,6 +55,15 @@ function resolveApiPublicUrl(env, transport, apiUrl, allowInsecureHttp) {
         return undefined;
     return apiUrl;
 }
+/** FMSG_MCP_STATE_SECRET, checked; HTTP only. */
+function stateSecret(env, transport) {
+    const secret = env.FMSG_MCP_STATE_SECRET?.trim();
+    if (transport !== "http" || !secret)
+        return undefined;
+    if (Buffer.byteLength(secret) < 32)
+        throw new Error("FMSG_MCP_STATE_SECRET must be at least 32 bytes");
+    return secret;
+}
 export function loadConfig(env, transport, overrides = {}, options = {}) {
     const requireCredentials = options.requireCredentials ?? true;
     const oauth = loadOAuthConfig(env, transport);
@@ -106,6 +115,7 @@ export function loadConfig(env, transport, overrides = {}, options = {}) {
             allowedOrigins: listEnv(env, "FMSG_MCP_ALLOWED_ORIGINS").map(normalizeOrigin),
             keyCacheMax: intEnv(env, "FMSG_MCP_KEY_CACHE_MAX", 500),
             keyCacheTtlMs: intEnv(env, "FMSG_MCP_KEY_CACHE_TTL_SECONDS", 1800) * 1000,
+            ...(stateSecret(env, transport) ? { stateSecret: stateSecret(env, transport) } : {}),
         },
     };
 }

package/dist/http.js

@@ -7,15 +7,18 @@ import { OAuthCallerProvider } from "./oauth/provider.js";
 import { invalidToken, insufficientScope, missingToken, notBearer, OAuthRequestError, oauthErrorResponse, oauthRequestState } from "./oauth/errors.js";
 import { MESSAGING_SCOPES, READ_SCOPE, WRITE_SCOPE, requestScopes } from "./oauth/scopes.js";
 import { DOWNLOAD_PATH, downloadBaseUrl, downloadHeaders, parseDownloadPath } from "./download.js";
-import { CHECKSUM_HEADER, UPLOAD_DRAIN_IDLE_MS, UPLOAD_PATH, UploadBodyError, decodedUploadBody, drainableBody, parseUploadPath, uploadEncoding } from "./upload.js";
+import { CHECKSUM_HEADER, UPLOAD_DRAIN_IDLE_MS, UPLOAD_PATH, UploadBodyError, decodedUploadBody, drainableBody, parseUploadPath, streamIntoDraft, uploadEncoding } from "./upload.js";
 import { AttachmentChecksumError, UploadInterruptedError } from "./client/client.js";
 import { FmsgHttpError } from "./client/errors.js";
 import { sameAddress } from "./address.js";
 import { attachmentType } from "./render.js";
 import { describeError } from "./errors.js";
-import { VERSION } from "./version.js";
+import { BUILD, VERSION } from "./version.js";
 import { safeErrorMessage } from "./client/redact.js";
 import { isLoopbackHost, normalizeOrigin } from "./client/url.js";
+import { LINK_PATH, PresignedLinks } from "./links.js";
+import { IndicatorRegistry } from "./indicators.js";
+import { createHash } from "node:crypto";
 export const MCP_PATH = "/mcp";
 /** How long close() lets in-flight requests finish (waits end at once) before cutting them off. */
 export const SHUTDOWN_GRACE_MS = 5000;
@@ -117,6 +120,99 @@ async function draftRefusal(caller, id, signal) {
         return `message ${id} is not your draft; only its sender can add attachments`;
     return undefined;
 }
+/** A presigned download's attachment is no longer the bytes its link was issued for. */
+class AttachmentChangedError extends Error {
+    constructor() { super("the attachment changed since this link was issued; ask for a new link"); this.name = "AttachmentChangedError"; }
+}
+/**
+ * The body as a stream that fails unless it is exactly `size` bytes with SHA-256 `sha256`. The last chunk is held
+ * back until the whole body is verified, so a client never receives all `size` bytes of a file that does not match.
+ */
+function verified(body, size, sha256) {
+    const hash = createHash("sha256");
+    let read = 0;
+    let held;
+    const changed = () => new AttachmentChangedError();
+    return body.pipeThrough(new TransformStream({
+        transform(chunk, controller) {
+            read += chunk.byteLength;
+            if (read > size) {
+                controller.error(changed());
+                return;
+            }
+            hash.update(chunk);
+            if (held)
+                controller.enqueue(held);
+            held = chunk;
+        },
+        flush(controller) {
+            if (read !== size || hash.digest("hex") !== sha256) {
+                controller.error(changed());
+                return;
+            }
+            if (held)
+                controller.enqueue(held);
+        },
+    }));
+}
+/**
+ * Serve a presigned link: no Authorization header, the link itself authorizes one transfer. GET streams the
+ * attachment, cutting the transfer off if its bytes are not the size and SHA-256 the link was issued for; PUT
+ * takes one file of the declared size and SHA-256 into the draft.
+ */
+async function serveLink(links, url, request, res, signal) {
+    const refuse = (status, error, headers = {}) => sendWebResponse(res, Response.json({ error }, { status, headers }));
+    const method = request.method;
+    if (method !== "GET" && method !== "PUT")
+        return refuse(405, "use GET or PUT, as the link says", { allow: "GET, PUT, OPTIONS" });
+    if (url.search)
+        return refuse(400, "presigned links must not have query parameters");
+    const token = url.pathname.slice(LINK_PATH.length + 1);
+    if (!/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/u.test(token))
+        return refuse(404, "unknown link");
+    const resolved = links.resolve(token, method);
+    if ("status" in resolved)
+        return refuse(resolved.status, resolved.error);
+    const { claims, caller } = resolved;
+    try {
+        if (claims.k === "get") {
+            const { stream, contentType } = await caller.client.streamAttachment(claims.m, claims.n, signal);
+            // Spend the link only once the attachment is there, so a concurrent request cannot use it twice.
+            if (!links.consume(claims.j)) {
+                await stream.cancel();
+                return refuse(409, "this link was already used; each link downloads once");
+            }
+            const headers = downloadHeaders(claims.n, contentType);
+            headers.set("content-length", String(claims.s));
+            headers.set(CHECKSUM_HEADER, claims.h);
+            return await sendWebResponse(res, new Response(verified(stream, claims.s, claims.h), { headers }));
+        }
+        let encoding;
+        try {
+            encoding = uploadEncoding(request.headers.get("content-encoding"));
+        }
+        catch (error) {
+            return refuse(415, error.message);
+        }
+        const response = await streamIntoDraft(links, caller, {
+            draft: claims.m, filename: claims.n, size: claims.s, sha256: claims.h, mimeType: claims.t ?? attachmentType(claims.n),
+        }, request, encoding, signal, "link");
+        return await sendWebResponse(res, response);
+    }
+    catch (error) {
+        if (error.undrained || res.headersSent) {
+            res.destroy();
+            return;
+        }
+        if (res.destroyed || signal.aborted)
+            return;
+        if (error instanceof AttachmentChangedError)
+            return refuse(409, error.message);
+        const status = error instanceof AttachmentChecksumError ? 422 : error instanceof UploadBodyError ? 400
+            : error instanceof FmsgHttpError && error.status >= 400 && error.status <= 599 && error.status !== 401 ? error.status : 502;
+        return refuse(status, describeError(error));
+    }
+}
 export function createHttpServer(config, log = (l) => console.error(l)) {
     const allowedHosts = config.http.allowedHosts.length
         ? config.http.allowedHosts
@@ -138,11 +234,22 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
     const metadataPath = resource ? `/.well-known/oauth-protected-resource${resource.pathname === "/" ? "" : resource.pathname}` : undefined;
     const metadataUrl = resource ? `${resource.origin}${metadataPath}` : "";
     const shutdown = new AbortController();
-    const mcpHandler = (provider, address) => createMcpHandler(({ authInfo }) => createFmsgMcpServer(provider, config, {
-        ...(authInfo ? { address: address(authInfo) } : {}),
-        ...(typeof authInfo?.extra?.owner === "string" ? { owner: authInfo.extra.owner } : {}),
-        shutdown: shutdown.signal,
-    }), { onerror: (error) => safeLog(`MCP transport failed: ${error instanceof Error ? error.message : String(error)}`) });
+    // Presigned links need the public URL to build them; they carry their own authorization.
+    const links = downloadBaseUrl(config) ? new PresignedLinks(downloadBaseUrl(config), config.http.stateSecret) : undefined;
+    // Each MCP request gets its own server instance, so indicators kept up between requests live here, one registry
+    // per provider so that combined mode never shares a caller's indicators across authentication paths.
+    const registries = [];
+    const mcpHandler = (provider, address) => {
+        const indicators = new IndicatorRegistry();
+        registries.push(indicators);
+        return createMcpHandler(({ authInfo }) => createFmsgMcpServer(provider, config, {
+            ...(authInfo ? { address: address(authInfo) } : {}),
+            ...(typeof authInfo?.extra?.owner === "string" ? { owner: authInfo.extra.owner } : {}),
+            shutdown: shutdown.signal,
+            ...(links ? { links } : {}),
+            indicators,
+        }), { onerror: (error) => safeLog(`MCP transport failed: ${error instanceof Error ? error.message : String(error)}`) });
+    };
     const oauthHandler = oauthProvider && mcpHandler(oauthProvider, (authInfo) => String(authInfo.extra?.address ?? ""));
     const apiKeyHandler = apiKeyProvider && mcpHandler(apiKeyProvider, (authInfo) => authInfo.clientId);
     const active = new Map();
@@ -160,18 +267,20 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
         res.once("close", abort);
         const url = new URL(req.url ?? "/", "http://localhost");
         const isUpload = url.pathname.startsWith(`${UPLOAD_PATH}/`);
+        const isLink = Boolean(links) && url.pathname.startsWith(`${LINK_PATH}/`);
+        const streamsBody = isUpload || (isLink && req.method === "PUT");
         // A progressing upload may take longer than any fixed budget; the upload stream has an idle timeout instead.
         // Closing the connection afterwards stops Node reading the rest of an upload refused before authentication;
         // an authenticated caller's failed upload is drained first so its answer arrives (see serveUpload).
-        const bodyTimer = isUpload ? undefined : setTimeout(() => { if (!req.complete)
+        const bodyTimer = streamsBody ? undefined : setTimeout(() => { if (!req.complete)
             req.destroy(); }, REQUEST_BODY_TIMEOUT_MS).unref();
-        if (isUpload)
+        if (streamsBody)
             res.setHeader("connection", "close");
         const done = (async () => {
             const isDownload = url.pathname.startsWith(`${DOWNLOAD_PATH}/`);
             if (url.pathname === "/healthz") {
                 res.writeHead(200, { "content-type": "application/json" });
-                res.end(JSON.stringify({ ok: true, name: "fmsg-mcp", version: VERSION }));
+                res.end(JSON.stringify({ ok: true, name: "fmsg-mcp", version: VERSION, ...(BUILD.commit ? { commit: BUILD.commit } : {}) }));
                 return;
             }
             if (resource && (url.pathname === metadataPath || url.pathname === "/.well-known/oauth-protected-resource")) {
@@ -187,7 +296,7 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
                     authorization_servers: [config.oauth.issuerUrl], scopes_supported: MESSAGING_SCOPES,
                     bearer_methods_supported: ["header"], resource_name: "fmsg messaging", }, { headers }));
             }
-            if (url.pathname !== MCP_PATH && !isDownload && !isUpload) {
+            if (url.pathname !== MCP_PATH && !isDownload && !isUpload && !isLink) {
                 res.writeHead(404, { "content-type": "text/plain" });
                 res.end("not found; the MCP endpoint is /mcp");
                 return;
@@ -219,7 +328,7 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
             if (req.method === "OPTIONS") {
                 const method = request.headers.get("access-control-request-method") ?? "";
                 const headers = (request.headers.get("access-control-request-headers") ?? "").split(",").map((v) => v.trim().toLowerCase()).filter(Boolean);
-                const methods = isDownload ? ["GET"] : isUpload ? ["PUT"] : CORS_METHODS;
+                const methods = isDownload ? ["GET"] : isUpload ? ["PUT"] : isLink ? ["GET", "PUT"] : CORS_METHODS;
                 if (!origin || !methods.includes(method) || headers.some((h) => !CORS_HEADERS.includes(h))) {
                     return sendWebResponse(res, new Response("preflight not allowed", { status: 403 }));
                 }
@@ -241,6 +350,8 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
                     return sendWebResponse(res, new Response("invalid attachment download path", { status: 400 }));
                 }
             }
+            if (isLink)
+                return serveLink(links, url, request, res, controller.signal);
             let upload;
             if (isUpload) {
                 // Refusals are JSON, like the errors from the upload itself.
@@ -439,6 +550,8 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
     const close = ({ graceMs = SHUTDOWN_GRACE_MS } = {}) => closing ??= (async () => {
         // Waits answer "interrupted" with a resumable cursor; new requests get 503.
         shutdown.abort();
+        for (const indicators of registries)
+            indicators.close();
         const closed = new Promise((resolve) => server.close(() => resolve()));
         server.closeIdleConnections();
         let timer;
@@ -454,6 +567,7 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
         }
         oauthProvider?.close();
         apiKeyProvider?.close();
+        links?.close();
         await Promise.all([oauthHandler?.close(), apiKeyHandler?.close()]);
         // Aborted fetches may open replacement sockets without a request, so
         // they are absent from `active` and must also be closed on shutdown.

package/dist/index.js

@@ -8,7 +8,7 @@ import { loadConfig, DEFAULT_HTTP_PORT } from "./config.js";
 import { StaticCallerProvider, UnconfiguredCallerProvider } from "./context.js";
 import { createHttpServer, MCP_PATH, SHUTDOWN_GRACE_MS } from "./http.js";
 import { createFmsgMcpServer } from "./server.js";
-import { PACKAGE_NAME, VERSION } from "./version.js";
+import { PACKAGE_NAME, VERSION, VERSION_LABEL } from "./version.js";
 const USAGE = `${PACKAGE_NAME} ${VERSION} — MCP server for fmsg
 
 Usage:
@@ -115,7 +115,7 @@ async function main() {
         }
         else if (cfg.apiUrl && cfg.apiKey) {
             provider = new StaticCallerProvider(new FmsgClient(cfg.apiUrl, cfg.apiKey, { allowInsecureHttp: cfg.allowInsecureHttp }));
-            console.error(safeErrorMessage(`fmsg-mcp ${VERSION} serving stdio for ${cfg.apiUrl}`));
+            console.error(safeErrorMessage(`fmsg-mcp ${VERSION_LABEL} serving stdio for ${cfg.apiUrl}`));
         }
         else {
             const missing = [!cfg.apiUrl && "FMSG_API_URL", !cfg.apiKey && "FMSG_API_KEY"].filter(Boolean).join(" and ");
@@ -153,7 +153,7 @@ async function main() {
     });
     const addr = server.address();
     const shown = typeof addr === "object" && addr ? `${addr.address}:${addr.port}` : `${config.http.host}:${config.http.port}`;
-    console.error(safeErrorMessage(`fmsg-mcp ${VERSION} serving Streamable HTTP at http://${shown}${MCP_PATH} for ${config.apiUrl}`));
+    console.error(safeErrorMessage(`fmsg-mcp ${VERSION_LABEL} serving Streamable HTTP at http://${shown}${MCP_PATH} for ${config.apiUrl}`));
     onShutdown(() => close());
 }
 /** Stop on SIGINT/SIGTERM within a bounded time; a second signal exits at once. */

package/dist/indicators.d.ts

@@ -0,0 +1,35 @@
+import type { Caller } from "./context.js";
+/** The emoji indicate shows by default: working on a reply. */
+export declare const WORKING_EMOJI = "\u23F3";
+export type IndicatorOptions = {
+    /** How often an indicator is re-sent (default 30 s); never more often than half its ttl allows, nor below 1 s. */
+    refreshMs?: number;
+    /** How long an indicator is kept up before it is cleared (default 5 minutes). */
+    maxMs?: number;
+    /** Most indicators kept up at once per caller (default 10); the oldest is cleared to make room. */
+    maxActive?: number;
+    /** Debug log for swallowed failures; nothing is logged by default. */
+    log?: (line: string) => void;
+};
+export declare class IndicatorRegistry {
+    private readonly callers;
+    private readonly settings;
+    private closed;
+    constructor(options?: IndicatorOptions);
+    /** The caller's indicators, if any, switched to its current client (a renewed OAuth token brings a new one). */
+    private existing;
+    private of;
+    /** After a reply was sent to `parentId`: stop what is shown on it and anywhere in its thread. */
+    replied(caller: Caller, parentId: string, rootId: string | null): void;
+    /** After a reaction or mark_read: the caller has handled these messages. */
+    handled(caller: Caller, ids: string[]): void;
+    /**
+     * The indicate tool: show `emoji` and keep it up, or clear with an empty one. Throws the host's refusal. `rootId` is
+     * the message's thread root, when known, so a reply anywhere in that thread stops it.
+     */
+    indicate(caller: Caller, id: string, emoji: string, ttl: number, rootId?: string | null): Promise<void>;
+    /** Message ids with an indicator kept up for this caller. */
+    active(caller: Caller): string[];
+    /** Stop every indicator, clearing them in the background. Idempotent. */
+    close(): void;
+}