@floatonnear/mcp 0.3.0 → 0.4.0

package/dist/key-file.js

@@ -0,0 +1,237 @@
+/**
+ * Read a secret from a FILE PATH instead of a plaintext env value.
+ *
+ * This is the same reasoning as `env-file.ts` in the adapter, taken one step
+ * further, so it is worth saying what the two have in common and where they
+ * part.
+ *
+ * `env-file.ts` exists because a secrets file must be DATA, never something a
+ * shell executes: `set -a && . .float/adapter.env` makes the shell run `$(...)`
+ * and backticks found in a value, and it has already died for real on one
+ * unquoted value containing a space. That argument is about how a file is
+ * LOADED.
+ *
+ * This module is about where the secret LIVES. Right now the agent key is a
+ * plaintext env value in two places — `.mcp.json` (`mcpServers.float-near.env`)
+ * and `.float/adapter.env`. Both are gitignored and neither has ever been
+ * committed, so nothing has leaked. The exposure is ORDINARY WORK: checking
+ * which vault an adapter is pointed at means reading its config, and reading
+ * its config prints a live private key into a terminal scrollback and into the
+ * transcript of whatever agent is driving. That is routine, it is not a
+ * mistake anyone would flag in review, and it is how the session that filed
+ * this acquired one.
+ *
+ * A PATH is not a secret, so the same `cat` becomes harmless. This repo already
+ * prefers that shape for the one credential it handles most carefully: NEAR CLI
+ * signing uses `sign-with-access-key-file` rather than
+ * `sign-with-plaintext-private-key`, chosen after a key was echoed into a
+ * terminal. This brings the MCP server and the adapter to the same footing.
+ *
+ * THE INLINE VARIABLES KEEP WORKING. They are in use; a file is an
+ * alternative, not a replacement. When both are set the file wins and the
+ * inline one is reported as ignored — the other way round would let an operator
+ * believe they had moved a secret out of their config while the config was
+ * still silently the thing being read.
+ *
+ * ---- WHAT NO MESSAGE IN HERE MAY CONTAIN
+ *
+ * The secret. Every refusal below is reached while holding a usable key, so
+ * quoting "what the file contained" would undo the entire point of the change
+ * at the one moment an operator is most likely to paste the output somewhere.
+ * Field NAMES are safe and are the actual diagnosis; values are not. This is
+ * pinned by `no refusal ever names the secret` in key-file.test.ts, which drives
+ * only cases that have a real secret in hand.
+ *
+ * That rule is also why a JSON parse failure is reported as "not valid JSON"
+ * with the parser's own message DISCARDED: V8's `JSON.parse` errors quote a
+ * fragment of the input, so passing one through would print part of the key.
+ */
+import { readFileSync, existsSync, statSync } from "node:fs";
+export class KeyFileError extends Error {
+}
+/** The shape to quote in a refusal, so the fix is in the message. */
+const CRED_SHAPE = '{"account_id", "public_key", "private_key"}';
+/**
+ * An env-file assignment, which is a FILE POINTED AT THE WRONG VARIABLE
+ * rather than a key.
+ *
+ * Why the name must contain an underscore and the value must be non-empty
+ * after stripping '=': a base64url secret can legitimately end in '=' padding
+ * and base64url's alphabet includes '_', so `ABC_DEF=` is a possible SECRET,
+ * not necessarily an assignment. Padding is always trailing, so requiring
+ * something other than '=' after the first one tells the two apart. Neither of
+ * the keys this actually carries can collide anyway — an `ed25519:` key is
+ * base58 (no '=', no '_') and a quote signer is hex — but this reader is
+ * generic and the wrong answer here is the silent kind.
+ */
+const ENV_LINE = /^(?:export\s+)?([A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+)\s*=(.*)$/;
+/**
+ * Read a key out of `path`.
+ *
+ * Accepts either the `~/.near-credentials` JSON shape or a bare key on one
+ * line. Throws `KeyFileError` for anything else — never returns an empty or
+ * partial credential, because "I could not read it" collapsing into "there
+ * isn't one" is the failure this is built to avoid.
+ */
+export function readKeyFile(path) {
+    if (!existsSync(path)) {
+        throw new KeyFileError(`key file ${path} does not exist. It should hold either the ` +
+            `~/.near-credentials shape ${CRED_SHAPE} or the bare key on one line.`);
+    }
+    let raw;
+    try {
+        // Checked explicitly: readFileSync on a directory throws EISDIR, and an
+        // errno in an error message is not a diagnosis.
+        if (statSync(path).isDirectory()) {
+            throw new KeyFileError(`key file ${path} is a directory, not a file.`);
+        }
+        raw = readFileSync(path, "utf8");
+    }
+    catch (e) {
+        if (e instanceof KeyFileError)
+            throw e;
+        const code = e.code;
+        throw new KeyFileError(`key file ${path} could not be read${code ? ` (${code})` : ""}.`);
+    }
+    /**
+     * A BOM IS ALREADY HANDLED, by `trim()`, and that is worth a sentence
+     * because it does not look handled.
+     *
+     * PowerShell's Set-Content and Out-File write a U+FEFF by default, so any
+     * file the operator has touched from a one-liner carries one, and left in
+     * place it becomes part of the secret or of the first JSON key's name — a
+     * failure whose cause is invisible. env-file.ts strips it explicitly, so the
+     * obvious thing here was to copy that.
+     *
+     * It is not needed. U+FEFF satisfies the spec's WhiteSpace production, so
+     * `String.prototype.trim` removes it (verified on node 24.14:
+     * `/^\s$/.test("")` is true). An explicit `startsWith("") ?
+     * slice(1)` ahead of this line is therefore dead code — it was written, and
+     * mutation testing exposed it: deleting it killed no test, because it could
+     * not change any outcome.
+     *
+     * The `tolerates CRLF and a BOM` test stays, pinning the real behaviour
+     * rather than the redundant guard.
+     */
+    const trimmed = raw.trim();
+    // EMPTY IS NOT ABSENT. A zero-byte key file resolving to "no key configured"
+    // would send the operator to set a variable they have already set, while the
+    // real fault is the file they are pointing at.
+    if (!trimmed) {
+        throw new KeyFileError(`key file ${path} is empty — there is no key in it.`);
+    }
+    // `[` as well as `{`: a JSON array must be named as the wrong shape, not fed
+    // to the bare-key reader, which would otherwise accept the literal text
+    // `["ed25519:..."]` as a secret.
+    if (trimmed.startsWith("{") || trimmed.startsWith("["))
+        return fromJson(trimmed, path);
+    return { secret: fromBare(trimmed, path) };
+}
+function fromJson(text, path) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        /**
+         * THE PARSER'S MESSAGE IS DELIBERATELY DROPPED, and this is load-bearing
+         * rather than tidiness.
+         *
+         * V8 quotes a run of the input in its `is not valid JSON` form. Measured on
+         * node 24.14 against a credentials file whose private_key had been
+         * hand-edited and left unquoted:
+         *
+         *   Unexpected token 'e', ..."ate_key": ed25519:3D"... is not valid JSON
+         *
+         * Forwarding that publishes the head of the key — into a terminal, a pm2
+         * log, or an agent transcript, which is the exact exposure this module
+         * exists to close. Pinned by `unquoted JSON value` in the leak test.
+         */
+        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)) {
+        throw new KeyFileError(`key file ${path} is JSON but not an object. Expected the ~/.near-credentials ` +
+            `shape ${CRED_SHAPE}.`);
+    }
+    const o = parsed;
+    const secret = typeof o.private_key === "string" ? o.private_key.trim() : "";
+    if (!secret) {
+        // FIELD NAMES, NEVER VALUES. The names are the whole diagnosis: a file
+        // written by a tool that calls it `secret` or `privateKey` is otherwise
+        // indistinguishable from a corrupt one.
+        const names = Object.keys(o);
+        throw new KeyFileError(`key file ${path} has no usable "private_key". Fields present: ` +
+            `${names.length ? names.join(", ") : "none"}. Expected the ~/.near-credentials ` +
+            `shape ${CRED_SHAPE}.`);
+    }
+    const str = (v) => (typeof v === "string" && v.trim() ? v.trim() : undefined);
+    return { secret, accountId: str(o.account_id), publicKey: str(o.public_key) };
+}
+function fromBare(text, path) {
+    const lines = text
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter((l) => l && !l.startsWith("#"));
+    // Reachable: a file holding nothing but comments trims to something, then
+    // filters to nothing.
+    if (lines.length === 0) {
+        throw new KeyFileError(`key file ${path} is empty — there is no key in it.`);
+    }
+    // BEFORE the line count, because an env file has many lines and "expected
+    // one key" would be a true statement that hides the actual mistake.
+    for (const line of lines) {
+        const m = ENV_LINE.exec(line);
+        if (m && m[2].replace(/=/g, "").trim()) {
+            throw new KeyFileError(`key file ${path} looks like an env file: it contains an assignment to ` +
+                `${m[1]}. This variable wants a file holding ONLY the key — either the ` +
+                `~/.near-credentials shape ${CRED_SHAPE} or the bare key on one line. ` +
+                `To load a whole env file instead, use FLOAT_ENV_FILE.`);
+        }
+    }
+    if (lines.length > 1) {
+        throw new KeyFileError(`key file ${path} has ${lines.length} content lines; expected exactly one key. ` +
+            `Which key signs is which budget is charged, so this is not guessed.`);
+    }
+    return lines[0];
+}
+/**
+ * Decide which of the two variables supplies a secret.
+ *
+ * The file wins. A failed file read does NOT fall back to the inline value:
+ * silently using the config an operator believes they have stopped using is
+ * worse than not starting.
+ */
+export function resolveKeySource(opts) {
+    const warnings = [];
+    // Trimmed, and blank treated as absent. `NEAR_VAULT_AGENT_KEY=` in an env
+    // file parses to "", and a key made of spaces fails at the signer several
+    // frames from its cause. No valid key has surrounding whitespace, so this
+    // can only rescue a config that was already broken.
+    const inline = (opts.inline ?? "").trim() || undefined;
+    const path = (opts.file ?? "").trim() || undefined;
+    if (!path) {
+        return inline ? { secret: inline, source: "inline", warnings } : { source: "none", warnings };
+    }
+    if (inline) {
+        warnings.push(`${opts.fileVar} is set, so ${opts.inlineVar} is ignored. Remove the inline ` +
+            `value: a key held in an env value is printed by any read of the config, ` +
+            `which is routine, whereas a path is not a secret.`);
+    }
+    try {
+        const got = readKeyFile(path);
+        return {
+            secret: got.secret,
+            source: "file",
+            path,
+            accountId: got.accountId,
+            publicKey: got.publicKey,
+            warnings,
+        };
+    }
+    catch (e) {
+        // `source` stays "file" with no secret. A caller that reports this as
+        // "nothing configured" has lost the only useful part of the message.
+        return { source: "file", path, error: `${opts.fileVar}: ${e.message}`, warnings };
+    }
+}

