@floatonnear/mcp 0.6.4 → 0.9.0

package/dist/server.js

@@ -53,13 +53,14 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { topUpFor, paymentsAfterTopUp } from "./gas-math.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { fromBaseUnits, toBaseUnits } from "./amounts.js";
-import { DEFAULT_GAS_TGAS, planAddNode, planAddRole, planBindVirtualAgent, planUnbindVirtualAgent, planFreezeNode, planPurgeSettled, planSetCooldown, planSetNodeCaps, planSetPaused, planSetRecipients, toCliCommand, planSetApprovalThreshold, planApprovePayment, planRejectPayment, planWithdraw, } from "./payloads.js";
-import { accountExists, rpcForNetwork, newRequestId, requireAgentKey, viewAccessKeys, viewAccount, viewFunction, } from "./rpc.js";
+import { fromBaseUnits, humaniseTreeNode, toBaseUnits } from "./amounts.js";
+import { DEFAULT_GAS_TGAS, planAddNode, planAddRole, planBindVirtualAgent, planUnbindVirtualAgent, planFreezeNode, planPurgeSettled, planSetCooldown, planSetNodeCaps, planSetPaused, planSetRecipients, planSetStrictAllocation, toCliCommand, planSetApprovalThreshold, planApprovePayment, planRejectPayment, planWithdraw, } from "./payloads.js";
+import { accountExists, rpcForNetwork, RPC_BY_NETWORK, newRequestId, requireAgentKey, viewAccessKeys, viewAccount, viewFunction, } from "./rpc.js";
 import { AGENT_NODE_ID, generateAgentKey } from "./agent-key.js";
 import { resolveKeySource } from "./key-file.js";
 import { dirname } from "node:path";
 import { listAgents, listRoles, selectRole } from "./roles.js";
+import { label as tokenLabel, tokenMeta } from "./token-meta.js";
 /**
  * A decimal NEAR string to yoctoNEAR, without floating point.
  *
@@ -74,6 +75,7 @@ function toYoctoNear(n) {
 }
 import { buildCreatePlan, FACTORY_BY_NETWORK } from "./create.js";
 import { buildRoute, sendRequestPayment } from "./sign.js";
+import { explainOutcome } from "./explain.js";
 import { getQuote, signBinding, toBase64 } from "./quote.js";
 /** How long a quote stays valid. Long enough to sign and send, short
  *  enough that a stale price is not honoured. */
