@needmoretruth/nmts-cli 0.17.2 → 0.34.2

package/dist/mcp-tools/share.js

@@ -11,6 +11,23 @@
 //    person or a program typed a grant, so this is a rule rather than a mechanism, and saying
 //    otherwise would be claiming a protection that is not there.
 //
+// ⛔ AND ON THIS SURFACE THE PERSON IS ASKED EVERY TIME. Once per
+//    machine is the right shape for a capability and the wrong one for this act: the machine
+//    agreed that sharing may happen, and no recorded agreement can say that THIS address is the
+//    one that was meant. Every other tool here acts on the account's own files; this one hands a
+//    key to somebody else, and the undo does not reach what has already been fetched. So the
+//    question goes to the client, over `elicitation/create`, once per call.
+//
+// ⛔ NO WAY TO ASK MEANS NO SHARE. A client that did not declare elicitation gets a refusal that
+//    names the terminal command instead. Falling back to the recorded agreement would let the
+//    least capable client decide the rule for all of them.
+//
+// ⛔ A MODE THAT WAS TURNED ON IS THE ANSWER ALREADY GIVEN. With `auto` or `skip-permissions` set,
+//    the person has said in writing that an agent may decide, and asking anyway would be ignoring
+//    them — the modes exist for the unattended case, which is exactly the case where nobody is
+//    there to answer. The mode was typed with a flag that spells out the risk, and every run that
+//    uses one announces it.
+//
 // ⛔ THE RECIPIENT'S PUBLIC CODE IS NOT CHECKED AGAINST A PERSON. A share sent to a well-formed
 //    code that belongs to somebody else is sent, and is not recallable. Confirm it with whoever
 //    gave it to you, out of band, before calling this.
