@floatonnear/mcp 0.10.0 → 0.10.2

package/SKILL.md

@@ -92,7 +92,7 @@ As soon as setup is done, say what they have and what it would cost. Something
 close to this, in your own words:
 
 > You don't have a vault yet. I can set one up — it's **one signature in your
-> own wallet**, and you need to be holding about **3.55 NEAR**. Almost all of
+> own wallet**, and you need to be holding about **3.7 NEAR**. Almost all of
 > that is a refundable storage deposit your vault keeps, not a fee. Want me to?
 
 Three things that wording is carrying, and all three matter:
@@ -105,10 +105,18 @@ Three things that wording is carrying, and all three matter:
 - **refundable.** 3.55 NEAR reads as a fee unless you say otherwise. It is a
   storage deposit the vault holds and returns on teardown.
 
-**Quote `vault_create`'s own `totalRequiredNear`, not the 3.55 above**, once you
+**Quote `vault_create`'s own `totalRequiredNear`, not the 3.7 above**, once you
 have called it. That figure is derived from the exact contract being deployed;
 this one is an illustration and will drift as the contract changes.
 
+**3.7 IS THE WITH-AGENT FIGURE, AND IT IS DELIBERATELY THE HIGHER ONE.** Binding
+an agent in the creation transaction adds 0.12 NEAR of gas-key funding, so the
+real totals are **3.54839 without** an agent and **3.66839 with** one. Binding
+one is the normal thing to do — otherwise the vault cannot pay — so the offer
+must quote the larger number. An understated quote is not a rounding nicety: a
+user who funds to exactly what they were told has the transaction REFUSED by
+their own wallet, which reads as the product being broken. Round up, always.
+
 **Do NOT auto-create one.** It spends real money, and it cannot complete
 without them anyway — `vault_create` returns a link they approve in their own
 wallet, so running it unasked produces a link nobody wanted and still waits.
@@ -143,11 +151,49 @@ key on the machine, which is the thing above.
   Your key's `method_names` is `["request_payment"]` and nothing else.
 - attach NEAR to anything. A NEAR function-call key cannot carry a deposit.
 - **fund the vault.** That needs the owner's tokens and the owner's key. If the
-  vault is empty, say so and ask the human — do not try to fix it yourself.
+  vault is empty, say so and ask the human — do not try to fix it yourself, and
+  send them to their WALLET, never to a CLI. See below.
 
 If a request needs one of those, produce a plan with `vault_plan_*` and hand it
 to the human. Do not attempt it and report the error.
 
+### Funding a vault — the wallet, always, never the CLI
+
+Someone has to put tokens in. **Tell them to send from their own wallet**, name
+the three fields, and stop:
+
+> Open your wallet as `<owner>` and send `<amount>` `<TOKEN>` to `<vault>`.
+> Check the token's CONTRACT ID, not just the ticker — `<contract>`.
+
+**Do NOT hand over an `ft_transfer` command, and do not offer to run one.**
+Measured 2026-11-13: asked to fund a vault, an agent found a full-access key in
+`~/.near-credentials` and offered `near call … ft_transfer` as a co-equal option
+beside the wallet. The user had to correct it. A token send is the one operation
+every wallet already does well — a button, with the balance, the ticker and the
+destination on screen before anything is signed. Replacing that with base-unit
+arithmetic (`"amount":"1000000"`), a `--depositYocto 1` the user cannot
+sanity-check, and a key read off disk is worse precisely when they are deciding
+whether to trust this thing with money.
+
+It also contradicts the rest of this file. Creation already refuses the CLI for
+anyone being onboarded — *"never offer to run the CLI on someone else's
+behalf"* — and funding is the same situation with the same answer. The wizard's
+`--fund` flag belongs to an operator on their own machine with their own key; it
+is not a funding path to offer a user.
+
+Two things to say in the same message, because both fail SILENTLY:
+
+- **the token contract, not the ticker.** Caps are keyed per token. NEAR has a
+  native USDC and an older bridged `USDC.e` — send the wrong one and it arrives,
+  shows as a balance, and the agent still has zero budget for it. The refusal
+  reads as a broken vault.
+- **the payee allowlist.** Read it with `vault_tree` first. If it still holds
+  only the owner, the agent can pay nobody but the owner, and funding past a
+  test amount buys nothing yet.
+
+Then verify instead of taking their word for it: read the vault's
+`ft_balance_of` and tell them what actually landed.
+
 ## Daily use — the MCP tools
 
 If `float` is configured in your MCP client, you have these. Read before you

package/dist/agent-key.d.ts

