@haven_ai/sdk 0.0.0-dev.202609190936.6937e31 → 0.0.0-dev.202609191414.43bc74c

package/README.md

@@ -147,6 +147,23 @@ if (apiResponse.status === 402) {
 }
 ```
 
+**MCP merchants, both dialects (#3118).** A merchant may serve x402 over MCP
+in Haven's HTTP layering (HTTP 402 with the `PAYMENT-REQUIRED` header or JSON
+body, payment in `PAYMENT-SIGNATURE` / `X-PAYMENT`, settlement in
+`PAYMENT-RESPONSE`) or in the official x402 MCP transport profile (a tool
+result with `isError: true` and the `PaymentRequired` as `structuredContent`,
+payment in `params._meta["x402/payment"]`, settlement in
+`result._meta["x402/payment-response"]`). `fetch()`, `quoteX402()`,
+`quoteMcpX402()` and `completeX402MerchantCall()` handle both: a payment-
+required tool result quotes like a 402, the paid retry carries the header and
+— for a `tools/call` body — the `_meta` object, and settlement is read from the
+header first, the `_meta` second. An in-band refusal (an `isError` challenge on
+the paid retry, or `success: false`) is a rejection even under HTTP 200. An
+ordinary tool error, or a successful result that merely resembles a challenge,
+is never paid for. The tool-result challenge is read only from a response
+declaring `application/json` or `text/event-stream`; any other content type is
+passed through untouched rather than buffered.
+
 ### Idempotency: what the key guarantees, and what it costs
 
 **Omit `idempotencyKey` and the SDK synthesises one** from the merchant's

package/dist/index.cjs

@@ -1488,6 +1488,9 @@ var MCP_NOTIFICATION_TIMEOUT = 1e4;
 var MCP_PROTOCOL_VERSION = "2025-06-18";
 var MCP_ACCEPT = "application/json, text/event-stream";
 var MCP_CLIENT_INFO = { name: "haven-sdk", version: "1" };
+var MCP_X402_PAYMENT_META_KEY = "x402/payment";
+var MCP_X402_PAYMENT_RESPONSE_META_KEY = "x402/payment-response";
+var X402_RETRY_REJECTED_STATUS = 402;
 var McpMerchantTransport = class {
   merchantTimeout;
   fetchImpl;
@@ -1583,7 +1586,7 @@ var McpMerchantTransport = class {
       return response;
     }
     const message = selectJsonRpcResult(parseSseJsonRpcMessages(text));
-    if (!message) return response;
+    if (!message || !("result" in message || "error" in message)) return response;
     const body = "result" in message ? message.result : message;
     const headers = new Headers(response.headers);
     headers.set("content-type", "application/json");
@@ -1646,7 +1649,34 @@ var McpMerchantTransport = class {
       if (send.includes(name)) headers.set(name, paymentHeader);
       else headers.delete(name);
     }
-    return this.fetch(url, { ...init, headers });
+    return this.fetch(url, withMcpPaymentMeta({ ...init, headers }, paymentHeader));
+  }
+  /**
+   * #3118: read a native MCP payment-required tool result from a response
+   * WITHOUT consuming it — JSON or SSE framed. `undefined` for anything that
+   * is not an `isError: true` tool result carrying a valid `PaymentRequired`
+   * (structured content first, text fallback second), so an ordinary tool
+   * error, a successful result that merely resembles a challenge, or an
+   * unparseable body is never mistaken for a payment demand.
+   */
+  async extractToolResultChallenge(response, init) {
+    const toolResult = await this.readToolResult(response, init);
+    return toolResult ? extractMcpPaymentRequired(toolResult) : void 0;
+  }
+  /**
+   * #3118: the tool RESULT a response carries, read WITHOUT consuming it, or
+   * `undefined`. Only a JSON or SSE body is read at all (#3155 review S2):
+   * a non-402 answer used to be returned untouched, and buffering an
+   * arbitrary body — a streaming or binary paid resource — to look for a
+   * challenge would block the caller until the stream ended or the merchant
+   * timeout fired. A merchant that speaks JSON-RPC declares one of those two
+   * content types.
+   */
+  async readToolResult(response, init) {
+    if (init !== void 0 && !isJsonRpcToolsCallBody(init.body)) return void 0;
+    const contentType = (response.headers.get("content-type") ?? "").toLowerCase();
+    if (!contentType.includes("application/json") && !contentType.includes("text/event-stream")) return void 0;
+    return mcpToolResultOf(await this.readMessage(response));
   }
   async notifyInitialized(url, init, sessionId, wallet) {
     try {
@@ -1668,6 +1698,88 @@ var McpMerchantTransport = class {
     }
   }
 };
+function mcpToolResultOf(value) {
+  if (!isRecord(value)) return void 0;
+  if ("jsonrpc" in value) {
+    return isRecord(value.result) ? value.result : void 0;
+  }
+  if ("isError" in value || Array.isArray(value.content) || isRecord(value._meta)) return value;
+  return void 0;
+}
+function extractMcpPaymentRequired(toolResult) {
+  if (toolResult.isError !== true) return void 0;
+  if (isRecord(toolResult.structuredContent)) {
+    const parsed = normalizePaymentRequired(toolResult.structuredContent);
+    if (parsed) return parsed;
+  }
+  if (Array.isArray(toolResult.content)) {
+    for (const item of toolResult.content) {
+      if (!isRecord(item) || item.type !== "text" || typeof item.text !== "string") continue;
+      let candidate;
+      try {
+        candidate = JSON.parse(item.text);
+      } catch {
+        continue;
+      }
+      const parsed = normalizePaymentRequired(candidate);
+      if (parsed) return parsed;
+    }
+  }
+  return void 0;
+}
+function mcpSettlementFromToolResult(toolResult) {
+  const meta = toolResult._meta;
+  if (!isRecord(meta)) return void 0;
+  const settlement = meta[MCP_X402_PAYMENT_RESPONSE_META_KEY];
+  if (!isRecord(settlement) || typeof settlement.success !== "boolean") return void 0;
+  return {
+    success: settlement.success,
+    ...typeof settlement.transaction === "string" ? { transaction: settlement.transaction } : {},
+    ...typeof settlement.network === "string" ? { network: settlement.network } : {},
+    ...typeof settlement.payer === "string" ? { payer: settlement.payer } : {},
+    ...typeof settlement.errorReason === "string" ? { errorReason: settlement.errorReason } : {}
+  };
+}
+function withMcpPaymentMeta(init, paymentHeader) {
+  const request = parseJsonRpcToolsCall(init.body);
+  if (!request) return init;
+  let envelope;
+  try {
+    envelope = decodeBase64Json(paymentHeader);
+  } catch {
+    return init;
+  }
+  if (!isRecord(envelope)) return init;
+  const params = request.params;
+  const existingMeta = isRecord(params._meta) ? params._meta : {};
+  return {
+    ...init,
+    body: JSON.stringify({
+      ...request,
+      params: { ...params, _meta: { ...existingMeta, [MCP_X402_PAYMENT_META_KEY]: envelope } }
+    })
+  };
+}
+function encodeMcpSettlementReceipt(settlement) {
+  return encodeBase64Json(settlement);
+}
+function parseJsonRpcToolsCall(body) {
+  if (typeof body !== "string") return void 0;
+  let request;
+  try {
+    request = JSON.parse(body);
+  } catch {
+    return void 0;
+  }
+  if (!isRecord(request) || request.method !== "tools/call" || !isRecord(request.params)) return void 0;
+  return request;
+}
+function isJsonRpcToolsCallBody(body) {
+  return parseJsonRpcToolsCall(body) !== void 0;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 async function captureMerchantResponse(response) {
   const merchant_body = await response.text().catch(() => "");
   return {
@@ -2821,7 +2933,11 @@ var MerchantCompletion = class {
       initialInit,
       receipt.paymentHeader
     );
-    if (!retryResponse.ok) {
+    const toolResult = retryResponse.ok ? await this.merchantTransport.readToolResult(retryResponse) : void 0;
+    const inBandChallenge = toolResult ? extractMcpPaymentRequired(toolResult) : void 0;
+    const metaSettlement = toolResult ? mcpSettlementFromToolResult(toolResult) : void 0;
+    const inBandRejection = inBandChallenge !== void 0 || metaSettlement?.success === false;
+    if (!retryResponse.ok || inBandRejection) {
       const merchant = await captureMerchantResponse(retryResponse);
       await this.recordRetryRejected({
         rail: "x402",
@@ -2836,7 +2952,7 @@ var MerchantCompletion = class {
       });
       throw new HavenApiError(
         "x402 retry failed after Haven funded the delegate wallet; reconciliation may be required.",
-        merchant.merchant_status,
+        inBandRejection ? X402_RETRY_REJECTED_STATUS : merchant.merchant_status,
         {
           marker: "x402_retry_rejected_after_funding",
           payment_id: receipt.paymentId,
@@ -2848,7 +2964,10 @@ var MerchantCompletion = class {
         }
       );
     }
-    const merchantSettlement = parseMerchantSettlement(retryResponse.headers.get("PAYMENT-RESPONSE"));
+    const headerReceipt = retryResponse.headers.get("PAYMENT-RESPONSE");
+    const protocolReceiptHeader = headerReceipt ?? (metaSettlement ? encodeMcpSettlementReceipt(metaSettlement) : void 0);
+    const protocolReceiptHeaderName = headerReceipt ? "PAYMENT-RESPONSE" : metaSettlement ? `_meta.${MCP_X402_PAYMENT_RESPONSE_META_KEY}` : void 0;
+    const merchantSettlement = parseMerchantSettlement(protocolReceiptHeader ?? null);
     if (receipt.merchant && merchantSettlement.settlementTxHash) {
       receipt.merchant.settlementTxHash = merchantSettlement.settlementTxHash;
       receipt.merchant.settlementExplorerUrl = buildExplorerUrl(
@@ -2866,8 +2985,8 @@ var MerchantCompletion = class {
       selectedPayment: receipt.accepted,
       paymentProofHeaderName: x402PaymentHeaderNamesSent(receipt.paymentHeader),
       paymentProofHeader: receipt.paymentHeader,
-      protocolReceiptHeaderName: "PAYMENT-RESPONSE",
-      protocolReceiptHeader: retryResponse.headers.get("PAYMENT-RESPONSE") ?? void 0
+      protocolReceiptHeaderName,
+      protocolReceiptHeader
     });
     await this.reportMerchantReceipt(receipt.paymentId, retryResponse);
     return retryResponse;
@@ -3842,6 +3961,11 @@ var HavenClient = class {
     const request = snapshotX402Request(url, initialInit);
     const response = await this.merchantTransport.fetch(url, initialInit);
     if (response.status !== 402) {
+      const toolResultChallenge = await this.merchantTransport.extractToolResultChallenge(response, initialInit);
+      if (toolResultChallenge) {
+        const mcpTransport2 = await this.merchantTransport.detect(url, toolResultChallenge, response);
+        return buildX402Quote(toolResultChallenge, request, options.idempotencyKey, mcpTransport2);
+      }
       let body;
       try {
         body = await response.clone().json();
@@ -4008,10 +4132,11 @@ var HavenClient = class {
     return this.merchantCompletion.retryRequest(url ?? paymentRequired.resource.url, initialInit, paymentRequired, receipt);
   }
   /**
-   * Fetch wrapper that automatically handles HTTP 402 responses.
+   * Fetch wrapper that automatically handles HTTP 402 responses — and, since
+   * #3118, a native-MCP payment-required tool result answered under HTTP 200.
    *
-   * Works like the standard `fetch()` but intercepts 402 responses,
-   * pays via x402 through Haven, and retries the request.
+   * Works like the standard `fetch()` but intercepts 402 responses (or that
+   * tool-result challenge), pays via x402 through Haven, and retries the request.
    *
    * ```ts
    * const response = await haven.fetch('https://paid-api.com/data')