@@ -25,24 +42,26 @@ export function shareTools(ctx) {
                 "recipient already fetched, and a public code typed wrongly is a share sent to whoever " +
                 "holds that code. The first share on a machine stops and asks the person to agree — show " +
                 "them what it says rather than agreeing for them. Nothing is uploaded and nothing is " +
-                "charged; the recipient pays nothing either.",
+                "charged; the recipient pays nothing either. Every call puts the file and the code in " +
+                "front of the person to confirm, unless they have turned on a mode that says an agent " +
+                "may decide.",
             inputSchema: {
                 type: "object",
                 properties: {
                     path: { type: "string", description: "The file to share, as nmts_list prints it." },
                     public_code: {
                         type: "string",
-                        description: "The recipient's PUBLIC CODE, given to you by them. Not their account code.",
+                        description: "The recipient's PUBLIC CODE, given to you by them. Not their NMTS key.",
                     },
                 },
                 required: ["path", "public_code"],
                 additionalProperties: false,
             },
-            run: (args) => say((write) => share(needString(args, "path"), needString(args, "public_code"), {
-                ...common(ctx),
-                json: true,
-                write,
-            })),
+            run: async (args) => {
+                const path = needString(args, "path");
+                const code = needString(args, "public_code");
+                return say((write) => share(path, code, { ...common(ctx), json: true, write }));
+            },
         },
         {
             name: "nmts_unshare",

package/dist/mcp-tools/support.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from "../mcp.ts";
+import { type ToolContext } from "./context.ts";
+export declare function supportTools(ctx: ToolContext): ToolDefinition[];

package/dist/mcp-tools/support.js

@@ -0,0 +1,140 @@
+// Writing to the person who builds NMTS, offered to an agent as tools.
+//
+// ⛔ WHY THIS IS ON THIS SURFACE AT ALL, when credentials, consent and the human check are not.
+//    Those are the person's to give. A report is the opposite: it is the one thing an agent that
+//    met a defect can do about it, and it is better placed than the person it works for to say
+//    what was run and what came back. The owner asked for it to be here (2026-09-03).
+//
+// ⛔ AND IT IS THE ONE TOOL HERE THAT SENDS WORDS SOMEWHERE. So the description says, in the
+//    words the command prints, what is stripped before anything leaves and what must not be
+//    typed. A model reads the description before it composes the message, which is the only
+//    moment where saying it changes what gets written.
+//
+// ⛔ IT DOES NOT ASK OVER ELICITATION, AND `nmts_share` DOES. The difference is what is at stake:
+//    a share hands somebody else the key to a file and cannot be recalled, and a report is words
+//    in an inbox. What replaces the question is that the tool answers with EXACTLY what it sent —
+//    the category, the message and the attachment, after redaction — so the preview is in the
+//    transcript whether or not anybody was watching.
+import { support } from "../commands/support.js";
+import { ATTACH_LOG_TEXT, categoryCodes, SUPPORT_SHORT } from "../support-copy.js";
+import { MAX_ATTACHED_RUNS } from "../run-log.js";
+import { common, needString, say } from "./context.js";
+const NO_ARGS = { type: "object", properties: {}, additionalProperties: false };
+/** The two sentences every message is written under, as one line for a description. */
+const CARE = SUPPORT_SHORT.join(" ");
+/** What `--attach-log` does, as one line for a description. */
+const LOG = ATTACH_LOG_TEXT.join(" ");
+/** Values a caller wants replaced on top of the rules. Declared the same way on both writers. */
+const OMIT_ARG = {
+    type: "array",
+    items: { type: "string" },
+    description: "Values that must not travel — a file name, a folder path. Every occurrence in the message " +
+        "and in the attached log becomes [omitted]. At least 3 characters each.",
+};
+export function supportTools(ctx) {
+    return [
+        {
+            name: "nmts_support_send",
+            description: "File a report with the developer of NMTS: a bug, a confusing message, an idea, a " +
+                `question. ${CARE} The NMTS key, API key, passphrase, tokens and key material are ` +
+                "replaced by labels on this machine before anything is sent, and file contents are never " +
+                `read at all; file names and the account's public code may go. ${LOG} The answer to this ` +
+                "call is exactly what was sent, so it can be checked afterwards. One report per problem.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    category: {
+                        type: "string",
+                        enum: categoryCodes(),
+                        description: "What the report is about.",
+                    },
+                    subcategory: {
+                        type: "string",
+                        description: "Which part of that category, when one fits. Optional everywhere.",
+                    },
+                    message: {
+                        type: "string",
+                        description: "The report. A good one has four parts: the command that was run, what was " +
+                            "expected, what happened, and anything that narrows it down. 1 to 4000 characters.",
+                    },
+                    attach_log_runs: {
+                        type: "integer",
+                        description: `How many of the CLI's last runs to attach. 0 to ${MAX_ATTACHED_RUNS}; 0 attaches none.`,
+                    },
+                    omit: OMIT_ARG,
+                },
+                required: ["category", "message"],
+                additionalProperties: false,
+            },
+            // ⚠ NOT `json: true`, unlike every read on this surface. The machine-readable answer is the
+            //   ticket alone; what this tool has to hand back is what it SENT.
+            run: (args) => say((write) => support("send", [], {
+                ...common(ctx),
+                write,
+                yes: true,
+                category: needString(args, "category"),
+                ...(typeof args["subcategory"] === "string" ? { sub: args["subcategory"] } : {}),
+                message: needString(args, "message"),
+                ...(runsAsked(args["attach_log_runs"])),
+                omit: stringsOf(args["omit"]),
+            })),
+        },
+        {
+            name: "nmts_support_list",
+            description: "The reports this account has filed from the command line, with their codes, what each " +
+                "is about, whether it has been answered, and how many threads hold something unread. " +
+                "Read-only; costs nothing.",
+            inputSchema: NO_ARGS,
+            run: () => say((write) => support("list", [], { ...common(ctx), json: true, write })),
+        },
+        {
+            name: "nmts_support_show",
+            description: "One report and everything said in it, oldest first, using a code from nmts_support_list. " +
+                "Reading it marks the thread as seen.",
+            inputSchema: {
+                type: "object",
+                properties: { code: { type: "string", description: "The report's code, from nmts_support_list." } },
+                required: ["code"],
+                additionalProperties: false,
+            },
+            run: (args) => say((write) => support("show", [needString(args, "code")], { ...common(ctx), json: true, write })),
+        },
+        {
+            name: "nmts_support_reply",
+            description: `Answer in a report's own thread, using a code from nmts_support_list. ${CARE} The same ` +
+                "redaction runs over a reply as over the first message. At most 8000 characters.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    code: { type: "string", description: "The report's code, from nmts_support_list." },
+                    message: { type: "string", description: "What to add to the thread." },
+                    omit: OMIT_ARG,
+                },
+                required: ["code", "message"],
+                additionalProperties: false,
+            },
+            run: (args) => say((write) => support("reply", [needString(args, "code")], {
+                ...common(ctx),
+                write,
+                yes: true,
+                message: needString(args, "message"),
+                omit: stringsOf(args["omit"]),
+            })),
+        },
+    ];
+}
+/**
+ * How many runs to attach, in the shape the command takes.
+ *
+ * ⛔ THE DEFAULT IS NONE. On the command line `--attach-log` is typed on purpose; here it is a
+ *    field a model fills in, and attaching a machine's recent history to every report because
+ *    nobody said not to is the wrong default for the side that cannot see what is in it.
+ */
+function runsAsked(value) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value <= 0)
+        return {};
+    return { attachLog: String(value) };
+}
+function stringsOf(value) {
+    return Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
+}

