@floatonnear/float-adapter 0.2.1 → 0.3.0

package/dist/keyring.d.ts

@@ -14,7 +14,7 @@
  * cannot exercise a hierarchy at all; it can only ever spend one leaf.
  *
  * On holding several keys at once: each is the restricted key from
- * `create_agent_account`, which can call only `request_payment` on its own
+ * a virtual agent's NEP-611 gas key, which can call only `request_payment` on its own
  * vault, cannot call other contracts, and cannot attach a deposit. The vault
  * enforces every cap regardless of who holds the key, so the blast radius of
  * the whole keyring is bounded by the tree's own limits. That is the same
@@ -25,12 +25,61 @@ export interface AgentCredential {
     secret: string;
     /** Present when known; lets a caller select by node instead of account id. */
     nodeId?: number;
+    /**
+     * A human name for this agent — "marketing", "news".
+     *
+     * THE ONLY IDENTIFIER THAT IS ACTUALLY UNIQUE PER AGENT once agents are
+     * virtual. `agentId` is the account a key signs AS, and a virtual agent's
+     * key is a gas key ON THE VAULT, so every agent on one vault shares it.
+     * `nodeId` is unique but is a number nobody wants to quote.
+     */
+    role?: string;
 }
 export interface Keyring {
-    /** agent account id -> credential */
+    /**
+     * agent account id -> credential.
+     *
+     * LOSSY FOR VIRTUAL AGENTS, deliberately kept for compatibility. Every
+     * agent on one vault has the same `agentId`, so this map holds only the
+     * last one loaded. Use `all` for anything that counts agents and `byRole`
+     * or `byNode` to select one.
+     */
     byAccount: Map<string, AgentCredential>;
     /** node id -> credential */
     byNode: Map<number, AgentCredential>;
+    /** role name -> credential */
+    byRole: Map<string, AgentCredential>;
+    /**
+     * Every credential loaded, in file order.
+     *
+     * The ONLY honest count. Ambiguity used to be judged by `byAccount.size`,
+     * which collapses virtual agents onto one key — so two agents read as
+     * "exactly one, unambiguous" and an un-targeted payment silently signed
+     * with whichever was written last, charging the wrong node. Measured
+     * 2026-11-03: a two-agent file produced `byAccount.size === 1`.
+     */
+    all: AgentCredential[];
+    /**
+     * How many file entries were skipped because they belong to a different
+     * vault. Zero unless `vault` was passed to `loadKeyring`.
+     *
+     * Surfaced rather than discarded: "no agents configured" and "three agents
+     * configured, none of them for this vault" look identical from an empty
+     * ring, and the second is a pointing error the operator can fix in
+     * seconds once told.
+     */
+    skippedOtherVault: number;
+    /**
+     * Why `NEAR_VAULT_AGENT_KEY_FILE` yielded no key, when one was named.
+     *
+     * THE THIRD CAUSE OF AN EMPTY RING, and the same reason
+     * `skippedOtherVault` is carried rather than discarded. The generic refusal
+     * says "Set NEAR_VAULT_AGENT_ID and NEAR_VAULT_AGENT_KEY" — which, for an
+     * operator whose key file is simply mistyped, is advice to paste the secret
+     * back inline. That is the exposure the file option exists to remove, so
+     * misreporting this case actively undoes the change.
+     */
+    agentKeyError?: string;
     /**
      * Used when a request names no agent. Preserves the previous single-agent
      * behaviour exactly, so existing deployments and the dashboard's own calls
@@ -52,6 +101,35 @@ export declare function loadKeyring(env: {
     agentId?: string;
     agentKey?: string;
     agentKeysPath?: string;
+    /**
+     * The vault this adapter serves. When given, credentials belonging to a
+     * DIFFERENT vault are skipped.
+     *
+     * The keyring file is per-machine, not per-vault: one `.float/agent-keys.json`
+     * accumulates every agent ever provisioned here. Without this filter an
+     * adapter serving vault A also loads vault B's agents, which goes wrong in
+     * two ways.
+     *
+     * Loudly, if there are several: `selectAgent` refuses an un-targeted payment
+     * and lists agents that are not even on this vault, so the error names
+     * options that could never have worked.
+     *
+     * QUIETLY, if there is exactly one: `all.length === 1` makes a credential
+     * for an unrelated vault the FALLBACK. Every un-targeted payment is then
+     * signed by a key the contract has never heard of — it fails on chain with
+     * NOT_VIRTUAL_AGENT, which reads like a binding bug rather than a
+     * configuration one, and sends the reader looking in the wrong place.
+     *
+     * Observed 2026-11-03: an adapter on work12-testnet-fleet loaded
+     * rudeisland4178's agent and named it in a refusal.
+     */
+    vault?: string;
+    /**
+     * Passed through from `resolveKeySource` when NEAR_VAULT_AGENT_KEY_FILE was
+     * named but unreadable. Carried, not acted on: a broken default must not
+     * stop the agents that DID load from being selected by name.
+     */
+    agentKeyError?: string;
 }): Keyring;
 export declare class AgentSelectionError extends Error {
 }
