@haven_ai/sdk 0.5.0-alpha.1 → 0.7.0-alpha.0

package/dist/index.js

@@ -1,8 +1,8 @@
-import { selectStandardPaymentOption, buildX402IdempotencyKey, x402AuthorizationAmount, assertBoundDirectPaymentUserOp, HavenTypedDataRefusedError, assertOwnSettlementChild, parsePaymentRequiredResponse, x402PaymentHeaderNamesSent, SDK_CLIENT_IDENTITY, readClientUpdate, HAVEN_CLIENT_HEADER, resolveTokenFromAddress, isSweepableChain, sweepUsdcAddress, x402PaymentHeaderNamesFor, X402_PAYMENT_HEADER_NAMES, toStandardPaymentRequirements, decodeBase64Json, encodeBase64Json, x402V2PaymentEnvelope, selectX402SettlementScheme, selectErc7710PaymentOption, isErc7710Option, x402AssetTransferMethod, normalizePaymentRequired } from './chunk-KQ7JXKTV.js';
-export { DEFAULT_NEXT_TOOL_BY_ACTION, ERC7710_ASSET_TRANSFER_METHOD, HAVEN_CLIENT_HEADER, HAVEN_MINIMUM_NODE_VERSION, HavenTypedDataRefusedError, NEXT_TOOL_SERVER_NAMES, NEXT_TOOL_SERVER_ROLES, SDK_CLIENT_IDENTITY, SDK_VERSION, SWEEP_BASE_CHAIN_ID, SWEEP_BASE_SEPOLIA_CHAIN_ID, SWEEP_BASE_SEPOLIA_USDC_ADDRESS, SWEEP_BASE_USDC_ADDRESS, TRANSFER_WITH_AUTHORIZATION_TYPES, TYPED_DATA_NOT_ALLOWED, X402PaymentHeaderValidationError, X402_LEGACY_PAYMENT_HEADER_NAME, X402_MAX_AUTHORIZATION_WINDOW_SECONDS, X402_PAYMENT_HEADER_NAME, X402_PAYMENT_HEADER_NAMES_SENT, X402_PAYMENT_REQUIRED_HEADER_NAME, X402_PAYMENT_RESPONSE_HEADER_NAME, X402_SETTLEMENT_FORWARD_MARGIN_SECONDS, assertBoundDirectPaymentUserOp, buildSweepAuthorizationMessage, buildSweepTypedData, buildX402ExpectedMessage, compareNodeVersions, createNextStepBuilder, decodeBase64Json, decodeBase64Utf8, defaultNextToolFor, encodeBase64Json, encodeBase64Utf8, encodePaymentProof, havenClientIdentity, isErc7710Option, isSupportedNodeVersion, isSweepableChain, normalizePaymentRequired, parseNextTool, parsePaymentRequired, parsePaymentRequiredResponse, readClientUpdate, renderNextTool, resolveTokenFromAddress, selectErc7710PaymentOption, selectPaymentOption, selectStandardPaymentOption, selectX402SettlementScheme, sweepUsdcAddress, sweepUsdcDomain, toStandardPaymentRequirements, unsupportedNodeVersionMessage, validateStandardX402PaymentHeader, x402AssetTransferMethod, x402AuthorizationAmount, x402FacilitatorAddresses, x402V2PaymentEnvelope } from './chunk-KQ7JXKTV.js';
-import { HavenSigningError, HavenError, DEFAULT_CONFIRMATION_TIMEOUT_MS, HavenApiError, assertUserOpTypedDataBinding, AgentPaymentRail, AgentPaymentPhase, HavenTimeoutError, X402UnexpectedStatusError, X402AlreadySettledError, AgentPaymentWarningCode, MerchantTimeoutError, AgentPaymentNextAction, HavenPaymentStateError, HavenZeroSettlementHashError, chainIdForNetwork } from './chunk-GLNG2GF7.js';
-export { AGENT_PAYMENT_FAILURE_CODE_VALUES, AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, AgentPaymentFailureCode, AgentPaymentFailureCodeDescriptions, AgentPaymentFailureCodeSchema, AgentPaymentNextAction, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, AgentPaymentWarningCode, CONNECTOR_PACKAGE_NAME, DEFAULT_CONFIRMATION_TIMEOUT_MS, DIRECT_SIGN_CONTEXT_VERSION, ENTRY_POINT_V07, HAVEN_CONNECTOR_CHANNEL, HYBRID_DELEGATOR_DOMAIN_NAME, HYBRID_DELEGATOR_DOMAIN_VERSION, HavenApiError, HavenError, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, HavenUnsupportedSignerVersionError, HavenUserOpBindingError, HavenZeroSettlementHashError, MerchantTimeoutError, PACKED_USER_OPERATION_FIELDS, ROOT_AUTHORITY, SIGNER_UPDATE_FALLBACK, SignerRefusalCode, X402AlreadySettledError, X402UnexpectedStatusError, assertUserOpTypedDataBinding, connectorRerunCommand, connectorSpec, deriveDelegateAccountAddress, isConnectorChannel, isPackedUserOperationTypedData, packedUserOperationHash, resolveConnectorChannel, signerUpdateFallback, verifySettlementChild } from './chunk-GLNG2GF7.js';
-import { hashTypedData } from 'viem';
+import { selectStandardPaymentOption, buildX402IdempotencyKey, x402AuthorizationAmount, assertBoundDirectPaymentUserOp, assertFundingLegPaysDelegate, HavenTypedDataRefusedError, assertOwnSettlementChild, parsePaymentRequiredResponse, x402PaymentHeaderNamesSent, SDK_CLIENT_IDENTITY, readClientUpdate, HAVEN_CLIENT_HEADER, resolveTokenFromAddress, isSweepableChain, sweepUsdcAddress, x402PaymentHeaderNamesFor, X402_PAYMENT_HEADER_NAMES, toStandardPaymentRequirements, decodeBase64Json, encodeBase64Json, x402V2PaymentEnvelope, selectX402SettlementScheme, selectErc7710PaymentOption, isErc7710Option, x402AssetTransferMethod, normalizePaymentRequired } from './chunk-R3RZJJWL.js';
+export { DEFAULT_NEXT_TOOL_BY_ACTION, ERC7710_ASSET_TRANSFER_METHOD, HAVEN_CLIENT_HEADER, HAVEN_MINIMUM_NODE_VERSION, HavenTypedDataRefusedError, MAX_TASK_BUDGET_TTL_SECONDS, NEXT_TOOL_SERVER_NAMES, NEXT_TOOL_SERVER_ROLES, SDK_CLIENT_IDENTITY, SDK_VERSION, SWEEP_BASE_CHAIN_ID, SWEEP_BASE_SEPOLIA_CHAIN_ID, SWEEP_BASE_SEPOLIA_USDC_ADDRESS, SWEEP_BASE_USDC_ADDRESS, TRANSFER_WITH_AUTHORIZATION_TYPES, TYPED_DATA_NOT_ALLOWED, X402PaymentHeaderValidationError, X402_LEGACY_PAYMENT_HEADER_NAME, X402_MAX_AUTHORIZATION_WINDOW_SECONDS, X402_PAYMENT_HEADER_NAME, X402_PAYMENT_HEADER_NAMES_SENT, X402_PAYMENT_REQUIRED_HEADER_NAME, X402_PAYMENT_RESPONSE_HEADER_NAME, X402_SETTLEMENT_FORWARD_MARGIN_SECONDS, assertBoundDirectPaymentUserOp, assertOwnTaskBudgetCloseUserOp, assertOwnTaskChild, buildSweepAuthorizationMessage, buildSweepTypedData, buildX402ExpectedMessage, compareNodeVersions, createNextStepBuilder, decodeBase64Json, decodeBase64Utf8, defaultNextToolFor, encodeBase64Json, encodeBase64Utf8, encodePaymentProof, hashDelegation, havenClientIdentity, isErc7710Option, isSupportedNodeVersion, isSweepableChain, isTaskChildTypedData, normalizePaymentRequired, parseNextTool, parsePaymentRequired, parsePaymentRequiredResponse, readClientUpdate, renderNextTool, resolveTokenBySymbol, resolveTokenFromAddress, selectErc7710PaymentOption, selectPaymentOption, selectStandardPaymentOption, selectX402SettlementScheme, sweepUsdcAddress, sweepUsdcDomain, toStandardPaymentRequirements, unsupportedNodeVersionMessage, validateStandardX402PaymentHeader, x402AssetTransferMethod, x402AuthorizationAmount, x402FacilitatorAddresses, x402V2PaymentEnvelope } from './chunk-R3RZJJWL.js';
+import { HavenSigningError, HavenError, DEFAULT_CONFIRMATION_TIMEOUT_MS, HavenApiError, assertUserOpTypedDataBinding, AgentPaymentRail, AgentPaymentPhase, HavenTimeoutError, X402TaskBudgetMismatchError, X402UnexpectedStatusError, X402AlreadySettledError, AgentPaymentWarningCode, MerchantTimeoutError, AgentPaymentNextAction, HavenPaymentStateError, HavenZeroSettlementHashError, X402Erc7710AlreadySettledError, DELEGATION_MANAGER, chainIdForNetwork } from './chunk-NNIT7WAI.js';
+export { AGENT_PAYMENT_FAILURE_CODE_VALUES, AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, AgentPaymentFailureCode, AgentPaymentFailureCodeDescriptions, AgentPaymentFailureCodeSchema, AgentPaymentNextAction, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, AgentPaymentWarningCode, CONNECTOR_PACKAGE_NAME, DEFAULT_CONFIRMATION_TIMEOUT_MS, DIRECT_SIGN_CONTEXT_VERSION, ENTRY_POINT_V07, HAVEN_CONNECTOR_CHANNEL, HYBRID_DELEGATOR_DOMAIN_NAME, HYBRID_DELEGATOR_DOMAIN_VERSION, HavenApiError, HavenError, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, HavenUnsupportedSignerVersionError, HavenUserOpBindingError, HavenZeroSettlementHashError, MerchantTimeoutError, PACKED_USER_OPERATION_FIELDS, ROOT_AUTHORITY, SIGNER_UPDATE_FALLBACK, SignerRefusalCode, TASK_SIGN_CONTEXT_VERSION, X402AlreadySettledError, X402Erc7710AlreadySettledError, X402TaskBudgetMismatchError, X402UnexpectedStatusError, assertUserOpTypedDataBinding, connectorRerunCommand, connectorSpec, connectorUpgradeCommand, deriveDelegateAccountAddress, isConnectorChannel, isPackedUserOperationTypedData, packedUserOperationHash, resolveConnectorChannel, signerUpdateFallback, verifySettlementChild } from './chunk-NNIT7WAI.js';
+import { keccak256, toBytes, concatHex, hashTypedData, encodeAbiParameters } from 'viem';
 import { ethers } from 'ethers';
 import { AsyncLocalStorage } from 'async_hooks';
 import { exact } from 'x402/schemes';
