@floatonnear/mcp 0.10.1 → 0.10.3

package/dist/payloads.d.ts

@@ -43,9 +43,11 @@ export interface OwnerPayload {
     /** Non-empty only when the action is destructive or hard to undo. */
     warnings: string[];
 }
-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 planAddNode(vault: string, parent: number | null, label: string, limits: HumanTokenLimit[], cooldownSec: number, recipients: string[] | null, 
+/** The PARENT's human label, so the summary can say "under news". */
+parentName?: string | null): OwnerPayload;
+export declare function planSetNodeCaps(vault: string, nodeId: number, limits: HumanTokenLimit[], nodeName?: string | null): OwnerPayload;
+export declare function planBindAgent(vault: string, nodeId: number, accountId: string, nodeName?: string | null): OwnerPayload;
 /**
  * A whole departmental agent in ONE owner signature: node, binding, gas key.
  *
@@ -69,7 +71,7 @@ export declare function planBindAgent(vault: string, nodeId: number, accountId:
  * 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;
+export declare function planBindVirtualAgent(vault: string, nodeId: number, publicKey: string, nodeName?: string | null): OwnerPayload;
 /**
  * Revoke a virtual agent's authority.
  *
@@ -80,9 +82,9 @@ export declare function planBindVirtualAgent(vault: string, nodeId: number, publ
  * 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 planSetRecipients(vault: string, nodeId: number, recipients: string[] | null, nodeName?: string | null): OwnerPayload;
+export declare function planSetCooldown(vault: string, nodeId: number, cooldownSec: number, nodeName?: string | null): OwnerPayload;
+export declare function planFreezeNode(vault: string, nodeId: number, frozen: boolean, nodeName?: string | null): 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;
@@ -195,7 +197,7 @@ export declare function toCliCommand(p: OwnerPayload, network?: string): string;
  * `toBaseUnits` throws rather than truncating excess precision — correct here:
  * silently rounding 0.1234567 would set a threshold the owner did not choose.
  */
-export declare function planSetApprovalThreshold(vault: string, nodeId: number, amount: string | null, decimals: number): OwnerPayload;
+export declare function planSetApprovalThreshold(vault: string, nodeId: number, amount: string | null, decimals: number, nodeName?: string | null): OwnerPayload;
 /**
  * Execute a held payment.
  *

package/dist/payloads.js

@@ -105,7 +105,9 @@ function assertCooldown(cooldownSec) {
         throw new Error(`cooldown must be at most ${MAX_COOLDOWN_SEC}s (MAX_COOLDOWN_SEC)`);
     }
 }
-export function planAddNode(vault, parent, label, limits, cooldownSec, recipients) {
+export function planAddNode(vault, parent, label, limits, cooldownSec, recipients, 
+/** The PARENT's human label, so the summary can say "under news". */
+parentName) {
     if (!label || label.length > MAX_LABEL_LEN) {
         throw new Error(`label must be 1..=${MAX_LABEL_LEN} characters (MAX_LABEL_LEN)`);
     }
@@ -123,35 +125,99 @@ export function planAddNode(vault, parent, label, limits, cooldownSec, recipient
         },
         gasTgas: DEFAULT_GAS_TGAS,
         depositYocto: ONE_YOCTO,
-        summary: `Create budget node "${label}" ${parent === null ? "as the ROOT" : `under node ${parent}`}` +
+        summary: 
+        // "the main budget" for a root, and the PARENT's name otherwise — a new
+        // child is described by where it hangs, which is the one thing the
+        // person choosing it cares about.
+        `Create a "${label}" budget ` +
+            `${parent === null ? "as the main budget" : `under ${budgetName(parent, parentName)}`}` +
             ` with ${describeLimits(limits)}` +
             (cooldownSec ? `, ${cooldownSec}s cooldown between payments` : "") +
             (recipients ? `, paying only: ${recipients.join(", ")}` : `, inheriting the payee allowlist`),
         warnings: [],
     };
 }