@@ -123,8 +125,36 @@ for (const err of [agentKeySource.error, quoteSignerSource.error]) {
  *
  * It used to be read inside the object literal, which meant `rpcUrl` could not
  * see it and fell back to a constant. See below.
+ *
+ * MAINNET IS THE DEFAULT, and it used to be testnet. The five CLIs all default
+ * to `--network mainnet`, so an operator who ran `create-float` and then
+ * started this server got a MAINNET vault being read by a TESTNET client, with
+ * nothing anywhere saying so. The symptom is not an error: reads answer
+ * "account does not exist" about an account holding real money, which reads as
+ * "Float is broken" rather than "these two halves disagree".
+ *
+ * Testnet is still one env var away. The asymmetry was the bug, not the value.
+ */
+const NETWORK = process.env.NEAR_VAULT_NETWORK ?? "mainnet";
+/**
+ * An unrecognised network FAILS CLOSED.
+ *
+ * `rpcForNetwork` falls back to a testnet endpoint for any string it does not
+ * know, and that fallback is pinned by a test, so it stays. But it means
+ * `NEAR_VAULT_NETWORK=Mainnet` — a capital letter — would resolve to TESTNET
+ * and answer mainnet questions about the wrong chain, confidently. That is the
+ * exact failure this server already shipped once by a different route.
+ *
+ * So validate at the boundary rather than widening the fallback: a typo should
+ * stop the server, not quietly move it to another chain.
  */
-const NETWORK = process.env.NEAR_VAULT_NETWORK ?? "testnet";
+if (!Object.hasOwn(RPC_BY_NETWORK, NETWORK)) {
+    console.error(`float: NEAR_VAULT_NETWORK is "${NETWORK}", which is not a network this server knows ` +
+        `(${Object.keys(RPC_BY_NETWORK).join(", ")}). Refusing to start rather than guessing a ` +
+        `chain — an unrecognised value would otherwise resolve to a testnet endpoint and answer ` +
+        `questions about the wrong chain.`);
+    process.exit(1);
+}
 const cfg = {
     vault: process.env.NEAR_VAULT_CONTRACT ?? "",
     /**
@@ -280,19 +310,39 @@ WORKFLOW
   5. Winding down is a CLI job, not a tool: npx -p @floatonnear/create-float float-exit. It returns the tokens,
      the gas-key balances and the storage deposit. vault_teardown_report says what is recoverable.
 
-REFUSALS ARE ANSWERS. Report the reason code, do not retry blindly:
-  DAILY_BUDGET         this agent's own cap is spent.
-  PARENT_DAILY_BUDGET  a SIBLING drained the shared pool; this agent's own cap may look free.
-  PER_TX_LIMIT         one payment was too large; splitting it may still be refused by the cap.
-  NO_RECIPIENTS_SET    the node pays nobody yet; that is an owner decision, via vault_plan_set_recipients.
+SPEAK LIKE A PERSON. NEVER SHOW A REASON CODE TO THE USER.
+  vault_pay returns "say" -- a plain-English sentence with the real numbers in it -- plus
+  "next_step" and "money_moved". RELAY "say". Add "next_step" if there is one. That is the
+  whole reply; do not append the code, the request id, or the raw JSON.
+
+  A user who asked to pay someone and got "PARENT_PER_TX_LIMIT" has been told nothing. The
+  codes are precise and they do matter -- they are under "technical" for debugging, and you
+  should quote them only if the user asks why, asks for detail, or is clearly a developer.
+
+  Say this:   "That is too big for one payment -- the most per payment is 10 USDC, and this
+               asked for 15. Nothing was sent. Send 10 USDC or less, or ask the vault owner
+               to raise the limit."
+  Not this:   "The payment was BLOCKED with reason_code PARENT_PER_TX_LIMIT."
+
+  On success too: "Sent 0.25 USDC to alice.near. There is 24.75 USDC left to spend today."
+  Not "status: SETTLED".
+
+  REFUSALS ARE ANSWERS, not errors. Do not retry blindly -- a refused payment is the contract
+  doing its job. "money_moved" tells you whether anything actually left the vault; never imply
+  money moved when it is false, and never imply money is lost when a refusal was free.
 
 WORTH KNOWING
   Budgets are hierarchical: a payment charges every ancestor, so a vault-wide ceiling holds even
   when a child's cap looks free.
+  Understand the difference between DAILY_BUDGET and PARENT_DAILY_BUDGET even though you must
+  not print either. DAILY_BUDGET means this agent spent its own allowance. PARENT_DAILY_BUDGET
+  means a SIBLING drained the shared pool, so this agent's own cap can still read as fully
+  available -- a user who checks their budget, sees room, and is told only "refused" will
+  reasonably think the product is broken. Neither is fixed by retrying.
   An implicit account (a 64-character hex id) cannot own a vault at all. Tell the user to use a
   named account rather than retrying.
   Amounts are whole tokens in these tools (1.5 means 1.5 USDC), never base units.`;
-const server = new McpServer({ name: "float", version: "0.6.4" }, { instructions: INSTRUCTIONS });
+const server = new McpServer({ name: "float", version: "0.9.0" }, { instructions: INSTRUCTIONS });
 // ----------------------------------------------------------------- reads
 /**
  * Wait for a create to land, and prove the result belongs to the user.
@@ -388,6 +438,36 @@ server.tool("vault_await_create", "After the user signs the create link, confirm
     }
     // THE OWNER READ IS THE POINT. Getting here only proves an account exists.
     const config = await viewFunction(rpc, target, "get_config", {}).catch(() => null);
+    /**
+     * A `get_config` WITH AN OWNER IS NOT PROOF OF A VAULT.
+     *
+     * The FACTORY also exports `get_config`, and it also returns an `owner` —
+     * so pointing this tool at `usefloat.near` with the factory's own owner
+     * returned **LIVE**, and the next step it printed was
+     * `NEAR_VAULT_CONTRACT=usefloat.near`. Every later read would then query a
+     * factory for budgets it does not have.
+     *
+     * Measured 2026-11-12 on mainnet: the two shapes are cleanly separable --
+     * a vault answers `vault_id, owner, network, paused, strict_allocation,
+     * node_count, clock_mode`; the factory answers `owner, code_hash, network,
+     * required_deposit, paused`. `vault_id` is the discriminator, and it is the
+     * field whose presence means "I am the vault you are asking about".
+     *
+     * Checked BEFORE the owner comparison, because "this is not a vault" is a
+     * different and more fundamental answer than "this vault is someone
+     * else's", and reporting the latter about a factory would send someone
+     * looking for a nonexistent rival owner.
+     */
+    if (config && typeof config.vault_id !== "string") {
+        return json({
+            status: "UNVERIFIED",
+            vault: target,
+            instruction: `${target} answers get_config but it is NOT a Float vault — a vault's config ` +
+                `carries vault_id, and this one does not. The factory exports get_config too, ` +
+                `with an owner field, so "it responded and the owner matched" is not proof. Do ` +
+                `NOT set NEAR_VAULT_CONTRACT to it.`,
+        });
+    }
     if (!config || typeof config.owner !== "string") {
         return json({
             status: "UNVERIFIED",
@@ -420,7 +500,64 @@ server.tool("vault_await_create", "After the user signs the create link, confirm
         ],
     });
 });
-server.tool("vault_tree", "Read the whole budget tree: every node, its caps, parent, bound agent account, cooldown and freeze state. No key required.", {}, async () => json(await viewFunction(cfg.rpcUrl, requireVault(), "get_tree", {})));
+/**
+ * Resolve every token named in a tree, once, so output can say "USDC".
+ *
+ * Fetched in PARALLEL and deduplicated: a tree with five nodes sharing one
+ * token must make one call, not five. `tokenMeta` caches for the process
+ * lifetime, so the second `vault_tree` of a session makes none.
+ */
+async function metaFor(tokens) {
+    const unique = [...new Set(tokens)];
+    const pairs = await Promise.all(unique.map(async (t) => [
+        t,
+        await tokenMeta(cfg.rpcUrl, t, (rpc, token) => viewFunction(rpc, token, "ft_metadata", {})),
+    ]));
+    return new Map(pairs);
+}
+server.tool("vault_tree", "Read the whole budget tree: every node, its caps, parent, bound agent account, cooldown and freeze state. No key required.", {}, async () => {
+    const tree = (await viewFunction(cfg.rpcUrl, requireVault(), "get_tree", {}));
+    if (!Array.isArray(tree))
+        return json(tree);
+    const meta = await metaFor(tree.flatMap((n) => n.limits?.map((l) => l.token) ?? []));
+    /**
+     * THE APPROVAL THRESHOLD WAS WRITE-ONLY.
+     *
+     * `vault_plan_set_approval_threshold` builds a payload to set one, and
+     * `get_effective_threshold` has always existed on the contract — but
+     * nothing read it back. So an owner could impose a rule and then had no
+     * way to see it, and an agent could not warn "this payment will be HELD"
+     * before making one. A policy you cannot read is a policy you cannot
+     * trust.
+     *
+     * EFFECTIVE, not the node's own: a threshold INHERITS down the tree, so
+     * the figure that actually governs a node may have been set on an
+     * ancestor. Reporting the local one would under-report the rule in force.
+     */
+    const thresholds = await Promise.all(tree.map((n) => viewFunction(cfg.rpcUrl, requireVault(), "get_effective_threshold", {
+        node_id: n.id,
+    }).catch(() => null)));
+    return json(tree.map((n, i) => {
+        const node = humaniseTreeNode(n, { token: cfg.token, decimals: cfg.decimals, meta });
+        const raw = thresholds[i];
+        if (raw === null || raw === undefined)
+            return node;
+        const tok = n.limits?.[0]?.token;
+        const d = (tok ? meta.get(tok)?.decimals : undefined) ?? cfg.decimals;
+        let human = String(raw);
+        try {
+            human = fromBaseUnits(BigInt(human), d);
+        }
+        catch {
+            /* surface what the contract said */
+        }
+        return {
+            ...node,
+            approval_threshold: human,
+            approval_note: `Payments above ${human} from this node are HELD until the owner approves them.`,
+        };
+    }));
+});
 server.tool("vault_budget", "Read one node's budget for a UTC day: cap, executed, in-flight (pending) and available, in human units. Omit `day` for today. No key required.", {
     nodeId: z.number().int().min(0),
     token: z.string().optional(),
@@ -431,20 +568,225 @@ server.tool("vault_budget", "Read one node's budget for a UTC day: cap, executed
         token: tokenFor(token),
         day: day ?? null,
     }));
-    if (!b)
-        return text(`node ${nodeId} has no limit for that token`);
-    const d = cfg.decimals;
+    if (!b) {
+        // "no limit for that token" ASSERTED THAT THE NODE EXISTS. Asked about
+        // node 999 of a two-node vault it said the same thing, which sends a
+        // user off to set a limit on a node that is not there. Two different
+        // facts had one message.
+        const missing = await assertNode(nodeId);
+        if (missing)
+            return text(noNodeForRead(nodeId, missing.known));
+        const tree = (await viewFunction(cfg.rpcUrl, requireVault(), "get_tree", {}).catch(() => null));
+        const here = tree?.find((n) => n.id === nodeId)?.limits?.map((l) => l.token) ?? [];
+        return text(`Node ${nodeId} exists but has no limit for ${tokenFor(token)}. ` +
+            (here.length
+                ? `It has limits for: ${here.join(", ")}.`
+                : `It has no limits for any token, so it can pay nothing — set one with vault_plan_set_caps.`));
+    }
+    // The TOKEN's own decimals, not the configured guess. A vault may hold
+    // caps for several tokens and only one of them is NEAR_VAULT_TOKEN.
+    const tok = tokenFor(token);
+    const meta = (await metaFor([tok])).get(tok) ?? null;
+    const d = meta?.decimals ?? cfg.decimals;
     return json({
         node_id: nodeId,
+        token: tokenLabel(tok, meta),
+        /**
+         * `day: 20768` MEANS NOTHING TO A PERSON. It is days since the Unix
+         * epoch, which is the right key for a ledger and the wrong thing to
+         * show someone asking what they have left. The number stays — it is
+         * what the contract indexes by, and a support conversation needs it —
+         * but the date leads, and the reset is stated because "daily" does not
+         * say WHEN, and a budget that resets at midnight in a timezone you do
+         * not live in is a surprise worth pre-empting.
+         */
+        date: new Date(Number(b.day) * 86_400_000).toISOString().slice(0, 10),
         day: b.day,
+        resets: "00:00 UTC",
         daily_cap: fromBaseUnits(BigInt(b.daily_cap), d),
         executed: fromBaseUnits(BigInt(b.executed), d),
         pending: fromBaseUnits(BigInt(b.pending), d),
         available: fromBaseUnits(BigInt(b.available), d),
     });
 });