@@ -4019,8 +4144,9 @@ var HavenClient = class {
    * ```
    *
    * **MCP-over-x402 auto-handshake (issue #315):** when the endpoint is
-   * MCP-shaped — the URL path ends in `/mcp`, or the 402 body carries a
-   * Coinbase Bazaar `extensions.bazaar` block — the SDK runs the MCP
+   * MCP-shaped — the URL path ends in `/mcp`, or the 402 body (or, since
+   * #3118, the tool-result challenge) carries a Coinbase Bazaar
+   * `extensions.bazaar` block — the SDK runs the MCP
    * `initialize` handshake, threads the resulting `mcp-session-id`,
    * `Accept: application/json, text/event-stream`, and `x402-wallet` headers
    * through every request, and collapses SSE responses to the JSON-RPC
@@ -4038,16 +4164,23 @@ var HavenClient = class {
     let requestInit = withX402Wallet(init, x402PayerAddress(this.delegateAddress, this.x402Wallet));
     if (mcpSessionId) requestInit = this.merchantTransport.withSessionHeaders(requestInit, mcpSessionId);
     const response = await this.merchantTransport.fetch(url, requestInit);
-    if (response.status !== 402) {
-      return mcpSessionId ? this.merchantTransport.surfaceResult(response) : response;
-    }
     let paymentRequired;
-    try {
-      paymentRequired = await parsePaymentRequiredResponse(response);
-    } catch {
-      return response;
+    let nativeChallenge = false;
+    if (response.status !== 402) {
+      const toolResultChallenge = await this.merchantTransport.extractToolResultChallenge(response, requestInit);
+      if (!toolResultChallenge) {
+        return mcpSessionId ? this.merchantTransport.surfaceResult(response) : response;
+      }
+      paymentRequired = toolResultChallenge;
+      nativeChallenge = true;
+    } else {
+      try {
+        paymentRequired = await parsePaymentRequiredResponse(response);
+      } catch {
+        return response;
+      }
     }
-    if (!mcpSessionId && await this.merchantTransport.hasBazaarExtension(response)) {
+    if (!mcpSessionId && (paymentRequired.extensions?.bazaar != null || await this.merchantTransport.hasBazaarExtension(response))) {
       mcpSessionId = await this.merchantTransport.initialize(url, init);
       if (mcpSessionId) requestInit = this.merchantTransport.withSessionHeaders(requestInit, mcpSessionId);
     }
@@ -4069,7 +4202,7 @@ var HavenClient = class {
       throw err;
     }
     const retryResponse = await this.merchantCompletion.retryRequest(url, requestInit, paymentRequired, receipt);
-    return mcpSessionId ? this.merchantTransport.surfaceResult(retryResponse) : retryResponse;
+    return mcpSessionId || nativeChallenge ? this.merchantTransport.surfaceResult(retryResponse) : retryResponse;
   }
   /**
    * Deliver an already-signed x402 payment header to the merchant and return
@@ -4130,9 +4263,7 @@ var HavenClient = class {
     let requestInit = withX402Wallet(input.init, x402Wallet) ?? {};
     if (mcpSessionId) requestInit = this.merchantTransport.withSessionHeaders(requestInit, mcpSessionId);
     const response = await this.merchantTransport.deliverPayment(input.url, requestInit, input.paymentHeader);
-    const surfaced = mcpSessionId ? await this.merchantTransport.surfaceResult(response) : response;
-    const protocolReceiptHeader = surfaced.headers.get("PAYMENT-RESPONSE") ?? void 0;
-    const settlement = parseMerchantSettlement(protocolReceiptHeader ?? null);
+    const surfaced = await this.merchantTransport.surfaceResult(response);
     const text = await surfaced.text();
     let body;
     try {
@@ -4140,8 +4271,16 @@ var HavenClient = class {
     } catch {
       body = text;
     }
+    const toolResult = mcpToolResultOf(body);
+    const inBandChallenge = toolResult ? extractMcpPaymentRequired(toolResult) : void 0;
+    const metaSettlement = toolResult ? mcpSettlementFromToolResult(toolResult) : void 0;
+    const headerReceipt = surfaced.headers.get("PAYMENT-RESPONSE") ?? void 0;
+    const protocolReceiptHeaderName = headerReceipt ? "PAYMENT-RESPONSE" : metaSettlement ? `_meta.${MCP_X402_PAYMENT_RESPONSE_META_KEY}` : void 0;
+    const protocolReceiptHeader = headerReceipt ?? (metaSettlement ? encodeMcpSettlementReceipt(metaSettlement) : void 0);
+    const settlement = parseMerchantSettlement(protocolReceiptHeader ?? null);
+    const merchantAccepted = surfaced.ok && inBandChallenge === void 0 && metaSettlement?.success !== false;
     let evidenceOutcome;
-    if (!surfaced.ok) {
+    if (!merchantAccepted) {
       if (!input.noFundingLeg && fundingTxHash) {
         await this.merchantCompletion.recordRetryRejected({
           rail: "x402",
@@ -4171,7 +4310,7 @@ var HavenClient = class {
           merchantStatus: surfaced.status,
           paymentProofHeaderName: x402PaymentHeaderNamesSent(input.paymentHeader),
           paymentProofHeader: input.paymentHeader,
-          protocolReceiptHeaderName: protocolReceiptHeader ? "PAYMENT-RESPONSE" : void 0,
+          protocolReceiptHeaderName,
           protocolReceiptHeader
         });
       }
@@ -4179,9 +4318,10 @@ var HavenClient = class {
     }
     return {
       status: surfaced.status,
-      ok: surfaced.ok,
+      ok: merchantAccepted,
       body,
-      settlementTxHash: settlement.settlementTxHash ?? void 0,
+      // #3155 review S3: a transaction beside a rejection is not a settlement.
+      settlementTxHash: merchantAccepted ? settlement.settlementTxHash ?? void 0 : void 0,
       evidenceOutcome
     };
   }
@@ -4371,12 +4511,12 @@ var toolDescriptions = {
   payX402OneShot: {
     summary: "Fetch an x402 paid HTTP resource in a single call. Handles the full probe -> pay -> retry round trip and returns the merchant response.",
     selectionGuidance: "Prefer this over the quote+pay split when the agent just wants the paid resource and does not need to inspect the price first. If you already have a quote from haven_quote_x402, use haven_pay_x402_quote instead. Do not use for read-only allowance, budget, spend-limit, remaining-amount, reset-period, or what-can-I-spend questions; use the allowance lookup tool instead.",
-    behavior: "Calls the URL, parses any HTTP 402 x402 challenge, signs the payment locally, then retries the original request with the signed payment header (sent under PAYMENT-SIGNATURE, plus the legacy X-PAYMENT on the EIP-3009 path only) and returns the merchant response. Settlement is either direct account-to-merchant with no funding leg, or a bridge that first redeems the agent's budget delegation to fund the delegate wallet for an EIP-3009 authorization. A payment outside the on-chain budget is declined before any money moves; nothing is queued for a human to approve later. If the resource returns a non-402 status, returns it unchanged without contacting Haven.",
+    behavior: "Calls the URL, parses any HTTP 402 x402 challenge (or, since #3118, a native-MCP payment-required tool result under HTTP 200), signs the payment locally, then retries the original request with the signed payment header (sent under PAYMENT-SIGNATURE, plus the legacy X-PAYMENT on the EIP-3009 path only) and returns the merchant response. Settlement is either direct account-to-merchant with no funding leg, or a bridge that first redeems the agent's budget delegation to fund the delegate wallet for an EIP-3009 authorization. A payment outside the on-chain budget is declined before any money moves; nothing is queued for a human to approve later. If the resource returns a non-402 status with no payment-required tool result, returns it unchanged without contacting Haven.",
     nextActionGuidance: "Preserve the returned resume_state or paymentId \u2014 either identifies this payment if you need to ask about it later. This tool performs the merchant retry itself, so do not wait on a signal while the call is in flight. If the process crashes after this call and a later haven_get_payment_status reports nextAction=retry_original_x402_request, Haven's funding leg confirmed but no merchant response was ever recorded \u2014 call the resume tool with the preserved resume_state or payment_id instead of paying again. If the response carries phase=insufficient_funds and nextAction=fund_account_or_raise_allowance, the payment cannot be retried until the account is funded or the agent budget raised \u2014 stop and tell the user the shortfall reported on the response."
   },
   resumeX402: {
     summary: "Resume an x402 payment whose Haven-side authorization already succeeded but whose merchant retry did not complete.",
-    behavior: "Accepts either resume_state or payment_id, validates the original x402 details against the authorized Haven funding, and retries the merchant request with the signed payment header (sent under PAYMENT-SIGNATURE, plus the legacy X-PAYMENT on the EIP-3009 path only). No new Haven payment is created.",
+    behavior: "Accepts either resume_state or payment_id, validates the x402 details against the authorized funding, and retries the merchant request with the signed payment header (PAYMENT-SIGNATURE, plus legacy X-PAYMENT on EIP-3009 only; also params._meta on an MCP tools/call body). No new Haven payment is created.",
     nextActionGuidance: "Only call this after haven_get_payment_status reports nextAction=retry_original_x402_request \u2014 that means Haven's funding leg confirmed but no merchant response was ever recorded, most often because the process crashed between funding and the merchant retry. Any other nextAction reports a conflict instead of retrying, so do not call this speculatively. Do not start a new merchant session and do not pay again \u2014 that would pay twice for one resource."
   },
   // #1328: quoteMpp / payMpp / resumeMpp (the mpp_demo challenge/quote/resume