@floatonnear/mcp 0.10.2 → 0.10.3

package/SKILL.md

@@ -30,8 +30,101 @@ the agent itself can change. Float gives it a **function-call key restricted to
 one method on one contract**, and puts the limits in a contract the key cannot
 reach.
 
-Read the next section before doing anything. It is the part that decides which
-of your requests can succeed.
+**Read the two sections below before doing anything.** The first decides how you
+speak to the person you are helping; the second decides which of your requests
+can succeed at all.
+
+## How you talk to the human (non-negotiable)
+
+**You are the product voice. The human is not debugging Float.** They asked for
+something to be paid, or set up, or limited. Everything below exists because
+the natural failure mode of a coding agent is to narrate the machine — rails,
+gas keys, reason codes, env vars — to someone who wanted one sentence.
+
+**Always:**
+
+- **2–4 short sentences** for a normal outcome. Not a report.
+- **Lead with the outcome**: paid / blocked / needs your approval / needs setup.
+- **Say whether money moved.** Yes or no, explicitly. It is the one fact a
+  person cannot infer and must never have to guess.
+- **One clear next step** when something is blocked — not a menu.
+- Everyday words: limit, budget, payment, wallet, *approve in your wallet*.
+
+**Never — unless they explicitly ask for technical detail, or are plainly a
+developer debugging:**
+
+- reason codes (`PARENT_PER_TX_LIMIT`, `COOLDOWN`, …)
+- tool names (`vault_pay`, `vault_add_role`, `vault_plan_set_caps`)
+- env vars, key files, keyrings, RPC urls, gas keys, nonces, wasm, yoctoNEAR,
+  base units, node ids
+- a setup essay in the middle of a task
+- several options when one sensible default exists
+
+### Use the tool's own words
+
+Tools return the user-facing sentence already built, with the real numbers in
+it:
+
+```json
+{
+  "say": "Sent 0.25 USDC to test015.near. Money moved.",
+  "next_step": null,
+  "money_moved": true,
+  "technical": { "status": "SETTLED", "reason_code": null }
+}
+```
+
+**Relay `say`. Add `next_step` if it is not null. Stop.** Do not re-derive a
+more technical story out of `technical` — those fields are for you, and for the
+moment someone asks *why*.
+
+`say` is built where the numbers live, which is why it can name the cap that
+bound and what is left today. A sentence you compose from `status` and
+`reason_code` alone cannot, because the payment response never carried them.
+
+### Templates
+
+**Paid:**
+
+> Sent **0.25 USDC** to test015.near. Money moved. About **24.75 USDC** left in
+> today's budget.
+
+**Blocked, over a limit:**
+
+> That payment was **too big** — the most this budget allows per payment is
+> **10 USDC**, and this asked for 15. **Nothing was sent.** Try 10 USDC or
+> less, or raise the limit (I'll give you something to approve in your wallet).
+
+**Needs a human signature:**
+
+> I can't change limits myself — only you can. Here's the change to **approve
+> in your wallet**. Tell me once you have and I'll confirm it's live.
+
+**No vault yet:**
+
+> You don't have a vault yet. Setting one up is **one approval in your wallet**
+> and about **3.7 NEAR** — almost all of it a refundable deposit your vault
+> holds, not a fee. Want me to start?
+
+**Not enough money:**
+
+> The vault doesn't have enough USDC for that. **Nothing was sent.** Add USDC to
+> the vault and ask me again.
+
+### Worked examples, before and after
+
+| situation | ❌ what not to say | ✅ what to say |
+| --- | --- | --- |
+| settled | `status: SETTLED, node_id: 1` | Sent 0.25 USDC to test015.near. Money moved. 24.75 USDC left today. |
+| over cap | "BLOCKED with reason_code PARENT_PER_TX_LIMIT" | That's too big for one payment — the limit is 10 USDC and this asked for 15. Nothing was sent. |
+| policy change | "Returns an unsigned payload; the server does not sign. Run `near contract call-function`…" | I can't change the limit myself — approve this in your wallet and it's done. |
+| new agent | "Generated an ed25519 keypair, wrote it to the keyring; the 0.12 NEAR deposit funds a NEP-611 gas key" | I'll set up a news budget: 1 USDC a day, 0.10 max per payment. Approve once in your wallet and I can pay within those limits. |
+| no vault | "`NEAR_VAULT_CONTRACT` is not set" | You don't have a vault yet — want me to set one up? |
+
+A person who asked to pay a vendor and got `PARENT_PER_TX_LIMIT` has been told
+nothing they can act on. The codes are precise, and that precision is a real
+asset for debugging and for explaining the design. It is just never the first
+thing a person wants.
 
 ## Setup — do this first if you arrived here cold
 
@@ -307,10 +400,13 @@ A refusal comes back as a **value**, not an error. `status: "BLOCKED"` with a
 
 ### Never show a reason code to the user
 
-`vault_pay` already returns a plain-English `say`, a `next_step`, and a
-`money_moved` flag. **Relay `say`, add `next_step` if there is one, and stop.**
-The `reason_code` lives under `technical`; quote it only if the user asks why,
-asks for detail, or is plainly a developer.
+This is governed by **How you talk to the human** near the top of this file —
+one source of truth, so the two cannot drift apart. The short form:
+
+**`vault_pay` returns `say`, `next_step` and `money_moved`. Relay `say`, add
+`next_step` if it is not null, and stop.** The `reason_code` lives under
+`technical`; quote it only if the user asks why, asks for detail, or is plainly
+a developer.
 
 > Say: *"That's 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
@@ -318,13 +414,9 @@ asks for detail, or is plainly a developer.
 >
 > Not: *"The payment was BLOCKED with reason_code PARENT_PER_TX_LIMIT."*
 
-The same applies when it works: *"Sent 0.25 USDC to alice.near. There's 24.75
-USDC left to spend today."* — not `status: SETTLED`.
-
-Someone who asked to pay a vendor and got `PARENT_PER_TX_LIMIT` has been told
-nothing they can act on. The codes are precise and that precision is a real
-asset for debugging and for explaining the design — it is just not what a
-person wants first.
+**A refusal is still an answer, not a failure.** Report it as the budget doing
+its job. And never imply money moved when `money_moved` is false — a blocked
+payment moved nothing, which is the whole point.
 
 ### The codes themselves
 

package/dist/explain.d.ts

@@ -57,3 +57,36 @@ export interface Explanation {
     moved: boolean;
 }
 export declare function explainOutcome(c: OutcomeContext): Explanation;
+/**
+ * The user-facing sentence for an UNSIGNED owner payload.
+ *
+ * WHY PLAN TOOLS NEEDED THIS TOO. `vault_pay` returned `say`/`next_step`/
+ * `money_moved` and the plan tools returned `{action, summary, warnings,
+ * unsigned_payload, approve_with}` — five technical keys and no sentence. So
+ * agents narrated the mechanism: "returns an unsigned payload; the server does
+ * not sign; run `near contract call-function`…". All true, and unusable by the
+ * person who asked to raise a limit.
+ *
+ * THE THREE THINGS A PERSON NEEDS HERE, in order:
+ *   1. this needs YOU — the agent cannot do it
+ *   2. what it will do, in the units they named
+ *   3. nothing has happened yet
+ *
+ * (3) matters most and is the easiest to leave out. An unsigned payload is a
+ * *proposal*; an agent that says "I've raised the limit" has lied about state
+ * the user is about to be asked to change themselves.
+ *
+ * `summary` is reused verbatim rather than rewritten. It is built where the
+ * amounts and tokens are known, in the units the caller passed, and
+ * duplicating that formatting here is how the two drift into disagreeing about
+ * a number. It does still say "node 1" — the honest fix for that is better
+ * summaries in `payloads.ts`, not a second renderer guessing at them here.
+ */
+export declare function planVoice(p: {
+    summary: string;
+    depositYocto?: string;
+    warnings?: string[];
+}): {
+    say: string;
+    next: string;
+};

package/dist/explain.js

@@ -207,3 +207,58 @@ export function explainOutcome(c) {
         }
     }
 }
