@haven_ai/mcp 0.10.0-alpha.0 → 0.12.0-alpha.0

package/README.md

@@ -54,9 +54,13 @@ the whole difference between the two paragraphs.
 The Haven connector may also write split credentials:
 
 ```sh
-npx @haven_ai/mcp@alpha --identity ~/.haven/agents/<agent-id>/identity.json --signer ~/.haven/agents/<agent-id>/signer.json
+npx @haven_ai/mcp@alpha --identity ~/.haven/agents/<slug>/identity.json --signer ~/.haven/agents/<slug>/signer.json
 ```
 
+A default setup names that directory from the wiring slug (the `haven-<slug>`
+pair, #3737); only a `--bare` run, or a `--replace` without `--name`, names it
+by the agent id instead.
+
 `identity.json` holds the local API key and setup metadata. `signer.json` holds
 the delegate key. Both files stay on the user's machine.
 
@@ -105,6 +109,44 @@ Environment variable form:
 }
 ```
 
+## Per-chain RPC endpoints
+
+When an x402 payment hits an idempotency collision, the server can tell a
+finished payment from a stuck one only by reading the agent delegate's balance
+on chain. Without an RPC endpoint it cannot, so every collision is refused as
+`unverifiable`, including the recoverable case where the delegate is still
+funded and the payment could resume.
+
+Give the server a read-only RPC endpoint per chain and it can check:
+
+```json
+{
+  "mcpServers": {
+    "haven": {
+      "command": "npx",
+      "args": ["@haven_ai/mcp"],
+      "env": {
+        "HAVEN_CREDENTIALS": "/absolute/path/to/haven-agent.json",
+        "HAVEN_RPC_URL_8453": "https://your-rpc.example/v3/key",
+        "HAVEN_RPC_URL_84532": "https://your-rpc.example/sepolia/v3/key"
+      }
+    }
+  }
+}
+```
+
+One variable per chain: the suffix is the chain id (`8453` is Base mainnet,
+`84532` is Base Sepolia). An unset variable changes nothing: collisions are
+refused exactly as before. A value whose suffix is not a positive integer is
+ignored, and a malformed or unreachable URL degrades to the same refusal.
+Nothing is written to stdout in any of these cases, because stdout is the
+protocol channel.
+
+With an endpoint wired for the payment's chain, a collision where the delegate
+is still funded resumes: the balance says the merchant never pulled the
+payment, so the server mints a fresh authorization. A drained delegate still
+refuses, with a settled basis, because the payment already completed.
+
 ## Tools
 
 - `haven_quote_x402`

package/dist/cli.cjs

@@ -238,6 +238,18 @@ async function warnIfCredentialFilePermissive(path, log = (message) => process.s
     );
   }
 }
+function chainRpcsFromEnv(env) {
+  const chainRpcs = {};
+  for (const [name, value] of Object.entries(env)) {
+    const match = /^HAVEN_RPC_URL_(\d+)$/.exec(name);
+    if (!match) continue;
+    const chainId = Number.parseInt(match[1], 10);
+    if (!Number.isSafeInteger(chainId) || chainId <= 0) continue;
+    const url = value?.trim();
+    if (url) chainRpcs[chainId] = url;
+  }
+  return chainRpcs;
+}
 var TASK_BUDGET_MIN_SIGNER_VERSION = "0.6.0-alpha.0";
 var SIGNER_CAPABILITY_KEY = "haven/signer-compatibility";
 function taskSignerCompatibilityNotice() {
@@ -250,6 +262,20 @@ function taskSignerCompatibilityNotice() {
   };
 }
 var headersSchema = v3.z.record(v3.z.string(), v3.z.string()).optional();
+function selectQuoteOption(accepts, agent) {
+  if (agent.executionRail === "delegation") {
+    const erc7710 = sdk.selectErc7710PaymentOption(accepts);
+    if (erc7710) return erc7710;
+  }
+  return sdk.selectStandardPaymentOption(accepts);
+}
+function humanDecimalToAtomic(human, decimals) {
+  const match = /^([0-9]+)(?:\.([0-9]+))?$/.exec(human);
+  if (!match) return null;
+  const fraction = match[2] ?? "";
+  if (fraction.length > decimals) return null;
+  return BigInt(match[1] + fraction.padEnd(decimals, "0"));
+}
 var toolSchemas = {
   haven_send: {
     asset: v3.z.enum(["ETH", "USDC"]),
@@ -281,6 +307,17 @@ var toolSchemas = {
     headers: headersSchema,
     body: v3.z.string().optional(),
     idempotency_key: v3.z.string().optional(),
+    /**
+     * #3967: the price the agent EXPECTS, in whole tokens ("0.10" = 0.1 USDC),
+     * compared against the amount of the option pay will actually select. A
+     * mismatch stops the agent — the same stop signals the hosted quote
+     * carries. Local parity: a hosted-only input would split the two tools'
+     * contracts. Same shape and name as the hosted surface's.
+     */
+    expected_amount: v3.z.string().regex(
+      /^[0-9]+(\.[0-9]+)?$/,
+      'expected_amount must be a plain decimal amount in whole tokens, e.g. "0.10"'
+    ).optional(),
     /** REMOVED (#3411): declared only so the resolver can refuse it by name, never accepted. */
     idempotencyKey: v3.z.string().optional().describe("REMOVED (#3411): refused \u2014 send idempotency_key")
   },
@@ -627,8 +664,39 @@ function createToolHandlers(haven) {
       const pf = preflight("haven_quote_x402", input);
       if ("success" in pf) return pf;
       const { args, warnings } = pf;
+      const agentPromise = args.expected_amount !== void 0 ? haven.getAgent().then(
+        (a) => a,
+        () => void 0
+      ) : null;
       try {
         const data = await haven.quoteX402(args.url, requestInit(args), { idempotencyKey: args.resolvedIdempotencyKey });
+        if (args.expected_amount !== void 0) {
+          const agent = agentPromise ? await agentPromise : void 0;
+          const option = agent ? selectQuoteOption(data.paymentRequired.accepts, agent) : null;
+          if (option && data.decimals !== null) {
+            const expectedAtomic = humanDecimalToAtomic(args.expected_amount, data.decimals);
+            let optionAmount = null;
+            try {
+              optionAmount = BigInt(sdk.x402AuthorizationAmount(option));
+            } catch {
+              optionAmount = null;
+            }
+            if (optionAmount !== null && expectedAtomic !== null) {
+              const priceDiffers = optionAmount !== expectedAtomic;
+              const payload = {
+                ...data,
+                price_differs_from_expected: priceDiffers,
+                ...priceDiffers ? {
+                  safe_to_continue: false,
+                  next_action: sdk.AgentPaymentNextAction.StopAndTellUser,
+                  next_tool_omitted_reason: "no Haven tool follows: the quoted price does not match the stated expectation \u2014 the user decides before any payment",
+                  reason: `The merchant's quoted price (${data.amount} ${data.asset}) does not match the expected price (${args.expected_amount}) stated with this quote. Stop and tell the user before any payment; do not re-quote, re-pay, or poll. If the x402 challenge itself is wrong and nothing has been paid via x402 on this invoice, the invoice's own deposit address MAY be an alternative \u2014 but only with the user's explicit go-ahead, never automatically, and never once anything has been paid via x402.`
+                } : {}
+              };
+              return warnings.length > 0 ? { success: true, data: payload, warnings } : { success: true, data: payload };
+            }
+          }
+        }
         return warnings.length > 0 ? { success: true, data, warnings } : { success: true, data };
       } catch (err) {
         return normalizeError(err);
@@ -1084,6 +1152,24 @@ function normalizeError(err) {
       message: err.message
     };
   }
