@haven_ai/sdk 0.1.9 → 0.1.11-alpha.0

package/dist/index.cjs

@@ -37,7 +37,14 @@ var AgentPaymentPhase = {
    * is no approval that would fix this — the originating Safe needs more
    * funds or the agent's per-token allowance needs to be raised first.
    */
-  InsufficientFunds: "insufficient_funds"
+  InsufficientFunds: "insufficient_funds",
+  /**
+   * Haven's funding leg (Safe → delegate) confirmed on-chain, but the
+   * merchant rejected the x402 retry. The delegate wallet may hold stranded
+   * USDC that was never settled to the merchant. The agent should stop, tell
+   * the user, and wait for the sweep flow to reclaim the funds.
+   */
+  FundedButUnsettled: "funded_but_unsettled"
 };
 var AgentPaymentNextAction = {
   /** Sign with the delegate key and submit the payment to Haven. */
@@ -61,7 +68,13 @@ var AgentPaymentNextAction = {
    * the agent's per-token allowance needs to be raised before the payment
    * can succeed. A user approval will not fix this state on its own.
    */
-  FundSafeOrRaiseAllowance: "fund_safe_or_raise_allowance"
+  FundSafeOrRaiseAllowance: "fund_safe_or_raise_allowance",
+  /**
+   * The delegate wallet may hold funds that were sent from the Safe but never
+   * settled to the merchant. The wallet owner should initiate a sweep to
+   * return those funds to the originating Safe.
+   */
+  SweepStrandedFunds: "sweep_stranded_funds"
 };
 var AgentPaymentRail = {
   /** Standard Haven payment from the user's Safe through an approved delegate allowance. */
@@ -93,7 +106,8 @@ var AgentPaymentPhaseDescriptions = {
   [AgentPaymentPhase.Rejected]: "The wallet owner rejected the request; the agent should stop and tell the user.",
   [AgentPaymentPhase.Expired]: "The payment or approval request expired before completion.",
   [AgentPaymentPhase.Failed]: "Haven could not complete the payment; the agent should stop and surface the failure.",
-  [AgentPaymentPhase.InsufficientFunds]: "Pre-flight check determined the delegate balance plus the remaining on-chain allowance cannot cover the requested amount, so no payment was created. The originating Safe must be funded or the agent allowance raised before retrying."
+  [AgentPaymentPhase.InsufficientFunds]: "Pre-flight check determined the delegate balance plus the remaining on-chain allowance cannot cover the requested amount, so no payment was created. The originating Safe must be funded or the agent allowance raised before retrying.",
+  [AgentPaymentPhase.FundedButUnsettled]: "Haven's funding leg confirmed on-chain but the merchant rejected the x402 retry. The delegate wallet may hold stranded funds. The agent should stop and wait for the wallet owner to sweep the stranded funds back to the Safe."
 };
 var AgentPaymentNextActionDescriptions = {
   [AgentPaymentNextAction.SignAndSubmitPayment]: "Sign with the delegate key and submit the payment to Haven.",
@@ -104,7 +118,8 @@ var AgentPaymentNextActionDescriptions = {
   [AgentPaymentNextAction.RetryOriginalX402Request]: "Resume this payment id and retry the original x402 request with the merchant payment header.",
   [AgentPaymentNextAction.StopAndTellUser]: "Stop retrying this payment and tell the user what happened.",
   [AgentPaymentNextAction.RequestAgainIfUserStillWantsIt]: "Ask again only if the user still wants the payment after expiry.",
-  [AgentPaymentNextAction.FundSafeOrRaiseAllowance]: "Stop and tell the user that the originating Safe needs to be funded or the agent allowance raised before the payment can succeed."
+  [AgentPaymentNextAction.FundSafeOrRaiseAllowance]: "Stop and tell the user that the originating Safe needs to be funded or the agent allowance raised before the payment can succeed.",
+  [AgentPaymentNextAction.SweepStrandedFunds]: "Tell the user that funds may be stranded in the delegate wallet and prompt them to initiate a sweep in Haven to return them to the originating Safe."
 };
 var AgentPaymentRailDescriptions = {
   [AgentPaymentRail.Direct]: "Standard Haven payment from the user-controlled Safe through an approved delegate allowance.",
@@ -218,16 +233,52 @@ function verifySignature(hash, signature, expectedAddress) {
     return false;
   }
 }
-var BASE_USDC_ADDRESS = "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913";
-var X402_IDEMPOTENCY_BUCKET_MS = 3e5;
-var DECIMAL_ATOMIC_AMOUNT_RE = /^[0-9]+$/;
+
+// src/base64.ts
+function normalizeBase64(value) {
+  const standard = value.replace(/-/g, "+").replace(/_/g, "/");
+  const remainder = standard.length % 4;
+  return remainder === 0 ? standard : standard + "=".repeat(4 - remainder);
+}
+function encodeBase64Utf8(value) {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(value, "utf8").toString("base64");
+  }
+  const bytes = new TextEncoder().encode(value);
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+function decodeBase64Utf8(value) {
+  const normalized = normalizeBase64(value);
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(normalized, "base64").toString("utf8");
+  }
+  const binary = atob(normalized);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return new TextDecoder().decode(bytes);
+}
+function encodeBase64Json(value) {
+  return encodeBase64Utf8(JSON.stringify(value));
+}
 function decodeBase64Json(value, label) {
   try {
-    return JSON.parse(atob(value));
-  } catch {
-    throw new Error(`Failed to decode ${label}`);
+    return JSON.parse(decodeBase64Utf8(value));
+  } catch (err) {
+    if (label) throw new Error(`Failed to decode ${label}`);
+    throw err;
   }
 }
+
+// src/x402.ts
+var BASE_USDC_ADDRESS = "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913";
+var X402_IDEMPOTENCY_BUCKET_MS = 3e5;
+var DECIMAL_ATOMIC_AMOUNT_RE = /^[0-9]+$/;
 function isPositiveDecimalAtomicAmount(value) {
   return DECIMAL_ATOMIC_AMOUNT_RE.test(value) && BigInt(value) > 0n;
 }
@@ -435,7 +486,7 @@ function encodePaymentProof(receipt) {
       chainId: receipt.chainId
     }
   };
-  return btoa(JSON.stringify(payload));
+  return encodeBase64Json(payload);
 }
 function resolveTokenFromAddress(address, network) {
   const lower = address.toLowerCase();
@@ -453,13 +504,6 @@ function stableStringify(value) {
   const object = value;
   return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(object[key])}`).join(",")}}`;
 }
