@floatonnear/mcp 0.2.0 → 0.4.0

package/dist/payloads.js

@@ -11,12 +11,27 @@
  * too, but failing locally costs no gas and no wallet round-trip, and the
  * message can explain *why* a bound exists.
  */
-import { toBaseUnits, fromBaseUnits } from "./amounts.js";
+import { toBaseUnits } from "./amounts.js";
+/** A node id must be a non-negative integer; there is no node -1. */
+function assertNodeId(nodeId) {
+    if (!Number.isInteger(nodeId) || nodeId < 0) {
+        throw new Error(`node id must be a non-negative integer, got ${nodeId}`);
+    }
+}
+/**
+ * Shape-check a public key before it reaches a wallet.
+ *
+ * Deliberately not a full base58 decode — the contract does that and rejects
+ * a malformed key. This catches the empty string and the obvious typo locally,
+ * where it costs nothing instead of a wallet round-trip.
+ */
+function assertPublicKey(publicKey) {
+    if (!/^(ed25519|secp256k1):[1-9A-HJ-NP-Za-km-z]{32,}$/.test(publicKey)) {
+        throw new Error(`not a public key: ${JSON.stringify(publicKey)}. ` +
+            `Expected "ed25519:<base58>" or "secp256k1:<base58>".`);
+    }
+}
 export const ONE_YOCTO = "1";
