@floatonnear/mcp 0.6.4 → 0.9.0

package/dist/amounts.d.ts

@@ -18,3 +18,54 @@
 export declare function toBaseUnits(amount: string, decimals: number): bigint;
 /** Render base units as a canonical human string: no trailing point, no trailing zeroes. */
 export declare function fromBaseUnits(units: bigint, decimals: number): string;
+/**
+ * The contract speaks BASE UNITS; a person reading a budget does not.
+ *
+ * `get_tree` returns `daily_cap: "25000000"` for a 25 USDC cap, while
+ * `vault_budget` — reading the same number through `get_node_budget` — returns
+ * `"25"`. Two tools, one vault, one figure, two formats, and nothing said
+ * which was which. In a demo that reads as a bug even when both are correct,
+ * and `"25000000"` next to a `per_tx_cap` of `"10000000"` invites someone to
+ * conclude the caps are enormous.
+ *
+ * CONVERTED ONLY WHERE THE DECIMALS ARE KNOWN. Caps are stored PER TOKEN and a
+ * vault may hold limits for several, but this server knows the decimals of
+ * exactly one — `NEAR_VAULT_TOKEN_DECIMALS`, which describes
+ * `NEAR_VAULT_TOKEN`. Scaling some other token by 6 would print a number that
+ * is wrong by orders of magnitude while looking tidy, which is strictly worse
+ * than the raw figure it replaced. So a token we cannot vouch for keeps its
+ * base units and says so, rather than being guessed at.
+ *
+ * `decimals` is echoed on every converted entry so the base figure stays
+ * derivable; nothing is lost, it is only no longer the default reading.
+ */
+export interface TreeLimit {
+    token: string;
+    daily_cap: string;
+    per_tx_cap: string;
+}
+export interface TreeNode {
+    limits?: TreeLimit[];
+    child_cap_sum?: [string, string][];
+    [k: string]: unknown;
+}
+export declare function humaniseTreeNode(node: TreeNode, cfg: {
+    token?: string;
+    decimals: number;
+    /**
+     * Per-token metadata, when it could be read from the chain.
+     *
+     * THIS REMOVES THE CAVEAT THE FIRST VERSION SHIPPED WITH. It could only
+     * humanise the one token whose decimals the operator had configured;
+     * every other kept base units, because scaling by a guessed exponent
+     * prints a figure wrong by orders of magnitude while looking tidy. The
+     * chain knows the real answer, so the guess was never necessary.
+     *
+     * A token still absent from this map keeps base units — "could not read
+     * the metadata" is not a licence to assume six.
+     */
+    meta?: Map<string, {
+        symbol: string;
+        decimals: number;
+    } | null>;
+}): TreeNode;

package/dist/amounts.js

@@ -53,3 +53,58 @@ export function fromBaseUnits(units, decimals) {
     const frac = (units % scale).toString().padStart(decimals, "0").replace(/0+$/, "");
     return frac ? `${whole}.${frac}` : whole.toString();
 }
+export function humaniseTreeNode(node, cfg) {
+    if (!node || typeof node !== "object")
+        return node;
+    // Prefer what the CHAIN said; fall back to the configured token only.
+    const dp = (token) => {
+        const m = cfg.meta?.get(token);
+        if (m)
+            return m.decimals;
+        return cfg.token && token === cfg.token ? cfg.decimals : null;
+    };
+    const sym = (token) => cfg.meta?.get(token)?.symbol ?? null;
+    const human = (v, decimals) => {
+        // EXPLICIT SHAPE CHECK, because `BigInt("")` is `0n` rather than a throw —
+        // and `BigInt("  ")` is too. A try/catch alone therefore converted an
+        // empty or whitespace cap into "0", which is not a parse failure the
+        // reader can see: "0" is a meaningful budget, and the wrong one. Caught by
+        // its own test, which is the only reason this is not shipping.
+        if (typeof v !== "string" || !/^\d+$/.test(v))
+            return v;
+        try {
+            return fromBaseUnits(BigInt(v), decimals);
+        }
+        catch {
+            // Still guarded: fromBaseUnits rejects decimals outside its own range,
+            // and a figure the contract produced is a fact worth surfacing
+            // unchanged rather than an exception to swallow.
+            return v;
+        }
+    };
+    const limits = node.limits?.map((l) => {
+        const d = dp(l.token);
+        const symbol = sym(l.token);
+        if (d === null)
+            return { ...l, decimals: null, units: "base" };
+        return {
+            ...l,
+            // The SYMBOL beside the id, never instead of it: anyone can deploy a
+            // token calling itself USDC, and a cap that names only a symbol cannot
+            // be checked against the one the user meant.
+            ...(symbol ? { token_symbol: symbol } : {}),
+            daily_cap: human(l.daily_cap, d),
+            per_tx_cap: human(l.per_tx_cap, d),
+            decimals: d,
+        };
+    });
+    const childCapSum = node.child_cap_sum?.map(([token, amount]) => {
+        const d = dp(token);
+        return (d === null ? [token, amount] : [token, human(amount, d)]);
+    });
+    return {
+        ...node,
+        ...(limits ? { limits } : {}),
+        ...(childCapSum ? { child_cap_sum: childCapSum } : {}),
+    };
+}

