@haven_ai/mcp 0.9.0-alpha.0 → 0.11.0-alpha.0

package/README.md

@@ -105,6 +105,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);
@@ -727,6 +795,10 @@ function createToolHandlers(haven) {
           price_atomic: entry.priceAtomic,
           asset: entry.asset,
           network: entry.network,
+          // #3839: same hint the hosted surface emits — a catalog hint, the
+          // live quote stays authoritative; "unknown" when nothing is recorded.
+          asset_transfer_methods: entry.assetTransferMethods ?? null,
+          funding_leg_expected: sdk.catalogFundingLegExpected(entry.assetTransferMethods),
           status: entry.status,
           verified_at: entry.verifiedAt,
           source: entry.source,
@@ -992,17 +1064,26 @@ function parseMaybeJson(text) {
     return text;
   }
 }
+var MERCHANT_OUT_OF_GAS_REASON = "settlement_wallet_out_of_gas";
+function merchantOutOfGasMessage(settlementsRemaining, failFloor) {
+  const remaining = typeof settlementsRemaining === "number" ? settlementsRemaining : null;
+  const floor = typeof failFloor === "number" ? failFloor : null;
+  const figures = remaining !== null && floor !== null ? ` It has gas for ${remaining} more settlement${remaining === 1 ? "" : "s"} and refuses new payments below ${floor} (settlements_remaining: ${remaining}, fail_floor: ${floor}).` : remaining !== null ? ` settlements_remaining: ${remaining}.` : "";
+  return `The merchant refused this call: its settlement wallet is out of gas (reason_code: ${MERCHANT_OUT_OF_GAS_REASON}).` + figures + " No payment was created. The merchant's operator must top up its settlement wallet; until then every retry is refused again. Tell the user, and re-quote once the merchant has been topped up.";
+}
 var MerchantNotReadyError = class extends Error {
+  constructor(message, nextToolOmittedReason = "the merchant needs to recover first; re-quote after the retry_after_s in the message") {
+    super(message);
+    this.nextToolOmittedReason = nextToolOmittedReason;
+    this.name = "MerchantNotReadyError";
+  }
+  nextToolOmittedReason;
   code = sdk.AgentPaymentFailureCode.MerchantNotReady;
   statusCode = 503;
   nextAction = sdk.AgentPaymentNextAction.StopAndTellUser;
   // Genuinely retryable — unlike a rejection, nothing about THIS call was
   // wrong; the merchant's own wallet needs to recover first.
   retryWithNewQuote = true;
-  constructor(message) {
-    super(message);
-    this.name = "MerchantNotReadyError";
-  }
 };
 async function merchantNotReadyErrorFor(response) {
   if (response.status !== 503) return null;
@@ -1015,7 +1096,14 @@ async function merchantNotReadyErrorFor(response) {
   if (!body || typeof body !== "object" || body.error !== "merchant_not_ready") {
     return null;
   }
-  const { reason_code, settlements_remaining, retry_after_s } = body;
+  const { reason_code, settlements_remaining, fail_floor, retry_after_s } = body;
+  if (reason_code === MERCHANT_OUT_OF_GAS_REASON) {
+    return new MerchantNotReadyError(
+      merchantOutOfGasMessage(settlements_remaining, fail_floor),
+      // Same reason the hosted runtime returns (support/mcp-context.ts).
+      "the merchant's operator must top up its settlement wallet first; re-quote after that"
+    );
+  }
   return new MerchantNotReadyError(
     "The merchant refused this call: it cannot settle a payment right now" + (typeof reason_code === "string" ? ` (reason_code: ${reason_code})` : "") + (typeof settlements_remaining === "number" ? `, settlements_remaining: ${settlements_remaining}` : "") + ". No payment was created." + (typeof retry_after_s === "number" ? ` Retry after approximately ${retry_after_s}s.` : " This is often transient; retry later.")
   );
@@ -1036,8 +1124,10 @@ function normalizeError(err) {
       next_action: err.nextAction,
       retry_with_new_quote: err.retryWithNewQuote,
       // #3103: the local runtime's one decision site — no tool can act until
-      // the merchant recovers; the message carries retry_after_s.
-      next_tool_omitted_reason: "the merchant needs to recover first; re-quote after the retry_after_s in the message"
+      // the merchant recovers. The reason rides the error (#3834): the
+      // generic one points at the message's retry_after_s, the out-of-gas
+      // one at the operator top-up.
+      next_tool_omitted_reason: err.nextToolOmittedReason
     };
   }
   if (err instanceof sdk.HavenPaymentStateError) {
@@ -1062,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 {
@@ -1304,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)
@@ -1315,7 +1427,7 @@ async function resolveHavenClient(options = {}) {
   return { client, credentials };
 }
 var MCP_NAME = "@haven_ai/mcp";
-var MCP_VERSION = "0.9.0-alpha.0";
+var MCP_VERSION = "0.11.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",