-/** Mirrors `AGENT_ACCOUNT_STORAGE` in the contract: 0.05 NEAR. */
-export const AGENT_ACCOUNT_STORAGE_YOCTO = (5n * 10n ** 22n).toString();
-/** Mirrors `MIN_AGENT_KEY_ALLOWANCE` in the contract: 0.5 NEAR. */
-export const MIN_AGENT_KEY_ALLOWANCE_YOCTO = (5n * 10n ** 23n).toString();
 /**
  * Gas attached to a payment, for every route.
  *
@@ -33,7 +48,6 @@ export const DEFAULT_GAS_TGAS = 100;
 export const MAX_TOKENS = 4;
 export const MAX_RECIPIENTS = 32;
 export const MAX_LABEL_LEN = 48;
-export const MAX_SUB_LABEL_LEN = 32;
 export const MAX_COOLDOWN_SEC = 7 * 24 * 60 * 60;
 export const MAX_PURGE_LIMIT = 100;
 const NEAR_DECIMALS = 24;
@@ -70,7 +84,6 @@ function describeLimits(limits) {
         .map((l) => `${l.token}: ${l.dailyCap}/day, max ${l.perTxCap}/payment`)
         .join("; ");
 }
-const SUB_LABEL = new RegExp(`^[a-z0-9_-]{1,${MAX_SUB_LABEL_LEN}}$`);
 function assertRecipients(recipients) {
     if (recipients === null)
         return;
@@ -138,47 +151,118 @@ export function planBindAgent(vault, nodeId, accountId) {
         summary: `Let ${accountId} spend from node ${nodeId}`,
         warnings: [
             `${accountId} is an EXISTING account whose keys you do not control. ` +
-                `Prefer create_agent_account, which issues a key restricted to request_payment.`,
+                `It can call request_payment with the full authority of node ${nodeId}.`,
+            `Prefer a VIRTUAL agent (bind_virtual_agent): it binds one key you generate ` +
+                `rather than a whole account, costs ~168 bytes, and strands nothing.`,
         ],
     };
 }
-export function planCreateAgentAccount(vault, nodeId, subLabel, publicKey, keyAllowanceNear) {
-    if (!SUB_LABEL.test(subLabel)) {
-        throw new Error(`invalid sub_label ${JSON.stringify(subLabel)}: 1..=32 chars of [a-z0-9_-]. ` +
-            `A dot in particular is refused — the account id is DERIVED as ` +
-            `<label>.${vault} so the new account cannot be aimed outside this vault's subtree.`);
-    }
-    if (!publicKey.startsWith("ed25519:") && !publicKey.startsWith("secp256k1:")) {
-        throw new Error("publicKey must be in NEAR form, e.g. ed25519:...");
+/**
+ * A whole departmental agent in ONE owner signature: node, binding, gas key.
+ *
+ * WHY THIS IS NOT `add_node` + `bind_virtual_agent` + an AddKey.
+ *
+ * Installing a gas key is an `AddKey` action, and NEAR requires
+ * `signer_id == receiver_id` for one. The owner signing a transaction TO the
+ * vault cannot carry it — only the vault can key itself. A browser wallet
+ * signs as the connected account and cannot sign as the vault, so composing
+ * this client-side would make fleet expansion CLI-only.
+ *
+ * And the node id cannot be threaded: `add_node` returns it, but no client
+ * can read one action's return value inside the same transaction, and
+ * predicting it from `next_node_id` races a concurrent `add_node`.
+ *
+ * So the contract does all three. This is one plain FunctionCall.
+ *
+ * THE DEPOSIT IS THE GAS KEY'S ENTIRE BALANCE, and that balance is its
+ * spending cap — a gas key's `allowance` is null by design. It is not a fee:
+ * the owner can reclaim it, because `WithdrawFromGasKey` is account-signed
+ * and the vault carries the owner's full-access key.
+ */
+export function planAddRole(vault, label, limits, cooldownSec, recipients, publicKey, fundingYocto) {
+    if (!label || label.length > MAX_LABEL_LEN) {
+        throw new Error(`label must be 1..=${MAX_LABEL_LEN} characters (MAX_LABEL_LEN)`);
     }
-    const allowance = toBaseUnits(keyAllowanceNear, NEAR_DECIMALS);
-    if (allowance < BigInt(MIN_AGENT_KEY_ALLOWANCE_YOCTO)) {
-        throw new Error(`key allowance ${keyAllowanceNear} NEAR is below the usable floor of ` +
-            `${fromBaseUnits(BigInt(MIN_AGENT_KEY_ALLOWANCE_YOCTO), NEAR_DECIMALS)} NEAR. ` +
-            `NEAR reserves the FULL prepaid gas of each call against the key up front and ` +
-            `refunds the remainder, so an allowance sized to expected burn produces a key ` +
-            `that cannot transact at all.`);
+    assertCooldown(cooldownSec);
+    assertRecipients(recipients);
+    assertPublicKey(publicKey);
+    // Mirrors MIN_AGENT_GAS_FUNDING in the vault. Below this the key is
+    // installed and cannot complete a single call: NEAR reserves
+    // `prepaid_gas * 1e9` and the tooling sends 60 TGas, which reserves 0.06.
+    // The contract refuses too; refusing here means the owner is not sent to a
+    // wallet to sign something that will revert.
+    if (BigInt(fundingYocto) < 6n * 10n ** 22n) {
+        throw new Error(`the agent's gas key needs at least 0.06 NEAR to make one 60 TGas call — ` +
+            `NEAR reserves prepaid gas up front, so a key funded to the expected ` +
+            `burn (~0.0007) cannot transact at all.`);
     }
-    const deposit = allowance + BigInt(AGENT_ACCOUNT_STORAGE_YOCTO);
-    const derived = `${subLabel}.${vault}`;
     return {
         receiverId: vault,
-        methodName: "create_agent_account",
+        methodName: "add_role",
         args: {
-            node_id: nodeId,
-            sub_label: subLabel,
+            label,
+            limits: limitsToArgs(limits),
+            cooldown_sec: cooldownSec,
+            recipients,
             public_key: publicKey,
-            key_allowance: allowance.toString(),
         },
         gasTgas: DEFAULT_GAS_TGAS,
-        depositYocto: deposit.toString(),
-        summary: `Create agent account ${derived}, bind it to node ${nodeId}, and give it ONE key ` +
-            `that can call only request_payment on ${vault} — it cannot call other methods, ` +
-            `cannot call other contracts, and cannot attach a deposit. ` +
-            `Funding ${fromBaseUnits(deposit, NEAR_DECIMALS)} NEAR ` +
-            `(${keyAllowanceNear} gas allowance + ` +
-            `${fromBaseUnits(BigInt(AGENT_ACCOUNT_STORAGE_YOCTO), NEAR_DECIMALS)} account storage).`,
-        warnings: [],
+        depositYocto: fundingYocto,
+        summary: `Add the "${label}" agent with its own budget, under root`,
+        warnings: [
+            `The ${(Number(fundingYocto) / 1e24).toFixed(3)} NEAR deposit funds the agent's ` +
+                `gas key. It is recoverable, not a fee.`,
+            `The new node is a CHILD OF ROOT, so root's caps still bound the whole ` +
+                `fleet: this divides what the vault can spend in a day, it does not raise it.`,
+            `Check the public key matches the one your agent reported before signing.`,
+        ],
+    };
+}
+export function planBindVirtualAgent(vault, nodeId, publicKey) {
+    assertNodeId(nodeId);
+    assertPublicKey(publicKey);
+    return {
+        receiverId: vault,
+        methodName: "bind_virtual_agent",
+        args: { node_id: nodeId, public_key: publicKey },
+        gasTgas: DEFAULT_GAS_TGAS,
+        // ONE YOCTO, not a funding amount. `bind_virtual_agent` calls
+        // `assert_owner()` -> `assert_one_yocto()`. Nothing is funded here, which
+        // is the whole point of moving off sub-accounts.
+        depositYocto: ONE_YOCTO,
+        summary: `Let the key ${publicKey.slice(0, 22)}… spend from node ${nodeId}`,
+        warnings: [
+            `A node may hold more than one key — binding another does not replace this one.`,
+            `This grants spending authority only. The key still needs gas: install it as ` +
+                `a NEP-611 gas key on the vault and fund it. That balance is recoverable.`,
+        ],
+    };
+}
+/**
+ * Revoke a virtual agent's authority.
+ *
+ * Frees the 82-byte `pubkey_to_node` entry. The 86-byte `pubkey_to_nonce`
+ * entry is RETAINED deliberately and never reclaimed — confirmed live, where
+ * next_nonce stayed at 2 instead of resetting to 1. Dropping it would let
+ * unbind-then-rebind reset the nonce and reopen the replay window, so about
+ * half the binding's storage is intentionally unrecoverable.
+ */
+export function planUnbindVirtualAgent(vault, publicKey) {
+    assertPublicKey(publicKey);
+    return {
+        receiverId: vault,
+        methodName: "unbind_virtual_agent",
+        args: { public_key: publicKey },
+        gasTgas: DEFAULT_GAS_TGAS,
+        depositYocto: ONE_YOCTO,
+        summary: `Revoke the key ${publicKey.slice(0, 22)}…`,
+        warnings: [
+            `The replay nonce for this key is kept forever, on purpose: resetting it ` +
+                `would let an unbind/rebind replay old signed payloads. About half the ` +
+                `binding's storage is therefore not reclaimed.`,
+            `Gas still sitting in this key's NEP-611 gas key is NOT returned by ` +
+                `unbinding. Withdraw from the gas key first, or it stays there.`,
+        ],
     };
 }
 export function planSetRecipients(vault, nodeId, recipients) {
@@ -270,18 +354,78 @@ export function planPurgeSettled(vault, beforeDay, limit) {
         ],
     };
 }
