@floatonnear/mcp 0.6.1 → 0.6.3

package/dist/agent-key.js

@@ -106,10 +106,15 @@ export function generateAgentKey(opts) {
     // because it holds ONE agent, while the keyring holds every agent — so the
     // keyring is the durable record and this is a convenience.
     writeFileSync(envPath, [
-        `# Written by vault_create. Contains a PRIVATE KEY — do not commit or paste.`,
+        `# Written by vault_create. Points at the keyring; holds NO key itself.`,
         `# The agent can only call request_payment on this vault, inside its budget.`,
         `NEAR_VAULT_AGENT_ID=${opts.vault}`,
-        `NEAR_VAULT_AGENT_KEY=${secret}`,
+        // A PATH, NOT THE SECRET. This file used to carry the key inline, so a
+        // `cat` to check which vault was configured printed a live private key
+        // into scrollback and into the driving agent's transcript. The keyring
+        // beside it is the durable record and `readKeyFile` now reads that shape,
+        // so naming it twice bought nothing except a second place to leak from.
+        `NEAR_VAULT_AGENT_KEY_FILE=${keyringPath}`,
         ``,
     ].join("\n"));
     // Best effort. Windows ignores POSIX modes, so this must not be load-bearing

package/dist/create.d.ts

@@ -35,7 +35,7 @@
  * clean failure: CreateAccount succeeds and the vault sits below its own
  * storage requirement, bricking on the first write.
  */
-export declare const CONTRACT_BYTES = 298920;
+export declare const CONTRACT_BYTES = 298839;
 /** NEAR charges 1e19 yoctoNEAR per byte of storage. */
 export declare const STORAGE_COST_PER_BYTE: bigint;
 /**
@@ -178,7 +178,51 @@ export interface CreatePlanInput {
      * anything is signed.
      */
     agentPk?: string | null;
+    /**
+     * The root node's caps and token, in HUMAN units — the answers to "how much
+     * per day?" and "how much per payment?".
+     *
+     * WHY THESE EXIST. The signing page has read `?daily=`, `?pertx=`, `?token=`
+     * and `?decimals=` since it was written, defaulting to 25/10 USDC on
+     * mainnet. This builder sent four params and never those, so an agent could
+     * not ask the user their budget and hand back a ready-to-sign link — which
+     * is the entire point of the flow. The page was finished; this side was not,
+     * and nothing compared the two lists.
+     *
+     * HUMAN UNITS, NOT BASE UNITS. The page scales by `decimals` itself —
+     * `units()` pads the fraction to DECIMALS digits — so base units passed here
+     * would be scaled a second time and turn a 100 USDC cap into 100 million.
+     */
+    daily?: string;
+    perTx?: string;
+    token?: string;
+    decimals?: number;
+    /**
+     * A vault label, which is PART OF THE ADDRESS.
+     *
+     * `resolve_vault` builds `{prefix}-{label}.{factory}`, so a labelled create
+     * does NOT land on the id `vault_id_for` returned. The page already knows
+     * this and appends the suffix before showing an address; this builder has to
+     * agree with it, or the user is told one address and gets another.
+     */
+    label?: string;
 }