package/dist/mcp-tools/tiers.d.ts

@@ -0,0 +1,31 @@
+import { type Autonomy } from "../autonomy.ts";
+import type { Asker } from "../mcp-ask.ts";
+import type { ToolDefinition } from "../mcp.ts";
+import { type ActId, type Tier } from "../risk.ts";
+interface ToolTier {
+    /** The act, or how to read it off the arguments when one tool both reads and sets. */
+    act: ActId | ((args: Record<string, unknown>) => ActId);
+    /** Changes nothing anywhere: the client may call it freely. */
+    readOnly?: true;
+    /** The question put to the person, when the generic one would not name what is at stake. */
+    question?: (args: Record<string, unknown>) => string;
+}
+export declare const TOOL_TIERS: Readonly<Record<string, ToolTier>>;
+/** What `tools/list` says about a tool, in the words the MCP specification gives those hints. */
+export declare function annotationsOf(name: string): Record<string, boolean>;
+/** The sentence put in front of a tool's description, so the model knows the tier before calling. */
+export declare function tierLine(tier: Tier): string;
+/** The refusal for a client that cannot be asked, and the way round it. */
+export declare function cannotAsk(what: string): string;
+/** The refusal after the question was put and not agreed to. */
+export declare const SAID_NO = "Refused: the person did not confirm it. Nothing was sent and nothing changed.";
+/**
+ * Run the tier gate for one tool call. Returns the refusal to hand back, or `null` to go ahead.
+ *
+ * ⛔ THE MODE AND THE ASKER ARE ARGUMENTS, NOT THINGS THIS READS, so every branch is tested for
+ *    the answer it gives rather than for the machine the test runs on.
+ */
+export declare function passTool(name: string, args: Record<string, unknown>, mode: Autonomy, ask: Asker, now?: Date): Promise<string | null>;
+/** Wrap the served tools: tier in the description, hints in the listing, the gate before each run. */
+export declare function withTiers(tools: readonly ToolDefinition[], asker: () => Asker): ToolDefinition[];
+export {};

package/dist/mcp-tools/tiers.js