+/**
+ * Move tokens out of the vault, to anywhere the owner says.
+ *
+ * THE STEP THAT DECIDES WHETHER MONEY SURVIVES A TEARDOWN. Deleting a NEAR
+ * account does NOT return its fungible tokens — the token ledger keeps a row
+ * keyed to an account nobody can ever sign for again. So this is not hygiene
+ * before closing a vault, it is the difference between recovering a balance
+ * and burning it, and `scripts/teardown-vault.mjs` runs it first for exactly
+ * that reason.
+ *
+ * BASE UNITS, NOT HUMAN ONES. `withdraw` passes the amount straight to
+ * `ft_transfer`, so this takes what the token uses. The caller scales, and
+ * the summary says the human figure so the two cannot silently disagree in
+ * the wallet.
+ *
+ * The contract refuses a zero amount (`amount must be positive`), so this
+ * does too — refusing here means the owner is not sent to a wallet to sign
+ * something that will revert and cost gas to learn.
+ */
+export function planWithdraw(vault, token, amountBase, receiverId, decimals) {
+    let amt;
+    try {
+        amt = BigInt(amountBase);
+    }
+    catch {
+        throw new Error(`amount must be an integer in base units, got "${amountBase}"`);
+    }
+    if (amt <= 0n) {
+        throw new Error(`amount must be positive — the contract rejects a zero withdrawal outright.`);
+    }
+    if (!receiverId)
+        throw new Error("a receiver account is required");
+    // Human figure for the summary only. Done with string surgery rather than
+    // Number(), because 2^53 is about 9 billion and a 6-decimal token hits that
+    // at 9,007 tokens — a figure a real vault can hold, and silently wrong is
+    // the one thing a wallet confirmation must never be.
+    const neg = amt < 0n;
+    const v = (neg ? -amt : amt).toString().padStart(decimals + 1, "0");
+    const whole = v.slice(0, v.length - decimals);
+    const frac = decimals ? v.slice(v.length - decimals).replace(/0+$/, "") : "";
+    const human = frac ? `${whole}.${frac}` : whole;
+    return {
+        receiverId: vault,
+        methodName: "withdraw",
+        args: { token, amount: amountBase, receiver_id: receiverId },
+        gasTgas: DEFAULT_GAS_TGAS,
+        // `withdraw` is #[payable] and calls assert_owner() -> assert_one_yocto().
+        depositYocto: ONE_YOCTO,
+        summary: `Send ${human} out of the vault to ${receiverId}`,
+        warnings: [
+            `This moves real tokens. ${receiverId} keeps them — the vault cannot pull them back.`,
+            `In-flight payments reserved against this balance may now fail at the token ` +
+                `contract. Their reservations are released by the existing sweep machinery, ` +
+                `so no accounting breaks, but a payment simply does not go through.`,
+        ],
+    };
+}
 /** Registry used by the MCP server, and asserted against the contract's method list. */
 export const OWNER_PLANNERS = {
     add_node: { methodName: "add_node", fn: planAddNode },
     set_node_caps: { methodName: "set_node_caps", fn: planSetNodeCaps },
     bind_agent: { methodName: "bind_agent", fn: planBindAgent },
-    create_agent_account: { methodName: "create_agent_account", fn: planCreateAgentAccount },
+    add_role: { methodName: "add_role", fn: planAddRole },
+    bind_virtual_agent: { methodName: "bind_virtual_agent", fn: planBindVirtualAgent },
+    unbind_virtual_agent: { methodName: "unbind_virtual_agent", fn: planUnbindVirtualAgent },
     set_recipients: { methodName: "set_recipients", fn: planSetRecipients },
     set_cooldown: { methodName: "set_cooldown", fn: planSetCooldown },
     freeze_node: { methodName: "freeze_node", fn: planFreezeNode },
     set_paused: { methodName: "set_paused", fn: planSetPaused },
     set_strict_allocation: { methodName: "set_strict_allocation", fn: planSetStrictAllocation },
     purge_settled: { methodName: "purge_settled", fn: planPurgeSettled },
+    withdraw: { methodName: "withdraw", fn: planWithdraw },
 };
 /** A ready-to-run command, so approving does not require trusting this server. */
 export function toCliCommand(p, network = "testnet") {
@@ -296,18 +440,47 @@ export function toCliCommand(p, network = "testnet") {
  * A threshold is a gate INSIDE the caps: it can only make the vault more
  * conservative, never less, so there is no value of it that moves more money
  * than the budget tree already allowed. `null` removes it.
+ *
+ * ---- `amount` IS HUMAN UNITS, and it used to be base units.
+ *
+ * Breaking change, 2026-10-31, made the same day the tool was published and
+ * before anyone used it. The parameter was `amountBase` and took raw base
+ * units, which made it the ONLY tool in this module on that convention:
+ *
+ *   vault_pay.amount                   human   "12.50"
+ *   planSetNodeCaps dailyCap/perTxCap  human   (the zod schema says so)
+ *   planSetApprovalThreshold           BASE    <- the odd one out
+ *
+ * And it is the one that configures a safety gate, so it FAILED OPEN. An owner
+ * thinking in human units who passed a figure at or above the per-tx cap in
+ * base units got a threshold ABOVE every cap in the tree: the gate never fires,
+ * nothing is ever held, and the transaction succeeds — so the owner believes the
+ * control is on. Measured against the live mainnet vault (per-tx cap 510000
+ * base = 0.51 USDC): "1000000" meaning "a million" yields a 1.0 USDC threshold,
+ * above every cap.
+ *
+ * The other direction fails closed and is merely annoying ("1" meaning 1 USDC
+ * became 0.000001, so everything got held), which is why only one direction is
+ * dangerous and why this is worth a breaking change rather than a doc fix.
+ *
+ * `toBaseUnits` throws rather than truncating excess precision — correct here:
+ * silently rounding 0.1234567 would set a threshold the owner did not choose.
  */
-export function planSetApprovalThreshold(vault, nodeId, amountBase) {
+export function planSetApprovalThreshold(vault, nodeId, amount, decimals) {
+    const base = amount === null ? null : toBaseUnits(amount, decimals).toString();
     return {
         receiverId: vault,
         methodName: "set_approval_threshold",
-        args: { node_id: nodeId, amount: amountBase },
+        args: { node_id: nodeId, amount: base },
         gasTgas: DEFAULT_GAS_TGAS,
         depositYocto: ONE_YOCTO,
-        summary: amountBase
-            ? `Payments above ${amountBase} (base units) from node ${nodeId} will need your approval`
+        // Human units in the summary too. The old line read "Payments above
+        // 1000000 (base units)", which is unreadable in precisely the moment the
+        // owner is checking the plan before signing it.
+        summary: amount
+            ? `Payments above ${amount} from node ${nodeId} will need your approval`
             : `Remove the approval threshold on node ${nodeId} — payments up to the caps run unattended`,
-        warnings: amountBase
+        warnings: amount
             ? []
             : ["After this, nothing at this node waits for a human: only the caps apply."],
     };

package/dist/roles.d.ts

@@ -0,0 +1,18 @@
+export interface RoleCredential {
+    agentId: string;
+    agentKey: string;
+    role: string;
+    nodeId?: number;
+}
+export declare class RoleSelectionError extends Error {
+}
+export declare function selectRole(cfg: {
+    agentKeysPath?: string;
+}, role: string): {
+    agentId: string;
+    agentKey: string;
+};
+/** Every role that could actually sign, for listing back to a caller. */
+export declare function listRoles(cfg: {
+    agentKeysPath?: string;
+}): RoleCredential[];

package/dist/roles.js

@@ -0,0 +1,61 @@
+/**
+ * Picking which agent in a fleet signs a payment.
+ *
+ * WHICH KEY SIGNS *IS* WHICH BUDGET IS CHARGED — the contract resolves the
+ * spending node from the signer (`pubkey_to_node`), never from the request
+ * body. So a wrong choice here does not fail; it succeeds against another
+ * agent's budget and shows up later as a balance nobody can explain.
+ *
+ * This reads the SAME file the adapter reads, and accepts the same entry
+ * shape, because two readers of one keyring that disagree about what counts
+ * as a credential is how an agent ends up "configured" and unreachable.
+ */
+import { existsSync, readFileSync } from "node:fs";
+/** Entries that `loadKeyring` would accept, nothing else. */
+function loadable(path) {
+    if (!existsSync(path))
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    // THE SAME PREDICATE THE ADAPTER USES. An entry failing it is skipped there
+    // in total silence, so listing it here would advertise an agent that can
+    // never be selected.
+    return parsed.filter((e) => e && typeof e.agentId === "string" && typeof e.secret === "string");
+}
+export class RoleSelectionError extends Error {
+}
+export function selectRole(cfg, role) {
+    const path = cfg.agentKeysPath ?? ".float/agent-keys.json";
+    const entries = loadable(path);
+    const known = entries
+        .map((e) => (typeof e.role === "string" ? e.role : null))
+        .filter(Boolean);
+    const hit = entries.find((e) => e.role === role);
+    if (!hit) {
+        throw new RoleSelectionError(`no agent with role '${role}' in ${path}. ` +
+            `Known roles: ${known.length ? known.join(", ") : "none"}. ` +
+            (entries.length && !known.length
+                ? `${entries.length} credential(s) are loaded but none carries a role — ` +
+                    `they predate roles, so select them by nodeId or add a "role" field.`
+                : `Add one with vault_add_role.`));
+    }
+    return { agentId: hit.agentId, agentKey: hit.secret };
+}
+/** Every role that could actually sign, for listing back to a caller. */
+export function listRoles(cfg) {
+    return loadable(cfg.agentKeysPath ?? ".float/agent-keys.json")
+        .filter((e) => typeof e.role === "string")
+        .map((e) => ({
+        agentId: e.agentId,
+        agentKey: e.secret,
+        role: e.role,
+        nodeId: typeof e.nodeId === "number" ? e.nodeId : undefined,
+    }));
+}

package/dist/rpc.d.ts

@@ -32,6 +32,19 @@ interface RawViewResponse {
  */
 export declare function decodeViewResult<T = unknown>(res: RawViewResponse): T;
 export declare function viewFunction<T = unknown>(rpcUrl: string, contractId: string, methodName: string, args?: unknown): Promise<T>;
+/**
+ * Does this account exist on chain?
+ *
+ * Used before offering to CREATE a vault at a derived address. Getting this
+ * wrong is not cosmetic: the create batch's first action is `CreateAccount`,
+ * so offering an address that is already taken sends the user to a wallet,
+ * takes their signature, and fails only after they have committed.
+ *
+ * Distinguishes "does not exist" from "could not tell". An RPC timeout that
+ * returned `false` would read as a free address, so ONLY the specific
+ * UNKNOWN_ACCOUNT answer counts as absent and anything else throws.
+ */
+export declare function accountExists(rpcUrl: string, accountId: string): Promise<boolean>;
 /** One access key as NEAR reports it. */
 export interface AccessKeyInfo {
     public_key: string;
@@ -43,6 +56,14 @@ export interface AccessKeyInfo {
                 receiver_id: string;
                 method_names: string[];
             };
+        } | {
+            GasKeyFunctionCall: {
+                allowance: string | null;
+                balance: string;
+                receiver_id: string;
+                method_names: string[];
+                num_nonces?: number;
+            };
         };
     };
 }
@@ -56,6 +77,20 @@ export interface AccessKeyInfo {
  * be true.
  */
 export declare function viewAccessKeys(rpcUrl: string, accountId: string): Promise<AccessKeyInfo[]>;
+/** An account's balance and storage, as the chain reports them. */
+export interface AccountView {
+    amount: string;
+    storage_usage: number;
+}
+/**
+ * Read an account's balance and storage.
+ *
+ * Both as the chain reports them: `amount` is the TOTAL, and the storage
+ * stake (`storage_usage * 1e19`) is locked inside it rather than held
+ * separately. Subtracting is the caller's job, and getting that backwards is
+ * how a vault with 0.02 spendable looks like it has 0.12.
+ */
+export declare function viewAccount(rpcUrl: string, accountId: string): Promise<AccountView>;
 export interface AgentCreds {
     agentId: string;
     agentKey: string;
@@ -68,6 +103,22 @@ export interface AgentCreds {
 export declare function requireAgentKey(env: {
     agentId?: string;
     agentKey?: string;
+    /**
+     * Why `NEAR_VAULT_AGENT_KEY_FILE` produced no key, when one was named.
+     *
+     * SEPARATE FROM `agentKey` BEING ABSENT, and it must stay that way. "The
+     * variable is not set" and "the file you pointed it at is broken" are
+     * different problems with different fixes; reporting the second as the first
+     * sends the operator to set something they have already set — and the
+     * quickest way out of that dead end is pasting the key inline, which undoes
+     * the reason the file option exists.
+     */
+    agentKeyError?: string;
+    /**
+     * `account_id` from a `~/.near-credentials`-shaped key file, when the key
+     * came from one. Absent for an inline key or a bare key file.
+     */
+    agentKeyAccountId?: string;
 }): AgentCreds;
 /**
  * A request id the contract will accept.

package/dist/rpc.js

@@ -71,6 +71,39 @@ export async function viewFunction(rpcUrl, contractId, methodName, args = {}) {
         return decodeViewResult({ error: json.error });
     return decodeViewResult(json.result ?? {});
 }
+/**
+ * Does this account exist on chain?
+ *
+ * Used before offering to CREATE a vault at a derived address. Getting this
+ * wrong is not cosmetic: the create batch's first action is `CreateAccount`,
+ * so offering an address that is already taken sends the user to a wallet,
+ * takes their signature, and fails only after they have committed.
+ *
+ * Distinguishes "does not exist" from "could not tell". An RPC timeout that
+ * returned `false` would read as a free address, so ONLY the specific
+ * UNKNOWN_ACCOUNT answer counts as absent and anything else throws.
+ */
+export async function accountExists(rpcUrl, accountId) {
+    const r = await fetch(rpcUrl, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: "near-vault-mcp",
+            method: "query",
+            params: { request_type: "view_account", finality: "final", account_id: accountId },
+        }),
+    });
+    if (!r.ok)
+        throw new Error(`RPC ${r.status} checking whether ${accountId} exists`);
+    const j = (await r.json());
+    if (j.result)
+        return true;
+    const name = j.error?.cause?.name;
+    if (name === "UNKNOWN_ACCOUNT")
+        return false;
+    throw new Error(`could not determine whether ${accountId} exists: ${name ?? j.error?.message ?? "unknown error"}`);
+}
 /**
  * Every access key on an account, read from the chain.
  *
@@ -98,28 +131,91 @@ export async function viewAccessKeys(rpcUrl, accountId) {
         throw new Error(`access key list failed: ${json.error.message ?? "unknown"}`);
     return json.result?.keys ?? [];
 }
+/**
+ * Read an account's balance and storage.
+ *
+ * Both as the chain reports them: `amount` is the TOTAL, and the storage
+ * stake (`storage_usage * 1e19`) is locked inside it rather than held
+ * separately. Subtracting is the caller's job, and getting that backwards is
+ * how a vault with 0.02 spendable looks like it has 0.12.
+ */
+export async function viewAccount(rpcUrl, accountId) {
+    const r = await fetch(rpcUrl, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: "near-vault-mcp",
+            method: "query",
+            params: { request_type: "view_account", finality: "final", account_id: accountId },
+        }),
+    });
+    if (!r.ok)
+        throw new Error(`RPC ${rpcUrl} returned HTTP ${r.status}`);
+    const json = (await r.json());
+    if (json.error)
+        throw new Error(`view_account failed: ${json.error.message ?? "unknown"}`);
+    if (!json.result)
+        throw new Error(`view_account returned no result for ${accountId}`);
+    return json.result;
+}
 /**
  * Both halves or neither. Failing here with the variable NAMES beats throwing a
  * TypeError three frames deeper, and beats silently signing with the wrong
  * account.
  */
 export function requireAgentKey(env) {
+    // THE FILE'S OWN FAILURE OUTRANKS EVERY "not set" MESSAGE BELOW. It is the
+    // only one of them that names a cause, and once a path is involved the
+    // missing-variable advice is actively misleading.
+    if (!env.agentKey && env.agentKeyError) {
+        throw new Error(`Paying needs the agent key, and the key file could not be read. ` +
+            `${env.agentKeyError} Fix the path or the file — or unset the _FILE variable ` +
+            `to fall back to an inline NEAR_VAULT_AGENT_KEY.`);
+    }
     // Name EVERY missing variable, not just the first. A message that reports
     // half the problem buys a second failed attempt.
     if (!env.agentId && !env.agentKey) {
-        throw new Error("Paying requires NEAR_VAULT_AGENT_ID and NEAR_VAULT_AGENT_KEY, and neither is set. " +
+        throw new Error("Paying requires NEAR_VAULT_AGENT_ID and a key, and neither is set. " +
+            "The key can be NEAR_VAULT_AGENT_KEY (inline) or NEAR_VAULT_AGENT_KEY_FILE " +
+            "(a path to a ~/.near-credentials-shaped JSON file, or a bare key file) — " +
+            "prefer the file, since an inline key is printed by any read of the config. " +
             "Reads and payload planning work without them; only paying needs them. " +
-            "The key must be the restricted one issued by create_agent_account — never a " +
+            "The key must be a RESTRICTED one, from a VIRTUAL AGENT — never a " +
             "full-access key.");
     }
     if (!env.agentId) {
         throw new Error("NEAR_VAULT_AGENT_ID is not set, so there is no agent account to pay from.");
     }
     if (!env.agentKey) {
-        throw new Error("NEAR_VAULT_AGENT_KEY is not set. This must be the restricted key issued by " +
-            "create_agent_account — it can call only request_payment on the vault, cannot " +
+        throw new Error("No agent key is set: use NEAR_VAULT_AGENT_KEY_FILE (a path — preferred, since " +
+            "an inline key is printed by any read of the config) or NEAR_VAULT_AGENT_KEY. " +
+            "This must be a VIRTUAL AGENT's key, bound " +
+            "with bind_virtual_agent and installed as a NEP-611 gas key on the vault — it can call only request_payment on the vault, cannot " +
             "call other contracts, and cannot attach a deposit. Never put a full-access key here.");
     }
+    /**
+     * THE KEY FILE AND NEAR_VAULT_AGENT_ID MUST NAME THE SAME ACCOUNT.
+     *
+     * Which key signs *is* which budget is charged — the contract resolves the
+     * spending node from the signer, never from the request body. So a key used
+     * under the wrong account id does not get rejected locally; it goes to chain
+     * and fails with NOT_VIRTUAL_AGENT, which reads as a binding bug and sends
+     * the reader to the contract rather than to their config.
+     *
+     * No mismatch is legitimate. A virtual agent's key is a NEP-611 gas key ON
+     * the vault, so it signs AS the vault, and a credentials file for it names
+     * the vault. A file naming some other account holds some other account's key
+     * — most often the owner's full-access one, which must never be used here.
+     */
+    if (env.agentKeyAccountId && env.agentKeyAccountId !== env.agentId) {
+        throw new Error(`the key file belongs to ${env.agentKeyAccountId}, but NEAR_VAULT_AGENT_ID is ` +
+            `${env.agentId}. A key signs as the account it was issued for, and the vault ` +
+            `resolves the spending budget from the signer — so this pairing cannot pay. ` +
+            `Point NEAR_VAULT_AGENT_ID at ${env.agentKeyAccountId}, or use the key file ` +
+            `for ${env.agentId}. A virtual agent's key is a gas key ON the vault, so for ` +
+            `one it is the vault's own id.`);
+    }
     return { agentId: env.agentId, agentKey: env.agentKey };
 }
 /**