-export function planSetNodeCaps(vault, nodeId, limits) {
+/**
+ * How a budget is NAMED to a person.
+ *
+ * WHY THIS EXISTS. Every plan summary said "node 1", and `planVoice` copies
+ * the summary verbatim into the `say` a user reads — so the product spoke the
+ * tree's internal vocabulary: "Set node 1 caps to 1/day", "Freeze node 0".
+ * A node id is the contract's primary key. It is exactly right in `args`, in
+ * `technical`, and in the unsigned payload a wallet signs, and it is a
+ * stranger's filing reference to the person who called the thing "news".
+ *
+ * The label is NOT derivable here — it lives on chain, and this module is pure
+ * and synchronously testable, which is worth keeping. So the caller resolves
+ * it and passes it in; `server.ts` already fetches the tree to check the node
+ * exists, so this costs no extra call.
+ *
+ * FALLBACKS, in order of how much they can honestly claim:
+ *   a label        -> `the "news" budget`
+ *   node 0, no label -> "the main budget"   (root is the only id with a meaning)
+ *   anything else  -> "this budget"         (true, and says nothing false)
+ *
+ * "this budget" is deliberately vague rather than wrong. The alternative was
+ * falling back to the id, which is the bug.
+ */
+/**
+ * Sentence-case a budget name for the start of a summary.
+ *
+ * `budgetName` returns a lowercase noun phrase because most of its uses sit
+ * mid-sentence ("Freeze the main budget"). A few lead the sentence, and
+ * "the main budget must wait 30s" reads like a fragment.
+ */
+function capitalise(s) {
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}
+function budgetName(nodeId, label) {
+    /**
+     * ROOT IS ALWAYS "the main budget", whatever its stored label.
+     *
+     * The contract hardcodes root's label to the literal string "root"
+     * (`lib.rs`: `label: "root".to_string()`), which is the tree's word, not a
+     * person's. `the "root" budget` would just be "node 0" wearing a hat.
+     */
+    if (nodeId === 0)
+        return "the main budget";
+    const clean = typeof label === "string" ? label.trim() : "";
+    if (clean)
+        return `the "${clean}" budget`;
+    /**
+     * NO LABEL means the tree read FAILED — `Node.label` is a required `String`
+     * on chain (`types.rs`), so every real node has one. "this budget" is
+     * deliberately vague rather than wrong; the alternative was falling back to
+     * the id, which is the thing being removed.
+     *
+     * It does cost distinguishability in that degraded case: two different
+     * budgets read the same. The node id is still in `args.node_id`, which is
+     * what the WALLET displays and what the owner actually signs, so the
+     * signature is never ambiguous even when the sentence is. Pinned by a test.
+     */
+    return "this budget";
+}
+export function planSetNodeCaps(vault, nodeId, limits, nodeName) {
     return {
         receiverId: vault,
         methodName: "set_node_caps",
         args: { node_id: nodeId, limits: limitsToArgs(limits) },
         gasTgas: DEFAULT_GAS_TGAS,
         depositYocto: ONE_YOCTO,
-        summary: `Set node ${nodeId} caps to ${describeLimits(limits)}`,
+        summary: `Update ${budgetName(nodeId, nodeName)} to ${describeLimits(limits)}`,
         warnings: [],
     };
 }
-export function planBindAgent(vault, nodeId, accountId) {
+export function planBindAgent(vault, nodeId, accountId, nodeName) {
     return {
         receiverId: vault,
         methodName: "bind_agent",
         args: { node_id: nodeId, account_id: accountId },
         gasTgas: DEFAULT_GAS_TGAS,
         depositYocto: ONE_YOCTO,
-        summary: `Let ${accountId} spend from node ${nodeId}`,
+        summary: `Let ${accountId} spend from ${budgetName(nodeId, nodeName)}`,
         warnings: [
             `${accountId} is an EXISTING account whose keys you do not control. ` +
-                `It can call request_payment with the full authority of node ${nodeId}.`,
+                `It can spend with the full authority of ${budgetName(nodeId, nodeName)}.`,
             `Prefer a VIRTUAL agent (bind_virtual_agent): it binds one key you generate ` +
                 `rather than a whole account, costs ~168 bytes, and strands nothing.`,
         ],
@@ -218,7 +284,7 @@ export function planAddRole(vault, label, limits, cooldownSec, recipients, publi
         ],
     };
 }
-export function planBindVirtualAgent(vault, nodeId, publicKey) {
+export function planBindVirtualAgent(vault, nodeId, publicKey, nodeName) {
     assertNodeId(nodeId);
     assertPublicKey(publicKey);
     return {
@@ -230,7 +296,7 @@ export function planBindVirtualAgent(vault, nodeId, publicKey) {
         // `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}`,
+        summary: `Let a new agent key spend from ${budgetName(nodeId, nodeName)}`,
         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 ` +
@@ -265,7 +331,7 @@ export function planUnbindVirtualAgent(vault, publicKey) {
         ],
     };
 }
-export function planSetRecipients(vault, nodeId, recipients) {
+export function planSetRecipients(vault, nodeId, recipients, nodeName) {
     assertRecipients(recipients);
     return {
         receiverId: vault,
@@ -274,17 +340,18 @@ export function planSetRecipients(vault, nodeId, recipients) {
         gasTgas: DEFAULT_GAS_TGAS,
         depositYocto: ONE_YOCTO,
         summary: recipients
-            ? `Node ${nodeId} may pay only: ${recipients.join(", ")}`
-            : `Node ${nodeId} inherits its payee allowlist from the nearest ancestor that sets one`,
+            ? `${capitalise(budgetName(nodeId, nodeName))} may pay only: ${recipients.join(", ")}`
+            : `${capitalise(budgetName(nodeId, nodeName))} takes its list of allowed payees from the budget above it`,
         warnings: recipients
             ? [
-                `This REPLACES the inherited allowlist for node ${nodeId} and its descendants; ` +
-                    `it does not add to it. Payees it currently inherits will stop being payable.`,
+                `This REPLACES the inherited payee list for ${budgetName(nodeId, nodeName)} and ` +
+                    `everything under it; it does not add to it. Payees it currently inherits will ` +
+                    `stop being payable.`,
             ]
             : [],
     };
 }
-export function planSetCooldown(vault, nodeId, cooldownSec) {
+export function planSetCooldown(vault, nodeId, cooldownSec, nodeName) {
     assertCooldown(cooldownSec);
     return {
         receiverId: vault,
@@ -293,21 +360,23 @@ export function planSetCooldown(vault, nodeId, cooldownSec) {
         gasTgas: DEFAULT_GAS_TGAS,
         depositYocto: ONE_YOCTO,
         summary: cooldownSec
-            ? `Node ${nodeId} must wait ${cooldownSec}s between payments`
-            : `Remove the cooldown on node ${nodeId}`,
+            ? `${capitalise(budgetName(nodeId, nodeName))} must wait ${cooldownSec}s between payments`
+            : `Remove the waiting time between payments on ${budgetName(nodeId, nodeName)}`,
         warnings: [],
     };
 }
-export function planFreezeNode(vault, nodeId, frozen) {
+export function planFreezeNode(vault, nodeId, frozen, nodeName) {
     return {
         receiverId: vault,
         methodName: "freeze_node",
         args: { node_id: nodeId, frozen },
         gasTgas: DEFAULT_GAS_TGAS,
         depositYocto: ONE_YOCTO,
-        summary: frozen ? `Freeze node ${nodeId}` : `Unfreeze node ${nodeId}`,
+        summary: frozen
+            ? `Freeze ${budgetName(nodeId, nodeName)} so nothing under it can pay until you unfreeze it`
+            : `Unfreeze ${budgetName(nodeId, nodeName)} so it can pay again`,
         warnings: frozen
-            ? [`This blocks payments from node ${nodeId} AND every node in its subtree.`]
+            ? [`This stops payments from ${budgetName(nodeId, nodeName)} and every budget under it.`]
             : [],
     };
 }
@@ -466,7 +535,7 @@ export function toCliCommand(p, network = "testnet") {
  * `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, amount, decimals) {
+export function planSetApprovalThreshold(vault, nodeId, amount, decimals, nodeName) {
     const base = amount === null ? null : toBaseUnits(amount, decimals).toString();
     return {
         receiverId: vault,
@@ -478,8 +547,8 @@ export function planSetApprovalThreshold(vault, nodeId, amount, decimals) {
         // 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`,
+            ? `Payments above ${amount} from ${budgetName(nodeId, nodeName)} will need your approval`
+            : `Stop requiring your approval on ${budgetName(nodeId, nodeName)} — payments inside the limits run unattended`,
         warnings: amount
             ? []
             : ["After this, nothing at this node waits for a human: only the caps apply."],

package/dist/roles.d.ts

@@ -4,6 +4,26 @@ export interface RoleCredential {
     role: string;
     nodeId?: number;
 }
+/**
+ * Entries belonging to this vault that the loader REJECTS, and why.
+ *
+ * `loadable` drops anything without a string `secret`, and the reasoning is
+ * sound — the adapter applies the same predicate, so listing such an entry
+ * would advertise an agent that can never be selected. But DROPPING IT
+ * SILENTLY is the same failure this file already has a memory about: the user
+ * holds a key, the tool shows nothing, and there is no way to tell "no agent"
+ * from "an agent in a shape I refuse to read".
+ *
+ * Shapes do vary in the wild: `prove-refusal.mjs` reads
+ * `privateKey ?? secret ?? agentKey`, so a file written by another path can
+ * land here unreadable. Reported, not hidden.
+ */
+export declare function listUnloadable(cfg: {
+    agentKeysPath?: string;
+    vault?: string;
+}): {
+    reason: string;
+}[];
 export declare class RoleSelectionError extends Error {
 }
 export declare function selectRole(cfg: {
@@ -43,4 +63,13 @@ export declare function listAgents(cfg: {
     agentId: string;
     role: string | null;
     nodeId?: number;
+    /**
+     * THE PUBLIC half, so a caller can ask the CHAIN about this key.
+     *
+     * It was omitted, and that omission is what made `vault_roles` unable to
+     * tell a working agent from a dead one: with no public key there is nothing
+     * to look up, so the only thing it could report was what the local file
+     * claimed. No key material — the public key is public.
+     */
+    publicKey?: string;
 }[];

package/dist/roles.js

@@ -11,6 +11,54 @@
  * as a credential is how an agent ends up "configured" and unreachable.
  */
 import { existsSync, readFileSync } from "node:fs";
+/**
+ * Entries belonging to this vault that the loader REJECTS, and why.
+ *
+ * `loadable` drops anything without a string `secret`, and the reasoning is
+ * sound — the adapter applies the same predicate, so listing such an entry
+ * would advertise an agent that can never be selected. But DROPPING IT
+ * SILENTLY is the same failure this file already has a memory about: the user
+ * holds a key, the tool shows nothing, and there is no way to tell "no agent"
+ * from "an agent in a shape I refuse to read".
+ *
+ * Shapes do vary in the wild: `prove-refusal.mjs` reads
+ * `privateKey ?? secret ?? agentKey`, so a file written by another path can
+ * land here unreadable. Reported, not hidden.
+ */
+export function listUnloadable(cfg) {
+    const path = cfg.agentKeysPath ?? ".float/agent-keys.json";
+    if (!existsSync(path))
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (e) {
+        return [{ reason: `${path} is not readable JSON (${e.message}). A UTF-8 BOM does this.` }];
+    }
+    if (!Array.isArray(parsed))
+        return [{ reason: `${path} is not a JSON array.` }];
+    const out = [];
+    for (const e of parsed) {
+        if (!e || typeof e !== "object")
+            continue;
+        const id = (e.agentId ?? e.vault);
+        // Only this vault's entries; another vault's are not this tool's business.
+        if (cfg.vault && id !== cfg.vault)
+            continue;
+        if (typeof e.agentId === "string" && typeof e.secret === "string")
+            continue; // loadable
+        const has = ["secret", "privateKey", "agentKey"].filter((k) => typeof e[k] === "string");
+        out.push({
+            reason: typeof e.agentId !== "string"
+                ? `an entry for this vault has no string 'agentId', so it cannot be matched to a vault.`
+                : `an entry has no 'secret' field${has.length ? ` (it uses '${has.join("', '")}' instead)` : ""}, ` +
+                    `which is the only field the keyring loader reads. It will never be selectable. ` +
+                    `Re-create the agent with vault_add_role.`,
+        });
+    }
+    return out;
+}
 /** Entries that `loadKeyring` would accept, nothing else. */
 function loadable(path) {
     if (!existsSync(path))
@@ -113,5 +161,6 @@ export function listAgents(cfg) {
         agentId: e.agentId,
         role: typeof e.role === "string" ? e.role : null,
         nodeId: typeof e.nodeId === "number" ? e.nodeId : undefined,
+        publicKey: typeof e.publicKey === "string" ? e.publicKey : undefined,
     }));
 }