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

package/dist/index.js

@@ -16,33 +16,40 @@ var AgentPaymentPhase = {
   PaymentSubmitted: "payment_submitted",
   /** The direct payment is confirmed; the agent does not need to do more for this payment id. */
   PaymentConfirmed: "payment_confirmed",
-  /** The payment needs wallet owner approval in Haven before it can continue. */
+  /**
+   * #2115: RETIRED wire value — no live rail produces it. It described the
+   * Safe rail's approval queue, which no longer exists. Kept so a stored value
+   * still typechecks; see `AgentPaymentPhaseDescriptions` below for the
+   * agent-visible wording, which this comment used to contradict.
+   */
   UserApprovalRequired: "user_approval_required",
-  /** The wallet owner approved the request and still needs to complete the funding payment. */
+  /** #2115: RETIRED wire value — no live rail produces it. Stop and tell the user. */
   UserExecutionRequired: "user_execution_required",
-  /** The funding payment was proposed and is waiting for the remaining account approvals. */
+  /** #2115: RETIRED wire value — no live rail produces it. Stop and tell the user. */
   WaitingForAdditionalApprovals: "waiting_for_additional_approvals",
   /** The Haven funding leg was sent; the agent can continue the merchant/protocol leg. */
   FundingSent: "funding_sent",
-  /** The wallet owner rejected the request; the agent should stop and tell the user. */
+  /** The payment was rejected and cannot proceed; the agent should stop and tell the user. */
   Rejected: "rejected",
-  /** The payment or approval request expired before completion. */
+  /** The payment expired before completion. */
   Expired: "expired",
   /** Haven could not complete the payment; the agent should stop and surface the failure. */
   Failed: "failed",
   /**
    * Pre-flight check determined the delegate's existing balance plus the
-   * remaining on-chain allowance cannot cover the requested amount, so no
-   * payment intent was created. Distinct from `UserApprovalRequired`: there
-   * is no approval that would fix this — the originating Safe needs more
-   * funds or the agent's per-token allowance needs to be raised first.
+   * remaining on-chain budget cannot cover the requested amount, so no
+   * payment intent was created. The account must be funded or the agent's
+   * budget raised before retrying — #2115: the old wording contrasted this
+   * with `UserApprovalRequired` as if that were a live alternative, and named
+   * the retired rail's Safe and per-token allowance as the fix.
    */
   InsufficientFunds: "insufficient_funds",
   /**
-   * Haven's funding leg (Safe → delegate) confirmed on-chain, but the
-   * merchant rejected the x402 retry. The delegate wallet may hold stranded
-   * USDC that was never settled to the merchant. The agent should stop, tell
-   * the user, and wait for the sweep flow to reclaim the funds.
+   * Haven's funding leg (account → delegate, the #946 EIP-3009 bridge)
+   * confirmed on-chain, but the merchant rejected the x402 retry. The delegate
+   * wallet may hold stranded USDC that was never settled to the merchant. The
+   * agent should stop, tell the user, and wait for the sweep flow to reclaim
+   * the funds.
    */
   FundedButUnsettled: "funded_but_unsettled"
 };
