@haven_ai/sdk 0.2.0-alpha.0 → 0.2.1-alpha.0

package/README.md

@@ -85,9 +85,13 @@ shows up in your Haven dashboard activity feed.
 ## Step-by-Step API
 
 Discovery and listing: `discoverTools({ verified?: 'any' | 'verified' | 'operator' })` returns the merged
-catalog — operator-curated plus `verified_payable` directory entries (epic #1717), each with `source`,
-`domainVerified` and `verifiedPayable`. `submitCatalogEntry(resourceUrl)` submits a merchant endpoint to
-the Verified Payable Directory (queue-only; the seller still must prove domain ownership before listing),
+catalog — operator-curated rows plus self-submitted directory entries (epic #1717), each with `source`,
+`domainVerified` and `verifiedPayable`. `verified: 'verified'` (#2978) filters on the badge, not the
+source: it returns any entry, from either source, whose endpoint Haven watched answer a live quote
+probe (`verifiedPayable === true`); `domainVerified` stays true only for entries that also proved
+domain ownership. `verified: 'operator'` filters on provenance alone. `submitCatalogEntry(resourceUrl)`
+submits a merchant endpoint to the Verified Payable Directory (queue-only; the seller still must prove
+domain ownership before listing),
 and `getCatalogSubmissionStatus(id)` returns coarse status plus the ownership-proof instructions while
 the submission can still prove ownership.
 
@@ -358,7 +362,8 @@ Terminal from any non-confirmed phase:
 
 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
+   merchant rejection after funding → MERCHANT_REJECTED_AFTER_FUNDING → haven_sweep_delegate (eip3009 only; erc7710: nothing to sweep, follow the message)
+   merchant timeout after funding → MERCHANT_UNRESPONSIVE_AFTER_FUNDING → check_status_later; eip3009: retry once, then haven_sweep_delegate; erc7710: no retry, check status after the window, re-quote only if unsettled
 ```
 
 ### `phase` reference
@@ -399,11 +404,13 @@ Hosted MCP and signer tools also return stable `code` values on recoverable x402
 
 | `code` | Meaning | Agent recovery |
 |--------|---------|----------------|
-| `PRICE_EXCEEDS_MAX` | The merchant-authoritative x402 price is above the caller's spending cap. No funding transfer was created. | Tell the user the live price exceeded the cap and retry only after they confirm a higher one. |
+| `PRICE_EXCEEDS_MAX` | The merchant-authoritative x402 price is above the caller's spending cap. No funding transfer was created. | Tell the user the live price exceeded the cap and retry only after they confirm a higher one. Payloads carry `next_action: stop_and_tell_user` and `retry_with_new_quote: true` — the latter means any retry needs a fresh quote, not that one should be attempted unattended. |
 | `AMBIGUOUS_MAX_AMOUNT` | Both `max_amount` (atomic units) and `max_amount_human` (whole tokens) were sent for one purchase. Nothing was contacted and nothing was spent. | Re-send with exactly one — `max_amount_human` for a cap the user stated in tokens, `max_amount` for an exact atomic figure. |
 | `MAX_AMOUNT_UNCONVERTIBLE` | `max_amount_human` could not be converted against this quote's asset — its decimals are unknown to Haven, or the cap has more decimal places than the asset supports. Nothing was spent. | Round the cap to the asset's decimals, or re-send it as an exact atomic `max_amount`. |
+| `MERCHANT_NOT_READY` | The merchant answered the quote probe with its own `503 { error: 'merchant_not_ready', reason_code, retry_after_s }` instead of a 402 — it cannot settle right now (e.g. its settlement wallet is out of gas). No payment was created. | Tell the user and retry later (`retry_after_s` in the message when given); do not treat it as a wrong endpoint. Payloads carry `next_action: stop_and_tell_user` and `retry_with_new_quote: true`. |
 | `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. |
+| `MERCHANT_REJECTED_AFTER_FUNDING` | The merchant rejected the paid retry. On eip3009 Haven's funding leg had succeeded; on erc7710 there is no funding leg (#2983). | eip3009: stop retrying the merchant and call `haven_sweep_delegate` so the user can recover stranded delegate USDC. erc7710: nothing to sweep — follow the message (re-quote later if the merchant declined to settle; otherwise check `haven_get_payment_status` after the payment window before re-quoting). |
+| `MERCHANT_UNRESPONSIVE_AFTER_FUNDING` | The merchant did not answer the paid retry before the timeout — NOT proof of rejection, the merchant may still settle late. On eip3009 Haven's funding leg had succeeded; on erc7710 there is no funding leg (#3000). | eip3009: check `haven_get_payment_status`, retry `haven_complete_mcp_tool` once, and only then call `haven_sweep_delegate` if no settlement appears. erc7710: nothing to sweep and `haven_complete_mcp_tool` has no erc7710 branch — do not retry it; check `haven_get_payment_status` after the payment window and re-quote only if it shows no settlement. |
 
 ## Payments outside the agent's budget
 

package/dist/index.cjs

@@ -125,7 +125,26 @@ var AgentPaymentNextAction = {
    * settled to the merchant. The wallet owner should initiate a sweep to
    * return those funds to the originating Safe.
    */
-  SweepStrandedFunds: "sweep_stranded_funds"
+  SweepStrandedFunds: "sweep_stranded_funds",
+  /**
+   * #2970: a `submitted` erc7710 x402 intent whose settlement window has
+   * passed with no on-chain settlement evidence Haven could verify. Distinct
+   * from {@link CheckStatusLater}, which this REPLACES once the window is
+   * past — but it is not futile: Haven's settlement sweep (120s tick) scans
+   * each candidate over its own window plus a 120s clock-skew allowance, so
+   * it can still attribute the settlement for a short while after this value
+   * first appears. Poll {@link CheckStatusLater}'s tool
+   * (`haven_get_payment_status`) once more, roughly two minutes later; if it
+   * still shows no evidence, tell the user the goods were delivered but
+   * Haven holds no verified settlement evidence for this payment. If the
+   * agent holds the merchant's real settlement transaction hash (from
+   * `PAYMENT-RESPONSE`'s `transaction` field, or a prior settle/complete
+   * result's `settlement_tx_hash`), report it with the hosted
+   * `haven_report_settlement_evidence` tool instead of waiting —
+   * `haven_report_x402_outcome` takes no hash and refuses a non-`confirmed`
+   * intent.
+   */
+  AwaitingSettlementEvidence: "awaiting_settlement_evidence"
 };
 var AgentPaymentNextActionAccountAlias = {
   /** Account-vocabulary twin of `fund_safe_or_raise_allowance`; same meaning. */
@@ -145,12 +164,14 @@ var AgentPaymentFailureCode = {
   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. */
+  /** The merchant rejected the paid retry. On eip3009 the funding leg had succeeded (sweep);
+   *  on erc7710 there is no funding leg — nothing to sweep, follow the message (#2983). */
   MerchantRejectedAfterFunding: "MERCHANT_REJECTED_AFTER_FUNDING",
   /** #1300 review: funding is on-chain but the merchant never ANSWERED the
    *  paid retry within the timeout. NOT proof of rejection — the merchant
-   *  holds a valid EIP-3009 authorization and may still settle late, so the
-   *  guidance is verify-then-sweep, never blind sweep. */
+   *  may still settle late, so the guidance is verify-then-act. On eip3009
+   *  the funding leg had succeeded (verify-then-sweep); on erc7710 there is
+   *  no funding leg — nothing to sweep, follow the message (#3000). */
   MerchantUnresponsiveAfterFunding: "MERCHANT_UNRESPONSIVE_AFTER_FUNDING",
   /**
    * #1307: the caller omitted merchant_url/tool_name (asking Haven to
@@ -176,7 +197,17 @@ var AgentPaymentFailureCode = {
    * asset can represent (truncating it would silently change the user's cap).
    * The fallback is the exact atomic `max_amount`.
    */
-  MaxAmountUnconvertible: "MAX_AMOUNT_UNCONVERTIBLE"
+  MaxAmountUnconvertible: "MAX_AMOUNT_UNCONVERTIBLE",
+  /**
+   * #2979: the merchant answered a `tools/call` probe with its own
+   * machine-readable "cannot settle right now" refusal (HTTP 503,
+   * `{ error: 'merchant_not_ready', reason_code, ... }`) instead of a 402
+   * challenge — e.g. its settlement wallet is out of gas. No 402 was ever
+   * issued and no payment was created; this is honest and (per
+   * `retry_after_s`, when present) usually transient, unlike a permanent
+   * endpoint miss.
+   */
+  MerchantNotReady: "MERCHANT_NOT_READY"
 };
 var AgentPaymentRail = {
   /** Standard Haven payment from the user's Safe through an approved delegate allowance. */
@@ -224,16 +255,18 @@ var AgentPaymentNextActionDescriptions = {
   [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 account needs to be funded or the agent budget raised before the payment can succeed.",
   [AgentPaymentNextAction.RetryWithExplicitContext]: "Retry the same tool call, this time passing merchant_url, tool_name, arguments, and mcp_transport explicitly \u2014 the server had no stored context to rehydrate for this payment id.",
-  [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 account."
+  [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 account.",
+  [AgentPaymentNextAction.AwaitingSettlementEvidence]: "The settlement window passed with no verified on-chain evidence yet. If you hold the merchant's real settlement transaction hash, report it with haven_report_settlement_evidence. Otherwise, Haven's settlement sweep may still attribute it within about two minutes \u2014 poll getPaymentStatus once more, then tell the user the goods were delivered but unverified if it still shows nothing."
 };
 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.",
-  [AgentPaymentFailureCode.MerchantUnresponsiveAfterFunding]: "The Haven funding leg succeeded, but the merchant did not answer the paid retry before the timeout. The merchant may still settle late \u2014 check haven_get_payment_status (and retry haven_complete_mcp_tool once) BEFORE sweeping; sweep only if no settlement appears.",
+  [AgentPaymentFailureCode.MerchantRejectedAfterFunding]: "The merchant rejected the paid retry. eip3009: the funding leg succeeded \u2014 stop retrying the merchant and reconcile stranded delegate funds with haven_sweep_delegate. erc7710: no funding leg, nothing to sweep \u2014 follow the message (re-quote later, or check haven_get_payment_status after the window first).",
+  [AgentPaymentFailureCode.MerchantUnresponsiveAfterFunding]: "The merchant did not answer the paid retry before the timeout. The merchant may still settle late. eip3009: the funding leg succeeded \u2014 check haven_get_payment_status, retry haven_complete_mcp_tool once, sweep only if no settlement appears. erc7710: no funding leg, nothing to sweep, and haven_complete_mcp_tool has no erc7710 branch \u2014 do not retry it; check haven_get_payment_status after the payment window and re-quote only if it shows no settlement.",
   [AgentPaymentFailureCode.MerchantCallContextUnavailable]: "merchant_url/tool_name were omitted and no stored merchant call context is available for this payment_id. Re-send merchant_url, tool_name, arguments, and mcp_transport explicitly.",
   [AgentPaymentFailureCode.AmbiguousMaxAmount]: "Both max_amount (atomic units) and max_amount_human (whole tokens) were supplied for one purchase. Nothing was contacted and nothing was spent. Re-send with exactly ONE: max_amount_human for a cap the user stated in tokens, max_amount for an exact atomic figure.",
-  [AgentPaymentFailureCode.MaxAmountUnconvertible]: "max_amount_human could not be converted to atomic units against this quote's asset \u2014 either its decimals are unknown to Haven or the cap has more decimal places than the asset supports. Nothing was spent. Round the cap, or re-send it as an exact atomic max_amount."
+  [AgentPaymentFailureCode.MaxAmountUnconvertible]: "max_amount_human could not be converted to atomic units against this quote's asset \u2014 either its decimals are unknown to Haven or the cap has more decimal places than the asset supports. Nothing was spent. Round the cap, or re-send it as an exact atomic max_amount.",
+  [AgentPaymentFailureCode.MerchantNotReady]: 'The merchant refused the probe with its own "cannot settle right now" signal instead of a 402 challenge. No payment was created. Often transient \u2014 retry later (see retry_after_s in the message, if given) rather than treating this as a broken or wrong endpoint.'
 };
 var AgentPaymentWarningCode = {
   /** No max_amount cap was supplied — the live quoted price was accepted as-is. */
@@ -264,7 +297,24 @@ var AgentPaymentWarningCode = {
    * on-chain policy re-checks at redemption either way; this only says the
    * guidance shown here may be optimistic.
    */
-  AllowanceReadOptimistic: "ALLOWANCE_READ_OPTIMISTIC"
+  AllowanceReadOptimistic: "ALLOWANCE_READ_OPTIMISTIC",
+  /**
+   * #2991: the quote tools' `expected_settlement_scheme` prediction of what
+   * `haven_prepare_catalog_purchase` / `haven_pay_mcp_tool` will actually
+   * select could not be computed — the agent's execution rail could not be
+   * read from Haven, so `expected_settlement_scheme` is `null` rather than a
+   * guess. `accepted_scheme` (the merchant's offer) is unaffected.
+   */
+  X402SchemeUnknown: "X402_SCHEME_UNKNOWN",
+  /**
+   * #2968: the merchant answered 200 and handed over goods, but Haven holds NO
+   * on-chain evidence that the payment moved. `settled: false` beside this code
+   * is not a failure — it is the absence of proof, and the two must travel
+   * together so an agent can tell "the user has the goods" apart from "the
+   * money moved". Carries the intent's `expires_at`: after that instant the
+   * settlement can no longer land at all.
+   */
+  SettlementUnconfirmed: "SETTLEMENT_UNCONFIRMED"
 };
 var AgentPaymentRailDescriptions = {
   [AgentPaymentRail.Direct]: "Standard Haven payment from the user-controlled account, redeeming the agent's on-chain budget delegation.",
@@ -328,8 +378,18 @@ var MerchantTimeoutError = class extends HavenApiError {
 };
 var X402UnexpectedStatusError = class extends HavenApiError {
   x402ErrorCode = "unexpected_non_402_status";
-  constructor(message, statusCode) {
-    super(message, statusCode);
+  /**
+   * #2979: `body` is the merchant's own JSON, when the non-402 response
+   * carried one — e.g. the demo merchant's `/mcp` readiness gate answers
+   * `503 { error: 'merchant_not_ready', reason_code, ... }`. Optional and
+   * best-effort: a non-JSON or unreadable body leaves this `undefined`, same
+   * as before this field existed. Consumers key on it (not on the message
+   * string) to distinguish an honest, machine-readable merchant refusal from
+   * a genuine "this is not the x402 endpoint" miss, which otherwise look
+   * identical — both are just "some non-402 status".
+   */
+  constructor(message, statusCode, body) {
+    super(message, statusCode, body);
     this.name = "X402UnexpectedStatusError";
   }
 };
@@ -368,6 +428,17 @@ var HavenSigningError = class extends HavenError {
     this.name = "HavenSigningError";
   }
 };
+var HavenZeroSettlementHashError = class extends HavenError {
+  constructor(paymentId) {
+    super(
+      "settlement_tx_hash is the zero hash (0x00\u202600), which is never a real settlement transaction \u2014 refused before any report was sent.",
+      "ZERO_SETTLEMENT_HASH",
+      400,
+      paymentId
+    );
+    this.name = "HavenZeroSettlementHashError";
+  }
+};
 var SignerRefusalCode = {
   /** `SUPPORTED_X402_EXPECTED_VERSIONS` in `@haven_ai/signer` does not include the received version. */
   UnsupportedExpectedContextVersion: "UNSUPPORTED_EXPECTED_CONTEXT_VERSION",
@@ -1116,6 +1187,15 @@ var HavenApiTransport = class {
 };
 
 // src/payment-mappers.ts
+function mapParties(raw) {
+  if (!raw) return void 0;
+  return {
+    treasuryAccount: raw.treasury_account,
+    delegate: raw.delegate,
+    delegateAccount: raw.delegate_account,
+    merchant: raw.merchant
+  };
+}
 function mapPaymentResult(raw, buildExplorerUrl2) {
   return {
     paymentId: raw.payment_id,
@@ -1155,6 +1235,7 @@ function mapPaymentStatusResult(raw) {
     resourceUrl: raw.resource_url,
     merchantAddress: raw.merchant_address,
     payerAddress: raw.payer_address ?? null,
+    parties: mapParties(raw.parties),
     txHash: raw.tx_hash,
     expiresAt: raw.expires_at,
     chainId: raw.chain_id,
@@ -1188,10 +1269,13 @@ function mapPaymentReceipt(raw) {
     rail: raw.rail,
     proofStatus: raw.proof_status,
     txHash: raw.tx_hash,
+    fundingTxHash: raw.funding_tx_hash ?? null,
+    settlementTxHash: raw.settlement_tx_hash ?? null,
     chainId: raw.chain_id,
     resourceUrl: raw.resource_url,
     merchantAddress: raw.merchant_address,
     payerAddress: raw.payer_address,
+    parties: mapParties(raw.parties),
     settlementAddress: raw.settlement_address,
     tokenSymbol: raw.token_symbol,
     tokenAddress: raw.token_address,
@@ -2915,15 +2999,57 @@ var MerchantCompletion = class {
     for (let attempt = 0; ; attempt += 1) {
       try {
         await this.post("/machine-payments/evidence", body);
-        return;
+        return { outcome: "confirmed" };
       } catch (err) {
-        const retryable = err instanceof HavenApiError && err.statusCode === EVIDENCE_RETRYABLE_STATUS;
-        if (!retryable || attempt >= EVIDENCE_RETRY_DELAYS_MS.length) return;
+        const statusCode = err instanceof HavenApiError ? err.statusCode : void 0;
+        const retryable = statusCode === EVIDENCE_RETRYABLE_STATUS;
+        if (!retryable) {
+          return { outcome: "refused", statusCode: statusCode ?? 0 };
+        }
+        if (attempt >= EVIDENCE_RETRY_DELAYS_MS.length) {
+          return { outcome: "retryable", statusCode };
+        }
         await this.sleep(EVIDENCE_RETRY_DELAYS_MS[attempt]);
       }
     }
   }
+  /**
+   * #2972: report the merchant's REAL settlement transaction hash for an
+   * erc7710 x402 payment out of band — the remedy #2970's guidance could not
+   * name, because no hosted tool accepted a hash. An agent reaches this after
+   * `haven_settle_mcp_tool` / `haven_complete_mcp_tool` answered
+   * `DELIVERED_UNSETTLED` or `SETTLEMENT_PENDING`, or after
+   * `haven_get_payment_status` reports `awaiting_settlement_evidence` — in
+   * every one of those cases the agent may be holding the merchant's own
+   * `PAYMENT-RESPONSE.transaction` while Haven has nothing.
+   *
+   * Reuses `reportEvidence` — same backend seam
+   * (`POST /machine-payments/evidence` → `observeErc7710Settlement`,
+   * fail-closed — see `settlement-observed.ts`), same three-outcome contract.
+   * `resourceUrl` and `merchantStatus` are omitted: this call has no fresh
+   * merchant HTTP exchange to read either from, and both are optional at the
+   * backend (see the parameter doc on `reportEvidence`).
+   *
+   * The zero hash is refused HERE, client-side, before any network call —
+   * never posted. `isZeroSettlementTxHash` is the same recognizer the #2970
+   * gate uses, so a caller cannot "fix" a missing hash by reporting the demo
+   * merchant's own marker and getting a different verdict than the settle
+   * path already gave it.
+   */
+  async reportSettlementEvidence(paymentId, settlementTxHash) {
+    if (isZeroSettlementTxHash(settlementTxHash)) {
+      throw new HavenZeroSettlementHashError(paymentId);
+    }
+    return this.reportEvidence({
+      paymentId,
+      rail: "x402",
+      txHash: settlementTxHash
+    });
+  }
 };
+function isZeroSettlementTxHash(hash) {
+  return typeof hash === "string" && /^0x0+$/i.test(hash);
+}
 function parseMerchantSettlement(header) {
   if (!header) return {};
   const parsed = parseProtocolReceiptHeader(header);
@@ -3425,7 +3551,7 @@ var HavenClient = class {
     const query = params.size > 0 ? `?${params.toString()}` : "";
     const raw = await this.get(`/catalog${query}`);
     let entries = raw.entries.map(mapCatalogEntry);
-    if (options.verified === "verified") entries = entries.filter((e) => e.source === "ingestion");
+    if (options.verified === "verified") entries = entries.filter((e) => e.verifiedPayable === true);
     if (options.verified === "operator") entries = entries.filter((e) => e.source === "operator");
     return entries;
   }
@@ -3562,9 +3688,16 @@ var HavenClient = class {
     const request = snapshotX402Request(url, initialInit);
     const response = await this.merchantTransport.fetch(url, initialInit);
     if (response.status !== 402) {
+      let body;
+      try {
+        body = await response.clone().json();
+      } catch {
+        body = void 0;
+      }
       throw new X402UnexpectedStatusError(
         `Expected an x402 quote response with HTTP 402, got HTTP ${response.status}.`,
-        response.status || 400
+        response.status || 400,
+        body
       );
     }
     if (response.headers.get("MACHINE-PAYMENT-CHALLENGE")) {
@@ -3853,6 +3986,7 @@ var HavenClient = class {
     } catch {
       body = text;
     }
+    let evidenceOutcome;
     if (!surfaced.ok) {
       if (!input.noFundingLeg && fundingTxHash) {
         await this.merchantCompletion.recordRetryRejected({
@@ -3872,9 +4006,10 @@ var HavenClient = class {
         });
       }
     } else {
-      const evidenceTxHash = input.noFundingLeg ? settlement.settlementTxHash ?? void 0 : fundingTxHash ?? void 0;
+      const rawEvidenceTxHash = input.noFundingLeg ? settlement.settlementTxHash ?? void 0 : fundingTxHash ?? void 0;
+      const evidenceTxHash = rawEvidenceTxHash && !isZeroSettlementTxHash(rawEvidenceTxHash) ? rawEvidenceTxHash : void 0;
       if (evidenceTxHash) {
-        await this.merchantCompletion.reportEvidence({
+        evidenceOutcome = await this.merchantCompletion.reportEvidence({
           paymentId: evidenceContext.paymentId,
           rail: "x402",
           txHash: evidenceTxHash,
@@ -3892,7 +4027,8 @@ var HavenClient = class {
       status: surfaced.status,
       ok: surfaced.ok,
       body,
-      settlementTxHash: settlement.settlementTxHash ?? void 0
+      settlementTxHash: settlement.settlementTxHash ?? void 0,
+      evidenceOutcome
     };
   }
   /**
@@ -3907,6 +4043,19 @@ var HavenClient = class {
   async reportX402MerchantOutcome(input) {
     return await this.merchantCompletion.reportMerchantOutcome(input);
   }
+  /**
+   * #2972: report the merchant's real settlement transaction hash for an
+   * erc7710 x402 payment — the remedy for `DELIVERED_UNSETTLED` /
+   * `SETTLEMENT_PENDING` / `awaiting_settlement_evidence` when the agent
+   * holds the hash (`PAYMENT-RESPONSE.transaction`, or a prior settle/
+   * complete result's `settlement_tx_hash`) and Haven does not. See
+   * `MerchantCompletion.reportSettlementEvidence` for the fail-closed
+   * verification this posts into (`observeErc7710Settlement`) and the
+   * client-side zero-hash refusal.
+   */
+  async reportSettlementEvidence(paymentId, settlementTxHash) {
+    return await this.merchantCompletion.reportSettlementEvidence(paymentId, settlementTxHash);
+  }
   /**
    * 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
@@ -4081,8 +4230,8 @@ var toolDescriptions = {
   // MACHINE-PAYMENT-CHALLENGE was never produced by anything besides the now
   // deleted `/demo/mpp/*` route. Use the x402 fragments above instead.
   getPaymentStatus: {
-    summary: "Fetch structured Haven payment status, including phase and nextAction taxonomy for agent recovery.",
-    behavior: "Accepts a payment intent id and returns the full state taxonomy (phase, nextAction, rail, amount, merchant, resource url, idempotency key, message).",
+    summary: "Fetch structured Haven payment status for agent recovery.",
+    behavior: "State: phase, nextAction, rail, amount, merchant, resource, idempotency, message; parties: treasury/delegate/delegateAccount/merchant. awaiting_settlement_evidence: poll once, else unverified.",
     nextActionGuidance: ""
   },
   getResumeState: {
@@ -4122,7 +4271,7 @@ var toolDescriptions = {
   },
   discoverTools: {
     summary: "Step 1 of a purchase: discover payable services from Haven's curated merchant catalog \u2014 names, prices, and which pay tool to use next.",
-    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. Use verified=verified to show only self-submitted directory entries that passed domain-ownership proof and a live quote probe \u2014 never treat those badges as proof of merchant honesty, quality, or reliability. 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.",
+    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. Use verified=verified for entries Haven watched pass a live quote probe (operator-curated or self-submitted) \u2014 domain_verified is the only ownership claim; never treat these badges as proof of merchant honesty, quality, or reliability. 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: "Use each entry's suggested_tool field first \u2014 it names the exact next call. Read-only lookup against Haven's curated catalog; entries are periodically re-verified against the live merchant and degraded entries are flagged. Use category for a case-insensitive category filter (for example, VPN or vpn), or search for a product name, category, or description term. Returns name, description, price, rail, resource URL, tool_name, tool_arguments, suggested_tool, and the provenance badges source/domain_verified/verified_payable. 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, tool_name, and tool_arguments for MCP merchants. Confirm the price from the live pay-tool result (not the catalog), and pass the user's cap as max_amount_human in whole tokens ("no more than 1 USDC" \u2192 max_amount_human: "1") \u2014 never convert it to atomic units by hand.`
   },
@@ -4143,6 +4292,11 @@ var toolDescriptions = {
     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 \u2014 use haven_pay_x402 instead. Do NOT use for read-only allowance, budget, or what-can-I-spend questions \u2014 use haven_get_allowances.",
     behavior: "Sends the requested amount by redeeming the agent's on-chain budget delegation, account to recipient with no funding leg. Budget, recipient and expiry are enforced on-chain while the transfer is prepared, so a request outside them is declined before any money moves and before the agent is asked to sign \u2014 it is never queued for a human to approve later. The agent's signing key signs the account's typed data; Haven never receives the key.",
     nextActionGuidance: "On a decline, report the reason to the user and ask them to grant or raise the budget in Haven \u2014 there is nothing to poll and no approval will arrive. After a successful send, poll haven_get_payment_status until nextAction=none."
+  },
+  reportSettlementEvidence: {
+    summary: "Report an erc7710 payment's real settlement transaction hash so Haven can verify it on-chain and confirm the payment.",
+    behavior: "Pass payment_id and settlement_tx_hash (0x + 64 hex chars) \u2014 from PAYMENT-RESPONSE or a prior settlement_tx_hash. Haven verifies on-chain before confirming; a zero, mismatched, or reverted hash is refused. Your own payments only.",
+    nextActionGuidance: "code DELIVERED_UNSETTLED: did not verify, do not retry \u2014 poll haven_get_payment_status. code SETTLEMENT_PENDING (retryable:true): not mined or RPC unreachable \u2014 report the same hash again shortly."
   }
 };
 
@@ -4745,15 +4899,30 @@ present and surface \`message\` or \`error\` verbatim. Common cases:
   Round the cap, or send an exact atomic \`max_amount\`.
 - \`PAYMENT_WINDOW_EXPIRED\`: re-run the quote/prepare tool with the same
   \`idempotency_key\`, then sign the fresh payload.
+- \`MERCHANT_NOT_READY\`: the merchant refused the quote with its own
+  "cannot settle right now" signal (a 503 \`merchant_not_ready\` with a
+  \`reason_code\`) instead of a 402. No payment was created. Tell the user;
+  retry later (the message carries \`retry_after_s\` when the merchant gave
+  one) \u2014 this is not a wrong or broken endpoint.
 - \`MERCHANT_REJECTED_AFTER_FUNDING\`: the merchant refused the paid retry.
-  Stop-and-sweep \u2014 stop retrying the merchant and use
-  \`mcp__haven__haven_sweep_delegate\` to recover stranded delegate funds.
-- \`MERCHANT_UNRESPONSIVE_AFTER_FUNDING\`: funding confirmed on-chain, but the
-  merchant never answered the paid retry. This is NOT proof of rejection \u2014 the
-  merchant may still settle late. Verify-then-sweep, never a blind sweep:
-  check \`mcp__haven__haven_get_payment_status\`, retry
+  On eip3009 (\`rail\` not \`erc7710\`): Stop-and-sweep \u2014 stop retrying the
+  merchant and use \`mcp__haven__haven_sweep_delegate\` to recover stranded
+  delegate funds. On erc7710 there is no funding leg and nothing to sweep:
+  follow the message \u2014 it says whether the merchant declined to settle
+  (re-quote later) or whether to check \`haven_get_payment_status\` after
+  the payment window first.
+- \`MERCHANT_UNRESPONSIVE_AFTER_FUNDING\`: the merchant never answered the paid
+  retry. This is NOT proof of rejection \u2014 the merchant may still settle late.
+  On eip3009 (\`rail\` not \`erc7710\`), funding confirmed on-chain: Verify-then-sweep,
+  never a blind sweep \u2014 check \`mcp__haven__haven_get_payment_status\`, retry
   \`mcp__haven__haven_complete_mcp_tool\` ONCE, and only sweep with
-  \`mcp__haven__haven_sweep_delegate\` if no settlement appears.
+  \`mcp__haven__haven_sweep_delegate\` if no settlement appears. On erc7710
+  there is no funding leg and nothing to sweep, and
+  \`mcp__haven__haven_complete_mcp_tool\` has no erc7710 branch (it refuses a
+  submitted intent) \u2014 do not retry it: the merchant may still redeem the
+  settlement authorization within the payment window, so check
+  \`mcp__haven__haven_get_payment_status\` after that window and re-quote only
+  if it shows no settlement.
 - Budget exceeded: tell the user how much remains (from
   \`mcp__haven__haven_get_allowances\`) and that they can raise the budget in
   Haven.
@@ -4904,6 +5073,7 @@ exports.HavenPaymentStateError = HavenPaymentStateError;
 exports.HavenSigningError = HavenSigningError;
 exports.HavenTimeoutError = HavenTimeoutError;
 exports.HavenUnsupportedSignerVersionError = HavenUnsupportedSignerVersionError;
+exports.HavenZeroSettlementHashError = HavenZeroSettlementHashError;
 exports.MERCHANT_DISCOVERY_PATHS = MERCHANT_DISCOVERY_PATHS;
 exports.MerchantTimeoutError = MerchantTimeoutError;
 exports.RECEIPT_VERSION = RECEIPT_VERSION;
@@ -4947,6 +5117,7 @@ exports.isErc7710Option = isErc7710Option;
 exports.isFundAccountOrRaiseAllowance = isFundAccountOrRaiseAllowance;
 exports.isSupportedNodeVersion = isSupportedNodeVersion;
 exports.isSweepableChain = isSweepableChain;
+exports.isZeroSettlementTxHash = isZeroSettlementTxHash;
 exports.normalizePaymentRequired = normalizePaymentRequired;
 exports.parsePaymentRequired = parsePaymentRequired;
 exports.parsePaymentRequiredResponse = parsePaymentRequiredResponse;