@@ -0,0 +1,147 @@
+// Every MCP tool carries the tier of the act it performs, and the same gate the command line runs.
+//
+// ⛔ ONE TABLE, HELD AGAINST THE SURFACE BY A TEST. A tool with no row here is a tool nobody
+//    decided about, so the test compares this table with the tools actually served, both ways.
+//
+// ⛔ THE GATE RUNS BEFORE THE TOOL, IN THE TRANSPORT'S WRAPPER, so a tool cannot forget it. What
+//    it does is what `gate.ts` does for a command: a locked act is refused until a person runs
+//    `nmts unlock <key>` at a terminal; an act that needs the person's yes in this mode is put in
+//    front of them over MCP elicitation, and refused when the client has no way to ask.
+import { currentMode } from "../autonomy.js";
+import { unlocked } from "../gate.js";
+import { BINARY_NAME } from "../product.js";
+import { ACTS } from "../risk.js";
+const READ = { act: "ls", readOnly: true };
+export const TOOL_TIERS = {
+    nmts_whoami: { act: "whoami", readOnly: true },
+    nmts_list: READ,
+    nmts_usage: { act: "usage", readOnly: true },
+    nmts_expiring: { act: "expiring", readOnly: true },
+    nmts_losses: { act: "losses", readOnly: true },
+    nmts_loss_recheck: { act: "losses", readOnly: true },
+    nmts_balance: { act: "balance", readOnly: true },
+    nmts_wallet_activity: { act: "wallet", readOnly: true },
+    nmts_wallet_storage: { act: "wallet", readOnly: true },
+    nmts_devices: { act: "devices", readOnly: true },
+    nmts_public_code: { act: "public-code", readOnly: true },
+    nmts_shares: { act: "shares", readOnly: true },
+    nmts_shares_sent: { act: "shares", readOnly: true },
+    nmts_notices: { act: "notices", readOnly: true },
+    nmts_notice: { act: "notices", readOnly: true },
+    nmts_terms: { act: "terms", readOnly: true },
+    nmts_privacy: { act: "privacy", readOnly: true },
+    nmts_get: { act: "get" },
+    nmts_pull: { act: "pull" },
+    nmts_receive: { act: "receive" },
+    nmts_put: { act: "put" },
+    nmts_push: { act: "push" },
+    nmts_mkdir: { act: "mkdir" },
+    nmts_move: { act: "mv" },
+    nmts_rename: { act: "rename" },
+    nmts_mark: { act: "star" },
+    nmts_label_rename: { act: "label" },
+    nmts_unlabel_all: { act: "unlabel" },
+    nmts_padding: { act: (args) => (typeof args["mode"] === "string" ? "padding.set" : "padding") },
+    nmts_deposit: { act: (args) => (typeof args["credits"] === "number" ? "deposit.set" : "deposit") },
+    nmts_credits_transfer: {
+        act: "credits.transfer",
+        question: (args) => `Move ${String(args["credits"])} credits from this account to ${String(args["to"])}?\n\n` +
+            "Both are accounts of yours — the server refuses any other recipient. Nothing is spent by " +
+            "moving them and the same move the other way puts them back, but the credits keep the date " +
+            "they were already going to lapse on: moving them does not renew them.",
+    },
+    nmts_trash: { act: "rm" },
+    nmts_restore: { act: "restore" },
+    nmts_share: {
+        act: "share",
+        question: (args) => `Share "${String(args["path"])}" with the NMTS account whose public code is ${String(args["public_code"])}?\n\n` +
+            "Whoever holds that code can then download the file. Withdrawing the share afterwards stops " +
+            "further downloads and cannot reach a copy already fetched. The code is not checked against " +
+            "a person — if it is the wrong one, the file goes to whoever holds it.",
+    },
+    nmts_unshare: { act: "unshare" },
+    nmts_support_send: { act: "support.send" },
+    nmts_support_list: { act: "support", readOnly: true },
+    nmts_support_show: { act: "support", readOnly: true },
+    nmts_support_reply: { act: "support.send" },
+};
+/** What `tools/list` says about a tool, in the words the MCP specification gives those hints. */
+export function annotationsOf(name) {
+    const t = TOOL_TIERS[name];
+    const tier = t === undefined || typeof t.act === "function" ? "low" : ACTS[t.act].tier;
+    return {
+        readOnlyHint: t?.readOnly === true,
+        destructiveHint: tier === "high" || tier === "ultra-high",
+        idempotentHint: t?.readOnly === true,
+        openWorldHint: false,
+    };
+}
+/** The sentence put in front of a tool's description, so the model knows the tier before calling. */
+export function tierLine(tier) {
+    switch (tier) {
+        case "none":
+            return "";
+        case "low":
+            return "Tier low: asked in the default mode, runs unasked in the auto modes. ";
+        case "medium":
+            return "Tier medium: asked in the default mode; in an auto mode it is your judgement whether this is what the person wants. ";
+        case "high":
+            return `Tier high: locked until a person runs \`${BINARY_NAME} unlock\` at a terminal, and asked every time in every mode but skip-permissions. `;
+        case "ultra-high":
+            return "Tier ultra-high: a person's act, in every mode. ";
+    }
+}
+/** The refusal for a client that cannot be asked, and the way round it. */
+export function cannotAsk(what) {
+    return (`Refused: ${what} needs the person's yes in this mode, and this client cannot put a question in ` +
+        `front of them. Ask them in your own words; once they agree, run the same thing with \`${BINARY_NAME}\` ` +
+        `at the command line with --yes, or use a client that supports MCP elicitation. Nothing was done.`);
+}
+/** The refusal after the question was put and not agreed to. */
+export const SAID_NO = "Refused: the person did not confirm it. Nothing was sent and nothing changed.";
+/**
+ * Run the tier gate for one tool call. Returns the refusal to hand back, or `null` to go ahead.
+ *
+ * ⛔ THE MODE AND THE ASKER ARE ARGUMENTS, NOT THINGS THIS READS, so every branch is tested for
+ *    the answer it gives rather than for the machine the test runs on.
+ */
+export async function passTool(name, args, mode, ask, now = new Date()) {
+    const t = TOOL_TIERS[name];
+    if (t === undefined)
+        return `Refused: ${name} has no tier. Nothing was done.`;
+    const act = typeof t.act === "function" ? t.act(args) : t.act;
+    const a = ACTS[act];
+    if (a.tier === "none" || args["dry_run"] === true)
+        return null;
+    if (mode === "skip-permissions")
+        return null;
+    if (a.tier === "ultra-high")
+        return `Refused: ${a.what ?? act} is a person's act, in every mode. Nothing was done.`;
+    const what = a.what ?? `${name} does this.`;
+    if ("lock" in a && !(await unlocked(a.lock, now))) {
+        return (`Refused: ${what} It is locked on this machine. A person unlocks it at a terminal, once: ` +
+            `\`${BINARY_NAME} unlock ${a.lock}\`. Do not run that yourself. Nothing was done.`);
+    }
+    const needsYes = a.tier === "high" ? !("standing" in a) : mode === "default";
+    if (!needsYes)
+        return null;
+    if (ask === null)
+        return cannotAsk(what);
+    const outcome = await ask(t.question?.(args) ?? `${what} Go ahead?`);
+    if (outcome === "unreachable")
+        return cannotAsk(what);
+    return outcome === "yes" ? null : SAID_NO;
+}
+/** Wrap the served tools: tier in the description, hints in the listing, the gate before each run. */
+export function withTiers(tools, asker) {
+    return tools.map((tool) => {
+        const t = TOOL_TIERS[tool.name];
+        const tier = t === undefined ? "low" : typeof t.act === "function" ? ACTS[t.act({})].tier : ACTS[t.act].tier;
+        return {
+            ...tool,
+            description: `${tierLine(tier)}${tool.description}`,
+            annotations: annotationsOf(tool.name),
+            run: async (args) => (await passTool(tool.name, args, currentMode(), asker())) ?? (await tool.run(args)),
+        };
+    });
+}