@@ -50,6 +50,22 @@ export interface GeneratedAgentKey {
 export declare function generateAgentKey(opts: {
     vault: string;
     dir?: string;
+    /**
+     * The exact keyring file to write, overriding `dir` and the hardcoded
+     * `agent-keys.json` filename.
+     *
+     * WHY IT HAS TO EXIST. The caller configures a keyring by full PATH
+     * (`NEAR_VAULT_AGENT_KEYS`), and this function used to accept only a
+     * directory and append a fixed filename. So pinning the keyring to, say,
+     * `~/keys/fleet.json` meant the server READ `fleet.json` and WROTE
+     * `~/keys/agent-keys.json` — a brand new agent, filed where nothing would
+     * ever look for it, reported as success. Silent, and exactly the "written
+     * somewhere you are not reading" failure this module is supposed to prevent.
+     *
+     * Caught by the smoke test that pins a non-default filename, not by a unit
+     * test: every unit test here passes a directory.
+     */
+    keyringPath?: string;
     /**
      * The node this agent spends from.
      *
@@ -85,3 +101,37 @@ export declare function agentKeyPaths(dir?: string): {
     envPath: string;
     dir: string;
 };
+/**
+ * Take a role name off a keyring entry that is PROVEN not bound on chain,
+ * without destroying its secret.
+ *
+ * WHY THIS IS NEEDED. `generateAgentKey` appends and never replaces, for the
+ * reason above: overwriting could destroy the only copy of a credential for an
+ * agent that is already bound and funded. But `selectRole` resolves a role with
+ * `entries.find(...)` — FIRST match wins. So an orphaned entry (a key written
+ * by a `vault_add_role` that then failed to land on chain) would permanently
+ * SHADOW the replacement: every future payment under that role would select a
+ * key the contract answers NOT_VIRTUAL_AGENT for, and the working key beside it
+ * would never be reached.
+ *
+ * So the orphan's role is RENAMED rather than deleted. The secret stays on
+ * disk, the entry stays in the file, and the name resolves to exactly one
+ * credential again. Deleting would be tidier and is not worth the risk: the
+ * caller's proof of deadness is a chain read, and a chain read can be wrong
+ * about a vault that is paused, migrating, or being served by a lagging RPC.
+ * A renamed entry survives that mistake; a deleted one does not.
+ *
+ * Identified BY PUBLIC KEY, never by role alone — the whole point is that two
+ * entries can share a role at this moment, and renaming the wrong one would
+ * retire the live agent.
+ *
+ * Returns the new role name, or null if no entry matched (already retired, or
+ * a keyring that moved under us) — which is not an error.
+ */
+export declare function retireRole(opts: {
+    keyringPath: string;
+    vault: string;
+    publicKey: string;
+}): {
+    retiredTo: string;
+} | null;

package/dist/agent-key.js

@@ -58,11 +58,13 @@ export const AGENT_NODE_ID = 1;
  * `NEAR_VAULT_AGENT_ID` is set to a vault id in `.mcp.json`.
  */
 export function generateAgentKey(opts) {
-    const dir = opts.dir ?? ".float";
     // `undefined` -> root (the creation-time agent). `null` -> unknown, and the
     // field is omitted rather than guessed.
     const nodeId = opts.nodeId === null ? undefined : (opts.nodeId ?? AGENT_NODE_ID);
-    const keyringPath = join(dir, "agent-keys.json");
+    // An explicit path wins and decides the directory; otherwise the old
+    // dir-plus-fixed-filename behaviour, unchanged.
+    const keyringPath = opts.keyringPath ?? join(opts.dir ?? ".float", "agent-keys.json");
+    const dir = dirname(keyringPath);
     const envPath = join(dir, "agent.env");
     const kp = KeyPair.fromRandom("ed25519");
     const publicKey = kp.getPublicKey().toString();
@@ -133,3 +135,67 @@ export function generateAgentKey(opts) {
 export function agentKeyPaths(dir = ".float") {
     return { keyringPath: join(dir, "agent-keys.json"), envPath: join(dir, "agent.env"), dir: dirname(join(dir, "x")) };
 }
+/**
+ * Take a role name off a keyring entry that is PROVEN not bound on chain,
+ * without destroying its secret.
+ *
+ * WHY THIS IS NEEDED. `generateAgentKey` appends and never replaces, for the
+ * reason above: overwriting could destroy the only copy of a credential for an
+ * agent that is already bound and funded. But `selectRole` resolves a role with
+ * `entries.find(...)` — FIRST match wins. So an orphaned entry (a key written
+ * by a `vault_add_role` that then failed to land on chain) would permanently
+ * SHADOW the replacement: every future payment under that role would select a
+ * key the contract answers NOT_VIRTUAL_AGENT for, and the working key beside it
+ * would never be reached.
+ *
+ * So the orphan's role is RENAMED rather than deleted. The secret stays on
+ * disk, the entry stays in the file, and the name resolves to exactly one
+ * credential again. Deleting would be tidier and is not worth the risk: the
+ * caller's proof of deadness is a chain read, and a chain read can be wrong
+ * about a vault that is paused, migrating, or being served by a lagging RPC.
+ * A renamed entry survives that mistake; a deleted one does not.
+ *
+ * Identified BY PUBLIC KEY, never by role alone — the whole point is that two
+ * entries can share a role at this moment, and renaming the wrong one would
+ * retire the live agent.
+ *
+ * Returns the new role name, or null if no entry matched (already retired, or
+ * a keyring that moved under us) — which is not an error.
+ */
+export function retireRole(opts) {
+    if (!existsSync(opts.keyringPath))
+        return null;
+    let entries;
+    try {
+        const parsed = JSON.parse(readFileSync(opts.keyringPath, "utf8"));
+        if (!Array.isArray(parsed))
+            return null;
+        entries = parsed;
+    }
+    catch {
+        // Unreadable is not this function's problem to fix; `generateAgentKey`
+        // already backs such a file aside before writing.
+        return null;
+    }
+    let retiredTo;
+    for (const e of entries) {
+        if (!e || typeof e !== "object")
+            continue;
+        if (e.agentId !== opts.vault)
+            continue;
+        if (e.publicKey !== opts.publicKey)
+            continue;
+        if (typeof e.role !== "string")
+            continue;
+        // A short slice of the public key keeps two retirements of the same role
+        // from colliding, and keeps the name traceable back to the exact entry.
+        retiredTo = `${e.role}-retired-${opts.publicKey.slice(8, 16)}`;
+        e.role = retiredTo;
+        // The node id, if any, was never real for an unbound key.
+        delete e.nodeId;
+    }
+    if (!retiredTo)
+        return null;
+    writeFileSync(opts.keyringPath, `${JSON.stringify(entries, null, 2)}${String.fromCharCode(10)}`);
+    return { retiredTo };
+}

package/dist/create.d.ts

@@ -62,6 +62,16 @@ export declare const STORAGE_COST_PER_BYTE: bigint;
  * copy that drifts.
  */
 export declare const PAGE_HEADROOM_YOCTO: bigint;
+/**
+ * NEP-145 registration for ONE token, mirroring the factory's
+ * `TOKEN_REGISTRATION` and the vault's `DEPOSIT_ADDRESS_STORAGE`.
+ *
+ * The factory registers a new vault on every token named in `root_limits`, so
+ * a plain `ft_transfer` into it succeeds — before that it failed with "the
+ * account is not registered", which broke funding for every browser-created
+ * vault. Pinned against the contract by `create.pins.test.ts`.
+ */
+export declare const TOKEN_REGISTRATION_YOCTO: bigint;
 /**
  * Funding for an agent's gas key, when one is bound at creation.
  *

package/dist/create.js

@@ -62,6 +62,16 @@ export const STORAGE_COST_PER_BYTE = 10n ** 19n;
  * copy that drifts.
  */
 export const PAGE_HEADROOM_YOCTO = 36n * 10n ** 22n;
+/**
+ * NEP-145 registration for ONE token, mirroring the factory's
+ * `TOKEN_REGISTRATION` and the vault's `DEPOSIT_ADDRESS_STORAGE`.
+ *
+ * The factory registers a new vault on every token named in `root_limits`, so
+ * a plain `ft_transfer` into it succeeds — before that it failed with "the
+ * account is not registered", which broke funding for every browser-created
+ * vault. Pinned against the contract by `create.pins.test.ts`.
+ */
+export const TOKEN_REGISTRATION_YOCTO = 125n * 10n ** 19n;
 /**
  * Funding for an agent's gas key, when one is bound at creation.
  *
@@ -258,8 +268,20 @@ export function buildCreatePlan(i) {
     // Both floors move by the gas-key funding when an agent is bound: the page
     // attaches it, and the factory requires it.
     const agentFunding = i.agentPk ? AGENT_GAS_KEY_FUNDING_YOCTO : 0n;
+    /**
+     * The factory also registers the new vault on each token in `root_limits`,
+     * so its floor covers that too — otherwise it would fund those receipts from
+     * its OWN balance, which is the drain documented in the contract.
+     *
+     * Counted as ONE because `vault_create` builds a single-token `root_limits`.
+     * It does not change the quoted total today: the page's 0.36 headroom keeps
+     * `pageAttaches` above the floor either way, and `max` picks the page. It is
+     * included so the floor stays correct if an operator raises
+     * `required_deposit` and the floor becomes the binding term.
+     */
+    const registrations = TOKEN_REGISTRATION_YOCTO;
     const pageAttaches = stake + PAGE_HEADROOM_YOCTO + agentFunding;
-    const factoryFloor = BigInt(i.requiredDepositYocto) + stake + agentFunding;
+    const factoryFloor = BigInt(i.requiredDepositYocto) + stake + agentFunding + registrations;
     const deposit = pageAttaches > factoryFloor ? pageAttaches : factoryFloor;
     const total = deposit + GAS_RESERVATION_YOCTO;
     // If the operator raises `required_deposit` past the page's headroom, the

package/dist/keyring-path.d.ts

@@ -0,0 +1,36 @@
+export declare const KEYRING_FILENAME: string;
+export interface ResolvedKeyring {
+    /** Absolute path. Never relative — that is the whole point of this module. */
+    path: string;
+    /** Plain-English reason, safe to show a user. Names no secrets. */
+    why: string;
+    /**
+     * Other keyrings that ALSO hold a credential for this vault and are not
+     * being read. Empty in the normal case. Non-empty means a split keyring,
+     * which a user needs told rather than silently resolved.
+     */
+    alsoFound: string[];
+}
+/**
+ * How many credentials a keyring file holds for `vault`.
+ *
+ * Deliberately TOLERANT about the credential field name. `roles.ts` loads only
+ * `secret`, but `prove-refusal.mjs` reads `privateKey ?? secret ?? agentKey`,
+ * and a file written by one path must still be FOUND by this one — otherwise
+ * resolution sends the user to an empty home keyring while their real keys sit
+ * in a shape this function refused to count. Finding the file and loading an
+ * entry out of it are different jobs; `listUnloadable` reports the second.
+ *
+ * Never throws, and never returns the contents. A corrupt or unreadable file
+ * counts as zero; the caller is choosing a path, not validating a keyring.
+ */
+export declare function countFor(path: string, vault?: string): number;
+export declare function resolveKeyringPath(opts: {
+    /** The raw `NEAR_VAULT_AGENT_KEYS` value, if the operator set one. */
+    explicit?: string;
+    vault?: string;
+    /** Injectable so a test does not depend on where it was run from. */
+    cwd?: string;
+    home?: string;
+    count?: (path: string, vault?: string) => number;
+}): ResolvedKeyring;

package/dist/keyring-path.js

@@ -0,0 +1,117 @@
+/**
+ * WHERE THE FLEET KEYRING LIVES — and why it must not be a relative path.
+ *
+ * THE BUG THIS EXISTS TO KILL. The default was the bare string
+ * `.float/agent-keys.json`, which Node resolves against `process.cwd()`. An MCP
+ * server's CWD is wherever the CLIENT was launched, which the user does not
+ * choose and cannot see. So one single server entry in `~/.claude.json` became
+ * a DIFFERENT keyring per directory:
+ *
+ *   launched from  New project\   ->  New project\.float\agent-keys.json
+ *   launched from  near-vault\    ->  near-vault\.float\agent-keys.json
+ *
+ * Measured 2026-11-13 on this machine: `NEAR_VAULT_AGENT_KEYS` is UNSET for the
+ * `float` server, so a `travel` agent key written from one directory was
+ * invisible from the other. The tool reported "no agent with role 'travel'"
+ * while the key sat on disk a few folders away. Nothing in the output could
+ * distinguish "never created" from "created somewhere you are not looking",
+ * which is the same shape as the keyring-reader disagreement `roles.ts` already
+ * has a comment about.
+ *
+ * THE RULE. Resolution answers one question: *which file can sign for THIS
+ * vault?* Not "which directory am I in".
+ *
+ *   1. `NEAR_VAULT_AGENT_KEYS` set  -> that, made absolute. Explicit wins; an
+ *      operator who pinned a path gets the path they pinned.
+ *   2. Otherwise, of the CWD keyring and the HOME keyring, the one that already
+ *      holds a credential for this vault. This is the back-compat case: anyone
+ *      whose keys are in a project-local `.float/` keeps working untouched.
+ *   3. Otherwise HOME — `~/.float/agent-keys.json`. New keys land somewhere
+ *      stable, so the NEXT session finds them whatever directory it starts in.
+ *
+ * Rule 3 is the actual fix. Rules 1 and 2 are there so turning it on cannot
+ * strand a key that already exists.
+ *
+ * WHEN BOTH HOLD KEYS it is a split keyring, and picking silently would hide
+ * one agent's roles behind another's. One is chosen so the tool still works,
+ * and the other is RETURNED in `alsoFound` so a caller can say so out loud.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+export const KEYRING_FILENAME = join(".float", "agent-keys.json");
+/**
+ * How many credentials a keyring file holds for `vault`.
+ *
+ * Deliberately TOLERANT about the credential field name. `roles.ts` loads only
+ * `secret`, but `prove-refusal.mjs` reads `privateKey ?? secret ?? agentKey`,
+ * and a file written by one path must still be FOUND by this one — otherwise
+ * resolution sends the user to an empty home keyring while their real keys sit
+ * in a shape this function refused to count. Finding the file and loading an
+ * entry out of it are different jobs; `listUnloadable` reports the second.
+ *
+ * Never throws, and never returns the contents. A corrupt or unreadable file
+ * counts as zero; the caller is choosing a path, not validating a keyring.
+ */
+export function countFor(path, vault) {
+    if (!existsSync(path))
+        return 0;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return 0;
+    }
+    if (!Array.isArray(parsed))
+        return 0;
+    return parsed.filter((e) => {
+        if (!e || typeof e !== "object")
+            return false;
+        const id = e.agentId ?? e.vault;
+        if (vault && id !== vault)
+            return false;
+        return ["secret", "privateKey", "agentKey"].some((k) => typeof e[k] === "string");
+    }).length;
+}
+export function resolveKeyringPath(opts) {
+    const cwd = opts.cwd ?? process.cwd();
+    const home = opts.home ?? homedir();
+    const count = opts.count ?? countFor;
+    if (opts.explicit) {
+        // Resolved even when already absolute, so the returned path is normalised
+        // and a relative override still cannot vary with CWD mid-session.
+        const path = isAbsolute(opts.explicit) ? opts.explicit : resolve(cwd, opts.explicit);
+        return { path, why: "NEAR_VAULT_AGENT_KEYS is set", alsoFound: [] };
+    }
+    const cwdRing = resolve(cwd, KEYRING_FILENAME);
+    const homeRing = join(home, KEYRING_FILENAME);
+    // Same directory: nothing to choose between, and no split to report.
+    if (cwdRing === homeRing) {
+        return { path: homeRing, why: "the default keyring in your home folder", alsoFound: [] };
+    }
+    const inCwd = count(cwdRing, opts.vault);
+    const inHome = count(homeRing, opts.vault);
+    if (inCwd > 0 && inHome === 0) {
+        return {
+            path: cwdRing,
+            why: "it already holds a key for this vault",
+            alsoFound: [],
+        };
+    }
+    if (inHome > 0 && inCwd > 0) {
+        return {
+            path: homeRing,
+            why: "it holds a key for this vault",
+            // The one NOT being read. Surfaced so "my agent vanished" is answerable.
+            alsoFound: [cwdRing],
+        };
+    }
+    return {
+        path: homeRing,
+        why: inHome > 0
+            ? "it already holds a key for this vault"
+            : "the default keyring in your home folder, so the next session finds it from any directory",
+        alsoFound: [],
+    };
+}

package/dist/roles.d.ts

@@ -4,6 +4,26 @@ export interface RoleCredential {
     role: string;
     nodeId?: number;
 }
+/**
+ * Entries belonging to this vault that the loader REJECTS, and why.
+ *
+ * `loadable` drops anything without a string `secret`, and the reasoning is
+ * sound — the adapter applies the same predicate, so listing such an entry
+ * would advertise an agent that can never be selected. But DROPPING IT
+ * SILENTLY is the same failure this file already has a memory about: the user
+ * holds a key, the tool shows nothing, and there is no way to tell "no agent"
+ * from "an agent in a shape I refuse to read".
+ *
+ * Shapes do vary in the wild: `prove-refusal.mjs` reads
+ * `privateKey ?? secret ?? agentKey`, so a file written by another path can
+ * land here unreadable. Reported, not hidden.
+ */
+export declare function listUnloadable(cfg: {
+    agentKeysPath?: string;
+    vault?: string;
+}): {
+    reason: string;
+}[];
 export declare class RoleSelectionError extends Error {
 }
 export declare function selectRole(cfg: {
@@ -43,4 +63,13 @@ export declare function listAgents(cfg: {
     agentId: string;
     role: string | null;
     nodeId?: number;
+    /**
+     * THE PUBLIC half, so a caller can ask the CHAIN about this key.
+     *
+     * It was omitted, and that omission is what made `vault_roles` unable to
+     * tell a working agent from a dead one: with no public key there is nothing
+     * to look up, so the only thing it could report was what the local file
+     * claimed. No key material — the public key is public.
+     */
+    publicKey?: string;
 }[];

package/dist/roles.js

@@ -11,6 +11,54 @@
  * as a credential is how an agent ends up "configured" and unreachable.
  */
 import { existsSync, readFileSync } from "node:fs";
+/**
+ * Entries belonging to this vault that the loader REJECTS, and why.
+ *
+ * `loadable` drops anything without a string `secret`, and the reasoning is
+ * sound — the adapter applies the same predicate, so listing such an entry
+ * would advertise an agent that can never be selected. But DROPPING IT
+ * SILENTLY is the same failure this file already has a memory about: the user
+ * holds a key, the tool shows nothing, and there is no way to tell "no agent"
+ * from "an agent in a shape I refuse to read".
+ *
+ * Shapes do vary in the wild: `prove-refusal.mjs` reads
+ * `privateKey ?? secret ?? agentKey`, so a file written by another path can
+ * land here unreadable. Reported, not hidden.
+ */
+export function listUnloadable(cfg) {
+    const path = cfg.agentKeysPath ?? ".float/agent-keys.json";
+    if (!existsSync(path))
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (e) {
+        return [{ reason: `${path} is not readable JSON (${e.message}). A UTF-8 BOM does this.` }];
+    }
+    if (!Array.isArray(parsed))
+        return [{ reason: `${path} is not a JSON array.` }];
+    const out = [];
+    for (const e of parsed) {
+        if (!e || typeof e !== "object")
+            continue;
+        const id = (e.agentId ?? e.vault);
+        // Only this vault's entries; another vault's are not this tool's business.
+        if (cfg.vault && id !== cfg.vault)
+            continue;
+        if (typeof e.agentId === "string" && typeof e.secret === "string")
+            continue; // loadable
+        const has = ["secret", "privateKey", "agentKey"].filter((k) => typeof e[k] === "string");
+        out.push({
+            reason: typeof e.agentId !== "string"
+                ? `an entry for this vault has no string 'agentId', so it cannot be matched to a vault.`
+                : `an entry has no 'secret' field${has.length ? ` (it uses '${has.join("', '")}' instead)` : ""}, ` +
+                    `which is the only field the keyring loader reads. It will never be selectable. ` +
+                    `Re-create the agent with vault_add_role.`,
+        });
+    }
+    return out;
+}
 /** Entries that `loadKeyring` would accept, nothing else. */
 function loadable(path) {
     if (!existsSync(path))
@@ -113,5 +161,6 @@ export function listAgents(cfg) {
         agentId: e.agentId,
         role: typeof e.role === "string" ? e.role : null,
         nodeId: typeof e.nodeId === "number" ? e.nodeId : undefined,
+        publicKey: typeof e.publicKey === "string" ? e.publicKey : undefined,
     }));
 }

package/dist/server.js

@@ -56,12 +56,13 @@ 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, 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 { AGENT_NODE_ID, generateAgentKey, retireRole } from "./agent-key.js";
 import { resolveKeySource } from "./key-file.js";
 import { dirname, resolve } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { listAgents, listRoles, selectRole } from "./roles.js";
+import { listAgents, listUnloadable, selectRole } from "./roles.js";
+import { resolveKeyringPath } from "./keyring-path.js";
 import { label as tokenLabel, tokenMeta } from "./token-meta.js";
 /**
  * A decimal NEAR string to yoctoNEAR, without floating point.
@@ -157,6 +158,25 @@ if (!Object.hasOwn(RPC_BY_NETWORK, NETWORK)) {
         `questions about the wrong chain.`);
     process.exit(1);
 }
+/**
+ * A syntactically valid ed25519 key used ONLY to dry-run payload construction.
+ *
+ * `planAddRole` needs a public key to build args, and we want its exceptions
+ * BEFORE generating a real one. All zeroes in base58 is "1" repeated, which
+ * parses as a key and is obviously not anyone's.
+ */
+/**
+ * Resolved ONCE, at startup, from the environment — never recomputed, so the
+ * path cannot change mid-session if something alters the working directory.
+ *
+ * The vault id is read straight from the env rather than from `cfg`, because
+ * `cfg` is what this feeds.
+ */
+const KEYRING = resolveKeyringPath({
+    explicit: process.env.NEAR_VAULT_AGENT_KEYS,
+    vault: process.env.NEAR_VAULT_CONTRACT,
+});
+const PLACEHOLDER_PUBLIC_KEY = `ed25519:${"1".repeat(44)}`;
 const cfg = {
     vault: process.env.NEAR_VAULT_CONTRACT ?? "",
     /**
@@ -220,10 +240,17 @@ const cfg = {
     // Guarded by `scripts/check-create-page.mjs`, which fetches the real link
     // shape, follows redirects, and checks the wasm at the landing origin.
     appUrl: process.env.NEAR_VAULT_APP_URL ?? "https://usefloat.xyz",
-    // The fleet keyring. Same default and same file the adapter reads — two
-    // readers disagreeing about where credentials live is how an agent ends up
-    // "configured" and unreachable.
-    agentKeysPath: process.env.NEAR_VAULT_AGENT_KEYS ?? ".float/agent-keys.json",
+    // The fleet keyring. Same file the adapter reads — two readers disagreeing
+    // about where credentials live is how an agent ends up "configured" and
+    // unreachable.
+    //
+    // RESOLVED, NOT DEFAULTED. This was the bare relative string
+    // `.float/agent-keys.json`, which Node resolves against the server's CWD —
+    // i.e. wherever the CLIENT happened to be launched. One server entry in
+    // `~/.claude.json` therefore meant a DIFFERENT keyring per directory, and a
+    // key written from one project was invisible from another. See
+    // `keyring-path.ts` for the resolution rule and the measurement.
+    agentKeysPath: KEYRING.path,
 };
 /**
  * NO VAULT IS THE COMMONEST STATE, SO THE MESSAGE HAS TO BE AN ONRAMP.
@@ -381,7 +408,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.0" }, { instructions: INSTRUCTIONS });
+const server = new McpServer({ name: "float", version: "0.10.2" }, { instructions: INSTRUCTIONS });
 /**
  * THE FULL OPERATING GUIDE, AS AN MCP RESOURCE.
  *
@@ -588,16 +615,97 @@ server.tool("vault_await_create", "After the user signs the create link, confirm
                 `under a label instead, which lands on a different address.`,
         });
     }
+    /**
+     * WHAT ACTUALLY STOPS THIS VAULT PAYING, read from the chain.
+     *
+     * The old `nextSteps` were a FIXED list ending "nothing can spend from it
+     * until an agent is bound — vault_add_role". For a vault created with
+     * `bindAgent` that is simply false: the agent is already bound, and the
+     * real gate is that the vault holds no tokens. Measured 2026-11-13 — the
+     * agent relaying it had to correct the tool in front of the user.
+     *
+     * Worse, nothing told the owner HOW to fund it, or that funding is a plain
+     * wallet send to an address, or what that address is. This is the moment
+     * they need it: they have just signed, they are looking at the result, and
+     * the next thing standing between them and a working vault is money.
+     *
+     * So the steps are derived from live state instead of asserted. Three
+     * reads, once, on a path that runs once per vault.
+     */
+    const rootToken = await (async () => {
+        // THE TREE IS AUTHORITATIVE, not cfg.token: at creation time
+        // NEAR_VAULT_CONTRACT is typically unset, so the configured token may be
+        // empty while the vault plainly names one in its root limits.
+        const tree = await viewFunction(rpc, target, "get_tree", {}).catch(() => null);
+        return tree?.find((n) => n.id === 0)?.limits?.[0]?.token;
+    })();
+    const meta = rootToken
+        ? await tokenMeta(rpc, rootToken, (r, t) => viewFunction(r, t, "ft_metadata", {})).catch(() => null)
+        : null;
+    const symbol = meta?.symbol ?? "the token";
+    const [held, registered, agentKeys] = await Promise.all([
+        rootToken
+            ? viewFunction(rpc, rootToken, "ft_balance_of", { account_id: target }).catch(() => null)
+            : Promise.resolve(null),
+        rootToken
+            ? viewFunction(rpc, rootToken, "storage_balance_of", {
+                account_id: target,
+            }).catch(() => undefined)
+            : Promise.resolve(undefined),
+        viewAccessKeys(rpc, target)
+            // Narrowed the same way vault_gas does: `permission` is a union and
+            // only the gas-key arm carries this field.
+            .then((ks) => ks.filter((k) => k.access_key?.permission
+            ?.GasKeyFunctionCall !== undefined).length)
+            .catch(() => null),
+    ]);
+    const empty = held !== null && BigInt(held) === 0n;
+    const funding = {
+        token: rootToken ?? null,
+        symbol: rootToken ? symbol : null,
+        balance: held === null ? null : fromBaseUnits(BigInt(held), meta?.decimals ?? cfg.decimals),
+        /** `undefined` = could not read; `null` = read and NOT registered. */
+        registeredOnToken: registered === undefined ? null : registered !== null,
+        sendTo: target,
+        howTo: `Funding is a plain send from the owner's own wallet: send ${symbol} to ${target}. ` +
+            `This server cannot do it — the agent key cannot touch a token contract, which is the ` +
+            `point of the product.`,
+    };
+    const nextSteps = [
+        `Set NEAR_VAULT_CONTRACT=${target} so every other tool reads this vault.`,
+    ];
+    /**
+     * UNREGISTERED IS NAMED FIRST, because it is the one that makes a transfer
+     * FAIL rather than merely be impossible. Vaults created before the factory
+     * registered them are still in this state; the fix is forward-only.
+     */
+    if (registered === null) {
+        nextSteps.push(`REGISTER IT FIRST: ${target} is not registered on ${rootToken}, and a transfer to an ` +
+            `unregistered account FAILS. The owner must call storage_deposit on the token with ` +
+            `about 0.00125 NEAR attached and registration_only: true. Vaults created through the ` +
+            `current factory are registered automatically; this one was not.`);
+    }
+    if (empty) {
+        nextSteps.push(`FUND IT: the vault holds no ${symbol}. Tell the owner to send ${symbol} to ${target} ` +
+            `from their own wallet, and ASK how much they want to move. Nothing can be paid out ` +
+            `until it has a balance — the budget caps what MAY be spent, not what exists.`);
+    }
+    if (agentKeys === 0) {
+        nextSteps.push(`No agent is bound yet, so nothing can authorise a payment — vault_add_role.`);
+    }
+    if (!empty && agentKeys !== 0 && registered !== null) {
+        nextSteps.push(`Ready. vault_budget shows today's allowance; vault_pay makes a payment.`);
+    }
+    else {
+        nextSteps.push(`vault_tree shows the budget shape; vault_budget shows what is left today.`);
+    }
     return json({
         status: "LIVE",
         vault: target,
         owner: config.owner,
         config,
-        nextSteps: [
-            `Set NEAR_VAULT_CONTRACT=${target} so every other tool reads this vault.`,
-            `vault_tree shows the budget; vault_budget shows what is left today.`,
-            `Nothing can spend from it until an agent is bound with a budget — vault_add_role.`,
-        ],
+        funding,
+        nextSteps,
     });
 });
 /**
@@ -907,32 +1015,103 @@ server.tool("vault_add_role", "Add a NEW departmental agent to an existing vault
         .describe("NEAR for the agent's gas key. Default 0.12 (~160 payments measured). Minimum 0.06, because NEAR reserves prepaid gas up front."),
 }, async ({ role, dailyCap, perTxCap, recipients, token, cooldownSec, fundingNear }) => {
     const vault = requireVault();
-    // REFUSE A DUPLICATE ROLE BEFORE GENERATING A KEY. The contract would
-    // happily create a second node with the same label, and the keyring would
-    // index only the last one — so the first agent would still be bound and
-    // funded on chain while becoming unreachable locally.
-    if (listRoles(cfg).some((r) => r.role === role)) {
-        return text(`This vault already has an agent with the role '${role}'. Roles index the ` +
-            `keyring, so a second one would hide the first — which would stay bound and ` +
-            `funded on chain with nothing able to select it. Pick another name, or use ` +
-            `the existing agent.`);
+    /**
+     * A DUPLICATE ROLE IS REFUSED — BUT "IN THE KEYRING" IS NOT "ALIVE".
+     *
+     * The contract would happily create a second node with the same label, and
+     * `selectRole` resolves with `find`, so the FIRST entry wins forever: the
+     * older agent would stay bound and funded on chain with nothing able to
+     * select it. That part of the old guard was right.
+     *
+     * What was wrong was treating a keyring entry as proof an agent exists. A
+     * `vault_add_role` that writes a key and then fails to land on chain leaves
+     * an ORPHAN — a role bound to nothing, no node, no gas key — and this guard
+     * then refused the user's own retry, citing the wreckage of the attempt
+     * that failed thirty seconds earlier. Reported 2026-11-13 for a `travel`
+     * agent; the user had to go and find the file by hand.
+     *
+     * So ask the CHAIN, which is the only thing that knows:
+     *   bound to a node -> a real agent. Refuse, as before.
+     *   not bound       -> an orphan. Retire it and carry on.
+     *   chain unreachable or no recorded key -> cannot tell. Refuse, and SAY
+     *                      it is a "cannot tell", not a "there is one".
+     */
+    let retired = null;
+    const clash = listAgents(cfg).find((a) => a.role === role);
+    if (clash) {
+        const boundNode = clash.publicKey
+            ? await viewFunction(cfg.rpcUrl, vault, "get_virtual_agent_node", {
+                public_key: clash.publicKey,
+            }).catch(() => undefined)
+            : undefined;
+        if (boundNode === undefined) {
+            return text(`There is already a key filed under the role '${role}' for this vault, and I could not ` +
+                `confirm with ${vault} whether it is a working agent — ` +
+                `${clash.publicKey ? "the network read failed" : "that entry predates recorded public keys"}. ` +
+                `Refusing rather than guessing: adding a second '${role}' would permanently hide ` +
+                `whichever was filed first, and if the existing one IS bound and funded, nothing ` +
+                `would be able to select it again. Try vault_roles to see the fleet, or pick ` +
+                `another name.`);
+        }
+        if (boundNode !== null) {
+            return text(`This vault already has a working agent with the role '${role}' — it is bound to ` +
+                `node ${boundNode}. A second one would hide it, and it would stay funded on chain ` +
+                `with nothing able to select it. Pick another name, or just use the existing agent.`);
+        }
+        /**
+         * ORPHAN. The chain says this key is bound to nothing, so it cannot be
+         * anyone's working agent. Its name is taken off it — the secret stays on
+         * disk, see `retireRole` — and the request proceeds, which is what the
+         * user asked for in the first place.
+         */
+        retired = retireRole({
+            keyringPath: cfg.agentKeysPath,
+            vault,
+            publicKey: clash.publicKey,
+        });
     }
+    /**
+     * VALIDATE EVERYTHING BEFORE A KEY TOUCHES DISK.
+     *
+     * This used to generate and WRITE the agent's key, and only then build the
+     * payload — which calls `tokenFor()` and the amount conversions, any of
+     * which can throw. So a call that failed validation left a real keypair
+     * filed under the role name, bound to nothing: no node, no gas key. The
+     * user's retry then hit "this vault already has an agent with the role
+     * 'travel'" and was blocked by the wreckage of their own failed attempt.
+     *
+     * Measured 2026-11-13: a `vault_add_role` that failed on a missing token
+     * wrote `travel` to the keyring 55 seconds before the retry was refused.
+     *
+     * Everything that can throw now runs FIRST, against a throwaway public key,
+     * so a failure writes nothing at all. The key is generated only once the
+     * payload is known to be buildable.
+     */
     const fundingYocto = toYoctoNear(fundingNear ?? "0.12");
-    // `nodeId: null` — NOT YET KNOWN. `add_role` creates the node inside the
-    // contract, so its id does not exist until the transaction lands.
+    let limits;
+    try {
+        limits = [{ token: tokenFor(token), dailyCap, perTxCap, decimals: cfg.decimals }];
+        // Build it once with a placeholder to force every conversion and check
+        // to run. Nothing is kept; this is a dry run for its exceptions.
+        planAddRole(vault, role, limits, cooldownSec ?? 0, recipients ?? null, PLACEHOLDER_PUBLIC_KEY, fundingYocto);
+    }
+    catch (e) {
+        return text(`${String(e.message)}${String.fromCharCode(10)}${String.fromCharCode(10)}` +
+            `Nothing was written — no key was generated, so '${role}' is still free to use once ` +
+            `this is corrected.`);
+    }
+    // Only now. `nodeId: null` — NOT YET KNOWN: `add_role` creates the node
+    // inside the contract, so its id does not exist until the transaction lands.
     const generated = generateAgentKey({
         vault,
-        dir: dirname(cfg.agentKeysPath),
+        // The FULL configured path, not its directory. Passing the directory
+        // discarded the filename, so a keyring pinned to anything other than
+        // `agent-keys.json` was read from one file and written to another.
+        keyringPath: cfg.agentKeysPath,
         role,
         nodeId: null,
     });
-    let payload;
-    try {
-        payload = planAddRole(vault, role, [{ token: tokenFor(token), dailyCap, perTxCap, decimals: cfg.decimals }], cooldownSec ?? 0, recipients ?? null, generated.publicKey, fundingYocto);
-    }
-    catch (e) {
-        return text(String(e.message));
-    }
+    const payload = planAddRole(vault, role, limits, cooldownSec ?? 0, recipients ?? null, generated.publicKey, fundingYocto);
     return json({
         role,
         agent: {
@@ -946,30 +1125,165 @@ server.tool("vault_add_role", "Add a NEW departmental agent to an existing vault
                 `credential is filed under the ROLE, so vault_pay({role:"${role}"}) works ` +
                 `without it.`,
         ],
+        // Only present when something was actually cleaned up, so the ordinary
+        // case stays quiet. An orphan silently replaced would be the same
+        // invisible-state problem in a new costume.
+        ...(retired
+            ? {
+                replaced: `A key was already filed under '${role}' but ${vault} reports it bound to ` +
+                    `nothing — a leftover from an earlier attempt that never landed on chain. It has ` +
+                    `been renamed '${retired.retiredTo}' so it cannot shadow this one. Its secret ` +
+                    `was NOT deleted.`,
+            }
+            : {}),
         warnings: [
             `Show the owner this public key and have them confirm it before signing: ${generated.publicKey}`,
             `The private key is at ${generated.keyringPath}. Do not print it.`,
+            // A second keyring holding keys for THIS vault means roles this server
+            // cannot see. Said here rather than left to surface later as "my agent
+            // vanished".
+            ...(KEYRING.alsoFound.length
+                ? [
+                    `Another keyring also holds keys for this vault and is NOT being read: ` +
+                        `${KEYRING.alsoFound.join(", ")}. This one was chosen. Set ` +
+                        `NEAR_VAULT_AGENT_KEYS to pin one deliberately.`,
+                ]
+                : []),
         ],
     });
 });
-server.tool("vault_roles", "List the agents this server can sign as, by role. Use it before vault_pay when a vault has more than one agent — the signing key decides which budget is charged. No key material is returned.", {}, async () => json(
-// `listAgents`, NOT `listRoles`. The latter filters to entries carrying a
-// role, which is correct for SELECTION and wrong for REPORTING: a
-// creation-time agent from `bindAgent` has no role, so a working vault
-// with a funded gas key reported `[]` — indistinguishable from having no
-// agent at all, and the obvious next move is then the wrong one.
-listAgents(cfg).map((r) => ({
-    role: r.role,
-    nodeId: r.nodeId,
-    agentId: r.agentId,
-    ...(r.role === null
-        ? {
-            note: "No role name — created by vault_create({bindAgent:true}), which does not " +
-                "name one. It can still sign; vault_pay selects it by nodeId or as the only " +
-                "credential. Give it a name with vault_add_role if you want several agents.",
+server.tool("vault_roles", "List the agents this server can sign as, CROSS-CHECKED against the vault. Says which keys are actually installed and which are dead. Use it before vault_pay when a vault has more than one agent — the signing key decides which budget is charged. No key material is returned.", {}, async () => {
+    const vault = requireVault();
+    /**
+     * THE KEYRING IS A CLAIM. THE CHAIN IS THE FACT.
+     *
+     * This used to report `listAgents(cfg)` verbatim — role, nodeId and all —
+     * straight out of the local file, without ever asking the vault whether it
+     * had heard of those keys. So a keyring pointing at the wrong directory
+     * reported a healthy, signable agent on node 1 that the vault had never
+     * been told about, and `vault_pay` then signed with it and came back
+     * NOT_VIRTUAL_AGENT.
+     *
+     * Measured 2026-11-13: that cost a user a whole session of forensics —
+     * reading .claude.json by hand, diffing two keyring files, checking gas
+     * balances — to find a single wrong path. The tool whose entire job is
+     * "which agents can I sign as" was the one reporting the false positive,
+     * which is why nothing caught it earlier.
+     *
+     * So every entry is now resolved against the vault:
+     *   get_virtual_agent_node(pk)  -> the node the CHAIN binds it to, or null
+     *   the access-key list         -> is a funded gas key actually installed
+     *
+     * And the INVERSE is reported too: a gas key on the vault that is not in
+     * the keyring is an agent you cannot sign as. Both directions of the
+     * disagreement matter, and only one of them was ever visible.
+     */
+    const local = listAgents(cfg);
+    const onChainKeys = await viewAccessKeys(cfg.rpcUrl, vault)
+        .then((ks) => ks
+        .map((k) => ({
+        publicKey: k.public_key,
+        gas: k.access_key?.permission?.GasKeyFunctionCall,
+    }))
+        .filter((k) => k.gas !== undefined))
+        .catch(() => null);
+    const resolved = await Promise.all(local.map(async (r) => {
+        if (!r.publicKey) {
+            return {
+                role: r.role,
+                agentId: r.agentId,
+                status: "UNVERIFIABLE",
+                detail: "This keyring entry has no public key recorded, so the chain cannot be asked " +
+                    "about it. It predates the field. Re-create the agent with vault_add_role.",
+            };
+        }
+        const node = await viewFunction(cfg.rpcUrl, vault, "get_virtual_agent_node", {
+            public_key: r.publicKey,
+        }).catch(() => undefined);
+        const installed = onChainKeys?.find((k) => k.publicKey === r.publicKey);
+        const balance = installed?.gas?.balance;
+        if (node === undefined) {
+            return { role: r.role, agentId: r.agentId, status: "UNKNOWN", detail: "could not reach the chain" };
         }
-        : {}),
-}))));
+        if (node === null) {
+            return {
+                role: r.role,
+                agentId: r.agentId,
+                publicKey: r.publicKey,
+                status: "DEAD",
+                detail: `This key is NOT bound on ${vault}. Signing with it returns NOT_VIRTUAL_AGENT. ` +
+                    `It is a key for a different vault, or left over from one that was torn down, or ` +
+                    `this client is reading the wrong keyring. Do NOT use it; vault_add_role creates ` +
+                    `one the vault will accept.`,
+            };
+        }
+        return {
+            role: r.role,
+            agentId: r.agentId,
+            nodeId: node,
+            // The LOCAL nodeId is reported only when it disagrees, because a
+            // disagreement means the file is stale and that is worth saying.
+            ...(r.nodeId !== undefined && r.nodeId !== node
+                ? { staleLocalNodeId: r.nodeId, note: "the keyring records a different node; the chain wins" }
+                : {}),
+            status: installed ? "USABLE" : "BOUND_BUT_NO_GAS_KEY",
+            gasNear: balance ? fromBaseUnits(BigInt(balance), 24) : null,
+            ...(installed
+                ? {}
+                : {
+                    detail: "Bound to a node, so it may AUTHORISE a payment, but no gas key is installed " +
+                        "on the vault, so it cannot SUBMIT one. float-agent installs and funds it.",
+                }),
+        };
+    }));
+    const heldKeys = new Set(local.map((r) => r.publicKey).filter(Boolean));
+    const unheld = (onChainKeys ?? [])
+        .filter((k) => !heldKeys.has(k.publicKey))
+        .map((k) => ({
+        publicKey: k.publicKey,
+        status: "ON_CHAIN_BUT_NO_LOCAL_KEY",
+        detail: "The vault has this agent installed, but this client does not hold its private key, " +
+            "so it cannot sign as it. It belongs to another machine or another client.",
+    }));
+    const unloadable = listUnloadable(cfg);
+    const usable = resolved.filter((r) => r.status === "USABLE").length;
+    return json({
+        vault,
+        usable,
+        /**
+         * WHICH FILE THIS ANSWER CAME FROM.
+         *
+         * Every status below is a claim about credentials in one specific file,
+         * and that file is CHOSEN (see `keyring-path.ts`) — so an answer that
+         * does not name it cannot be checked. Omitting it is what turned "my
+         * travel agent is missing" into a session of hand-diffing keyrings:
+         * the tool had the path and did not say it.
+         */
+        keyring: {
+            path: cfg.agentKeysPath,
+            chosenBecause: KEYRING.why,
+            ...(KEYRING.alsoFound.length
+                ? {
+                    NOT_being_read: KEYRING.alsoFound,
+                    warning: `Another keyring also holds keys for this vault. Agents filed there will NOT ` +
+                        `appear above. Set NEAR_VAULT_AGENT_KEYS to pin one deliberately.`,
+                }
+                : {}),
+        },
+        agents: resolved,
+        ...(unheld.length ? { onChainWithoutLocalKey: unheld } : {}),
+        // Entries the loader refuses to read. Reported rather than dropped, so
+        // "I have a key but this shows nothing" is answerable.
+        ...(unloadable.length ? { unreadableKeyringEntries: unloadable } : {}),
+        ...(usable === 0
+            ? {
+                warning: `NO USABLE AGENT. vault_pay cannot succeed against ${vault} from this client. ` +
+                    `Every entry above is dead, unbound, or missing its gas key — the commonest cause ` +
+                    `is NEAR_VAULT_AGENT_KEYS pointing at a keyring for a different vault.`,
+            }
+            : {}),
+    });
+});
 // ------------------------------------------------------------- onboarding
 server.tool("vault_create", "For a user who has NO vault yet. Works out where their vault will live, exactly what it costs to create, and returns a URL they approve in their own wallet. Needs no key and no existing vault — this is the only tool that works before NEAR_VAULT_CONTRACT is set. This server never signs it.", {
     owner: z

package/package.json

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