@haven_ai/sdk 0.1.14-alpha.0 → 0.1.15-alpha.0

package/README.md

@@ -229,6 +229,8 @@ The enum values and JSON Schema fragments are exported from `@haven_ai/sdk`:
 import {
   AgentPaymentNextAction,
   AgentPaymentNextActionSchema,
+  AgentPaymentFailureCode,
+  AgentPaymentFailureCodeSchema,
   AgentPaymentPhase,
   AgentPaymentPhaseSchema,
   AgentPaymentRail,
@@ -277,6 +279,10 @@ Terminal from any non-confirmed phase:
    rejected → stop_and_tell_user
    failed   → stop_and_tell_user
    expired  → request_again_if_user_still_wants_it
+
+x402 tool-window failures:
+   expired funding/quote window → PAYMENT_WINDOW_EXPIRED → re-quote with same idempotency_key
+   merchant rejection after funding → MERCHANT_REJECTED_AFTER_FUNDING → haven_sweep_delegate
 ```
 
 ### `phase` reference
@@ -308,6 +314,18 @@ The merchant settlement leg of x402 (and the MPP retry) is the agent's own reque
 | `retry_original_x402_request` | Resume this payment id and retry the original x402 request with the merchant payment header. Do not start a new merchant session. |
 | `stop_and_tell_user` | Stop retrying and tell the user the payment failed or was rejected. |
 | `request_again_if_user_still_wants_it` | The request expired; ask again only if the user still wants the payment. |
+| `payment_window_expired` | The x402 funding/quote window expired. Re-quote the same paid MCP tool call with the same `idempotency_key`, then sign the fresh `payload_hash`. |
+| `sweep_stranded_funds` | A funding leg succeeded but the merchant/protocol leg did not settle. Stop retrying and use `haven_sweep_delegate` to recover stranded delegate funds. |
+
+### Machine-readable recovery codes
+
+Hosted MCP and signer tools also return stable `code` values on recoverable x402 failures:
+
+| `code` | Meaning | Agent recovery |
+|--------|---------|----------------|
+| `PRICE_EXCEEDS_MAX` | The merchant-authoritative x402 price is above the caller's `max_amount` cap. No funding transfer was created. | Tell the user the live price exceeded the cap and retry only after they confirm a higher `max_amount`. |
+| `PAYMENT_WINDOW_EXPIRED` | The funding/quote window closed before `haven_x402_sign_header`, `haven_submit`, or `haven_complete_mcp_tool` could finish. | Re-run `haven_pay_mcp_tool` with the same `idempotency_key`, then sign and complete the fresh quote. Payloads include `retry_with_new_quote: true`. |
+| `MERCHANT_REJECTED_AFTER_FUNDING` | Haven's funding leg succeeded, but the merchant rejected the paid retry. | Stop retrying the merchant and call `haven_sweep_delegate` so the user can recover stranded delegate USDC. |
 
 ## Payments above the on-chain allowance
 

package/dist/index.cjs

@@ -63,6 +63,11 @@ var AgentPaymentNextAction = {
   StopAndTellUser: "stop_and_tell_user",
   /** Ask again only if the user still wants the payment after expiry. */
   RequestAgainIfUserStillWantsIt: "request_again_if_user_still_wants_it",
+  /**
+   * The x402 funding/quote window expired. Re-quote the same logical merchant
+   * operation with the same idempotency key to stay double-charge-safe.
+   */
+  PaymentWindowExpired: "payment_window_expired",
   /**
    * Stop and tell the user that the originating Safe needs to be funded or
    * the agent's per-token allowance needs to be raised before the payment
@@ -76,6 +81,14 @@ var AgentPaymentNextAction = {
    */
   SweepStrandedFunds: "sweep_stranded_funds"
 };
+var AgentPaymentFailureCode = {
+  /** A merchant-authoritative x402 price exceeds the caller's pre-funding max_amount cap. */
+  PriceExceedsMax: "PRICE_EXCEEDS_MAX",
+  /** The x402 funding/quote window expired before the signer or hosted settle step could finish. */
+  PaymentWindowExpired: "PAYMENT_WINDOW_EXPIRED",
+  /** The Haven funding leg succeeded, but the merchant rejected the paid retry. */
+  MerchantRejectedAfterFunding: "MERCHANT_REJECTED_AFTER_FUNDING"
+};
 var AgentPaymentRail = {
   /** Standard Haven payment from the user's Safe through an approved delegate allowance. */
   Direct: "direct",
@@ -94,6 +107,7 @@ var AgentPaymentRail = {
 };
 var AGENT_PAYMENT_PHASE_VALUES = Object.values(AgentPaymentPhase);
 var AGENT_PAYMENT_NEXT_ACTION_VALUES = Object.values(AgentPaymentNextAction);
+var AGENT_PAYMENT_FAILURE_CODE_VALUES = Object.values(AgentPaymentFailureCode);
 var AGENT_PAYMENT_RAIL_VALUES = Object.values(AgentPaymentRail);
 var AgentPaymentPhaseDescriptions = {
   [AgentPaymentPhase.AgentSignatureRequired]: "The agent must sign and submit the prepared payment before Haven can relay it.",
@@ -118,9 +132,15 @@ 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.PaymentWindowExpired]: "The x402 funding/quote window expired. Re-quote with the same idempotency key before asking the signer to build a merchant payment header again.",
   [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 AgentPaymentFailureCodeDescriptions = {
+  [AgentPaymentFailureCode.PriceExceedsMax]: "The merchant-authoritative x402 amount exceeds the caller's max_amount cap. No funding transfer was created; ask the user before retrying with a larger cap.",
+  [AgentPaymentFailureCode.PaymentWindowExpired]: "The x402 funding/quote window expired before the signer or hosted settle step could finish. Re-quote via haven_pay_mcp_tool with the same idempotency key to avoid duplicate funding.",
+  [AgentPaymentFailureCode.MerchantRejectedAfterFunding]: "The Haven funding leg succeeded, but the merchant rejected the paid retry. Stop retrying the merchant and reconcile stranded delegate funds with haven_sweep_delegate."
+};
 var AgentPaymentRailDescriptions = {
   [AgentPaymentRail.Direct]: "Standard Haven payment from the user-controlled Safe through an approved delegate allowance.",
   [AgentPaymentRail.X402]: "x402 HTTP 402 payment flow with a Haven funding leg and merchant retry leg.",
@@ -142,6 +162,12 @@ var AgentPaymentNextActionSchema = {
   description: "Stable next action an agent should take for a Haven payment state.",
   "x-enumDescriptions": AgentPaymentNextActionDescriptions
 };
+var AgentPaymentFailureCodeSchema = {
+  type: "string",
+  enum: AGENT_PAYMENT_FAILURE_CODE_VALUES,
+  description: "Stable machine-readable failure codes for Haven agent payment recovery paths.",
+  "x-enumDescriptions": AgentPaymentFailureCodeDescriptions
+};
 var AgentPaymentRailSchema = {
   type: "string",
   enum: AGENT_PAYMENT_RAIL_VALUES,
@@ -329,7 +355,8 @@ function normalizePaymentRequired(value) {
     x402Version: candidate.x402Version,
     resource,
     accepts,
-    error: candidate.error
+    error: candidate.error,
+    ...candidate.extensions && typeof candidate.extensions === "object" ? { extensions: candidate.extensions } : {}
   };
 }
 var SUPPORTED_X402_NETWORKS = {
@@ -425,8 +452,7 @@ function x402AuthorizationAmount(option) {
   return amount;
 }
 function buildX402ExpectedMessage(context) {
-  return `Haven x402 expected context v1
-${stableStringify({
+  const payload = {
     version: 1,
     kind: "haven.x402.expected",
     paymentId: context.paymentId,
@@ -436,7 +462,12 @@ ${stableStringify({
     amount: context.amount,
     asset: context.asset.toLowerCase(),
     network: context.network
-  })}`;
+  };
+  if (context.expiresAt) {
+    payload.expiresAt = context.expiresAt;
+  }
+  return `Haven x402 expected context v1
+${stableStringify(payload)}`;
 }
 function toStandardPaymentRequirements(paymentRequired, option) {
   const network = STANDARD_X402_NETWORKS[option.network];
@@ -892,6 +923,7 @@ var HavenClient = class {
     }
     return {
       paymentId: raw.payment_id,
+      idempotencyKey,
       status: "pending_signature",
       expiresAt: raw.expires_at,
       signData: raw.sign_data,
@@ -1043,6 +1075,30 @@ var HavenClient = class {
       transfers
     };
   }
+  /**
+   * Hosted (keyless) split-signer sweep — step 1 of 2.
+   *
+   * Asks the backend to build a gasless EIP-3009 sweep authorization for the
+   * delegate's stranded USDC. Returns `nothing_stranded` when the delegate is
+   * empty, otherwise an `authorization` + Haven `expected_auth` to hand to the
+   * edge signer's `haven_sign_sweep_delegate`. No key is required on this client.
+   */
+  async prepareSweep() {
+    return this.post("/machine-payments/sweep/prepare", {});
+  }
+  /**
+   * Hosted (keyless) split-signer sweep — step 2 of 2.
+   *
+   * Relays the delegate-signed authorization. The Haven relayer submits the
+   * on-chain `transferWithAuthorization` and pays gas; this client never holds
+   * the key.
+   */
+  async submitSweep(authorization, signature) {
+    return this.post("/machine-payments/sweep/submit", {
+      authorization,
+      signature
+    });
+  }
   /**
    * Get configured and on-chain allowances for the authenticated agent.
    */
@@ -1198,7 +1254,8 @@ var HavenClient = class {
       throw new HavenApiError("quoteX402 only supports standard x402 Payment Required responses.", 400);
     }
     const paymentRequired = await parsePaymentRequiredResponse(response);
-    return this.buildX402Quote(paymentRequired, request, options.idempotencyKey);
+    const mcpTransport = await this.detectX402McpTransport(url, paymentRequired, response);
+    return this.buildX402Quote(paymentRequired, request, options.idempotencyKey, mcpTransport);
   }
   /**
    * Pay a previously inspected x402 quote and retry the exact captured request.
@@ -1403,12 +1460,11 @@ var HavenClient = class {
    * 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) {
+  async mcpInitialize(url, init, wallet = this.x402PayerAddress()) {
     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",
@@ -1429,7 +1485,7 @@ var HavenClient = class {
       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);
+      await this.mcpNotifyInitialized(url, init, sessionId, wallet);
       return sessionId;
     } catch {
       return void 0;
@@ -1440,13 +1496,12 @@ var HavenClient = class {
    * lifecycle handshake. Best-effort: the session is already established, so a
    * failed notification must not abort the payment.
    */
-  async mcpNotifyInitialized(url, init, sessionId) {
+  async mcpNotifyInitialized(url, init, sessionId, wallet = this.x402PayerAddress()) {
     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",
@@ -1624,30 +1679,33 @@ var HavenClient = class {
    * amount/merchant/nonce-bound EIP-3009 authorization the edge signer already
    * produced — the hosted server cannot mint or reuse signing authority.
    *
-   * When the URL is MCP-shaped (`/mcp` path), runs a fresh `initialize`
+   * When the URL is MCP-shaped (`/mcp` path) or the quote-time transport context
+   * says the merchant was Bazaar-discoverable, runs a fresh `initialize`
    * handshake (the quote-time session is gone once funding confirms; the x402
    * challenge is stateless w.r.t. the MCP session, so a fresh session is
    * accepted), threads the session + wallet headers, sets `X-PAYMENT`, and
    * collapses an SSE JSON-RPC response to its `result`.
-   *
-   * Limitation: detects MCP only by the `/mcp` path convention, not the
-   * Coinbase Bazaar `extensions.bazaar` 402 signal that `fetch()` also honors.
-   * A Bazaar-discoverable merchant on a non-`/mcp` URL would need the standard
-   * `fetch()` path. All current MCP-tool merchants use the `/mcp` convention.
    */
   async completeX402MerchantCall(input) {
+    const evidenceContext = await this.resolveX402MerchantCompletionContext({
+      paymentId: input.paymentId,
+      url: input.url
+    });
+    const shouldHandshakeMcp = isMcpUrl(input.url) || input.mcpTransport?.handshakeRequired === true;
+    const x402Wallet = shouldHandshakeMcp ? await this.resolveX402WalletForMerchantCall() : this.x402PayerAddress();
     let mcpSessionId;
-    if (isMcpUrl(input.url)) {
-      mcpSessionId = await this.mcpInitialize(input.url, input.init);
+    if (shouldHandshakeMcp) {
+      mcpSessionId = await this.mcpInitialize(input.url, input.init, x402Wallet);
     }
-    let requestInit = this.withX402Wallet(input.init, this.x402PayerAddress()) ?? {};
+    let requestInit = this.withX402Wallet(input.init, x402Wallet) ?? {};
     if (mcpSessionId) requestInit = this.withMcpHeaders(requestInit, mcpSessionId);
     const headers = new Headers(requestInit.headers);
     headers.set("X-PAYMENT", input.paymentHeader);
     requestInit = { ...requestInit, headers };
     const response = await globalThis.fetch(input.url, requestInit);
     const surfaced = mcpSessionId ? await this.surfaceMcpResult(response) : response;
-    const settlement = parseMerchantSettlement(surfaced.headers.get("PAYMENT-RESPONSE"));
+    const protocolReceiptHeader = surfaced.headers.get("PAYMENT-RESPONSE") ?? void 0;
+    const settlement = parseMerchantSettlement(protocolReceiptHeader ?? null);
     const text = await surfaced.text();
     let body;
     try {
@@ -1655,6 +1713,35 @@ var HavenClient = class {
     } catch {
       body = text;
     }
+    if (!surfaced.ok) {
+      await this.recordMerchantRetryRejected({
+        rail: "x402",
+        paymentId: evidenceContext.paymentId,
+        txHash: evidenceContext.txHash,
+        resourceUrl: evidenceContext.resourceUrl,
+        merchant: {
+          merchant_status: surfaced.status,
+          merchant_status_text: surfaced.statusText,
+          merchant_headers: Object.fromEntries(surfaced.headers.entries()),
+          merchant_body: text
+        },
+        details: {
+          merchant_to: evidenceContext.merchantAddress
+        }
+      });
+    } else {
+      await this.reportMachinePaymentEvidence({
+        paymentId: evidenceContext.paymentId,
+        rail: "x402",
+        txHash: evidenceContext.txHash,
+        resourceUrl: evidenceContext.resourceUrl,
+        merchantStatus: surfaced.status,
+        paymentProofHeaderName: "X-PAYMENT",
+        paymentProofHeader: input.paymentHeader,
+        protocolReceiptHeaderName: protocolReceiptHeader ? "PAYMENT-RESPONSE" : void 0,
+        protocolReceiptHeader
+      });
+    }
     return {
       status: surfaced.status,
       ok: surfaced.ok,
@@ -1662,6 +1749,53 @@ var HavenClient = class {
       settlementTxHash: settlement.settlementTxHash ?? void 0
     };
   }
+  async resolveX402MerchantCompletionContext(input) {
+    const status = await this.getPaymentStatus(input.paymentId);
+    if (status.rail !== "x402") {
+      throw new HavenPaymentStateError(
+        `Payment ${status.paymentId} is ${status.rail}, not x402.`,
+        409,
+        status
+      );
+    }
+    const readyForMerchantCompletion = status.nextAction === AgentPaymentNextAction.RetryOriginalX402Request || status.kind === "payment_intent" && status.status === "confirmed" && status.phase === AgentPaymentPhase.PaymentConfirmed && status.nextAction === AgentPaymentNextAction.None;
+    if (!readyForMerchantCompletion) {
+      throw new HavenPaymentStateError(status.message, PAYMENT_STATE_STATUS_CODES[status.status] ?? 409, status);
+    }
+    if (!status.txHash) {
+      throw new HavenApiError(
+        `x402 payment ${status.paymentId} is ready for merchant completion but has no Haven transaction hash.`,
+        502,
+        status,
+        status.paymentId
+      );
+    }
+    const approvedResourceUrl = status.resourceUrl ?? status.x402?.resourceUrl ?? null;
+    if (approvedResourceUrl && approvedResourceUrl !== input.url) {
+      throw new HavenApiError(
+        "x402 merchant completion does not match the approved resource URL.",
+        409,
+        { status, url: input.url },
+        status.paymentId
+      );
+    }
+    return {
+      paymentId: status.paymentId,
+      txHash: status.txHash,
+      resourceUrl: approvedResourceUrl ?? input.url,
+      merchantAddress: status.merchantAddress ?? status.x402?.merchantAddress ?? null
+    };
+  }
+  async resolveX402WalletForMerchantCall() {
+    const localWallet = this.x402PayerAddress();
+    if (localWallet) return localWallet;
+    try {
+      const agent = await this.getAgent();
+      return agent.delegateAddress ?? void 0;
+    } catch {
+      return void 0;
+    }
+  }
   async authorizeMachinePayment(challenge, options = {}) {
     if (!this.delegateKey) {
       throw new HavenSigningError(
@@ -2259,7 +2393,7 @@ var HavenClient = class {
       headers
     };
   }
-  buildX402Quote(paymentRequired, request, idempotencyKey) {
+  buildX402Quote(paymentRequired, request, idempotencyKey, mcpTransport) {
     const option = selectStandardPaymentOption(paymentRequired.accepts);
     if (!option) {
       throw new HavenApiError(
@@ -2274,6 +2408,7 @@ var HavenClient = class {
       paymentRequired,
       accepted: option,
       request,
+      ...mcpTransport ? { mcpTransport } : {},
       resourceUrl: paymentRequired.resource.url,
       description: paymentRequired.resource.description ?? option.description ?? null,
       mimeType: paymentRequired.resource.mimeType ?? option.mimeType ?? null,
@@ -2287,6 +2422,18 @@ var HavenClient = class {
       maxTimeoutSeconds: option.maxTimeoutSeconds
     };
   }
+  async detectX402McpTransport(url, paymentRequired, response) {
+    if (isMcpUrl(url)) {
+      return { handshakeRequired: true, source: "path" };
+    }
+    if (paymentRequired.extensions?.bazaar != null) {
+      return { handshakeRequired: true, source: "bazaar" };
+    }
+    if (await responseHasBazaarExtension(response)) {
+      return { handshakeRequired: true, source: "bazaar" };
+    }
+    return void 0;
+  }
   buildX402ResumeState(input) {
     const token = resolveTokenFromAddress(input.accepted.asset, input.accepted.network);
     return {
@@ -2839,8 +2986,8 @@ var toolDescriptions = {
   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)."
+    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. The catalog price (price_display/price_atomic, marked price_is_indicative) is a last-verified hint, NOT authoritative \u2014 the real price comes from the merchant's live 402 at pay time. Never creates a payment, signature, or approval.",
+    nextActionGuidance: "Pick an entry and pay it with the tool named in suggested_tool, passing the entry's resource_url (and tool_name for MCP merchants). Confirm the price from the live pay-tool result (not the catalog), and pass max_amount when the user has a cap."
   },
   sweep_delegate: {
     summary: "Sweep stranded USDC and/or ETH from the delegate wallet back to the originating Safe.",
@@ -3107,6 +3254,9 @@ the Haven MCP tools. Every payment is checked against the agent's on-chain
 budget before money moves; payments above the remaining budget wait for the
 user's approval in Haven.
 
+Hosted tools run in the \`mcp__haven__\` namespace. Local signing tools run in
+the \`mcp__haven-signer__\` namespace and keep the delegate key on this machine.
+
 ## When to use this skill
 
 - The user asks to send money, pay someone, tip, donate, or transfer tokens.
@@ -3132,13 +3282,33 @@ normal, not an error.
   the local Haven signer; follow the tool results \u2014 they tell you the next
   action at every step. Retry the original request only when the result says
   \`retry_original_x402_request\`.
-- **Paid MCP tool call:** \`haven_pay_mcp_tool\` with the merchant URL, tool
-  name, and arguments. Then follow the returned steps: \`haven_sign\` the
-  funding hash, \`haven_submit\` the signature, \`haven_x402_sign_header\` to
-  build the payment header, and finally \`haven_complete_mcp_tool\` to settle
-  with the merchant and get the tool result. Pass \`payment_required\` and
-  \`arguments\` through verbatim from the \`haven_pay_mcp_tool\` result. Do not
-  call the merchant yourself \u2014 Haven completes the merchant leg for you.
+- **Paid MCP tool call:** \`mcp__haven__haven_pay_mcp_tool\` with the merchant
+  URL, tool name, and arguments, then finish in two calls (fast path):
+  \`mcp__haven-signer__haven_sign_x402\` on the local signer (pass
+  \`payload_hash\`, \`x402_expected\` as the nested \`x402.expected\` object, and
+  \`payment_required\`) returns \`{ signature, payment_header }\`; then
+  \`mcp__haven__haven_settle_mcp_tool\` (pass \`payment_id\`, \`signature\`,
+  \`payment_header\`, \`merchant_url\`, \`tool_name\`, \`arguments\`,
+  \`mcp_transport\`) funds and settles in one step and returns the tool result.
+  If it returns \`settled: false\`, funding is queued for the user's approval \u2014
+  tell them and check status later, do not re-pay. Step-by-step alternative:
+  \`mcp__haven-signer__haven_sign\` \u2192 \`mcp__haven__haven_submit\` \u2192
+  \`mcp__haven-signer__haven_x402_sign_header\` \u2192
+  \`mcp__haven__haven_complete_mcp_tool\`. Pass \`payment_required\`,
+  \`arguments\`, and \`mcp_transport\` verbatim from the
+  \`mcp__haven__haven_pay_mcp_tool\` result. The returned \`expires_at\` is the
+  signing window; if a tool returns \`PAYMENT_WINDOW_EXPIRED\`, re-run
+  \`mcp__haven__haven_pay_mcp_tool\` with the same
+  \`idempotency_key\`. Do not call the merchant yourself \u2014 Haven completes the
+  merchant leg for you.
+- **Prices:** show the user the live price from the pay-tool result, never a
+  catalog price. \`haven_discover_tools\` prices are indicative
+  (\`price_is_indicative\`) and can be stale. The pay-tool result's \`amount\` /
+  \`amount_atomic\` is the amount Haven authorizes for the call \u2014 a ceiling the
+  merchant settles at or below \u2014 so present it as the most the user will pay.
+  Pass \`max_amount\` (atomic units) to \`haven_pay_mcp_tool\` /
+  \`haven_pay_x402_quote\` to reject a quote whose authorized amount is above the
+  user's cap, before any funds move.
 - **Status:** \`haven_get_payment_status\` with a \`payment_id\` to check on
   queued or in-flight payments. Do not poll in a tight loop.
 
@@ -3147,18 +3317,26 @@ normal, not an error.
 - A result with \`pending_approval\` means the payment exceeded the remaining
   budget and is waiting for the user in Haven. Tell the user, then check
   status later.
-- Never ask the user for private keys and never try to sign anything
-  yourself \u2014 Haven signs. If a tool reports a missing or invalid credential,
-  tell the user to re-run the Haven setup command.
+- Never ask the user for private keys. Signing happens only in the local Haven
+  signer; the hosted Haven tools never receive the signing key. If a tool
+  reports a missing or invalid credential, tell the user to re-run the Haven
+  setup command.
 
 ## Failure handling
 
-Haven errors are shaped \`{ error, status, details? }\` and written for
-humans \u2014 surface the message verbatim. Common cases:
+Haven tool failures are shaped like \`{ success: false, code, message, ... }\`
+or older \`{ error, status, details? }\` responses. Branch on \`code\` when
+present and surface \`message\` or \`error\` verbatim. Common cases:
 
 - \`pending_approval\`: queued for the user's approval (see above).
 - \`insufficient_funds\`: the Haven wallet doesn't hold enough of that token.
   Suggest the user add funds in the Haven dashboard.
+- \`PRICE_EXCEEDS_MAX\`: the live merchant price exceeded your \`max_amount\`.
+  No funds moved; ask the user before retrying with a higher cap.
+- \`PAYMENT_WINDOW_EXPIRED\`: re-run \`mcp__haven__haven_pay_mcp_tool\` with the same
+  \`idempotency_key\`, then sign the fresh \`payload_hash\`.
+- \`MERCHANT_REJECTED_AFTER_FUNDING\`: stop retrying the merchant and use
+  \`mcp__haven__haven_sweep_delegate\` to recover stranded delegate funds.
 - Budget exceeded: tell the user how much remains (from
   \`haven_get_allowances\`) and that they can raise the budget in Haven.
 
@@ -3170,9 +3348,105 @@ for that credential.
 `;
 var SKILL_FOLDER_NAME = "haven-pay";
 
+// src/sweep.ts
+var SWEEP_BASE_CHAIN_ID = 8453;
+var SWEEP_BASE_USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+var USDC_EIP712_DOMAIN_BY_CHAIN = {
+  [SWEEP_BASE_CHAIN_ID]: {
+    name: "USD Coin",
+    version: "2",
+    chainId: SWEEP_BASE_CHAIN_ID,
+    verifyingContract: SWEEP_BASE_USDC_ADDRESS
+  }
+};
+var USDC_ADDRESS_BY_CHAIN = {
+  [SWEEP_BASE_CHAIN_ID]: SWEEP_BASE_USDC_ADDRESS
+};
+var TRANSFER_WITH_AUTHORIZATION_TYPES = {
+  TransferWithAuthorization: [
+    { name: "from", type: "address" },
+    { name: "to", type: "address" },
+    { name: "value", type: "uint256" },
+    { name: "validAfter", type: "uint256" },
+    { name: "validBefore", type: "uint256" },
+    { name: "nonce", type: "bytes32" }
+  ]
+};
+function sweepUsdcAddress(chainId) {
+  const address = USDC_ADDRESS_BY_CHAIN[chainId];
+  if (!address) {
+    throw new HavenSigningError(
+      `Sweep is only supported on Base (chainId ${SWEEP_BASE_CHAIN_ID}). Got chainId ${chainId}.`
+    );
+  }
+  return address;
+}
+function sweepUsdcDomain(chainId) {
+  const domain = USDC_EIP712_DOMAIN_BY_CHAIN[chainId];
+  if (!domain) {
+    throw new HavenSigningError(
+      `Sweep is only supported on Base (chainId ${SWEEP_BASE_CHAIN_ID}). Got chainId ${chainId}.`
+    );
+  }
+  return domain;
+}
+function sameAddress2(a, b) {
+  return a.toLowerCase() === b.toLowerCase();
+}
+function buildSweepTypedData(auth) {
+  const domain = sweepUsdcDomain(auth.chainId);
+  const expectedToken = sweepUsdcAddress(auth.chainId);
+  if (!sameAddress2(auth.token, expectedToken)) {
+    throw new HavenSigningError(
+      `Sweep token ${auth.token} is not the canonical USDC contract for chain ${auth.chainId}.`
+    );
+  }
+  if (!/^0x[0-9a-fA-F]{64}$/.test(auth.nonce)) {
+    throw new HavenSigningError("Sweep nonce must be a 0x-prefixed 32-byte hex string.");
+  }
+  return {
+    domain,
+    types: TRANSFER_WITH_AUTHORIZATION_TYPES,
+    primaryType: "TransferWithAuthorization",
+    message: {
+      from: auth.from,
+      to: auth.to,
+      value: BigInt(auth.value),
+      validAfter: BigInt(auth.validAfter),
+      validBefore: BigInt(auth.validBefore),
+      nonce: auth.nonce
+    }
+  };
+}
+function buildSweepAuthorizationMessage(auth) {
+  return `Haven sweep authorization v1
+${stableStringify2({
+    version: 1,
+    kind: "haven.sweep.authorization",
+    from: auth.from.toLowerCase(),
+    to: auth.to.toLowerCase(),
+    value: auth.value,
+    validAfter: auth.validAfter,
+    validBefore: auth.validBefore,
+    nonce: auth.nonce.toLowerCase(),
+    token: auth.token.toLowerCase(),
+    chainId: auth.chainId
+  })}`;
+}
+function stableStringify2(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map((item) => stableStringify2(item)).join(",")}]`;
+  const object = value;
+  return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${stableStringify2(object[key])}`).join(",")}}`;
+}
+
+exports.AGENT_PAYMENT_FAILURE_CODE_VALUES = AGENT_PAYMENT_FAILURE_CODE_VALUES;
 exports.AGENT_PAYMENT_NEXT_ACTION_VALUES = AGENT_PAYMENT_NEXT_ACTION_VALUES;
 exports.AGENT_PAYMENT_PHASE_VALUES = AGENT_PAYMENT_PHASE_VALUES;
 exports.AGENT_PAYMENT_RAIL_VALUES = AGENT_PAYMENT_RAIL_VALUES;
+exports.AgentPaymentFailureCode = AgentPaymentFailureCode;
+exports.AgentPaymentFailureCodeDescriptions = AgentPaymentFailureCodeDescriptions;
+exports.AgentPaymentFailureCodeSchema = AgentPaymentFailureCodeSchema;
 exports.AgentPaymentNextAction = AgentPaymentNextAction;
 exports.AgentPaymentNextActionDescriptions = AgentPaymentNextActionDescriptions;
 exports.AgentPaymentNextActionSchema = AgentPaymentNextActionSchema;
@@ -3190,8 +3464,13 @@ exports.HavenPaymentStateError = HavenPaymentStateError;
 exports.HavenSigningError = HavenSigningError;
 exports.HavenTimeoutError = HavenTimeoutError;
 exports.SKILL_FOLDER_NAME = SKILL_FOLDER_NAME;
+exports.SWEEP_BASE_CHAIN_ID = SWEEP_BASE_CHAIN_ID;
+exports.SWEEP_BASE_USDC_ADDRESS = SWEEP_BASE_USDC_ADDRESS;
+exports.TRANSFER_WITH_AUTHORIZATION_TYPES = TRANSFER_WITH_AUTHORIZATION_TYPES;
 exports.addressFromKey = addressFromKey;
 exports.buildMachinePaymentIdempotencyKey = buildMachinePaymentIdempotencyKey;
+exports.buildSweepAuthorizationMessage = buildSweepAuthorizationMessage;
+exports.buildSweepTypedData = buildSweepTypedData;
 exports.buildX402ExpectedMessage = buildX402ExpectedMessage;
 exports.composeDescription = composeDescription;
 exports.decodeBase64Json = decodeBase64Json;
@@ -3208,6 +3487,8 @@ exports.parsePaymentRequiredResponse = parsePaymentRequiredResponse;
 exports.selectPaymentOption = selectPaymentOption;
 exports.selectStandardPaymentOption = selectStandardPaymentOption;
 exports.signHash = signHash;
+exports.sweepUsdcAddress = sweepUsdcAddress;
+exports.sweepUsdcDomain = sweepUsdcDomain;
 exports.toStandardPaymentRequirements = toStandardPaymentRequirements;
 exports.toolDescriptions = toolDescriptions;
 exports.verifySignature = verifySignature;