package/dist/mcp.d.ts

@@ -0,0 +1,80 @@
+import { type Asker } from "./mcp-ask.ts";
+import { hermesFromParent, type HostSighting } from "./agent-host.ts";
+/** JSON-RPC 2.0, the subset MCP uses. `id` absent means a notification: no answer is sent. */
+export interface Request {
+    jsonrpc: "2.0";
+    id?: string | number;
+    method: string;
+    params?: Record<string, unknown>;
+}
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    /** The MCP hints (read-only, destructive, …); listed when present. */
+    annotations?: Record<string, boolean>;
+    /** Returns the text the model reads. Throwing produces a tool error, not a dead session. */
+    run(args: Record<string, unknown>): Promise<string>;
+}
+/**
+ * Protocol versions this server knows how to speak.
+ *
+ * ⛔ Ordered newest first. If the client asks for one of these it gets that one back; if it asks
+ *    for anything else it gets the newest we know, which is what the specification says to do —
+ *    guessing that an unknown version is compatible is how a session half-works.
+ */
+export declare const PROTOCOL_VERSIONS: readonly ["2025-06-18", "2025-03-26", "2024-11-05"];
+export interface ServerInfo {
+    name: string;
+    version: string;
+}
+/**
+ * Answer one request. Returns the response object, or `null` for a notification.
+ *
+ * Pure apart from the tools it is handed, so the whole protocol is testable without pipes.
+ */
+export declare function handle(request: unknown, tools: readonly ToolDefinition[], info: ServerInfo): Promise<Record<string, unknown> | null>;
+/** What `initialize` said about the client at the other end. */
+export interface ClientSighting {
+    /** The name the client gave, verbatim, or `null` if it gave none. */
+    name: string | null;
+    /** The agent host that name belongs to, or `null` when the name belongs to no host we know. */
+    host: HostSighting | null;
+}
+/**
+ * Who is on the other end, read out of an `initialize` request. `null` for anything else.
+ *
+ * ⛔ THE NAME IS KEPT EVEN WHEN IT MATCHES NOTHING. A client calling itself something we have never
+ *    heard of is a fact somebody can act on; turning it into `null` throws away the only evidence
+ *    that would let a person work out what is talking to them.
+ *
+ * ⚠ Hermes is the one host that sends no name of its own — the Python SDK's default arrives
+ *   instead — so it is looked for in the shape of the parent process, and only where that can be
+ *   read. On every other platform Hermes is simply not recognised.
+ */
+export declare function clientOf(request: unknown, readParent?: typeof hermesFromParent): ClientSighting | null;
+/**
+ * What the client said it can do, read out of the same `initialize` request.
+ *
+ * ⛔ SEPARATE FROM `clientOf` ON PURPOSE. Who is connected and what it can do are different
+ *    questions with different consumers, and the first one is deliberately kept usable even when
+ *    the client names itself nothing.
+ */
+export declare function capabilitiesOf(request: unknown): unknown;
+export interface ServeOptions {
+    input: NodeJS.ReadableStream;
+    /** Where protocol messages go. NOTHING else may write here. */
+    output: (line: string) => void;
+    tools: readonly ToolDefinition[];
+    info: ServerInfo;
+    /** Called once per `initialize`, with whatever the client said about itself. */
+    onClient?: (client: ClientSighting) => void;
+    /**
+     * Called once per `initialize`, with the way to ask this client a question — or `null` when it
+     * declared no way to ask. ⛔ It arrives here rather than in `ToolContext` because it cannot exist
+     * until the client has spoken, and the tools are built before that.
+     */
+    onAsker?: (asker: Asker) => void;
+}
+/** Read newline-delimited JSON-RPC from `input` until it ends, answering on `output`. */
+export declare function serve(options: ServeOptions): Promise<void>;

