@floatonnear/mcp 0.6.5 → 0.9.1

package/dist/amounts.d.ts

@@ -52,4 +52,20 @@ export interface TreeNode {
 export declare function humaniseTreeNode(node: TreeNode, cfg: {
     token?: string;
     decimals: number;
+    /**
+     * Per-token metadata, when it could be read from the chain.
+     *
+     * THIS REMOVES THE CAVEAT THE FIRST VERSION SHIPPED WITH. It could only
+     * humanise the one token whose decimals the operator had configured;
+     * every other kept base units, because scaling by a guessed exponent
+     * prints a figure wrong by orders of magnitude while looking tidy. The
+     * chain knows the real answer, so the guess was never necessary.
+     *
+     * A token still absent from this map keeps base units — "could not read
+     * the metadata" is not a licence to assume six.
+     */
+    meta?: Map<string, {
+        symbol: string;
+        decimals: number;
+    } | null>;
 }): TreeNode;

package/dist/amounts.js

@@ -56,8 +56,15 @@ export function fromBaseUnits(units, decimals) {
 export function humaniseTreeNode(node, cfg) {
     if (!node || typeof node !== "object")
         return node;
-    const known = (token) => !!cfg.token && token === cfg.token;
-    const human = (v) => {
+    // Prefer what the CHAIN said; fall back to the configured token only.
+    const dp = (token) => {
+        const m = cfg.meta?.get(token);
+        if (m)
+            return m.decimals;
+        return cfg.token && token === cfg.token ? cfg.decimals : null;
+    };
+    const sym = (token) => cfg.meta?.get(token)?.symbol ?? null;
+    const human = (v, decimals) => {
         // EXPLICIT SHAPE CHECK, because `BigInt("")` is `0n` rather than a throw —
         // and `BigInt("  ")` is too. A try/catch alone therefore converted an
         // empty or whitespace cap into "0", which is not a parse failure the
@@ -66,7 +73,7 @@ export function humaniseTreeNode(node, cfg) {
         if (typeof v !== "string" || !/^\d+$/.test(v))
             return v;
         try {
-            return fromBaseUnits(BigInt(v), cfg.decimals);
+            return fromBaseUnits(BigInt(v), decimals);
         }
         catch {
             // Still guarded: fromBaseUnits rejects decimals outside its own range,
@@ -75,10 +82,26 @@ export function humaniseTreeNode(node, cfg) {
             return v;
         }
     };
-    const limits = node.limits?.map((l) => known(l.token)
-        ? { ...l, daily_cap: human(l.daily_cap), per_tx_cap: human(l.per_tx_cap), decimals: cfg.decimals }
-        : { ...l, decimals: null, units: "base" });
-    const childCapSum = node.child_cap_sum?.map(([token, amount]) => (known(token) ? [token, human(amount)] : [token, amount]));
+    const limits = node.limits?.map((l) => {
+        const d = dp(l.token);
+        const symbol = sym(l.token);
+        if (d === null)
+            return { ...l, decimals: null, units: "base" };
+        return {
+            ...l,
+            // The SYMBOL beside the id, never instead of it: anyone can deploy a
+            // token calling itself USDC, and a cap that names only a symbol cannot
+            // be checked against the one the user meant.
+            ...(symbol ? { token_symbol: symbol } : {}),
+            daily_cap: human(l.daily_cap, d),
+            per_tx_cap: human(l.per_tx_cap, d),
+            decimals: d,
+        };
+    });
+    const childCapSum = node.child_cap_sum?.map(([token, amount]) => {
+        const d = dp(token);
+        return (d === null ? [token, amount] : [token, human(amount, d)]);
+    });
     return {
         ...node,
         ...(limits ? { limits } : {}),

package/dist/explain.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Turn a payment outcome into something a person would actually say.
+ *
+ * WHY THE SERVER DOES THIS AND NOT THE MODEL. Two reasons, and the second is
+ * the one that decides it.
+ *
+ * First, the old instructions literally said "Report the reason code", so the
+ * agent did: a user asking to pay someone got `PARENT_PER_TX_LIMIT` back. That
+ * is a correct answer to a question nobody asked. Telling the model "be
+ * friendly" instead would help, but phrasing drifts between models, between
+ * versions, and between one conversation and the next.
+ *
+ * Second, and decisively: a USEFUL explanation needs NUMBERS the model does
+ * not have. "That's over the limit" is nearly as useless as the raw code. What
+ * a person needs is "the most you can send in one payment is 10, and this asked
+ * for 15 — try 10 or less". Those figures live in the budget tree, which the
+ * payment response never carried. So the server reads them and writes the
+ * sentence; the agent relays it.
+ *
+ * THE CODE IS KEPT, not discarded. Precision about WHICH rule fired is a real
+ * asset — `PARENT_DAILY_BUDGET` meaning "a sibling drained the shared pool" is
+ * something a flat policy model cannot express, and developers and the pitch
+ * both want it. So it stays in the payload under `technical`, out of the way
+ * of the sentence a user sees.
+ *
+ * HOUSE STYLE, since this is product copy:
+ *   - one or two short sentences, no jargon, no ALL-CAPS codes
+ *   - name the real numbers and the real token symbol
+ *   - say what to do next when there IS something to do
+ *   - never imply money moved when it did not, and never imply it is gone
+ *     when the refusal was free
+ */
+/** What the contract returned, plus whatever context the handler could gather. */
+export interface OutcomeContext {
+    status?: string;
+    reason_code?: string;
+    /** Human-units amount that was requested, e.g. "15". */
+    amount: string;
+    recipient: string;
+    /** Token symbol if known ("USDC"), else a short id. */
+    symbol: string;
+    /** Per-payment cap in human units, when known. */
+    perTxCap?: string | undefined;
+    /** Remaining budget today in human units, when known. */
+    available?: string | undefined;
+    /** Daily cap in human units, when known. */
+    dailyCap?: string | undefined;
+    /** Seconds left on a cooldown, when known. */
+    cooldownLeftSec?: number | undefined;
+}
+export interface Explanation {
+    /** The sentence(s) to say to the user. No codes, no jargon. */
+    say: string;
+    /** A concrete next step, or null when there is nothing for the user to do. */
+    next: string | null;
+    /** True when value actually moved. */
+    moved: boolean;
+}
+export declare function explainOutcome(c: OutcomeContext): Explanation;

package/dist/explain.js

@@ -0,0 +1,209 @@
+/**
+ * Turn a payment outcome into something a person would actually say.
+ *
+ * WHY THE SERVER DOES THIS AND NOT THE MODEL. Two reasons, and the second is
+ * the one that decides it.
+ *
+ * First, the old instructions literally said "Report the reason code", so the
+ * agent did: a user asking to pay someone got `PARENT_PER_TX_LIMIT` back. That
+ * is a correct answer to a question nobody asked. Telling the model "be
+ * friendly" instead would help, but phrasing drifts between models, between
+ * versions, and between one conversation and the next.
+ *
+ * Second, and decisively: a USEFUL explanation needs NUMBERS the model does
+ * not have. "That's over the limit" is nearly as useless as the raw code. What
+ * a person needs is "the most you can send in one payment is 10, and this asked
+ * for 15 — try 10 or less". Those figures live in the budget tree, which the
+ * payment response never carried. So the server reads them and writes the
+ * sentence; the agent relays it.
+ *
+ * THE CODE IS KEPT, not discarded. Precision about WHICH rule fired is a real
+ * asset — `PARENT_DAILY_BUDGET` meaning "a sibling drained the shared pool" is
+ * something a flat policy model cannot express, and developers and the pitch
+ * both want it. So it stays in the payload under `technical`, out of the way
+ * of the sentence a user sees.
+ *
+ * HOUSE STYLE, since this is product copy:
+ *   - one or two short sentences, no jargon, no ALL-CAPS codes
+ *   - name the real numbers and the real token symbol
+ *   - say what to do next when there IS something to do
+ *   - never imply money moved when it did not, and never imply it is gone
+ *     when the refusal was free
+ */
+const plural = (n, one, many) => (n === 1 ? one : many);
+/** "2 minutes", "3 hours" — a duration a person can act on. */
+function human(sec) {
+    if (sec < 60)
+        return `${sec} ${plural(sec, "second", "seconds")}`;
+    const m = Math.ceil(sec / 60);
+    if (m < 60)
+        return `${m} ${plural(m, "minute", "minutes")}`;
+    const h = Math.ceil(m / 60);
+    return `${h} ${plural(h, "hour", "hours")}`;
+}
+export function explainOutcome(c) {
+    const amt = `${c.amount} ${c.symbol}`;
+    const code = c.reason_code ?? "";
+    // ---- It worked. Say what happened, in that order: what, to whom, what is left.
+    if (c.status === "SETTLED" || code === "SETTLED") {
+        const left = c.available !== undefined
+            ? ` There's ${c.available} ${c.symbol} left to spend today.`
+            : "";
+        return { say: `Sent ${amt} to ${c.recipient}.${left}`, next: null, moved: true };
+    }
+    // ---- In flight. Do NOT claim it arrived.
+    if (c.status === "TRANSFER_PENDING" || code === "TRANSFER_PENDING") {
+        return {
+            say: `The ${amt} payment to ${c.recipient} is on its way — it hasn't confirmed yet.`,
+            next: "Check again in a moment to see whether it completed.",
+            moved: true,
+        };
+    }
+    /**
+     * ---- Approved by the rules, then the transfer itself failed.
+     *
+     * Said carefully: the budget was NOT charged, and people assume a failed
+     * payment means missing money. The usual cause is a payee not registered on
+     * the token, which is a real thing they can fix.
+     */
+    if (c.status === "TRANSFER_FAILED" || code === "TRANSFER_FAILED") {
+        return {
+            say: `The ${amt} payment to ${c.recipient} didn't go through, so nothing left the vault. ` +
+                `Usually that means ${c.recipient} isn't set up to receive ${c.symbol} yet.`,
+            next: `Ask ${c.recipient} to register for ${c.symbol}, then try again.`,
+            moved: false,
+        };
+    }
+    const nothingMoved = " Nothing was sent.";
+    switch (code) {
+        // ---- The two limit shapes, which are the ones users actually meet.
+        case "PER_TX_LIMIT":
+        case "PARENT_PER_TX_LIMIT": {
+            const cap = c.perTxCap;
+            const whose = code === "PARENT_PER_TX_LIMIT"
+                ? "a limit set higher up the budget"
+                : "this agent's limit";
+            return {
+                say: cap
+                    ? `That's too big for one payment — ${whose} caps each payment at ${cap} ${c.symbol}, ` +
+                        `and this asked for ${c.amount}.${nothingMoved}`
+                    : `That's more than ${whose} allows in a single payment.${nothingMoved}`,
+                next: cap
+                    ? `Send ${cap} ${c.symbol} or less, or ask the vault owner to raise the per-payment limit.`
+                    : "Try a smaller amount, or ask the vault owner to raise the per-payment limit.",
+                moved: false,
+            };
+        }
+        case "DAILY_BUDGET": {
+            const left = c.available;
+            return {
+                say: left
+                    ? `That would go past today's spending limit — ${left} ${c.symbol} is left of ` +
+                        `${c.dailyCap ?? "today's"} ${c.symbol}, and this asked for ${c.amount}.${nothingMoved}`
+                    : `Today's spending limit is used up.${nothingMoved}`,
+                next: left && Number(left) > 0
+                    ? `Send ${left} ${c.symbol} or less, or wait — the limit resets at midnight UTC.`
+                    : "The limit resets at midnight UTC, or the owner can raise it.",
+                moved: false,
+            };
+        }
+        /**
+         * The one worth explaining properly, because the obvious reading is wrong:
+         * this agent's OWN allowance can look completely free.
+         */
+        case "PARENT_DAILY_BUDGET":
+            return {
+                say: `This agent still has room, but the shared pool it spends from is used up for today — ` +
+                    `another agent got there first.${nothingMoved}`,
+                next: "The pool resets at midnight UTC, or the owner can raise the shared limit.",
+                moved: false,
+            };
+        case "COOLDOWN":
+        case "PARENT_COOLDOWN":
+            return {
+                say: `Payments from here are spaced out, and the next one isn't due yet` +
+                    `${c.cooldownLeftSec ? ` — about ${human(c.cooldownLeftSec)} to go` : ""}.${nothingMoved}`,
+                next: "Try again shortly.",
+                moved: false,
+            };
+        // ---- Owner decisions. The user cannot fix these themselves, so say who can.
+        case "NO_RECIPIENTS_SET":
+            return {
+                say: `This agent isn't cleared to pay anyone yet.${nothingMoved}`,
+                next: "The vault owner needs to approve a list of payees first.",
+                moved: false,
+            };
+        case "RECIPIENT_NOT_ALLOWED":
+            return {
+                say: `${c.recipient} isn't on this agent's approved list of payees.${nothingMoved}`,
+                next: "The vault owner decides who can be paid, and can add them.",
+                moved: false,
+            };
+        case "VAULT_PAUSED":
+            return {
+                say: `The vault is paused, so no payments can go out right now.${nothingMoved}`,
+                next: "The vault owner can unpause it.",
+                moved: false,
+            };
+        case "NODE_FROZEN":
+            return {
+                say: `This agent is frozen, so it can't spend.${nothingMoved}`,
+                next: "The vault owner can unfreeze it.",
+                moved: false,
+            };
+        case "TOKEN_NOT_ALLOWED":
+            return {
+                say: `This agent doesn't have a ${c.symbol} budget.${nothingMoved}`,
+                next: `The vault owner can give it one, or pay in a token it does have.`,
+                moved: false,
+            };
+        /**
+         * Not a refusal — a pause. Must not read as a failure, and must not read
+         * as done either.
+         */
+        case "APPROVAL_REQUIRED":
+            return {
+                say: `${amt} to ${c.recipient} is large enough to need the owner's sign-off, so it's ` +
+                    `waiting for them. Nothing has been sent yet.`,
+                next: "Ask the vault owner to approve it.",
+                moved: false,
+            };
+        case "APPROVAL_REJECTED":
+            return {
+                say: `The vault owner turned down the ${amt} payment to ${c.recipient}.${nothingMoved}`,
+                next: null,
+                moved: false,
+            };
+        case "DUPLICATE_REQUEST":
+            return {
+                say: "That exact payment was already submitted, so it wasn't sent twice.",
+                next: "Check whether the first one went through before trying again.",
+                moved: false,
+            };
+        case "INVALID_AMOUNT":
+            return { say: `${c.amount} isn't a valid amount to send.`, next: "Use an amount above zero.", moved: false };
+        case "INVALID_MEMO":
+            return {
+                say: "The note attached to that payment isn't allowed — it's too long or has odd characters.",
+                next: "Shorten the note and try again.",
+                moved: false,
+            };
+        default: {
+            /**
+             * UNKNOWN CODE: say plainly that it was refused and that nothing moved,
+             * and THEN give the code — because an unrecognised code is the one case
+             * where the raw value is genuinely the most useful thing a user can pass
+             * on to whoever can help. Guessing a friendly sentence for a rule we
+             * cannot describe would be worse than admitting it.
+             */
+            if (!code) {
+                return { say: `The ${amt} payment to ${c.recipient} didn't go through.${nothingMoved}`, next: null, moved: false };
+            }
+            return {
+                say: `The payment was refused by the vault's rules, so nothing was sent.`,
+                next: `If you need to report this, the reason given was "${code}".`,
+                moved: false,
+            };
+        }
+    }
+}

package/dist/server.js

@@ -54,12 +54,13 @@ import { topUpFor, paymentsAfterTopUp } from "./gas-math.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { fromBaseUnits, humaniseTreeNode, 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 { 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 ?? "",
     /**
@@ -193,9 +223,40 @@ const cfg = {
     // "configured" and unreachable.
     agentKeysPath: process.env.NEAR_VAULT_AGENT_KEYS ?? ".float/agent-keys.json",
 };
+/**
+ * NO VAULT IS THE COMMONEST STATE, SO THE MESSAGE HAS TO BE AN ONRAMP.
+ *
+ * This said "NEAR_VAULT_CONTRACT is not set" — true, and a dead end. Measured
+ * 2026-11-12: an agent asked to pay someone got that from `vault_config` and
+ * `vault_tree`, concluded the NEAR rail was unavailable, then searched three
+ * unrelated wallets for something that could reach a `.near` address, and
+ * finally asked the user to paste a contract id. It never suggested MAKING a
+ * vault, because nothing in the failure told it that was possible without one.
+ *
+ * The WORKFLOW preamble already said "No vault yet? vault_create" and that was
+ * not enough: at the moment of failure an agent reads the ERROR, not the
+ * instructions it was handed at startup. So the routing belongs here.
+ *
+ * It is the FIRST thing a new install hits, and the product's answer is
+ * genuinely good: `vault_create` needs no key, no existing vault and no
+ * configuration. An error that does not say so turns the normal first step
+ * into a support question.
+ *
+ * Names BOTH cases — "you have none" and "you have one this client does not
+ * know about" — because the fix differs completely and the message cannot tell
+ * which it is.
+ */
 function requireVault() {
-    if (!cfg.vault)
-        throw new Error("NEAR_VAULT_CONTRACT is not set");
+    if (!cfg.vault) {
+        throw new Error("No vault is configured, so there is nothing to read yet. " +
+            "If the user does not have a vault, call vault_create — it needs NO key, no existing " +
+            "vault and no configuration, and returns a link they approve in their own wallet. That " +
+            "is the normal first step, not an error. " +
+            "If they DO have one, set NEAR_VAULT_CONTRACT to its address and restart the client " +
+            "(servers are read once at startup); vault_create with an `owner` reports the address " +
+            "the factory derives for them. " +
+            "Do not go looking for another way to send money — no other rail can reach a NEAR vault.");
+    }
     return cfg.vault;
 }
 function tokenFor(t) {
@@ -280,19 +341,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.5" }, { instructions: INSTRUCTIONS });
+const server = new McpServer({ name: "float", version: "0.9.1" }, { instructions: INSTRUCTIONS });
 // ----------------------------------------------------------------- reads
 /**
  * Wait for a create to land, and prove the result belongs to the user.
@@ -388,6 +469,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,11 +531,63 @@ server.tool("vault_await_create", "After the user signs the create link, confirm
         ],
     });
 });
+/**
+ * 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", {}));
-    return json(Array.isArray(tree)
-        ? tree.map((n) => humaniseTreeNode(n, { token: cfg.token, decimals: cfg.decimals }))
-        : 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),
@@ -436,20 +599,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()
@@ -784,7 +1152,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.", {
@@ -794,15 +1232,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));
@@ -817,11 +1315,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()
@@ -840,6 +1401,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,
@@ -852,13 +1418,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.
@@ -1026,9 +1602,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.",

package/dist/token-meta.d.ts

@@ -0,0 +1,42 @@
+/**
+ * What a token is CALLED, and how many decimals it really has.
+ *
+ * WHY. Caps, balances and errors were all rendered with the raw NEP-141
+ * account id, and on mainnet USDC that is
+ * `17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1` — 64
+ * hex characters appearing in `vault_tree`, `vault_budget`, the teardown
+ * report and every "no limit for that token" message. Nobody reading a budget
+ * can tell that is USDC, and two different tokens look identical at a glance
+ * until you diff the strings.
+ *
+ * AND IT FIXES A REAL CORRECTNESS LIMIT, not just readability. `vault_tree`
+ * could only humanise the ONE token whose decimals the operator had
+ * configured; any other kept base units, because scaling by a guessed
+ * exponent prints a figure wrong by orders of magnitude while looking tidy.
+ * The chain knows the answer — `ft_metadata` returns it — so the guess was
+ * never necessary. Every token can now be rendered correctly.
+ *
+ * CACHED FOR THE PROCESS LIFETIME. Metadata is immutable in practice (a token
+ * that changed its decimals would break every holder), and a budget read
+ * should not make an extra round trip per node per token. A failed lookup is
+ * cached as `null` too: the common cause is an account that is not a token at
+ * all, and retrying that on every render turns one bad id into a storm.
+ */
+export interface TokenMeta {
+    symbol: string;
+    decimals: number;
+}
+type Fetcher = (rpcUrl: string, token: string) => Promise<unknown>;
+/** Visible for tests; a process-lifetime cache is otherwise untestable. */
+export declare function clearTokenMetaCache(): void;
+export declare function tokenMeta(rpcUrl: string, token: string, view: Fetcher): Promise<TokenMeta | null>;
+/**
+ * `USDC` where known, the raw id where not — never a symbol alone.
+ *
+ * The id stays because a symbol is NOT unique: anyone can deploy a token
+ * calling itself USDC, and a budget that names only the symbol cannot be
+ * checked against the one the user meant. This is money; the identifier has
+ * to remain visible.
+ */
+export declare function label(token: string, meta: TokenMeta | null): string;
+export {};

package/dist/token-meta.js

@@ -0,0 +1,46 @@
+const cache = new Map();
+/** Visible for tests; a process-lifetime cache is otherwise untestable. */
+export function clearTokenMetaCache() {
+    cache.clear();
+}
+export async function tokenMeta(rpcUrl, token, view) {
+    if (cache.has(token))
+        return cache.get(token) ?? null;
+    let meta = null;
+    try {
+        const raw = (await view(rpcUrl, token));
+        // BOTH FIELDS OR NEITHER. A partial answer is worse than none: a symbol
+        // without decimals invites rendering with the configured default, which
+        // is the wrong-exponent bug this exists to remove.
+        if (raw &&
+            typeof raw.symbol === "string" &&
+            raw.symbol.length > 0 &&
+            // REDUNDANT WITH THE NEXT LINE, kept for readability. Mutation-tested:
+            // removing this changes nothing because Number.isInteger(undefined) is
+            // already false, so `Number.isInteger` is the clause actually carrying
+            // the guard. Delete that one and the suite reds; delete this one and it
+            // does not.
+            typeof raw.decimals === "number" &&
+            Number.isInteger(raw.decimals) &&
+            raw.decimals >= 0 &&
+            raw.decimals <= 24) {
+            meta = { symbol: raw.symbol, decimals: raw.decimals };
+        }
+    }
+    catch {
+        meta = null;
+    }
+    cache.set(token, meta);
+    return meta;
+}
+/**
+ * `USDC` where known, the raw id where not — never a symbol alone.
+ *
+ * The id stays because a symbol is NOT unique: anyone can deploy a token
+ * calling itself USDC, and a budget that names only the symbol cannot be
+ * checked against the one the user meant. This is money; the identifier has
+ * to remain visible.
+ */
+export function label(token, meta) {
+    return meta ? `${meta.symbol} (${token})` : token;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floatonnear/mcp",
-  "version": "0.6.5",
+  "version": "0.9.1",
   "type": "module",
   "description": "MCP server for the hierarchical budget vault. The agent key signs request_payment only; owner methods emit unsigned payloads for wallet approval.",
   "license": "MIT",