@markmnl/fmsg-mcp 1.2.3 → 1.4.0

package/dist/indicators.js

@@ -0,0 +1,186 @@
+import { FmsgHttpError } from "./client/errors.js";
+/** The emoji indicate shows by default: working on a reply. */
+export const WORKING_EMOJI = "⏳";
+/** A 4xx other than 401 (renewed by the client), 408 or 429 will not succeed on a retry; neither will a closed client. */
+function permanent(error) {
+    if (error instanceof FmsgHttpError)
+        return error.status >= 400 && error.status < 500 && ![401, 408, 429].includes(error.status);
+    return error instanceof Error && error.name === "AbortError";
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** The indicators one caller shows. Sends for one message are serialized so a clear never overtakes a refresh. */
+class CallerIndicators {
+    client;
+    settings;
+    onIdle;
+    entries = new Map();
+    tails = new Map();
+    constructor(client, settings, onIdle) {
+        this.client = client;
+        this.settings = settings;
+        this.onIdle = onIdle;
+    }
+    get idle() { return this.entries.size === 0 && this.tails.size === 0; }
+    ids() { return [...this.entries.keys()]; }
+    has(id) { return this.entries.has(id); }
+    enqueue(id, emoji, ttl) {
+        const previous = this.tails.get(id) ?? Promise.resolve();
+        const sent = previous.then(() => this.client.indicate(id, emoji, ttl));
+        const settled = sent.then(() => undefined, () => undefined);
+        this.tails.set(id, settled);
+        void settled.then(() => {
+            if (this.tails.get(id) === settled)
+                this.tails.delete(id);
+            if (this.idle)
+                this.onIdle();
+        });
+        return sent;
+    }
+    /** Send in the background, dropping the indicator when the host will never take it. */
+    sendQuietly(entry, emoji, ttl) {
+        this.enqueue(entry.id, emoji, ttl).catch((error) => {
+            this.settings.log(`indicator on ${entry.id} failed: ${describe(error)}`);
+            if (permanent(error) && this.entries.get(entry.id) === entry)
+                this.stop(entry.id, false);
+        });
+    }
+    schedule(entry) {
+        const remaining = this.settings.maxMs - (Date.now() - entry.startedAt);
+        entry.timer = setTimeout(() => this.tick(entry), Math.max(0, Math.min(entry.refreshMs, remaining)));
+        entry.timer.unref?.();
+    }
+    tick(entry) {
+        if (this.entries.get(entry.id) !== entry)
+            return;
+        if (Date.now() - entry.startedAt >= this.settings.maxMs) {
+            this.stop(entry.id);
+            return;
+        }
+        this.sendQuietly(entry, entry.emoji, entry.ttl);
+        this.schedule(entry);
+    }
+    add(id, emoji, ttl, rootId) {
+        this.stop(id, false);
+        while (this.entries.size >= this.settings.maxActive) {
+            const oldest = this.entries.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.stop(oldest);
+        }
+        const refreshMs = Math.max(1000, Math.min(this.settings.refreshMs, Math.floor((ttl * 1000) / 2)));
+        const entry = { id, emoji, ttl, refreshMs, rootId, startedAt: Date.now() };
+        this.entries.set(id, entry);
+        this.schedule(entry);
+        return entry;
+    }
+    /**
+     * Show `emoji` now, failing if the host refuses it, then keep it up. The send is queued before the old indicator stops
+     * so this caller never looks idle (and is dropped from the registry) while replacing one.
+     */
+    async set(id, emoji, ttl, rootId) {
+        rootId ??= this.entries.get(id)?.rootId ?? null;
+        const sent = this.enqueue(id, emoji, ttl);
+        this.stop(id, false);
+        await sent;
+        this.add(id, emoji, ttl, rootId);
+    }
+    /** Clear now, failing if the host refuses it. */
+    async clear(id) {
+        const sent = this.enqueue(id, "", 0);
+        this.stop(id, false);
+        await sent;
+    }
+    /** Stop refreshing; with `clear`, also clear the indicator in the background. */
+    stop(id, clear = true) {
+        const entry = this.entries.get(id);
+        if (!entry)
+            return;
+        clearTimeout(entry.timer);
+        this.entries.delete(id);
+        if (clear) {
+            this.enqueue(id, "", 0).catch((error) => this.settings.log(`clearing indicator on ${id} failed: ${describe(error)}`));
+        }
+        else if (this.idle)
+            this.onIdle();
+    }
+    stopThread(rootId) {
+        for (const entry of [...this.entries.values()])
+            if (entry.rootId === rootId || entry.id === rootId)
+                this.stop(entry.id);
+    }
+    stopAll(clear) {
+        for (const id of [...this.entries.keys()])
+            this.stop(id, clear);
+    }
+}
+export class IndicatorRegistry {
+    callers = new Map();
+    settings;
+    closed = false;
+    constructor(options = {}) {
+        this.settings = {
+            refreshMs: options.refreshMs ?? 30_000,
+            maxMs: options.maxMs ?? 5 * 60_000,
+            maxActive: options.maxActive ?? 10,
+            log: options.log ?? (() => undefined),
+        };
+    }
+    /** The caller's indicators, if any, switched to its current client (a renewed OAuth token brings a new one). */
+    existing(caller) {
+        const indicators = this.callers.get(caller.address.toLowerCase());
+        if (indicators)
+            indicators.client = caller.client;
+        return indicators;
+    }
+    of(caller) {
+        const key = caller.address.toLowerCase();
+        let indicators = this.existing(caller);
+        if (!indicators) {
+            const created = new CallerIndicators(caller.client, this.settings, () => {
+                if (this.callers.get(key) === created && created.idle)
+                    this.callers.delete(key);
+            });
+            indicators = created;
+            this.callers.set(key, created);
+        }
+        return indicators;
+    }
+    /** After a reply was sent to `parentId`: stop what is shown on it and anywhere in its thread. */
+    replied(caller, parentId, rootId) {
+        const indicators = this.existing(caller);
+        if (!indicators)
+            return;
+        indicators.stop(parentId);
+        if (rootId)
+            indicators.stopThread(rootId);
+    }
+    /** After a reaction or mark_read: the caller has handled these messages. */
+    handled(caller, ids) {
+        const indicators = this.existing(caller);
+        for (const id of ids)
+            indicators?.stop(id);
+    }
+    /**
+     * 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.
+     */
+    async indicate(caller, id, emoji, ttl, rootId = null) {
+        if (!emoji)
+            return this.of(caller).clear(id);
+        if (this.closed)
+            return caller.client.indicate(id, emoji, ttl);
+        return this.of(caller).set(id, emoji, ttl, rootId);
+    }
+    /** Message ids with an indicator kept up for this caller. */
+    active(caller) {
+        return this.callers.get(caller.address.toLowerCase())?.ids() ?? [];
+    }
+    /** Stop every indicator, clearing them in the background. Idempotent. */
+    close() {
+        this.closed = true;
+        for (const indicators of this.callers.values())
+            indicators.stopAll(true);
+    }
+}

package/dist/instructions.js

@@ -11,10 +11,10 @@ import { ownerSentence } from "./owner.js";
 /** How to send files, naming only the routes this server offers. */
 function filesParagraph(files) {
     const large = [
-        ...(files?.uploadUrl ? ["create_draft, PUT each file to its upload URL, then send_draft"] : []),
+        ...(files?.uploadUrl ? [`create_draft, PUT each file to its upload URL${files.presigned ? " (or a get_attachment_upload_url link)" : ""}, then send_draft`] : []),
         ...(files?.uploadFolder ? ["give path, a file in the upload folder"] : []),
     ];
-    return "Files: data_text for text, data_base64 for small files." + (large.length ? ` Large files: ${large.join("; or ")}.` : "");
+    return "Files: data_text for text, data_base64 for small files (best effort; always add sha256)." + (large.length ? ` Large files: ${large.join("; or ")}.` : "");
 }
 export function buildInstructions(ctx = {}) {
     const identity = ctx.address
@@ -37,7 +37,9 @@ export function buildInstructions(ctx = {}) {
             "added to a message after it was sent; they can read it and its attachments.",
         "To check the inbox: list_messages with unread_only, get_thread on what matters, act or reply, then mark_read " +
             "what you have handled; reading does not mark a message read. There is no search: to find a thread by name, " +
-            "find its first message by topic in list_messages, then get_thread on a later message for the conversation.",
+            "find its first message by topic in list_messages, then get_thread on a later message for the conversation. " +
+            "indicate can show the other participants a status such as ⏳ while you work on a reply (cleared when you reply, " +
+            "react or mark it read, or after 5 minutes); an empty emoji clears it.",
         filesParagraph(ctx.files),
         "Carry out the user's requested messaging task or authorized automation without repeatedly asking for " +
             "confirmation. Sending is immediate and sent messages cannot be edited or recalled. Ask the user only " +

package/dist/links.d.ts

@@ -0,0 +1,63 @@
+import type { Caller } from "./context.js";
+import type { UploadTracker } from "./upload.js";
+export declare const LINK_PATH = "/mcp/links";
+/** How long a presigned link stays usable. */
+export declare const LINK_TTL_SECONDS = 300;
+/** What a link allows, signed into it. */
+export type LinkClaims = {
+    v: 1;
+    /** GET downloads an attachment; PUT uploads one file into a draft. */
+    k: "get" | "put";
+    /** Link id, for single use. */
+    j: string;
+    /** The fmsg address it acts for. */
+    a: string;
+    /** Message id (GET) or draft id (PUT). */
+    m: string;
+    /** Attachment name. */
+    n: string;
+    /** Size in bytes. */
+    s: number;
+    /** SHA-256, lowercase hex. */
+    h: string;
+    /** Media type (PUT). */
+    t?: string;
+    /** Expiry, unix seconds. */
+    e: number;
+};
+export declare class PresignedLinks implements UploadTracker {
+    private readonly publicUrl;
+    private readonly ttlSeconds;
+    private readonly key;
+    private readonly issued;
+    private readonly uploading;
+    private readonly verified;
+    private readonly sweeper;
+    constructor(publicUrl: string, secret: string | undefined, ttlSeconds?: number);
+    private sign;
+    /** Issue a link for `caller`. */
+    mint(caller: Caller, claims: Omit<LinkClaims, "v" | "j" | "a" | "e">): {
+        url: string;
+        expiresAt: number;
+    };
+    /** The link in a request path, with the caller it acts for, or the status and reason to refuse it with. */
+    resolve(token: string, method: string, now?: number): {
+        claims: LinkClaims;
+        caller: Caller;
+    } | {
+        status: number;
+        error: string;
+    };
+    /** Spend a download link. False when it was already spent. */
+    consume(id: string): boolean;
+    begin(key: string): boolean;
+    end(key: string): void;
+    recordVerified(key: string, sha256: string): void;
+    verifiedSha256(key: string): string | undefined;
+    private sweep;
+    close(): void;
+}
+/** A string as one POSIX shell word. */
+export declare function shellQuote(value: string): string;
+/** A local file name for curl -o: the attachment's name reduced to portable characters. */
+export declare function localFileName(filename: string): string;

package/dist/links.js

@@ -0,0 +1,104 @@
+/**
+ * Presigned links: short-lived, single-use URLs that carry their own authorization, for hosts that cannot send this
+ * MCP connection's Authorization header with their HTTP requests. A link is a signed capability for exactly one
+ * transfer: GET one attachment, or PUT one file of a declared size and SHA-256 into one draft. It never contains
+ * an API key or access token. The caller it acts for is kept in this process, so a link works only on the instance
+ * that issued it.
+ */
+import { createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+export const LINK_PATH = "/mcp/links";
+/** How long a presigned link stays usable. */
+export const LINK_TTL_SECONDS = 300;
+export class PresignedLinks {
+    publicUrl;
+    ttlSeconds;
+    key;
+    issued = new Map();
+    uploading = new Set();
+    verified = new Map();
+    sweeper;
+    constructor(publicUrl, secret, ttlSeconds = LINK_TTL_SECONDS) {
+        this.publicUrl = publicUrl;
+        this.ttlSeconds = ttlSeconds;
+        this.key = secret ? Buffer.from(secret, "utf8") : randomBytes(32);
+        this.sweeper = setInterval(() => this.sweep(), 60_000).unref();
+    }
+    sign(body) {
+        return createHmac("sha256", this.key).update(`fmsg-mcp.presigned-link.v1:${body}`).digest("base64url");
+    }
+    /** Issue a link for `caller`. */
+    mint(caller, claims) {
+        const expiresAt = Math.floor(Date.now() / 1000) + this.ttlSeconds;
+        const full = { v: 1, j: randomUUID(), a: caller.address, e: expiresAt, ...claims };
+        const body = Buffer.from(JSON.stringify(full)).toString("base64url");
+        this.issued.set(full.j, { caller, used: false, expires: expiresAt * 1000 });
+        return { url: `${this.publicUrl.replace(/\/$/u, "")}/links/${body}.${this.sign(body)}`, expiresAt };
+    }
+    /** The link in a request path, with the caller it acts for, or the status and reason to refuse it with. */
+    resolve(token, method, now = Date.now()) {
+        const [body, mac, extra] = token.split(".");
+        const unknown = { status: 404, error: "unknown link" };
+        if (!body || !mac || extra !== undefined)
+            return unknown;
+        const expected = Buffer.from(this.sign(body));
+        const given = Buffer.from(mac);
+        if (expected.length !== given.length || !timingSafeEqual(expected, given))
+            return unknown;
+        let claims;
+        try {
+            claims = JSON.parse(Buffer.from(body, "base64url").toString("utf8"));
+        }
+        catch {
+            return unknown;
+        }
+        if (claims.v !== 1)
+            return unknown;
+        if ((claims.k === "get") !== (method === "GET"))
+            return { status: 405, error: claims.k === "get" ? "this link is for GET" : "this link is for PUT" };
+        if (claims.e * 1000 <= now)
+            return { status: 410, error: `this link expired at ${new Date(claims.e * 1000).toISOString()}; ask for a new one` };
+        const issued = this.issued.get(claims.j);
+        // Signed by this key but not issued here: another instance (shared key) or before a restart.
+        if (!issued)
+            return { status: 404, error: "this link was issued by another server instance or before a restart; ask for a new one" };
+        if (claims.k === "get" && issued.used)
+            return { status: 409, error: "this link was already used; each link downloads once" };
+        return { claims, caller: issued.caller };
+    }
+    /** Spend a download link. False when it was already spent. */
+    consume(id) {
+        const issued = this.issued.get(id);
+        if (!issued || issued.used)
+            return false;
+        issued.used = true;
+        return true;
+    }
+    // UploadTracker: a PUT link takes one successful upload; failed attempts leave it usable until it expires.
+    begin(key) { if (this.uploading.has(key))
+        return false; this.uploading.add(key); return true; }
+    end(key) { this.uploading.delete(key); }
+    recordVerified(key, sha256) { this.verified.set(key, sha256); }
+    verifiedSha256(key) { return this.verified.get(key); }
+    sweep() {
+        const now = Date.now();
+        for (const [id, issued] of this.issued)
+            if (issued.expires <= now)
+                this.issued.delete(id);
+        if (!this.issued.size)
+            this.verified.clear();
+    }
+    close() {
+        clearInterval(this.sweeper);
+        this.issued.clear();
+        this.verified.clear();
+    }
+}
+/** A string as one POSIX shell word. */
+export function shellQuote(value) {
+    return `'${value.replace(/'/gu, `'\\''`)}'`;
+}
+/** A local file name for curl -o: the attachment's name reduced to portable characters. */
+export function localFileName(filename) {
+    const name = filename.normalize("NFKD").replace(/[\u0300-\u036f]/gu, "").replace(/[^A-Za-z0-9._-]+/gu, "_").replace(/^[.-]+/u, "");
+    return name || "attachment";
+}

package/dist/oauth/scopes.js

@@ -9,8 +9,9 @@ export const TOOL_SCOPES = {
     get_thread: [READ_SCOPE], delivery_status: [READ_SCOPE], download_attachment: [READ_SCOPE],
     save_attachment: [READ_SCOPE], get_attachment_download_url: [READ_SCOPE], wait_for_message: [READ_SCOPE],
     send_message: [WRITE_SCOPE], reply: MESSAGING_SCOPES,
-    mark_read: [WRITE_SCOPE], add_recipients: [WRITE_SCOPE], react: [WRITE_SCOPE],
+    mark_read: [WRITE_SCOPE], add_recipients: [WRITE_SCOPE], react: [WRITE_SCOPE], indicate: [WRITE_SCOPE],
     create_draft: MESSAGING_SCOPES, send_draft: MESSAGING_SCOPES, delete_draft: MESSAGING_SCOPES,
+    get_attachment_upload_url: MESSAGING_SCOPES,
 };
 export function parseScopes(value) {
     if (typeof value !== "string")

package/dist/prompts.js

@@ -4,13 +4,15 @@ function sendFileSteps(routes, to, replyTo) {
     const recipients = to ? `to ${to}, with a short topic` : "to the recipients I name (ask me if I have not)";
     const draft = replyTo ? `with reply_to "${replyTo}"${to ? ` and to: ${to}` : ""}` : recipients;
     const direct = replyTo ? `reply with id "${replyTo}"${to ? ` and recipients: ${to}` : ""}` : `send_message ${recipients}`;
-    const inline = "attach text files as data_text and small binary files as data_base64, each with its sha256 when you can compute it";
+    const inline = "attach text files as data_text and small binary files as data_base64 with their sha256 (base64 is best effort, so keep it for small files)";
     if (routes.uploadUrl) {
         return [
             `1. Call create_draft ${draft}; ${inline}.`,
             "2. For each larger file, PUT its raw bytes to the draft's upload URL with your host's authenticated HTTP tools, " +
                 "sending its sha256 in x-content-sha256, and check each response's size and sha256. If your host cannot send this " +
-                "connection's credentials with its own requests, recreate the draft with the file as data_base64 instead; never look for or copy credentials.",
+                "connection's credentials with its own requests, " + (routes.presigned
+                ? "get a single-use link for each file from get_attachment_upload_url and run the curl command it returns"
+                : "recreate the draft with the file as data_base64 instead") + "; never look for or copy credentials.",
             "3. Call send_draft with the draft id and tell me what was sent. If a step fails, call delete_draft unless I want to keep the draft.",
         ];
     }

package/dist/public.d.ts

@@ -7,5 +7,6 @@ export { ApiKeyCallerProvider } from "./auth.js";
 export { waitForMessage, type WaitOptions, type WaitResult } from "./wait.js";
 export { assembleThread, renderThread, type AssembledThread } from "./thread.js";
 export { resolveAddress, resolveAddresses, normalizeFmsgAddress } from "./address.js";
+export { IndicatorRegistry, type IndicatorOptions } from "./indicators.js";
 export { VERSION } from "./version.js";
 export * from "./client/index.js";

package/dist/public.js

@@ -7,5 +7,6 @@ export { ApiKeyCallerProvider } from "./auth.js";
 export { waitForMessage } from "./wait.js";
 export { assembleThread, renderThread } from "./thread.js";
 export { resolveAddress, resolveAddresses, normalizeFmsgAddress } from "./address.js";
+export { IndicatorRegistry } from "./indicators.js";
 export { VERSION } from "./version.js";
 export * from "./client/index.js";

package/dist/server.d.ts

@@ -1,6 +1,8 @@
 import { McpServer } from "@modelcontextprotocol/server";
 import type { Config } from "./config.js";
 import type { CallerProvider } from "./context.js";
+import type { PresignedLinks } from "./links.js";
+import { IndicatorRegistry } from "./indicators.js";
 export declare const SERVER_NAME = "fmsg";
 export type CreateServerOptions = {
     /** The caller's address when already known; makes the instructions name it. */
@@ -9,6 +11,15 @@ export type CreateServerOptions = {
     owner?: string;
     /** Aborted when the process begins shutting down, so wait_for_message returns "interrupted". */
     shutdown?: AbortSignal;
+    /** Issues presigned download and upload links (HTTP with a public URL). */
+    links?: PresignedLinks;
+    /**
+     * Indicators set with the indicate tool and kept up on the caller's behalf (FMSG-006). A factory that builds one
+     * server per HTTP request must pass a shared registry and close it on shutdown. Without one, the server owns its own
+     * and clears every indicator when it closes or `shutdown` aborts, which suits a server that lives for a whole session
+     * (stdio).
+     */
+    indicators?: IndicatorRegistry;
 };
 /**
  * Build an fmsg MCP server. Registration only — no I/O — so the same factory

package/dist/server.js

@@ -13,6 +13,7 @@ import { registerWaitTools } from "./tools/wait.js";
 import { registerSaveTool } from "./tools/save.js";
 import { registerDownloadTool } from "./tools/download.js";
 import { VERSION } from "./version.js";
+import { IndicatorRegistry } from "./indicators.js";
 export const SERVER_NAME = "fmsg";
 /**
  * Build an fmsg MCP server. Registration only — no I/O — so the same factory
@@ -23,12 +24,23 @@ export function createFmsgMcpServer(provider, config, options = {}) {
         ...(options.address ? { address: options.address } : {}),
         ...(options.owner ? { owner: options.owner } : {}),
         ...(config.defaultDomain ? { defaultDomain: config.defaultDomain } : {}),
-        files: fileRoutes(config),
+        files: fileRoutes(config, Boolean(options.links)),
     });
     const server = new McpServer({ name: SERVER_NAME, title: "fmsg", version: VERSION }, { instructions });
     const includeOwner = includeOwnerSchema(options.address, options.owner);
+    let indicators = options.indicators;
+    if (!indicators) {
+        const owned = new IndicatorRegistry();
+        indicators = owned;
+        const previous = server.server.onclose;
+        server.server.onclose = () => { owned.close(); previous?.(); };
+        options.shutdown?.addEventListener("abort", () => owned.close(), { once: true });
+        if (options.shutdown?.aborted)
+            owned.close();
+    }
     const deps = {
         provider, config, ...(includeOwner ? { includeOwner } : {}), ...(options.shutdown ? { shutdown: options.shutdown } : {}),
+        ...(options.links ? { links: options.links } : {}), indicators,
     };
     registerIdentityTools(server, deps);
     registerListTools(server, deps);
@@ -39,6 +51,6 @@ export function createFmsgMcpServer(provider, config, options = {}) {
     registerDraftTools(server, deps);
     registerWaitTools(server, deps);
     registerResources(server, deps);
-    registerPrompts(server, fileRoutes(config));
+    registerPrompts(server, fileRoutes(config, Boolean(options.links)));
     return server;
 }

package/dist/tools/attachments.d.ts

@@ -9,12 +9,16 @@ export type FileRoutes = {
     uploadUrl: boolean;
     /** Attachments may name a file in FMSG_MCP_UPLOAD_DIR (stdio). */
     uploadFolder: boolean;
+    /** get_attachment_upload_url issues single-use upload links that need no credentials (HTTP). */
+    presigned: boolean;
 };
-export declare function fileRoutes(config: Config): FileRoutes;
+export declare function fileRoutes(config: Config, presigned?: boolean): FileRoutes;
+/** The routes for files too large for base64, in words for a model; empty when there are none. */
+export declare function largeFileRoutes(routes: FileRoutes): string[];
 /** A hint for the model after it wrote a large file as base64 although this server offers a route that avoids it. */
 export declare function base64Hint(items: AttachmentArgs[] | undefined, routes: FileRoutes): string | undefined;
 /** One outbound attachment as a tool argument: a filename and exactly one source of bytes. */
-export declare function attachmentInput(config: Config): z.ZodObject<{
+export declare function attachmentInput(config: Config, routes?: FileRoutes): z.ZodObject<{
     content_type: z.ZodOptional<z.ZodString>;
     sha256: z.ZodOptional<z.ZodString>;
     path?: z.ZodOptional<z.ZodString> | undefined;

package/dist/tools/attachments.js

@@ -8,8 +8,16 @@ import { downloadBaseUrl } from "../download.js";
 import { attachmentType } from "../render.js";
 export const FILENAME = /^[A-Za-z0-9._-]+$/u;
 const SHA256 = /^[0-9A-Fa-f]{64}$/u;
-export function fileRoutes(config) {
-    return { uploadUrl: Boolean(downloadBaseUrl(config)), uploadFolder: Boolean(config.uploadDir) };
+export function fileRoutes(config, presigned = false) {
+    const uploadUrl = Boolean(downloadBaseUrl(config));
+    return { uploadUrl, uploadFolder: Boolean(config.uploadDir), presigned: uploadUrl && presigned };
+}
+/** The routes for files too large for base64, in words for a model; empty when there are none. */
+export function largeFileRoutes(routes) {
+    return [
+        ...(routes.uploadFolder ? ["path, a file in the upload folder"] : []),
+        ...(routes.uploadUrl ? [`create_draft's upload URL${routes.presigned ? " (or a single-use link from get_attachment_upload_url)" : ""}`] : []),
+    ];
 }
 /** Inline base64 this long (about 48 KB of file) earns a hint about a better route next time. A hint only, never a limit. */
 const BASE64_HINT_CHARS = 64 * 1024;
@@ -17,7 +25,7 @@ const BASE64_HINT_CHARS = 64 * 1024;
 export function base64Hint(items, routes) {
     const large = (items ?? []).filter((a) => (a.data_base64?.length ?? 0) >= BASE64_HINT_CHARS).map((a) => a.filename);
     const better = [
-        ...(routes.uploadUrl ? ["call create_draft, PUT them to its upload URL, then call send_draft"] : []),
+        ...(routes.uploadUrl ? [`call create_draft, PUT them to its upload URL${routes.presigned ? " or to single-use links from get_attachment_upload_url" : ""}, then call send_draft`] : []),
         ...(routes.uploadFolder ? ["give their path in the upload folder instead of data_base64"] : []),
     ];
     if (!large.length || !better.length)
@@ -29,17 +37,20 @@ function sources(config) {
     return ["data_base64", "data_text", ...(config.uploadDir ? ["path"] : [])];
 }
 /** One outbound attachment as a tool argument: a filename and exactly one source of bytes. */
-export function attachmentInput(config) {
+export function attachmentInput(config, routes = fileRoutes(config)) {
     const names = sources(config);
+    const large = largeFileRoutes(routes);
     return z.strictObject({
         filename: z.string().regex(FILENAME, "letters, digits, dot, underscore, hyphen only").describe("file name"),
-        data_base64: z.string().optional().describe(`base64 file contents, for small files${config.uploadDir ? "; give large files as path" : downloadBaseUrl(config) ? "; send large files with create_draft's upload URL" : ""}. The host sets the size limit`),
+        data_base64: z.string().optional().describe("base64 file contents. You write the base64, so it is best effort: fine for " +
+            `small files (checked exact up to 16 KB). Always give sha256 with it${large.length ? `. For anything larger use ${large.join(", or ")}` : ""}. ` +
+            "The host sets the size limit"),
         data_text: z.string().optional().describe("text file contents, sent as UTF-8 bytes; use instead of data_base64 for text"),
         ...(config.uploadDir ? {
             path: z.string().min(1).optional().describe("file in the configured upload folder, relative to it; the server reads it so its bytes skip model context"),
         } : {}),
         content_type: z.string().optional().describe("inferred from the filename when omitted"),
-        sha256: z.string().regex(SHA256, "64 hexadecimal characters").optional().describe("hex sha256 of the file; the attachment is refused, and nothing sent, if the bytes differ. Give it when you can compute it"),
+        sha256: z.string().regex(SHA256, "64 hexadecimal characters").optional().describe("hex sha256 of the file; the attachment is refused, and nothing sent, if the bytes differ. Always give it with data_base64"),
     }).superRefine((a, ctx) => {
         const given = names.filter((name) => a[name] !== undefined);
         if (given.length !== 1)

package/dist/tools/common.d.ts

@@ -3,6 +3,8 @@ import * as z from "zod/v4";
 import type { AddressResolver } from "../address.js";
 import type { FmsgMessage } from "../client/types.js";
 import type { Config } from "../config.js";
+import type { IndicatorRegistry } from "../indicators.js";
+import type { PresignedLinks } from "../links.js";
 import { type Caller, type CallerProvider } from "../context.js";
 export type ToolDeps = {
     provider: CallerProvider;
@@ -11,6 +13,10 @@ export type ToolDeps = {
     includeOwner?: z.ZodDefault<z.ZodBoolean>;
     /** Aborted when the server begins shutting down; long waits then return early. */
     shutdown?: AbortSignal;
+    /** Presigned links, when this server has a public URL. */
+    links?: PresignedLinks;
+    /** FMSG-006 indicators the caller sets with the indicate tool, kept up until replied, handled or cleared. */
+    indicators: IndicatorRegistry;
 };
 export declare const READ_ONLY: ToolAnnotations;
 export declare const SENDS: ToolAnnotations;