@floatonnear/mcp 0.4.0 → 0.6.0

package/dist/agent-key.d.ts

@@ -1,10 +1,22 @@
 /**
  * The node a creation-time agent is bound to.
  *
- * ROOT_NODE in the vault. The factory binds at the root because it is the only
- * node that exists at `new` — children are added later by the owner.
+ * ONE, NOT ZERO, SINCE 2026-11-08. `new` used to bind at ROOT_NODE because it
+ * was the only node that existed — which left the FIRST agent holding the
+ * whole vault budget while every agent added later through `add_role` got a
+ * child of its own. The hierarchy only began constraining from agent #2.
+ *
+ * `new` now creates the agent its own child of root, carrying the same limits,
+ * exactly as `add_role` does. Root is 0 and that child is the first node
+ * inserted after it, so the agent is 1.
+ *
+ * PREDICTED, NOT READ, and that is unavoidable: the credential is generated
+ * before the vault exists, so there is nothing to ask. It is pinned by
+ * `binding_at_init_matches_binding_afterwards` in the contract, which asserts
+ * the node is 1 and not 0 — if `new` ever inserts another node first, that
+ * test fails rather than this constant drifting in silence.
  */
-export declare const AGENT_NODE_ID = 0;
+export declare const AGENT_NODE_ID = 1;
 export interface GeneratedAgentKey {
     publicKey: string;
     /** The role this credential was filed under, when one was given. */

package/dist/agent-key.js

@@ -21,10 +21,22 @@ import { KeyPair } from "near-api-js";
 /**
  * The node a creation-time agent is bound to.
  *
- * ROOT_NODE in the vault. The factory binds at the root because it is the only
- * node that exists at `new` — children are added later by the owner.
+ * ONE, NOT ZERO, SINCE 2026-11-08. `new` used to bind at ROOT_NODE because it
+ * was the only node that existed — which left the FIRST agent holding the
+ * whole vault budget while every agent added later through `add_role` got a
+ * child of its own. The hierarchy only began constraining from agent #2.
+ *
+ * `new` now creates the agent its own child of root, carrying the same limits,
+ * exactly as `add_role` does. Root is 0 and that child is the first node
+ * inserted after it, so the agent is 1.
+ *
+ * PREDICTED, NOT READ, and that is unavoidable: the credential is generated
+ * before the vault exists, so there is nothing to ask. It is pinned by
+ * `binding_at_init_matches_binding_afterwards` in the contract, which asserts
+ * the node is 1 and not 0 — if `new` ever inserts another node first, that
+ * test fails rather than this constant drifting in silence.
  */
-export const AGENT_NODE_ID = 0;
+export const AGENT_NODE_ID = 1;
 /**
  * Write the agent's credential where the adapter will actually find it.
  *

package/dist/create.d.ts

@@ -24,13 +24,18 @@
  * caught the drift the moment the contract shrank, which is the entire
  * reason it exists.
  *
+ * 298,819 -> 298,920 on 2026-11-08, when `new` began giving a creation-time
+ * agent its OWN child node instead of binding it to root. +101 bytes, about
+ * 0.00101 NEAR more per vault. The pin caught this one too, on the first gate
+ * run after the rebuild.
+ *
  * Mirrors `packages/create-float/res/vault.wasm`, and `create.pins.test.ts`
  * reads that file and fails if the two disagree — so a contract rebuild cannot
  * silently leave this quoting a deposit that is too small. Too small is not a
  * clean failure: CreateAccount succeeds and the vault sits below its own
  * storage requirement, bricking on the first write.
  */
-export declare const CONTRACT_BYTES = 298819;
+export declare const CONTRACT_BYTES = 298920;
 /** NEAR charges 1e19 yoctoNEAR per byte of storage. */
 export declare const STORAGE_COST_PER_BYTE: bigint;
 /**
@@ -104,10 +109,24 @@ export declare const GAS_RESERVATION_YOCTO: bigint;
 /**
  * Known factories.
  *
- * MAINNET IS DELIBERATELY ABSENT until one is deployed and verified. A wrong
- * default here does not fail safely: it sends a real user with real NEAR to
- * sign a 3.4 NEAR deposit into an account we do not control. Absent means the
- * tool asks, which is the correct behaviour for a value nobody has measured.
+ * MAINNET WAS DELIBERATELY ABSENT until one was deployed AND VERIFIED, because
+ * a wrong default here does not fail safely: it sends a real user with real
+ * NEAR to sign a ~3.4 NEAR deposit into an account we do not control.
+ *
+ * That precondition is now met. `usefloat.near` was registered on 2026-11-09
+ * (tx 2Gfh9H5T1VhEZ465NJ15CnuxFZpyMgsjchY66Lgsvntm) and the factory deployed
+ * into it, verified against the chain rather than against the deploy's own
+ * report:
+ *
+ *   local sha256                  ee925937c7b90771c477dd5e0a36770cd2c9654e…
+ *   chain code_hash (b58 -> hex)  ee925937c7b90771c477dd5e0a36770cd2c9654e…
+ *   deployed bytes fetched        163,525 — byte-for-byte equal to the artifact
+ *   get_config                    network mainnet, not paused, deposit 0.1
+ *   vault_id_for(test015.near)    test015-near.usefloat.near
+ *
+ * The name is TOP-LEVEL on purpose (DECISIONS.md 2026-11-08): it is embedded
+ * in every user's vault address permanently, because a vault is a sub-account
+ * of its factory, and `float.near` was already taken.
  */
 export declare const FACTORY_BY_NETWORK: Record<string, string | undefined>;
 export interface CreatePlanInput {
@@ -131,6 +150,26 @@ export interface CreatePlanInput {
     appUrl: string;
     /** Whether the derived account is already on chain. */
     exists?: boolean;
+    /**
+     * The EXISTING account's own `get_config.owner`, when it could be read.
+     *
+     * WHY THIS IS NOT OPTIONAL REASONING. "The account at your derived id exists,
+     * therefore it is yours" is an inference from the derivation, not a fact
+     * about the account — and `derive_prefix` IS NOT INJECTIVE. The factory says
+     * so in capitals, and `derive_prefix_collides_between_a_dot_and_a_hyphen`
+     * asserts it: `a.b.testnet` and `a-b.testnet` both land on `a-b-testnet`,
+     * because replacing the dot merges it into an alphabet that already contains
+     * the hyphen. Whoever creates first takes the id.
+     *
+     * Without reading the vault back, this tool would tell the LOSER of that
+     * collision to point their agent at the WINNER's vault. Narrow, but the
+     * failure is "you are now configured against someone else's money".
+     *
+     * `null` means the read failed, or the account is not a Float vault at all.
+     * That is a THIRD outcome and must not be flattened into either of the
+     * others — "I could not check" is not "it is yours".
+     */
+    existingOwner?: string | null;
     /**
      * The agent public key to bind at creation, if any.
      *

package/dist/create.js

@@ -24,13 +24,18 @@
  * caught the drift the moment the contract shrank, which is the entire
  * reason it exists.
  *
+ * 298,819 -> 298,920 on 2026-11-08, when `new` began giving a creation-time
+ * agent its OWN child node instead of binding it to root. +101 bytes, about
+ * 0.00101 NEAR more per vault. The pin caught this one too, on the first gate
+ * run after the rebuild.
+ *
  * Mirrors `packages/create-float/res/vault.wasm`, and `create.pins.test.ts`
  * reads that file and fails if the two disagree — so a contract rebuild cannot
  * silently leave this quoting a deposit that is too small. Too small is not a
  * clean failure: CreateAccount succeeds and the vault sits below its own
  * storage requirement, bricking on the first write.
  */
-export const CONTRACT_BYTES = 298819;
+export const CONTRACT_BYTES = 298920;
 /** NEAR charges 1e19 yoctoNEAR per byte of storage. */
 export const STORAGE_COST_PER_BYTE = 10n ** 19n;
 /**
@@ -104,14 +109,28 @@ export const GAS_RESERVATION_YOCTO = CREATE_GAS_TGAS * 10n ** 12n * 10n ** 9n;
 /**
  * Known factories.
  *
- * MAINNET IS DELIBERATELY ABSENT until one is deployed and verified. A wrong
- * default here does not fail safely: it sends a real user with real NEAR to
- * sign a 3.4 NEAR deposit into an account we do not control. Absent means the
- * tool asks, which is the correct behaviour for a value nobody has measured.
+ * MAINNET WAS DELIBERATELY ABSENT until one was deployed AND VERIFIED, because
+ * a wrong default here does not fail safely: it sends a real user with real
+ * NEAR to sign a ~3.4 NEAR deposit into an account we do not control.
+ *
+ * That precondition is now met. `usefloat.near` was registered on 2026-11-09
+ * (tx 2Gfh9H5T1VhEZ465NJ15CnuxFZpyMgsjchY66Lgsvntm) and the factory deployed
+ * into it, verified against the chain rather than against the deploy's own
+ * report:
+ *
+ *   local sha256                  ee925937c7b90771c477dd5e0a36770cd2c9654e…
+ *   chain code_hash (b58 -> hex)  ee925937c7b90771c477dd5e0a36770cd2c9654e…
+ *   deployed bytes fetched        163,525 — byte-for-byte equal to the artifact
+ *   get_config                    network mainnet, not paused, deposit 0.1
+ *   vault_id_for(test015.near)    test015-near.usefloat.near
+ *
+ * The name is TOP-LEVEL on purpose (DECISIONS.md 2026-11-08): it is embedded
+ * in every user's vault address permanently, because a vault is a sub-account
+ * of its factory, and `float.near` was already taken.
  */
 export const FACTORY_BY_NETWORK = {
     testnet: "fac.floatv4.testnet",
-    mainnet: undefined,
+    mainnet: "usefloat.near",
 };
 /** yoctoNEAR -> a NEAR string, without floating point. */
 export function yoctoToNear(y, dp = 5) {
@@ -139,8 +158,25 @@ export function buildCreatePlan(i) {
             `64-character limit. Use a named account.`);
     }
     if (known && i.exists) {
-        throw new Error(`${i.vaultId} already exists. That is this owner's vault — connect to it ` +
-            `with NEAR_VAULT_CONTRACT=${i.vaultId} rather than creating another.`);
+        // Three outcomes, deliberately not two. The old message asserted the
+        // first one for all three.
+        if (i.existingOwner && i.existingOwner === i.owner) {
+            throw new Error(`${i.vaultId} already exists and ${i.owner} owns it — confirmed by reading ` +
+                `its get_config. Connect to it with NEAR_VAULT_CONTRACT=${i.vaultId} ` +
+                `rather than creating another.`);
+        }
+        if (i.existingOwner) {
+            throw new Error(`${i.vaultId} already exists and is owned by ${i.existingOwner}, NOT by ` +
+                `${i.owner}. Do NOT point an agent at it.\n\n` +
+                `The factory derives a vault id by replacing dots with hyphens, and that ` +
+                `is not injective: "a.b.near" and "a-b.near" both derive "a-b-near", and ` +
+                `whoever created first holds the id. Create yours under a label instead, ` +
+                `which puts it at a different address.`);
+        }
+        throw new Error(`${i.vaultId} already exists, but its owner could NOT be read, so whether it ` +
+            `is yours is unknown — not assumed. It may not be a Float vault at all. ` +
+            `Check it before pointing anything at it:\n` +
+            `  near view ${i.vaultId} get_config`);
     }
     // Two different floors, and the quote must clear BOTH.
     //

package/dist/server.js

@@ -183,7 +183,57 @@ const limitShape = z
 // startup: a wrong relative path would break the server outright instead of
 // merely reporting a stale version. server.smoke.test.ts asserts the two agree,
 // so a bump cannot land with only one of them moved.
-const server = new McpServer({ name: "float", version: "0.4.0" });
+/**
+ * WHAT THE AGENT READS BEFORE IT TOUCHES A TOOL.
+ *
+ * 23 tool descriptions tell a model what each CALL does and nothing about what
+ * the product IS, when to reach for it, or which of the three trust lanes a
+ * given task belongs in. The MCP `instructions` field is the one place that
+ * can say so, and it is injected into the client's system prompt — which is
+ * why servers that set it feel like the agent "already understands the
+ * project", and why ours did not.
+ *
+ * Kept to what a model cannot infer from a tool list: the workflow order, the
+ * fact that this server never signs policy, and the three refusals that are
+ * answers rather than errors. Everything that IS inferable from a schema is
+ * left to the schema.
+ */
+const INSTRUCTIONS = `Float gives an AI agent a spending budget that a smart contract enforces, on NEAR.
+The agent's key can call exactly one method on exactly one contract: it cannot move tokens
+directly, cannot raise its own limit, and cannot reach owner functions. Those are protocol-level
+key restrictions, not policy checks.
+
+Reach for these tools when the user wants to pay for something from an agent budget, set up or
+change spending limits, see what an agent has spent, or wind a vault down.
+
+THREE LANES, and the difference is the whole design:
+  READ    vault_tree, vault_budget, vault_config, vault_roles, vault_request. No key, no risk.
+  PAY     vault_pay. The ONLY tool that signs, and only with a restricted agent key.
+  PLAN    vault_plan_*. These RETURN AN UNSIGNED PAYLOAD. This server never signs a policy
+          change; the human approves it in their own wallet. Do not describe a plan as done.
+
+WORKFLOW
+  1. No vault yet? vault_create. It needs no key and no existing vault, and returns a URL the
+     user approves in their own wallet. Never ask anyone for a private key or seed phrase.
+  2. Look before acting: vault_tree shows the budget shape, vault_budget what is left today.
+  3. Pay with vault_pay. Check the result: a refusal is a recorded outcome, not an exception.
+  4. Change policy with a vault_plan_* tool, then hand the payload to the user to sign.
+  5. Winding down is a CLI job, not a tool: npx @floatonnear/float-exit. It returns the tokens,
+     the gas-key balances and the storage deposit. vault_teardown_report says what is recoverable.
+
+REFUSALS ARE ANSWERS. Report the reason code, do not retry blindly:
+  DAILY_BUDGET         this agent's own cap is spent.
+  PARENT_DAILY_BUDGET  a SIBLING drained the shared pool; this agent's own cap may look free.
+  PER_TX_LIMIT         one payment was too large; splitting it may still be refused by the cap.
+  NO_RECIPIENTS_SET    the node pays nobody yet; that is an owner decision, via vault_plan_set_recipients.
+
+WORTH KNOWING
+  Budgets are hierarchical: a payment charges every ancestor, so a vault-wide ceiling holds even
+  when a child's cap looks free.
+  An implicit account (a 64-character hex id) cannot own a vault at all. Tell the user to use a
+  named account rather than retrying.
+  Amounts are whole tokens in these tools (1.5 means 1.5 USDC), never base units.`;
+const server = new McpServer({ name: "float", version: "0.6.0" }, { instructions: INSTRUCTIONS });
 // ----------------------------------------------------------------- reads
 server.tool("vault_tree", "Read the whole budget tree: every node, its caps, parent, bound agent account, cooldown and freeze state. No key required.", {}, async () => json(await viewFunction(cfg.rpcUrl, requireVault(), "get_tree", {})));
 server.tool("vault_budget", "Read one node's budget for a UTC day: cap, executed, in-flight (pending) and available, in human units. Omit `day` for today. No key required.", {
@@ -316,6 +366,25 @@ server.tool("vault_create", "For a user who has NO vault yet. Works out where th
             `the vault will be initialised with "${config.network}".`);
     }
     const exists = owner && vaultId ? await accountExists(rpc, vaultId) : false;
+    /**
+     * ASK THE EXISTING VAULT WHO OWNS IT, rather than inferring it from the
+     * derivation that produced the id.
+     *
+     * `derive_prefix` replaces dots with hyphens and is NOT injective:
+     * `a.b.near` and `a-b.near` both derive `a-b-near`, and the factory ships
+     * a test asserting exactly that. So "an account exists at your derived id"
+     * does not mean "it is yours" — and the message here used to say it did,
+     * which would point the loser of a collision at the winner's vault.
+     *
+     * `null` on any failure, which the planner treats as a THIRD outcome.
+     * Collapsing the error into "not yours" would be as wrong as collapsing it
+     * into "yours": a vault that is merely unreadable right now is neither.
+     */
+    const existingOwner = exists && vaultId
+        ? await viewFunction(rpc, vaultId, "get_config", {})
+            .then((c) => c?.owner ?? null)
+            .catch(() => null)
+        : null;
     // AN AGENT NEEDS A VAULT ID, and not for the transaction — the page
     // derives that from the connected wallet. It is needed for the CREDENTIAL,
     // which the adapter files under the account the key signs as. A virtual
@@ -345,6 +414,7 @@ server.tool("vault_create", "For a user who has NO vault yet. Works out where th
             paused: config.paused,
             appUrl: cfg.appUrl,
             exists,
+            existingOwner,
             agentPk: generated?.publicKey ?? null,
         });
         return json({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floatonnear/mcp",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "MCP server for the hierarchical budget vault. The agent key signs request_payment only; owner methods emit unsigned payloads for wallet approval.",
   "license": "MIT",