-server.tool("vault_request", "Read one stored payment request: status, reason code, amount, the ancestor chain it charged, and the UTC day it was reserved against. No key required.", { requestId: z.string() }, async ({ requestId }) => json(await viewFunction(cfg.rpcUrl, requireVault(), "get_request", { request_id: requestId })));
-server.tool("vault_config", "Read vault config: owner, paused, strict-vs-overcommit allocation, node count, and clock mode. No key required.", {}, async () => json(await viewFunction(cfg.rpcUrl, requireVault(), "get_config", {})));
+/**
+ * THE ACTIVITY FEED, which nothing exposed.
+ *
+ * `list_requests` has been on the contract all along. The MCP had only
+ * `vault_request(requestId)` — a lookup by an id you can obtain *only* from a
+ * `vault_pay` response — so a user asking "what has my agent been spending
+ * on?" had nothing but running totals. For the one question people ask most
+ * about an autonomous spender, the answer was a number with no history behind
+ * it.
+ *
+ * THE CAVEAT IS LOAD-BEARING AND THE CONTRACT SAYS SO ITSELF: a BLOCKED
+ * request is never stored. The hot path returns the refusal as a value and
+ * emits an event, deliberately, because storing rejected attempts would let
+ * an agent inflate the vault's storage bill at will. So this feed shows
+ * in-flight, settled and failed payments — and an agent that was refused
+ * every time looks identical to one that never tried.
+ *
+ * Reporting that silently would be the worst kind of wrong: "no payments" is
+ * exactly what a user wants to hear when the real answer is "twelve refusals
+ * you cannot see here". So the caveat ships WITH the data, every time, rather
+ * than in a doc nobody opens.
+ */
+server.tool("vault_history", "The vault's payment activity, newest first: what was paid, to whom, when, and how each one ended. Use this for 'what has my agent been spending on?'. No key required. IMPORTANT: refused payments are NOT recorded here — the contract deliberately does not store them, so an agent that was blocked every time looks the same as one that never tried.", {
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .optional()
+        .describe("how many to return, newest first. Default 20."),
+    fromIndex: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe("skip this many of the newest, to page backwards through history."),
+}, async ({ limit, fromIndex }) => {
+    const rows = (await viewFunction(cfg.rpcUrl, requireVault(), "list_requests", {
+        from_index: fromIndex ?? 0,
+        limit: limit ?? 20,
+    }));
+    if (!Array.isArray(rows))
+        return json(rows);
+    const meta = await metaFor(rows.map((r) => String(r.token)));
+    const payments = rows.map((r) => {
+        const m = meta.get(String(r.token)) ?? null;
+        const d = m?.decimals ?? cfg.decimals;
+        let amount = String(r.amount);
+        try {
+            amount = fromBaseUnits(BigInt(amount), d);
+        }
+        catch {
+            /* a figure the contract produced is a fact; surface it unchanged */
+        }
+        return {
+            request_id: r.request_id,
+            status: r.status,
+            reason: r.reason_code,
+            amount,
+            token: tokenLabel(String(r.token), m),
+            to: r.recipient,
+            node_id: r.node_id,
+            ...(r.memo ? { memo: r.memo } : {}),
+            // Nanoseconds are what the contract stores and not what anyone reads.
+            when: new Date(Number(BigInt(String(r.created_at_ns)) / 1000000n)).toISOString(),
+            charged_on_utc_day: r.reserved_day,
+        };
+    });
+    return json({
+        count: payments.length,
+        payments,
+        not_shown: "REFUSED payments are not in this list. The contract does not store a blocked " +
+            "request — that would let an agent grow the vault's storage bill by spamming " +
+            "refusals — so it returns the reason to the caller and emits an event instead. " +
+            "An empty list therefore means 'nothing was paid', NOT 'nothing was attempted'.",
+        ...(payments.length === (limit ?? 20)
+            ? { more: `Possibly more: pass fromIndex=${(fromIndex ?? 0) + payments.length}.` }
+            : {}),
+    });
+});
+server.tool("vault_request", "Read one stored payment request: status, reason code, amount, the ancestor chain it charged, and the UTC day it was reserved against. No key required.", { requestId: z.string() }, async ({ requestId }) => {
+    const r = await viewFunction(cfg.rpcUrl, requireVault(), "get_request", {
+        request_id: requestId,
+    });
+    // A BARE `null` IS AMBIGUOUS and this tool returned one. To a reader it is
+    // indistinguishable from a failed call, and to an agent it is a value to
+    // guess about rather than a fact to relay. Requests are also PURGEABLE, so
+    // "not found" has two very different causes and the honest answer names
+    // both instead of implying the payment never happened.
+    if (r === null || r === undefined) {
+        return text(`No request "${requestId}" on ${cfg.vault}. Either the id is wrong, or the ` +
+            `request was settled and later removed by purge_settled — purging is how a ` +
+            `vault reclaims storage, so an OLD successful payment can legitimately be gone. ` +
+            `vault_tree and vault_budget still reflect what it spent.`);
+    }
+    return json(r);
+});
+server.tool("vault_config", "Read vault config: owner, paused, strict-vs-overcommit allocation, node count, and clock mode. No key required.", {}, async () => {
+    const c = (await viewFunction(cfg.rpcUrl, requireVault(), "get_config", {}));
+    if (!c || typeof c !== "object")
+        return json(c);
+    /**
+     * EXPLAIN THE HIERARCHY, because it is the whole product and nothing
+     * showed it.
+     *
+     * `vault_tree` prints `child_cap_sum` and leaves the reader to work out
+     * what it implies. The implication is the entire differentiator: budgets
+     * are hierarchical, a payment charges every ancestor, and so a SIBLING
+     * spending first can exhaust a shared pool while your own cap still reads
+     * "25 of 25 available". That is the moment `PARENT_DAILY_BUDGET` arrives
+     * and looks like a bug.
+     *
+     * `strict_allocation` is the switch that decides whether that can happen
+     * at all, and as a bare boolean it told nobody anything — a reader cannot
+     * tell whether `false` is the safe setting or the dangerous one.
+     *
+     * Computed from the TREE rather than restated from config, so the numbers
+     * are the ones actually in force.
+     */
+    const tree = (await viewFunction(cfg.rpcUrl, requireVault(), "get_tree", {}).catch(() => null));
+    let allocation;
+    const root = Array.isArray(tree) ? tree.find((n) => n.id === 0) : null;
+    if (root) {
+        const lim = root.limits?.[0];
+        const sum = root.child_cap_sum?.[0];
+        if (lim && sum) {
+            const meta = (await metaFor([lim.token])).get(lim.token) ?? null;
+            const d = meta?.decimals ?? cfg.decimals;
+            const cap = BigInt(lim.daily_cap);
+            const allocated = BigInt(sum[1]);
+            const strict = c.strict_allocation === true;
+            allocation = {
+                token: tokenLabel(lim.token, meta),
+                root_daily_cap: fromBaseUnits(cap, d),
+                allocated_to_children: fromBaseUnits(allocated, d),
+                unallocated: fromBaseUnits(cap > allocated ? cap - allocated : 0n, d),
+                mode: strict ? "strict" : "overcommit",
+                meaning: strict
+                    ? "Children's caps may not sum above the parent's, so each child's cap is " +
+                        "genuinely its own and a sibling cannot take it."
+                    : "Children's caps MAY sum above the parent's. A sibling that spends first can " +
+                        "exhaust the shared pool, and the others are then refused PARENT_DAILY_BUDGET " +
+                        "while their OWN cap still shows as available. That refusal is the design " +
+                        "working, not a fault.",
+                ...(allocated >= cap && cap > 0n
+                    ? {
+                        note: "Children are allocated the ENTIRE root budget, so any second agent would " +
+                            "share this pool rather than add to it.",
+                    }
+                    : {}),
+            };
+        }
+    }
+    /**
+     * AN OWNERSHIP TRANSFER IN FLIGHT WAS INVISIBLE.
+     *
+     * `get_pending_owner` exists and nothing read it. A two-step transfer is
+     * the safe design — the new owner must accept — but a half-finished one
+     * is exactly the state worth seeing, and `owner` alone shows the OLD
+     * owner with no hint that control is mid-handover.
+     */
+    const pendingOwner = await viewFunction(cfg.rpcUrl, requireVault(), "get_pending_owner", {}).catch(() => null);
+    return json({
+        ...c,
+        ...(pendingOwner
+            ? {
+                pending_owner: pendingOwner,
+                ownership_note: `A transfer to ${pendingOwner} is IN FLIGHT. ${c.owner} still controls this ` +
+                    `vault until ${pendingOwner} accepts.`,
+            }
+            : {}),
+        // A bare `clock_mode: "production"` invites the question it does not
+        // answer. The test clock exists so integration tests can roll a UTC day
+        // without waiting; seeing it on a real vault would be alarming.
+        clock: c.clock_mode === "production" ? "real UTC time" : `TEST CLOCK (${c.clock_mode})`,
+        ...(allocation ? { allocation } : {}),
+    });
+});
 server.tool("vault_add_role", "Add a NEW departmental agent to an existing vault — e.g. a 'marketing' or 'news' agent with its own budget. Generates the agent's key, files it under the role name, and returns an UNSIGNED payload for the owner to approve. One FunctionCall creates the node, binds the key and installs its funded gas key. This server never signs it.", {
     role: z
         .string()
@@ -779,7 +1121,77 @@ server.tool("vault_pay", "Send a payment from the agent's node. Signs with the a
         gasTgas: DEFAULT_GAS_TGAS,
         route,
     });
-    return json(out);
+    /**
+     * HAND THE AGENT THE SENTENCE, do not hope it writes a good one.
+     *
+     * This used to `return json(out)` — just the contract's four fields — and
+     * the instructions said "Report the reason code", so a user who asked to
+     * pay someone got `PARENT_PER_TX_LIMIT` back. Correct, and useless to them.
+     *
+     * A good explanation needs NUMBERS the payment response never carried: the
+     * per-payment cap, what is left today. So read them HERE, on the way out,
+     * and only when they will be used. The budget read is one view call; the
+     * caps come from the tree, fetched only when a limit actually fired.
+     *
+     * The code is NOT discarded — it moves under `technical`. Knowing exactly
+     * which rule fired is a real asset (PARENT_DAILY_BUDGET meaning "a sibling
+     * drained the shared pool" is something a flat policy model cannot say),
+     * it is just not what a person wants first.
+     */
+    const o = out;
+    const limitFired = /PER_TX_LIMIT|DAILY_BUDGET/.test(o.reason_code ?? "");
+    const settled = o.status === "SETTLED";
+    const tok = tokenFor(token);
+    // The token's own symbol and decimals, cached process-wide, so the sentence
+    // says "USDC" and not a 64-character contract id.
+    const meta = await tokenMeta(cfg.rpcUrl, tok, (rpc, t) => viewFunction(rpc, t, "ft_metadata", {})).catch(() => null);
+    const dec = meta?.decimals ?? cfg.decimals;
+    let perTxCap;
+    let available;
+    let dailyCap;
+    const nodeId = o.node_id;
+    if (nodeId !== undefined && (limitFired || settled)) {
+        // One view call, and it is the figure BOTH a success and a daily-cap
+        // refusal want.
+        const b = await viewFunction(cfg.rpcUrl, vault, "get_node_budget", { node_id: nodeId, token: tok }).catch(() => null);
+        if (b) {
+            available = fromBaseUnits(BigInt(b.available), dec);
+            dailyCap = fromBaseUnits(BigInt(b.daily_cap), dec);
+        }
+        if (limitFired) {
+            const tree = await viewFunction(cfg.rpcUrl, vault, "get_tree", {}).catch(() => null);
+            if (tree) {
+                const byId = new Map(tree.map((n) => [n.id, n]));
+                let smallest;
+                for (let cur = byId.get(nodeId); cur !== undefined; cur = cur.parent === null ? undefined : byId.get(cur.parent)) {
+                    const lim = (cur.limits ?? []).find((l) => l.token === tok);
+                    if (!lim)
+                        continue;
+                    const v = BigInt(lim.per_tx_cap);
+                    if (smallest === undefined || v < smallest)
+                        smallest = v;
+                }
+                if (smallest !== undefined)
+                    perTxCap = fromBaseUnits(smallest, dec);
+            }
+        }
+    }
+    const explained = explainOutcome({
+        status: o.status,
+        reason_code: o.reason_code,
+        amount,
+        recipient,
+        symbol: meta?.symbol ?? "tokens",
+        perTxCap,
+        available,
+        dailyCap,
+    });
+    return json({
+        say: explained.say,
+        next_step: explained.next,
+        money_moved: explained.moved,
+        technical: out,
+    });
 });
 // ------------------------------------------------------- plans (unsigned)
 server.tool("vault_plan_add_node", "Build an UNSIGNED payload to create a budget node. Pass parent=null for the root. Not signed by this server.", {
@@ -789,15 +1201,75 @@ server.tool("vault_plan_add_node", "Build an UNSIGNED payload to create a budget
     cooldownSec: z.number().int().min(0).default(0),
     recipients: z.array(z.string()).nullable().default(null),
 }, async ({ parent, label, limits, cooldownSec, recipients }) => renderPlan(planAddNode(requireVault(), parent, label, limits, cooldownSec, recipients)));
-server.tool("vault_plan_set_caps", "Build an UNSIGNED payload to change a node's daily and per-payment caps. Not signed by this server.", { nodeId: z.number().int().min(0), limits: limitShape }, async ({ nodeId, limits }) => renderPlan(planSetNodeCaps(requireVault(), nodeId, limits)));
+/**
+ * Refuse to build a signable payload for a node that does not exist.
+ *
+ * PLAN TOOLS HANDED OUT PAYLOADS FOR ANY `nodeId`. Measured 2026-11-10:
+ * `vault_plan_set_caps({nodeId: 999})` against a two-node vault returned a
+ * cheerful summary — "Set node 999 caps to … 1/day" — and a complete unsigned
+ * transaction. The user approves it in their wallet, pays the gas, and the
+ * CONTRACT rejects it. The cost is small and the experience is not: the only
+ * signal anything was wrong arrives after a signature, from a layer the user
+ * cannot read.
+ *
+ * A plan tool's entire job is to produce something safe to sign. "Safe to
+ * sign" has to include "addresses something real".
+ *
+ * Costs one view call per plan. That is the right trade against a wasted
+ * signature, and these are human-speed operations — nobody plans in a loop.
+ *
+ * Returns the node ids that DO exist, because "999 does not exist" without
+ * them just prompts another guess.
+ */
+async function assertNode(nodeId) {
+    const tree = (await viewFunction(cfg.rpcUrl, requireVault(), "get_tree", {}).catch(() => null));
+    // A failed READ must not block a plan: the chain being briefly unreachable
+    // is not evidence the node is missing, and refusing here would turn a blip
+    // into "your node does not exist".
+    if (!Array.isArray(tree))
+        return null;
+    if (tree.some((n) => n.id === nodeId))
+        return null;
+    // RETURNS THE FACTS, NOT A SENTENCE. The first version returned prose and
+    // the read path tried to reuse it by regex-stripping the signing clause,
+    // which left "no node 999, Nodes: ...". Composing at the call site costs two
+    // lines and cannot produce a mangled sentence.
+    return { known: tree.map((n) => `${n.id}${n.label ? ` (${n.label})` : ""}`).join(", ") };
+}
+/** For a PLAN: the cost of getting this wrong is a wasted signature. */
+const noNodeForPlan = (nodeId, known) => `This vault has no node ${nodeId}, so that payload would be refused by the ` +
+    `contract AFTER you signed and paid for it. Nodes: ${known}.`;
+/** For a READ: nothing is at stake, so just say what exists. */
+const noNodeForRead = (nodeId, known) => `This vault has no node ${nodeId}. Nodes: ${known}.`;
+server.tool("vault_plan_set_caps", "Build an UNSIGNED payload to change a node's daily and per-payment caps. Not signed by this server.", { nodeId: z.number().int().min(0), limits: limitShape }, async ({ nodeId, limits }) => {
+    const bad = await assertNode(nodeId);
+    return bad
+        ? text(noNodeForPlan(nodeId, bad.known))
+        : renderPlan(planSetNodeCaps(requireVault(), nodeId, limits));
+});
 server.tool("vault_plan_bind_agent", "Build an UNSIGNED payload binding a signing key to a node, so that key may spend from it. Generate the keypair yourself and pass only the public half. Many keys may share one node. Not signed by this server.", {
     nodeId: z.number().int().min(0),
     publicKey: z.string().describe("ed25519:..."),
 }, async ({ nodeId, publicKey }) => renderPlan(planBindVirtualAgent(requireVault(), nodeId, publicKey)));
 server.tool("vault_plan_unbind_agent", "Build an UNSIGNED payload revoking a signing key's authority to spend. Does NOT return any gas left in that key's NEP-611 gas key — withdraw from the gas key separately. Not signed by this server.", { publicKey: z.string().describe("ed25519:...") }, async ({ publicKey }) => renderPlan(planUnbindVirtualAgent(requireVault(), publicKey)));
-server.tool("vault_plan_freeze", "Build an UNSIGNED payload to freeze or unfreeze a node. Freezing blocks the node AND its whole subtree. Not signed by this server.", { nodeId: z.number().int().min(0), frozen: z.boolean() }, async ({ nodeId, frozen }) => renderPlan(planFreezeNode(requireVault(), nodeId, frozen)));
-server.tool("vault_plan_set_recipients", "Build an UNSIGNED payload to set a node's payee allowlist. This REPLACES the inherited list rather than adding to it; pass null to inherit. Not signed by this server.", { nodeId: z.number().int().min(0), recipients: z.array(z.string()).nullable() }, async ({ nodeId, recipients }) => renderPlan(planSetRecipients(requireVault(), nodeId, recipients)));
-server.tool("vault_plan_set_cooldown", "Build an UNSIGNED payload to set the minimum seconds between a node's payments. Not signed by this server.", { nodeId: z.number().int().min(0), cooldownSec: z.number().int().min(0) }, async ({ nodeId, cooldownSec }) => renderPlan(planSetCooldown(requireVault(), nodeId, cooldownSec)));
+server.tool("vault_plan_freeze", "Build an UNSIGNED payload to freeze or unfreeze a node. Freezing blocks the node AND its whole subtree. Not signed by this server.", { nodeId: z.number().int().min(0), frozen: z.boolean() }, async ({ nodeId, frozen }) => {
+    const bad = await assertNode(nodeId);
+    return bad
+        ? text(noNodeForPlan(nodeId, bad.known))
+        : renderPlan(planFreezeNode(requireVault(), nodeId, frozen));
+});
+server.tool("vault_plan_set_recipients", "Build an UNSIGNED payload to set a node's payee allowlist. This REPLACES the inherited list rather than adding to it; pass null to inherit. Not signed by this server.", { nodeId: z.number().int().min(0), recipients: z.array(z.string()).nullable() }, async ({ nodeId, recipients }) => (async () => {
+    const bad = await assertNode(nodeId);
+    return bad
+        ? text(noNodeForPlan(nodeId, bad.known))
+        : renderPlan(planSetRecipients(requireVault(), nodeId, recipients));
+})());
+server.tool("vault_plan_set_cooldown", "Build an UNSIGNED payload to set the minimum seconds between a node's payments. Not signed by this server.", { nodeId: z.number().int().min(0), cooldownSec: z.number().int().min(0) }, async ({ nodeId, cooldownSec }) => {
+    const bad = await assertNode(nodeId);
+    return bad
+        ? text(noNodeForPlan(nodeId, bad.known))
+        : renderPlan(planSetCooldown(requireVault(), nodeId, cooldownSec));
+});
 server.tool("vault_pending_approval", "Look up a payment that is HELD awaiting the owner's approval. Returns null if there is no ticket for that id — already approved, already rejected, or never held.", { requestId: z.string().min(1) }, async ({ requestId }) => json((await viewFunction(cfg.rpcUrl, requireVault(), "get_pending_approval", {
     request_id: requestId,
 })) ?? null));
@@ -812,11 +1284,74 @@ server.tool("vault_plan_set_approval_threshold", 'Build an UNSIGNED payload requ
 }, async ({ nodeId, amount, decimals }) => renderPlan(planSetApprovalThreshold(requireVault(), nodeId, amount, decimals)));
 server.tool("vault_plan_approve_payment", "Build an UNSIGNED payload to APPROVE a held payment, which sends it. Every limit is re-checked at approval, so it can still be refused. Not signed by this server.", { requestId: z.string().min(1) }, async ({ requestId }) => renderPlan(planApprovePayment(requireVault(), requestId)));
 server.tool("vault_plan_reject_payment", "Build an UNSIGNED payload to REJECT a held payment. Nothing moves and the ticket is discarded. Not signed by this server.", { requestId: z.string().min(1) }, async ({ requestId }) => renderPlan(planRejectPayment(requireVault(), requestId)));