package/dist/payloads.d.ts

@@ -12,10 +12,6 @@
  * message can explain *why* a bound exists.
  */
 export declare const ONE_YOCTO = "1";
-/** Mirrors `AGENT_ACCOUNT_STORAGE` in the contract: 0.05 NEAR. */
-export declare const AGENT_ACCOUNT_STORAGE_YOCTO: string;
-/** Mirrors `MIN_AGENT_KEY_ALLOWANCE` in the contract: 0.5 NEAR. */
-export declare const MIN_AGENT_KEY_ALLOWANCE_YOCTO: string;
 /**
  * Gas attached to a payment, for every route.
  *
@@ -28,7 +24,6 @@ export declare const DEFAULT_GAS_TGAS = 100;
 export declare const MAX_TOKENS = 4;
 export declare const MAX_RECIPIENTS = 32;
 export declare const MAX_LABEL_LEN = 48;
-export declare const MAX_SUB_LABEL_LEN = 32;
 export declare const MAX_COOLDOWN_SEC: number;
 export declare const MAX_PURGE_LIMIT = 100;
 export interface HumanTokenLimit {
@@ -51,13 +46,66 @@ export interface OwnerPayload {
 export declare function planAddNode(vault: string, parent: number | null, label: string, limits: HumanTokenLimit[], cooldownSec: number, recipients: string[] | null): OwnerPayload;
 export declare function planSetNodeCaps(vault: string, nodeId: number, limits: HumanTokenLimit[]): OwnerPayload;
 export declare function planBindAgent(vault: string, nodeId: number, accountId: string): OwnerPayload;
-export declare function planCreateAgentAccount(vault: string, nodeId: number, subLabel: string, publicKey: string, keyAllowanceNear: string): OwnerPayload;
+/**
+ * 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 declare function planAddRole(vault: string, label: string, limits: HumanTokenLimit[], cooldownSec: number, recipients: string[] | null, publicKey: string, fundingYocto: string): OwnerPayload;
+export declare function planBindVirtualAgent(vault: string, nodeId: number, publicKey: string): OwnerPayload;
+/**
+ * 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 declare function planUnbindVirtualAgent(vault: string, publicKey: string): OwnerPayload;
 export declare function planSetRecipients(vault: string, nodeId: number, recipients: string[] | null): OwnerPayload;
 export declare function planSetCooldown(vault: string, nodeId: number, cooldownSec: number): OwnerPayload;
 export declare function planFreezeNode(vault: string, nodeId: number, frozen: boolean): OwnerPayload;
 export declare function planSetPaused(vault: string, paused: boolean): OwnerPayload;
 export declare function planSetStrictAllocation(vault: string, strict: boolean): OwnerPayload;
 export declare function planPurgeSettled(vault: string, beforeDay: number, limit: number): OwnerPayload;
+/**
+ * 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 declare function planWithdraw(vault: string, token: string, amountBase: string, receiverId: string, decimals: number): OwnerPayload;
 /** Registry used by the MCP server, and asserted against the contract's method list. */
 export declare const OWNER_PLANNERS: {
     readonly add_node: {
@@ -72,9 +120,17 @@ export declare const OWNER_PLANNERS: {
         readonly methodName: "bind_agent";
         readonly fn: typeof planBindAgent;
     };
-    readonly create_agent_account: {
-        readonly methodName: "create_agent_account";
-        readonly fn: typeof planCreateAgentAccount;
+    readonly add_role: {
+        readonly methodName: "add_role";
+        readonly fn: typeof planAddRole;
+    };
+    readonly bind_virtual_agent: {
+        readonly methodName: "bind_virtual_agent";
+        readonly fn: typeof planBindVirtualAgent;
+    };
+    readonly unbind_virtual_agent: {
+        readonly methodName: "unbind_virtual_agent";
+        readonly fn: typeof planUnbindVirtualAgent;
     };
     readonly set_recipients: {
         readonly methodName: "set_recipients";
@@ -100,6 +156,10 @@ export declare const OWNER_PLANNERS: {
         readonly methodName: "purge_settled";
         readonly fn: typeof planPurgeSettled;
     };
+    readonly withdraw: {
+        readonly methodName: "withdraw";
+        readonly fn: typeof planWithdraw;
+    };
 };
 /** A ready-to-run command, so approving does not require trusting this server. */
 export declare function toCliCommand(p: OwnerPayload, network?: string): string;

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") {

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[];