@@ -65,4 +143,5 @@ export declare class AgentSelectionError extends Error {
 export declare function selectAgent(ring: Keyring, want?: {
     agent?: string;
     nodeId?: number;
+    role?: string;
 }): AgentCredential;

package/dist/keyring.js

@@ -14,7 +14,7 @@
  * cannot exercise a hierarchy at all; it can only ever spend one leaf.
  *
  * On holding several keys at once: each is the restricted key from
- * `create_agent_account`, which can call only `request_payment` on its own
+ * a virtual agent's NEP-611 gas key, which can call only `request_payment` on its own
  * vault, cannot call other contracts, and cannot attach a deposit. The vault
  * enforces every cap regardless of who holds the key, so the blast radius of
  * the whole keyring is bounded by the tree's own limits. That is the same
@@ -22,7 +22,7 @@
  */
 import { readFileSync, existsSync } from "node:fs";
 export function emptyKeyring() {
-    return { byAccount: new Map(), byNode: new Map() };
+    return { byAccount: new Map(), byNode: new Map(), byRole: new Map(), all: [], skippedOtherVault: 0 };
 }
 /**
  * Build a keyring from the singular env vars plus, optionally, the JSON file
@@ -35,10 +35,14 @@ export function emptyKeyring() {
  */
 export function loadKeyring(env) {
     const ring = emptyKeyring();
+    ring.agentKeyError = env.agentKeyError;
     const add = (c) => {
+        ring.all.push(c);
         ring.byAccount.set(c.agentId, c);
         if (typeof c.nodeId === "number")
             ring.byNode.set(c.nodeId, c);
+        if (c.role)
+            ring.byRole.set(c.role, c);
     };
     if (env.agentKeysPath && existsSync(env.agentKeysPath)) {
         let parsed;
@@ -54,10 +58,19 @@ export function loadKeyring(env) {
         if (Array.isArray(parsed)) {
             for (const e of parsed) {
                 if (e && typeof e.agentId === "string" && typeof e.secret === "string") {
+                    // A credential for ANOTHER vault is not this adapter's to use.
+                    // Counted rather than dropped in silence, so a keyring that looks
+                    // empty can be told apart from one whose entries all belong
+                    // elsewhere — those are different problems with different fixes.
+                    if (env.vault && e.agentId !== env.vault) {
+                        ring.skippedOtherVault += 1;
+                        continue;
+                    }
                     add({
                         agentId: e.agentId,
                         secret: e.secret,
                         nodeId: typeof e.nodeId === "number" ? e.nodeId : undefined,
+                        role: typeof e.role === "string" && e.role ? e.role : undefined,
                     });
                 }
             }
@@ -68,11 +81,15 @@ export function loadKeyring(env) {
         add(c);
         ring.fallback = c;
     }
-    else if (ring.byAccount.size === 1) {
-        // Exactly one key in the file and no env pair: unambiguous, so use it.
-        // More than one with no env pair is deliberately NOT guessed at — see
-        // selectAgent.
-        ring.fallback = [...ring.byAccount.values()][0];
+    else if (ring.all.length === 1) {
+        // Exactly one credential and no env pair: unambiguous, so use it.
+        //
+        // `all.length`, NOT `byAccount.size`. Every virtual agent on a vault
+        // shares an `agentId`, so the map collapses them and two agents read as
+        // one — which made this branch fire on an ambiguous keyring and pick
+        // whichever was written last. Silently: the payment succeeded, against
+        // the wrong node's budget.
+        ring.fallback = ring.all[0];
     }
     return ring;
 }
@@ -86,10 +103,26 @@ export class AgentSelectionError extends Error {
  * costs the caller another round trip to discover what the valid options were.
  */
 export function selectAgent(ring, want = {}) {
+    // Lists `all`, not `byAccount.values()`. The map holds one entry per
+    // ACCOUNT, so on a fleet it named a single agent while several were
+    // loaded — an error message that under-reports the thing it exists to
+    // report.
     const known = () => {
-        const list = [...ring.byAccount.values()].map((c) => `${c.agentId}${typeof c.nodeId === "number" ? ` (node ${c.nodeId})` : ""}`);
+        const list = ring.all.map((c) => {
+            const bits = [c.role, typeof c.nodeId === "number" ? `node ${c.nodeId}` : null].filter(Boolean);
+            return bits.length ? `${c.agentId} (${bits.join(", ")})` : c.agentId;
+        });
         return list.length ? list.join(", ") : "none";
     };
+    if (want.role !== undefined) {
+        const c = ring.byRole.get(want.role);
+        if (!c) {
+            const roles = ring.all.map((x) => x.role).filter(Boolean);
+            throw new AgentSelectionError(`no key for role '${want.role}'. Known roles: ${roles.length ? roles.join(", ") : "none"}. ` +
+                `Loaded agents: ${known()}.`);
+        }
+        return c;
+    }
     if (want.agent !== undefined) {
         const c = ring.byAccount.get(want.agent);
         if (!c) {
@@ -108,12 +141,49 @@ export function selectAgent(ring, want = {}) {
     }
     if (ring.fallback)
         return ring.fallback;
-    if (ring.byAccount.size > 1) {
+    // A BROKEN KEY FILE IS WHAT REMOVED THE DEFAULT. Appended to the ambiguity
+    // error below as well as replacing the empty-ring one, because with a fleet
+    // on disk the ring is NOT empty and "pass role, agent or nodeId" is a true
+    // statement that hides a regression — a deployment that had a default and
+    // silently lost it reads as a caller bug.
+    const keyFileNote = ring.agentKeyError
+        ? ` The default agent is ALSO missing because a key file was named and could ` +
+            `not be read: ${ring.agentKeyError}`
+        : "";
+    if (ring.all.length > 1) {
         // Refuse rather than guess. Picking arbitrarily would charge a budget the
         // caller did not choose, and the payment would succeed — so the mistake
         // would surface later as a confusing balance, not as an error.
+        //
+        // `all.length`, NOT `byAccount.size`. This guard was unreachable for a
+        // fleet of virtual agents: they share an `agentId`, the map held one, and
+        // `loadKeyring` had already installed the last-written one as `fallback`
+        // on the way past. The refusal below never fired and the wrong agent paid.
         throw new AgentSelectionError(`several agents are loaded and the request named none, so there is no ` +
-            `safe default. Pass "agent" or "nodeId". Loaded agents: ${known()}.`);
+            `safe default. Pass "role", "agent" or "nodeId". Loaded agents: ${known()}.` +
+            keyFileNote);
+    }
+    // BEFORE the other-vault and nothing-configured branches. A named-but-broken
+    // key file is a cause; both of those are descriptions of an empty result, and
+    // the nothing-configured one would tell the operator to paste the secret
+    // inline — undoing the reason the file option exists.
+    if (ring.agentKeyError) {
+        throw new AgentSelectionError(`no agent key could be loaded: ${ring.agentKeyError} Fix the path or the file — ` +
+            `or unset the _FILE variable to fall back to an inline NEAR_VAULT_AGENT_KEY.` +
+            (ring.skippedOtherVault > 0
+                ? ` (${ring.skippedOtherVault} credential(s) in the keyring file belong to a ` +
+                    `different vault and were skipped.)`
+                : ""));
+    }
+    // "NOTHING CONFIGURED" AND "NOTHING FOR THIS VAULT" ARE DIFFERENT PROBLEMS.
+    // Both leave an empty ring, and the generic message sends someone to add
+    // credentials they already have — when the real fix is pointing the adapter
+    // at the vault those credentials belong to.
+    if (ring.skippedOtherVault > 0) {
+        throw new AgentSelectionError(`no agent credentials for this vault. ${ring.skippedOtherVault} credential(s) ` +
+            `were loaded but belong to a DIFFERENT vault, so they were skipped — a key ` +
+            `bound to another vault cannot spend here. Check NEAR_VAULT_CONTRACT points ` +
+            `at the vault you mean, or provision an agent for it with vault_add_role.`);
     }
     throw new AgentSelectionError("no agent credentials are configured. Set NEAR_VAULT_AGENT_ID and " +
         "NEAR_VAULT_AGENT_KEY, or point NEAR_VAULT_AGENT_KEYS at the " +

package/dist/map.d.ts

@@ -69,9 +69,47 @@ export interface DayUsage {
 export interface ApiAgent {
     agentId: string;
     walletAddress: string;
-    createdAt: string;
+    /**
+     * NULL, because the contract does not record one.
+     *
+     * `Node` has no timestamp field - id, parent, path, label, account,
+     * limits, cooldown, frozen, recipients, and nothing else. Only a payment
+     * REQUEST carries `created_at_ns`.
+     *
+     * This used to be `new Date(0).toISOString()`, which satisfied a
+     * non-nullable type by inventing "1970-01-01T00:00:00.000Z". Nothing
+     * rendered it yet, so it was not a visible bug - it was a loaded one: the
+     * first page to show an agent's age would have shipped "Created Jan 1,
+     * 1970" with complete confidence. A missing value has to BE missing, or
+     * the type system is helping you lie.
+     */
+    createdAt: string | null;
     status: "active" | "killed";
+    /** The node's own label. NO tree glyphs, no indentation. */
     displayName: string;
+    /**
+     * How deep in the budget tree this node sits. Root is 0.
+     *
+     * A NUMBER, deliberately. Depth used to be encoded into displayName as
+     * U+00A0 padding plus a box-drawing glyph, and every invisible-character
+     * bug in this project traces back to that: regexes that silently matched
+     * nothing, `btoa` throwing on the glyph, agent names carrying invisible
+     * padding into prose. A consumer that wants indentation can multiply.
+     */
+    depth: number;
+    /**
+     * This node's parent id, or null at the root.
+     *
+     * WITHOUT IT THE DASHBOARD CANNOT CHECK THE CONTRACT'S OWN RULE. Under
+     * strict allocation `set_node_caps` refuses a cap below the sum already
+     * allocated to that node's children, at EVERY depth, not just root
+     * (lib.rs:854). The policies page could only evaluate that for root,
+     * because `depth` alone says a node sits at level 2 but not WHICH level-1
+     * node it hangs from. So shrinking a mid-tree budget below its children
+     * passed validation, and the owner signed and paid gas for a transaction
+     * the contract was always going to reject.
+     */
+    parent: number | null;
     lifetimeSpent?: string;
     lifetimePayments?: number;
     walletBalance?: string | null;
@@ -82,7 +120,24 @@ export interface ApiAgent {
         perTxLimit?: string;
         cooldownSeconds?: number;
         blockUnknown?: boolean;
+        /** The EFFECTIVE allowlist — this node's own, or the nearest ancestor's. */
         allowedAddresses?: string[];
+        /**
+         * This node's OWN list, present only when it has one.
+         *
+         * Reported separately from `allowedAddresses` because the two answer
+         * different questions, and an editor needs both. `allowedAddresses` says
+         * "who can be paid from here", which is what a reader wants. This says
+         * "who is written on THIS node", which is what a writer needs — because
+         * saving a list REPLACES the inherited one rather than extending it, so
+         * an editor that only sees the effective list would show a parent's
+         * addresses and silently offer to copy them onto the child.
+         *
+         * Absent means inheriting. That is a different state from an empty list,
+         * which the contract rejects outright: `validate_recipients` fails on
+         * `is_empty()` with "1..=32 recipients, or None to inherit".
+         */
+        ownAllowedAddresses?: string[];
     } | null;
 }
 export interface Payment {
@@ -113,16 +168,6 @@ export declare function treeToApiAgents(tree: VaultNode[], budgets: Map<number,
     spent: bigint;
     count: number;
 }>): ApiAgent[];
-/**
- * Depth prefix using NON-BREAKING spaces.
- *
- * Plain spaces look right in a test assertion and vanish on screen: HTML
- * collapses leading whitespace, so depth-2 rendered identically to depth-1 and
- * the hierarchy — the entire point of the view — was invisible. The unit test
- * was green while the screen was wrong, which is why this is asserted against
- * the rendered character and not a trimmed string.
- */
-export declare function indent(depth: number, label: string): string;
 /** Mirrors the contract's `effective_recipients`: nearest ancestor with a list. */
 export declare function effectiveRecipients(n: VaultNode, byId: Map<number, VaultNode>): string[] | undefined;
 /** Settled spend per node, within RETAINED history (purge_settled removes rows). */

package/dist/map.js

@@ -23,9 +23,11 @@ export function nodeToApiAgent(n, usage, decimals) {
         // the thing this product exists to make visible.
         agentId: n.account ?? `node-${n.id}`,
         walletAddress: n.account ?? "",
-        createdAt: new Date(0).toISOString(),
+        createdAt: null,
         status: n.frozen ? "killed" : "active",
         displayName: n.label,
+        depth: 0,
+        parent: n.parent,
         dailySpent: fromBaseUnits(used, decimals),
         dailyBudgetUsedPercent: cap > 0n ? Number((used * 100n) / cap) : 0,
         walletBalance: null, // the VAULT holds the tokens; an agent account holds none
@@ -50,12 +52,21 @@ export function treeToApiAgents(tree, budgets, decimals, lifetime = new Map()) {
     const byId = new Map(tree.map((n) => [n.id, n]));
     return tree.map((n) => {
         const a = nodeToApiAgent(n, budgets.get(n.id) ?? { executed: "0", pending: "0" }, decimals);
-        a.displayName = indent(n.path.length, n.label);
+        a.depth = n.path.length;
         // The EFFECTIVE allowlist, resolved the way the contract resolves it.
         // Reporting the raw `recipients` field made every inheriting node look
         // unrestricted in the UI ("Open x402"), which is the opposite of true:
         // they inherit the root's allowlist and the contract enforces it.
-        a.policy = { ...a.policy, allowedAddresses: effectiveRecipients(n, byId) };
+        // BOTH, deliberately. `allowedAddresses` is what the contract will
+        // enforce here; `ownAllowedAddresses` is what is actually written on this
+        // node, and is undefined when it inherits. An editor that cannot tell
+        // them apart will offer to "keep" a parent's list and, by saving it,
+        // detach the child from the parent forever.
+        a.policy = {
+            ...a.policy,
+            allowedAddresses: effectiveRecipients(n, byId),
+            ownAllowedAddresses: n.recipients?.length ? n.recipients : undefined,
+        };
         const lt = lifetime.get(n.id);
         if (lt) {
             a.lifetimeSpent = fromBaseUnits(lt.spent, decimals);
@@ -64,20 +75,6 @@ export function treeToApiAgents(tree, budgets, decimals, lifetime = new Map()) {
         return a;
     });
 }
-/**
- * Depth prefix using NON-BREAKING spaces.
- *
- * Plain spaces look right in a test assertion and vanish on screen: HTML
- * collapses leading whitespace, so depth-2 rendered identically to depth-1 and
- * the hierarchy — the entire point of the view — was invisible. The unit test
- * was green while the screen was wrong, which is why this is asserted against
- * the rendered character and not a trimmed string.
- */
-export function indent(depth, label) {
-    if (depth === 0)
-        return label;
-    return `${"\u00a0".repeat(3 * (depth - 1))}└─ ${label}`;
-}
 /** Mirrors the contract's `effective_recipients`: nearest ancestor with a list. */
 export function effectiveRecipients(n, byId) {
     const chain = [...n.path, n.id].reverse(); // self first, then upward
@@ -138,9 +135,30 @@ export function requestToPayment(r, nodeLabels, decimals, delivery) {
         amount: fromBaseUnits(BigInt(r.amount), decimals),
         currency: "USDC",
         recipientAddress: r.recipient,
-        // What the agent paid FOR, which is what the memo carries. The recipient
-        // is already its own column, so echoing it adds nothing.
-        venue: r.memo || r.recipient,
+        /**
+         * THE MEMO IS REDACTED HERE, and only here.
+         *
+         * The dashboard is keyless and multi-tenant: anyone can type a vault name
+         * and read it. A memo is what the agent paid FOR — "landing page draft",
+         * "copywriting" — and that is a company's operations, legible to anyone
+         * who guesses an account id.
+         *
+         * BE EXACT ABOUT WHAT THIS DOES. The memo is ON CHAIN and public; this
+         * does not make it secret and must never be described as privacy. It
+         * removes it from the surface that turned "know how to query a NEAR RPC"
+         * into "type a name", which is a real reduction in casual exposure and
+         * nothing more. Anyone determined still has it in one view call.
+         *
+         * THE AGENT'S OWN TOOLING IS UNAFFECTED. `vault_history` in
+         * @floatonnear/mcp calls `list_requests` directly against the chain and
+         * never passes through this adapter, so an agent keeps full context on the
+         * machine its owner controls. The split is PUBLIC SURFACE vs LOCAL TOOL,
+         * not two different truths.
+         *
+         * Falls back to the recipient, which was already the behaviour for a
+         * payment with no memo — so a row still says who was paid.
+         */
+        venue: r.recipient,
         rail: railOf(r.route),
         // A Base payment is NOT "success". The contract proved it obtained a
         // signature; it cannot see whether the transaction landed, and nothing in
@@ -161,7 +179,11 @@ export function requestToPayment(r, nodeLabels, decimals, delivery) {
         // anything undelivered.
         txSignature: delivery?.baseTxHash ?? null,
         createdAt: nsToIso(r.created_at_ns),
-        prompt: r.memo || null,
+        // Redacted with `venue` above. Null rather than omitted, so a consumer
+        // that expects the field still type-checks and an absent memo and a
+        // withheld one look the same to it — the dashboard must not render a
+        // "redacted" badge that advertises which vaults have interesting ones.
+        prompt: null,
         resultUrl: null,
         // Carried for terminal failures too, so a failed row can say WHY.
         blockReason: r.status === "SETTLED" ? null : r.reason_code,

package/dist/owner-plan.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Every owner action the dashboard can prepare.
+ *
+ * This lived as a switch inline in the request handler, which meant it was
+ * unreachable from a test — and that is how `pause` and `allocation` came to
+ * be rendered as dead readout text on the Policies page despite both having
+ * contract setters and both being checked on every single payment.
+ *
+ * It stays a PURE function: no signing, no network, no key. The adapter only
+ * ever holds an agent key, which can call `request_payment` and nothing else,
+ * so an owner method can only ever be *described* here and signed in the
+ * owner's own wallet.
+ */
+export type OwnerPlanRequest = {
+    action: "caps";
+    nodeId: number;
+    dailyCap?: string;
+    perTxCap?: string;
+} | {
+    action: "cooldown";
+    nodeId: number;
+    cooldownSec?: number;
+} | {
+    action: "recipients";
+    nodeId: number;
+    recipients?: string[] | null;
+} | {
+    action: "freeze";
+    nodeId: number;
+    frozen?: boolean;
+} | {
+    action: "pause";
+    paused?: boolean;
+} | {
+    action: "allocation";
+    strict?: boolean;
+}
+/**
+ * The two teardown steps a BROWSER SIGNATURE CAN REACH.
+ *
+ * Closing a vault is six steps (see scripts/teardown-vault.mjs) and four of
+ * them need the VAULT as signer, not the owner: the gas-key withdrawal, the
+ * token's `storage_unregister`, the 33-byte stub deploy and the
+ * `DeleteAccount` itself. A wallet refuses `DeployContract` from a dApp —
+ * which is the entire reason vault CREATION goes through a factory — so a
+ * dashboard cannot finish a teardown and must not pretend to.
+ *
+ * These two it can do, and they are the two that matter most:
+ *
+ *   withdraw   deleting an account does NOT return fungible tokens, so
+ *              moving them out first is the difference between recovering
+ *              a balance and burning it
+ *   purge      the only lever that shrinks STATE, and without it the
+ *              delete is refused outright
+ */
+ | {
+    action: "withdraw";
+    token?: string;
+    amountBase?: string;
+    receiverId?: string;
+} | {
+    action: "purge";
+    beforeDay?: number;
+    limit?: number;
+}
+/**
+ * Give an agent key spending authority, AFTER the vault already exists.
+ *
+ * `add_role` is the method and `bind_virtual_agent` is not, which is not
+ * obvious and matters. Binding alone grants authority and leaves the key
+ * unable to transact: it still needs installing as a NEP-611 gas key ON
+ * the vault, and that `AddKey` would need the VAULT as signer — the same
+ * wall the teardown runs into.
+ *
+ * `add_role` does the whole thing in one owner-signed call, and the
+ * contract says why in its own comment: "THE KEY IS ADDED TO THIS
+ * ACCOUNT, BY THIS ACCOUNT. That is the only way an AddKey can reach the
+ * vault from a browser signature." The attached deposit funds the gas key
+ * and the vault nets zero.
+ *
+ * The cost is that it creates a NEW node under root rather than attaching
+ * to an existing one. That is the honest trade: the alternative is not
+ * "attach to an existing node", it is "cannot be done from a browser".
+ */
+ | {
+    action: "role";
+    label?: string;
+    dailyCap?: string;
+    perTxCap?: string;
+    cooldownSec?: number;
+    recipients?: string[] | null;
+    publicKey?: string;
+    fundingYocto?: string;
+};
+/**
+ * The action name is not one we serve.
+ *
+ * A SEPARATE type from a bad argument, because the HTTP layer has to tell
+ * them apart: it used to catch every throw from here and report
+ * `unknown action: <name>`, so a negative cooldown or a duplicate recipient
+ * was reported as a method that does not exist - the one explanation that
+ * cannot lead the caller to a fix.
+ */
+export declare class UnknownActionError extends Error {
+    constructor(action: string);
+}
+export type OwnerPlanEnv = {
+    vault: string;
+    token: string;
+    decimals: number;
+};
+export declare function planOwnerAction(b: OwnerPlanRequest, env: OwnerPlanEnv): import("@floatonnear/mcp/payloads").OwnerPayload;