@@ -53,9 +60,12 @@ var AgentPaymentNextAction = {
   CheckStatusLater: "check_status_later",
   /** No further agent action is required for this payment id. */
   None: "none",
-  /** Wait for the wallet owner to approve or reject the request in Haven. */
+  /**
+   * #2115: RETIRED wire value — no live rail produces it and nothing maps to
+   * it. Stop and tell the user rather than polling; no approval will arrive.
+   */
   WaitForUserApproval: "wait_for_user_approval",
-  /** Wait for the wallet owner to finish sending the approved funding payment. */
+  /** #2115: RETIRED wire value — no live rail produces it. Stop and tell the user rather than polling. */
   WaitForUserToCompletePayment: "wait_for_user_to_complete_payment",
   /** Resume this payment id and retry the original x402 request with the merchant payment header. */
   RetryOriginalX402Request: "retry_original_x402_request",
@@ -145,29 +155,29 @@ var AgentPaymentPhaseDescriptions = {
   [AgentPaymentPhase.AgentSignatureRequired]: "The agent must sign and submit the prepared payment before Haven can relay it.",
   [AgentPaymentPhase.PaymentSubmitted]: "Haven has received the signed payment and the agent should poll for confirmation.",
   [AgentPaymentPhase.PaymentConfirmed]: "The direct payment is confirmed; the agent does not need to do more for this payment id.",
-  [AgentPaymentPhase.UserApprovalRequired]: "The payment needs wallet owner approval in Haven before it can continue.",
-  [AgentPaymentPhase.UserExecutionRequired]: "The wallet owner approved the request and still needs to complete the funding payment.",
-  [AgentPaymentPhase.WaitingForAdditionalApprovals]: "The funding payment was proposed and is waiting for the remaining account approvals.",
+  [AgentPaymentPhase.UserApprovalRequired]: "Retired wire value: no live rail produces it. It described the Safe rail's approval queue, which no longer exists \u2014 an out-of-policy payment is declined before any money moves. If it is ever seen, stop and tell the user; no approval is pending.",
+  [AgentPaymentPhase.UserExecutionRequired]: "Retired wire value: no live rail produces it. Stop and tell the user.",
+  [AgentPaymentPhase.WaitingForAdditionalApprovals]: "Retired wire value: no live rail produces it. Stop and tell the user.",
   [AgentPaymentPhase.FundingSent]: "The Haven funding leg was sent; the agent can continue the merchant/protocol leg.",
-  [AgentPaymentPhase.Rejected]: "The wallet owner rejected the request; the agent should stop and tell the user.",
-  [AgentPaymentPhase.Expired]: "The payment or approval request expired before completion.",
+  [AgentPaymentPhase.Rejected]: "The payment was rejected and cannot proceed; the agent should stop and tell the user.",
+  [AgentPaymentPhase.Expired]: "The payment expired before completion.",
   [AgentPaymentPhase.Failed]: "Haven could not complete the payment; the agent should stop and surface the failure.",
-  [AgentPaymentPhase.InsufficientFunds]: "Pre-flight check determined the delegate balance plus the remaining on-chain allowance cannot cover the requested amount, so no payment was created. The originating Safe must be funded or the agent allowance raised before retrying.",
-  [AgentPaymentPhase.FundedButUnsettled]: "Haven's funding leg confirmed on-chain but the merchant rejected the x402 retry. The delegate wallet may hold stranded funds. The agent should stop and wait for the wallet owner to sweep the stranded funds back to the Safe."
+  [AgentPaymentPhase.InsufficientFunds]: "Pre-flight check determined the delegate balance plus the remaining on-chain budget cannot cover the requested amount, so no payment was created. The account must be funded or the agent budget raised before retrying.",
+  [AgentPaymentPhase.FundedButUnsettled]: "Haven's funding leg confirmed on-chain but the merchant rejected the x402 retry. The delegate wallet may hold stranded funds. The agent should stop and wait for the wallet owner to sweep the stranded funds back to the account."
 };
 var AgentPaymentNextActionDescriptions = {
   [AgentPaymentNextAction.SignAndSubmitPayment]: "Sign with the delegate key and submit the payment to Haven.",
   [AgentPaymentNextAction.CheckStatusLater]: "Poll getPaymentStatus later using this payment id.",
   [AgentPaymentNextAction.None]: "No further agent action is required for this payment id.",
-  [AgentPaymentNextAction.WaitForUserApproval]: "Wait for the wallet owner to approve or reject the request in Haven.",
-  [AgentPaymentNextAction.WaitForUserToCompletePayment]: "Wait for the wallet owner to finish sending the approved funding payment.",
+  [AgentPaymentNextAction.WaitForUserApproval]: "Retired wire value: no live rail produces it, and nothing maps to it. It described a per-payment approval queue that no longer exists. If it is ever seen, stop and tell the user rather than polling \u2014 no approval will arrive.",
+  [AgentPaymentNextAction.WaitForUserToCompletePayment]: "Retired wire value: no live rail produces it. Stop and tell the user rather than polling.",
   [AgentPaymentNextAction.RetryOriginalX402Request]: "Resume this payment id and retry the original x402 request with the merchant payment header.",
   [AgentPaymentNextAction.StopAndTellUser]: "Stop retrying this payment and tell the user what happened.",
   [AgentPaymentNextAction.RequestAgainIfUserStillWantsIt]: "Ask again only if the user still wants the payment after expiry.",
   [AgentPaymentNextAction.PaymentWindowExpired]: "The x402 funding/quote window expired. Re-quote with the same idempotency key before asking the signer to build a merchant payment header again.",
-  [AgentPaymentNextAction.FundSafeOrRaiseAllowance]: "Stop and tell the user that the originating Safe needs to be funded or the agent allowance raised before the payment can succeed.",
+  [AgentPaymentNextAction.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 Safe."
+  [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."
 };
 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.",
@@ -210,7 +220,7 @@ var AgentPaymentWarningCode = {
   AllowanceReadOptimistic: "ALLOWANCE_READ_OPTIMISTIC"
 };
 var AgentPaymentRailDescriptions = {
-  [AgentPaymentRail.Direct]: "Standard Haven payment from the user-controlled Safe through an approved delegate allowance.",
+  [AgentPaymentRail.Direct]: "Standard Haven payment from the user-controlled account, redeeming the agent's on-chain budget delegation.",
   [AgentPaymentRail.X402]: "x402 HTTP 402 payment flow with a Haven funding leg and merchant retry leg.",
   [AgentPaymentRail.Mpp]: "Categorical MPP rail value used as a resume-state discriminator. Response bodies carry a granular mpp_* value instead.",
   [AgentPaymentRail.MppDemo]: "Haven internal MPP demo rail. Not for production traffic.",
@@ -1144,10 +1154,10 @@ function nextActionForStatus(status) {
   if (status === "pending_signature") return AgentPaymentNextAction.SignAndSubmitPayment;
   if (status === "submitted") return AgentPaymentNextAction.CheckStatusLater;
   if (status === "confirmed") return AgentPaymentNextAction.None;
-  if (status === "pending" || status === "pending_approval") return AgentPaymentNextAction.WaitForUserApproval;
+  if (status === "pending" || status === "pending_approval") return AgentPaymentNextAction.StopAndTellUser;
   if (status === "approved") return AgentPaymentNextAction.WaitForUserToCompletePayment;
-  if (status === "proposed") return AgentPaymentNextAction.WaitForUserApproval;
-  if (status === "executed") return AgentPaymentNextAction.RetryOriginalX402Request;
+  if (status === "proposed") return AgentPaymentNextAction.StopAndTellUser;
+  if (status === "executed") return AgentPaymentNextAction.StopAndTellUser;
   if (status === "rejected") return AgentPaymentNextAction.StopAndTellUser;
   if (status === "expired") return AgentPaymentNextAction.RequestAgainIfUserStillWantsIt;
   if (status === "failed") return AgentPaymentNextAction.StopAndTellUser;
@@ -1155,10 +1165,10 @@ function nextActionForStatus(status) {
 }
 function messageForState(label, status, paymentId, nextAction) {
   if (status === "pending" || status === "pending_approval") {
-    return `${label} is above the remaining agent budget and is waiting for user approval in Haven (payment_id: ${paymentId}).`;
+    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 === "executed") {
-    return "The user completed the funding payment. Retry the original x402 request.";
+    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.`;
   }
   if (status === "rejected") {
     return `The user rejected this payment request (payment_id: ${paymentId}).`;
@@ -1225,7 +1235,7 @@ function throwPaymentStateError(label, raw) {
   }
   if (raw.status === "pending_approval") {
     throw new HavenApiError(
-      `${label} exceeds the on-chain allowance and was queued for owner approval (payment_id: ${raw.payment_id}).`,
+      `${label} exceeds the agent's on-chain budget and was declined; no approval is pending and none will arrive (payment_id: ${raw.payment_id}).`,
       statusCode,
       raw
     );
@@ -1769,13 +1779,18 @@ function requestInitFromSnapshot(request) {
     body: request.body
   };
 }
+function noCompatiblePaymentOptionError(accepts) {
+  const erc7710Only = selectErc7710PaymentOption(accepts) !== null;
+  return new HavenApiError(
+    "No compatible payment option found in x402 requirements. Haven supports standard x402 exact payments on Base USDC." + (erc7710Only ? " The only Haven-compatible option this merchant advertises is tagged extra.assetTransferMethod: 'erc7710' (direct settlement), which this EIP-3009 payment path cannot settle \u2014 the limitation is the settlement scheme, not the asset. Paying this merchant requires a delegation-rail erc7710 flow (settleX402Erc7710, or the hosted MCP purchase tools)." : ""),
+    400
+  );
+}
 function buildX402Quote(paymentRequired, request, idempotencyKey, mcpTransport) {
-  const option = selectStandardPaymentOption(paymentRequired.accepts);
+  const standard = selectStandardPaymentOption(paymentRequired.accepts);
+  const option = standard ?? selectErc7710PaymentOption(paymentRequired.accepts);
   if (!option) {
-    throw new HavenApiError(
-      "No compatible payment option found in x402 requirements. Haven supports standard x402 exact payments on Base USDC.",
-      400
-    );
+    throw noCompatiblePaymentOptionError(paymentRequired.accepts);
   }
   const token = resolveTokenFromAddress(option.asset, option.network);
   return {
@@ -1783,6 +1798,7 @@ function buildX402Quote(paymentRequired, request, idempotencyKey, mcpTransport)
     idempotencyKey: idempotencyKey ?? buildX402IdempotencyKey(paymentRequired, option),
     paymentRequired,
     accepted: option,
+    acceptedScheme: standard ? "standard" : "erc7710",
     request,
     ...mcpTransport ? { mcpTransport } : {},
     resourceUrl: paymentRequired.resource.url,
@@ -2276,6 +2292,9 @@ var X402Erc7710 = class {
       // becomes a loud mismatch instead of a silent reroute to the 3009 leg.
       payTo: merchantPayTo,
       settlementScheme: "erc7710",
+      // #2041: sent only when the caller supplied one, so an omitting caller's
+      // request body is byte-identical to the pre-#2041 shape.
+      ...options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {},
       amount: amountAtomic,
       asset: option.asset,
       network: option.network,
@@ -2437,6 +2456,8 @@ function toolError(err) {
 
 // src/merchant-completion.ts
 var MERCHANT_BODY_SNIPPET_LIMIT = 1e3;
+var EVIDENCE_RETRY_DELAYS_MS = [1e3, 2e3, 4e3];
+var EVIDENCE_RETRYABLE_STATUS = 503;
 var MerchantCompletion = class {
   post;
   merchantTransport;
@@ -2444,7 +2465,9 @@ var MerchantCompletion = class {
   getAgent;
   delegateAddress;
   x402Wallet;
+  sleep;
   constructor(options) {
+    this.sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
     this.post = options.post;
     this.merchantTransport = options.merchantTransport;
     this.getPaymentStatus = options.getPaymentStatus;
@@ -2618,22 +2641,29 @@ var MerchantCompletion = class {
     }
   }
   async reportEvidence(input) {
-    try {
-      await this.post("/machine-payments/evidence", {
-        paymentId: input.paymentId,
-        rail: input.rail,
-        txHash: input.txHash,
-        resourceUrl: input.resourceUrl,
-        merchantStatus: input.merchantStatus,
-        challengePayload: input.challengePayload,
-        selectedPayment: input.selectedPayment,
-        paymentProofHeaderName: input.paymentProofHeaderName,
-        paymentProofHeader: input.paymentProofHeader,
-        protocolReceiptHeaderName: input.protocolReceiptHeaderName,
-        protocolReceiptHeader: input.protocolReceiptHeader,
-        protocolReceiptPayload: input.protocolReceiptHeader ? parseProtocolReceiptHeader(input.protocolReceiptHeader) : void 0
-      });
-    } catch {
+    const body = {
+      paymentId: input.paymentId,
+      rail: input.rail,
+      txHash: input.txHash,
+      resourceUrl: input.resourceUrl,
+      merchantStatus: input.merchantStatus,
+      challengePayload: input.challengePayload,
+      selectedPayment: input.selectedPayment,
+      paymentProofHeaderName: input.paymentProofHeaderName,
+      paymentProofHeader: input.paymentProofHeader,
+      protocolReceiptHeaderName: input.protocolReceiptHeaderName,
+      protocolReceiptHeader: input.protocolReceiptHeader,
+      protocolReceiptPayload: input.protocolReceiptHeader ? parseProtocolReceiptHeader(input.protocolReceiptHeader) : void 0
+    };
+    for (let attempt = 0; ; attempt += 1) {
+      try {
+        await this.post("/machine-payments/evidence", body);
+        return;
+      } catch (err) {
+        const retryable = err instanceof HavenApiError && err.statusCode === EVIDENCE_RETRYABLE_STATUS;
+        if (!retryable || attempt >= EVIDENCE_RETRY_DELAYS_MS.length) return;
+        await this.sleep(EVIDENCE_RETRY_DELAYS_MS[attempt]);
+      }
     }
   }
 };
@@ -2683,7 +2713,10 @@ function mapCatalogEntry(entry) {
     asset: entry.asset,
     network: entry.network,
     status: entry.status,
-    verifiedAt: entry.verified_at
+    verifiedAt: entry.verified_at,
+    source: entry.source,
+    domainVerified: entry.domain_verified,
+    verifiedPayable: entry.verified_payable
   };
 }
 var HavenClient = class {
@@ -2840,10 +2873,7 @@ var HavenClient = class {
   async createX402Intent(paymentRequired, options = {}) {
     const option = selectStandardPaymentOption(paymentRequired.accepts);
     if (!option) {
-      throw new HavenApiError(
-        "No compatible payment option found in x402 requirements. Haven supports standard x402 exact payments on Base USDC.",
-        400
-      );
+      throw noCompatiblePaymentOptionError(paymentRequired.accepts);
     }
     const fundingTo = options.delegateAddress ?? (await this.getAgent()).delegateAddress;
     if (!fundingTo) {
@@ -3119,7 +3149,7 @@ var HavenClient = class {
     return status;
   }
   /**
-   * Discover payable services from Haven's curated merchant catalog.
+   * Discover payable services from Haven's merchant catalog (epic #1717).
    *
    * Read-only: returns catalog entries (price, rail, protocol) so an agent
    * can choose a service and pay it with the regular payment tools in the
@@ -3132,7 +3162,39 @@ var HavenClient = class {
     if (options.rail) params.set("rail", options.rail);
     const query = params.size > 0 ? `?${params.toString()}` : "";
     const raw = await this.get(`/catalog${query}`);
-    return raw.entries.map(mapCatalogEntry);
+    let entries = raw.entries.map(mapCatalogEntry);
+    if (options.verified === "verified") entries = entries.filter((e) => e.source === "ingestion");
+    if (options.verified === "operator") entries = entries.filter((e) => e.source === "operator");
+    return entries;
+  }
+  /**
+   * Submit a merchant's payable (x402/MCP) endpoint to the Verified Payable
+   * Directory (epic #1717, #1716). Queue-only: writes a submission row and
+   * returns the id + verify_token. The request path makes no outbound
+   * request; domain-ownership proof and the read-only quote probe run later
+   * on the leader-locked monitor. Ownership proof is ALWAYS required before
+   * any listing — this method cannot skip it. `website` is a honeypot field
+   * that bots fill; leave it unset.
+   */
+  async submitCatalogEntry(resourceUrl, options = {}) {
+    const accepted = await this.post("/catalog/submit", {
+      resource_url: resourceUrl,
+      ...options.website ? { website: options.website } : {}
+    });
+    return {
+      id: accepted.id,
+      verifyToken: accepted.verify_token,
+      status: accepted.status
+    };
+  }
+  /**
+   * Fetch one submission's coarse status by id (epic #1717, #1716). Public
+   * and read-only. While the submission can still prove ownership the
+   * response carries the exact well-known / DNS-TXT `instructions`; the
+   * verify token is never returned here.
+   */
+  async getCatalogSubmissionStatus(id) {
+    return this.get(`/catalog/submit/${encodeURIComponent(id)}`);
   }
   /**
    * Fetch one curated catalog entry by id (#1306).
@@ -3207,10 +3269,7 @@ var HavenClient = class {
     }
     const option = selectStandardPaymentOption(paymentRequired.accepts);
     if (!option) {
-      throw new HavenApiError(
-        "No compatible payment option found in x402 requirements. Haven supports standard x402 exact payments on Base USDC.",
-        400
-      );
+      throw noCompatiblePaymentOptionError(paymentRequired.accepts);
     }
     const idempotencyKey = options.idempotencyKey ?? buildX402IdempotencyKey(paymentRequired, option);
     const cached = this.fundingLeg.cachedReceipt(idempotencyKey);
@@ -3350,10 +3409,7 @@ var HavenClient = class {
     }
     const option = selectStandardPaymentOption(input.paymentRequired.accepts);
     if (!option) {
-      throw new HavenApiError(
-        "No compatible payment option found in x402 requirements. Haven supports standard x402 exact payments on Base USDC.",
-        400
-      );
+      throw noCompatiblePaymentOptionError(input.paymentRequired.accepts);
     }
     const idempotencyKey = input.idempotencyKey ?? buildX402IdempotencyKey(input.paymentRequired, option);
     const cached = this.fundingLeg.cachedReceipt(idempotencyKey);
@@ -3553,11 +3609,12 @@ var HavenClient = class {
         });
       }
     } else {
-      if (!input.noFundingLeg && fundingTxHash) {
+      const evidenceTxHash = input.noFundingLeg ? settlement.settlementTxHash ?? void 0 : fundingTxHash ?? void 0;
+      if (evidenceTxHash) {
         await this.merchantCompletion.reportEvidence({
           paymentId: evidenceContext.paymentId,
           rail: "x402",
-          txHash: fundingTxHash,
+          txHash: evidenceTxHash,
           resourceUrl: evidenceContext.resourceUrl,
           merchantStatus: surfaced.status,
           paymentProofHeaderName: "X-PAYMENT",
@@ -3730,19 +3787,19 @@ var toolDescriptions = {
   payX402: {
     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 EIP-3009 payment from the delegate wallet, asks Haven for a Safe AllowanceModule top-up if needed, and returns the merchant response or a pending-approval state.",
-    nextActionGuidance: "If approval is needed, preserve the returned resume_state and wait for nextAction=retry_original_x402_request before resuming. If the response carries phase=insufficient_funds and nextAction=fund_safe_or_raise_allowance, the payment cannot be retried until the originating Safe is funded or the agent allowance raised \u2014 stop and tell the user the shortfall reported on the response."
+    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."
   },
   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 EIP-3009 payment from the delegate wallet, asks Haven for a Safe AllowanceModule top-up if needed, then retries the original request with the X-PAYMENT header and returns the merchant response. If the resource returns a non-402 status, returns it unchanged without contacting Haven.",
-    nextActionGuidance: "If approval is needed, preserve the returned resume_state or paymentId and call the resume tool once nextAction=retry_original_x402_request. If the response carries phase=insufficient_funds and nextAction=fund_safe_or_raise_allowance, the payment cannot be retried until the originating Safe is funded or the agent allowance raised \u2014 stop and tell the user the shortfall reported on the response."
+    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.",
+    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 after the Haven wallet owner approved the funding step.",
-    behavior: "Accepts either resume_state or payment_id, validates the original x402 details against the approved Haven funding, and retries the merchant request with the X-PAYMENT header. No new Haven approval is created.",
-    nextActionGuidance: "Only use when get_payment_status returns nextAction=retry_original_x402_request; do not start a new merchant session."
+    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.",
+    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
   // fragments) are retired along with the client surface they described —
@@ -3750,24 +3807,24 @@ var toolDescriptions = {
   // 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 or approval request id and returns the full state taxonomy (phase, nextAction, rail, amount, merchant, resource url, idempotency key, message).",
+    behavior: "Accepts a payment intent id and returns the full state taxonomy (phase, nextAction, rail, amount, merchant, resource url, idempotency key, message).",
     nextActionGuidance: ""
   },
   getResumeState: {
     summary: "Rehydrate stored x402 resume_state by payment_id.",
-    behavior: "Returns the context that the agent originally received in a pending-approval response, reconstructed from Haven's database. This is context only; signing still happens locally when a resume tool is called.",
+    behavior: "Returns the x402 context the agent originally received when the payment was authorized, reconstructed from Haven's database. This is context only; signing still happens locally when a resume tool is called.",
     nextActionGuidance: ""
   },
   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 on-chain AllowanceModule on the legacy rail, the active budget delegation on the delegation rail. 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. What an over-budget payment does differs by rail: on the legacy AllowanceModule rail it is queued for the wallet owner to approve in Haven; on the delegation rail there is no approval queue \u2014 an over-budget redemption reverts on-chain, 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, safeAddress, delegateAddress, chainId) are unchanged from before.`,
     nextActionGuidance: ""
   },
   getAllowances: {
     summary: "Return configured and on-chain allowance state for the authenticated agent. On-chain allowance is the real spend gate.",
     selectionGuidance: "Use this when the user asks about allowance, budget, spend limit, remaining amount, remaining allowance, remaining budget, daily limit, reset period, what can I spend, or what the agent can still spend.",
-    behavior: "Returns the per-token spend authority for the account's rail: the Safe AllowanceModule snapshot (allowance, spent, remaining, reset window) on the legacy rail, or the active budget delegation (remaining = the period budget; over-budget redemptions revert on-chain, nothing queues) on the delegation rail. Configured amounts from Haven are returned alongside.",
+    behavior: "Returns the per-token spend authority for the account: the active budget delegation (remaining = the period budget, which re-arms natively at the period boundary). An over-budget payment is declined before any money moves; nothing queues. Configured amounts from Haven are returned alongside.",
     nextActionGuidance: ""
   },
   listReceipts: {
@@ -3785,15 +3842,21 @@ var toolDescriptions = {
   payMcpTool: {
     summary: "Call a named tool on an MCP merchant that requires an x402 payment, handling the full initialize \u2192 pay \u2192 retry round trip in one call.",
     selectionGuidance: "Use this when the agent wants to call a specific tool on an MCP merchant (e.g. Soundside, Coinbase Bazaar) and payment is required. Prefer this over haven_pay_x402 when you know the merchant_url and tool_name \u2014 it builds the JSON-RPC envelope internally. Use haven_pay_x402 for arbitrary HTTP resources. Do NOT use for read-only allowance or budget questions \u2014 use haven_get_allowances.",
-    behavior: "Builds the JSON-RPC tools/call envelope, runs the MCP Streamable-HTTP initialize handshake automatically (if the endpoint is MCP-shaped), pays any HTTP 402 x402 challenge through Haven's AllowanceModule path, and retries the request, returning the JSON-RPC result (the actual merchant output) on success. Amounts within the on-chain allowance execute automatically; over-allowance transfers are queued as pending_approval \u2014 follow the response's nextAction when present.",
-    nextActionGuidance: "If pending_approval is returned, preserve payment_id and resume_state and wait for the wallet owner to approve in Haven. Use haven_resume_x402_payment once nextAction=retry_original_x402_request."
+    behavior: "Builds the JSON-RPC tools/call envelope, runs the MCP Streamable-HTTP initialize handshake automatically (if the endpoint is MCP-shaped), pays any HTTP 402 x402 challenge against the agent's on-chain budget delegation, and retries the request, returning the JSON-RPC result (the actual merchant output) on success. Amounts within the remaining on-chain budget execute automatically; anything outside it is declined before any money moves \u2014 follow the response's nextAction when present.",
+    nextActionGuidance: "On a decline, report the reason to the user and ask them to raise the budget in Haven \u2014 there is no approval queue to wait on. This tool retries the merchant itself while it runs, so do not wait on a signal mid-call. If the process crashes after payment, a later haven_get_payment_status call may report nextAction=retry_original_x402_request \u2014 resume via haven_resume_x402_payment instead of paying again."
   },
   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. 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, and suggested_tool. 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.",
+    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.",
+    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.`
   },
+  submitCatalogEntry: {
+    summary: "Submit a merchant's payable (x402/MCP) endpoint to Haven's Verified Payable Directory for verification and listing.",
+    selectionGuidance: "Use this when a merchant or seller asks to be listed in the directory, or when you have discovered a payable endpoint and want it registered. The submission is queue-only: it books a spot and returns a verify_token. The seller must then prove control of the domain (a well-known line or DNS TXT record); only after that plus a live quote probe does the entry become listed. Do NOT use to pay \u2014 check the returned status with getCatalogSubmissionStatus instead.",
+    behavior: "Sends the https resource_url to Haven's public submission endpoint. The request path makes no outbound request to the merchant. Returns id + verify_token + status; the verify_token is shown exactly once. Ownership proof is always required later and cannot be skipped from the agent side. The website field is a honeypot for bots \u2014 leave it unset.",
+    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.",
     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.",
@@ -3803,8 +3866,8 @@ var toolDescriptions = {
   send: {
     summary: "Send ETH or USDC directly from the agent's Haven wallet to a recipient address.",
     selectionGuidance: "Use this for plain transfers \u2014 refunding a user, paying a freelancer, topping up a co-agent's wallet, or moving funds between addresses. Do NOT use for x402 paid endpoints \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 through the Safe AllowanceModule. Amounts within the remaining on-chain allowance for the asset execute automatically; amounts that exceed the allowance are queued as pending_approval for the wallet owner to approve in Haven. The agent's signing key signs the AllowanceModule transfer hash; Haven never receives the key.",
-    nextActionGuidance: "If pending_approval is returned, preserve the payment_id and wait for the wallet owner to approve in Haven. Poll haven_get_payment_status until nextAction=none."
+    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."
   }
 };
 
@@ -3875,7 +3938,7 @@ var authorizeX402Schema = {
     },
     idempotencyKey: {
       type: "string",
-      description: "Stable caller-supplied key for this user intent. Reuse it when resuming after user approval."
+      description: "Stable caller-supplied key for this user intent. Reuse it when resuming the same payment."
     }
   },
   required: ["url", "payTo", "amount", "asset", "network"]
@@ -3885,7 +3948,7 @@ var resumeX402Schema = {
   properties: {
     payment_id: {
       type: "string",
-      description: "The payment or approval request ID returned by authorize_x402_payment."
+      description: "The payment ID returned by authorize_x402_payment."
     },
     url: {
       type: "string",
@@ -3918,11 +3981,11 @@ var resumeX402Schema = {
   },
   required: ["payment_id", "url", "payTo", "amount", "asset", "network"]
 };
-var MAKE_PAYMENT_DESCRIPTION = "Request and sign a payment from the user-controlled Safe within approved on-chain limits. 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, validates the signed intent, and relays the Safe AllowanceModule transaction; 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 and approval request IDs. Returns the current status, phase, next_action, transaction hash if available, and payment details.";
+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 and request a policy-limited Safe AllowanceModule top-up when needed. Haven relays signed transactions only; the agent key authorizes payment and on-chain limits enforce spend. If this returns pending_approval, tell the user it is waiting in Haven, preserve the original merchant/MCP session and x402 details, call get_payment_status later, and use resume_x402_payment only when next_action is retry_original_x402_request. Do not start a new merchant session or loop retries while approval is pending. Use the returned payment_header as the X-PAYMENT header on the retry request when doing a manual HTTP retry.";
-var RESUME_X402_DESCRIPTION = toolDescriptions.resumeX402.summary + " Use this only after get_payment_status returns next_action=retry_original_x402_request. It checks the approved payment, validates the original x402 details, and returns a merchant X-PAYMENT header without creating a new approval request or merchant session.";
+var AUTHORIZE_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 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 = {
   type: "object",
@@ -4032,8 +4095,8 @@ description: Pay for things from the user's Haven wallet within their agent rule
 
 This skill lets the agent make payments from the user's Haven wallet through
 the Haven MCP tools. Every payment is checked against the agent's on-chain
-budget before money moves; payments above the remaining budget wait for the
-user's approval in Haven.
+budget before money moves; a payment above the remaining budget is declined \u2014
+nothing is paid past the rules the user set.
 
 Hosted tools run in the \`mcp__haven__\` namespace. Local signing tools run in
 the \`mcp__haven-signer__\` namespace and keep the delegate key on this machine.
@@ -4077,8 +4140,8 @@ spending:
   (configured, spent, reset window) when you need more than the summary.
 
 Budgets reset on a period the user chose. If a payment exceeds the remaining
-budget it is queued for the user to approve in the Haven dashboard \u2014 this is
-normal, not an error.
+budget it is declined before any money moves \u2014 tell the user; they can raise
+the budget in the Haven dashboard, or wait for the period reset.
 
 ## Paying
 
@@ -4120,8 +4183,8 @@ context (\`merchant_url\`, \`tool_name\`, \`arguments\`, \`mcp_transport\`)
 server-side from \`payment_id\`. Pass those four fields explicitly only as a
 version-skew fallback when Haven has no stored context for the id \u2014 both or
 none together, never just one. If the settle result carries \`settled: false\`,
-funding is queued for the user's approval \u2014 tell them and check status later,
-do not re-pay.
+funding has not confirmed \u2014 follow the result's guidance fields and check
+status later, do not re-pay.
 
 Step-by-step alternative (also key-safe; for an older signer or backend, or
 when you already have a merchant URL and tool name instead of a
@@ -4144,8 +4207,12 @@ 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, sign in the local Haven signer, and retry the original request only
-when the result says \`retry_original_x402_request\`.
+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
+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
+payment id, instead of paying again.
 
 **Catalog tool arguments:** when \`haven_discover_tools\` returns
 \`tool_arguments\`, pass that object unchanged as the pay tool's
@@ -4161,14 +4228,14 @@ Haven authorizes for that call \u2014 a ceiling the merchant settles at or below
 so present it as the most the user will pay.
 
 **Status:** \`mcp__haven__haven_get_payment_status\` with a \`payment_id\` to
-check on queued or in-flight payments. Do not poll in a tight loop.
+check on in-flight payments. Do not poll in a tight loop.
 
-## Approval semantics
+## Declines and stop signals
 
-- A result with \`pending_approval\` means the payment exceeded the remaining
-  budget and is waiting for the user in Haven. Tell the user, then check
-  status later.
-- \`safe_to_continue: false\` on a guidance block is the same signal in
+- A payment outside the agent's rules \u2014 above the remaining budget, wrong
+  recipient, or expired budget \u2014 is declined before any money moves. Nothing
+  is queued; tell the user, who can raise the budget in Haven.
+- \`safe_to_continue: false\` on a guidance block is a stop signal in
   machine-readable form: stop and involve the user before calling anything
   else for this payment.
 - Never ask the user for private keys. Signing happens only in the local Haven
@@ -4182,7 +4249,6 @@ Haven tool failures are shaped like \`{ success: false, code, message, ... }\`
 or older \`{ error, status, details? }\` responses. Branch on \`code\` when
 present and surface \`message\` or \`error\` verbatim. Common cases:
 
-- \`pending_approval\`: queued for the user's approval (see above).
 - \`insufficient_funds\`: the Haven wallet doesn't hold enough of that token.
   Suggest the user add funds in the Haven dashboard.
 - \`PRICE_EXCEEDS_MAX\`: the live merchant price exceeded your cap. No funds