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

package/dist/index.cjs

@@ -110,9 +110,14 @@ var AgentPaymentNextAction = {
    */
   PaymentWindowExpired: "payment_window_expired",
   /**
-   * Stop and tell the user that the originating Safe needs to be funded or
+   * Stop and tell the user that the originating account needs to be funded or
    * the agent's per-token allowance needs to be raised before the payment
    * can succeed. A user approval will not fix this state on its own.
+   *
+   * #2908: the wire twin `fund_account_or_raise_allowance`
+   * ({@link AgentPaymentNextActionAccountAlias}) means the same thing; the
+   * server keeps emitting THIS value until #2914. Compare via
+   * {@link canonicalAgentPaymentNextAction}.
    */
   FundSafeOrRaiseAllowance: "fund_safe_or_raise_allowance",
   /**
@@ -120,19 +125,53 @@ 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. */
+  FundAccountOrRaiseAllowance: "fund_account_or_raise_allowance"
+};
+function canonicalAgentPaymentNextAction(value) {
+  if (value === AgentPaymentNextActionAccountAlias.FundAccountOrRaiseAllowance) {
+    return AgentPaymentNextAction.FundSafeOrRaiseAllowance;
+  }
+  return value;
+}
+function isFundAccountOrRaiseAllowance(value) {
+  return value === AgentPaymentNextAction.FundSafeOrRaiseAllowance || value === AgentPaymentNextActionAccountAlias.FundAccountOrRaiseAllowance;
+}
 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. */
+  /** 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
@@ -158,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. */
@@ -206,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. */
@@ -246,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.",
@@ -310,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";
   }
 };