+/**
+ * THE TOOL THAT WAS MISSING, and the gap had teeth.
+ *
+ * `vault_config` reports `strict_allocation` and now explains, at length,
+ * that `overcommit` lets a sibling drain a shared pool and leave another
+ * agent refused `PARENT_DAILY_BUDGET` with its own cap apparently free. The
+ * payload builder `planSetStrictAllocation` has existed all along, and the
+ * DASHBOARD exposes it as an owner action — but no MCP tool did.
+ *
+ * So the server described a mode worth changing and offered no way to change
+ * it, through the one interface an agent can reach. Found by listing all 25
+ * tools against the payload builders rather than by anyone hitting it.
+ */
+server.tool("vault_plan_set_strict_allocation", "Build an UNSIGNED payload switching the vault between STRICT and OVERCOMMIT allocation. Strict refuses any change that would let children's caps sum above their parent's, so each child's budget is genuinely its own. Overcommit allows it, and then a sibling spending first can exhaust the shared pool — the others are refused PARENT_DAILY_BUDGET while their own cap still reads available. Read the current mode with vault_config. Not signed by this server.", {
+    strict: z
+        .boolean()
+        .describe("true = children may not be allocated more than their parent holds. false = they may, and siblings then compete for the pool."),
+}, async ({ strict }) => renderPlan(planSetStrictAllocation(requireVault(), strict)));
 server.tool("vault_plan_pause", "Build an UNSIGNED payload to pause or resume the whole vault. Pausing halts every agent payment. Not signed by this server.", { paused: z.boolean() }, async ({ paused }) => renderPlan(planSetPaused(requireVault(), paused)));