+/**
+ * The user-facing sentence for an UNSIGNED owner payload.
+ *
+ * WHY PLAN TOOLS NEEDED THIS TOO. `vault_pay` returned `say`/`next_step`/
+ * `money_moved` and the plan tools returned `{action, summary, warnings,
+ * unsigned_payload, approve_with}` — five technical keys and no sentence. So
+ * agents narrated the mechanism: "returns an unsigned payload; the server does
+ * not sign; run `near contract call-function`…". All true, and unusable by the
+ * person who asked to raise a limit.
+ *
+ * THE THREE THINGS A PERSON NEEDS HERE, in order:
+ *   1. this needs YOU — the agent cannot do it
+ *   2. what it will do, in the units they named
+ *   3. nothing has happened yet
+ *
+ * (3) matters most and is the easiest to leave out. An unsigned payload is a
+ * *proposal*; an agent that says "I've raised the limit" has lied about state
+ * the user is about to be asked to change themselves.
+ *
+ * `summary` is reused verbatim rather than rewritten. It is built where the
+ * amounts and tokens are known, in the units the caller passed, and
+ * duplicating that formatting here is how the two drift into disagreeing about
+ * a number. It does still say "node 1" — the honest fix for that is better
+ * summaries in `payloads.ts`, not a second renderer guessing at them here.
+ */
+export function planVoice(p) {
+    const bits = [];
+    // (1) and (2) together, because "needs you" is meaningless without "to do
+    // what". Leading with the actor is what stops the agent claiming the credit.
+    bits.push(`This one needs you — I can't make this change myself. ${p.summary}.`);
+    /**
+     * A DEPOSIT IS STATED, ALWAYS, WHEN THERE IS ONE.
+     *
+     * 1 yoctoNEAR is the NEP-141 anti-phishing deposit — a rounding error that
+     * no person should ever be told about. Anything larger is real money leaving
+     * their wallet, and a wallet prompt showing an unexplained NEAR figure is
+     * the fastest way to make a safe action look like a scam.
+     */
+    const dep = BigInt(p.depositYocto ?? "0");
+    if (dep > 1n) {
+        const near = (Number(dep) / 1e24).toFixed(3).replace(/\.?0+$/, "");
+        bits.push(`It sends ${near} NEAR with it, which the vault keeps — not a fee.`);
+    }
+    // (3). Said last so it is the thing left ringing.
+    bits.push("Nothing has changed yet.");
+    // `warnings` is non-empty only for destructive or hard-to-undo actions, so
+    // when one exists it outranks brevity.
+    const firstWarning = (p.warnings ?? []).find((w) => typeof w === "string" && !!w.trim());
+    if (firstWarning)
+        bits.push(firstWarning);
+    return {
+        say: bits.join(" "),
+        next: "Approve it in your wallet, then tell me and I'll confirm it went through.",
+    };
+}

