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

package/dist/index.cjs

@@ -114,12 +114,12 @@ var AgentPaymentNextAction = {
    * 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}.
+   * #2914: the account-vocabulary spelling, and the only one — the
+   * pre-#2907 `fund_safe_or_raise_allowance` wire value (and the
+   * `AgentPaymentNextActionAccountAlias` seam #2908 added to bridge it) are
+   * retired along with the rest of the #2908 compatibility window.
    */
-  FundSafeOrRaiseAllowance: "fund_safe_or_raise_allowance",
+  FundAccountOrRaiseAllowance: "fund_account_or_raise_allowance",
   /**
    * The delegate wallet may hold funds that were sent from the Safe but never
    * settled to the merchant. The wallet owner should initiate a sweep to
@@ -146,19 +146,6 @@ var AgentPaymentNextAction = {
    */
   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",
@@ -253,7 +240,7 @@ var AgentPaymentNextActionDescriptions = {
   [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 account needs to be funded or the agent budget raised before the payment can succeed.",
+  [AgentPaymentNextAction.FundAccountOrRaiseAllowance]: "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.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."
@@ -721,7 +708,13 @@ function normalizePaymentOption(value) {
     mimeType: candidate.mimeType,
     asset: candidate.asset,
     payTo: candidate.payTo,
-    maxTimeoutSeconds: clampAuthorizationWindow(candidate.maxTimeoutSeconds),
+    // Keep the merchant offer intact for v2 `accepted` matching. Only the
+    // signing conversion may cap its authorization lifetime (#3117).
+    // Retain legacy fallback behavior for missing or unusable timeouts.
+    // Integer, because the authorize body types it `integer` and the child's
+    // timestamp caveat is built from it — the old clamp floored, so keeping a
+    // fractional value here would 400 a merchant that used to work (#3117).
+    maxTimeoutSeconds: typeof candidate.maxTimeoutSeconds === "number" && Number.isFinite(candidate.maxTimeoutSeconds) && candidate.maxTimeoutSeconds >= 1 ? Math.floor(candidate.maxTimeoutSeconds) : clampAuthorizationWindow(candidate.maxTimeoutSeconds),
     extra: candidate.extra
   };
 }
@@ -872,6 +865,13 @@ function selectPaymentOption(accepts) {
   return null;
 }
 var ERC7710_ASSET_TRANSFER_METHOD = "erc7710";
+function isEip3009ConstructibleOption(option) {
+  const rawMethod = option.extra?.assetTransferMethod;
+  if (rawMethod !== void 0 && rawMethod !== "eip3009") return false;
+  const rawFlow = option.extra?.paymentFlow;
+  if (rawFlow !== void 0 && rawFlow !== "authorization") return false;
+  return true;
+}
 function x402AssetTransferMethod(option) {
   const raw = option.extra?.assetTransferMethod;
   return typeof raw === "string" ? raw : null;
@@ -892,7 +892,8 @@ function selectStandardPaymentOption(accepts) {
   if (!accepts || accepts.length === 0) return null;
   for (const opt of accepts) {
     if (opt === null || typeof opt !== "object") continue;
-    if (!isErc7710Option(opt) && isPayableStandardOption(opt)) return opt;
+    if (!isEip3009ConstructibleOption(opt)) continue;
+    if (isPayableStandardOption(opt)) return opt;
   }
   return null;
 }
@@ -901,6 +902,7 @@ function selectErc7710PaymentOption(accepts) {
   for (const opt of accepts) {
     if (opt === null || typeof opt !== "object") continue;
     if (isErc7710Option(opt) && isPayableStandardOption(opt)) return opt;
+    if (!isEip3009ConstructibleOption(opt)) continue;
   }
   return null;
 }
@@ -962,6 +964,11 @@ function toStandardPaymentRequirements(paymentRequired, option) {
   if (option.scheme !== "exact") {
     throw new Error(`Unsupported x402 scheme: ${option.scheme}`);
   }
+  if (!isEip3009ConstructibleOption(option)) {
+    throw new Error(
+      "Unsupported x402 payment requirements: this SDK constructs EIP-3009 authorization payments only. The merchant advertised a different extra.assetTransferMethod or an unrecognized extra.paymentFlow."
+    );
+  }
   return {
     scheme: "exact",
     network,
@@ -971,14 +978,11 @@ function toStandardPaymentRequirements(paymentRequired, option) {
     mimeType: option.mimeType ?? paymentRequired.resource.mimeType ?? "application/octet-stream",
     payTo: option.payTo,
     asset: option.asset,
-    // Second enforcement point (#715): the parse path clamps too, but this is
-    // the last stop before the x402 library turns the timeout into
-    // `validBefore` — options constructed without parsing are bounded here.
-    // The forward margin (#1256) is added ONLY here, at signing: the parse
-    // path keeps recording the merchant's advertised timeout unchanged, and
-    // the library's `validBefore = now + this value` then carries enough
-    // slack to satisfy the facilitator's `validBefore ≥ now + maxTimeout`
-    // verify rule after our funding leg confirms.
+    // Signing-only policy (#715/#3117): parsed and directly supplied options
+    // share this cap before the library computes validBefore. Keep the offer
+    // echoed in `accepted` unchanged. The forward margin (#1256) adds time
+    // for funding/retry, but does not guarantee a merchant timeout above the
+    // total bounded lifetime can pass facilitator verification.
     maxTimeoutSeconds: clampAuthorizationWindow(option.maxTimeoutSeconds) + X402_SETTLEMENT_FORWARD_MARGIN_SECONDS,
     extra: option.extra
   };
@@ -1226,10 +1230,7 @@ function mapPaymentStatusResult(raw) {
     rail: raw.rail,
     status: raw.status,
     phase: raw.phase,
-    // #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),
+    nextAction: raw.next_action,
     amount: raw.amount,
     token: raw.token,
     resourceUrl: raw.resource_url,
@@ -1365,7 +1366,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 = canonicalAgentPaymentNextAction(raw.next_action) ?? nextActionForStatus(raw.status);
+  const nextAction = raw.next_action ?? nextActionForStatus(raw.status);
   if (!phase || !nextAction) return null;
   const amount = raw.amount ?? raw.requested ?? "";
   const token = raw.token ?? "";
@@ -1436,6 +1437,51 @@ function throwPaymentStateError(label, raw) {
   throw new HavenApiError(message, statusCode, raw);
 }
 
+// src/x402-retry-target.ts
+function resolveX402RetryTarget(input) {
+  const requestUrl = input.requestUrl?.trim() || void 0;
+  if (requestUrl) {
+    return {
+      url: requestUrl,
+      source: "request",
+      resourceUrlDiffersFromRequest: requestUrl !== input.resourceUrl
+    };
+  }
+  return { url: input.resourceUrl, source: "resource" };
+}
+var LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["localhost", "::1", "[::1]"]);
+var RESERVED_SUFFIXES = [".test", ".localhost", ".invalid", ".example"];
+var IPV4_LOOPBACK = /^127(?:\.(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}$/;
+function isSecureX402RetryTarget(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return false;
+  }
+  if (parsed.protocol === "https:") return true;
+  if (parsed.protocol !== "http:") return false;
+  const host = parsed.hostname.toLowerCase();
+  if (LOOPBACK_HOSTS.has(host) || IPV4_LOOPBACK.test(host)) return true;
+  return RESERVED_SUFFIXES.some((suffix) => host.endsWith(suffix));
+}
+var INSECURE_RETRY_TARGET_CODE = "INSECURE_RETRY_TARGET";
+var HavenInsecureRetryTargetError = class extends HavenError {
+  constructor(url) {
+    super(
+      `Refusing to send a payment header to ${url}: the paid x402 retry must go to an https URL (or a loopback / reserved test host). The merchant's challenge declared this resource URL; retry with the https URL you quoted (pass it as \`url\`), and report a merchant whose challenge downgrades the scheme.`,
+      INSECURE_RETRY_TARGET_CODE,
+      400
+    );
+    this.url = url;
+    this.name = "HavenInsecureRetryTargetError";
+  }
+  url;
+};
+function assertSecureX402RetryTarget(url) {
+  if (!isSecureX402RetryTarget(url)) throw new HavenInsecureRetryTargetError(url);
+}
+
 // src/mcp-merchant-transport.ts
 var DEFAULT_MERCHANT_TIMEOUT = 3e5;
 var MCP_NOTIFICATION_TIMEOUT = 1e4;
@@ -1593,6 +1639,7 @@ var McpMerchantTransport = class {
    * overwrite, which is worse than the duplicate this change removes.
    */
   async deliverPayment(url, init, paymentHeader) {
+    assertSecureX402RetryTarget(url);
     const headers = new Headers(init?.headers);
     const send = x402PaymentHeaderNamesFor(paymentHeader);
     for (const name of X402_PAYMENT_HEADER_NAMES) {
@@ -1688,20 +1735,6 @@ 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 {
@@ -1721,6 +1754,10 @@ function deriveReadiness(status, allowances) {
   if (status !== "active") return "revoked";
   return allowances.some((allowance) => safeBigInt(allowance.remainingAtomic) > 0n) ? "ready" : "needs_approval";
 }
+function formatRemainingDisplay(tokenAddress, tokenSymbol, remainingAtomic) {
+  const token = resolveTokenFromAddress(tokenAddress);
+  return token ? `${formatAtomicAmount(safeBigInt(remainingAtomic), token.decimals)} ${tokenSymbol}` : `${remainingAtomic} ${tokenSymbol} (atomic; unknown decimals)`;
+}
 var AccountReads = class {
   transport;
   getPaymentStatus;
@@ -1742,12 +1779,12 @@ var AccountReads = class {
   async getAgentSummary() {
     const [agent, allowanceSummary] = await Promise.all([this.getAgent(), this.getAllowances()]);
     const allowances = allowanceSummary.allowances.map((allowance) => {
-      const token = resolveTokenFromAddress(allowance.tokenAddress);
-      const remainingDisplay = token ? `${formatAtomicAmount(safeBigInt(allowance.onchain.remaining), token.decimals)} ${allowance.tokenSymbol}` : `${allowance.onchain.remaining} ${allowance.tokenSymbol} (atomic; unknown decimals)`;
       return {
+        id: allowance.id,
         tokenSymbol: allowance.tokenSymbol,
+        tokenAddress: allowance.tokenAddress,
         remainingAtomic: allowance.onchain.remaining,
-        remainingDisplay,
+        remainingDisplay: allowance.remainingDisplay,
         configuredAmount: allowance.configuredAmount,
         resetPeriodMin: allowance.resetPeriodMin,
         isResetPending: allowance.onchain.isResetPending
@@ -1760,10 +1797,13 @@ var AccountReads = class {
     const raw = await this.transport.get("/machine-payments/allowances");
     return {
       agentId: raw.agent_id,
-      // #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)),
+      // `account_address` is required on the wire contract, so the declared
+      // type stays `string`; a server that omits it is off-contract and the
+      // cast is the one place that case is allowed through as `undefined`
+      // rather than a fabricated `''` (a present-but-blank address downstream
+      // — the hosted MCP output spreads this object, and the sweep uses it as
+      // a destination).
+      accountAddress: raw.account_address,
       delegateAddress: raw.delegate_address,
       chainId: raw.chain_id,
       allowances: raw.allowances.map((allowance) => ({
@@ -1772,6 +1812,7 @@ var AccountReads = class {
         tokenSymbol: allowance.token_symbol,
         configuredAmount: allowance.configured_amount,
         resetPeriodMin: allowance.reset_period_min,
+        remainingDisplay: formatRemainingDisplay(allowance.token_address, allowance.token_symbol, allowance.onchain.remaining),
         onchain: {
           amount: allowance.onchain.amount,
           spent: allowance.onchain.spent,
@@ -1786,6 +1827,33 @@ var AccountReads = class {
       }))
     };
   }
+  /**
+   * #3126 — the sufficiency signal behind {@link HavenBalanceCoverage}.
+   *
+   * Deliberately NOT a balance read: the endpoint answers whether the
+   * account HOLDS at least the checked amount, as `covered
+   * true/false/null`, and never returns the balance itself. The camelCase
+   * mapping is permissive (raw fields flow through; the server owns the
+   * wire shape, pinned by the backend's `expectMatchesSpec` assertion), so
+   * an older server that has not deployed the endpoint surfaces its 404 as
+   * a thrown error rather than a fabricated answer.
+   */
+  async checkFunds(input) {
+    const query = `token=${encodeURIComponent(input.token)}&amount_atomic=${encodeURIComponent(input.amountAtomic)}`;
+    const raw = await this.transport.get(
+      `/machine-payments/balance-coverage?${query}`
+    );
+    return {
+      covered: raw.covered,
+      ...raw.coverage_error !== void 0 ? { coverageError: raw.coverage_error } : {},
+      chainId: raw.chain_id,
+      tokenAddress: raw.token_address,
+      tokenSymbol: raw.token_symbol,
+      checkedAmountAtomic: raw.checked_amount_atomic,
+      budgetRemainingAtomic: raw.budget_remaining_atomic,
+      ...raw.budget_remaining_is_from_chain !== void 0 ? { budgetRemainingIsFromChain: raw.budget_remaining_is_from_chain } : {}
+    };
+  }
   async getPostPurchaseAllowanceSummary(paymentId) {
     const unavailable = (detail, payment2 = null) => ({
       payment: payment2,
@@ -1837,10 +1905,23 @@ var AccountReads = class {
       return unavailable(error instanceof Error ? error.message : String(error));
     }
   }
+  /** The first page's receipts as a bare array — the pre-#3128 shape, kept for callers that never page. */
   async listReceipts(options = {}) {
-    const query = options.limit ? `?limit=${encodeURIComponent(String(options.limit))}` : "";
+    return (await this.listReceiptsPage(options)).receipts;
+  }
+  /** #3128: one page with `total`, `hasMore` and `nextCursor` — see {@link HavenPaymentReceiptsPage}. */
+  async listReceiptsPage(options = {}) {
+    const params = new URLSearchParams();
+    if (options.limit) params.set("limit", String(options.limit));
+    if (options.cursor) params.set("cursor", options.cursor);
+    const query = params.size > 0 ? `?${params.toString()}` : "";
     const raw = await this.transport.get(`/machine-payments/receipts${query}`);
-    return raw.receipts.map(mapPaymentReceipt);
+    return {
+      receipts: raw.receipts.map(mapPaymentReceipt),
+      total: typeof raw.total === "number" ? raw.total : null,
+      hasMore: typeof raw.has_more === "boolean" ? raw.has_more : null,
+      nextCursor: typeof raw.next_cursor === "string" ? raw.next_cursor : null
+    };
   }
   async getReceipt(paymentId) {
     const { receipt } = await this.transport.get(`/payments/${paymentId}/receipt`);
@@ -1852,10 +1933,10 @@ var AccountReads = class {
       id: raw.id,
       name: raw.name,
       status: raw.status,
-      // #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)),
+      // See the comment on `getAllowances` above: `account_address` is
+      // required on the wire contract, so an omission here is off-contract
+      // and comes through as `undefined` rather than a fabricated `''`.
+      accountAddress: raw.account_address,
       delegateAddress: raw.delegate_address,
       chainId: raw.chain_id,
       executionRail: raw.execution_rail === "delegation" ? "delegation" : "legacy"
@@ -2012,8 +2093,11 @@ function requestInitFromSnapshot(request) {
 }
 function noCompatiblePaymentOptionError(accepts) {
   const erc7710Only = selectErc7710PaymentOption(accepts) !== null;
+  const unsupportedOnly = !erc7710Only && accepts.some(
+    (opt) => opt !== null && typeof opt === "object" && !isErc7710Option(opt) && (x402AssetTransferMethod(opt) !== null || opt.extra?.paymentFlow !== void 0)
+  );
   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)." : ""),
+    "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)." : unsupportedOnly ? " Every option this merchant advertises asks for a transfer method or payment flow Haven cannot construct (for example extra.assetTransferMethod: 'permit2', or an unrecognized extra.paymentFlow). No payment intent was created and no funds moved." : ""),
     400
   );
 }
@@ -2033,6 +2117,11 @@ function buildX402Quote(paymentRequired, request, idempotencyKey, mcpTransport)
     request,
     ...mcpTransport ? { mcpTransport } : {},
     resourceUrl: paymentRequired.resource.url,
+    // #3097: the merchant's declaration vs the URL the caller quoted. The
+    // paid retry goes to the caller's URL; a quote that says the two disagree
+    // is how an agent sees a challenge that downgrades the scheme or moves
+    // the host before it pays.
+    resourceUrlDiffersFromRequest: paymentRequired.resource.url !== request.url,
     description: paymentRequired.resource.description ?? option.description ?? null,
     mimeType: paymentRequired.resource.mimeType ?? option.mimeType ?? null,
     amountAtomic: x402AuthorizationAmount(option),
@@ -2187,6 +2276,13 @@ function assertCanResumeX402(status, paymentRequired, option) {
     );
   }
 }
+
+// src/account-naming.ts
+function readX402ReceiptPayer(raw) {
+  return raw.payer ?? raw.account_address ?? raw.sign_data?.components?.payer_account;
+}
+
+// src/x402-funding-leg.ts
 var X402FundingLeg = class {
   delegateKey;
   delegateAddress;
@@ -3099,7 +3195,18 @@ function mapCatalogEntry(entry) {
     verifiedAt: entry.verified_at,
     source: entry.source,
     domainVerified: entry.domain_verified,
-    verifiedPayable: entry.verified_payable
+    verifiedPayable: entry.verified_payable,
+    // #3078: absent (older backend) or null (unresolved join) both mean "no
+    // merchant known" — the public field is then absent, never null.
+    ...entry.merchant ? {
+      merchant: {
+        id: entry.merchant.id,
+        slug: entry.merchant.slug,
+        name: entry.merchant.name,
+        listingStatus: entry.merchant.listing_status,
+        isTestMerchant: entry.merchant.is_test_merchant
+      }
+    } : {}
   };
 }
 var HavenClient = class {
@@ -3481,6 +3588,49 @@ var HavenClient = class {
   async getAllowances() {
     return this.accountReads.getAllowances();
   }
+  /**
+   * #3126 — is the checked amount of the token actually HELD on the
+   * agent's own account?
+   *
+   * This is the companion to {@link getAllowances}, not a variant of it:
+   * allowances answer what the agent is PERMITTED to spend this period;
+   * this answers whether the account HOLDS funds behind that permission,
+   * as a sufficiency signal — `covered: true | false | null` — never as a
+   * balance. `covered: null` means the chain read failed: treat it as
+   * unverifiable, not as absence (`coverageError` says why). The account's
+   * balance itself is deliberately not returned.
+   */
+  async checkFunds(input) {
+    return this.accountReads.checkFunds(input);
+  }
+  /**
+   * `POST /machine-payments/budget-precheck` (#3054): ask Haven to decide —
+   * server-side — whether `amountAtomic` of `token` fits the agent's
+   * remaining delegation budget, the same compare the guided prepare used to
+   * run locally over its allowances read.
+   *
+   * On insufficiency Haven refuses (403, `delegation_budget_exceeded`) and
+   * the refusal reaches the `payment_refusals` ledger with
+   * `source: 'hosted_prepare'` — the point of the endpoint. This method
+   * surfaces that decision as a thrown {@link HavenApiError}; it does NOT
+   * swallow it, because swallowing would turn a decided refusal into the
+   * degrade-to-warning path and the ledger row would still land while the
+   * purchase proceeded.
+   *
+   * camelCase body like the route family; the response mirrors the wire
+   * (`sufficient`, `remaining_atomic`). `resourceUrl` is the merchant
+   * resource being bought — the ledger dedupe window's discriminating
+   * column — never this request's own URL.
+   */
+  async precheckBudget(input) {
+    return this.post("/machine-payments/budget-precheck", {
+      chainId: input.chainId,
+      token: input.token,
+      amountAtomic: input.amountAtomic,
+      ...input.merchantTo !== void 0 ? { merchantTo: input.merchantTo } : {},
+      ...input.resourceUrl !== void 0 ? { resourceUrl: input.resourceUrl } : {}
+    });
+  }
   /**
    * Post-purchase allowance/budget summary for a settled payment (#1310).
    *
@@ -3603,6 +3753,10 @@ var HavenClient = class {
   async listReceipts(options = {}) {
     return this.accountReads.listReceipts(options);
   }
+  /** #3128: one page of receipts with `total`, `hasMore` and `nextCursor`. */
+  async listReceiptsPage(options = {}) {
+    return this.accountReads.listReceiptsPage(options);
+  }
   /**
    * Fetch the verifiable receipt bundle for a settled payment and verify it
    * locally. The server's own verification is ignored — the receipt is verified
@@ -4212,13 +4366,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 (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."
+    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_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 (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."
+    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_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.",
@@ -4240,21 +4394,29 @@ var toolDescriptions = {
     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 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.`,
+    summary: "Return the authenticated agent identity AND its live spend authority in one call: Haven wallet, delegate, chain, raw status, spend_authority_readiness, per-token remaining allowance (atomic + human-readable). The recommended first call in a new session.",
+    selectionGuidance: "Use this as the session bootstrap, or to confirm identity together with whether the agent can spend right now. For per-token detail (configured vs spent vs reset window) use haven_get_allowances.",
+    behavior: 'Reads identity plus the live spend-authority snapshot \u2014 the 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 \u2014 ask the owner to grant or raise the budget in Haven. allowances[] carries id, tokenAddress, remainingAtomic, remainingDisplay per token. Identity fields: id, name, status, accountAddress, delegateAddress, chainId.',
     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: 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.",
+    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. For whether the account actually HOLDS funds behind the budget use haven_check_funds.",
+    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), each with id, onchain.remaining, remainingDisplay. An over-budget payment is declined before any money moves; nothing queues. Configured amounts from Haven are returned alongside.",
     nextActionGuidance: ""
   },
+  // #3126 — the sufficiency signal, deliberately NOT a balance tool. The
+  // constrained actor reads a boolean, never the treasury total.
+  checkFunds: {
+    summary: "Check whether the agent's account actually holds at least the given amount of a token \u2014 funds held, not spend permitted.",
+    selectionGuidance: "Use this before attempting a payment when it matters whether the money is really there: allowance answers say what you are PERMITTED to spend, never whether the account HOLDS it. For allowance, budget, spend-limit, remaining-budget, reset-period, or what-can-I-spend questions use the allowance lookup tool instead.",
+    behavior: "Returns covered: true (the account holds at least the checked amount), false (a live chain read reports less \u2014 the budget is backed by an empty account; stop and tell the user funds are missing), or null (the chain read failed \u2014 unverifiable, never treat it as absence; coverageError says why). The account balance itself is deliberately not returned: this is a sufficiency signal, not a balance read. budget_remaining_atomic is the permitted figure from the allowance lookup (the SDK spells it budgetRemainingAtomic), named so it can never be confused with holdings.",
+    nextActionGuidance: "On covered=false, do not attempt the payment \u2014 tell the user the account is short and let them fund it; on covered=null, retry the check shortly or proceed knowing the payment may fail on-chain."
+  },
   listReceipts: {
-    summary: "List recent machine-payment receipts and evidence for bookkeeping.",
-    selectionGuidance: "Use this for transaction history, receipts, payment evidence, or bookkeeping; use the allowance tool instead for remaining allowance, budget, spend-limit, or what-can-I-spend questions.",
-    behavior: "Returns the agent's recent machine-payment receipts ordered by recency. Proof header values are not returned.",
+    summary: "List machine-payment receipts, newest first, by page.",
+    selectionGuidance: "For transaction history or payment evidence; use the allowance tool instead for remaining allowance or what-can-I-spend questions.",
+    behavior: "Page: { receipts, total, hasMore, nextCursor }; total 0 = none exist (no indexing delay); hasMore = cut at limit, send nextCursor as cursor. parties.treasuryAccount is Haven's authoritative payer. protocolReceiptPayload is the merchant's PAYMENT-RESPONSE, relayed verbatim: merchant-controlled, unverified, not Haven's record; payer may differ from payerAddress. Proof header values are omitted.",
     nextActionGuidance: ""
   },
   verifyReceipt: {
@@ -4270,10 +4432,10 @@ var toolDescriptions = {
     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. 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.`
+    summary: "Step 1 of a purchase: discover payable services from Haven's curated merchant catalog \u2014 names, prices, the next call.",
+    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 next tool to call.",
+    behavior: "Use each entry's suggested_tool + suggested_arguments first; an entry without them says why. 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, the hint, 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: `Call suggested_tool with suggested_arguments VERBATIM (no hint: read suggested_tool_omitted_reason). Confirm the price from the live quote or pay result, not the catalog; if the next tool takes a cap, pass the user's cap as max_amount_human in whole tokens ("no more than 1 USDC" \u2192 max_amount_human: "1"), never atomic units by hand.`
   },
   submitCatalogEntry: {
     summary: "Submit a merchant's payable (x402/MCP) endpoint to Haven's Verified Payable Directory for verification and listing.",
@@ -4283,13 +4445,13 @@ var toolDescriptions = {
   },
   sweep_delegate: {
     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.",
+    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, or haven_check_funds for whether the account holds funds.",
     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: {
     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.",
+    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. Do NOT use to check whether funds are held before sending \u2014 use haven_check_funds.",
     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."
   },
@@ -4668,8 +4830,10 @@ the \`mcp__haven-signer__\` namespace and keep the delegate key on this machine.
 That namespacing is Claude-family; other runtimes name the servers by their
 own config keys (Codex: \`haven\`, \`haven_signer\`). Tool results carry the
 exact next step (\`next_action\`, \`next_tool\`, \`next_arguments\`, plus the
-runtime-neutral \`next_tool_server\` + \`next_tool_name\` \u2014 the bare tool name
-on that logical server, whatever your runtime calls it).
+runtime-neutral \`next_tool_server\` + \`next_tool_name\` + \`next_tool_server_role\`
+\u2014 the bare tool name on that logical server, whatever your runtime calls it).
+When no tool follows, \`next_tool\` is absent and \`next_tool_omitted_reason\`
+says why; that is a complete answer.
 Follow those fields first; the prose below is fallback and orientation, not
 the source of truth.
 
@@ -4756,6 +4920,13 @@ spending:
   local signer; the signer is verified by calling any signer tool.
 - \`mcp__haven__haven_get_allowances\` \u2014 detailed per-token breakdown
   (configured, spent, reset window) when you need more than the summary.
+- \`mcp__haven__haven_check_funds\` \u2014 whether the account actually HOLDS at
+  least a given amount of a token. Allowance answers above say what you are
+  permitted to spend; this one says whether the money is really there,
+  answered as \`covered\` true/false/null \u2014 never as a balance. On
+  \`covered: false\`, stop and tell the user the account is short; on
+  \`covered: null\` (the chain read failed), treat it as unverifiable rather
+  than as absence.
 
 Budgets reset on a period the user chose. If a payment exceeds the remaining
 budget it is declined before any money moves \u2014 tell the user; they can raise
@@ -4884,8 +5055,10 @@ check on in-flight payments. Do not poll in a tight loop.
 ## Failure handling
 
 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:
+or older \`{ error, status, details? }\` responses. A failure carries the same
+\`next_action\` / \`next_tool\` / \`next_arguments\` / \`next_tool_omitted_reason\`
+fields a success does; follow them first, then branch on \`code\` and surface
+\`message\` or \`error\` verbatim. Common cases:
 
 - \`insufficient_funds\`: the Haven wallet doesn't hold enough of that token.
   Suggest the user add funds in the Haven dashboard.
@@ -4946,6 +5119,64 @@ for that credential.
 var SKILL_FOLDER_NAME = "haven-pay";
 var HAVEN_SKILL_BODY_MD = HAVEN_SKILL_MD.replace(/^---\n[\s\S]*?\n---\n+/, "");
 
+// src/next-step.ts
+var NEXT_TOOL_SERVER_NAMES = {
+  hosted: "haven",
+  signer: "haven-signer"
+};
+var NEXT_TOOL_SERVER_ROLES = {
+  haven: "hosted",
+  "haven-signer": "signer"
+};
+function renderNextTool(role, name) {
+  return `mcp__${NEXT_TOOL_SERVER_NAMES[role]}__${name}`;
+}
+function parseNextTool(literal) {
+  const m = /^mcp__([a-z0-9-]+)__([a-z0-9_]+)$/.exec(literal);
+  if (!m) return null;
+  const role = NEXT_TOOL_SERVER_ROLES[m[1]];
+  return { server: m[1], name: m[2], ...role ? { role } : {} };
+}
+var DEFAULT_NEXT_TOOL_BY_ACTION = {
+  check_status_later: "haven_get_payment_status",
+  sweep_stranded_funds: "haven_sweep_delegate"
+  // `retry_original_x402_request` is NOT here: its only live emitter
+  // (state-direct-recovery.ts, erc7710) names no tool on purpose — the retry
+  // is the agent's own HTTP call — so a default would contradict the site.
+};
+function defaultNextToolFor(action) {
+  return DEFAULT_NEXT_TOOL_BY_ACTION[action];
+}
+function createNextStepBuilder(targets) {
+  return function nextStep(input) {
+    const i = input;
+    const base = {
+      next_action: input.nextAction,
+      safe_to_continue: input.safeToContinue,
+      reason: input.reason
+    };
+    if (i.nextTool === null) {
+      return { ...base, next_tool_omitted_reason: i.nextToolOmittedReason ?? "no next tool" };
+    }
+    const target = targets[i.nextTool];
+    if (!target) {
+      return { ...base, next_tool_omitted_reason: `${i.nextTool} is not a registered next-step target` };
+    }
+    const problem = target.validate(i.nextArguments);
+    if (problem) {
+      return { ...base, next_tool_omitted_reason: `next_arguments do not parse under ${i.nextTool}: ${problem}` };
+    }
+    return {
+      ...base,
+      next_tool: renderNextTool(target.role, i.nextTool),
+      next_tool_server: NEXT_TOOL_SERVER_NAMES[target.role],
+      next_tool_name: i.nextTool,
+      next_tool_server_role: target.role,
+      next_arguments: i.nextArguments
+    };
+  };
+}
+
 // src/node-version.ts
 var HAVEN_MINIMUM_NODE_VERSION = "22.0.0";
 function parseNodeVersion(value) {
@@ -5047,7 +5278,6 @@ exports.AgentPaymentFailureCode = AgentPaymentFailureCode;
 exports.AgentPaymentFailureCodeDescriptions = AgentPaymentFailureCodeDescriptions;
 exports.AgentPaymentFailureCodeSchema = AgentPaymentFailureCodeSchema;
 exports.AgentPaymentNextAction = AgentPaymentNextAction;
-exports.AgentPaymentNextActionAccountAlias = AgentPaymentNextActionAccountAlias;
 exports.AgentPaymentNextActionDescriptions = AgentPaymentNextActionDescriptions;
 exports.AgentPaymentNextActionSchema = AgentPaymentNextActionSchema;
 exports.AgentPaymentPhase = AgentPaymentPhase;
@@ -5059,6 +5289,7 @@ exports.AgentPaymentRailSchema = AgentPaymentRailSchema;
 exports.AgentPaymentWarningCode = AgentPaymentWarningCode;
 exports.CONNECTOR_PACKAGE_NAME = CONNECTOR_PACKAGE_NAME;
 exports.DEFAULT_CONFIRMATION_TIMEOUT_MS = DEFAULT_CONFIRMATION_TIMEOUT_MS;
+exports.DEFAULT_NEXT_TOOL_BY_ACTION = DEFAULT_NEXT_TOOL_BY_ACTION;
 exports.DISCOVERY_MAX_BYTES = DISCOVERY_MAX_BYTES;
 exports.ERC7710_ASSET_TRANSFER_METHOD = ERC7710_ASSET_TRANSFER_METHOD;
 exports.HAVEN_AGENT_RUNBOOK_MD = HAVEN_AGENT_RUNBOOK_MD;
@@ -5069,13 +5300,17 @@ exports.HAVEN_SKILL_MD = HAVEN_SKILL_MD;
 exports.HavenApiError = HavenApiError;
 exports.HavenClient = HavenClient;
 exports.HavenError = HavenError;
+exports.HavenInsecureRetryTargetError = HavenInsecureRetryTargetError;
 exports.HavenPaymentStateError = HavenPaymentStateError;
 exports.HavenSigningError = HavenSigningError;
 exports.HavenTimeoutError = HavenTimeoutError;
 exports.HavenUnsupportedSignerVersionError = HavenUnsupportedSignerVersionError;
 exports.HavenZeroSettlementHashError = HavenZeroSettlementHashError;
+exports.INSECURE_RETRY_TARGET_CODE = INSECURE_RETRY_TARGET_CODE;
 exports.MERCHANT_DISCOVERY_PATHS = MERCHANT_DISCOVERY_PATHS;
 exports.MerchantTimeoutError = MerchantTimeoutError;
+exports.NEXT_TOOL_SERVER_NAMES = NEXT_TOOL_SERVER_NAMES;
+exports.NEXT_TOOL_SERVER_ROLES = NEXT_TOOL_SERVER_ROLES;
 exports.RECEIPT_VERSION = RECEIPT_VERSION;
 exports.SIGNER_UPDATE_FALLBACK = SIGNER_UPDATE_FALLBACK;
 exports.SKILL_FOLDER_NAME = SKILL_FOLDER_NAME;
@@ -5095,18 +5330,19 @@ 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.assertSecureX402RetryTarget = assertSecureX402RetryTarget;
 exports.buildSweepAuthorizationMessage = buildSweepAuthorizationMessage;
 exports.buildSweepTypedData = buildSweepTypedData;
 exports.buildX402ExpectedMessage = buildX402ExpectedMessage;
-exports.canonicalAgentPaymentNextAction = canonicalAgentPaymentNextAction;
 exports.compareNodeVersions = compareNodeVersions;
 exports.composeDescription = composeDescription;
 exports.connectorRerunCommand = connectorRerunCommand;
 exports.connectorSpec = connectorSpec;
+exports.createNextStepBuilder = createNextStepBuilder;
 exports.decodeBase64Json = decodeBase64Json;
 exports.decodeBase64Utf8 = decodeBase64Utf8;
+exports.defaultNextToolFor = defaultNextToolFor;
 exports.discoverMerchantMcpUrl = discoverMerchantMcpUrl;
 exports.encodeBase64Json = encodeBase64Json;
 exports.encodeBase64Utf8 = encodeBase64Utf8;
@@ -5114,18 +5350,19 @@ exports.encodePaymentProof = encodePaymentProof;
 exports.havenTools = havenTools;
 exports.isConnectorChannel = isConnectorChannel;
 exports.isErc7710Option = isErc7710Option;
-exports.isFundAccountOrRaiseAllowance = isFundAccountOrRaiseAllowance;
+exports.isSecureX402RetryTarget = isSecureX402RetryTarget;
 exports.isSupportedNodeVersion = isSupportedNodeVersion;
 exports.isSweepableChain = isSweepableChain;
 exports.isZeroSettlementTxHash = isZeroSettlementTxHash;
 exports.normalizePaymentRequired = normalizePaymentRequired;
+exports.parseNextTool = parseNextTool;
 exports.parsePaymentRequired = parsePaymentRequired;
 exports.parsePaymentRequiredResponse = parsePaymentRequiredResponse;
-exports.readAccountAddress = readAccountAddress;
-exports.readAccountId = readAccountId;
 exports.readX402ReceiptPayer = readX402ReceiptPayer;
+exports.renderNextTool = renderNextTool;
 exports.resolveConnectorChannel = resolveConnectorChannel;
 exports.resolveTokenFromAddress = resolveTokenFromAddress;
+exports.resolveX402RetryTarget = resolveX402RetryTarget;
 exports.sameUrl = sameUrl;
 exports.selectErc7710PaymentOption = selectErc7710PaymentOption;
 exports.selectPaymentOption = selectPaymentOption;