@@ -161,7 +161,18 @@ function mapParties(raw) {
     treasuryAccount: raw.treasury_account,
     delegate: raw.delegate,
     delegateAccount: raw.delegate_account,
-    merchant: raw.merchant
+    merchant: raw.merchant,
+    // #3332: additive — absent unless the wire shape carries it.
+    ...raw.buyer ? {
+      buyer: {
+        legalName: raw.buyer.legal_name,
+        country: raw.buyer.country,
+        orgNumber: raw.buyer.org_number,
+        vatNumber: raw.buyer.vat_number,
+        viesStatus: raw.buyer.vies_status,
+        viesCheckedAt: raw.buyer.vies_checked_at
+      }
+    } : {}
   };
 }
 function mapPaymentResult(raw, buildExplorerUrl2) {
@@ -205,6 +216,9 @@ function mapPaymentStatusResult(raw) {
     expiresAt: raw.expires_at,
     chainId: raw.chain_id,
     message: raw.message,
+    // #3420: the delivered half of the settle vocabulary, additive — absent
+    // from the raw payload (older backend) stays absent here.
+    ...raw.delivered === true ? { delivered: true } : {},
     fee: raw.fee ? {
       amount: raw.fee.amount,
       token: raw.fee.token,
@@ -232,17 +246,13 @@ function mapPaymentReceipt(raw) {
     id: raw.id,
     paymentId: raw.payment_id,
     source: raw.rail,
-    rail: raw.rail,
     paymentProofStatus: raw.proof_status,
-    proofStatus: raw.proof_status,
     txHash: raw.tx_hash,
     fundingTxHash: raw.funding_tx_hash ?? null,
     settlementTxHash: raw.settlement_tx_hash ?? null,
     chainId: raw.chain_id,
     x402ResourceUrl: raw.resource_url,
-    resourceUrl: raw.resource_url,
     x402MerchantAddress: raw.merchant_address,
-    merchantAddress: raw.merchant_address,
     payerAddress: raw.payer_address,
     parties: mapParties(raw.parties),
     settlementAddress: raw.settlement_address,
@@ -842,22 +852,93 @@ function selectJsonRpcResult(messages) {
   return messages.find((message) => "result" in message || "error" in message) ?? messages.at(-1);
 }
 var RECEIPT_VERSION = "haven-receipt-1";
+var DELEGATION_MANAGER_CHAIN_IDS = /* @__PURE__ */ new Set([8453, 84532]);
+var EIP712_DOMAIN_TYPEHASH = keccak256(
+  toBytes("EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)")
+);
+function delegationDomainSeparator(chainId) {
+  return keccak256(
+    encodeAbiParameters(
+      [{ type: "bytes32" }, { type: "bytes32" }, { type: "bytes32" }, { type: "uint256" }, { type: "address" }],
+      [
+        EIP712_DOMAIN_TYPEHASH,
+        keccak256(toBytes("DelegationManager")),
+        keccak256(toBytes("1")),
+        BigInt(chainId),
+        DELEGATION_MANAGER
+      ]
+    )
+  );
+}
+function delegationDigest(structHash, chainId) {
+  return keccak256(concatHex(["0x1901", delegationDomainSeparator(chainId), structHash]));
+}
 function defaultRecover(hash, signature) {
   return ethers.recoverAddress(hash, signature);
 }
-function verifyPaymentReceipt(receipt, recover = defaultRecover) {
-  const { delegate, signHash: signHash2, signature } = receipt.authorization;
-  if (!signature) return { verified: false, reason: "missing_signature" };
+var NOT_A_SIGNED_RECEIPT = { verified: false, reason: "not_a_signed_receipt" };
+function match(delegate, hash, signature, recover) {
   let recovered;
   try {
-    recovered = recover(signHash2, signature);
+    recovered = recover(hash, signature);
   } catch {
-    return { verified: false, reason: "bad_signature" };
+    return { ok: false, reason: "bad_signature" };
   }
   if (recovered.toLowerCase() !== delegate.toLowerCase()) {
-    return { verified: false, reason: "signer_mismatch", recoveredSigner: recovered };
+    return { ok: false, reason: "signer_mismatch", recoveredSigner: recovered };
+  }
+  return { ok: true, recoveredSigner: recovered };
+}
+function finish(result, verifiedOver) {
+  if (result.ok) {
+    return { verified: true, recoveredSigner: result.recoveredSigner, verifiedOver };
   }
-  return { verified: true, recoveredSigner: recovered };
+  return result.recoveredSigner !== void 0 ? { verified: false, reason: result.reason, recoveredSigner: result.recoveredSigner } : { verified: false, reason: result.reason };
+}
+function verifyPaymentReceipt(receipt, recover = defaultRecover) {
+  if (typeof receipt !== "object" || receipt === null) return NOT_A_SIGNED_RECEIPT;
+  const source = receipt;
+  if (typeof source.authorization !== "object" || source.authorization === null) {
+    return NOT_A_SIGNED_RECEIPT;
+  }
+  const auth = source.authorization;
+  const { delegate, signHash: signHash2, signature, signatureScheme } = auth;
+  if (typeof delegate !== "string" || delegate === "" || typeof signHash2 !== "string" || signHash2 === "") {
+    return NOT_A_SIGNED_RECEIPT;
+  }
+  if (typeof signature !== "string" || signature === "") {
+    return { verified: false, reason: "missing_signature" };
+  }
+  const chainId = typeof source.onChain?.chainId === "number" ? source.onChain.chainId : void 0;
+  const digestVerifiable = chainId !== void 0 && DELEGATION_MANAGER_CHAIN_IDS.has(chainId);
+  if (signatureScheme === "eip712_userop") {
+    return { verified: false, reason: "not_verifiable_offline" };
+  }
+  if (signatureScheme === "eip712_delegation") {
+    if (!digestVerifiable) {
+      return { verified: false, reason: "not_verifiable_offline" };
+    }
+    let digest;
+    try {
+      digest = delegationDigest(signHash2, chainId);
+    } catch {
+      return { verified: false, reason: "bad_signature" };
+    }
+    return finish(match(delegate, digest, signature, recover), "delegation_digest");
+  }
+  const raw = match(delegate, signHash2, signature, recover);
+  if (raw.ok) return finish(raw, "sign_hash");
+  if (digestVerifiable) {
+    let digest;
+    try {
+      digest = delegationDigest(signHash2, chainId);
+    } catch {
+      return finish(raw, "sign_hash");
+    }
+    const delegated = match(delegate, digest, signature, recover);
+    if (delegated.ok) return finish(delegated, "delegation_digest");
+  }
+  return finish(raw, "sign_hash");
 }
 
 // src/account-reads.ts
@@ -883,6 +964,54 @@ function formatRemainingDisplay(tokenAddress, tokenSymbol, remainingAtomic) {
   const token = resolveTokenFromAddress(tokenAddress);
   return token ? `${formatAtomicAmount(safeBigInt(remainingAtomic), token.decimals)} ${tokenSymbol}` : `${remainingAtomic} ${tokenSymbol} (atomic; unknown decimals)`;
 }
+function formatTokenAmount(atomic, decimals) {
+  const value = safeBigInt(atomic);
+  if (value < 0n) return "0";
+  const digits = value.toString().padStart(decimals + 1, "0");
+  const intPart = digits.slice(0, digits.length - decimals) || "0";
+  const fracPart = digits.slice(digits.length - decimals).replace(/0+$/, "");
+  return fracPart ? `${intPart}.${fracPart}` : intPart;
+}
+function mapTaskBudget(raw) {
+  return {
+    id: raw.id,
+    agentId: raw.agent_id,
+    chainId: raw.chain_id,
+    tokenAddress: raw.token_address,
+    recipientAddress: raw.recipient_address,
+    parentDelegationHash: raw.parent_delegation_hash,
+    delegationHash: raw.delegation_hash,
+    label: raw.label,
+    maxAtomic: raw.max_atomic,
+    status: raw.status,
+    expiresAt: raw.expires_at,
+    isExpired: raw.is_expired,
+    createdAt: raw.created_at,
+    openedAt: raw.opened_at,
+    closedAt: raw.closed_at,
+    closeTxHash: raw.close_tx_hash
+  };
+}
+function summarizeTaskBudget(taskBudget) {
+  const token = resolveTokenFromAddress(taskBudget.tokenAddress);
+  const maxDisplay = token ? `${formatAtomicAmount(safeBigInt(taskBudget.maxAtomic), token.decimals)} ${token.symbol}` : `${taskBudget.maxAtomic} (atomic; unknown decimals)`;
+  return {
+    id: taskBudget.id,
+    label: taskBudget.label,
+    tokenAddress: taskBudget.tokenAddress,
+    maxAtomic: taskBudget.maxAtomic,
+    maxDisplay,
+    recipientAddress: taskBudget.recipientAddress,
+    expiresAt: taskBudget.expiresAt
+  };
+}
+function compactReceipt(receipt) {
+  const row = { ...receipt };
+  delete row.challengePayload;
+  delete row.selectedPayment;
+  delete row.protocolReceiptPayload;
+  return row;
+}
 var AccountReads = class {
   transport;
   getPaymentStatus;
@@ -902,7 +1031,11 @@ var AccountReads = class {
     return request;
   }
   async getAgentSummary() {
-    const [agent, allowanceSummary] = await Promise.all([this.getAgent(), this.getAllowances()]);
+    const [agent, allowanceSummary, taskBudgets] = await Promise.all([
+      this.getAgent(),
+      this.getAllowances(),
+      this.listOpenTaskBudgetsSummary()
+    ]);
     const allowances = allowanceSummary.allowances.map((allowance) => {
       return {
         id: allowance.id,
@@ -916,7 +1049,30 @@ var AccountReads = class {
       };
     });
     const readiness = deriveReadiness(agent.status, allowances);
-    return { ...agent, readiness, spend_authority_readiness: readiness, allowances };
+    return { ...agent, readiness, spend_authority_readiness: readiness, allowances, taskBudgets };
+  }
+  /**
+   * #3329: `GET /task-budgets?status=open`, mapped to the condensed summary
+   * row `getAgentSummary()` carries. Fails SOFT per the #3093 rule (default
+   * every array wire key to `[]` so an absent/malformed key degrades instead
+   * of taking the route down): a 404 (a backend that predates #3329's
+   * route), ANY other transport error, an undefined/null body, or a missing
+   * or non-array `task_budgets` key all return `[]` rather than throwing —
+   * `getAgentSummary`'s identity + readiness + allowances fields are what
+   * callers depend on, and this read must never be why the whole summary
+   * fails.
+   */
+  async listOpenTaskBudgetsSummary() {
+    try {
+      const raw = await this.transport.get(
+        "/task-budgets?status=open"
+      );
+      const rows = raw?.task_budgets;
+      if (!Array.isArray(rows)) return [];
+      return rows.map((row) => summarizeTaskBudget(mapTaskBudget(row)));
+    } catch {
+      return [];
+    }
   }
   async getAllowances() {
     const raw = await this.transport.get("/machine-payments/allowances");
@@ -1006,22 +1162,22 @@ var AccountReads = class {
     try {
       const tokenAddress = payment.asset ?? payment.x402?.asset ?? null;
       if (!tokenAddress) return unavailable("the settled payment does not carry a resolvable token address", payment);
-      const match = allowanceResult.value.allowances.find(
+      const match2 = allowanceResult.value.allowances.find(
         (allowance) => allowance.tokenAddress.toLowerCase() === tokenAddress.toLowerCase()
       );
-      if (!match) return unavailable("no allowance/budget row matches the settled token", payment);
-      const token = resolveTokenFromAddress(match.tokenAddress);
-      const remainingDisplay = token ? `${formatAtomicAmount(safeBigInt(match.onchain.remaining), token.decimals)} ${match.tokenSymbol}` : void 0;
+      if (!match2) return unavailable("no allowance/budget row matches the settled token", payment);
+      const token = resolveTokenFromAddress(match2.tokenAddress);
+      const remainingDisplay = token ? `${formatAtomicAmount(safeBigInt(match2.onchain.remaining), token.decimals)} ${match2.tokenSymbol}` : void 0;
       const rail = agentResult.value.executionRail;
       return {
         payment,
         allowance: {
           rail,
-          remaining_atomic: match.onchain.remaining,
+          remaining_atomic: match2.onchain.remaining,
           ...remainingDisplay ? { remaining_display: remainingDisplay } : {},
-          token_symbol: match.tokenSymbol,
-          token_address: match.tokenAddress,
-          reset_period: match.resetPeriodMin,
+          token_symbol: match2.tokenSymbol,
+          token_address: match2.tokenAddress,
+          reset_period: match2.resetPeriodMin,
           source: rail === "delegation" ? "active_delegations" : "allowance_module"
         },
         warnings: []
@@ -1041,8 +1197,13 @@ var AccountReads = class {
     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}`);
+    const receipts = raw.receipts.map(mapPaymentReceipt);
     return {
-      receipts: raw.receipts.map(mapPaymentReceipt),
+      // #3423 (owner decision, opt-in): `compact` drops the three bulky
+      // payload echoes (the merchant's full 402 challenge, the selected
+      // option, and the merchant's PAYMENT-RESPONSE) from each row. The keys
+      // are absent, not null, and the default shape is unchanged.
+      receipts: options.compact ? receipts.map(compactReceipt) : receipts,
       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
@@ -1408,6 +1569,10 @@ function readX402ReceiptPayer(raw) {
 }
 
 // src/x402-funding-leg.ts
+function sameX402TaskBudget(a, b) {
+  if (a === void 0 || b === void 0) return a === b;
+  return a.toLowerCase() === b.toLowerCase();
+}
 var X402FundingLeg = class {
   delegateKey;
   delegateAddress;
@@ -1433,20 +1598,35 @@ var X402FundingLeg = class {
     this.assertSignableAuthorizationState = options.assertSignableAuthorizationState;
   }
   // ── Receipt cache ────────────────────────────────────────────────
-  /** A still-valid cached receipt for this key, or undefined. */
-  cachedReceipt(idempotencyKey) {
+  /**
+   * #3392: each cached receipt records the authorizing budget id(s) it was
+   * created under (absent when none) — `taskBudgetId` since #3329, and since
+   * #3330 `subBudgetId` (agent B's grant). A call naming a DIFFERENT
+   * combination is refused here — before any network call — instead of
+   * silently returning a receipt paid under another budget. Absent-vs-absent
+   * and equal ids (case-insensitive) hit as before.
+   */
+  cachedReceipt(idempotencyKey, taskBudgetId, subBudgetId) {
     const cached = this.receiptCache.get(idempotencyKey);
-    if (cached && cached.expiresAt > Date.now()) return cached.receipt;
-    return void 0;
+    if (!cached || cached.expiresAt <= Date.now()) return void 0;
+    if (!sameX402TaskBudget(cached.taskBudgetId, taskBudgetId) || !sameX402TaskBudget(cached.subBudgetId, subBudgetId)) {
+      throw new X402TaskBudgetMismatchError(
+        `The x402 idempotency key '${idempotencyKey}' was already used under a different authorizing budget (task '${cached.taskBudgetId ?? "none"}' vs '${taskBudgetId ?? "none"}', sub '${cached.subBudgetId ?? "none"}' vs '${subBudgetId ?? "none"}'). Pass a new idempotencyKey to pay under this budget.`,
+        idempotencyKey,
+        cached.taskBudgetId,
+        taskBudgetId
+      );
+    }
+    return cached.receipt;
   }
-  cacheReceipt(idempotencyKey, paymentHeader, receipt) {
+  cacheReceipt(idempotencyKey, paymentHeader, receipt, taskBudgetId, subBudgetId) {
     const expiresAt = getPaymentHeaderValidBefore(paymentHeader);
     if (expiresAt > Date.now()) {
-      this.receiptCache.set(idempotencyKey, { expiresAt, receipt });
+      this.receiptCache.set(idempotencyKey, { expiresAt, taskBudgetId, subBudgetId, receipt });
     }
   }
   // ── Authorization ────────────────────────────────────────────────
-  async authorize(paymentRequired, option, idempotencyKey) {
+  async authorize(paymentRequired, option, idempotencyKey, taskBudgetId, subBudgetId) {
     const raw = await this.post("/x402", {
       url: paymentRequired.resource.url,
       payTo: this.delegateAddress,
@@ -1459,7 +1639,15 @@ var X402FundingLeg = class {
       // #1360: same explicit funding-leg declaration as createX402Intent —
       // this local-key path derives payTo from the key (never stale), but the
       // declaration keeps both writers of the 3009 shape loud-by-default.
-      settlementScheme: "eip3009"
+      settlementScheme: "eip3009",
+      // #3329: `/x402` bodies are camelCase (`X402AuthorizeRequest`) — do not
+      // switch this to `task_budget_id`, which is only the `POST /payments` key.
+      ...taskBudgetId ? { taskBudgetId } : {},
+      // #3330: same camelCase channel one level deeper — agent B pays through
+      // the sub-budget agent A granted it (`[funding, B grant, A parent-child,
+      // A budget]`). Mutually exclusive with `taskBudgetId` server-side; the
+      // backend refuses a body naming both.
+      ...subBudgetId ? { subBudgetId } : {}
     });
     const state = paymentStateFromRaw("x402 payment", raw);
     const executedReplay = raw.success && raw.tx_hash ? "idempotency-collision" : state?.nextAction === AgentPaymentNextAction.RetryOriginalX402Request ? "approval-resume" : null;
@@ -1482,19 +1670,22 @@ var X402FundingLeg = class {
     const paymentHeader = await this.createPaymentHeader(paymentRequired, option);
     if (raw.success && raw.tx_hash) {
       const receipt2 = this.receiptFromAuthorization(paymentRequired, option, paymentHeader, raw);
-      this.cacheReceipt(idempotencyKey, paymentHeader, receipt2);
+      this.cacheReceipt(idempotencyKey, paymentHeader, receipt2, taskBudgetId, subBudgetId);
       return receipt2;
     }
     if (state?.nextAction === AgentPaymentNextAction.RetryOriginalX402Request) {
       const receipt2 = this.receiptFromStatus(paymentRequired, option, paymentHeader, state);
-      this.cacheReceipt(idempotencyKey, paymentHeader, receipt2);
+      this.cacheReceipt(idempotencyKey, paymentHeader, receipt2, taskBudgetId, subBudgetId);
       return receipt2;
     }
     this.assertSignableAuthorizationState("x402 payment", raw);
     if (!raw.sign_data?.hash) {
       throw new HavenApiError("No sign_hash returned from x402/authorize", 500, raw);
     }
-    const sig = await this.signForData(raw.sign_data);
+    const sig = await this.signForData(raw.sign_data, {
+      asset: option.asset,
+      amount: x402AuthorizationAmount(option)
+    });
     const execResult = await this.post(
       `/payments/${raw.payment_id}/sign`,
       { signature: sig }
@@ -1507,7 +1698,7 @@ var X402FundingLeg = class {
       execResult.chain_id ?? chainIdFromNetwork(option.network)
     );
     const receipt = this.receiptFromAuthorization(paymentRequired, option, paymentHeader, raw, execResult);
-    this.cacheReceipt(idempotencyKey, paymentHeader, receipt);
+    this.cacheReceipt(idempotencyKey, paymentHeader, receipt, taskBudgetId, subBudgetId);
     return receipt;
   }
   // ── Header minting ───────────────────────────────────────────────
@@ -1770,11 +1961,30 @@ var X402Erc7710 = class {
       ...selection.facilitatorAddresses ? { facilitatorAddresses: selection.facilitatorAddresses } : {},
       // #1307/#1547: persisted so the settle leg can rehydrate the merchant
       // call by payment_id on this scheme too, not only on the 3009 bridge.
-      ...options.mcpCallContext ? { mcpCallContext: options.mcpCallContext } : {}
+      ...options.mcpCallContext ? { mcpCallContext: options.mcpCallContext } : {},
+      // #3329: `/x402` bodies are camelCase (`X402AuthorizeRequest`) — do not
+      // switch this to `task_budget_id`, which is only the `POST /payments` key.
+      ...options.taskBudgetId ? { taskBudgetId: options.taskBudgetId } : {},
+      // #3330: same camelCase channel one level deeper; mutually exclusive
+      // with `taskBudgetId` server-side.
+      ...options.subBudgetId ? { subBudgetId: options.subBudgetId } : {}
     });
     if (!raw.payment_id) {
       throw new HavenApiError("No payment_id returned from x402/authorize", 500, raw);
     }
+    if (raw.status === "confirmed" && raw.tx_hash) {
+      const requestedUrl = options.resourceUrl ?? paymentRequired.resource?.url;
+      const samePurchase = typeof raw.to === "string" && raw.to.toLowerCase() === merchantPayTo.toLowerCase() && raw.resource_url === requestedUrl;
+      if (!samePurchase) {
+        throw new HavenApiError(
+          `Idempotency key already belongs to confirmed payment ${raw.payment_id}, which is not this erc7710 purchase (different payee or resource). Nothing was signed and nothing was charged. Check that payment's status before buying again: a funded but undelivered EIP-3009 payment is recovered, not paid twice. Otherwise use a new idempotency key for this purchase.`,
+          409,
+          raw,
+          raw.payment_id
+        );
+      }
+      throw new X402Erc7710AlreadySettledError(raw.payment_id, raw.tx_hash, raw);
+    }
     const signData = raw.sign_data;
     if (signData?.signature_scheme !== "eip712_delegation" || !signData.typed_data) {
       throw new HavenApiError(
@@ -1805,10 +2015,20 @@ var X402Erc7710 = class {
    * hosted boundary) is irrelevant here.
    */
   async submit(paymentId, signature) {
-    const settled = await this.post(
-      `/x402/${paymentId}/settle`,
-      { signature }
-    );
+    let settled;
+    try {
+      settled = await this.post(`/x402/${paymentId}/settle`, { signature });
+    } catch (err) {
+      const body = err instanceof HavenApiError ? err.body : void 0;
+      if (err instanceof HavenApiError && err.statusCode === 409 && body?.code === "payment_already_settled" && typeof body.tx_hash === "string") {
+        throw new X402Erc7710AlreadySettledError(
+          typeof body.payment_id === "string" ? body.payment_id : paymentId,
+          body.tx_hash,
+          body
+        );
+      }
+      throw err;
+    }
     if (!settled.payment_header) {
       throw new HavenApiError(
         "x402 settle returned no payment_header \u2014 the merchant cannot be retried.",
@@ -2371,6 +2591,15 @@ var HavenClient = class {
   pollingInterval;
   chainRpcs;
   inFlightX402 = /* @__PURE__ */ new Map();
+  /**
+   * #3392: the task budget each in-flight x402 entry was created under
+   * (`undefined` = none). A call joining an in-flight entry under a
+   * different budget is refused before any network call — never silently
+   * charged to another budget's payment.
+   */
+  inFlightX402TaskBudget = /* @__PURE__ */ new Map();
+  /** #3330: the sub-budget each in-flight entry was created under, same pin as `inFlightX402TaskBudget`. */
+  inFlightX402SubBudget = /* @__PURE__ */ new Map();
   /**
    * The EIP-3009 funding-leg lifecycle (#1618). The facade holds a reference
    * and delegates; it does not reimplement any of it.
@@ -2416,7 +2645,7 @@ var HavenClient = class {
       x402Wallet: this.x402Wallet,
       chainRpcs: this.chainRpcs,
       post: (path, body) => this.post(path, body),
-      signForData: (signData) => this.signForData(signData),
+      signForData: (signData, fundingExpectation) => this.signForData(signData, void 0, fundingExpectation),
       assertSignableAuthorizationState: (label, raw) => this.throwIfNonSignableAuthorizationState(label, raw)
     });
     this.merchantCompletion = new MerchantCompletion({
@@ -2493,7 +2722,11 @@ var HavenClient = class {
       token: request.token,
       amount: request.amount,
       to: request.to,
-      ...request.idempotencyKey ? { idempotency_key: request.idempotencyKey } : {}
+      ...request.idempotencyKey ? { idempotency_key: request.idempotencyKey } : {},
+      ...request.taskBudgetId ? { task_budget_id: request.taskBudgetId } : {},
+      // #3330: `POST /payments` is snake_case — agent B pays through the
+      // sub-budget A granted it; the backend refuses a body naming both ids.
+      ...request.subBudgetId ? { sub_budget_id: request.subBudgetId } : {}
     });
     if (raw.status === "pending_approval") {
       throwPaymentStateError("Payment", raw);
@@ -2553,7 +2786,14 @@ var HavenClient = class {
       // the agent passes only payment_id. Bounded: the backend rejects >64KB,
       // so an oversized blob is omitted here (signer falls back to the
       // caller-supplied copy) rather than failing the intent.
-      ...new TextEncoder().encode(JSON.stringify(paymentRequired)).length <= 65536 ? { paymentRequired } : {}
+      ...new TextEncoder().encode(JSON.stringify(paymentRequired)).length <= 65536 ? { paymentRequired } : {},
+      // #3329: `/x402` bodies are camelCase (`X402AuthorizeRequest`), unlike
+      // `POST /payments`'s snake_case `task_budget_id` above — the two
+      // surfaces use different conventions, so this key is NOT `task_budget_id`.
+      ...options.taskBudgetId ? { taskBudgetId: options.taskBudgetId } : {},
+      // #3330: same camelCase channel one level deeper (`X402AuthorizeRequest`);
+      // mutually exclusive with `taskBudgetId` server-side.
+      ...options.subBudgetId ? { subBudgetId: options.subBudgetId } : {}
     });
     if (raw.status !== "pending_signature") {
       throwPaymentStateError("x402 payment", raw);
@@ -2625,7 +2865,7 @@ var HavenClient = class {
    * (#834) — the backend refuses those intents with HTTP 410 before any
    * sign_data reaches a client, so encountering it here is a hard error too.
    */
-  async signForData(signData, settlementExpectation) {
+  async signForData(signData, settlementExpectation, fundingExpectation) {
     if (!this.delegateKey) {
       throw new HavenSigningError(
         "Cannot sign without a delegateKey. Pass the private key in HavenClient config, or sign externally."
@@ -2648,6 +2888,13 @@ var HavenClient = class {
         signData.typed_data,
         this.delegateAddress
       );
+      if (fundingExpectation) {
+        assertFundingLegPaysDelegate(signData.typed_data, {
+          delegateAddress: this.delegateAddress,
+          asset: fundingExpectation.asset,
+          amount: fundingExpectation.amount
+        });
+      }
       return signUserOpTypedDataForDelegation(this.delegateKey, signData.typed_data);
     }
     if (scheme === "eip712_delegation") {
@@ -2926,7 +3173,12 @@ var HavenClient = class {
   async listReceipts(options = {}) {
     return this.accountReads.listReceipts(options);
   }
-  /** #3128: one page of receipts with `total`, `hasMore` and `nextCursor`. */
+  /**
+   * One page of receipts with `total`, `hasMore` and `nextCursor` (#3128).
+   * `compact: true` (#3423) drops each row's
+   * `challengePayload`, `selectedPayment` and `protocolReceiptPayload`; the
+   * default shape is unchanged.
+   */
   async listReceiptsPage(options = {}) {
     return this.accountReads.listReceiptsPage(options);
   }
@@ -2939,6 +3191,96 @@ var HavenClient = class {
   async getReceipt(paymentId) {
     return this.accountReads.getReceipt(paymentId);
   }
+  // ── Task Budgets (#3329) ────────────────────────────────────────────
+  /**
+   * Open a task budget: a self-delegated, time-boxed slice of the agent's own
+   * budget delegation. Returns the pending row plus the child delegation's
+   * `sign_data` — sign it (via `signForData` / `haven_sign` with
+   * `task_budget_id`) and pass the signature to `submitTaskBudget` to make it
+   * OPEN. Nothing is on-chain until then.
+   */
+  async openTaskBudget(request) {
+    const raw = await this.post("/task-budgets", {
+      ...request.tokenAddress ? { token_address: request.tokenAddress } : {},
+      max_amount_atomic: request.maxAmountAtomic,
+      ttl_seconds: request.ttlSeconds,
+      ...request.recipientAddress ? { recipient_address: request.recipientAddress } : {},
+      ...request.label ? { label: request.label } : {}
+    });
+    return {
+      taskBudget: mapTaskBudget(raw.task_budget),
+      signData: raw.sign_data,
+      nextAction: raw.next_action,
+      instructions: raw.instructions
+    };
+  }
+  /** Read one task budget by id. */
+  async getTaskBudget(id) {
+    const raw = await this.get(`/task-budgets/${encodeURIComponent(id)}`);
+    return mapTaskBudget(raw.task_budget);
+  }
+  /** List this agent's task budgets — `status: 'open'` (default; unexpired only) or `'all'`. */
+  async listTaskBudgets(options = {}) {
+    const query = options.status ? `?status=${encodeURIComponent(options.status)}` : "";
+    const raw = await this.get(`/task-budgets${query}`);
+    return raw.task_budgets.map(mapTaskBudget);
+  }
+  /**
+   * The exact signing payload for a pending (purpose `open`) or closing
+   * (purpose `close`) task budget — the `task_budget_id` counterpart of
+   * `getResumeState` / the payment sign-context reads. `haven_sign` with
+   * `task_budget_id` fetches this itself; call it directly only for manual
+   * signing.
+   */
+  async getTaskBudgetSignContext(id) {
+    const raw = await this.get(`/task-budgets/${encodeURIComponent(id)}/sign-context`);
+    if (raw.purpose === "close") {
+      return {
+        taskBudgetId: raw.task_budget_id,
+        purpose: "close",
+        taskSignContextVersion: raw.task_sign_context_version,
+        typedData: raw.typed_data,
+        userOperation: raw.user_operation,
+        userOpHash: raw.user_op_hash,
+        expected: raw.expected
+      };
+    }
+    return {
+      taskBudgetId: raw.task_budget_id,
+      purpose: "open",
+      taskSignContextVersion: raw.task_sign_context_version,
+      typedData: raw.typed_data,
+      expected: raw.expected
+    };
+  }
+  /** Submit a signature for a pending (open) or closing task budget. */
+  async submitTaskBudget(id, signature) {
+    const raw = await this.post(
+      `/task-budgets/${encodeURIComponent(id)}/submit`,
+      { signature }
+    );
+    return {
+      taskBudget: mapTaskBudget(raw.task_budget),
+      status: raw.status,
+      ...raw.close_tx_hash ? { closeTxHash: raw.close_tx_hash } : {}
+    };
+  }
+  /**
+   * Close a task budget early. A `pending` or already-expired `open` budget
+   * closes immediately (nothing was ever signed or is on-chain). A live
+   * `open` budget returns `sign_data` for an on-chain `disableDelegation`
+   * UserOp — sign it (`haven_sign` with `task_budget_id`) and call
+   * `submitTaskBudget`.
+   */
+  async closeTaskBudget(id) {
+    const raw = await this.post(`/task-budgets/${encodeURIComponent(id)}/close`, {});
+    return {
+      taskBudget: mapTaskBudget(raw.task_budget),
+      status: raw.status,
+      ...raw.sign_data ? { signData: raw.sign_data } : {},
+      ...raw.next_action ? { nextAction: raw.next_action } : {}
+    };
+  }
   /**
    * Rehydrate the x402 resume-state bundle for a payment id (#1328: the MPP
    * resume-state variant retired along with the rest of the mpp_demo surface).
@@ -2987,12 +3329,30 @@ var HavenClient = class {
       throw noCompatiblePaymentOptionError(paymentRequired.accepts);
     }
     const idempotencyKey = options.idempotencyKey ?? buildX402IdempotencyKey(paymentRequired, option);
-    const cached = this.fundingLeg.cachedReceipt(idempotencyKey);
+    const cached = this.fundingLeg.cachedReceipt(idempotencyKey, options.taskBudgetId, options.subBudgetId);
     if (cached) return cached;
     const inFlight = this.inFlightX402.get(idempotencyKey);
-    if (inFlight) return inFlight;
-    const promise = this.fundingLeg.authorize(paymentRequired, option, idempotencyKey);
+    if (inFlight) {
+      if (!sameX402TaskBudget(this.inFlightX402TaskBudget.get(idempotencyKey), options.taskBudgetId) || !sameX402TaskBudget(this.inFlightX402SubBudget.get(idempotencyKey), options.subBudgetId)) {
+        throw new X402TaskBudgetMismatchError(
+          `The x402 idempotency key '${idempotencyKey}' has an in-flight payment created under a different authorizing budget (task '${this.inFlightX402TaskBudget.get(idempotencyKey) ?? "none"}' vs '${options.taskBudgetId ?? "none"}', sub '${this.inFlightX402SubBudget.get(idempotencyKey) ?? "none"}' vs '${options.subBudgetId ?? "none"}'). Pass a new idempotencyKey to pay under this budget.`,
+          idempotencyKey,
+          this.inFlightX402TaskBudget.get(idempotencyKey),
+          options.taskBudgetId
+        );
+      }
+      return inFlight;
+    }
+    const promise = this.fundingLeg.authorize(
+      paymentRequired,
+      option,
+      idempotencyKey,
+      options.taskBudgetId,
+      options.subBudgetId
+    );
     this.inFlightX402.set(idempotencyKey, promise);
+    this.inFlightX402TaskBudget.set(idempotencyKey, options.taskBudgetId);
+    this.inFlightX402SubBudget.set(idempotencyKey, options.subBudgetId);
     try {
       return await promise;
     } catch (err) {
@@ -3004,6 +3364,8 @@ var HavenClient = class {
       throw err;
     } finally {
       this.inFlightX402.delete(idempotencyKey);
+      this.inFlightX402TaskBudget.delete(idempotencyKey);
+      this.inFlightX402SubBudget.delete(idempotencyKey);
     }
   }
   /**
@@ -3073,7 +3435,7 @@ var HavenClient = class {
   async payX402Quote(quote, options = {}) {
     const idempotencyKey = options.idempotencyKey ?? quote.idempotencyKey;
     try {
-      const receipt = await this.authorizeX402(quote.paymentRequired, { idempotencyKey });
+      const receipt = await this.authorizeX402(quote.paymentRequired, { ...options, idempotencyKey });
       return this.merchantCompletion.retryRequest(
         quote.request.url,
         requestInitFromSnapshot(quote.request),
@@ -3139,7 +3501,7 @@ var HavenClient = class {
       throw noCompatiblePaymentOptionError(input.paymentRequired.accepts);
     }
     const idempotencyKey = input.idempotencyKey ?? buildX402IdempotencyKey(input.paymentRequired, option);
-    const cached = this.fundingLeg.cachedReceipt(idempotencyKey);
+    const cached = this.fundingLeg.cachedReceipt(idempotencyKey, input.taskBudgetId);
     if (cached) return cached;
     const status = await this.getPaymentStatus(input.paymentId);
     assertCanResumeX402(status, input.paymentRequired, option);
@@ -3157,7 +3519,7 @@ var HavenClient = class {
     }
     const paymentHeader = await this.fundingLeg.createPaymentHeader(input.paymentRequired, option);
     const receipt = this.fundingLeg.receiptFromStatus(input.paymentRequired, option, paymentHeader, status);
-    this.fundingLeg.cacheReceipt(idempotencyKey, paymentHeader, receipt);
+    this.fundingLeg.cacheReceipt(idempotencyKey, paymentHeader, receipt, input.taskBudgetId);
     return receipt;
   }
   async resumeX402Payment(input) {
@@ -3584,7 +3946,7 @@ var toolDescriptions = {
   // deleted `/demo/mpp/*` route. Use the x402 fragments above instead.
   getPaymentStatus: {
     summary: "Fetch structured Haven payment status for agent recovery.",
-    behavior: "State: phase, nextAction, rail, amount, merchant, resource, idempotency, message; parties: treasury/delegate/delegateAccount/merchant. awaiting_settlement_evidence: poll once, else unverified.",
+    behavior: "State: phase, nextAction, rail, amount, merchant, resource, idempotency, message; delivered when the merchant answered; parties: treasury/delegate/delegateAccount/merchant. awaiting_settlement_evidence: poll once, else unverified. delivered_unverified: terminal, stop.",
     nextActionGuidance: ""
   },
   getResumeState: {
@@ -3619,9 +3981,9 @@ var toolDescriptions = {
     nextActionGuidance: ""
   },
   verifyReceipt: {
-    summary: "Verify a payment receipt offline \u2014 confirm the agent authorised the transfer.",
-    selectionGuidance: "Use this to check a receipt you already hold; it needs no network and does not trust Haven. Use the history tool to fetch receipts in the first place.",
-    behavior: "Recovers the signer from the receipt authorisation and confirms it matches the agent delegate. Returns verified true/false with the recovered signer or a reason. Pure and local \u2014 no backend call.",
+    summary: "Verify a signed payment receipt offline \u2014 confirm the agent delegate signed its authorisation.",
+    selectionGuidance: "Takes the signed bundle from GET /payments/{id}/receipt, not a haven_list_receipts row \u2014 a row carries no signature and returns not_a_signed_receipt. No network.",
+    behavior: "Never throws. An erc7710 bundle verifies over the delegation digest the delegate signed; a direct or eip3009 bundle returns not_verifiable_offline. verified true means only that the delegate signed the hash named by verifiedOver \u2014 payment facts are Haven-asserted and settlement is not proven; check settlementTxHash on an explorer.",
     nextActionGuidance: ""
   },
   payMcpTool: {
@@ -3651,7 +4013,7 @@ var toolDescriptions = {
   send: {
     summary: "Send ETH or USDC directly from the agent's Haven wallet to a recipient address.",
     selectionGuidance: "Use this for plain transfers \u2014 refunding a user, paying a freelancer, topping up a co-agent's wallet, or moving funds between addresses. Do NOT use for x402 paid endpoints \u2014 use haven_pay_x402 instead. Do NOT use for read-only allowance, budget, or what-can-I-spend questions \u2014 use haven_get_allowances. Do NOT use to check whether funds are held before sending \u2014 use haven_check_funds.",
-    behavior: "Sends the 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 or any signing \u2014 never queued for a human to approve. The agent's signing key signs the account's typed data, refusing any that mismatches the payment's hash; Haven never receives the key.",
+    behavior: "Sends the 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 or any signing \u2014 never queued for a human to approve. The agent's signing key signs the account's typed data; a current signer refuses any that does not match the payment's hash (USEROP_BINDING_MISMATCH), an older signer signs it and the account rejects it on-chain. Haven never receives the key.",
     nextActionGuidance: "On a decline, report the reason to the user and ask them to grant or raise the budget in Haven \u2014 there is nothing to poll and no approval will arrive. After a successful send, poll haven_get_payment_status until nextAction=none."
   },
   reportSettlementEvidence: {
@@ -3908,7 +4270,7 @@ Your user gives you a **budget on their own account** \u2014 not their wallet, a
 
 Four of the six steps are your user's \u2014 each needs a human signature or a human decision. The rest is yours. If they already have a funded account, start at step 3.
 
-1. **HUMAN \u2014 create the account.** Name, email, password, then a passkey (Face ID / Touch ID) or a wallet. Never offer to enter any of it: you must not have their password, and the passkey is bound to their device. With a terminal, \`npx @haven_ai/cli@<channel> login --api <api-url>\` afterwards gets you a scoped session for steps 3-4 (that flag or \`HAVEN_API_URL\`, on the first command \u2014 the session then remembers the backend; **the CLI's built-in default is Haven's hosted production backend**, so on any other deployment an omitted flag connects you somewhere real and wrong rather than failing) \u2014 they approve a code in the browser, you never hold their password. The \`<channel>\` in that command is the tag your deployment names \u2014 read it from \`/.well-known/haven.json\` (\`packages.cli.channel\`), never a tag you pick. Do not hold the process open while you wait: under \`--json\`, pass \`--no-wait\` to get the link object back at once, then poll it with \`haven login --poll <device_code>\` \u2014 one round per invocation, exit 3 while it is still pending, 0 once approved. It can set up agents and read the account; it cannot sign, approve a budget, move funds, or rotate any agent's keys.
+1. **HUMAN \u2014 create the account.** Name, email, password, then a passkey (Face ID / Touch ID) or a wallet. Never offer to enter any of it: you must not have their password, and the passkey is bound to their device. With a terminal, \`<packages.cli.one_liner> login --api <api-url>\` afterwards gets you a scoped session for steps 3-4 (that flag or \`HAVEN_API_URL\`, on the first command \u2014 the session then remembers the backend; **the CLI's built-in default is Haven's hosted production backend**, so on any other deployment an omitted flag connects you somewhere real and wrong rather than failing) \u2014 they approve a code in the browser, you never hold their password. That command is the manifest's \`packages.cli.one_liner\` (\`/.well-known/haven.json\`) \u2014 run it as given: \`packages.cli.channel\` serves the full spec. Do not hold the process open while you wait: under \`--json\`, pass \`--no-wait\` to get the link object back at once, then poll it with \`haven login --poll <device_code>\` \u2014 one round per invocation, exit 3 while it is still pending, 0 once approved. It can set up agents and read the account; it cannot sign, approve a budget, move funds, or rotate any agent's keys.
 2. **HUMAN \u2014 fund it.** USDC only, no ETH: Haven sponsors the gas. \`/.well-known/haven.json\` names \`chains.default\` as the deployment's expected chain, but after login \`haven wallets funding\` prints the address, the amount and which chain in one place; confirm that chain before you message your user. Without a CLI session, the dashboard's funding card shows the address and amount and its Receive-funds screen names the chain; never assume one: a testnet deployment and production both call themselves Haven. Before you write that message, read the manifest: \`environment\` says whether this deployment is \`production\`, and each \`chains.supported\` entry says whether that chain is a \`testnet\`. Real money is at stake only on a non-testnet chain of a \`production\` deployment \u2014 tell your user which case theirs is.
 3. **HUMAN \u2014 create the agent, set its budget**, and paste you the **setup prompt** it hands back. With a CLI session (step 1) you can do this step yourself: \`haven agents connect --name <n> --budget <amount> --token USDC --period <minutes>\` prints the same connector command and approval link; add \`--run\` to do step 4 too.
 4. **YOU \u2014 run the connector command** in that prompt (below). It makes your signing key locally, registering only the public address.
@@ -3984,6 +4346,10 @@ Call \`haven_get_agent\`, one of the Haven MCP tools the connector wires into yo
 
 Nothing here needs you to. Steps 1-3 are links: hand your user the full \`<host>/\u2026\` URL and ask them to say when it is done. Step 5 is a link only when your run reported one in \`approval.url\` \u2014 otherwise it is the tab they already have open, as above. Then poll \`haven_get_agent\` until it reads \`ready\`. Do not route around the sign-in wall \u2014 it makes the account theirs, not yours.
 
+## If something breaks
+
+If a Haven result carries \`client_update\`, that client is out of date: run its \`upgrade_command\` as given, then any repair line it prints, then retry. \`required: true\` means payments are refused until you do. What changed: [/releases](/releases).
+
 ## Vocabulary
 
 | Term | What it is |
@@ -4002,12 +4368,12 @@ Start by reading {{HAVEN_ORIGIN}}/for-agents.md \u2014 it is written for you and
 
 Then:
 
-1. Run \`npx @haven_ai/cli@<channel> login\`. The \`<channel>\` in that command is the tag your deployment names \u2014 read it from \`/.well-known/haven.json\` (\`packages.cli.channel\`), never a tag you pick. It prints a link and a code and does not need my password \u2014 it must never ask for it. Give me the link straight away and wait for me to approve it in my browser.
+1. Run \`<packages.cli.one_liner> login\`. That command is the manifest's \`packages.cli.one_liner\` (\`/.well-known/haven.json\`) \u2014 run it as given: \`packages.cli.channel\` serves the full spec. It prints a link and a code and does not need my password \u2014 it must never ask for it. Give me the link straight away and wait for me to approve it in my browser.
 2. Once I have approved, run \`haven agents connect --name <a name you choose> --budget <amount> --token USDC --period <minutes>\` with the budget I tell you. If I have not given you one, ask me before running it. Add \`--run\` to complete the connection in the same step.
 3. ${AGENT_APPROVAL_RELAY_JSON_SENTENCE}
 4. Once I have approved the budget, verify with the \`haven_get_agent\` tool: \`ready\` means you can pay, \`needs_approval\` means my approval has not landed yet.
 
-Two things only I can do: approving that budget with my passkey, and funding the account with USDC on Base \u2014 no ETH, Haven sponsors the gas. Tell me if either is missing rather than working around it.
+Two things only I can do: approving that budget with my passkey, and funding the account with USDC \u2014 no ETH, Haven sponsors the gas. Tell me if either is missing rather than working around it.
 
 ${AGENT_SECRET_HYGIENE_SENTENCE}`;
 
@@ -4151,28 +4517,43 @@ the budget in the Haven dashboard, or wait for the period reset.
 4. Then FOLLOW THE RESPONSE'S GUIDANCE FIELDS: \`next_action\`, \`next_tool\`,
    and \`next_arguments\` name the exact next call \u2014 act on those first; the
    prose in this section is fallback and debugging detail. If the catalog
-   entry is missing or degraded, the response instead names
-   \`mcp__haven__haven_pay_mcp_tool\` (merchant URL, tool name, arguments) as
-   the manual fallback.
+   row is a plain-HTTP x402 paywall (no MCP tool metadata), the response
+   instead names \`mcp__haven__haven_quote_x402\` with the entry's resource
+   URL as \`url\`. If an MCP row is degraded or has no tool name, the response
+   instead names \`mcp__haven__haven_pay_mcp_tool\` (merchant URL, tool name,
+   arguments) as the manual fallback.
 
-**Signing:** \`mcp__haven-signer__haven_sign_x402\` with \`payment_id\` ONLY \u2014
+**Signing:** which signer tool to call depends on the settlement scheme the
+prepare/pay response already named as \`next_tool\` \u2014 follow that field, never
+hard-code a choice. **erc7710** (direct settlement \u2014 chosen per merchant when
+its 402 advertises \`assetTransferMethod: "erc7710"\` AND your account is on
+the delegation rail; never a blanket default): \`mcp__haven-signer__haven_sign\`
+with \`payment_id\` ONLY; the signer fetches the settlement child itself.
+**EIP-3009** (the bridge \u2014 used otherwise, whenever the merchant offers a
+standard entry): \`mcp__haven-signer__haven_sign_x402\` with \`payment_id\` ONLY \u2014
 the local signer fetches the exact signing bytes AND \`payment_required\`
-itself, so never relay \`typed_data\` or the 402 blob yourself. If the signer
-reports its fetched context carried no \`payment_required\` (older backend),
-re-call with \`payment_required\` added verbatim. Fallback for an older signer
-or backend: re-run the quote/prepare tool with the SAME \`idempotency_key\`
-plus \`include_signing_payload=true\`, then pass \`payload_hash\`,
-\`x402_expected\` (the nested \`x402.expected\` object), and
+itself, so never relay \`typed_data\` or the 402 blob yourself. A merchant
+that advertises ONLY erc7710 against an account that is NOT on the
+delegation rail is refused outright \u2014 it does not fall back to EIP-3009. If
+the signer reports its fetched context carried no \`payment_required\` (older
+backend), re-call with \`payment_required\` added verbatim. Fallback for an
+older signer or backend: re-run the quote/prepare tool with the SAME
+\`idempotency_key\` plus \`include_signing_payload=true\`, then pass
+\`payload_hash\`, \`x402_expected\` (the nested \`x402.expected\` object), and
 \`typed_data\`/\`typed_data_b64\` through unchanged.
 
-**Settle:** \`mcp__haven__haven_settle_mcp_tool\` with \`payment_id\`,
-\`signature\`, and \`payment_header\` ONLY \u2014 Haven rehydrates the merchant call
+**Settle:** \`mcp__haven__haven_settle_mcp_tool\` with \`payment_id\` and
+\`signature\` always. On **erc7710**, pass no \`payment_header\` \u2014 Haven
+assembles it at settle, so there is nothing to build locally and no funding
+transaction to wait for. On **EIP-3009**, also pass \`payment_header\` (from
+\`haven_sign_x402\`) ONLY. Either way Haven rehydrates the merchant call
 context (\`merchant_url\`, \`tool_name\`, \`arguments\`, \`mcp_transport\`)
 server-side from \`payment_id\`. Pass those four fields explicitly only as a
 version-skew fallback when Haven has no stored context for the id \u2014 both or
-none together, never just one. If the settle result carries \`settled: false\`,
-funding has not confirmed \u2014 follow the result's guidance fields and check
-status later, do not re-pay.
+none together, never just one. On **EIP-3009**, \`settled: false\` means
+funding has not confirmed; on **erc7710** it means the merchant delivered but
+settlement is not yet verified. Either way, follow the result's guidance
+fields and do not re-pay.
 
 Step-by-step alternative (also key-safe; for an older signer or backend, or
 when you already have a merchant URL and tool name instead of a
@@ -4362,6 +4743,6 @@ function sameUrl(a, b) {
   }
 }
 
-export { AGENT_APPROVAL_RELAY_JSON_SENTENCE, AGENT_APPROVAL_RELAY_PROSE_SENTENCE, AGENT_COMMAND_MODIFICATION_SENTENCE, AGENT_JSON_MODE_SENTENCE, AGENT_LOCAL_KEY_SENTENCE, AGENT_NETWORK_ACCESS_SENTENCE, AGENT_ONBOARDING_PROMPT, AGENT_README_SECTION_MD, AGENT_SECRET_HYGIENE_SENTENCE, AGENT_WIRING_COLLISION_RELAY_SENTENCE, DISCOVERY_MAX_BYTES, HAVEN_AGENT_RUNBOOK_MD, HAVEN_SKILL_BODY_MD, HAVEN_SKILL_MD, HavenClient, HavenInsecureRetryTargetError, INSECURE_RETRY_TARGET_CODE, MERCHANT_DISCOVERY_PATHS, RECEIPT_VERSION, SKILL_FOLDER_NAME, addressFromKey, assertSecureX402RetryTarget, composeDescription, discoverMerchantMcpUrl, havenTools, isSecureX402RetryTarget, isZeroSettlementTxHash, readX402ReceiptPayer, resolveX402RetryTarget, sameUrl, signHash, signUserOpTypedDataForDelegation, toolDescriptions, verifyPaymentReceipt, verifySignature };
+export { AGENT_APPROVAL_RELAY_JSON_SENTENCE, AGENT_APPROVAL_RELAY_PROSE_SENTENCE, AGENT_COMMAND_MODIFICATION_SENTENCE, AGENT_JSON_MODE_SENTENCE, AGENT_LOCAL_KEY_SENTENCE, AGENT_NETWORK_ACCESS_SENTENCE, AGENT_ONBOARDING_PROMPT, AGENT_README_SECTION_MD, AGENT_SECRET_HYGIENE_SENTENCE, AGENT_WIRING_COLLISION_RELAY_SENTENCE, DISCOVERY_MAX_BYTES, HAVEN_AGENT_RUNBOOK_MD, HAVEN_SKILL_BODY_MD, HAVEN_SKILL_MD, HavenClient, HavenInsecureRetryTargetError, INSECURE_RETRY_TARGET_CODE, MERCHANT_DISCOVERY_PATHS, RECEIPT_VERSION, SKILL_FOLDER_NAME, addressFromKey, assertSecureX402RetryTarget, composeDescription, discoverMerchantMcpUrl, formatTokenAmount, havenTools, isSecureX402RetryTarget, isZeroSettlementTxHash, readX402ReceiptPayer, resolveX402RetryTarget, sameUrl, signHash, signUserOpTypedDataForDelegation, toolDescriptions, verifyPaymentReceipt, verifySignature };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map