package/dist/payloads.d.ts

@@ -43,9 +43,11 @@ export interface OwnerPayload {
     /** Non-empty only when the action is destructive or hard to undo. */
     warnings: string[];
 }
-export declare function planAddNode(vault: string, parent: number | null, label: string, limits: HumanTokenLimit[], cooldownSec: number, recipients: string[] | null): OwnerPayload;
-export declare function planSetNodeCaps(vault: string, nodeId: number, limits: HumanTokenLimit[]): OwnerPayload;
-export declare function planBindAgent(vault: string, nodeId: number, accountId: string): OwnerPayload;
+export declare function planAddNode(vault: string, parent: number | null, label: string, limits: HumanTokenLimit[], cooldownSec: number, recipients: string[] | null, 
+/** The PARENT's human label, so the summary can say "under news". */
+parentName?: string | null): OwnerPayload;
+export declare function planSetNodeCaps(vault: string, nodeId: number, limits: HumanTokenLimit[], nodeName?: string | null): OwnerPayload;
+export declare function planBindAgent(vault: string, nodeId: number, accountId: string, nodeName?: string | null): OwnerPayload;
 /**
  * A whole departmental agent in ONE owner signature: node, binding, gas key.
  *
@@ -69,7 +71,7 @@ export declare function planBindAgent(vault: string, nodeId: number, accountId:
  * and the vault carries the owner's full-access key.
  */
 export declare function planAddRole(vault: string, label: string, limits: HumanTokenLimit[], cooldownSec: number, recipients: string[] | null, publicKey: string, fundingYocto: string): OwnerPayload;
-export declare function planBindVirtualAgent(vault: string, nodeId: number, publicKey: string): OwnerPayload;
+export declare function planBindVirtualAgent(vault: string, nodeId: number, publicKey: string, nodeName?: string | null): OwnerPayload;
 /**
  * Revoke a virtual agent's authority.
  *
@@ -80,9 +82,9 @@ export declare function planBindVirtualAgent(vault: string, nodeId: number, publ
  * half the binding's storage is intentionally unrecoverable.
  */
 export declare function planUnbindVirtualAgent(vault: string, publicKey: string): OwnerPayload;
-export declare function planSetRecipients(vault: string, nodeId: number, recipients: string[] | null): OwnerPayload;
-export declare function planSetCooldown(vault: string, nodeId: number, cooldownSec: number): OwnerPayload;
-export declare function planFreezeNode(vault: string, nodeId: number, frozen: boolean): OwnerPayload;
+export declare function planSetRecipients(vault: string, nodeId: number, recipients: string[] | null, nodeName?: string | null): OwnerPayload;
+export declare function planSetCooldown(vault: string, nodeId: number, cooldownSec: number, nodeName?: string | null): OwnerPayload;
+export declare function planFreezeNode(vault: string, nodeId: number, frozen: boolean, nodeName?: string | null): OwnerPayload;
 export declare function planSetPaused(vault: string, paused: boolean): OwnerPayload;
 export declare function planSetStrictAllocation(vault: string, strict: boolean): OwnerPayload;
 export declare function planPurgeSettled(vault: string, beforeDay: number, limit: number): OwnerPayload;
@@ -195,7 +197,7 @@ export declare function toCliCommand(p: OwnerPayload, network?: string): string;
  * `toBaseUnits` throws rather than truncating excess precision — correct here:
  * silently rounding 0.1234567 would set a threshold the owner did not choose.
  */
-export declare function planSetApprovalThreshold(vault: string, nodeId: number, amount: string | null, decimals: number): OwnerPayload;
+export declare function planSetApprovalThreshold(vault: string, nodeId: number, amount: string | null, decimals: number, nodeName?: string | null): OwnerPayload;
 /**
  * Execute a held payment.
  *

package/dist/payloads.js

@@ -105,7 +105,9 @@ function assertCooldown(cooldownSec) {
         throw new Error(`cooldown must be at most ${MAX_COOLDOWN_SEC}s (MAX_COOLDOWN_SEC)`);
     }
 }
-export function planAddNode(vault, parent, label, limits, cooldownSec, recipients) {
+export function planAddNode(vault, parent, label, limits, cooldownSec, recipients, 
+/** The PARENT's human label, so the summary can say "under news". */
+parentName) {
     if (!label || label.length > MAX_LABEL_LEN) {
         throw new Error(`label must be 1..=${MAX_LABEL_LEN} characters (MAX_LABEL_LEN)`);
     }
@@ -123,35 +125,99 @@ export function planAddNode(vault, parent, label, limits, cooldownSec, recipient
         },
         gasTgas: DEFAULT_GAS_TGAS,
         depositYocto: ONE_YOCTO,
-        summary: `Create budget node "${label}" ${parent === null ? "as the ROOT" : `under node ${parent}`}` +
+        summary: 
+        // "the main budget" for a root, and the PARENT's name otherwise — a new
+        // child is described by where it hangs, which is the one thing the
+        // person choosing it cares about.
+        `Create a "${label}" budget ` +
+            `${parent === null ? "as the main budget" : `under ${budgetName(parent, parentName)}`}` +
             ` with ${describeLimits(limits)}` +
             (cooldownSec ? `, ${cooldownSec}s cooldown between payments` : "") +
             (recipients ? `, paying only: ${recipients.join(", ")}` : `, inheriting the payee allowlist`),
         warnings: [],
     };
 }