-function decodeBase64Json2(value, label) {
-  try {
-    return JSON.parse(atob(value));
-  } catch {
-    throw new Error(`Failed to decode ${label}`);
-  }
-}
 function normalizeChallenge(value) {
   const candidate = value;
   if (!candidate || typeof candidate !== "object" || candidate.rail !== "mpp_demo" || typeof candidate.version !== "string" || typeof candidate.challengeId !== "string" || typeof candidate.resource !== "string" || typeof candidate.description !== "string" || // TODO: relax these checks when non-demo machine payment rails are added.
@@ -486,7 +530,7 @@ function parseMachinePaymentChallenge(response) {
     throw new Error("No MACHINE-PAYMENT-CHALLENGE header found in 402 response.");
   }
   const parsed = normalizeChallenge(
-    decodeBase64Json2(header, "MACHINE-PAYMENT-CHALLENGE header")
+    decodeBase64Json(header, "MACHINE-PAYMENT-CHALLENGE header")
   );
   if (!parsed) throw new Error("Invalid machine payment challenge");
   return parsed;
@@ -517,7 +561,7 @@ function buildMachinePaymentIdempotencyKey(challenge) {
   return `${challenge.rail}:${crypto.createHash("sha256").update(material).digest("hex").slice(0, 16)}`;
 }
 function encodeMachinePaymentProof(receipt) {
-  return btoa(JSON.stringify({
+  return encodeBase64Json({
     rail: receipt.rail,
     challengeId: receipt.challengeId,
     paymentId: receipt.paymentId,
@@ -525,7 +569,16 @@ function encodeMachinePaymentProof(receipt) {
     settledVia: "haven",
     payer: receipt.payer,
     chainId: receipt.chainId
-  }));
+  });
+}
+function createJsonRpcProvider(url) {
+  return new ethers.ethers.JsonRpcProvider(url);
+}
+function createWallet(privateKey, provider) {
+  return new ethers.ethers.Wallet(privateKey, provider);
+}
+function createErc20Contract(address, abi, signer) {
+  return new ethers.ethers.Contract(address, abi, signer);
 }
 
 // src/client.ts
@@ -534,6 +587,9 @@ var CHAIN_EXPLORER_TX = {
   100: "https://gnosisscan.io/tx",
   8453: "https://basescan.org/tx"
 };
+var CHAIN_USDC = {
+  8453: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
+};
 function buildExplorerUrl(chainId, txHash) {
   const base = CHAIN_EXPLORER_TX[chainId ?? 8453] ?? CHAIN_EXPLORER_TX[8453];
   return `${base}/${txHash}`;
@@ -544,6 +600,16 @@ function explorerUrlOrEmpty(chainId, txHash) {
 var DEFAULT_REQUEST_TIMEOUT = 3e4;
 var DEFAULT_CONFIRMATION_TIMEOUT = 9e4;
 var DEFAULT_POLLING_INTERVAL = 3e3;
+function formatAtomicAmount(atomic, decimals) {
+  const s = atomic.toString().padStart(decimals + 1, "0");
+  const intPart = s.slice(0, s.length - decimals) || "0";
+  const fracPart = s.slice(s.length - decimals).replace(/0+$/, "") || "0";
+  return `${intPart}.${fracPart}`;
+}
+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 MERCHANT_BODY_SNIPPET_LIMIT = 1e3;
 var PAYMENT_STATE_STATUS_CODES = {
   pending: 202,
   pending_approval: 202,
@@ -631,6 +697,47 @@ function parseMerchantSettlement(header) {
   const tx = typeof parsed?.transaction === "string" ? parsed.transaction : typeof parsed?.txHash === "string" ? parsed.txHash : typeof parsed?.tx_hash === "string" ? parsed.tx_hash : null;
   return { settlementTxHash: tx };
 }
+function isMcpUrl(url) {
+  try {
+    return new URL(url).pathname.replace(/\/+$/, "").endsWith("/mcp");
+  } catch {
+    return /\/mcp(?:[/?#]|$)/.test(url);
+  }
+}
+async function responseHasBazaarExtension(response) {
+  try {
+    const body = await response.clone().json();
+    return body?.extensions?.bazaar != null;
+  } catch {
+    return false;
+  }
+}
+function parseSseJsonRpcMessages(text) {
+  const messages = [];
+  let dataLines = [];
+  const flush = () => {
+    if (dataLines.length === 0) return;
+    try {
+      messages.push(JSON.parse(dataLines.join("\n")));
+    } catch {
+    }
+    dataLines = [];
+  };
+  for (const line of text.split(/\r?\n/)) {
+    if (line === "") {
+      flush();
+      continue;
+    }
+    if (line.startsWith("data:")) {
+      dataLines.push(line.slice(5).replace(/^ /, ""));
+    }
+  }
+  flush();
+  return messages;
+}
+function selectJsonRpcResult(messages) {
+  return messages.find((m) => "result" in m || "error" in m) ?? messages[messages.length - 1];
+}
 var HavenClient = class {
   apiKey;
   delegateKey;
@@ -639,6 +746,7 @@ var HavenClient = class {
   requestTimeout;
   confirmationTimeout;
   pollingInterval;
+  chainRpcs;
   inFlightX402 = /* @__PURE__ */ new Map();
   x402ReceiptCache = /* @__PURE__ */ new Map();
   inFlightMachinePayments = /* @__PURE__ */ new Map();
@@ -655,6 +763,8 @@ var HavenClient = class {
    * the same time — see their own headers without stepping on each other.
    */
   requestContext = new async_hooks.AsyncLocalStorage();
+  /** Monotonic JSON-RPC id source for the MCP `initialize` handshake. */
+  mcpRequestId = 0;
   /** Delegate address derived from the private key (if provided) */
   delegateAddress;
   constructor(config) {
@@ -665,6 +775,7 @@ var HavenClient = class {
     this.requestTimeout = config.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT;
     this.confirmationTimeout = config.confirmationTimeout ?? DEFAULT_CONFIRMATION_TIMEOUT;
     this.pollingInterval = config.pollingInterval ?? DEFAULT_POLLING_INTERVAL;
+    this.chainRpcs = config.chainRpcs ?? {};
     this.defaultHeaders = { ...config.defaultHeaders ?? {} };
     if (this.delegateKey) {
       this.delegateAddress = addressFromKey(this.delegateKey);
@@ -860,6 +971,78 @@ var HavenClient = class {
       chainId: raw.chain_id
     };
   }
+  /**
+   * Sweep stranded USDC and ETH from the delegate EOA back to the originating Safe.
+   *
+   * The delegate key held by this client signs and submits the transfer transactions
+   * directly — Haven's backend never handles the key or constructs signed txs
+   * (CASP/MiCA Red Line #2). Funds always go to the Safe linked to this agent.
+   *
+   * Requires `chainRpcs` to be set for the agent's chain in `HavenClientConfig`.
+   */
+  async sweepDelegate() {
+    if (!this.delegateKey) {
+      throw new HavenSigningError("delegateKey is required for sweepDelegate.");
+    }
+    const agent = await this.getAgent();
+    const { safeAddress, delegateAddress, chainId } = agent;
+    if (!delegateAddress) {
+      throw new HavenApiError("Agent has no delegate address.", 422);
+    }
+    const rpcUrl = this.chainRpcs[chainId];
+    if (!rpcUrl) {
+      throw new HavenApiError(
+        `chainRpcs[${chainId}] must be configured to sweep the delegate wallet.`,
+        422
+      );
+    }
+    const provider = createJsonRpcProvider(rpcUrl);
+    const wallet = createWallet(this.delegateKey, provider);
+    const ERC20_TRANSFER_ABI = ["function balanceOf(address) view returns (uint256)", "function transfer(address to, uint256 amount) returns (bool)"];
+    const transfers = [];
+    const usdcAddress = CHAIN_USDC[chainId];
+    if (usdcAddress) {
+      const usdcContract = createErc20Contract(usdcAddress, ERC20_TRANSFER_ABI, wallet);
+      const usdcBalance = await usdcContract.balanceOf(delegateAddress);
+      if (usdcBalance > 0n) {
+        const tx = await usdcContract.transfer(safeAddress, usdcBalance);
+        const receipt = await tx.wait(1);
+        const txHash = receipt?.hash ?? tx.hash;
+        transfers.push({
+          asset: "USDC",
+          amount: formatAtomicAmount(usdcBalance, 6),
+          amountAtomic: usdcBalance.toString(),
+          txHash,
+          explorerUrl: buildExplorerUrl(chainId, txHash)
+        });
+      }
+    }
+    const ethBalance = await provider.getBalance(delegateAddress);
+    if (ethBalance > 0n) {
+      const gasPrice = (await provider.getFeeData()).gasPrice ?? 1000000n;
+      const gasLimit = 21000n;
+      const gasCost = gasPrice * gasLimit;
+      const ethToSend = ethBalance > gasCost ? ethBalance - gasCost : 0n;
+      if (ethToSend > 0n) {
+        const tx = await wallet.sendTransaction({ to: safeAddress, value: ethToSend });
+        const receipt = await tx.wait(1);
+        const txHash = receipt?.hash ?? tx.hash;
+        transfers.push({
+          asset: "ETH",
+          amount: formatAtomicAmount(ethToSend, 18),
+          amountAtomic: ethToSend.toString(),
+          txHash,
+          explorerUrl: buildExplorerUrl(chainId, txHash)
+        });
+      }
+    }
+    return {
+      fromAddress: delegateAddress,
+      toAddress: safeAddress,
+      chainId,
+      transfers
+    };
+  }
   /**
    * Get configured and on-chain allowances for the authenticated agent.
    */
@@ -889,6 +1072,36 @@ var HavenClient = class {
       }))
     };
   }
+  /**
+   * Discover payable services from Haven's curated merchant catalog.
+   *
+   * Read-only: returns catalog entries (price, rail, protocol) so an agent
+   * can choose a service and pay it with the regular payment tools in the
+   * same session. Never creates payments or signatures.
+   */
+  async discoverTools(options = {}) {
+    const params = new URLSearchParams();
+    if (options.category) params.set("category", options.category);
+    if (options.rail) params.set("rail", options.rail);
+    const query = params.size > 0 ? `?${params.toString()}` : "";
+    const raw = await this.get(`/catalog${query}`);
+    return raw.entries.map((entry) => ({
+      id: entry.id,
+      name: entry.name,
+      description: entry.description,
+      category: entry.category,
+      resourceUrl: entry.resource_url,
+      rail: entry.rail,
+      protocol: entry.protocol,
+      toolName: entry.tool_name,
+      priceDisplay: entry.price_display,
+      priceAtomic: entry.price_atomic,
+      asset: entry.asset,
+      network: entry.network,
+      status: entry.status,
+      verifiedAt: entry.verified_at
+    }));
+  }
   /**
    * List recent machine-payment receipts/evidence for bookkeeping.
    */
@@ -1046,6 +1259,10 @@ var HavenClient = class {
     if (execResult.status !== "confirmed") {
       this.throwPaymentStateError("x402 payment", execResult);
     }
+    await this.waitForFundingTx(
+      execResult.tx_hash,
+      execResult.chain_id ?? chainIdFromNetwork(option.network)
+    );
     const receipt = this.mapX402ReceiptFromAuthorization(paymentRequired, option, paymentHeader, raw, execResult);
     this.cacheX402Receipt(idempotencyKey, paymentHeader, receipt);
     return receipt;
@@ -1112,16 +1329,33 @@ var HavenClient = class {
    * const data = await response.json()
    * ```
    *
+   * **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
+   * `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
+   * `result`. The caller just passes `(url, { body })` and never sees the
+   * protocol plumbing. A non-MCP server (handshake error / no session id)
+   * falls back to standard x402 behaviour.
+   *
    * Requires `delegateKey` to be set in the client config.
    */
   async fetch(url, init, options = {}) {
-    const initialInit = this.withX402Wallet(init, this.x402PayerAddress());
-    const response = await globalThis.fetch(url, initialInit);
-    if (response.status !== 402) return response;
+    let mcpSessionId;
+    if (isMcpUrl(url)) {
+      mcpSessionId = await this.mcpInitialize(url, init);
+    }
+    let requestInit = this.withX402Wallet(init, this.x402PayerAddress());
+    if (mcpSessionId) requestInit = this.withMcpHeaders(requestInit, mcpSessionId);
+    const response = await globalThis.fetch(url, requestInit);
+    if (response.status !== 402) {
+      return mcpSessionId ? this.surfaceMcpResult(response) : response;
+    }
     const machineChallengeHeader = response.headers.get("MACHINE-PAYMENT-CHALLENGE");
     if (machineChallengeHeader) {
       const challenge = await parseMachinePaymentChallengeResponse(response);
-      return this.fetchWithMachinePayment(url, initialInit, challenge);
+      return this.fetchWithMachinePayment(url, requestInit, challenge);
     }
     let paymentRequired;
     try {
@@ -1133,9 +1367,13 @@ var HavenClient = class {
       } catch {
         return response;
       }
-      return this.fetchWithMachinePayment(url, initialInit, challenge);
+      return this.fetchWithMachinePayment(url, requestInit, challenge);
     }
-    const request = this.snapshotX402Request(url, initialInit);
+    if (!mcpSessionId && await responseHasBazaarExtension(response)) {
+      mcpSessionId = await this.mcpInitialize(url, init);
+      if (mcpSessionId) requestInit = this.withMcpHeaders(requestInit, mcpSessionId);
+    }
+    const request = this.snapshotX402Request(url, requestInit);
     const option = selectStandardPaymentOption(paymentRequired.accepts);
     const idempotencyKey = options.idempotencyKey ?? (option ? buildX402IdempotencyKey(paymentRequired, option) : void 0);
     let receipt;
@@ -1153,7 +1391,122 @@ var HavenClient = class {
       }
       throw err;
     }
-    return this.retryX402Request(url, initialInit, paymentRequired, receipt);
+    const retryResponse = await this.retryX402Request(url, requestInit, paymentRequired, receipt);
+    return mcpSessionId ? this.surfaceMcpResult(retryResponse) : retryResponse;
+  }
+  // ── MCP-over-x402 transport helpers (issue #315) ─────────────────
+  /**
+   * Run the MCP `initialize` handshake against a Streamable-HTTP endpoint and
+   * return the `mcp-session-id` the server assigns.
+   *
+   * Returns `undefined` whenever the endpoint is not actually an MCP server —
+   * a transport/HTTP error, a missing session id, or a JSON-RPC error in the
+   * handshake response — so the caller can fall back to plain x402.
+   */
+  async mcpInitialize(url, init) {
+    try {
+      const headers = new Headers(init?.headers);
+      headers.set("Content-Type", "application/json");
+      headers.set("Accept", MCP_ACCEPT);
+      const wallet = this.x402PayerAddress();
+      if (wallet && !headers.has("x402-wallet")) headers.set("x402-wallet", wallet);
+      const response = await globalThis.fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          id: ++this.mcpRequestId,
+          method: "initialize",
+          params: {
+            protocolVersion: MCP_PROTOCOL_VERSION,
+            capabilities: {},
+            clientInfo: MCP_CLIENT_INFO
+          }
+        })
+      });
+      if (!response.ok) return void 0;
+      const sessionId = response.headers.get("mcp-session-id");
+      if (!sessionId) return void 0;
+      const message = await this.readMcpMessage(response);
+      if (message && "error" in message) return void 0;
+      await this.mcpNotifyInitialized(url, init, sessionId);
+      return sessionId;
+    } catch {
+      return void 0;
+    }
+  }
+  /**
+   * Send the MCP `notifications/initialized` notification that completes the
+   * lifecycle handshake. Best-effort: the session is already established, so a
+   * failed notification must not abort the payment.
+   */
+  async mcpNotifyInitialized(url, init, sessionId) {
+    try {
+      const headers = new Headers(init?.headers);
+      headers.set("Content-Type", "application/json");
+      headers.set("Accept", MCP_ACCEPT);
+      headers.set("mcp-session-id", sessionId);
+      const wallet = this.x402PayerAddress();
+      if (wallet && !headers.has("x402-wallet")) headers.set("x402-wallet", wallet);
+      await globalThis.fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" })
+      });
+    } catch {
+    }
+  }
+  /** Read a single JSON-RPC message from an MCP response (JSON or SSE body). */
+  async readMcpMessage(response) {
+    let text;
+    try {
+      text = await response.clone().text();
+    } catch {
+      return void 0;
+    }
+    if ((response.headers.get("content-type") ?? "").includes("text/event-stream")) {
+      return selectJsonRpcResult(parseSseJsonRpcMessages(text));
+    }
+    try {
+      return JSON.parse(text);
+    } catch {
+      return void 0;
+    }
+  }
+  /** Add the MCP transport headers (session id + SSE Accept) to a request. */
+  withMcpHeaders(init, sessionId) {
+    const headers = new Headers(init?.headers);
+    headers.set("mcp-session-id", sessionId);
+    headers.set("Accept", MCP_ACCEPT);
+    return { ...init, headers };
+  }
+  /**
+   * Collapse an MCP SSE response into a plain JSON response carrying the
+   * JSON-RPC `result`, so callers of `fetch()` never see raw SSE framing.
+   * Non-SSE responses pass through untouched.
+   */
+  async surfaceMcpResult(response) {
+    if (!(response.headers.get("content-type") ?? "").includes("text/event-stream")) {
+      return response;
+    }
+    let text;
+    try {
+      text = await response.clone().text();
+    } catch {
+      return response;
+    }
+    const message = selectJsonRpcResult(parseSseJsonRpcMessages(text));
+    if (!message) return response;
+    const body = "result" in message ? message.result : message;
+    const headers = new Headers(response.headers);
+    headers.set("content-type", "application/json");
+    headers.delete("content-length");
+    headers.delete("mcp-session-id");
+    return new Response(JSON.stringify(body), {
+      status: response.status,
+      statusText: response.statusText,
+      headers
+    });
   }
   /**
    * Probe a paid MPP endpoint or inspect an existing challenge without creating
@@ -1212,12 +1565,13 @@ var HavenClient = class {
       headers: retryHeaders
     });
     if (!retryResponse.ok) {
+      const merchant = await captureMerchantResponse(retryResponse);
       await this.recordMerchantRetryRejected({
         rail: "x402",
         paymentId: receipt.paymentId,
         txHash: receipt.txHash,
         resourceUrl: receipt.resourceUrl,
-        retryResponse,
+        merchant,
         details: {
           merchant_to: receipt.merchantTo,
           delegate_to: receipt.to
@@ -1225,14 +1579,15 @@ var HavenClient = class {
       });
       throw new HavenApiError(
         "x402 retry failed after Haven funded the delegate wallet; reconciliation may be required.",
-        retryResponse.status,
+        merchant.merchant_status,
         {
           marker: "x402_retry_rejected_after_funding",
           payment_id: receipt.paymentId,
           tx_hash: receipt.txHash,
           resource_url: receipt.resourceUrl,
           merchant_to: receipt.merchantTo,
-          delegate_to: receipt.to
+          delegate_to: receipt.to,
+          ...merchant
         }
       );
     }
@@ -1365,25 +1720,27 @@ var HavenClient = class {
       headers: retryHeaders
     });
     if (!retryResponse.ok) {
+      const merchant = await captureMerchantResponse(retryResponse);
       await this.recordMerchantRetryRejected({
         rail: receipt.rail,
         paymentId: receipt.paymentId,
         txHash: receipt.txHash,
         resourceUrl: receipt.resourceUrl,
-        retryResponse,
+        merchant,
         details: {
           challenge_id: receipt.challengeId
         }
       });
       throw new HavenApiError(
         "Machine payment retry failed after Haven sent the payment.",
-        retryResponse.status,
+        merchant.merchant_status,
         {
           marker: "machine_payment_retry_rejected_after_payment",
           payment_id: receipt.paymentId,
           tx_hash: receipt.txHash,
           resource_url: receipt.resourceUrl,
-          rail: receipt.rail
+          rail: receipt.rail,
+          ...merchant
         }
       );
     }
@@ -1619,12 +1976,12 @@ var HavenClient = class {
       requirements
     );
     if (paymentRequired.x402Version < 2) return header;
-    const payment = decodeBase64Json3(header);
-    return btoa(JSON.stringify({
+    const payment = decodeBase64Json(header);
+    return encodeBase64Json({
       x402Version: paymentRequired.x402Version,
       accepted: option,
       payload: payment.payload
-    }));
+    });
   }
   cacheX402Receipt(idempotencyKey, paymentHeader, receipt) {
     const expiresAt = getPaymentHeaderValidBefore(paymentHeader);
@@ -1686,11 +2043,11 @@ var HavenClient = class {
         rail: input.rail,
         eventType: "merchant_retry_rejected_after_payment",
         txHash: input.txHash,
-        reason: `Merchant returned HTTP ${input.retryResponse.status} after Haven payment confirmation`,
+        reason: `Merchant returned HTTP ${input.merchant.merchant_status} after Haven payment confirmation`,
         details: {
           resource_url: input.resourceUrl,
-          retry_status: input.retryResponse.status,
-          retry_body: await responseSnippet(input.retryResponse),
+          retry_status: input.merchant.merchant_status,
+          retry_body: input.merchant.merchant_body.slice(0, MERCHANT_BODY_SNIPPET_LIMIT) || null,
           ...input.details
         }
       });
@@ -1716,6 +2073,29 @@ var HavenClient = class {
     } catch {
     }
   }
+  /**
+   * Wait for a funding tx to be mined with ≥1 confirmation before the
+   * merchant retry, eliminating the race where the merchant's
+   * `balanceOf(delegate)` runs before the funding block propagates.
+   *
+   * Skipped when `chainRpcs` does not include the chain; in that case Haven's
+   * backend has already confirmed on-chain submission and callers accept the
+   * small propagation window as a trade-off for not configuring an RPC URL.
+   */
+  async waitForFundingTx(txHash, chainId, timeoutMs = 3e4) {
+    if (!txHash || !chainId) return;
+    const rpcUrl = this.chainRpcs[chainId];
+    if (!rpcUrl) return;
+    const provider = createJsonRpcProvider(rpcUrl);
+    const onChainReceipt = await provider.waitForTransaction(txHash, 1, timeoutMs);
+    if (!onChainReceipt || onChainReceipt.status !== 1) {
+      throw new HavenApiError(
+        "Funding tx did not confirm on-chain within the timeout window.",
+        500,
+        { txHash, chainId }
+      );
+    }
+  }
   throwIfNonSignableAuthorizationState(label, raw) {
     if (raw.status === "pending_signature") return;
     this.throwPaymentStateError(label, raw);
@@ -2301,7 +2681,7 @@ function sleep(ms) {
 }
 function getPaymentHeaderValidBefore(paymentHeader) {
   try {
-    const payment = decodeBase64Json3(
+    const payment = decodeBase64Json(
       paymentHeader
     );
     const payload = payment.payload;
@@ -2311,12 +2691,9 @@ function getPaymentHeaderValidBefore(paymentHeader) {
   }
   return 0;
 }
-function decodeBase64Json3(value) {
-  return JSON.parse(atob(value));
-}
 function parseProtocolReceiptHeader(value) {
   try {
-    return JSON.parse(atob(value));
+    return decodeBase64Json(value);
   } catch {
     try {
       return JSON.parse(value);
@@ -2325,13 +2702,14 @@ function parseProtocolReceiptHeader(value) {
     }
   }
 }
-async function responseSnippet(response) {
-  try {
-    const text = await response.clone().text();
-    return text.slice(0, 1e3) || null;
-  } catch {
-    return null;
-  }
+async function captureMerchantResponse(response) {
+  const merchant_body = await response.text().catch(() => "");
+  return {
+    merchant_status: response.status,
+    merchant_status_text: response.statusText,
+    merchant_headers: Object.fromEntries(response.headers.entries()),
+    merchant_body
+  };
 }
 
 // src/tool-descriptions.ts
@@ -2403,6 +2781,30 @@ var toolDescriptions = {
     selectionGuidance: "Use this for transaction history, receipts, payment evidence, or bookkeeping; use the allowance tool instead for remaining allowance, budget, spend-limit, or what-can-I-spend questions.",
     behavior: "Returns the agent's recent machine-payment receipts ordered by recency. Proof header values are not returned.",
     nextActionGuidance: ""
+  },
+  payMcpTool: {
+    summary: "Call a named tool on an MCP merchant that requires an x402 payment, handling the full initialize \u2192 pay \u2192 retry round trip.",
+    selectionGuidance: "Use this when the agent wants to call a specific tool on an MCP merchant (e.g. Soundside, Coinbase Bazaar) and payment is required. Prefer this over haven_pay_x402 when you know the merchant_url and tool_name \u2014 it builds the JSON-RPC envelope internally. Use haven_pay_x402 for arbitrary HTTP resources. Do NOT use for read-only allowance or budget questions \u2014 use haven_get_allowances.",
+    behavior: "Builds the JSON-RPC tools/call envelope, runs the MCP Streamable-HTTP initialize handshake automatically (if the endpoint is MCP-shaped), pays any HTTP 402 x402 challenge through Haven's AllowanceModule path, and retries the request. Returns the JSON-RPC result (the actual merchant output) on success. Amounts within the on-chain allowance execute automatically; over-allowance transfers are queued as pending_approval.",
+    nextActionGuidance: "If pending_approval is returned, preserve payment_id and resume_state and wait for the wallet owner to approve in Haven. Use haven_resume_x402_payment once nextAction=retry_original_x402_request."
+  },
+  discoverTools: {
+    summary: "Discover payable services from Haven's curated merchant catalog \u2014 names, prices, and which pay tool to use.",
+    selectionGuidance: "Use this when the user asks what the agent can buy, pay for, or which paid services exist \u2014 or when you need a resource URL for a service the user described. Do NOT use for balance, budget, or spend-limit questions \u2014 use haven_get_allowances. Do NOT use to pay \u2014 each returned entry names the pay tool to use next.",
+    behavior: "Read-only lookup against Haven's curated catalog. Entries are periodically re-verified against the live merchant; degraded entries are flagged. Returns name, description, price, rail, resource URL, and a suggested_tool field naming the exact Haven pay tool for that entry. Never creates a payment, signature, or approval.",
+    nextActionGuidance: "Pick an entry, confirm the price with the user if it is non-trivial, and pay it with the tool named in suggested_tool, passing the entry's resource_url (and tool_name for MCP merchants)."
+  },
+  sweep_delegate: {
+    summary: "Sweep stranded USDC and/or ETH from the delegate wallet back to the originating Safe.",
+    selectionGuidance: "Use this when the user instructs you to recover stranded funds on the delegate wallet, or when a payment status returns nextAction=sweep_stranded_funds. Do NOT use for normal payments \u2014 use haven_pay_x402 or haven_pay_mpp_challenge. Do NOT use to read balances only \u2014 use haven_get_allowances.",
+    behavior: "Reads the delegate EOA's on-chain USDC and ETH balances. For each non-zero balance, signs and submits a transfer from the delegate EOA to the originating Safe (hardcoded destination). The delegate key signs locally \u2014 Haven never sees it and the backend never constructs signed transactions (CASP/MiCA Red Line #2). Returns tx hashes and recovered amounts. Returns an empty transfers list when nothing is stranded.",
+    nextActionGuidance: "If transfers is non-empty, confirm the amounts with the user. No further action required \u2014 funds are on their way back to the Safe."
+  },
+  send: {
+    summary: "Send ETH or USDC directly from the agent's Haven wallet to a recipient address.",
+    selectionGuidance: "Use this for plain transfers \u2014 refunding a user, paying a freelancer, topping up a co-agent's wallet, or moving funds between addresses. Do NOT use for x402 paid endpoints (use haven_pay_x402 instead) or MPP merchant payments (use haven_pay_mpp_challenge). Do NOT use for read-only allowance, budget, or what-can-I-spend questions \u2014 use haven_get_allowances.",
+    behavior: "Sends the requested amount through the Safe AllowanceModule. Amounts within the remaining on-chain allowance for the asset execute automatically; amounts that exceed the allowance are queued as pending_approval for the wallet owner to approve in Haven. The agent's signing key signs the AllowanceModule transfer hash; Haven never receives the key.",
+    nextActionGuidance: "If pending_approval is returned, preserve the payment_id and wait for the wallet owner to approve in Haven. Poll haven_get_payment_status until nextAction=none."
   }
 };
 
@@ -2532,6 +2934,12 @@ var GET_ALLOWANCES_DESCRIPTION = composeDescription(toolDescriptions.getAllowanc
 var AUTHORIZE_X402_DESCRIPTION = composeDescription(toolDescriptions.payX402) + " In this SDK tool set, the allowance lookup tool is get_allowances. When a paid API returns x402 payment requirements, use this tool to sign with the agent-owned delegate key and request a policy-limited Safe AllowanceModule top-up when needed. Haven relays signed transactions only; the agent key authorizes payment and on-chain limits enforce spend. If this returns pending_approval, tell the user it is waiting in Haven, preserve the original merchant/MCP session and x402 details, call get_payment_status later, and use resume_x402_payment only when next_action is retry_original_x402_request. Do not start a new merchant session or loop retries while approval is pending. Use the returned payment_header as the X-PAYMENT header on the retry request when doing a manual HTTP retry.";
 var RESUME_X402_DESCRIPTION = toolDescriptions.resumeX402.summary + " Use this only after get_payment_status returns next_action=retry_original_x402_request. It checks the approved payment, validates the original x402 details, and returns a merchant X-PAYMENT header without creating a new approval request or merchant session.";
 var AUTHORIZE_MACHINE_PAYMENT_DESCRIPTION = composeDescription(toolDescriptions.payMpp) + " In this SDK tool set, the allowance lookup tool is get_allowances. Currently scoped to the internal MPP demo rail. The agent signs the payment, Haven relays it within the on-chain allowance, and the tool returns a proof header for the retry request.";
+var SWEEP_DELEGATE_DESCRIPTION = composeDescription(toolDescriptions.sweep_delegate);
+var sweepDelegateSchema = {
+  type: "object",
+  properties: {},
+  required: []
+};
 function claudeTools() {
   return [
     {
@@ -2563,6 +2971,11 @@ function claudeTools() {
       name: "authorize_machine_payment",
       description: AUTHORIZE_MACHINE_PAYMENT_DESCRIPTION,
       input_schema: authorizeMachinePaymentSchema
+    },
+    {
+      name: "haven_sweep_delegate",
+      description: SWEEP_DELEGATE_DESCRIPTION,
+      input_schema: sweepDelegateSchema
     }
   ];
 }
@@ -2615,6 +3028,14 @@ function openaiTools() {
         description: AUTHORIZE_MACHINE_PAYMENT_DESCRIPTION,
         parameters: authorizeMachinePaymentSchema
       }
+    },
+    {
+      type: "function",
+      function: {
+        name: "haven_sweep_delegate",
+        description: SWEEP_DELEGATE_DESCRIPTION,
+        parameters: sweepDelegateSchema
+      }
     }
   ];
 }
@@ -2647,6 +3068,10 @@ exports.addressFromKey = addressFromKey;
 exports.buildMachinePaymentIdempotencyKey = buildMachinePaymentIdempotencyKey;
 exports.buildX402ExpectedMessage = buildX402ExpectedMessage;
 exports.composeDescription = composeDescription;
+exports.decodeBase64Json = decodeBase64Json;
+exports.decodeBase64Utf8 = decodeBase64Utf8;
+exports.encodeBase64Json = encodeBase64Json;
+exports.encodeBase64Utf8 = encodeBase64Utf8;
 exports.encodeMachinePaymentProof = encodeMachinePaymentProof;
 exports.encodePaymentProof = encodePaymentProof;
 exports.havenTools = havenTools;