@haven_ai/sdk 0.11.0-alpha.0 → 0.13.0-alpha.0

package/dist/index.js

@@ -1,9 +1,9 @@
-import { decodeBase64Json, selectStandardPaymentOption, buildX402IdempotencyKey, x402AuthorizationAmount, assertBoundDirectPaymentUserOp, assertFundingLegPaysDelegate, HavenTypedDataRefusedError, assertOwnSettlementChild, parsePaymentRequiredResponse, x402PaymentHeaderNamesSent, SDK_CLIENT_IDENTITY, readClientUpdate, HAVEN_CLIENT_HEADER, isSweepableChain, sweepUsdcAddress, x402PaymentHeaderNamesFor, X402_PAYMENT_HEADER_NAMES, toStandardPaymentRequirements, deriveX402PaymentNonce, encodeBase64Json, x402V2PaymentEnvelope, isErc7710Option, buildSignedTaxDeclaration, encodeTaxDeclarationHeader, selectX402SettlementScheme, selectErc7710PaymentOption, x402AssetTransferMethod, resolveTokenFromAddress, normalizePaymentRequired, X_TAX_DECLARATION_HEADER } from './chunk-ZDJ55LR7.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_NONCE_TAG, 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, deriveX402PaymentNonce, 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, x402PaymentHeaderNamesFor, x402RetryHeadersFor, x402V2PaymentEnvelope } from './chunk-ZDJ55LR7.js';
-import { verifyPaymentReceipt } from './chunk-34YJQFCM.js';
-export { RECEIPT_VERSION, verifyPaymentReceipt } from './chunk-34YJQFCM.js';
-import { HavenSigningError, HavenError, DEFAULT_CONFIRMATION_TIMEOUT_MS, HavenApiError, assertUserOpTypedDataBinding, AgentPaymentRail, AgentPaymentPhase, HavenTimeoutError, X402TaskBudgetMismatchError, X402UnexpectedStatusError, X402AlreadySettledError, MerchantTimeoutError, AgentPaymentWarningCode, AgentPaymentNextAction, HavenPaymentStateError, HavenZeroSettlementHashError, X402Erc7710AlreadySettledError, chainIdForNetwork } from './chunk-I7SL4A6X.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-I7SL4A6X.js';
+import { decodeBase64Json, selectStandardPaymentOption, buildX402IdempotencyKey, x402AuthorizationAmount, assertBoundDirectPaymentUserOp, assertFundingLegPaysDelegate, HavenTypedDataRefusedError, assertOwnSettlementChild, parsePaymentRequiredResponse, x402PaymentHeaderNamesSent, SDK_CLIENT_IDENTITY, readClientUpdate, HAVEN_CLIENT_HEADER, isSweepableChain, sweepUsdcAddress, x402PaymentHeaderNamesFor, X402_PAYMENT_HEADER_NAMES, toStandardPaymentRequirements, deriveX402PaymentNonce, encodeBase64Json, x402V2PaymentEnvelope, isErc7710Option, buildSignedTaxDeclaration, encodeTaxDeclarationHeader, selectX402SettlementScheme, selectErc7710PaymentOption, x402AssetTransferMethod, resolveTokenFromAddress, normalizePaymentRequired, X_TAX_DECLARATION_HEADER } from './chunk-CXQ42FOA.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_NONCE_TAG, 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, deriveX402PaymentNonce, 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, x402PaymentHeaderNamesFor, x402RetryHeadersFor, x402V2PaymentEnvelope } from './chunk-CXQ42FOA.js';
+import { verifyPaymentReceipt } from './chunk-CK6VRIPR.js';
+export { RECEIPT_VERSION, verifyPaymentReceipt } from './chunk-CK6VRIPR.js';
+import { HavenSigningError, HavenError, DEFAULT_CONFIRMATION_TIMEOUT_MS, HavenApiError, assertUserOpTypedDataBinding, AgentPaymentRail, AgentPaymentPhase, HavenTimeoutError, X402TaskBudgetMismatchError, X402UnexpectedStatusError, X402AlreadySettledError, MerchantTimeoutError, AgentPaymentWarningCode, AgentPaymentNextAction, FundingConfirmationUnknownError, FundingRevertedError, HavenPaymentStateError, HavenZeroSettlementHashError, X402Erc7710AlreadySettledError, chainIdForNetwork } from './chunk-MI7LVP56.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, FundingConfirmationUnknownError, FundingRevertedError, 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-MI7LVP56.js';
 import { hashTypedData } from 'viem';
 import { ethers } from 'ethers';
 import { AsyncLocalStorage } from 'async_hooks';