@@ -350,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",
@@ -1098,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,
@@ -1128,12 +1226,16 @@ function mapPaymentStatusResult(raw) {
     rail: raw.rail,
     status: raw.status,
     phase: raw.phase,
-    nextAction: raw.next_action,
+    // #2908: the account-vocabulary alias collapses onto the canonical value
+    // so every `=== AgentPaymentNextAction.X` downstream keeps working when
+    // the server flips its emit at #2914.
+    nextAction: canonicalAgentPaymentNextAction(raw.next_action),
     amount: raw.amount,
     token: raw.token,
     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,
@@ -1167,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,
@@ -1260,7 +1365,7 @@ function messageForState(label, status, paymentId, nextAction) {
 function paymentStateFromRaw(label, raw) {
   if (!raw.payment_id || !raw.status) return null;
   const phase = raw.phase ?? phaseForStatus(raw.status);
-  const nextAction = raw.next_action ?? nextActionForStatus(raw.status);
+  const nextAction = canonicalAgentPaymentNextAction(raw.next_action) ?? nextActionForStatus(raw.status);
   if (!phase || !nextAction) return null;
   const amount = raw.amount ?? raw.requested ?? "";
   const token = raw.token ?? "";
@@ -1583,6 +1688,20 @@ function verifyPaymentReceipt(receipt, recover = defaultRecover) {
   return { verified: true, recoveredSigner: recovered };
 }
 
+// src/account-naming.ts
+function readAccountAddress(raw) {
+  return raw.account_address ?? raw.safe_address ?? void 0;
+}
+function readAccountId(raw) {
+  return raw.account_id ?? raw.safe_id ?? void 0;
+}
+function accountAddressTwins(address) {
+  return { accountAddress: address, safeAddress: address };
+}
+function readX402ReceiptPayer(raw) {
+  return raw.payer ?? raw.account_address ?? raw.sign_data?.components?.payer_account ?? raw.safe_address ?? raw.sign_data?.components?.safe;
+}
+
 // src/account-reads.ts
 function safeBigInt(value) {
   try {
@@ -1641,7 +1760,10 @@ var AccountReads = class {
     const raw = await this.transport.get("/machine-payments/allowances");
     return {
       agentId: raw.agent_id,
-      safeAddress: raw.safe_address,
+      // #2908: one mapper, both names, same value — `readAccountAddress`
+      // prefers the server's `account_address` twin and falls back to
+      // `safe_address` for a pre-#2907 server.
+      ...accountAddressTwins(readAccountAddress(raw)),
       delegateAddress: raw.delegate_address,
       chainId: raw.chain_id,
       allowances: raw.allowances.map((allowance) => ({
@@ -1730,7 +1852,10 @@ var AccountReads = class {
       id: raw.id,
       name: raw.name,
       status: raw.status,
-      safeAddress: raw.safe_address,
+      // #2908: both camelCase names off whichever snake_case name the server
+      // sent (new first). The hosted MCP's `haven_get_agent` spreads this
+      // object, so this is also the hosted output's dual-emit point.
+      ...accountAddressTwins(readAccountAddress(raw)),
       delegateAddress: raw.delegate_address,
       chainId: raw.chain_id,
       executionRail: raw.execution_rail === "delegation" ? "delegation" : "legacy"
@@ -1780,7 +1905,7 @@ var DelegateSweepApi = class {
       const contract = createErc20Contract(sweepUsdcAddress(agent.chainId), ["function balanceOf(address) view returns (uint256)", "function transfer(address to, uint256 amount) returns (bool)"], wallet);
       const balance2 = await contract.balanceOf(agent.delegateAddress);
       if (balance2 > 0n) {
-        const tx = await contract.transfer(agent.safeAddress, balance2);
+        const tx = await contract.transfer(agent.accountAddress, balance2);
         const { txHash, confirmation } = await waitForSweepTx(tx);
         transfers.push({ asset: "USDC", amount: format(balance2, 6), amountAtomic: balance2.toString(), txHash, explorerUrl: this.options.buildExplorerUrl(agent.chainId, txHash), confirmation });
       }
@@ -1790,12 +1915,12 @@ var DelegateSweepApi = class {
       const fee = await provider.getFeeData();
       const send = balance - (fee.maxFeePerGas ?? fee.gasPrice ?? 1000000n) * 21000n * 2n;
       if (send > 0n) {
-        const tx = await wallet.sendTransaction({ to: agent.safeAddress, value: send });
+        const tx = await wallet.sendTransaction({ to: agent.accountAddress, value: send });
         const { txHash, confirmation } = await waitForSweepTx(tx);
         transfers.push({ asset: "ETH", amount: format(send, 18), amountAtomic: send.toString(), txHash, explorerUrl: this.options.buildExplorerUrl(agent.chainId, txHash), confirmation });
       }
     }
-    return { fromAddress: agent.delegateAddress, toAddress: agent.safeAddress, chainId: agent.chainId, transfers, unconfirmed: transfers.some((t) => t.confirmation === "unconfirmed") };
+    return { fromAddress: agent.delegateAddress, toAddress: agent.accountAddress, chainId: agent.chainId, transfers, unconfirmed: transfers.some((t) => t.confirmation === "unconfirmed") };
   }
   prepareSweep() {
     return this.options.transport.post("/machine-payments/sweep/prepare", {});
@@ -2189,7 +2314,7 @@ var X402FundingLeg = class {
     const to = execResult?.to ?? raw.to ?? this.delegateAddress ?? "";
     const explorerUrl = execResult?.explorer_url ?? raw.explorer_url ?? explorerUrlOrEmpty(chainId, txHash);
     const merchantTo = execResult?.merchant_to ?? raw.merchant_to ?? option.payTo;
-    const payer = raw.payer ?? raw.safe_address ?? raw.sign_data?.components.safe;
+    const payer = readX402ReceiptPayer(raw);
     return buildX402Receipt({
       paymentId: raw.payment_id,
       txHash,
@@ -2874,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);
@@ -3384,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;
   }
@@ -3521,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")) {
@@ -3812,6 +3986,7 @@ var HavenClient = class {
     } catch {
       body = text;
     }
+    let evidenceOutcome;
     if (!surfaced.ok) {
       if (!input.noFundingLeg && fundingTxHash) {
         await this.merchantCompletion.recordRetryRejected({
@@ -3831,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,
@@ -3851,7 +4027,8 @@ var HavenClient = class {
       status: surfaced.status,
       ok: surfaced.ok,
       body,
-      settlementTxHash: settlement.settlementTxHash ?? void 0
+      settlementTxHash: settlement.settlementTxHash ?? void 0,
+      evidenceOutcome
     };
   }
   /**
@@ -3866,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
@@ -4022,13 +4212,13 @@ var toolDescriptions = {
     summary: "Pay an inspected x402 quote. The delegate key signs locally; Haven only validates and relays signed, on-chain-constrained payment transactions.",
     selectionGuidance: "Do not use this for read-only allowance, budget, spend-limit, remaining-amount, reset-period, or what-can-I-spend questions; use the allowance lookup tool instead.",
     behavior: "Signs the payment locally 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.",
-    nextActionGuidance: "Preserve the returned resume_state \u2014 it 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."
+    nextActionGuidance: "Preserve the returned resume_state \u2014 it 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 (or fund_account_or_raise_allowance), the payment cannot be retried until the account is funded or the agent budget raised \u2014 stop and tell the user the shortfall reported on the response."
   },
   payX402OneShot: {
     summary: "Fetch an x402 paid HTTP resource in a single call. Handles the full probe -> pay -> retry round trip and returns the merchant response.",
     selectionGuidance: "Prefer this over the quote+pay split when the agent just wants the paid resource and does not need to inspect the price first. If you already have a quote from haven_quote_x402, use haven_pay_x402_quote instead. Do not use for read-only allowance, budget, spend-limit, remaining-amount, reset-period, or what-can-I-spend questions; use the allowance lookup tool instead.",
     behavior: "Calls the URL, parses any HTTP 402 x402 challenge, signs the payment locally, then retries the original request with the signed payment header (sent under PAYMENT-SIGNATURE, plus the legacy X-PAYMENT on the EIP-3009 path only) and returns the merchant response. Settlement is either direct account-to-merchant with no funding leg, or a bridge that first redeems the agent's budget delegation to fund the delegate wallet for an EIP-3009 authorization. A payment outside the on-chain budget is declined before any money moves; nothing is queued for a human to approve later. If the resource returns a non-402 status, returns it unchanged without contacting Haven.",
-    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."
+    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 (or fund_account_or_raise_allowance), the payment cannot be retried until the account is funded or the agent budget raised \u2014 stop and tell the user the shortfall reported on the response."
   },
   resumeX402: {
     summary: "Resume an x402 payment whose Haven-side authorization already succeeded but whose merchant retry did not complete.",
@@ -4040,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: {
@@ -4052,7 +4242,7 @@ var toolDescriptions = {
   getAgent: {
     summary: "Return the authenticated agent identity AND its live spend authority in one call: Haven wallet, delegate, chain, raw status, spend_authority_readiness, and per-token remaining allowance (atomic + human-readable). The recommended first call in a new session to confirm who you are and whether Haven will let you spend right now.",
     selectionGuidance: "Use this as the one-shot orientation/bootstrap at the start of a session, or whenever you need to confirm identity together with whether the agent can spend right now. For a detailed per-token breakdown (configured vs spent vs reset window) use haven_get_allowances.",
-    behavior: `Reads identity plus the live spend-authority snapshot in one shot \u2014 the agent's active on-chain budget delegation. spend_authority_readiness (readiness is a deprecated alias, same value) is "ready" when at least one token has remaining spend authority, "needs_approval" when the agent is active but has none, and "revoked" when the credential is not active. It covers hosted identity + on-chain spend authority ONLY \u2014 the hosted server cannot see the LOCAL signer, so "ready" does not mean the signer can start; verify the signer with a signer tool call or connect --doctor. An over-budget payment is declined before any money moves: there is no approval queue, so ask the owner to grant or raise the budget in Haven rather than waiting for an approval. allowances[] carries remainingAtomic and remainingDisplay per token. Identity fields (id, name, status, safeAddress, delegateAddress, chainId) are unchanged from before.`,
+    behavior: `Reads identity plus the live spend-authority snapshot in one shot \u2014 the agent's active on-chain budget delegation. spend_authority_readiness (readiness is a deprecated alias, same value) is "ready" when at least one token has remaining spend authority, "needs_approval" when the agent is active but has none, and "revoked" when the credential is not active. It covers hosted identity + on-chain spend authority ONLY \u2014 the hosted server cannot see the LOCAL signer, so "ready" does not mean the signer can start; verify the signer with a signer tool call or connect --doctor. An over-budget payment is declined before any money moves: there is no approval queue, so ask the owner to grant or raise the budget in Haven rather than waiting for an approval. allowances[] carries remainingAtomic and remainingDisplay per token. Identity fields: id, name, status, accountAddress (safeAddress: deprecated alias, same value), delegateAddress, chainId.`,
     nextActionGuidance: ""
   },
   getAllowances: {
@@ -4081,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.`
   },
@@ -4092,9 +4282,9 @@ var toolDescriptions = {
     nextActionGuidance: "Give the verify_token and the well-known instructions (from getCatalogSubmissionStatus) to the merchant so they can publish the proof line, then poll the submission status until it reaches verified_payable or failed."
   },
   sweep_delegate: {
-    summary: "Sweep stranded USDC and/or ETH from the delegate wallet back to the originating Safe.",
+    summary: "Sweep stranded USDC and/or ETH from the delegate wallet back to the originating account.",
     selectionGuidance: "Use this when the user instructs you to recover stranded funds on the delegate wallet, or when a payment status returns nextAction=sweep_stranded_funds. Do NOT use for normal payments \u2014 use haven_pay_x402. Do NOT use to read balances only \u2014 use haven_get_allowances.",
-    behavior: `Reads the delegate EOA's on-chain USDC and ETH balances. For each non-zero balance, signs and submits a transfer from the delegate EOA to the originating Safe (hardcoded destination). The delegate key signs locally \u2014 Haven never sees it and the backend never constructs signed transactions (CASP/MiCA Red Line #2). Returns tx hashes and recovered amounts. Returns an empty transfers list when nothing is stranded. Each transfer carries confirmation: "confirmed" (a receipt was seen \u2014 the funds are in the Safe) or "unconfirmed" (broadcast but not confirmed within 90 seconds \u2014 still in the mempool, may still land). The top-level unconfirmed flag is true when any transfer is unconfirmed.`,
+    behavior: `Reads the delegate EOA's on-chain USDC and ETH balances. For each non-zero balance, signs and submits a transfer from the delegate EOA to the originating account (hardcoded destination). The delegate key signs locally \u2014 Haven never sees it and the backend never constructs signed transactions (CASP/MiCA Red Line #2). Returns tx hashes and recovered amounts. Returns an empty transfers list when nothing is stranded. Each transfer carries confirmation: "confirmed" (a receipt was seen \u2014 the funds are in the account) or "unconfirmed" (broadcast but not confirmed within 90 seconds \u2014 still in the mempool, may still land). The top-level unconfirmed flag is true when any transfer is unconfirmed.`,
     nextActionGuidance: 'If transfers is non-empty, confirm the amounts with the user. Report a transfer as recovered ONLY when its confirmation is "confirmed". For an "unconfirmed" transfer, tell the user it was submitted but not yet confirmed, give them its txHash and explorerUrl to check, and do not re-run the sweep immediately \u2014 a re-run after it lands will simply find nothing stranded.'
   },
   send: {
@@ -4102,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."
   }
 };
 
@@ -4704,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.
@@ -4837,6 +5047,7 @@ exports.AgentPaymentFailureCode = AgentPaymentFailureCode;
 exports.AgentPaymentFailureCodeDescriptions = AgentPaymentFailureCodeDescriptions;
 exports.AgentPaymentFailureCodeSchema = AgentPaymentFailureCodeSchema;
 exports.AgentPaymentNextAction = AgentPaymentNextAction;
+exports.AgentPaymentNextActionAccountAlias = AgentPaymentNextActionAccountAlias;
 exports.AgentPaymentNextActionDescriptions = AgentPaymentNextActionDescriptions;
 exports.AgentPaymentNextActionSchema = AgentPaymentNextActionSchema;
 exports.AgentPaymentPhase = AgentPaymentPhase;
@@ -4862,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;
@@ -4883,10 +5095,12 @@ 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.accountAddressTwins = accountAddressTwins;
 exports.addressFromKey = addressFromKey;
 exports.buildSweepAuthorizationMessage = buildSweepAuthorizationMessage;
 exports.buildSweepTypedData = buildSweepTypedData;
 exports.buildX402ExpectedMessage = buildX402ExpectedMessage;
+exports.canonicalAgentPaymentNextAction = canonicalAgentPaymentNextAction;
 exports.compareNodeVersions = compareNodeVersions;
 exports.composeDescription = composeDescription;
 exports.connectorRerunCommand = connectorRerunCommand;
@@ -4900,11 +5114,16 @@ exports.encodePaymentProof = encodePaymentProof;
 exports.havenTools = havenTools;
 exports.isConnectorChannel = isConnectorChannel;
 exports.isErc7710Option = isErc7710Option;
+exports.isFundAccountOrRaiseAllowance = isFundAccountOrRaiseAllowance;
 exports.isSupportedNodeVersion = isSupportedNodeVersion;
 exports.isSweepableChain = isSweepableChain;
+exports.isZeroSettlementTxHash = isZeroSettlementTxHash;
 exports.normalizePaymentRequired = normalizePaymentRequired;
 exports.parsePaymentRequired = parsePaymentRequired;
 exports.parsePaymentRequiredResponse = parsePaymentRequiredResponse;
+exports.readAccountAddress = readAccountAddress;
+exports.readAccountId = readAccountId;
+exports.readX402ReceiptPayer = readX402ReceiptPayer;
 exports.resolveConnectorChannel = resolveConnectorChannel;
 exports.resolveTokenFromAddress = resolveTokenFromAddress;
 exports.sameUrl = sameUrl;