@haven_ai/sdk 0.1.32-alpha.0 → 0.1.34-alpha.0

package/README.md

@@ -125,7 +125,8 @@ if (apiResponse.status === 402) {
   const receipt = await haven.authorizeX402(paymentRequired, {
     idempotencyKey: 'paid-api-data-2026-05-22',
   })
-  // Retry with { 'X-PAYMENT': receipt.paymentHeader }
+  // Retry with { 'PAYMENT-SIGNATURE': receipt.paymentHeader }, and on the
+  // EIP-3009 bridge 'X-PAYMENT' too. NEVER both on erc7710 — see below.
   console.log(receipt.explorerUrl)
 }
 ```
@@ -209,7 +210,7 @@ const response = await haven.payX402Quote(quote)
 const data = await response.json()
 ```
 
-Merchant-verified x402 retries use the official EIP-3009 `exact` scheme on Base USDC (`base` / `eip155:8453`) and send the payment as `X-PAYMENT`. Haven's older tx-hash proof helper remains exported for Haven-native integrations, but `haven.fetch()` does not send `PAYMENT-SIGNATURE`.
+Merchant-verified x402 retries use the official EIP-3009 `exact` scheme on Base USDC (`base` / `eip155:8453`). `haven.fetch()` sends the payment under `PAYMENT-SIGNATURE` (the x402 v2 name), and on the EIP-3009 bridge also under `X-PAYMENT` (v1), so a merchant on either version reads it. **On erc7710 it sends the v2 name ALONE**: that payload is always x402 v2, and its header carries a whole delegation chain, so duplicating it overflows the merchant's header limit and the request is refused with HTTP 431. If you build the retry yourself, follow the same rule. Haven's older tx-hash proof helper remains exported for Haven-native integrations; it is a different payload that happens to have shared the v2 name, and it is not what `haven.fetch()` sends.
 
 For standard x402, the `x402-wallet` identity is the agent delegate wallet, because that is the wallet that signs and settles the merchant payment. Integrations that scope access by Haven wallet/Safe address should use a Haven-native flow instead of standard merchant x402.
 
@@ -364,7 +365,7 @@ x402 tool-window failures:
 | `expired` | Payment expired before completion. | yes |
 | `failed` | Haven could not complete the payment. | yes |
 
-The merchant settlement leg of x402 (and the MPP retry) is the agent's own request to the merchant — it does not have a Haven `phase`. The payment is `funding_sent` until the agent retries with `X-PAYMENT` (x402) or the MPP proof header; from Haven's perspective the payment becomes `executed` only after the agent successfully resumes.
+The merchant settlement leg of x402 (and the MPP retry) is the agent's own request to the merchant — it does not have a Haven `phase`. The payment is `funding_sent` until the agent retries with the payment header (`PAYMENT-SIGNATURE`, plus `X-PAYMENT` on this bridged path) (x402) or the MPP proof header; from Haven's perspective the payment becomes `executed` only after the agent successfully resumes.
 
 ### `nextAction` reference
 
@@ -471,7 +472,9 @@ Think of bridged x402 as two separate legs:
   `txHash` describe this leg. It is automatic and bounded by the budget — no
   human step.
 - Merchant x402 leg: after the funding leg is complete, the agent resumes the
-  same payment id and retries the original merchant request with `X-PAYMENT`.
+  same payment id and retries the original merchant request with the payment
+  header, under `PAYMENT-SIGNATURE` and — on this bridged path only —
+  `X-PAYMENT`.
   Do not treat a new 402 probe or a new MCP session as a resume.
 
 For manual HTTP stacks, use `resumeAuthorizedX402()` to get the merchant header