package/dist/explain.d.ts

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

package/dist/explain.js

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

package/dist/roles.d.ts

@@ -8,6 +8,7 @@ export declare class RoleSelectionError extends Error {
 }
 export declare function selectRole(cfg: {
     agentKeysPath?: string;
+    vault?: string;
 }, role: string): {
     agentId: string;
     agentKey: string;
@@ -15,6 +16,7 @@ export declare function selectRole(cfg: {
 /** Every role that could actually sign, for listing back to a caller. */
 export declare function listRoles(cfg: {
     agentKeysPath?: string;
+    vault?: string;
 }): RoleCredential[];
 /**
  * EVERY credential in the keyring, named or not.
@@ -36,6 +38,7 @@ export declare function listRoles(cfg: {
  */
 export declare function listAgents(cfg: {
     agentKeysPath?: string;
+    vault?: string;
 }): {
     agentId: string;
     role: string | null;

package/dist/roles.js

@@ -29,11 +29,42 @@ function loadable(path) {
     // never be selected.
     return parsed.filter((e) => e && typeof e.agentId === "string" && typeof e.secret === "string");
 }
+/**
+ * Keyring entries belonging to THIS vault.
+ *
+ * A credential's `agentId` IS the vault account it was issued for. Nothing
+ * filtered on it, so every function here operated on the whole file — every
+ * vault the user has ever created, on either network.
+ *
+ * Measured 2026-11-10 against a mainnet vault: `vault_roles` listed
+ * `rudeisland4178-testnet.fac.floatv4.testnet` and
+ * `work12-testnet-fleet.fac.floatv4.testnet` as that vault's agents. Both are
+ * TESTNET accounts from earlier experiments, and neither has any relationship
+ * to the configured mainnet vault.
+ *
+ * `vault_roles` listing them is a display bug. `selectRole` was worse: asked
+ * for role "root" it would hand `vault_pay` the testnet fleet key to sign a
+ * MAINNET payment. That fails at the chain — the key is not on the vault — but
+ * the tool chose a credential from a different network and the error arrives
+ * with no hint of why.
+ *
+ * `vault` empty means nothing is configured, so there is nothing to scope to
+ * and every entry is returned. That is the `vault_create` case, where the
+ * server legitimately runs with no vault at all.
+ */
+function forVault(cfg) {
+    const entries = loadable(cfg.agentKeysPath ?? ".float/agent-keys.json");
+    if (!cfg.vault)
+        return entries;
+    return entries.filter((e) => e.agentId === cfg.vault);
+}
 export class RoleSelectionError extends Error {
 }
 export function selectRole(cfg, role) {
     const path = cfg.agentKeysPath ?? ".float/agent-keys.json";
-    const entries = loadable(path);
+    // SCOPED. A role name is not unique across vaults — "root" exists in every
+    // one — so an unscoped lookup picks whichever was written first.
+    const entries = forVault(cfg);
     const known = entries
         .map((e) => (typeof e.role === "string" ? e.role : null))
         .filter(Boolean);
@@ -50,7 +81,7 @@ export function selectRole(cfg, role) {
 }
 /** Every role that could actually sign, for listing back to a caller. */
 export function listRoles(cfg) {
-    return loadable(cfg.agentKeysPath ?? ".float/agent-keys.json")
+    return forVault(cfg)
         .filter((e) => typeof e.role === "string")
         .map((e) => ({
         agentId: e.agentId,
@@ -78,7 +109,7 @@ export function listRoles(cfg) {
  * name is genuinely absent and the fix is `vault_add_role`, not a guess.
  */
 export function listAgents(cfg) {
-    return loadable(cfg.agentKeysPath ?? ".float/agent-keys.json").map((e) => ({
+    return forVault(cfg).map((e) => ({
         agentId: e.agentId,
         role: typeof e.role === "string" ? e.role : null,
         nodeId: typeof e.nodeId === "number" ? e.nodeId : undefined,