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

package/README.md

@@ -79,6 +79,7 @@ shows up in your Haven dashboard activity feed.
 - The delegate key signs payment payloads locally. Haven's backend never receives it.
 - The agent's on-chain budget delegation enforces the agent budget: budget, recipient and expiry are checked by audited caveat enforcers at redemption, not by an off-chain rules engine.
 - `getAllowances()` / `get_allowances` is the right path for budget, remaining amount, reset period, or "what can I spend?" questions.
+- `checkFunds()` / `haven_check_funds` answers the different question of whether the account actually holds funds behind the budget — as a sufficiency signal (`covered` true/false/null), never as a balance.
 - If an API key is exposed or lost, rotate it from the Haven agent detail page. The new key is shown once and the old key stops working.
 - If a delegate key is exposed or lost, a delegation-rail agent is **re-keyed** rather than replaced — same agent, new signing key, budget remainder carried. See [Replacing an agent's signing key](../../docs/product/agent-key-rotation.md).
 

package/dist/index.cjs

@@ -708,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
   };
 }
@@ -859,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;
@@ -879,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;
 }
@@ -888,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;
 }
@@ -949,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,
@@ -958,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
   };
@@ -1420,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;
@@ -1577,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) {
@@ -1691,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;
@@ -1712,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
@@ -1745,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,
@@ -1759,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,
@@ -1810,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`);
@@ -1985,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
   );
 }
@@ -2006,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),
@@ -3079,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 {
@@ -3461,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).
    *
@@ -3583,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
@@ -4220,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, 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: {
@@ -4250,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.",
@@ -4263,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."
   },
@@ -4648,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.
 
@@ -4736,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
@@ -4864,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.
@@ -4926,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) {
@@ -5038,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;
@@ -5048,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;
@@ -5075,6 +5331,7 @@ exports.X402_PAYMENT_REQUIRED_HEADER_NAME = X402_PAYMENT_REQUIRED_HEADER_NAME;
 exports.X402_PAYMENT_RESPONSE_HEADER_NAME = X402_PAYMENT_RESPONSE_HEADER_NAME;
 exports.X402_SETTLEMENT_FORWARD_MARGIN_SECONDS = X402_SETTLEMENT_FORWARD_MARGIN_SECONDS;
 exports.addressFromKey = addressFromKey;
+exports.assertSecureX402RetryTarget = assertSecureX402RetryTarget;
 exports.buildSweepAuthorizationMessage = buildSweepAuthorizationMessage;
 exports.buildSweepTypedData = buildSweepTypedData;
 exports.buildX402ExpectedMessage = buildX402ExpectedMessage;
@@ -5082,8 +5339,10 @@ 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;
@@ -5091,15 +5350,19 @@ exports.encodePaymentProof = encodePaymentProof;
 exports.havenTools = havenTools;
 exports.isConnectorChannel = isConnectorChannel;
 exports.isErc7710Option = isErc7710Option;
+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.readX402ReceiptPayer = readX402ReceiptPayer;
+exports.renderNextTool = renderNextTool;
 exports.resolveConnectorChannel = resolveConnectorChannel;
 exports.resolveTokenFromAddress = resolveTokenFromAddress;
+exports.resolveX402RetryTarget = resolveX402RetryTarget;
 exports.sameUrl = sameUrl;
 exports.selectErc7710PaymentOption = selectErc7710PaymentOption;
 exports.selectPaymentOption = selectPaymentOption;