@@ -485,15 +488,58 @@ const receipt = await haven.resumeAuthorizedX402({
 })
 
 await fetch('https://paid-api.example.com/data', {
-  headers: { 'X-PAYMENT': receipt.paymentHeader! },
+  headers: {
+    'PAYMENT-SIGNATURE': receipt.paymentHeader!,
+    // Bridged (EIP-3009) resume only. On erc7710 send the v2 name ALONE —
+    // that header carries a delegation chain and duplicating it is refused
+    // with HTTP 431.
+    'X-PAYMENT': receipt.paymentHeader!,
+  },
 })
 ```
 
+**When YOU make the retry, report the outcome (#2292).** `haven.fetch()` and
+the `payX402*` helpers call the merchant themselves and write the evidence or
+reconciliation record from what they observed. `resumeAuthorizedX402()` and the
+raw MCP/SSE flow below deliberately do not — you hold the header and make the
+call — so Haven cannot learn what happened unless you tell it:
+
+```typescript
+const response = await fetch('https://paid-api.example.com/data', {
+  headers: {
+    'PAYMENT-SIGNATURE': receipt.paymentHeader!,
+    // Bridged (EIP-3009) resume only — see the erc7710 note above.
+    'X-PAYMENT': receipt.paymentHeader!,
+  },
+})
+
+await haven.reportX402MerchantOutcome({
+  paymentId: status.paymentId,
+  outcome: response.ok ? 'accepted' : 'rejected',
+  merchantStatus: response.status,
+})
+```
+
+A `rejected` report writes the same open `merchant_retry_rejected_after_payment`
+reconciliation event the built-in retry writes, so the next
+`getPaymentStatus()` answers `phase: funded_but_unsettled` /
+`nextAction: sweep_stranded_funds` instead of reading as complete for the
+fifteen-minute merchant-report grace window. An `accepted` report records the
+merchant response so a delivered payment never enters that window at all.
+
+It is evidence, not authority. The funding transaction hash and resource URL are
+read from the payment's own record rather than taken from you — they are not
+parameters — the call is scoped to your own agent's payments, and it changes no
+amount, recipient or status. `outcome` must agree with `merchantStatus`
+(`accepted` only for a 2xx), and an acceptance is terminal: a rejection reported
+after a recorded merchant response is refused rather than re-flagging a
+delivered payment as stranded.
+
 For MCP/SSE x402 tools, keep the same MCP session and JSON-RPC payload where the
 merchant requires it: initialize, retain `mcp-session-id`, send the original
 `tools/call`, parse the 402 challenge, wait for the funding leg to confirm if
 the payment is bridged, then resume with the same `payment_id` and retry the
-original `tools/call` with `X-PAYMENT`. Use a stable `idempotencyKey` for the
+original `tools/call`, setting BOTH `PAYMENT-SIGNATURE` (x402 v2) and `X-PAYMENT` (v1) to the header. Use a stable `idempotencyKey` for the
 user intent so fresh merchant quotes or sessions do not become duplicate Haven
 payments.
 

package/dist/index.cjs

@@ -617,6 +617,7 @@ function normalizePaymentRequired(value) {
   const resourceUrl = candidate.resource?.url ?? first.resource;
   if (!resourceUrl) return null;
   const resource = {
+    ...candidate.resource && typeof candidate.resource === "object" ? candidate.resource : {},
     url: resourceUrl,
     description: candidate.resource?.description ?? first.description,
     mimeType: candidate.resource?.mimeType ?? first.mimeType
@@ -667,6 +668,41 @@ var NETWORK_TOKENS = {
   "eip155:84532": BASE_SEPOLIA_TOKENS,
   "base-sepolia": BASE_SEPOLIA_TOKENS
 };
+var X402_PAYMENT_HEADER_NAME = "PAYMENT-SIGNATURE";
+var X402_LEGACY_PAYMENT_HEADER_NAME = "X-PAYMENT";
+var X402_PAYMENT_REQUIRED_HEADER_NAME = "PAYMENT-REQUIRED";
+var X402_PAYMENT_RESPONSE_HEADER_NAME = "PAYMENT-RESPONSE";
+var X402_PAYMENT_HEADER_NAMES_SENT = `${X402_PAYMENT_HEADER_NAME}, ${X402_LEGACY_PAYMENT_HEADER_NAME}`;
+var X402_PAYMENT_HEADER_NAMES = [
+  X402_PAYMENT_HEADER_NAME,
+  X402_LEGACY_PAYMENT_HEADER_NAME
+];
+function x402PaymentHeaderNamesFor(paymentHeader) {
+  const both = [X402_PAYMENT_HEADER_NAME, X402_LEGACY_PAYMENT_HEADER_NAME];
+  let decoded;
+  try {
+    decoded = decodeBase64Json(paymentHeader);
+  } catch {
+    return both;
+  }
+  const accepted = decoded?.accepted;
+  if (!accepted || typeof accepted !== "object" || Array.isArray(accepted)) return both;
+  return isErc7710Option(accepted) ? [X402_PAYMENT_HEADER_NAME] : both;
+}
+function x402PaymentHeaderNamesSent(paymentHeader) {
+  return x402PaymentHeaderNamesFor(paymentHeader).join(", ");
+}
+function x402V2PaymentEnvelope(paymentRequired, accepted, payload) {
+  const resource = paymentRequired.resource;
+  const extensions = paymentRequired.extensions;
+  return {
+    x402Version: paymentRequired.x402Version,
+    ...resource && typeof resource === "object" && !Array.isArray(resource) ? { resource } : {},
+    accepted,
+    payload,
+    ...extensions && typeof extensions === "object" && !Array.isArray(extensions) ? { extensions } : {}
+  };
+}
 function parsePaymentRequired(response) {
   const v2Header = response.headers.get("PAYMENT-REQUIRED");
   if (v2Header) {
@@ -846,7 +882,15 @@ async function validateStandardX402PaymentHeader(paymentHeader, context) {
         throw new Error("context");
       }
     } else {
-      if (!hasOnlyKeys(decoded, ["x402Version", "accepted", "payload"])) throw new Error("shape");
+      if (!hasOnlyKeys(decoded, ["x402Version", "accepted", "payload"], ["resource", "extensions"])) {
+        throw new Error("shape");
+      }
+      if ("resource" in decoded && (!decoded.resource || typeof decoded.resource !== "object" || Array.isArray(decoded.resource))) {
+        throw new Error("shape");
+      }
+      if ("extensions" in decoded && (!decoded.extensions || typeof decoded.extensions !== "object" || Array.isArray(decoded.extensions))) {
+        throw new Error("shape");
+      }
       const accepted = selectStandardPaymentOption([decoded.accepted]);
       if (!accepted || !matchesHeaderContext(accepted, context)) throw new Error("context");
     }
@@ -898,8 +942,8 @@ async function validateStandardX402PaymentHeader(paymentHeader, context) {
     throw new X402PaymentHeaderValidationError();
   }
 }
-function hasOnlyKeys(value, allowed) {
-  return Object.keys(value).every((key) => allowed.includes(key)) && allowed.every((key) => key in value);
+function hasOnlyKeys(value, required, optional = []) {
+  return Object.keys(value).every((key) => required.includes(key) || optional.includes(key)) && required.every((key) => key in value);
 }
 function sameAddress2(left, right) {
   return left.toLowerCase() === right.toLowerCase();
@@ -1157,7 +1201,7 @@ function nextActionForStatus(status) {
   if (status === "submitted") return AgentPaymentNextAction.CheckStatusLater;
   if (status === "confirmed") return AgentPaymentNextAction.None;
   if (status === "pending" || status === "pending_approval") return AgentPaymentNextAction.StopAndTellUser;
-  if (status === "approved") return AgentPaymentNextAction.WaitForUserToCompletePayment;
+  if (status === "approved") return AgentPaymentNextAction.StopAndTellUser;
   if (status === "proposed") return AgentPaymentNextAction.StopAndTellUser;
   if (status === "executed") return AgentPaymentNextAction.StopAndTellUser;
   if (status === "rejected") return AgentPaymentNextAction.StopAndTellUser;
@@ -1169,6 +1213,9 @@ function messageForState(label, status, paymentId, nextAction) {
   if (status === "pending" || status === "pending_approval") {
     return `${label} is not payable: it is outside the agent's on-chain budget and no approval is pending (payment_id: ${paymentId}). Ask the user to grant or raise the budget in Haven.`;
   }