+  if (err instanceof sdk.MerchantEgressRefusedError && !err.beforeRequest && err.paymentId) {
+    const noFundingLeg = err.settlementScheme === "erc7710";
+    const nextAction = noFundingLeg ? sdk.AgentPaymentNextAction.CheckStatusLater : sdk.AgentPaymentNextAction.SweepStrandedFunds;
+    return {
+      success: false,
+      code: err.code,
+      message: err.message,
+      statusCode: err.statusCode,
+      paymentId: err.paymentId,
+      status: "merchant_unresponsive_after_funding",
+      phase: noFundingLeg ? "not_delivered" : "funded_but_unsettled",
+      nextAction,
+      next_action: nextAction,
+      next_tool: "haven_get_payment_status",
+      next_arguments: { payment_id: err.paymentId },
+      suggested_tool: "haven_get_payment_status"
+    };
+  }
   if (err instanceof sdk.HavenApiError) {
     const body = err.body;
     return {
@@ -1326,10 +1412,14 @@ async function resolveHavenClient(options = {}) {
     signerPath: options.signerPath
   } : void 0;
   const credentials = options.credentials ?? await loadCredentials(credentialSource);
+  const chainRpcs = chainRpcsFromEnv(process.env);
   const client = new sdk.HavenClient({
     apiKey: credentials.apiKey,
     delegateKey: credentials.delegateKey,
     baseUrl: credentials.apiUrl,
+    // Only added when non-empty so the unset-variable construction is byte-for-byte
+    // today's: the SDK defaults `chainRpcs` to `{}` either way.
+    ...Object.keys(chainRpcs).length > 0 ? { chainRpcs } : {},
     // #3303: name this package, not the SDK inside it, so the backend's
     // update hint and refusal speak about what the user actually installed.
     clientIdentity: sdk.havenClientIdentity(MCP_NAME, MCP_VERSION)
@@ -1337,7 +1427,7 @@ async function resolveHavenClient(options = {}) {
   return { client, credentials };
 }
 var MCP_NAME = "@haven_ai/mcp";
-var MCP_VERSION = "0.10.0-alpha.0";
+var MCP_VERSION = "0.12.0-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",