-server.tool("vault_plan_purge", "Build an UNSIGNED payload to delete settled payment records older than a UTC day. Spend totals are NOT refunded, but a deleted request id becomes reusable. Not signed by this server.", {
-    beforeDay: z.number().int().min(0),
-    limit: z.number().int().min(0).max(100).default(100),
-}, async ({ beforeDay, limit }) => renderPlan(planPurgeSettled(requireVault(), beforeDay, limit)));
+server.tool("vault_plan_purge", "Build an UNSIGNED payload deleting SETTLED payment records older than a cutoff, to reclaim the vault's storage stake. Spend totals are NOT refunded — purging frees bytes, it does not restore budget. Give `beforeDate` as YYYY-MM-DD; `beforeDay` (a Unix day number) is accepted for exactness. Not signed by this server.", {
+    /**
+     * A DATE, because the raw form asked a human for a Unix day number.
+     *
+     * `beforeDay: 20768` is what the contract indexes by and is unusable as an
+     * input: nobody knows today's number, and an off-by-one silently purges a
+     * day more or less than intended — of records that are then gone. The same
+     * figure was shown in `vault_budget` output and fixed there for the same
+     * reason; this is the input side of it.
+     *
+     * `beforeDay` survives for callers that genuinely have one, and because a
+     * test-clock vault's day is NOT derivable from the wall clock.
+     */
+    beforeDate: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/, "beforeDate must be YYYY-MM-DD")
+        .optional()
+        .describe("purge records from strictly BEFORE this UTC date, e.g. 2026-10-01"),
+    beforeDay: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe("the raw Unix day number, if you have it. Overrides beforeDate."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(1000)
+        .optional()
+        .describe("how many records at most, default 100. Large purges may exceed the gas limit."),
+}, async ({ beforeDate, beforeDay, limit }) => {
+    // EXACTLY ONE CUTOFF, and no default. A purge deletes records
+    // irreversibly; guessing "today" for a caller who forgot the argument
+    // would silently purge everything settled.
+    if (beforeDay === undefined && beforeDate === undefined) {
+        return text(`Give a cutoff: beforeDate "YYYY-MM-DD" (records strictly before it are removed), ` +
+            `or beforeDay if you have the raw number. There is deliberately no default — ` +
+            `a purge cannot be undone, and "today" would remove every settled record.`);
+    }
+    let day = beforeDay;
+    if (day === undefined) {
+        const ms = Date.parse(`${beforeDate}T00:00:00Z`);
+        if (Number.isNaN(ms))
+            return text(`"${beforeDate}" is not a real date.`);
+        day = Math.floor(ms / 86_400_000);
+    }
+    return renderPlan(planPurgeSettled(requireVault(), day, limit ?? 100));
+});
 server.tool("vault_plan_withdraw", "Build an UNSIGNED payload to move tokens OUT of the vault to any account. The owner approves it in their own wallet; this server never signs. This is the step that decides whether money survives a teardown: deleting a NEAR account does NOT return fungible tokens, so they must be moved first.", {
     amount: z
         .string()
@@ -835,6 +1370,11 @@ server.tool("vault_plan_withdraw", "Build an UNSIGNED payload to move tokens OUT
      * zero a delete needs.
      */
     let base;
+    // "Send 42 out of the vault" reads the same whether 42 is part of the
+    // balance or ALL of it, and those are different decisions: the second
+    // empties the vault, can fail in-flight payments, and is the step before a
+    // teardown. The signer sees a summary, not this code.
+    let emptying = false;
     if (amount === undefined) {
         const bal = await viewFunction(cfg.rpcUrl, tok, "ft_balance_of", {
             account_id: vault,
@@ -847,13 +1387,23 @@ server.tool("vault_plan_withdraw", "Build an UNSIGNED payload to move tokens OUT
             return text(`${vault} holds no ${tok}. Nothing to withdraw.`);
         }
         base = String(bal);
+        emptying = true;
     }
     else {
         // `toBaseUnits` returns a bigint; the payload carries base units as a
         // STRING, because that is what the contract's U128 arg expects.
         base = toBaseUnits(amount, cfg.decimals).toString();
     }
-    return renderPlan(planWithdraw(vault, tok, base, receiverId, cfg.decimals));
+    const plan = planWithdraw(vault, tok, base, receiverId, cfg.decimals);
+    if (emptying) {
+        plan.warnings = [
+            `This is the vault's ENTIRE ${tok} balance — it will hold zero afterwards. ` +
+                `You did not name an amount, so the figure above was read from the chain.`,
+            ...plan.warnings,
+        ];
+        plan.summary = `${plan.summary} (the ENTIRE balance)`;
+    }
+    return renderPlan(plan);
 });
 /**
  * WHY A QUOTE AND NOT A PLAN, which every other owner action here is.
@@ -1021,9 +1571,51 @@ server.tool("vault_teardown_report", "Read-only. Report exactly what closing thi
                 "0.08322 NEAR as tokens_burnt. Always withdrawFromGasKey first. teardown-vault.mjs " +
                 "does this and exits rather than continuing if it fails.",
         },
+        /**
+         * POINT AT THE USER-FACING CLI, not the repo's internal script.
+         *
+         * This emitted `NETWORK=… VAULT=… OWNER=… TOKEN=… CONFIRM_MAINNET=1
+         * EXPECT_TOKENS=1 node scripts/teardown-vault.mjs` — six environment
+         * variables, a path only someone who cloned the repo has, no dry run,
+         * and a delete at the end. For the one action a user takes when they are
+         * already nervous, that is the worst possible interface, and it is not
+         * what the product ships.
+         *
+         * `float-exit` is the published CLI for exactly this, and it is better
+         * in every way that matters here: two flags, `--dry-run`, numbered steps,
+         * "would" phrasing for everything it has not done yet, and an explicit
+         * "This is irreversible" before the delete. It works via npx, so it needs
+         * no checkout. `--network` defaults to mainnet.
+         *
+         * I pointed at the internal script for a week and then spent a round
+         * fixing ITS ergonomics — adding the missing CONFIRM_MAINNET and
+         * EXPECT_TOKENS — when the friendly path already existed. Fixing the
+         * hard road is not the same as checking whether the easy one is there.
+         *
+         * THE DRY RUN LEADS, deliberately. The destructive form is given second
+         * and separately, so copying the first thing you see cannot delete a
+         * vault.
+         *
+         * THE `-p` IS LOAD-BEARING. float-exit is a BIN of create-float, not a
+         * package of its own, so invoking it by bare scoped name 404s on the
+         * registry. `scripts/check-npx-commands.mjs` enforces this — and it
+         * flagged THIS comment when the wrong form was written out as a
+         * counter-example, which is the check working: it cannot tell a warning
+         * from an instruction, and neither can someone copying a line out of a
+         * file. So the bad form is described rather than spelled.
+         */
         command: signable
-            ? `NETWORK=${cfg.network} VAULT=${vault} OWNER=${config?.owner ?? "<owner>"} ` +
-                `TOKEN=${tok ?? "<token>"} node scripts/teardown-vault.mjs`
+            ? {
+                first_look: `npx -p @floatonnear/create-float float-exit --owner ${config?.owner ?? "<owner>"} ` +
+                    `--vault ${vault}${cfg.network === "mainnet" ? "" : ` --network ${cfg.network}`} --dry-run`,
+                then_for_real: `npx -p @floatonnear/create-float float-exit --owner ${config?.owner ?? "<owner>"} ` +
+                    `--vault ${vault}${cfg.network === "mainnet" ? "" : ` --network ${cfg.network}`}`,
+                what_the_dry_run_shows: "Every step it WOULD take, the exact NEAR and tokens coming back, and which " +
+                    "account they go to — without touching anything. Run it first.",
+                needs: `A full-access key for ${config?.owner ?? "the owner"} in ~/.near-credentials. ` +
+                    `The owner's key is already full-access ON the vault (the factory adds it at ` +
+                    `creation), so no separate vault key is needed.`,
+            }
             : "(none — nothing can sign as this vault)",
         note: "Read-only. This server holds at most a restricted agent key and signed nothing. " +
             "Run the command yourself, after the token withdrawal has settled.",