+  if (status === "approved") {
+    return `This payment carries a retired status ("approved") that no live Haven rail produces (payment_id: ${paymentId}). Nothing is waiting to be completed \u2014 tell the user to review this payment in Haven.`;
+  }
   if (status === "executed") {
     return `This payment carries a retired status ("executed") that no live Haven rail produces (payment_id: ${paymentId}). Do not retry it \u2014 tell the user to review this payment in Haven.`;
   }
@@ -1386,10 +1433,37 @@ var McpMerchantTransport = class {
   hasBazaarExtension(response) {
     return responseHasBazaarExtension(response);
   }
-  /** Deliver an already-signed x402 header without changing the caller body. */
+  /**
+   * Deliver an already-signed x402 header without changing the caller body.
+   *
+   * #2289: x402 v2 reads `PAYMENT-SIGNATURE`; v1 reads `X-PAYMENT`. Sending
+   * only the legacy name meant a strict v2 merchant never saw the header —
+   * indistinguishable, from the merchant's side, from sending no header at
+   * all, while on the EIP-3009 bridge the funding leg had already moved the
+   * money.
+   *
+   * #2341: WHICH names go on is per-payload, not always both — see
+   * `x402PaymentHeaderNamesFor`. Both for EIP-3009; `PAYMENT-SIGNATURE` alone
+   * for erc7710, whose header carries a whole delegation chain and answered
+   * HTTP 431 when duplicated. The decision is made here rather than by the
+   * caller so every path inherits it, and it is read from the payload rather
+   * than passed in, because a flag a caller supplies is a flag a caller can
+   * get wrong.
+   *
+   * Always `set`, never `append`, so a stale header on the caller's `init` is
+   * replaced rather than added to — a merchant that reads the first of two
+   * values would otherwise verify a superseded authorization. The name NOT
+   * being sent is deleted for the same reason: on erc7710 a stale `X-PAYMENT`
+   * left in place would be a superseded authorization we chose not to
+   * overwrite, which is worse than the duplicate this change removes.
+   */
   async deliverPayment(url, init, paymentHeader) {
     const headers = new Headers(init?.headers);
-    headers.set("X-PAYMENT", paymentHeader);
+    const send = x402PaymentHeaderNamesFor(paymentHeader);
+    for (const name of X402_PAYMENT_HEADER_NAMES) {
+      if (send.includes(name)) headers.set(name, paymentHeader);
+      else headers.delete(name);
+    }
     return this.fetch(url, { ...init, headers });
   }
   async notifyInitialized(url, init, sessionId, wallet) {
@@ -2074,11 +2148,7 @@ var X402FundingLeg = class {
     );
     if (paymentRequired.x402Version < 2) return header;
     const payment = decodeBase64Json(header);
-    return encodeBase64Json({
-      x402Version: paymentRequired.x402Version,
-      accepted: option,
-      payload: payment.payload
-    });
+    return encodeBase64Json(x402V2PaymentEnvelope(paymentRequired, option, payment.payload));
   }
   // ── Receipt mapping ──────────────────────────────────────────────
   receiptFromAuthorization(paymentRequired, option, paymentHeader, raw, execResult) {
@@ -2235,10 +2305,11 @@ var X402Erc7710 = class {
    * settled when this returns** — that is why it does not return an
    * `X402Receipt`.
    *
-   * Requires a delegation-rail account. The backend enforces that
-   * (`validateGenericSchemeRail`), and so does this method, before building a
-   * request the backend would only reject: an error a client can explain is
-   * worth more than a 400 it has to decode.
+   * Requires a delegation-rail account. The backend enforces that at the
+   * rail seam — a non-delegation account gets the #1986 retired-rail 410 from
+   * `POST /x402/authorize` whatever scheme it asks for (#2245) — and so does
+   * this method, before building a request the backend would only reject: an
+   * error a client can explain is worth more than a refusal it has to decode.
    *
    * **MCP callers must pass `options.resourceUrl`.** An in-band MCP 402
    * challenge frequently carries no `resource` object at all, so
@@ -2288,6 +2359,16 @@ var X402Erc7710 = class {
     const amountAtomic = x402AuthorizationAmount(option);
     const raw = await this.post("/x402", {
       url: options.resourceUrl ?? paymentRequired.resource?.url,
+      // #2373: the full 402 challenge, persisted verbatim by the backend
+      // (#1355) so the settle handoff can echo its resource/extensions into
+      // the X-PAYMENT envelope (#2361). This scheme decomposes the challenge
+      // into the fields below for AUTHORITY; the stored copy exists for the
+      // echo, which cannot be reconstructed from the decomposition — omitting
+      // it is how every erc7710 payment failed a merchant that enforces the
+      // spec's extensions-echo MUST. Same ≤64KB guard and omission behaviour
+      // as the 3009 path (client.ts): an oversized challenge omits the field
+      // rather than failing the payment, and the settle echo then omits too.
+      ...new TextEncoder().encode(JSON.stringify(paymentRequired)).length <= 65536 ? { paymentRequired } : {},
       // payTo = the MERCHANT is what selects direct settlement server-side.
       // The explicit settlementScheme must AGREE with that shape (#1360) —
       // disagreement is a 400 by design, so that a stale delegate address
@@ -2532,7 +2613,7 @@ var MerchantCompletion = class {
       merchantStatus: retryResponse.status,
       challengePayload: paymentRequired,
       selectedPayment: receipt.accepted,
-      paymentProofHeaderName: "X-PAYMENT",
+      paymentProofHeaderName: x402PaymentHeaderNamesSent(receipt.paymentHeader),
       paymentProofHeader: receipt.paymentHeader,
       protocolReceiptHeaderName: "PAYMENT-RESPONSE",
       protocolReceiptHeader: retryResponse.headers.get("PAYMENT-RESPONSE") ?? void 0
@@ -2642,6 +2723,109 @@ var MerchantCompletion = class {
     } catch {
     }
   }
+  /**
+   * #2292: record what a merchant said to a retry **Haven did not make**.
+   *
+   * On the plain-HTTP x402 path Haven tells the agent to call the merchant
+   * itself — that is the keyless design, not an oversight — so the two writes
+   * above were reachable only from `completeX402MerchantCall`, where Haven IS
+   * the caller. A manual retry had nowhere to put its outcome, which left
+   * `intentStateFor`'s merchant-rejected branch dead on the one flow Haven
+   * prescribes and made the 15-minute grace window the only route to
+   * `funded_but_unsettled`.
+   *
+   * Three properties distinguish this from `recordRetryRejected` /
+   * `reportEvidence`, and each is deliberate:
+   *
+   * 1. **It does not swallow.** Those two are bookkeeping hung off a call
+   *    whose outcome is already decided, so an exception there would turn a
+   *    completed payment into a reported failure. Here the report IS the
+   *    caller's request; silently dropping it would recreate the exact
+   *    unobservability #2292 exists to remove.
+   * 2. **The anchor is server-side.** `txHash` and `resourceUrl` come from
+   *    the payment's own Haven record, never from the reporter — so a report
+   *    cannot be pointed at a different transaction or a different resource,
+   *    and it can never CONFIRM an intent (an erc7710 intent has no Haven
+   *    tx hash and is refused here rather than completed from a supplied one,
+   *    which is #2092's verified seam and stays its own path).
+   * 3. **It is evidence, never authority.** Haven does not and must not check
+   *    the claim: verifying it would mean calling the merchant, which is the
+   *    property this whole path exists to preserve. What bounds a false
+   *    report is scope — the backend routes resolve the payment
+   *    `WHERE agent_id = $`, so a caller can only ever describe its own
+   *    payment — plus the fact that nothing financial keys off the claim:
+   *    the sweep is balance-driven, the intent's status/amount/recipient are
+   *    untouched, and a false `accepted` runs the server's own on-chain
+   *    residue check, which re-flags stranded funds independently.
+   */
+  async reportMerchantOutcome(input) {
+    if (!Number.isInteger(input.merchantStatus) || input.merchantStatus < 100 || input.merchantStatus > 599) {
+      throw new HavenApiError(
+        `merchant_status must be an integer HTTP status from 100 to 599 (received ${input.merchantStatus}).`,
+        400,
+        void 0,
+        input.paymentId
+      );
+    }
+    const looksAccepted = input.merchantStatus >= 200 && input.merchantStatus < 300;
+    if (looksAccepted !== (input.outcome === "accepted")) {
+      throw new HavenApiError(
+        `outcome "${input.outcome}" contradicts merchant_status ${input.merchantStatus}: report "accepted" only for a 2xx and "rejected" only for a non-2xx.`,
+        400,
+        void 0,
+        input.paymentId
+      );
+    }
+    const status = await this.getPaymentStatus(input.paymentId);
+    if (status.rail !== "x402") {
+      throw new HavenPaymentStateError(
+        `Payment ${status.paymentId} is ${status.rail}, not x402 \u2014 there is no merchant retry to report.`,
+        409,
+        status
+      );
+    }
+    if (status.status !== "confirmed" || !status.txHash) {
+      throw new HavenPaymentStateError(
+        `Payment ${status.paymentId} has no confirmed Haven funding transaction to anchor a merchant report to (status ${status.status}). ${status.message}`,
+        paymentStateStatusCode(status.status, 409),
+        status
+      );
+    }
+    const resourceUrl = status.resourceUrl ?? status.x402?.resourceUrl ?? null;
+    if (!resourceUrl) {
+      throw new HavenApiError(
+        `Payment ${status.paymentId} has no recorded resource URL, so a merchant report cannot be stored.`,
+        409,
+        status,
+        status.paymentId
+      );
+    }
+    const txHash = status.txHash;
+    if (input.outcome === "rejected") {
+      await this.post("/machine-payments/reconciliation-events", {
+        paymentId: status.paymentId,
+        rail: "x402",
+        eventType: "merchant_retry_rejected_after_payment",
+        txHash,
+        reason: `Agent-reported: merchant returned HTTP ${input.merchantStatus} to a manual retry after Haven payment confirmation`,
+        details: {
+          resource_url: resourceUrl,
+          retry_status: input.merchantStatus,
+          retry_body: input.merchantBody?.slice(0, MERCHANT_BODY_SNIPPET_LIMIT) || null,
+          reported_by: "agent_manual_retry"
+        }
+      });
+      return { paymentId: status.paymentId, outcome: "rejected", txHash, resourceUrl, recorded: "reconciliation_event" };
+    }
+    await this.post("/machine-payments/evidence", {
+      paymentId: status.paymentId,
+      rail: "x402",
+      txHash,
+      resourceUrl,
+      merchantStatus: input.merchantStatus
+    });
+    return { paymentId: status.paymentId, outcome: "accepted", txHash, resourceUrl, recorded: "evidence" };
+  }
   async reportEvidence(input) {
     const body = {
       paymentId: input.paymentId,
@@ -3528,7 +3712,7 @@ var HavenClient = class {
    * Deliver an already-signed x402 payment header to the merchant and return
    * the merchant's response. Used by the hosted MCP server to complete the
    * merchant leg of an MCP tool payment after the edge signer has built the
-   * `X-PAYMENT` header.
+   * merchant payment header.
    *
    * Custody note: this never needs the delegate key. It relays a signed,
    * amount/merchant/nonce-bound EIP-3009 authorization the edge signer already
@@ -3538,13 +3722,14 @@ var HavenClient = class {
    * 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
+   * accepted), threads the session + wallet headers, sets the x402 payment
+   * header under the names that scheme requires (#2341), and
    * collapses an SSE JSON-RPC response to its `result`.
    */
   /**
    * Wait for a payment's Safe→delegate funding tx to reach ≥1 on-chain
    * confirmation. The hosted x402 completion path MUST call this after funding
-   * and before delivering the X-PAYMENT header, so the merchant's
+   * and before delivering the merchant payment header, so the merchant's
    * balanceOf(delegate) / transferWithAuthorization verification sees the funded
    * balance — otherwise it rejects with "Payment verification failed". The
    * SDK's local path already does this (see `X402FundingLeg.authorize`); the hosted
@@ -3619,7 +3804,7 @@ var HavenClient = class {
           txHash: evidenceTxHash,
           resourceUrl: evidenceContext.resourceUrl,
           merchantStatus: surfaced.status,
-          paymentProofHeaderName: "X-PAYMENT",
+          paymentProofHeaderName: x402PaymentHeaderNamesSent(input.paymentHeader),
           paymentProofHeader: input.paymentHeader,
           protocolReceiptHeaderName: protocolReceiptHeader ? "PAYMENT-RESPONSE" : void 0,
           protocolReceiptHeader
@@ -3634,6 +3819,18 @@ var HavenClient = class {
       settlementTxHash: settlement.settlementTxHash ?? void 0
     };
   }
+  /**
+   * #2292: report the outcome of a merchant retry the AGENT performed.
+   *
+   * The hosted `haven_complete_mcp_tool` / `completeX402MerchantCall` path is
+   * for merchants Haven calls itself. On the plain-HTTP x402 path Haven never
+   * talks to the merchant, so the outcome of that retry had no way back —
+   * see `MerchantCompletion.reportMerchantOutcome` for what is verified about
+   * a caller-asserted report and what deliberately is not.
+   */
+  async reportX402MerchantOutcome(input) {
+    return await this.merchantCompletion.reportMerchantOutcome(input);
+  }
   /**
    * GET /x402/:id/merchant-call-context — the settle-leg twin of #1263's
    * sign-context fetch (#1307). Re-serves the stored merchant MCP-tool call
@@ -3795,12 +3992,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 X-PAYMENT header 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, 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.",
     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_safe_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 X-PAYMENT header. No new Haven payment is created.",
+    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.",
     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
@@ -3986,7 +4183,7 @@ var resumeX402Schema = {
 var MAKE_PAYMENT_DESCRIPTION = "Request and sign a payment from the user-controlled account within its on-chain budget. For read-only allowance, budget, spend-limit, remaining-amount, or reset-period questions, use get_allowances instead of making a payment. Haven authenticates the agent and relays the signed transaction that redeems the agent budget delegation; it does not hold keys or control funds. Gnosis Chain tokens: EURe, USDC.e, xDAI. Base tokens: USDC, ETH.";
 var GET_STATUS_DESCRIPTION = toolDescriptions.getPaymentStatus.summary + " Accepts payment intent IDs. Returns the current status, phase, next_action, transaction hash if available, and payment details.";
 var GET_ALLOWANCES_DESCRIPTION = composeDescription(toolDescriptions.getAllowances);
-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; funding, when the scheme needs it, is redeemed from the agent budget delegation and is bounded by it. Haven relays signed transactions only; the agent key authorizes payment and on-chain limits enforce spend. A payment outside the on-chain budget is declined before any money moves \u2014 report the decline and ask the user to raise the budget in Haven; do not loop retries and do not wait for an approval, because none is queued. Preserve the original merchant/MCP session and x402 details. Use the returned payment_header as the X-PAYMENT header on the retry request when doing a manual HTTP retry.";
+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; funding, when the scheme needs it, is redeemed from the agent budget delegation and is bounded by it. Haven relays signed transactions only; the agent key authorizes payment and on-chain limits enforce spend. A payment outside the on-chain budget is declined before any money moves \u2014 report the decline and ask the user to raise the budget in Haven; do not loop retries and do not wait for an approval, because none is queued. Preserve the original merchant/MCP session and x402 details. On a manual HTTP retry always set PAYMENT-SIGNATURE (x402 v2) to the returned payment_header; a strict v2 merchant reads only that name. Also set X-PAYMENT (v1) on the EIP-3009 funding path for legacy merchants, but NEVER on erc7710 \u2014 that header carries a delegation chain and duplicating it is refused with HTTP 431.";
 var RESUME_X402_DESCRIPTION = toolDescriptions.resumeX402.summary + " Only call this after get_payment_status reports nextAction=retry_original_x402_request \u2014 that means Haven's funding leg confirmed but no merchant response was ever recorded (typically a crash between funding and the merchant retry). Any other nextAction reports a conflict instead of retrying \u2014 do not call this speculatively, and do not pay again.";
 var SWEEP_DELEGATE_DESCRIPTION = composeDescription(toolDescriptions.sweep_delegate);
 var sweepDelegateSchema = {
@@ -4198,8 +4395,14 @@ The paid call always obtains a fresh quote before it creates any intent. Then
 continue \`mcp__haven__haven_pay_mcp_tool\` \u2192
 \`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 quote/prepare result.
+\`mcp__haven__haven_complete_mcp_tool\`. Call that last step with
+\`payment_id\` and the signer's \`payment_header\` ONLY. It does not take
+\`payment_required\`: Haven rehydrates the merchant call context
+(\`merchant_url\`, \`tool_name\`, \`arguments\`, \`mcp_transport\`) and the
+402 server-side from \`payment_id\`, exactly as at settle. Pass that context
+explicitly only as a version-skew fallback when Haven has no stored context
+for the id \u2014 \`merchant_url\` and \`tool_name\` both or none together, never
+just one.
 The returned \`expires_at\` is the signing window; if a tool returns
 \`PAYMENT_WINDOW_EXPIRED\`, re-run the same quote/prepare tool with the same
 \`idempotency_key\`. Do not call the merchant yourself \u2014 Haven completes the
@@ -4209,8 +4412,20 @@ merchant leg for you.
 recipient, amount, and token for a plain transfer. For an arbitrary,
 non-MCP x402 paywall: \`mcp__haven__haven_quote_x402\` to get a quote, then
 \`mcp__haven__haven_pay_x402_quote\` \u2014 follow the result's guidance fields
-first and sign in the local Haven signer. The pay tool performs the merchant
-retry itself, so do not wait on a signal while it runs. If the process
+first and sign in the local Haven signer. On THIS path Haven does not talk to
+the merchant: \`mcp__haven-signer__haven_sign_x402\` returns both
+\`signature\` and \`payment_header\`; relay \`signature\` with
+\`mcp__haven__haven_submit\`, then retry the paywalled URL yourself with
+\`payment_header\`. Do not pass that call's \`x402_binding\` to
+\`mcp__haven-signer__haven_x402_sign_header\` \u2014 the one-shot already spent it
+building the header, so the call can only refuse. Then tell Haven what the
+merchant answered: \`mcp__haven__haven_report_x402_outcome\` with the
+\`payment_id\`, \`outcome\` (\`"accepted"\` for a 2xx, else \`"rejected"\`)
+and the \`merchant_status\` you got. Because Haven never contacted that
+merchant, this is the only way it can learn the purchase failed \u2014 without it a
+failed purchase reads as complete for fifteen minutes. (The SDK's own
+\`haven_pay_x402\` tool does perform the merchant retry itself; that tool is
+not part of the hosted MCP surface.) If the process
 crashes after payment, a later \`mcp__haven__haven_get_payment_status\` call
 may report \`nextAction: 'retry_original_x402_request'\` \u2014 only then call
 \`mcp__haven__haven_resume_x402_payment\` with the preserved resume state or
@@ -4225,9 +4440,11 @@ payment id, instead of paying again.
 result, never a catalog price. \`haven_discover_tools\` prices are indicative
 (\`price_is_indicative\`) and can be stale. A read-only quote is informational
 only and does not reserve a price; the later paid call re-quotes and enforces
-the cap. The pay-tool result's \`amount\` / \`amount_atomic\` is the amount
-Haven authorizes for that call \u2014 a ceiling the merchant settles at or below \u2014
-so present it as the most the user will pay.
+the cap. The pay-tool result's \`amount\` / \`amount_atomic\` is the merchant's
+own quoted price for that call \u2014 a ceiling the merchant settles at or below \u2014
+so present it as the most the user will pay. It is a price, not an approval:
+the payment goes through only if it also fits the cap you set and the on-chain
+budget the user signed, which is enforced on-chain rather than by Haven.
 
 **Status:** \`mcp__haven__haven_get_payment_status\` with a \`payment_id\` to
 check on in-flight payments. Do not poll in a tight loop.
@@ -4422,7 +4639,12 @@ exports.TRANSFER_WITH_AUTHORIZATION_TYPES = TRANSFER_WITH_AUTHORIZATION_TYPES;
 exports.X402AlreadySettledError = X402AlreadySettledError;
 exports.X402PaymentHeaderValidationError = X402PaymentHeaderValidationError;
 exports.X402UnexpectedStatusError = X402UnexpectedStatusError;
+exports.X402_LEGACY_PAYMENT_HEADER_NAME = X402_LEGACY_PAYMENT_HEADER_NAME;
 exports.X402_MAX_AUTHORIZATION_WINDOW_SECONDS = X402_MAX_AUTHORIZATION_WINDOW_SECONDS;
+exports.X402_PAYMENT_HEADER_NAME = X402_PAYMENT_HEADER_NAME;
+exports.X402_PAYMENT_HEADER_NAMES_SENT = X402_PAYMENT_HEADER_NAMES_SENT;
+exports.X402_PAYMENT_REQUIRED_HEADER_NAME = X402_PAYMENT_REQUIRED_HEADER_NAME;
+exports.X402_PAYMENT_RESPONSE_HEADER_NAME = X402_PAYMENT_RESPONSE_HEADER_NAME;
 exports.X402_SETTLEMENT_FORWARD_MARGIN_SECONDS = X402_SETTLEMENT_FORWARD_MARGIN_SECONDS;
 exports.addressFromKey = addressFromKey;
 exports.buildSweepAuthorizationMessage = buildSweepAuthorizationMessage;
@@ -4462,5 +4684,6 @@ exports.verifySignature = verifySignature;
 exports.x402AssetTransferMethod = x402AssetTransferMethod;
 exports.x402AuthorizationAmount = x402AuthorizationAmount;
 exports.x402FacilitatorAddresses = x402FacilitatorAddresses;
+exports.x402V2PaymentEnvelope = x402V2PaymentEnvelope;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map