@@ -143,12 +143,16 @@ var HavenApiTransport = class {
       return data;
     } catch (err) {
       if (err instanceof HavenApiError) throw err;
+      const failureCause = { kind: "no_answer", method };
       if (err instanceof Error && err.name === "AbortError") {
-        throw new HavenApiError(`Request to ${path} timed out`, 408);
+        throw new HavenApiError(`Request to ${path} timed out`, 408, void 0, void 0, failureCause);
       }
       throw new HavenApiError(
         `Request to ${path} failed: ${err instanceof Error ? err.message : String(err)}`,
-        0
+        0,
+        void 0,
+        void 0,
+        failureCause
       );
     } finally {
       clearTimeout(timeout);
@@ -282,6 +286,10 @@ function mapPaymentStatusResult(raw) {
     // carried through even when `null` (a real, known answer).
     ...raw.settlement_scheme !== void 0 ? { settlementScheme: raw.settlement_scheme } : {},
     ...raw.merchant_settlement_recorded === true ? { merchantSettlementRecorded: true } : {},
+    // #4530: the recorded transaction itself — absent from the raw payload
+    // (older backend, or nothing recorded) stays absent here, so the field
+    // never claims a hash the backend did not record.
+    ...typeof raw.merchant_settlement_tx_hash === "string" ? { merchantSettlementTxHash: raw.merchant_settlement_tx_hash } : {},
     // #3494: additive, mirrors the backend's own `status === 'failed'` gate —
     // absent from the raw payload (older backend, or any non-failed status)
     // stays absent here.
@@ -354,6 +362,30 @@ function mapPaymentReceipt(raw) {
   if ("approval_request_id" in raw) {
     receipt.approvalRequestId = raw.approval_request_id ?? null;
   }
+  if ("settlement_scheme" in raw) {
+    receipt.settlementScheme = raw.settlement_scheme ?? null;
+  }
+  if ("budget_delegation_hash" in raw) {
+    receipt.budgetDelegationHash = raw.budget_delegation_hash ?? null;
+  }
+  if ("delivery_quality" in raw) {
+    receipt.deliveryQuality = raw.delivery_quality ?? null;
+  }
+  if ("delivery_note" in raw) {
+    receipt.deliveryNote = raw.delivery_note ?? null;
+  }
+  if ("delivery_reported_at" in raw) {
+    receipt.deliveryReportedAt = raw.delivery_reported_at ?? null;
+  }
+  if ("delivery_reference" in raw) {
+    receipt.deliveryReference = raw.delivery_reference ?? null;
+  }
+  if ("purchase_group_id" in raw) {
+    receipt.purchaseGroupId = raw.purchase_group_id ?? null;
+  }
+  if ("parent_payment_id" in raw) {
+    receipt.parentPaymentId = raw.parent_payment_id ?? null;
+  }
   return receipt;
 }
 
@@ -473,7 +505,7 @@ function throwPaymentStateError(label, raw) {
     throw new HavenPaymentStateError(state.message, statusCode, state, raw);
   }
   if (raw.status === "pending_approval") {
-    throw new HavenApiError(
+    throw HavenApiError.deterministic(
       `${label} exceeds the agent's on-chain budget and was declined; no approval is pending and none will arrive (payment_id: ${raw.payment_id}).`,
       statusCode,
       raw
@@ -488,6 +520,7 @@ function throwPaymentStateError(label, raw) {
   }
   const paymentId = raw.payment_id ? ` (payment_id: ${raw.payment_id})` : "";
   const message = raw.error ?? `${label} ${raw.status}${paymentId}`;
+  if (statusCode >= 500) throw HavenApiError.deterministic(message, statusCode, raw);
   throw new HavenApiError(message, statusCode, raw);
 }
 
@@ -1346,6 +1379,17 @@ function deriveReadiness(status, allowances) {
   if (status !== "active") return "revoked";
   return allowances.some((allowance) => safeBigInt(allowance.remainingAtomic) > 0n) ? "ready" : "needs_approval";
 }
+function deriveBudgetRefillsAt(readiness, allowances) {
+  if (readiness !== "needs_approval" || allowances.length === 0) return null;
+  const times = allowances.map((allowance) => allowance.nextRefillAt).filter((at) => at !== null && !Number.isNaN(Date.parse(at)));
+  if (times.length === 0) return null;
+  return times.reduce((earliest, at) => Date.parse(at) < Date.parse(earliest) ? at : earliest);
+}
+function deriveBudgetEndedAt(readiness, allowances, budgetEndedAt) {
+  if (readiness !== "needs_approval" || allowances.length > 0) return null;
+  if (!budgetEndedAt || Number.isNaN(Date.parse(budgetEndedAt))) return null;
+  return budgetEndedAt;
+}
 function formatRemainingDisplay(tokenAddress, tokenSymbol, remainingAtomic) {
   const token = resolveTokenFromAddress(tokenAddress);
   return token ? `${formatAtomicAmount(safeBigInt(remainingAtomic), token.decimals)} ${tokenSymbol}` : `${remainingAtomic} ${tokenSymbol} (atomic; unknown decimals)`;
@@ -1514,11 +1558,23 @@ var AccountReads = class {
         isResetPending: allowance.onchain.isResetPending,
         // #3731: same provenance as the detailed read's field — the compact
         // row is a projection of the same allowance, never a second source.
-        fundsCoverRemaining: allowance.fundsCoverRemaining
+        fundsCoverRemaining: allowance.fundsCoverRemaining,
+        nextRefillAt: allowance.nextRefillAt
       };
     });
     const readiness = deriveReadiness(agent.status, allowances);
-    return { ...agent, readiness, spend_authority_readiness: readiness, allowances, taskBudgets, pendingSubBudgetSignatures };
+    const budgetRefillsAt = deriveBudgetRefillsAt(readiness, allowances);
+    const budgetEndedAt = deriveBudgetEndedAt(readiness, allowances, allowanceSummary.budgetEndedAt);
+    return {
+      ...agent,
+      readiness,
+      spend_authority_readiness: readiness,
+      budgetRefillsAt,
+      budgetEndedAt,
+      allowances,
+      taskBudgets,
+      pendingSubBudgetSignatures
+    };
   }
   /**
    * #3329: `GET /task-budgets?status=open`, mapped to the condensed summary
@@ -1614,6 +1670,9 @@ var AccountReads = class {
       accountAddress: raw.account_address,
       delegateAddress: raw.delegate_address,
       chainId: raw.chain_id,
+      // #4352: a non-empty parseable date → itself; anything else (absent on
+      // an older backend, null when no budget has ended) → null.
+      budgetEndedAt: typeof raw.budget_ended_at === "string" && !Number.isNaN(Date.parse(raw.budget_ended_at)) ? raw.budget_ended_at : null,
       supersededBy: mapSupersession(raw.superseded_by),
       allowances: raw.allowances.map((allowance) => ({
         id: allowance.id,
@@ -1632,6 +1691,9 @@ var AccountReads = class {
         // "unverifiable", not a missing key. The key is absent on the wire
         // when the remaining is 0; that maps to null here too.
         fundsCoverRemaining: allowance.funds_cover_remaining === true || allowance.funds_cover_remaining === false ? allowance.funds_cover_remaining : null,
+        // #4355: a non-empty string → itself; anything else (absent on an
+        // older backend, null when the budget never refills) → null.
+        nextRefillAt: typeof allowance.next_refill_at === "string" && allowance.next_refill_at !== "" ? allowance.next_refill_at : null,
         remainingDisplay: formatRemainingDisplay(allowance.token_address, allowance.token_symbol, allowance.onchain.remaining),
         onchain: {
           amount: allowance.onchain.amount,
@@ -2257,7 +2319,7 @@ var X402FundingLeg = class {
     }
     this.assertSignableAuthorizationState("x402 payment", raw);
     if (!raw.sign_data?.hash) {
-      throw new HavenApiError("No sign_hash returned from x402/authorize", 500, raw);
+      throw HavenApiError.deterministic("No sign_hash returned from x402/authorize", 500, raw);
     }
     const sig = await this.signForData(raw.sign_data, {
       asset: option.asset,
@@ -2379,20 +2441,27 @@ var X402FundingLeg = class {
    * Skipped when `chainRpcs` does not include the chain; in that case Haven's
    * backend has already confirmed on-chain submission and callers accept the
    * small propagation window as a trade-off for not configuring an RPC URL.
+   *
+   * #4470: the two outcomes are typed apart. ethers 6 `waitForTransaction`
+   * REJECTS on its timeout (and on an RPC failure) rather than resolving
+   * null, so that path is `FundingConfirmationUnknownError` — funding may
+   * have moved. A mined receipt with `status !== 1` is `FundingRevertedError`.
    */
   async waitForFundingTx(txHash, chainId, timeoutMs = 3e4) {
     if (!txHash || !chainId) return;
     const rpcUrl = this.chainRpcs[chainId];
     if (!rpcUrl) return;
     const provider = createJsonRpcProvider(rpcUrl);
-    const onChainReceipt = await provider.waitForTransaction(txHash, 1, timeoutMs);
-    if (!onChainReceipt || onChainReceipt.status !== 1) {
-      throw new HavenApiError(
-        "Funding tx did not confirm on-chain within the timeout window.",
-        500,
-        { txHash, chainId }
-      );
+    let onChainReceipt;
+    try {
+      onChainReceipt = await provider.waitForTransaction(txHash, 1, timeoutMs);
+    } catch (err) {
+      throw new FundingConfirmationUnknownError(txHash, chainId, err instanceof Error ? err.message : String(err));
+    }
+    if (!onChainReceipt) {
+      throw new FundingConfirmationUnknownError(txHash, chainId, "no receipt within the timeout window");
     }
+    if (onChainReceipt.status !== 1) throw new FundingRevertedError(txHash, chainId);
   }
   /**
    * Can the delegate EOA still fund an authorization for `amountAtomic`?
@@ -2574,7 +2643,7 @@ var X402Erc7710 = class {
       ...options.subBudgetId ? { subBudgetId: options.subBudgetId } : {}
     });
     if (!raw.payment_id) {
-      throw new HavenApiError("No payment_id returned from x402/authorize", 500, raw);
+      throw HavenApiError.deterministic("No payment_id returned from x402/authorize", 500, raw);
     }
     if (raw.status === "confirmed" && raw.tx_hash) {
       const requestedUrl = options.resourceUrl ?? paymentRequired.resource?.url;
@@ -2591,7 +2660,7 @@ var X402Erc7710 = class {
     }
     const signData = raw.sign_data;
     if (signData?.signature_scheme !== "eip712_delegation" || !signData.typed_data) {
-      throw new HavenApiError(
+      throw HavenApiError.deterministic(
         `x402/authorize did not return an erc7710 settlement child (signature_scheme was ${JSON.stringify(signData?.signature_scheme)}). Refusing to sign a payload this path did not ask for.`,
         500,
         raw
@@ -2634,7 +2703,7 @@ var X402Erc7710 = class {
       throw err;
     }
     if (!settled.payment_header) {
-      throw new HavenApiError(
+      throw HavenApiError.deterministic(
         "x402 settle returned no payment_header \u2014 the merchant cannot be retried.",
         500,
         settled
@@ -2805,10 +2874,10 @@ var MerchantCompletion = class {
   }
   async retryRequest(url, initialInit, paymentRequired, receipt) {
     if (!receipt.accepted) {
-      throw new HavenApiError("No accepted x402 option was recorded for payment retry", 500);
+      throw HavenApiError.deterministic("No accepted x402 option was recorded for payment retry", 500);
     }
     if (!receipt.paymentHeader) {
-      throw new HavenApiError("No x402 payment header was returned for payment retry", 500);
+      throw HavenApiError.deterministic("No x402 payment header was returned for payment retry", 500);
     }
     let retryInit = initialInit;
     if (this.getTaxDeclarationHeader && this.delegateKey) {
@@ -3172,7 +3241,11 @@ var MerchantCompletion = class {
       merchantStatus: input.merchantStatus,
       // #3778: accepted outcomes only — a rejection delivered nothing, so
       // there is no deliverable to point at.
-      ...input.deliveryReference ? { deliveryReference: input.deliveryReference } : {}
+      ...input.deliveryReference ? { deliveryReference: input.deliveryReference } : {},
+      // #4534: the purchase correlation key — accepted outcomes only, for the
+      // same reason: a rejected retry bought nothing to group.
+      ...input.purchaseGroupId ? { purchaseGroupId: input.purchaseGroupId } : {},
+      ...input.merchantResponse ? { merchantResponse: input.merchantResponse } : {}
     });
     return { paymentId: status.paymentId, outcome: "accepted", txHash, resourceUrl, recorded: "evidence" };
   }
@@ -3194,15 +3267,16 @@ var MerchantCompletion = class {
     };
     for (let attempt = 0; ; attempt += 1) {
       const result = await this.postEvidenceOnce(body);
-      if (result.outcome !== "retryable" || attempt >= EVIDENCE_RETRY_DELAYS_MS.length) {
+      if (result.outcome !== "retryable" || result.statusCode !== EVIDENCE_RETRYABLE_STATUS || attempt >= EVIDENCE_RETRY_DELAYS_MS.length) {
         return result;
       }
       await this.sleep(EVIDENCE_RETRY_DELAYS_MS[attempt]);
     }
   }
   /**
-   * ONE evidence attempt — the body of `reportEvidence`'s loop above. A 503
-   * answers `retryable` immediately; the caller decides whether to sleep and
+   * ONE evidence attempt — the body of `reportEvidence`'s loop above. A 503,
+   * or no verdict at all (a non-answer or a 408, #4470), answers `retryable`
+   * immediately; the caller decides whether to sleep and
    * re-attempt (`reportEvidence`, and — #4215 — the local settlement report
    * in `retryRequest`) or hand the outcome to its consumer (#3764 D2, the
    * hosted settlement report).
@@ -3213,7 +3287,8 @@ var MerchantCompletion = class {
       return { outcome: "confirmed" };
     } catch (err) {
       const statusCode = err instanceof HavenApiError ? err.statusCode : void 0;
-      if (statusCode !== EVIDENCE_RETRYABLE_STATUS) {
+      const noVerdict = statusCode === 408 || err instanceof HavenApiError && err.failureCause?.kind === "no_answer";
+      if (statusCode !== EVIDENCE_RETRYABLE_STATUS && !noVerdict) {
         const reason = refusalReasonFromBody(err);
         const errorCode = refusalErrorCodeFromBody(err);
         return {
@@ -3634,7 +3709,7 @@ var HavenClient = class {
     }
     const fundingTo = options.delegateAddress ?? (await this.getAgent()).delegateAddress;
     if (!fundingTo) {
-      throw new HavenApiError("Authenticated agent has no delegate address registered.", 502);
+      throw HavenApiError.deterministic("Authenticated agent has no delegate address registered.", 502);
     }
     const idempotencyKey = options.idempotencyKey ?? buildX402IdempotencyKey(paymentRequired, option);
     const raw = await this.post("/x402", {
@@ -3672,7 +3747,7 @@ var HavenClient = class {
       throwPaymentStateError("x402 payment", raw);
     }
     if (!raw.sign_data?.hash) {
-      throw new HavenApiError("No sign_hash returned from x402/authorize", 500, raw);
+      throw HavenApiError.deterministic("No sign_hash returned from x402/authorize", 500, raw);
     }
     if (raw.sign_data.signature_scheme !== void 0 && !raw.sign_data.typed_data) {
       throw new HavenSigningError(
@@ -3680,7 +3755,7 @@ var HavenClient = class {
       );
     }
     if (!raw.x402_expected_auth) {
-      throw new HavenApiError("No x402 expected-context binding returned from x402/authorize", 500, raw);
+      throw HavenApiError.deterministic("No x402 expected-context binding returned from x402/authorize", 500, raw);
     }
     return {
       paymentId: raw.payment_id,
@@ -3910,6 +3985,12 @@ var HavenClient = class {
    * degrade-to-warning path and the ledger row would still land while the
    * purchase proceeded.
    *
+   * #4458: an agent whose only budget for the token has ENDED is refused the
+   * same way with `error_code: 'delegation_expired'` and `budget_ended_at`
+   * (ISO 8601) — also thrown, also recorded (`source: 'hosted_prepare'`).
+   * The remedy differs: the owner sets a NEW budget, waiting for a period to
+   * reset cannot help.
+   *
    * #3518: without `merchantTo`, an agent whose budgets for the token are all
    * merchant-locked gets 409 `budget_requires_recipient` (thrown, nothing
    * recorded) naming the pins in `budget_recipient_addresses` — repeat the
@@ -3934,12 +4015,13 @@ var HavenClient = class {
   /**
    * Post-purchase allowance/budget summary for a settled payment (#1310).
    *
-   * Reuses the EXACT rail-aware read path {@link getAllowances} / #1306's
-   * catalog-purchase preflight `allowance` block use — `GET
-   * /machine-payments/allowances`, with delegation-rail values coming from
-   * the #1090 `deriveDelegationBudgets`-backed enforcer read, never
+   * Reuses the EXACT rail-aware read path {@link getAllowances} uses —
+   * `GET /machine-payments/allowances`, with delegation-rail values coming
+   * from the #1090 `deriveDelegationBudgets`-backed enforcer read, never
    * `agent_allowances` — so this can never disagree with
-   * {@link getAllowances} for the same fixture. The settled token is
+   * {@link getAllowances} for the same fixture. (#1306's catalog-purchase
+   * preflight read the same path until #3054; it now calls
+   * `POST /machine-payments/budget-precheck` instead.) The settled token is
    * resolved from {@link getPaymentStatus} so callers pass only
    * `paymentId`, never a second haven_get_agent-style round trip.
    *
@@ -4964,7 +5046,7 @@ var toolDescriptions = {
   getAgent: {
     summary: "Return the authenticated agent identity AND its live spend authority in one call: Haven wallet, delegate, chain, raw status, spend_authority_readiness, 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 has spend authority 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. Readiness is AUTHORITY: it says a budget is live, not that the account holds funds. Each allowances[] row carries fundsCoverRemaining: false when the account's balance cannot back that row's whole remaining budget \u2014 a heads-up to mention to the user, not a refusal (budgets above the balance are a normal setup; an owner may top up weekly) \u2014 and null when the coverage read failed or the remaining figure was not read live; the key is absent when the remaining is 0, and rows for one token are compared alone. 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. taskBudgets[] rows carry maxAtomic/maxDisplay plus spentAtomic/remainingAtomic/remainingDisplay \u2014 what the chain still allows that budget \u2014 and remainingIsFromChain: false marks a failed read (figures null, never the full cap); only live rows are listed (closed and expired omitted), each with its status (pending | open | closing) and isExpired, so a closing budget stays visible. pendingSubBudgetSignatures[] lists sub-budget rows awaiting YOUR signature, each with its haven_sign next step. Identity fields: id, name, status, accountAddress, delegateAddress, chainId.`,
+    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. needs_approval with no allowances[] rows and budgetEndedAt set: the budget ENDED on that date \u2014 ask the owner to set a new one, waiting will not help; with no rows and no budgetEndedAt: nothing approved yet; with rows: spent for this period, refilling at budgetRefillsAt (null: it ends first). Readiness is AUTHORITY \u2014 a budget is live, not that funds are held. Each allowances[] row carries fundsCoverRemaining: false when the account's balance cannot back that row's whole remaining budget \u2014 a heads-up to mention, not a refusal (budgets above the balance are normal; an owner may top up weekly) \u2014 and null when the coverage read failed or the remaining was not read live; the key is absent at remaining 0, and rows for one token are compared alone. 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 it 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. allowances[] carries id, tokenAddress, remainingAtomic, remainingDisplay, nextRefillAt per token. taskBudgets[] rows carry maxAtomic/maxDisplay plus spentAtomic/remainingAtomic/remainingDisplay \u2014 what the chain still allows that budget \u2014 and remainingIsFromChain: false marks a failed read (figures null, never the cap); only live rows are listed, each with its status (pending | open | closing) and isExpired. pendingSubBudgetSignatures[] lists sub-budget rows awaiting YOUR signature, with the haven_sign step. Identity fields: id, name, status, accountAddress, delegateAddress, chainId.`,
     nextActionGuidance: ""
   },
   getAllowances: {
@@ -5286,7 +5368,7 @@ You are an AI agent whose user has no Haven account yet, or has one but has not
 
 ## What Haven is, in three sentences
 
-Your user gives you a **budget on their own account** \u2014 not their wallet, and not a key to their funds. The budget is a delegation they sign, enforced on-chain: a payment over it, to the wrong recipient, or past its expiry is refused at execution time, not by a dashboard promise. Haven constructs and relays the payments; you get an agent credential and a signing key made on your machine, and your user can revoke the budget without you and without Haven.
+Your user gives you a **budget on their own account** \u2014 not their wallet, and not a key to their funds. The budget is a delegation they sign, enforced on-chain: a payment over it, to the wrong recipient, or past its expiry is refused at execution time, not by a dashboard promise. The budget also ENDS on a date your user chooses \u2014 30, 90 (default), 180 or 365 days out \u2014 and that day is enforced on-chain too. When the budget ends, your authority to pay ends with it; ask your user to renew it (a new approval on the agent's page, or a new \`budget grant\`). Haven constructs and relays the payments; you get an agent credential and a signing key made on your machine, and your user can revoke the budget without you and without Haven.
 
 ## The sequence
 
@@ -5359,7 +5441,7 @@ If the approval wait times out, nothing is lost \u2014 your agent is registered
 Call \`haven_get_agent\`, one of the Haven MCP tools the connector wires into your runtime in step 4. It returns identity plus \`spend_authority_readiness\`:
 
 - \`ready\` \u2014 a budget is live: you have the authority to pay. It does not say the account holds funds \u2014 the \`allowances[]\` rows carry \`funds_cover_remaining\`, and \`false\` there is a heads-up to mention to your user, not a refusal.
-- \`needs_approval\` \u2014 the connector finished, nobody approved yet. Ask your user again, in their Haven tab; there is no queue to wait in.
+- \`needs_approval\` \u2014 no budget can pay. \`allowances[]\` empty with \`budgetEndedAt\` set: your budget ENDED on that date; waiting will not help \u2014 ask your user to set a new one in their Haven tab. \`allowances[]\` empty with \`budgetEndedAt\` null: nobody approved one yet; ask your user again \u2014 there is no queue. Rows, all spent: it refills at \`budgetRefillsAt\`; tell your user, then wait or ask them to raise it (\`null\`: it ends first; ask them to renew it).
 - \`revoked\` \u2014 the credential is not active; ask your user to create a new agent.
 
 \`ready\` covers hosted identity and the budget only, not your local signer. Check that with \`npx -y @haven_ai/connect@<channel> --doctor\`, the same tag your prompt named \u2014 a separate command, so the command-modification rule does not bind it.
@@ -5395,7 +5477,7 @@ Then:
 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 I have given you the authority to pay \u2014 it does not confirm the account holds funds, so if its allowances rows carry \`funds_cover_remaining: false\`, tell me and still try the payment; \`needs_approval\` means my approval has not landed yet.
+4. Once I have approved the budget, verify with the \`haven_get_agent\` tool: \`ready\` means I have given you the authority to pay \u2014 it does not confirm the account holds funds, so if its allowances rows carry \`funds_cover_remaining: false\`, tell me and still try the payment; \`needs_approval\` with no allowances rows and \`budgetEndedAt\` set means my budget ended on that date \u2014 tell me, and I will set a new one; with no rows and no \`budgetEndedAt\`, my approval has not landed yet; with rows, the budget is spent \u2014 it refills at \`budgetRefillsAt\` (\`null\`: it ends first), so tell me, and I can raise or renew 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.
 
@@ -5515,8 +5597,10 @@ Do not guess the wallet address, network, or budget.
 
 For instant orientation at the start of a session, read the non-secret
 \`agent.json\` the connector wrote to your Haven credential directory (typically
-\`~/.haven/agents/<agent-id>/agent.json\` \u2014 if you don't know the agent id, list
-\`~/.haven/agents/\` to find the folder). It
+\`~/.haven/agents/<slug>/agent.json\`, where \`<slug>\` is the wiring name of the
+\`haven-<slug>\` pair \u2014 only a \`--bare\` run, or a \`--replace\` without \`--name\`,
+names the directory by the agent id instead; if you don't know the folder, list
+\`~/.haven/agents/\` to find it). It
 holds your agent id, Haven wallet address, network, and *configured* per-token
 budget, and contains no keys \u2014 the fastest way to answer "who am I and what may
 I spend" with no round trip. If that file is absent (some setups don't write
@@ -5537,7 +5621,13 @@ spending:
   the user, not a refusal \u2014 a budget above the balance is a normal setup, so
   still try the payment; \`null\` means the coverage read failed or the remaining
   figure was not read live; the key is absent when the remaining is 0. Rows for
-  one token are compared alone.
+  one token are compared alone. \`needs_approval\` with no \`allowances[]\`
+  rows and \`budgetEndedAt\` set means the budget ENDED on that date \u2014 waiting
+  will not help, ask the owner to set a new one; with no rows and no
+  \`budgetEndedAt\`, nobody approved a budget yet; with rows (all at remaining 0) the
+  budget is spent for this period, and \`budgetRefillsAt\` says when it refills
+  (\`null\`: it ends before it refills) \u2014 tell the user, then wait or ask them
+  to raise it.
 - \`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
@@ -5751,8 +5841,10 @@ for example, an invoice carrying an \`x402_payment_url\` to POST with its
   report it, the merchant's settlement evidence. (A deposit transfer is bound
   to its payee and amount on-chain too; the difference is the record, not
   the binding.)
-- **If the quote says stop, stop.** The quote checks the agent's remaining
-  budget at quote time, and it can check a price you state (\`expected_amount\`).
+- **If the quote says stop, stop.** The hosted quote checks the agent's
+  remaining budget at quote time, and it can check a price you state
+  (\`expected_amount\`). On the local runtime (\`@haven_ai/mcp\`) the quote
+  checks only a price you state; the budget is checked when you pay.
   When it returns \`safe_to_continue: false\` \u2014 the amount exceeds the budget, or
   the price does not match what you expected \u2014 it prefills no cap and names no
   next tool: stop and tell the user. If the x402 challenge itself is wrong (a
@@ -5897,8 +5989,8 @@ only part of it was usable), and an optional \`note\` (max 2000 characters)
 saying what was wrong. It is evidence only: it moves no money, never changes
 \`settled\` or any money field, and works only on your own settled
 payments \u2014 another agent's payment is refused. A re-report replaces your
-earlier verdict; the receipt then carries it beside the payment, so the
-owner does not read a junk delivery as a success.
+earlier verdict; the receipt then carries it beside the payment, so a junk
+delivery does not read as a success.
 ### Relay a delivered code or credential to the owner \u2014 immediately, verbatim
 
 If a merchant response carries what the user PAID FOR \u2014 a redemption code, gift