-export function planSetNodeCaps(vault, nodeId, limits) {
+/**
+ * How a budget is NAMED to a person.
+ *
+ * WHY THIS EXISTS. Every plan summary said "node 1", and `planVoice` copies
+ * the summary verbatim into the `say` a user reads — so the product spoke the
+ * tree's internal vocabulary: "Set node 1 caps to 1/day", "Freeze node 0".
+ * A node id is the contract's primary key. It is exactly right in `args`, in
+ * `technical`, and in the unsigned payload a wallet signs, and it is a
+ * stranger's filing reference to the person who called the thing "news".
+ *
+ * The label is NOT derivable here — it lives on chain, and this module is pure
+ * and synchronously testable, which is worth keeping. So the caller resolves
+ * it and passes it in; `server.ts` already fetches the tree to check the node
+ * exists, so this costs no extra call.
+ *
+ * FALLBACKS, in order of how much they can honestly claim:
+ *   a label        -> `the "news" budget`
+ *   node 0, no label -> "the main budget"   (root is the only id with a meaning)
+ *   anything else  -> "this budget"         (true, and says nothing false)
+ *
+ * "this budget" is deliberately vague rather than wrong. The alternative was
+ * falling back to the id, which is the bug.
+ */
+/**
+ * Sentence-case a budget name for the start of a summary.
+ *
+ * `budgetName` returns a lowercase noun phrase because most of its uses sit
+ * mid-sentence ("Freeze the main budget"). A few lead the sentence, and
+ * "the main budget must wait 30s" reads like a fragment.
+ */
+function capitalise(s) {
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}
+function budgetName(nodeId, label) {
+    /**
+     * ROOT IS ALWAYS "the main budget", whatever its stored label.
+     *
+     * The contract hardcodes root's label to the literal string "root"
+     * (`lib.rs`: `label: "root".to_string()`), which is the tree's word, not a
+     * person's. `the "root" budget` would just be "node 0" wearing a hat.
+     */
+    if (nodeId === 0)
+        return "the main budget";
+    const clean = typeof label === "string" ? label.trim() : "";
+    if (clean)
+        return `the "${clean}" budget`;
+    /**
+     * NO LABEL means the tree read FAILED — `Node.label` is a required `String`
+     * on chain (`types.rs`), so every real node has one. "this budget" is
+     * deliberately vague rather than wrong; the alternative was falling back to
+     * the id, which is the thing being removed.
+     *
+     * It does cost distinguishability in that degraded case: two different
+     * budgets read the same. The node id is still in `args.node_id`, which is
+     * what the WALLET displays and what the owner actually signs, so the
+     * signature is never ambiguous even when the sentence is. Pinned by a test.
+     */
+    return "this budget";
+}
+export function planSetNodeCaps(vault, nodeId, limits, nodeName) {
     return {
         receiverId: vault,
         methodName: "set_node_caps",
         args: { node_id: nodeId, limits: limitsToArgs(limits) },
         gasTgas: DEFAULT_GAS_TGAS,
         depositYocto: ONE_YOCTO,
-        summary: `Set node ${nodeId} caps to ${describeLimits(limits)}`,
+        summary: `Update ${budgetName(nodeId, nodeName)} to ${describeLimits(limits)}`,
         warnings: [],
     };
 }
-export function planBindAgent(vault, nodeId, accountId) {
+export function planBindAgent(vault, nodeId, accountId, nodeName) {
     return {
         receiverId: vault,
         methodName: "bind_agent",
         args: { node_id: nodeId, account_id: accountId },
         gasTgas: DEFAULT_GAS_TGAS,
         depositYocto: ONE_YOCTO,
-        summary: `Let ${accountId} spend from node ${nodeId}`,
+        summary: `Let ${accountId} spend from ${budgetName(nodeId, nodeName)}`,
         warnings: [
             `${accountId} is an EXISTING account whose keys you do not control. ` +
-                `It can call request_payment with the full authority of node ${nodeId}.`,
+                `It can spend with the full authority of ${budgetName(nodeId, nodeName)}.`,
             `Prefer a VIRTUAL agent (bind_virtual_agent): it binds one key you generate ` +
                 `rather than a whole account, costs ~168 bytes, and strands nothing.`,
         ],
@@ -218,7 +284,7 @@ export function planAddRole(vault, label, limits, cooldownSec, recipients, publi
         ],
     };
 }
-export function planBindVirtualAgent(vault, nodeId, publicKey) {
+export function planBindVirtualAgent(vault, nodeId, publicKey, nodeName) {
     assertNodeId(nodeId);
     assertPublicKey(publicKey);
     return {
@@ -230,7 +296,7 @@ export function planBindVirtualAgent(vault, nodeId, publicKey) {
         // `assert_owner()` -> `assert_one_yocto()`. Nothing is funded here, which
         // is the whole point of moving off sub-accounts.
         depositYocto: ONE_YOCTO,
-        summary: `Let the key ${publicKey.slice(0, 22)}… spend from node ${nodeId}`,
+        summary: `Let a new agent key spend from ${budgetName(nodeId, nodeName)}`,
         warnings: [
             `A node may hold more than one key — binding another does not replace this one.`,
             `This grants spending authority only. The key still needs gas: install it as ` +
@@ -265,7 +331,7 @@ export function planUnbindVirtualAgent(vault, publicKey) {
         ],
     };
 }
-export function planSetRecipients(vault, nodeId, recipients) {
+export function planSetRecipients(vault, nodeId, recipients, nodeName) {
     assertRecipients(recipients);
     return {
         receiverId: vault,
@@ -274,17 +340,18 @@ export function planSetRecipients(vault, nodeId, recipients) {
         gasTgas: DEFAULT_GAS_TGAS,
         depositYocto: ONE_YOCTO,
         summary: recipients
-            ? `Node ${nodeId} may pay only: ${recipients.join(", ")}`
-            : `Node ${nodeId} inherits its payee allowlist from the nearest ancestor that sets one`,
+            ? `${capitalise(budgetName(nodeId, nodeName))} may pay only: ${recipients.join(", ")}`
+            : `${capitalise(budgetName(nodeId, nodeName))} takes its list of allowed payees from the budget above it`,
         warnings: recipients
             ? [
-                `This REPLACES the inherited allowlist for node ${nodeId} and its descendants; ` +
-                    `it does not add to it. Payees it currently inherits will stop being payable.`,
+                `This REPLACES the inherited payee list for ${budgetName(nodeId, nodeName)} and ` +
+                    `everything under it; it does not add to it. Payees it currently inherits will ` +
+                    `stop being payable.`,
             ]
             : [],
     };
 }
-export function planSetCooldown(vault, nodeId, cooldownSec) {
+export function planSetCooldown(vault, nodeId, cooldownSec, nodeName) {
     assertCooldown(cooldownSec);
     return {
         receiverId: vault,
@@ -293,21 +360,23 @@ export function planSetCooldown(vault, nodeId, cooldownSec) {
         gasTgas: DEFAULT_GAS_TGAS,
         depositYocto: ONE_YOCTO,
         summary: cooldownSec
-            ? `Node ${nodeId} must wait ${cooldownSec}s between payments`
-            : `Remove the cooldown on node ${nodeId}`,
+            ? `${capitalise(budgetName(nodeId, nodeName))} must wait ${cooldownSec}s between payments`
+            : `Remove the waiting time between payments on ${budgetName(nodeId, nodeName)}`,
         warnings: [],
     };
 }
-export function planFreezeNode(vault, nodeId, frozen) {
+export function planFreezeNode(vault, nodeId, frozen, nodeName) {
     return {
         receiverId: vault,
         methodName: "freeze_node",
         args: { node_id: nodeId, frozen },
         gasTgas: DEFAULT_GAS_TGAS,
         depositYocto: ONE_YOCTO,
-        summary: frozen ? `Freeze node ${nodeId}` : `Unfreeze node ${nodeId}`,
+        summary: frozen
+            ? `Freeze ${budgetName(nodeId, nodeName)} so nothing under it can pay until you unfreeze it`
+            : `Unfreeze ${budgetName(nodeId, nodeName)} so it can pay again`,
         warnings: frozen
-            ? [`This blocks payments from node ${nodeId} AND every node in its subtree.`]
+            ? [`This stops payments from ${budgetName(nodeId, nodeName)} and every budget under it.`]
             : [],
     };
 }
@@ -466,7 +535,7 @@ export function toCliCommand(p, network = "testnet") {
  * `toBaseUnits` throws rather than truncating excess precision — correct here:
  * silently rounding 0.1234567 would set a threshold the owner did not choose.
  */
-export function planSetApprovalThreshold(vault, nodeId, amount, decimals) {
+export function planSetApprovalThreshold(vault, nodeId, amount, decimals, nodeName) {
     const base = amount === null ? null : toBaseUnits(amount, decimals).toString();
     return {
         receiverId: vault,
@@ -478,8 +547,8 @@ export function planSetApprovalThreshold(vault, nodeId, amount, decimals) {
         // 1000000 (base units)", which is unreadable in precisely the moment the
         // owner is checking the plan before signing it.
         summary: amount
-            ? `Payments above ${amount} from node ${nodeId} will need your approval`
-            : `Remove the approval threshold on node ${nodeId} — payments up to the caps run unattended`,
+            ? `Payments above ${amount} from ${budgetName(nodeId, nodeName)} will need your approval`
+            : `Stop requiring your approval on ${budgetName(nodeId, nodeName)} — payments inside the limits run unattended`,
         warnings: amount
             ? []
             : ["After this, nothing at this node waits for a human: only the caps apply."],

package/dist/server.js

@@ -63,7 +63,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { listAgents, listUnloadable, selectRole } from "./roles.js";
 import { resolveKeyringPath } from "./keyring-path.js";
-import { label as tokenLabel, tokenMeta } from "./token-meta.js";
+import { displaySymbol, label as tokenLabel, tokenMeta } from "./token-meta.js";
 /**
  * A decimal NEAR string to yoctoNEAR, without floating point.
  *
@@ -78,7 +78,7 @@ function toYoctoNear(n) {
 }
 import { buildCreatePlan, FACTORY_BY_NETWORK } from "./create.js";
 import { buildRoute, sendRequestPayment } from "./sign.js";
-import { explainOutcome } from "./explain.js";
+import { explainOutcome, planVoice } 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. */
@@ -296,12 +296,65 @@ function tokenFor(t) {
 }
 const text = (s) => ({ content: [{ type: "text", text: s }] });
 const json = (v) => text(JSON.stringify(v, null, 2));
-/** Payload + summary + warnings + a runnable command, so approving needs no trust in this server. */
-function renderPlan(p) {
+/**
+ * Payload + summary + warnings + a runnable command, so approving needs no
+ * trust in this server — fronted by the plain-English fields.
+ *
+ * THE UX FIELDS COME FIRST, AND THEY ARE THE SAME THREE `vault_pay` RETURNS.
+ * This used to return five technical keys and no sentence, so agents described
+ * the mechanism — "returns an unsigned payload; the server does not sign; run
+ * `near contract call-function`…" — to someone who had asked to raise a limit.
+ * One shape across every tool means the instruction can be one sentence:
+ * relay `say`, add `next_step`, stop.
+ *
+ * `money_moved` is ALWAYS false here, and that is not a technicality worth
+ * hiding: a plan is a proposal. Nothing has moved, nothing has changed, and an
+ * agent that reports otherwise has lied about state the user is about to be
+ * asked to change themselves.
+ *
+ * `unsigned_payload` stays TOP-LEVEL rather than moving under `technical`:
+ * `scripts/check-mcp-live.mjs` asserts on it against the real server, and
+ * quietly renaming the key it reads would turn a live check green-by-absence.
+ */
+async function renderPlan(p) {
+    const voice = planVoice(p);
+    /**
+     * SWAP TOKEN IDS FOR SYMBOLS IN THE SENTENCE ONLY.
+     *
+     * `summary` is built in `payloads.ts`, which is pure and has no network — so
+     * it prints the token's ACCOUNT ID. For mainnet USDC that is 64 hex
+     * characters, and `planVoice` reuses the summary verbatim, so the sentence
+     * read: 'Create budget node "research" as the ROOT with
+     * 17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1: 5/day'.
+     *
+     * Resolving here rather than in `payloads.ts` keeps that module pure and
+     * synchronously testable, which is worth more than saving this substitution.
+     * `technical.summary` is left EXACT — the id is the useful form there.
+     *
+     * Only the `say` is rewritten, and only for ids actually present, so a
+     * payload with no tokens costs nothing.
+     */
+    let say = voice.say;
+    const ids = [
+        ...new Set((Array.isArray(p.args.limits) ? p.args.limits : [])
+            .map((l) => l?.token)
+            .filter((t) => typeof t === "string" && say.includes(t))),
+    ];
+    if (ids.length > 0) {
+        const metas = await metaFor(ids);
+        for (const id of ids) {
+            const sym = metas.get(id)?.symbol;
+            // Substituted ONLY when a symbol actually resolved. Falling back to
+            // "tokens" here would erase which token a limit applies to, and a
+            // multi-token payload would become ambiguous.
+            if (sym)
+                say = say.split(id).join(sym);
+        }
+    }
     return json({
-        action: p.methodName,
-        summary: p.summary,
-        warnings: p.warnings,
+        say,
+        next_step: voice.next,
+        money_moved: false,
         unsigned_payload: {
             receiver_id: p.receiverId,
             method_name: p.methodName,
@@ -309,6 +362,11 @@ function renderPlan(p) {
             gas_tgas: p.gasTgas,
             deposit_yocto: p.depositYocto,
         },
+        technical: {
+            action: p.methodName,
+            summary: p.summary,
+            warnings: p.warnings,
+        },
         approve_with: toCliCommand(p, cfg.network),
         note: "This server did NOT sign this. Review the summary, then run the command " +
             "or approve the payload in your wallet.",
@@ -408,7 +466,7 @@ WORTH KNOWING
   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.10.2" }, { instructions: INSTRUCTIONS });
+const server = new McpServer({ name: "float", version: "0.10.3" }, { instructions: INSTRUCTIONS });
 /**
  * THE FULL OPERATING GUIDE, AS AN MCP RESOURCE.
  *
@@ -606,6 +664,11 @@ server.tool("vault_await_create", "After the user signs the create link, confirm
     }
     if (config.owner !== owner) {
         return json({
+            say: `That vault address already belongs to someone else, so it is not yours to use. ` +
+                `Nothing was changed. I can set one up for you under a different name instead — ` +
+                `want me to?`,
+            next_step: `Say the word and I'll create a vault under a label, on a different address.`,
+            money_moved: false,
             status: "NOT_YOURS",
             vault: target,
             actualOwner: config.owner,
@@ -699,7 +762,26 @@ server.tool("vault_await_create", "After the user signs the create link, confirm
     else {
         nextSteps.push(`vault_tree shows the budget shape; vault_budget shows what is left today.`);
     }
+    /**
+     * "LIVE" PLUS A CONFIG DUMP IS NOT AN ANSWER TO "did it work?".
+     *
+     * `funding` and `nextSteps` already hold everything a person needs; what
+     * was missing was the one sentence that orders them. The empty-vault case
+     * is the one that matters: a vault that exists but holds nothing cannot
+     * pay, and "LIVE" on its own reads as done.
+     */
+    const liveSay = empty
+        ? `Your vault is set up and ready. It has no money in it yet, so add funds to it and ` +
+            `then I can start paying from it.`
+        : agentKeys === 0
+            ? `Your vault is set up and funded. One thing left: it needs an agent budget before ` +
+                `anything can be paid from it.`
+            : `Your vault is live, funded, and has an agent that can pay within its limits. ` +
+                `Nothing else to do.`;
     return json({
+        say: liveSay,
+        next_step: nextSteps[0] ?? null,
+        money_moved: false,
         status: "LIVE",
         vault: target,
         owner: config.owner,
@@ -796,7 +878,33 @@ server.tool("vault_budget", "Read one node's budget for a UTC day: cap, executed
     const tok = tokenFor(token);
     const meta = (await metaFor([tok])).get(tok) ?? null;
     const d = meta?.decimals ?? cfg.decimals;
+    // The SYMBOL for the sentence; the full `SYMBOL (id)` label stays on the
+    // `token` field below, where the id is useful rather than alarming.
+    const sym = displaySymbol(meta);
+    const cap = fromBaseUnits(BigInt(b.daily_cap), d);
+    const used = fromBaseUnits(BigInt(b.executed), d);
+    const left = fromBaseUnits(BigInt(b.available), d);
+    const inFlight = fromBaseUnits(BigInt(b.pending), d);
+    /**
+     * A BUDGET READ IS THE COMMONEST QUESTION A PERSON ASKS, and it was
+     * answered with eight fields and no sentence — including `day: 20768`.
+     * "Today: 0.25 of 25 USDC used, 24.75 left" is the same facts in the order
+     * someone asked for them.
+     *
+     * `pending` is mentioned ONLY when it is non-zero. It is in-flight money —
+     * reserved, not yet settled — and naming it on every read invites the
+     * question "what's pending?" when the answer is almost always "nothing".
+     * But when it IS non-zero, leaving it out makes the arithmetic look wrong:
+     * cap minus used would not equal what is left.
+     */
+    const pendingNote = BigInt(b.pending) > 0n ? ` ${inFlight} ${sym} is still in flight.` : "";
     return json({
+        say: `Today: ${used} of ${cap} ${sym} used, ${left} ${sym} left.${pendingNote}` +
+            ` Resets at midnight UTC.`,
+        next_step: null,
+        // A read moves nothing. Stated rather than omitted so the field means the
+        // same thing on every tool that has it.
+        money_moved: false,
         node_id: nodeId,
         token: tokenLabel(tok, meta),
         /**
@@ -811,10 +919,10 @@ server.tool("vault_budget", "Read one node's budget for a UTC day: cap, executed
         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),
+        daily_cap: cap,
+        executed: used,
+        pending: inFlight,
+        available: left,
     });
 });
 /**
@@ -1112,7 +1220,38 @@ server.tool("vault_add_role", "Add a NEW departmental agent to an existing vault
         nodeId: null,
     });
     const payload = planAddRole(vault, role, limits, cooldownSec ?? 0, recipients ?? null, generated.publicKey, fundingYocto);
+    /**
+     * THE SENTENCE FOR THE MOMENT THIS TOOL IS USED.
+     *
+     * This returned a public key, a keyring path, a payload and two warnings —
+     * and agents duly reported "generated an ed25519 keypair, wrote it to the
+     * keyring; the 0.12 NEAR deposit funds a NEP-611 gas key" to someone who
+     * had asked for a news agent with a small budget.
+     *
+     * What the person needs is the BUDGET, in the units they named, and that
+     * one approval stands between them and it. The key, the path and the
+     * funding mechanics are real and stay in the payload for the agent.
+     *
+     * The caps are re-stated from the ARGUMENTS rather than the built payload,
+     * because the payload holds base units and the caller spoke in tokens.
+     */
+    /**
+     * RESOLVE THE SYMBOL. Passing `null` metadata here printed the token's
+     * ACCOUNT ID in the sentence — "1 usdc.testnet a day", and on mainnet a
+     * 64-character hex string. One cached view call, and it degrades to
+     * "tokens" rather than to an id when the chain cannot be reached, which
+     * keeps this tool usable offline.
+     */
+    const roleMeta = await tokenMeta(cfg.rpcUrl, tokenFor(token), (rpc, t) => viewFunction(rpc, t, "ft_metadata", {})).catch(() => null);
+    const roleSay = `I'll set up a ${role} budget: ${dailyCap} ${displaySymbol(roleMeta)} a day, and no ` +
+        `single payment over ${perTxCap}. You approve it once in your wallet, and after that ` +
+        `I can pay within those limits — I can't raise them myself. Nothing has changed yet.`;
     return json({
+        say: roleSay,
+        next_step: `Approve it in your wallet, then tell me and I'll confirm the ${role} budget is live.`,
+        // The approval moves 0.12 NEAR into the agent's gas key when signed, but
+        // NOTHING has moved at this point — this is an unsigned proposal.
+        money_moved: false,
         role,
         agent: {
             publicKey: generated.publicKey,
@@ -1614,7 +1753,12 @@ server.tool("vault_plan_add_node", "Build an UNSIGNED payload to create a budget
     limits: limitShape,
     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)));
+}, async ({ parent, label, limits, cooldownSec, recipients }) => {
+    // The PARENT's name, so the summary reads "under news" not "under node 1".
+    // Only looked up when there IS a parent.
+    const parentName = parent === null ? null : (await resolveNode(parent)).label;
+    return renderPlan(planAddNode(requireVault(), parent, label, limits, cooldownSec, recipients, parentName));
+});
 /**
  * Refuse to build a signable payload for a node that does not exist.
  *
@@ -1636,19 +1780,38 @@ server.tool("vault_plan_add_node", "Build an UNSIGNED payload to create a budget
  * them just prompts another guess.
  */
 async function assertNode(nodeId) {
+    return (await resolveNode(nodeId)).missing;
+}
+/**
+ * One tree read, answering BOTH questions a plan handler has: does this node
+ * exist, and what do humans call it?
+ *
+ * THE LABEL WAS ALREADY BEING FETCHED AND THROWN AWAY. `assertNode` read
+ * `label` purely to list it in a "no such node" message, so every plan summary
+ * said "node 1" while the word "news" sat in the same response. Returning it
+ * costs nothing and is what lets `budgetName` do its job.
+ *
+ * A FAILED READ RETURNS NO LABEL AND NO COMPLAINT. The chain being briefly
+ * unreachable is not evidence the node is missing — refusing here would turn a
+ * blip into "your node does not exist" — and it is not evidence the node is
+ * unnamed either, so the summary falls back to "this budget" rather than
+ * inventing one.
+ */
+async function resolveNode(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;
+        return { missing: null, label: null };
+    const hit = tree.find((n) => n.id === nodeId);
+    if (hit)
+        return { missing: null, label: hit.label ?? 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(", ") };
+    return {
+        missing: { known: tree.map((n) => `${n.id}${n.label ? ` (${n.label})` : ""}`).join(", ") },
+        label: null,
+    };
 }
 /** 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 ` +
@@ -1656,33 +1819,33 @@ const noNodeForPlan = (nodeId, known) => `This vault has no node ${nodeId}, so t
 /** 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));
+    const n = await resolveNode(nodeId);
+    return n.missing
+        ? text(noNodeForPlan(nodeId, n.missing.known))
+        : renderPlan(planSetNodeCaps(requireVault(), nodeId, limits, n.label));
 });
 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)));
+}, async ({ nodeId, publicKey }) => renderPlan(planBindVirtualAgent(requireVault(), nodeId, publicKey, (await resolveNode(nodeId)).label)));
 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 }) => {
-    const bad = await assertNode(nodeId);
-    return bad
-        ? text(noNodeForPlan(nodeId, bad.known))
-        : renderPlan(planFreezeNode(requireVault(), nodeId, frozen));
+    const n = await resolveNode(nodeId);
+    return n.missing
+        ? text(noNodeForPlan(nodeId, n.missing.known))
+        : renderPlan(planFreezeNode(requireVault(), nodeId, frozen, n.label));
 });
 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));
+    const n = await resolveNode(nodeId);
+    return n.missing
+        ? text(noNodeForPlan(nodeId, n.missing.known))
+        : renderPlan(planSetRecipients(requireVault(), nodeId, recipients, n.label));
 })());
 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));
+    const n = await resolveNode(nodeId);
+    return n.missing
+        ? text(noNodeForPlan(nodeId, n.missing.known))
+        : renderPlan(planSetCooldown(requireVault(), nodeId, cooldownSec, n.label));
 });
 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,
@@ -1695,7 +1858,7 @@ server.tool("vault_plan_set_approval_threshold", 'Build an UNSIGNED payload requ
     // planSetApprovalThreshold in payloads.ts for the measurement.
     amount: z.string().min(1).nullable().describe('human units, e.g. "0.25" — NOT base units'),
     decimals: z.number().int().min(0).max(38).default(6),
-}, async ({ nodeId, amount, decimals }) => renderPlan(planSetApprovalThreshold(requireVault(), nodeId, amount, decimals)));
+}, async ({ nodeId, amount, decimals }) => renderPlan(planSetApprovalThreshold(requireVault(), nodeId, amount, decimals, (await resolveNode(nodeId)).label)));
 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)));
 /**

package/dist/token-meta.d.ts

@@ -39,4 +39,20 @@ export declare function tokenMeta(rpcUrl: string, token: string, view: Fetcher):
  * to remain visible.
  */
 export declare function label(token: string, meta: TokenMeta | null): string;
+/**
+ * The symbol ALONE, for a sentence a person reads.
+ *
+ * `label()` returns `USDC (17208628f84f5d6ad33f…)`, which is right for a JSON
+ * field — the id is what a support conversation needs — and wrong inside
+ * prose. Dropped into a `say` it produced "1 usdc.testnet a day", and on
+ * mainnet it would have been "1 17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1 a day",
+ * because Circle-native USDC's account id is 64 hex characters.
+ *
+ * Falls back to "tokens" rather than the id. An unresolvable symbol is a
+ * cosmetic loss; a 64-character hex string in the middle of a sentence tells
+ * the reader the product is broken. `vault_pay` already did exactly this —
+ * `meta?.symbol ?? "tokens"` — and this just names the pattern so the next
+ * caller does not have to rediscover it.
+ */
+export declare function displaySymbol(meta: TokenMeta | null): string;
 export {};

package/dist/token-meta.js

@@ -44,3 +44,21 @@ export async function tokenMeta(rpcUrl, token, view) {
 export function label(token, meta) {
     return meta ? `${meta.symbol} (${token})` : token;
 }
+/**
+ * The symbol ALONE, for a sentence a person reads.
+ *
+ * `label()` returns `USDC (17208628f84f5d6ad33f…)`, which is right for a JSON
+ * field — the id is what a support conversation needs — and wrong inside
+ * prose. Dropped into a `say` it produced "1 usdc.testnet a day", and on
+ * mainnet it would have been "1 17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1 a day",
+ * because Circle-native USDC's account id is 64 hex characters.
+ *
+ * Falls back to "tokens" rather than the id. An unresolvable symbol is a
+ * cosmetic loss; a 64-character hex string in the middle of a sentence tells
+ * the reader the product is broken. `vault_pay` already did exactly this —
+ * `meta?.symbol ?? "tokens"` — and this just names the pattern so the next
+ * caller does not have to rediscover it.
+ */
+export function displaySymbol(meta) {
+    return meta?.symbol ?? "tokens";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floatonnear/mcp",
-  "version": "0.10.2",
+  "version": "0.10.3",
   "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",