package/dist/mcp.js

@@ -15,7 +15,9 @@
 //   anywhere else on disk, and it cannot make or revoke a key — those need a person at a browser.
 import { createInterface } from "node:readline";
 import { checkArgs } from "./mcp-args.js";
+import { askerFor } from "./mcp-ask.js";
 import { renderError } from "./errors.js";
+import { hermesFromParent, hostFromClientInfo } from "./agent-host.js";
 /**
  * Protocol versions this server knows how to speak.
  *
@@ -34,6 +36,19 @@ function isRequest(value) {
     const v = value;
     return v["jsonrpc"] === "2.0" && typeof v["method"] === "string";
 }
+/**
+ * A JSON-RPC answer to something WE sent. The client only sends these once this server has started
+ * asking questions of its own (see `mcp-ask.ts`), and before that they were reported as malformed
+ * requests — which put an error on the wire for a message that was perfectly well formed.
+ */
+function isResponse(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    if (v["jsonrpc"] !== "2.0" || typeof v["method"] === "string")
+        return false;
+    return typeof v["id"] === "string" && ("result" in v || "error" in v);
+}
 /**
  * Answer one request. Returns the response object, or `null` for a notification.
  *
@@ -48,6 +63,10 @@ export async function handle(request, tools, info) {
     const fail = (code, message) => ({ jsonrpc: "2.0", id, error: { code, message } });
     switch (request.method) {
         case "initialize": {
+            // ⛔ `clientInfo` IS NOT READ HERE, ON PURPOSE. It changes nothing about the answer, and this
+            //    function is pure so that the whole protocol can be tested without pipes. Who connected
+            //    is a fact about the SESSION, so `serve` reads it out of the same request — see
+            //    `clientOf` below.
             const asked = request.params?.["protocolVersion"];
             const version = typeof asked === "string" && PROTOCOL_VERSIONS.includes(asked)
                 ? asked
@@ -62,7 +81,12 @@ export async function handle(request, tools, info) {
             return reply({});
         case "tools/list":
             return reply({
-                tools: tools.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })),
+                tools: tools.map((t) => ({
+                    name: t.name,
+                    description: t.description,
+                    inputSchema: t.inputSchema,
+                    ...(t.annotations === undefined ? {} : { annotations: t.annotations }),
+                })),
             });
         case "tools/call": {
             const name = request.params?.["name"];
@@ -113,9 +137,55 @@ export async function handle(request, tools, info) {
             return fail(METHOD_NOT_FOUND, `unknown method ${request.method}`);
     }
 }
+/**
+ * Who is on the other end, read out of an `initialize` request. `null` for anything else.
+ *
+ * ⛔ THE NAME IS KEPT EVEN WHEN IT MATCHES NOTHING. A client calling itself something we have never
+ *    heard of is a fact somebody can act on; turning it into `null` throws away the only evidence
+ *    that would let a person work out what is talking to them.
+ *
+ * ⚠ Hermes is the one host that sends no name of its own — the Python SDK's default arrives
+ *   instead — so it is looked for in the shape of the parent process, and only where that can be
+ *   read. On every other platform Hermes is simply not recognised.
+ */
+export function clientOf(request, readParent = hermesFromParent) {
+    if (!isRequest(request) || request.method !== "initialize")
+        return null;
+    const raw = request.params?.["clientInfo"];
+    const info = typeof raw === "object" && raw !== null && !Array.isArray(raw) ? raw : undefined;
+    const name = typeof info?.name === "string" && info.name !== "" ? info.name : null;
+    return { name, host: hostFromClientInfo(info) ?? readParent() };
+}
+/**
+ * What the client said it can do, read out of the same `initialize` request.
+ *
+ * ⛔ SEPARATE FROM `clientOf` ON PURPOSE. Who is connected and what it can do are different
+ *    questions with different consumers, and the first one is deliberately kept usable even when
+ *    the client names itself nothing.
+ */
+export function capabilitiesOf(request) {
+    if (!isRequest(request) || request.method !== "initialize")
+        return null;
+    return request.params?.["capabilities"] ?? null;
+}
 /** Read newline-delimited JSON-RPC from `input` until it ends, answering on `output`. */
 export async function serve(options) {
     const lines = createInterface({ input: options.input, crlfDelay: Infinity });
+    // ⛔ IDS WE SEND ARE IN OUR OWN NAMESPACE. JSON-RPC scopes ids per direction, so a client
+    //    numbering its requests 1, 2, 3 says nothing about ours. The prefix makes a stray answer
+    //    obviously ours to whoever is reading a transcript.
+    let asked = 0;
+    const waiting = new Map();
+    /** Tool calls still in flight. See the note in the loop for why they are not awaited there. */
+    const running = new Set();
+    const send = (method, params) => {
+        asked += 1;
+        const id = `nmts-${asked}`;
+        return new Promise((resolve) => {
+            waiting.set(id, resolve);
+            options.output(JSON.stringify({ jsonrpc: "2.0", id, method, params }));
+        });
+    };
     for await (const line of lines) {
         if (line.trim() === "")
             continue;
@@ -127,16 +197,47 @@ export async function serve(options) {
             options.output(JSON.stringify({ jsonrpc: "2.0", id: null, error: { code: PARSE_ERROR, message: "invalid JSON" } }));
             continue;
         }
-        let response;
-        try {
-            response = await handle(parsed, options.tools, options.info);
+        // An answer to one of ours is routed and never handled as a request.
+        if (isResponse(parsed)) {
+            const resolve = waiting.get(parsed.id);
+            if (resolve !== undefined) {
+                waiting.delete(parsed.id);
+                // ⛔ An `error` answer resolves with `undefined` rather than throwing. The caller reads
+                //    "not an accept" out of that, which is the same no it gives for every other shape it
+                //    cannot read — one refusal path instead of two.
+                resolve("result" in parsed ? parsed.result : undefined);
+            }
+            continue;
         }
-        catch (error) {
+        const client = clientOf(parsed);
+        if (client !== null) {
+            options.onClient?.(client);
+            options.onAsker?.(askerFor(capabilitiesOf(parsed), send));
+        }
+        // ⛔ THE LOOP DOES NOT WAIT FOR THE TOOL, AND THAT IS NOT AN OPTIMISATION. This server now
+        //    asks the client questions from inside a tool call (`mcp-ask.ts`), and the answer arrives
+        //    as another line on this same pipe. Awaiting the tool here would mean the loop cannot read
+        //    the answer until the tool finishes, and the tool cannot finish until the answer is read —
+        //    a deadlock that no test of the pieces would find, because each piece is correct.
+        //
+        // ⛔ REPLIES MAY THEREFORE COME BACK OUT OF ORDER, WHICH JSON-RPC ALLOWS: every reply carries
+        //    the id it answers. Nothing here shares state between calls, so two in flight cannot see
+        //    each other.
+        const job = handle(parsed, options.tools, options.info)
+            .catch((error) => {
             // The handler itself falling over must not end the session either.
             const message = error instanceof Error ? error.message : "the server failed";
-            response = { jsonrpc: "2.0", id: null, error: { code: INTERNAL_ERROR, message } };
-        }
-        if (response !== null)
-            options.output(JSON.stringify(response));
+            return { jsonrpc: "2.0", id: null, error: { code: INTERNAL_ERROR, message } };
+        })
+            .then((response) => {
+            if (response !== null)
+                options.output(JSON.stringify(response));
+        });
+        running.add(job);
+        void job.finally(() => running.delete(job));
     }
+    // ⛔ THE INPUT ENDING IS NOT THE SESSION ENDING. A client that closes the pipe with a tool still
+    //    running gets its answer written before this returns; dropping it would lose work already
+    //    done, and in the paid tools that means work already charged for.
+    await Promise.all(running);
 }