@haven_ai/mcp 0.1.34-alpha.0 → 0.1.36-alpha.0

package/README.md

@@ -16,6 +16,17 @@ The server is intentionally local-only:
 - Haven's backend receives API identity plus signed payloads. It never receives
   the delegate key.
 
+## Are you an AI agent whose user has no Haven account yet?
+
+Read **`/for-agents.md`** on the Haven host your user gave you — or
+[the copy in this repository](https://github.com/d-hinders/Haven-AI/blob/dev/packages/frontend/public/for-agents.md)
+if you do not have that host yet.
+
+Your user creates the account and the passkey: those are theirs, they need a
+human, and you should never ask for their password. You can do everything else
+— including running the connector command from the setup prompt they paste you,
+and managing the account from the shell with `@haven_ai/cli`.
+
 ## Credential file
 
 Create a private JSON file from the values in the Haven agent handoff:
@@ -35,7 +46,7 @@ Create a private JSON file from the values in the Haven agent handoff:
 The Haven connector may also write split credentials:
 
 ```sh
-npx @haven_ai/mcp --identity ~/.haven/agents/<agent-id>/identity.json --signer ~/.haven/agents/<agent-id>/signer.json
+npx @haven_ai/mcp@alpha --identity ~/.haven/agents/<agent-id>/identity.json --signer ~/.haven/agents/<agent-id>/signer.json
 ```
 
 `identity.json` holds the local API key and setup metadata. `signer.json` holds
@@ -99,6 +110,22 @@ Environment variable form:
 - `haven_submit_catalog_entry`
 - `haven_list_receipts`
 
+### `idempotencyKey` is deprecated — send `idempotency_key`
+
+The tools that take an idempotency key (`haven_send`, `haven_pay_mcp_tool`,
+`haven_quote_x402`, `haven_pay_x402_quote`, `haven_pay_x402`) now accept
+**`idempotency_key`**, the spelling the hosted Haven MCP surface and every other
+Haven wire contract use. `idempotencyKey` still works and returns a deprecation
+warning; it will be removed in a future release.
+
+Send **one** of them. Sending both with different values is refused
+(`AMBIGUOUS_IDEMPOTENCY_KEY`) with nothing contacted or spent — the key decides
+whether a retry is the same payment or a second one, so Haven will not guess
+which scope you meant. Sending both with the same value is fine.
+
+The warning arrives in an optional `warnings` array on the success result. It is
+additive: a caller that ignores it sees the response it always saw.
+
 ## First-launch consent
 
 The first time the MCP server runs against a credential file it refuses to
@@ -137,7 +164,7 @@ Acknowledge in one of two ways:
 - **Sidecar file (recommended).** Re-run once with `--ack`:
 
   ```sh
-  npx @haven_ai/mcp --credentials /absolute/path/to/haven-agent.json --ack
+  npx @haven_ai/mcp@alpha --credentials /absolute/path/to/haven-agent.json --ack
   ```
 
   This writes `haven-agent.json.ack.json` next to your credential. Future
@@ -192,6 +219,6 @@ flow above instead.
 ## Non-custodial invariant
 
 Do not run this as a hosted multi-tenant signer. The expected deployment is
-`npx @haven_ai/mcp` running beside the agent runtime that owns the credential
+`npx @haven_ai/mcp@alpha` running beside the agent runtime that owns the credential
 file. Revoking the agent on-chain disables spending even if this MCP server is
 still running.

package/dist/cli.cjs

@@ -222,12 +222,16 @@ var toolSchemas = {
     asset: v3.z.enum(["ETH", "USDC"]),
     recipient: v3.z.string().min(1),
     amount: v3.z.string().min(1),
+    idempotency_key: v3.z.string().optional(),
+    /** Legacy spelling, accepted during the #2366 window. Warns; do not use. */
     idempotencyKey: v3.z.string().optional()
   },
   haven_pay_mcp_tool: {
     merchant_url: v3.z.string().url(),
     tool_name: v3.z.string().min(1),
     arguments: v3.z.record(v3.z.string(), v3.z.unknown()).optional(),
+    idempotency_key: v3.z.string().optional(),
+    /** Legacy spelling, accepted during the #2366 window. Warns; do not use. */
     idempotencyKey: v3.z.string().optional()
   },
   haven_quote_x402: {
@@ -235,10 +239,14 @@ var toolSchemas = {
     method: v3.z.string().optional(),
     headers: headersSchema,
     body: v3.z.string().optional(),
+    idempotency_key: v3.z.string().optional(),
+    /** Legacy spelling, accepted during the #2366 window. Warns; do not use. */
     idempotencyKey: v3.z.string().optional()
   },
   haven_pay_x402_quote: {
     quote: v3.z.unknown(),
+    idempotency_key: v3.z.string().optional(),
+    /** Legacy spelling, accepted during the #2366 window. Warns; do not use. */
     idempotencyKey: v3.z.string().optional()
   },
   haven_pay_x402: {
@@ -246,6 +254,8 @@ var toolSchemas = {
     method: v3.z.string().optional(),
     headers: headersSchema,
     body: v3.z.string().optional(),
+    idempotency_key: v3.z.string().optional(),
+    /** Legacy spelling, accepted during the #2366 window. Warns; do not use. */
     idempotencyKey: v3.z.string().optional()
   },
   haven_resume_x402_payment: {
@@ -298,8 +308,10 @@ var toolDescriptions = {
 function createToolHandlers(haven) {
   return {
     haven_send: async (input) => {
+      const pf = preflight("haven_send", input);
+      if ("success" in pf) return pf;
+      const { args, warnings } = pf;
       return runTool(async () => {
-        const args = objectInput("haven_send", input);
         try {
           const result = await haven.pay({
             token: args.asset,
@@ -307,7 +319,7 @@ function createToolHandlers(haven) {
             to: args.recipient,
             // #1207: was accepted by the schema but silently dropped — now
             // carried to the backend's replay contract.
-            idempotencyKey: typeof args.idempotencyKey === "string" ? args.idempotencyKey : void 0
+            idempotencyKey: args.idempotencyKey
           });
           return {
             payment_id: result.paymentId,
@@ -331,11 +343,13 @@ function createToolHandlers(haven) {
           }
           throw err;
         }
-      });
+      }, warnings);
     },
     haven_pay_mcp_tool: async (input) => {
+      const pf = preflight("haven_pay_mcp_tool", input);
+      if ("success" in pf) return pf;
+      const { args, warnings } = pf;
       return runTool(async () => {
-        const args = objectInput("haven_pay_mcp_tool", input);
         const envelope = buildMcpToolsCallEnvelope(args.tool_name, args.arguments);
         const init = {
           method: "POST",
@@ -366,18 +380,23 @@ function createToolHandlers(haven) {
           merchant_url: merchantUrl,
           ...merchantUrl !== args.merchant_url ? { merchant_url_discovered_from: args.merchant_url } : {}
         };
-      });
+      }, warnings);
     },
     haven_quote_x402: async (input) => {
-      const args = objectInput("haven_quote_x402", input);
+      const pf = preflight("haven_quote_x402", input);
+      if ("success" in pf) return pf;
+      const { args, warnings } = pf;
       try {
-        return { success: true, data: await haven.quoteX402(args.url, requestInit(args), { idempotencyKey: args.idempotencyKey }) };
+        const data = await haven.quoteX402(args.url, requestInit(args), { idempotencyKey: args.idempotencyKey });
+        return warnings.length > 0 ? { success: true, data, warnings } : { success: true, data };
       } catch (err) {
         return normalizeError(err);
       }
     },
     haven_pay_x402_quote: async (input) => {
-      const args = objectInput("haven_pay_x402_quote", input);
+      const pf = preflight("haven_pay_x402_quote", input);
+      if ("success" in pf) return pf;
+      const { args, warnings } = pf;
       const quote = args.quote;
       if (!quote || typeof quote !== "object") {
         return wrongTool(
@@ -396,14 +415,16 @@ function createToolHandlers(haven) {
       return runTool(async () => {
         const response = await haven.payX402Quote(args.quote, { idempotencyKey: args.idempotencyKey });
         return responsePayload(response);
-      });
+      }, warnings);
     },
     haven_pay_x402: async (input) => {
-      const args = objectInput("haven_pay_x402", input);
+      const pf = preflight("haven_pay_x402", input);
+      if ("success" in pf) return pf;
+      const { args, warnings } = pf;
       return runTool(async () => {
         const response = await haven.fetch(args.url, requestInit(args), { idempotencyKey: args.idempotencyKey });
         return responsePayload(response);
-      });
+      }, warnings);
     },
     haven_resume_x402_payment: async (input) => {
       const args = objectInput("haven_resume_x402_payment", input);
@@ -501,6 +522,39 @@ function isPendingApproval(status) {
 function wrongTool(code, message, suggested_tool) {
   return { success: false, code, message, suggested_tool };
 }
+function preflight(name, input) {
+  let args;
+  try {
+    args = objectInput(name, input);
+  } catch (err) {
+    return normalizeError(err);
+  }
+  const idem = resolveIdempotencyKey(args);
+  if ("success" in idem) return idem;
+  if (idem.key !== void 0) args = { ...args, idempotencyKey: idem.key };
+  return { args, warnings: idem.warnings };
+}
+function resolveIdempotencyKey(args) {
+  const modern = typeof args.idempotency_key === "string" ? args.idempotency_key : void 0;
+  const legacy = typeof args.idempotencyKey === "string" ? args.idempotencyKey : void 0;
+  if (modern !== void 0 && legacy !== void 0 && modern !== legacy) {
+    return {
+      success: false,
+      code: "AMBIGUOUS_IDEMPOTENCY_KEY",
+      message: "Both idempotency_key and idempotencyKey were sent with different values. Nothing was contacted or spent. Send exactly one \u2014 idempotency_key is the current spelling; idempotencyKey is deprecated and will be removed."
+    };
+  }
+  if (modern !== void 0) return { key: modern, warnings: [] };
+  if (legacy !== void 0) {
+    return {
+      key: legacy,
+      warnings: [
+        "idempotencyKey is deprecated and will be removed in a future release of @haven_ai/mcp. Send idempotency_key instead \u2014 it is the spelling the hosted Haven MCP surface and every other Haven wire contract use."
+      ]
+    };
+  }
+  return { warnings: [] };
+}
 function buildMcpToolsCallEnvelope(toolName, args) {
   return {
     jsonrpc: "2.0",
@@ -523,9 +577,10 @@ function requestInit(input) {
     body: input.body
   };
 }
-async function runTool(fn) {
+async function runTool(fn, warnings = []) {
   try {
-    return { success: true, data: await fn() };
+    const data = await fn();
+    return warnings.length > 0 ? { success: true, data, warnings } : { success: true, data };
   } catch (err) {
     return normalizeError(err);
   }
@@ -796,7 +851,7 @@ async function resolveHavenClient(options = {}) {
   return { client, credentials };
 }
 var MCP_NAME = "@haven_ai/mcp";
-var MCP_VERSION = "0.1.34-alpha.0";
+var MCP_VERSION = "0.1.36-alpha.0";
 var MCP_INSTRUCTIONS = [
   "Haven local MCP server: signs in-process with the delegate key it holds on",
   "this machine \u2014 the key never leaves this process. Call haven_get_agent",