+/**
+ * Refuse a cap the page would silently round, or the contract would reject.
+ *
+ * EVERY ONE OF THESE IS A POST-SIGNATURE FAILURE IF IT GETS THROUGH. These
+ * values go into a transaction the user approves, so a bad one is not a
+ * validation error they can correct — it is a panic after the deposit moved,
+ * or worse, a cap that is quietly not the number they agreed to.
+ */
+export declare function validateCaps(i: {
+    daily?: string;
+    perTx?: string;
+    decimals?: number;
+    token?: string;
+    label?: string;
+    factory: string;
+}): string[];
 export interface CreatePlan {
     owner: string | null;
     /** Null when the owner is unknown — the wallet decides it at signing time. */
@@ -194,6 +238,17 @@ export interface CreatePlan {
     url: string;
     warnings: string[];
     note: string;
+    /** What the agent should do after the user signs, instead of asking them. */
+    confirm: {
+        vault: string | null;
+        tool: string;
+        args: {
+            vault: string | null;
+            owner: string;
+            network: string;
+        } | null;
+        instruction: string;
+    };
 }
 /** yoctoNEAR -> a NEAR string, without floating point. */
 export declare function yoctoToNear(y: bigint, dp?: number): string;

package/dist/create.js

@@ -35,7 +35,7 @@
  * clean failure: CreateAccount succeeds and the vault sits below its own
  * storage requirement, bricking on the first write.
  */
-export const CONTRACT_BYTES = 298920;
+export const CONTRACT_BYTES = 298839;
 /** NEAR charges 1e19 yoctoNEAR per byte of storage. */
 export const STORAGE_COST_PER_BYTE = 10n ** 19n;
 /**
@@ -132,6 +132,73 @@ export const FACTORY_BY_NETWORK = {
     testnet: "fac.floatv4.testnet",
     mainnet: "usefloat.near",
 };
+/**
+ * Refuse a cap the page would silently round, or the contract would reject.
+ *
+ * EVERY ONE OF THESE IS A POST-SIGNATURE FAILURE IF IT GETS THROUGH. These
+ * values go into a transaction the user approves, so a bad one is not a
+ * validation error they can correct — it is a panic after the deposit moved,
+ * or worse, a cap that is quietly not the number they agreed to.
+ */
+export function validateCaps(i) {
+    const problems = [];
+    const dp = i.decimals ?? 6;
+    const numeric = /^\d+(\.\d+)?$/;
+    if (i.decimals !== undefined &&
+        (!Number.isInteger(i.decimals) || i.decimals < 0 || i.decimals > 24)) {
+        problems.push(`decimals must be an integer 0-24, got ${i.decimals}`);
+    }
+    for (const [name, v] of [
+        ["daily", i.daily],
+        ["perTx", i.perTx],
+    ]) {
+        if (v === undefined)
+            continue;
+        if (!numeric.test(v)) {
+            problems.push(`${name} must be a plain decimal in HUMAN units, e.g. "100" or "25", got "${v}"`);
+            continue;
+        }
+        if (Number(v) <= 0) {
+            problems.push(`${name} must be greater than 0 — a zero cap refuses every payment`);
+            continue;
+        }
+        // THE PAGE TRUNCATES; IT DOES NOT ROUND AND DOES NOT COMPLAIN. `units()`
+        // slices the fraction to `decimals` digits, so "2.0400001" against a
+        // 6-decimal token becomes 2.040000 and the user approves a cap that is not
+        // the one they were quoted. Never silently alter a number about money.
+        const frac = v.split(".")[1] ?? "";
+        if (frac.length > dp) {
+            problems.push(`${name} "${v}" has ${frac.length} decimal places but the token has ${dp}. ` +
+                `The signing page truncates rather than rounding, so the cap would silently ` +
+                `become "${v.split(".")[0]}.${frac.slice(0, dp)}".`);
+        }
+    }
+    if (i.daily && i.perTx && numeric.test(i.daily) && numeric.test(i.perTx)) {
+        if (Number(i.perTx) > Number(i.daily)) {
+            problems.push(`perTx (${i.perTx}) is larger than daily (${i.daily}), so the per-payment cap ` +
+                `can never bind — the daily cap refuses first. Probably swapped.`);
+        }
+    }
+    if (i.token !== undefined && !/^[a-z0-9._-]{2,64}$/.test(i.token)) {
+        problems.push(`token "${i.token}" is not a legal NEAR account id`);
+    }
+    if (i.label !== undefined) {
+        // The CONTRACT's rule, not a looser one, so a bad label is refused here
+        // rather than panicking BAD_LABEL after the user has paid.
+        if (!/^[a-z0-9]{1,16}$/.test(i.label)) {
+            problems.push(`label "${i.label}" must be 1-16 characters of a-z or 0-9`);
+        }
+        else if (i.label === i.factory.split(".").pop()) {
+            // Added to the factory on 2026-11-10: a label equal to the factory's own
+            // suffix rebuilds another account's derived id. The page predates that
+            // guard and does not know about it, so this is the only layer that can
+            // catch it before a signature.
+            problems.push(`label "${i.label}" is the factory's own suffix, which the factory refuses — ` +
+                `it would rebuild another account's derived vault id`);
+        }
+    }
+    return problems;
+}
 /** yoctoNEAR -> a NEAR string, without floating point. */
 export function yoctoToNear(y, dp = 5) {
     const neg = y < 0n;
@@ -209,6 +276,22 @@ export function buildCreatePlan(i) {
                 `headroom constant needs raising — this is an operator bug, not a funding problem.`,
         ]
         : [];
+    // REFUSE BEFORE BUILDING A LINK, not after. Returning a URL alongside a
+    // warning would still be a URL the agent hands over and the user signs.
+    const capProblems = validateCaps({
+        daily: i.daily,
+        perTx: i.perTx,
+        decimals: i.decimals,
+        token: i.token,
+        label: i.label,
+        factory: i.factory,
+    });
+    if (capProblems.length) {
+        throw new Error(`Refusing to build a signing link:\n  - ${capProblems.join("\n  - ")}\n\n` +
+            `These become part of a transaction the user approves, so a bad value is ` +
+            `not a correctable error — it is a panic after the deposit moved, or a cap ` +
+            `that is not the number they agreed to.`);
+    }
     const url = new URL(i.appUrl);
     if (known)
         url.searchParams.set("owner", i.owner);
@@ -216,6 +299,19 @@ export function buildCreatePlan(i) {
         url.searchParams.set("agent_pk", i.agentPk);
     url.searchParams.set("factory", i.factory);
     url.searchParams.set("network", i.network);
+    // The interview answers. Names are the PAGE's (`pertx`, not `perTx`) —
+    // `scripts/check-create-url-params.mjs` compares the two lists so a rename
+    // on either side cannot drift silently again.
+    if (i.daily !== undefined)
+        url.searchParams.set("daily", i.daily);
+    if (i.perTx !== undefined)
+        url.searchParams.set("pertx", i.perTx);
+    if (i.token !== undefined)
+        url.searchParams.set("token", i.token);
+    if (i.decimals !== undefined)
+        url.searchParams.set("decimals", String(i.decimals));
+    if (i.label !== undefined)
+        url.searchParams.set("label", i.label);
     const unknownOwnerWarnings = known
         ? []
         : [
@@ -224,9 +320,29 @@ export function buildCreatePlan(i) {
             `Nothing has checked whether you already have a vault. If you do, the page ` +
                 `will say so rather than creating a second one.`,
         ];
+    // THE LABEL IS PART OF THE ADDRESS, so the id the factory's view returned is
+    // not where a labelled create lands. `web/index.html:1282` does exactly this
+    // and says why: showing the unlabelled id while signing for the labelled one
+    // tells the user the wrong address.
+    //
+    // Derived by surgery on the VIEW's answer rather than by reimplementing
+    // `derive_prefix` — this file states that the derivation is not duplicated
+    // here, and a second copy of it is how the two would disagree. `vault_id`
+    // builds `{prefix}.{factory}`, so stripping the known factory suffix leaves
+    // exactly the prefix. Asserted rather than assumed, because a `vaultId` that
+    // did not end in the factory would silently produce a nonsense address.
+    let vault = known ? i.vaultId : null;
+    if (vault && i.label !== undefined) {
+        const suffix = `.${i.factory}`;
+        if (!vault.endsWith(suffix)) {
+            throw new Error(`vaultId "${vault}" does not end in ".${i.factory}", so the label suffix ` +
+                `cannot be placed. Refusing to guess an address next to a real deposit.`);
+        }
+        vault = `${vault.slice(0, -suffix.length)}-${i.label}${suffix}`;
+    }
     return {
         owner: known ? i.owner : null,
-        vault: known ? i.vaultId : null,
+        vault,
         factory: i.factory,
         network: i.network,
         depositYocto: deposit.toString(),
@@ -250,5 +366,42 @@ export function buildCreatePlan(i) {
         note: `This server never sees or holds a key. Open the URL and approve the ` +
             `transaction in your own wallet; the contract travels as an argument to ` +
             `one ordinary function call, and the factory deploys it for you.`,
+        /**
+         * WHAT THE AGENT DOES NEXT, so it stops asking the user to read an address
+         * back to it.
+         *
+         * The derived id is known BEFORE anything is signed, so "did it work?" is a
+         * question this server can answer by looking at the chain. It used to end
+         * at "approve it in your wallet", which left the human relaying an account
+         * id the agent already had — the clunkiest step in the flow and a pure
+         * documentation gap, not a technical limit.
+         *
+         * OWNERSHIP IS A SEPARATE CHECK FROM EXISTENCE, and that is the whole
+         * reason this names a method rather than saying "poll until it appears".
+         * `derive_prefix` is not injective, so an account AT the derived id is not
+         * proof the vault is the user's: `vault_await_create` reads `get_config`
+         * back and compares `owner`. Three outcomes, never two — mine, someone
+         * else's, or could-not-read.
+         */
+        confirm: known
+            ? {
+                vault,
+                tool: "vault_await_create",
+                args: { vault, owner: i.owner, network: i.network },
+                instruction: `Do NOT ask the user to paste the vault id back — you already have it. ` +
+                    `After they say they have signed, call \`vault_await_create\` with the ` +
+                    `arguments above. It polls for the account and verifies \`get_config.owner\` ` +
+                    `is ${i.owner}, because an account existing at a derived id is not proof it ` +
+                    `belongs to them.`,
+            }
+            : {
+                vault: null,
+                tool: "vault_await_create",
+                args: null,
+                instruction: `The address depends on which wallet connects, so it is not known yet. ` +
+                    `Ask the user for their account id once they have signed, then call ` +
+                    `\`vault_await_create\` with it — or call \`vault_create\` again with ` +
+                    `\`owner\` set to get the address up front.`,
+            },
     };
 }

package/dist/gas-math.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Gas-key arithmetic, mirrored from `create-float`'s `bin/gas-key.mjs`.
+ *
+ * WHY A MIRROR AND NOT AN IMPORT. `@floatonnear/create-float` does not depend
+ * on `@floatonnear/mcp` and vice versa — they are siblings, published
+ * separately, and installed independently by users. Adding a dependency in
+ * either direction to share four lines of arithmetic would couple two release
+ * cycles, and this repo has already lost an afternoon to a workspace range
+ * that silently resolved to a PUBLISHED sibling instead of the local one.
+ *
+ * So it is duplicated DELIBERATELY, following the pattern already used for
+ * `shared/contract-constants.json`: mirror the values, then make drift fail a
+ * check. `scripts/check-gas-math.mjs` compares these constants against
+ * create-float's and fails the gate if they diverge. A silent divergence here
+ * would quote a user one number and charge them another.
+ *
+ * Every figure is a measurement; see gas-key.mjs for the provenance.
+ */
+/**
+ * What NEAR holds for one in-flight call: `prepaid_gas x 1e9`, refunded a
+ * receipt later. It is ~350x the real burn, so a key funded by expected cost
+ * alone fails every call with NotEnoughBalance.
+ */
+export declare const gasReservation: (tgas: number) => bigint;
+/** The real cost of one `request_payment`, rounded up from measurement. */
+export declare const PAYMENT_BURN: bigint;
+/** The vault's MIN_GAS_FOR_DISPATCH. Below it a call is refused before anything happens. */
+export declare const MIN_TGAS = 50;
+/**
+ * What to ADD so the key can make `payments` MORE calls.
+ *
+ * The reservation is charged once for the key's life, not once per top-up, so
+ * this is NOT reservation + burn x payments — that would overcharge by a full
+ * reservation every time. A depleted key (below the reservation, unable to
+ * transact at all) is lifted back over that line first.
+ */
+export declare function topUpFor({ balance, tgas, payments, }?: {
+    balance?: bigint;
+    tgas?: number;
+    payments?: number;
+}): bigint;
+/**
+ * The inverse: TOTAL payments possible once `amount` is added.
+ *
+ * ZERO IS A REAL ANSWER. A key that still cannot cover one reservation makes
+ * NO calls, not "a few" — every call fails NotEnoughBalance, which reads as a
+ * broken agent rather than an underfunded one.
+ */
+export declare function paymentsAfterTopUp({ balance, tgas, amount, }?: {
+    balance?: bigint;
+    tgas?: number;
+    amount?: bigint;
+}): number;

package/dist/gas-math.js

@@ -0,0 +1,61 @@
+/**
+ * Gas-key arithmetic, mirrored from `create-float`'s `bin/gas-key.mjs`.
+ *
+ * WHY A MIRROR AND NOT AN IMPORT. `@floatonnear/create-float` does not depend
+ * on `@floatonnear/mcp` and vice versa — they are siblings, published
+ * separately, and installed independently by users. Adding a dependency in
+ * either direction to share four lines of arithmetic would couple two release
+ * cycles, and this repo has already lost an afternoon to a workspace range
+ * that silently resolved to a PUBLISHED sibling instead of the local one.
+ *
+ * So it is duplicated DELIBERATELY, following the pattern already used for
+ * `shared/contract-constants.json`: mirror the values, then make drift fail a
+ * check. `scripts/check-gas-math.mjs` compares these constants against
+ * create-float's and fails the gate if they diverge. A silent divergence here
+ * would quote a user one number and charge them another.
+ *
+ * Every figure is a measurement; see gas-key.mjs for the provenance.
+ */
+/**
+ * What NEAR holds for one in-flight call: `prepaid_gas x 1e9`, refunded a
+ * receipt later. It is ~350x the real burn, so a key funded by expected cost
+ * alone fails every call with NotEnoughBalance.
+ */
+export const gasReservation = (tgas) => BigInt(tgas) * 10n ** 12n * 10n ** 9n;
+/** The real cost of one `request_payment`, rounded up from measurement. */
+export const PAYMENT_BURN = 12n * 10n ** 20n;
+/** The vault's MIN_GAS_FOR_DISPATCH. Below it a call is refused before anything happens. */
+export const MIN_TGAS = 50;
+/**
+ * What to ADD so the key can make `payments` MORE calls.
+ *
+ * The reservation is charged once for the key's life, not once per top-up, so
+ * this is NOT reservation + burn x payments — that would overcharge by a full
+ * reservation every time. A depleted key (below the reservation, unable to
+ * transact at all) is lifted back over that line first.
+ */
+export function topUpFor({ balance = 0n, tgas = 60, payments = 50, } = {}) {
+    if (tgas < MIN_TGAS)
+        throw new Error(`tgas must be at least ${MIN_TGAS}`);
+    if (payments < 0)
+        throw new Error("payments cannot be negative");
+    const have = BigInt(balance);
+    const reservation = gasReservation(tgas);
+    const shortfall = have >= reservation ? 0n : reservation - have;
+    return shortfall + PAYMENT_BURN * BigInt(payments);
+}
+/**
+ * The inverse: TOTAL payments possible once `amount` is added.
+ *
+ * ZERO IS A REAL ANSWER. A key that still cannot cover one reservation makes
+ * NO calls, not "a few" — every call fails NotEnoughBalance, which reads as a
+ * broken agent rather than an underfunded one.
+ */
+export function paymentsAfterTopUp({ balance = 0n, tgas = 60, amount = 0n, } = {}) {
+    if (tgas < MIN_TGAS)
+        throw new Error(`tgas must be at least ${MIN_TGAS}`);
+    const spendable = BigInt(balance) + BigInt(amount) - gasReservation(tgas);
+    if (spendable <= 0n)
+        return 0;
+    return Number(spendable / PAYMENT_BURN);
+}

package/dist/key-file.js

@@ -150,7 +150,65 @@ function fromJson(text, path) {
         throw new KeyFileError(`key file ${path} is not valid JSON. Expected the ~/.near-credentials shape ` +
             `${CRED_SHAPE}, or a bare key on one line.`);
     }
-    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    /**
+     * THE FLEET KEYRING IS A LEGITIMATE SHAPE, and accepting it is what lets the
+     * provisioning path stop writing a second copy of the secret.
+     *
+     * `.float/agent-keys.json` is an ARRAY of
+     * `{kind, vault, node, publicKey, privateKey}` — the durable record of every
+     * agent, written by create-float and by vault_create. Before this, pointing
+     * NEAR_VAULT_AGENT_KEY_FILE at it was refused as "the wrong shape", so the
+     * only way to configure an agent was the INLINE form: the secret pasted into
+     * .mcp.json and .float/adapter.env, where reading a config to answer "which
+     * vault is this?" prints a live private key into scrollback and into the
+     * driving agent's transcript. That exposure is realised, not theoretical.
+     *
+     * The alternative was writing a THIRD file in the credentials shape, which
+     * would duplicate the secret into one more place — more exposure, not less.
+     *
+     * AMBIGUITY IS REFUSED, NOT GUESSED. A keyring with several agents has no
+     * single answer to "which key", and picking the first would sign as an agent
+     * the operator did not choose — from the wrong node, against the wrong
+     * budget. They are told to name one with NEAR_VAULT_AGENT_ID instead.
+     */
+    if (Array.isArray(parsed)) {
+        /**
+         * TWO FIELD SPELLINGS EXIST, and assuming one cost a round of this change.
+         *
+         * `loadKeyring` documents the canonical entry as
+         * `{ nodeId, agentId, secret }` and `generateAgentKey` writes exactly
+         * that. But a keyring on this machine, written by an older path, uses
+         * `{ kind, vault, node, publicKey, privateKey }`. Both are real files an
+         * operator may point this at, so both are read — and a refusal names the
+         * keys it DID find, because "wrong shape" without the field names sends
+         * someone to re-read a file they already have open.
+         */
+        const entries = parsed.filter((e) => e !== null && typeof e === "object");
+        const secretOf = (e) => typeof e.secret === "string" && e.secret
+            ? e.secret
+            : typeof e.privateKey === "string" && e.privateKey
+                ? e.privateKey
+                : "";
+        const idOf = (e) => typeof e.agentId === "string" ? e.agentId : typeof e.vault === "string" ? e.vault : undefined;
+        const withKeys = entries.filter((e) => secretOf(e) !== "");
+        if (withKeys.length === 0) {
+            const found = [...new Set(entries.flatMap((e) => Object.keys(e)))].join(", ") || "none";
+            throw new KeyFileError(`key file ${path} is a JSON array but no entry carries a key. Expected a fleet ` +
+                `keyring entry with \`secret\` (or \`privateKey\`); the fields present were: ${found}.`);
+        }
+        if (withKeys.length > 1) {
+            // COUNT AND LABELS ONLY, never a key. The labels are the whole fix.
+            const names = withKeys
+                .map((e) => `${idOf(e) ?? "?"}#${String(e.nodeId ?? e.node ?? "?")}`)
+                .join(", ");
+            throw new KeyFileError(`key file ${path} holds ${withKeys.length} agent keys (${names}), so which one to ` +
+                `sign as is ambiguous. Set NEAR_VAULT_AGENT_ID to name one, or point ` +
+                `NEAR_VAULT_AGENT_KEY_FILE at a single-key file.`);
+        }
+        const only = withKeys[0];
+        return { secret: secretOf(only).trim(), accountId: idOf(only) };
+    }
+    if (parsed === null || typeof parsed !== "object") {
         throw new KeyFileError(`key file ${path} is JSON but not an object. Expected the ~/.near-credentials ` +
             `shape ${CRED_SHAPE}.`);
     }

package/dist/server.d.ts

@@ -38,7 +38,8 @@
  *                              exists on purpose — guessing it wrong would
  *                              send a real deposit somewhere unverified.
  *   NEAR_VAULT_APP_URL         only needed to CREATE, default
- *                              https://app.usefloat.xyz
+ *                              https://usefloat.xyz (the APEX — `app.` is the
+ *                              dashboard and has no create flow)
  *
  * A user with NO vault can therefore run this server with nothing configured,
  * call `vault_create`, and be onboarded — which is the point. Every other tool

package/dist/server.js

@@ -38,13 +38,15 @@
  *                              exists on purpose — guessing it wrong would
  *                              send a real deposit somewhere unverified.
  *   NEAR_VAULT_APP_URL         only needed to CREATE, default
- *                              https://app.usefloat.xyz
+ *                              https://usefloat.xyz (the APEX — `app.` is the
+ *                              dashboard and has no create flow)
  *
  * A user with NO vault can therefore run this server with nothing configured,
  * call `vault_create`, and be onboarded — which is the point. Every other tool
  * reports that NEAR_VAULT_CONTRACT is unset rather than guessing one.
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { topUpFor, paymentsAfterTopUp } from "./gas-math.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { fromBaseUnits, toBaseUnits } from "./amounts.js";
@@ -128,7 +130,23 @@ const cfg = {
     // Onboarding only. Both have safe defaults and neither is needed by any
     // tool that touches an existing vault.
     factory: process.env.NEAR_VAULT_FACTORY,
-    appUrl: process.env.NEAR_VAULT_APP_URL ?? "https://app.usefloat.xyz",
+    // The APEX, where the create page actually lives — one hop instead of two.
+    //
+    // `app.` ALSO WORKS AND IS NOT A BUG. It serves the Next.js dashboard, but
+    // nginx bounces anything carrying `?factory=` to the apex signing page, and
+    // `buildCreatePlan` sets `factory` on every link unconditionally. That rule
+    // exists because the published @floatonnear/mcp 0.5.0 hardcodes `app.`, and
+    // breaking it would break vault creation for every existing install.
+    // Verified 2026-11-10: `app.usefloat.xyz/?factory=…` → 200 at
+    // `usefloat.xyz`, "Create your Float vault".
+    //
+    // So this is a small simplification, NOT a repair — an earlier version of
+    // this comment claimed users were landing on the dashboard, which came from
+    // probing the bare URL that nothing emits.
+    //
+    // 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.
@@ -218,7 +236,7 @@ WORKFLOW
   2. Look before acting: vault_tree shows the budget shape, vault_budget what is left today.
   3. Pay with vault_pay. Check the result: a refusal is a recorded outcome, not an exception.
   4. Change policy with a vault_plan_* tool, then hand the payload to the user to sign.
-  5. Winding down is a CLI job, not a tool: npx @floatonnear/float-exit. It returns the tokens,
+  5. Winding down is a CLI job, not a tool: npx -p @floatonnear/create-float float-exit. It returns the tokens,
      the gas-key balances and the storage deposit. vault_teardown_report says what is recoverable.
 
 REFUSALS ARE ANSWERS. Report the reason code, do not retry blindly:
@@ -233,8 +251,100 @@ 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.6.1" }, { instructions: INSTRUCTIONS });
+const server = new McpServer({ name: "float", version: "0.6.3" }, { instructions: INSTRUCTIONS });
 // ----------------------------------------------------------------- reads
+/**
+ * Wait for a create to land, and prove the result belongs to the user.
+ *
+ * WHY A TOOL AND NOT A SENTENCE IN THE NOTE. `vault_create` knows the derived
+ * address before anything is signed, so "did it work?" is answerable from the
+ * chain — yet the flow used to end at "approve it in your wallet", leaving the
+ * human to read an account id back to an agent that already had it. That was
+ * the clunkiest step in onboarding and it was a documentation gap, not a
+ * technical limit.
+ *
+ * EXISTENCE IS NOT OWNERSHIP, and conflating them is the actual hazard here.
+ * `derive_prefix` is not injective — `a.b.near` and `a-b.near` land on the same
+ * id — so an account AT the derived address may belong to whoever created
+ * first. Reporting "your vault is live" on existence alone would point a user's
+ * agent at a stranger's money. So this reads `get_config` back and compares
+ * `owner`, and reports THREE outcomes, never two: yours, someone else's, or
+ * could-not-read. "I could not check" is not "it is yours".
+ *
+ * Polls rather than asking once, because a `final`-finality read immediately
+ * after a write can be a whole transaction behind.
+ */
+server.tool("vault_await_create", "After the user signs the create link, confirm the vault is live and VERIFY IT IS THEIRS. Reads the chain, so it needs no key. Call this instead of asking the user to paste their vault id back — vault_create already told you the address.", {
+    vault: z.string().describe("the derived vault id, from vault_create's `confirm.vault`"),
+    owner: z.string().describe("who it must belong to — compared against the vault's own get_config.owner"),
+    network: z.enum(["mainnet", "testnet"]).optional(),
+    timeoutSeconds: z
+        .number()
+        .int()
+        .min(1)
+        .max(300)
+        .optional()
+        .describe("how long to wait for the account to appear, default 90"),
+}, async ({ vault, owner, network, timeoutSeconds }) => {
+    const net = network ?? cfg.network;
+    const rpc = rpcForNetwork(net, {
+        configuredNetwork: cfg.network,
+        override: process.env.NEAR_VAULT_RPC_URL,
+    });
+    const deadline = Date.now() + (timeoutSeconds ?? 90) * 1000;
+    let appeared = false;
+    for (;;) {
+        if (await accountExists(rpc, vault).catch(() => false)) {
+            appeared = true;
+            break;
+        }
+        if (Date.now() >= deadline)
+            break;
+        await new Promise((r) => setTimeout(r, 3000));
+    }
+    if (!appeared) {
+        return json({
+            status: "NOT_YET",
+            vault,
+            instruction: `${vault} does not exist yet. That is not a failure — the user may not have ` +
+                `signed, or may have cancelled. Ask whether they approved it, and call this ` +
+                `again. Do NOT tell them the vault is created.`,
+        });
+    }
+    // THE OWNER READ IS THE POINT. Getting here only proves an account exists.
+    const config = await viewFunction(rpc, vault, "get_config", {}).catch(() => null);
+    if (!config || typeof config.owner !== "string") {
+        return json({
+            status: "UNVERIFIED",
+            vault,
+            instruction: `${vault} exists but its get_config could not be read, so whether it is ${owner}'s ` +
+                `is UNKNOWN — not assumed. It may not be a Float vault at all. Do not point an ` +
+                `agent at it until this is resolved: near view ${vault} get_config`,
+        });
+    }
+    if (config.owner !== owner) {
+        return json({
+            status: "NOT_YOURS",
+            vault,
+            actualOwner: config.owner,
+            instruction: `${vault} exists but is owned by ${config.owner}, NOT ${owner}. The vault id ` +
+                `derivation is not injective, so a different account can hold this address — ` +
+                `whoever created it first. Do NOT configure anything against it. Create one ` +
+                `under a label instead, which lands on a different address.`,
+        });
+    }
+    return json({
+        status: "LIVE",
+        vault,
+        owner: config.owner,
+        config,
+        nextSteps: [
+            `Set NEAR_VAULT_CONTRACT=${vault} 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.`,
+        ],
+    });
+});
 server.tool("vault_tree", "Read the whole budget tree: every node, its caps, parent, bound agent account, cooldown and freeze state. No key required.", {}, async () => json(await viewFunction(cfg.rpcUrl, requireVault(), "get_tree", {})));
 server.tool("vault_budget", "Read one node's budget for a UTC day: cap, executed, in-flight (pending) and available, in human units. Omit `day` for today. No key required.", {
     nodeId: z.number().int().min(0),
@@ -341,7 +451,30 @@ server.tool("vault_create", "For a user who has NO vault yet. Works out where th
         .boolean()
         .optional()
         .describe("generate an agent key and bind it in the SAME transaction, so one signature creates the vault and authorises you. Adds 0.12 NEAR of gas-key funding to the deposit. The user is shown the public key and must confirm it before signing. Requires `owner`, because the credential is filed under the vault id and that cannot be derived without one."),
-}, async ({ owner, network, factory, bindAgent }) => {
+    daily: z
+        .string()
+        .optional()
+        .describe("The root budget per UTC day, in HUMAN units of the token, e.g. \"25\" or \"100\" — not base units. PROPOSE a figure rather than interrogating the user; caps are changeable later with a signed vault_plan_set_caps. Page default when omitted: 25 (mainnet) / 100 (testnet)."),
+    perTx: z
+        .string()
+        .optional()
+        .describe("Maximum per single payment, HUMAN units. Must be <= daily or it can never bind, and must EXCEED the largest payment intended — cross-chain is EXACT_OUTPUT, so the vault is charged more than the payee receives and a cap of 5 refuses a round 5.00. Page default when omitted: 10 (mainnet) / 10 (testnet)."),
+    token: z
+        .string()
+        .optional()
+        .describe("the NEP-141 token the caps are denominated in. Defaults per network (USDC on mainnet). Caps are keyed PER TOKEN, so a wrong id silently gives the agent no budget for the token it actually pays in."),
+    decimals: z
+        .number()
+        .int()
+        .min(0)
+        .max(24)
+        .optional()
+        .describe("the token's decimals, default 6. Wrong here scales every cap by a power of ten."),
+    label: z
+        .string()
+        .optional()
+        .describe("optional vault label, 1-16 chars of a-z0-9. IT BECOMES PART OF THE ADDRESS (<prefix>-<label>.<factory>), so pass it only if the user wants a second vault or a specific name."),
+}, async ({ owner, network, factory, bindAgent, daily, perTx, token, decimals, label }) => {
     const net = network ?? cfg.network;
     const fac = factory ?? cfg.factory ?? FACTORY_BY_NETWORK[net];
     if (!fac) {
@@ -423,6 +556,15 @@ server.tool("vault_create", "For a user who has NO vault yet. Works out where th
             exists,
             existingOwner,
             agentPk: generated?.publicKey ?? null,
+            // The interview answers, forwarded verbatim. Undefined stays undefined
+            // so the PAGE's own defaults apply — substituting a default here would
+            // mean two places deciding the same number, which is how the deposit
+            // quote came to disagree with the page by 0.26 NEAR.
+            daily,
+            perTx,
+            token,
+            decimals,
+            label,
         });
         return json({
             ...plan,
@@ -621,6 +763,99 @@ server.tool("vault_plan_withdraw", "Build an UNSIGNED payload to move tokens OUT
     }
     return renderPlan(planWithdraw(vault, tok, base, receiverId, cfg.decimals));
 });
+/**
+ * WHY A QUOTE AND NOT A PLAN, which every other owner action here is.
+ *
+ * The rest of `vault_plan_*` returns an UNSIGNED payload the user approves in
+ * their own wallet. A top-up cannot work that way: `transferToGasKey` is an
+ * action on the VAULT account, so it needs a full-access key OF the vault —
+ * and wallets IGNORE `signerId`, silently signing as the connected account and
+ * returning SUCCESS while doing the wrong thing. Measured 2026-11-07 across
+ * Meteor, Intear and the CLI connector alike.
+ *
+ * So this takes the shape `vault_teardown_report` already uses: read the
+ * chain, do the arithmetic, hand over the exact command. The half an agent CAN
+ * serve is the part a human cannot do in their head — which agent is low, what
+ * a given amount buys, what a given payment count costs.
+ */
+server.tool("vault_gas", "Read-only. How much gas each agent has left, and what topping one up would cost or buy. Needs no key and signs nothing. Use for 'is my agent about to run out?' and 'top up the marketing agent' — it returns the exact command, because a top-up must be signed BY THE VAULT and a browser wallet cannot do that.", {
+    agent: z
+        .string()
+        .optional()
+        .describe("a gas key's public key, or a node label like 'marketing'. Omit to list every agent."),
+    payments: z.number().int().positive().optional().describe("quote the cost of this many MORE payments"),
+    amountNear: z.string().optional().describe("or quote how many payments this much NEAR would buy"),
+    tgas: z.number().int().optional().describe("gas per call (default 60, floor 50)"),
+}, async ({ agent, payments, amountNear, tgas }) => {
+    const vault = requireVault();
+    const TG = tgas ?? 60;
+    const keyList = await viewAccessKeys(cfg.rpcUrl, vault);
+    const tree = await viewFunction(cfg.rpcUrl, vault, "get_tree", {}).catch(() => []);
+    // KEY -> NODE -> LABEL, so "top up marketing" can find the right key. The
+    // vault identifies an agent BY ITS PUBLIC KEY (`pubkey_to_node`), which is
+    // why each agent has its own: one shared key would be one node, and the
+    // per-agent budgets would collapse into a single shared one.
+    const rows = [];
+    for (const k of keyList) {
+        const gk = k.access_key?.permission
+            ?.GasKeyFunctionCall;
+        if (!gk)
+            continue;
+        const node = await viewFunction(cfg.rpcUrl, vault, "get_virtual_agent_node", {
+            public_key: k.public_key,
+        }).catch(() => null);
+        rows.push({
+            publicKey: k.public_key,
+            nodeId: node,
+            label: tree.find((t) => t.id === node)?.label ?? (node === 0 ? "root" : null),
+            balanceNear: fromBaseUnits(BigInt(gk.balance), 24),
+            paymentsLeft: paymentsAfterTopUp({ balance: BigInt(gk.balance), tgas: TG, amount: 0n }),
+        });
+    }
+    if (rows.length === 0) {
+        return json({
+            vault,
+            agents: [],
+            note: "No gas keys on this vault, so no agent can transact. Add one with: npx -p @floatonnear/create-float float-agent",
+        });
+    }
+    const picked = agent ? rows.find((r) => r.publicKey === agent || r.label === agent) : undefined;
+    if (agent && !picked) {
+        // NOT a silent fallback to the first agent. Quoting against the wrong
+        // key prices a top-up for an agent the user did not name.
+        return json({
+            vault,
+            error: "NO_SUCH_AGENT",
+            asked: agent,
+            agents: rows,
+            note: "No gas key matches that public key or node label.",
+        });
+    }
+    if (!picked)
+        return json({ vault, tgas: TG, agents: rows });
+    const bal = BigInt(keyList.find((k) => k.public_key === picked.publicKey).access_key
+        .permission.GasKeyFunctionCall.balance);
+    const add = amountNear
+        ? toBaseUnits(amountNear, 24)
+        : topUpFor({ balance: bal, tgas: TG, payments: payments ?? 50 });
+    const after = paymentsAfterTopUp({ balance: bal, tgas: TG, amount: add });
+    return json({
+        vault,
+        agent: picked,
+        quote: {
+            addNear: fromBaseUnits(add, 24),
+            paymentsBefore: picked.paymentsLeft,
+            paymentsAfter: after,
+            gained: after - picked.paymentsLeft,
+        },
+        command: `npx -p @floatonnear/create-float float-topup --vault ${vault} --owner <YOUR-OWNER-ACCOUNT> ` +
+            `--agent ${picked.publicKey} ` +
+            `${amountNear ? `--amount ${amountNear}` : `--payments ${payments ?? 50}`} ` +
+            `--network ${cfg.network}`,
+        note: "A top-up is signed BY THE VAULT, so a browser wallet cannot do it — wallets ignore " +
+            "signerId and sign as the connected account. Run the command with the owner's key on disk.",
+    });
+});
 server.tool("vault_teardown_report", "Read-only. Report exactly what closing this vault would return, what it would strand, and the command that does it. Needs no key and signs nothing. Use this to answer 'can I close this vault and what do I get back?' before anyone exports anything.", {}, async () => {
     const vault = requireVault();
     const tok = cfg.token;

package/package.json

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