@haven_ai/sdk 0.1.25-alpha.0 → 0.1.27-alpha.0

package/dist/index.js

@@ -275,6 +275,17 @@ var X402UnexpectedStatusError = class extends HavenApiError {
     this.name = "X402UnexpectedStatusError";
   }
 };
+var X402AlreadySettledError = class extends HavenApiError {
+  constructor(message, receipt, basis) {
+    super(message, 409, void 0, receipt.paymentId);
+    this.receipt = receipt;
+    this.basis = basis;
+    this.name = "X402AlreadySettledError";
+  }
+  receipt;
+  basis;
+  x402ErrorCode = "already_settled";
+};
 var HavenPaymentStateError = class extends HavenApiError {
   constructor(message, statusCode, state, body) {
     super(message, statusCode, body, state.paymentId);
@@ -951,8 +962,8 @@ function createJsonRpcProvider(url) {
 function createWallet(privateKey, provider) {
   return new ethers.Wallet(privateKey, provider);
 }
-function createErc20Contract(address, abi, signer) {
-  return new ethers.Contract(address, abi, signer);
+function createErc20Contract(address, abi, runner) {
+  return new ethers.Contract(address, abi, runner);
 }
 
 // src/client.ts
@@ -1501,7 +1512,8 @@ var HavenClient = class {
         isResetPending: a.onchain.isResetPending
       };
     });
-    return { ...agent, readiness: deriveReadiness(agent.status, allowances), allowances };
+    const readiness = deriveReadiness(agent.status, allowances);
+    return { ...agent, readiness, spend_authority_readiness: readiness, allowances };
   }
   /**
    * Sweep stranded USDC and ETH from the delegate EOA back to the originating Safe.
@@ -1932,7 +1944,6 @@ var HavenClient = class {
     }
   }
   async authorizeStandardX402(paymentRequired, option, idempotencyKey) {
-    const paymentHeader = await this.createStandardX402Header(paymentRequired, option);
     const raw = await this.post("/x402", {
       url: paymentRequired.resource.url,
       payTo: this.delegateAddress,
@@ -1947,12 +1958,30 @@ var HavenClient = class {
       // declaration keeps both writers of the 3009 shape loud-by-default.
       settlementScheme: "eip3009"
     });
+    const state = this.paymentStateFromRaw("x402 payment", raw);
+    const executedReplay = raw.success && raw.tx_hash ? "idempotency-collision" : state?.nextAction === AgentPaymentNextAction.RetryOriginalX402Request ? "approval-resume" : null;
+    if (executedReplay) {
+      const canFund = await this.delegateCanFund(
+        raw.chain_id ?? state?.chainId ?? chainIdFromNetwork(option.network),
+        option.asset,
+        x402AuthorizationAmount(option)
+      );
+      const refuse = executedReplay === "idempotency-collision" ? canFund !== true : canFund === false;
+      if (refuse) {
+        const settledReceipt = state && executedReplay === "approval-resume" ? this.mapX402ReceiptFromStatus(paymentRequired, option, void 0, state) : this.mapX402ReceiptFromAuthorization(paymentRequired, option, void 0, raw);
+        throw new X402AlreadySettledError(
+          canFund === false ? "This x402 payment already settled \u2014 the delegate no longer holds the funds to authorize it again. To buy the same item a second time, pass a distinct `idempotencyKey`; the synthesised key intentionally collapses repeat calls for the same product within a 5-minute window so a retried request cannot pay twice." : "This x402 payment already settled, and whether the delegate can still fund a new authorization could not be verified (no `chainRpcs` entry for this chain). Refusing rather than issue an authorization that may be unfundable. To buy the same item a second time, pass a distinct `idempotencyKey`; to finish an interrupted payment, resume it by `paymentId`.",
+          settledReceipt,
+          canFund === false ? "settled" : "unverifiable"
+        );
+      }
+    }
+    const paymentHeader = await this.createStandardX402Header(paymentRequired, option);
     if (raw.success && raw.tx_hash) {
       const receipt2 = this.mapX402ReceiptFromAuthorization(paymentRequired, option, paymentHeader, raw);
       this.cacheX402Receipt(idempotencyKey, paymentHeader, receipt2);
       return receipt2;
     }
-    const state = this.paymentStateFromRaw("x402 payment", raw);
     if (state?.nextAction === AgentPaymentNextAction.RetryOriginalX402Request) {
       const receipt2 = this.mapX402ReceiptFromStatus(paymentRequired, option, paymentHeader, state);
       this.cacheX402Receipt(idempotencyKey, paymentHeader, receipt2);
@@ -2064,7 +2093,10 @@ var HavenClient = class {
       // redeemable ONLY by them. `null` here means the merchant advertised none
       // (or an empty array, which the backend 400s on), so the field is OMITTED
       // rather than sent empty. See x402FacilitatorAddresses.
-      ...selection.facilitatorAddresses ? { facilitatorAddresses: selection.facilitatorAddresses } : {}
+      ...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 } : {}
     });
     if (!raw.payment_id) {
       throw new HavenApiError("No payment_id returned from x402/authorize", 500, raw);
@@ -2133,6 +2165,18 @@ var HavenClient = class {
     if (cached && cached.expiresAt > Date.now()) return cached.receipt;
     const status = await this.getPaymentStatus(input.paymentId);
     this.assertCanResumeX402(status, input.paymentRequired, option);
+    const canFund = await this.delegateCanFund(
+      status.chainId ?? chainIdFromNetwork(option.network),
+      option.asset,
+      x402AuthorizationAmount(option)
+    );
+    if (canFund === false) {
+      throw new X402AlreadySettledError(
+        `x402 payment ${status.paymentId} has already settled \u2014 the delegate no longer holds the funds to authorize it again, so there is nothing left to resume.`,
+        this.mapX402ReceiptFromStatus(input.paymentRequired, option, void 0, status),
+        "settled"
+      );
+    }
     const paymentHeader = await this.createStandardX402Header(input.paymentRequired, option);
     const receipt = this.mapX402ReceiptFromStatus(input.paymentRequired, option, paymentHeader, status);
     this.cacheX402Receipt(idempotencyKey, paymentHeader, receipt);
@@ -2860,6 +2904,45 @@ var HavenClient = class {
       );
     }
   }
+  /**
+   * Can the delegate EOA still fund an authorization for `amountAtomic`?
+   *
+   * #1521: the only question that separates a legitimate resume (funding
+   * confirmed, merchant never paid — the delegate still holds the money) from
+   * a replayed settled payment (funding confirmed, merchant paid, delegate
+   * spent). The intent's own `status: 'confirmed'` is identical in both.
+   *
+   * The balance is asked of the CHAIN rather than of Haven's bookkeeping on
+   * purpose: the merchant-settlement evidence record is written by this SDK
+   * *after* the merchant call, so a client that dies between the two leaves
+   * the backend believing the merchant was never paid — the exact case the
+   * discriminator has to get right. The chain cannot be behind in that way.
+   *
+   * Returns `null` — never a guess — when `chainRpcs` has no entry for the
+   * chain or the read fails. Callers must treat that as "unverifiable", not
+   * as "funded".
+   */
+  async delegateCanFund(chainId, tokenAddress, amountAtomic, timeoutMs = 1e4) {
+    if (!chainId || !this.delegateAddress) return null;
+    const rpcUrl = this.chainRpcs[chainId];
+    if (!rpcUrl) return null;
+    try {
+      const provider = createJsonRpcProvider(rpcUrl);
+      const token = createErc20Contract(
+        tokenAddress,
+        ["function balanceOf(address) view returns (uint256)"],
+        provider
+      );
+      const balance = await Promise.race([
+        token.balanceOf(this.delegateAddress),
+        new Promise((resolve) => setTimeout(() => resolve(null), timeoutMs).unref?.())
+      ]);
+      if (balance === null) return null;
+      return balance >= BigInt(amountAtomic);
+    } catch {
+      return null;
+    }
+  }
   throwIfNonSignableAuthorizationState(label, raw) {
     if (raw.status === "pending_signature") return;
     this.throwPaymentStateError(label, raw);
@@ -3495,9 +3578,9 @@ var toolDescriptions = {
     nextActionGuidance: ""
   },
   getAgent: {
-    summary: "Return the authenticated agent identity AND its live spend authority in one call: Haven wallet, delegate, chain, raw status, a readiness signal, and per-token remaining allowance (atomic + human-readable). The recommended first call in a new session to confirm who you are and whether you can pay right now.",
+    summary: "Return the authenticated agent identity AND its live spend authority in one call: Haven wallet, delegate, chain, raw status, spend_authority_readiness, and per-token remaining allowance (atomic + human-readable). The recommended first call in a new session to confirm who you are and whether Haven will let you spend right now.",
     selectionGuidance: "Use this as the one-shot orientation/bootstrap at the start of a session, or whenever you need to confirm identity together with whether the agent can spend right now. For a detailed per-token breakdown (configured vs spent vs reset window) use haven_get_allowances.",
-    behavior: 'Reads identity plus the live spend-authority snapshot in one shot \u2014 the on-chain AllowanceModule on the legacy rail, the active budget delegation on the delegation rail. readiness 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. What an over-budget payment does differs by rail: on the legacy AllowanceModule rail it is queued for the wallet owner to approve in Haven; on the delegation rail there is no approval queue \u2014 an over-budget redemption reverts on-chain, so ask the owner to grant or raise the budget in Haven rather than waiting for an approval. allowances[] carries remainingAtomic and remainingDisplay per token. Identity fields (id, name, status, safeAddress, delegateAddress, chainId) are unchanged from before.',
+    behavior: 'Reads identity plus the live spend-authority snapshot in one shot \u2014 the on-chain AllowanceModule on the legacy rail, the active budget delegation on the delegation rail. spend_authority_readiness (readiness is a deprecated alias, same value) is "ready" when at least one token has remaining spend authority, "needs_approval" when the agent is active but has none, and "revoked" when the credential is not active. It covers hosted identity + on-chain spend authority ONLY \u2014 the hosted server cannot see the LOCAL signer, so "ready" does not mean the signer can start; verify the signer with a signer tool call or connect --doctor. What an over-budget payment does differs by rail: on the legacy AllowanceModule rail it is queued for the wallet owner to approve in Haven; on the delegation rail there is no approval queue \u2014 an over-budget redemption reverts on-chain, so ask the owner to grant or raise the budget in Haven rather than waiting for an approval. allowances[] carries remainingAtomic and remainingDisplay per token. Identity fields (id, name, status, safeAddress, delegateAddress, chainId) are unchanged from before.',
     nextActionGuidance: ""
   },
   getAllowances: {
@@ -3528,7 +3611,7 @@ var toolDescriptions = {
     summary: "Step 1 of a purchase: discover payable services from Haven's curated merchant catalog \u2014 names, prices, and which pay tool to use next.",
     selectionGuidance: "Use this when the user asks what the agent can buy, pay for, or which paid services exist \u2014 or when you need a resource URL for a service the user described. Do NOT use for balance, budget, or spend-limit questions \u2014 use haven_get_allowances. Do NOT use to pay \u2014 each returned entry names the pay tool to use next.",
     behavior: "Use each entry's suggested_tool field first \u2014 it names the exact next call. Read-only lookup against Haven's curated catalog; entries are periodically re-verified against the live merchant and degraded entries are flagged. Use category for a case-insensitive category filter (for example, VPN or vpn), or search for a product name, category, or description term. Returns name, description, price, rail, resource URL, tool_name, tool_arguments, and suggested_tool. The catalog price (price_display/price_atomic, marked price_is_indicative) is a last-verified hint, NOT authoritative \u2014 the real price comes from the merchant's live 402 at pay time. Never creates a payment, signature, or approval.",
-    nextActionGuidance: `Pick an entry and pay it with the tool named in suggested_tool, passing the entry's resource_url, tool_name, and tool_arguments for MCP merchants. Confirm the price from the live pay-tool result (not the catalog), and pass the user's cap as max_amount_human in whole tokens ("no more than 1 USDC" \u2192 max_amount_human: "1") \u2014 never convert it to atomic units by hand (#1351).`
+    nextActionGuidance: `Pick an entry and pay it with the tool named in suggested_tool, passing the entry's resource_url, tool_name, and tool_arguments for MCP merchants. Confirm the price from the live pay-tool result (not the catalog), and pass the user's cap as max_amount_human in whole tokens ("no more than 1 USDC" \u2192 max_amount_human: "1") \u2014 never convert it to atomic units by hand.`
   },
   sweep_delegate: {
     summary: "Sweep stranded USDC and/or ETH from the delegate wallet back to the originating Safe.",
@@ -3773,9 +3856,13 @@ user's approval in Haven.
 
 Hosted tools run in the \`mcp__haven__\` namespace. Local signing tools run in
 the \`mcp__haven-signer__\` namespace and keep the delegate key on this machine.
-Tool results carry the exact next step (\`next_action\`, \`next_tool\`,
-\`next_arguments\`) \u2014 follow those fields first; the prose below is fallback
-and orientation, not the source of truth.
+That namespacing is Claude-family; other runtimes name the servers by their
+own config keys (Codex: \`haven\`, \`haven_signer\`). Tool results carry the
+exact next step (\`next_action\`, \`next_tool\`, \`next_arguments\`, plus the
+runtime-neutral \`next_tool_server\` + \`next_tool_name\` \u2014 the bare tool name
+on that logical server, whatever your runtime calls it).
+Follow those fields first; the prose below is fallback and orientation, not
+the source of truth.
 
 ## When to use this skill
 
@@ -3801,8 +3888,10 @@ Before any payment, confirm the *live remaining* budget with the tools \u2014
 spending:
 
 - \`mcp__haven__haven_get_agent\` \u2014 the recommended first call: identity
-  (wallet, network) plus a readiness signal (\`ready\` / \`needs_approval\` /
-  \`revoked\`) and live remaining per-token allowance, in one shot.
+  (wallet, network) plus \`spend_authority_readiness\` (\`ready\` / \`needs_approval\` /
+  \`revoked\`) and live remaining per-token allowance, in one shot. That signal
+  covers hosted identity and on-chain spend authority only \u2014 it cannot see the
+  local signer; the signer is verified by calling any signer tool.
 - \`mcp__haven__haven_get_allowances\` \u2014 detailed per-token breakdown
   (configured, spent, reset window) when you need more than the summary.
 
@@ -4040,6 +4129,6 @@ function sameUrl(a, b) {
   }
 }
 
-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, DISCOVERY_MAX_BYTES, ERC7710_ASSET_TRANSFER_METHOD, HAVEN_MINIMUM_NODE_VERSION, HAVEN_SKILL_BODY_MD, HAVEN_SKILL_MD, HavenApiError, HavenClient, HavenError, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, HavenUnsupportedSignerVersionError, MERCHANT_DISCOVERY_PATHS, MerchantTimeoutError, RECEIPT_VERSION, SIGNER_UPDATE_FALLBACK, SKILL_FOLDER_NAME, SWEEP_BASE_CHAIN_ID, SWEEP_BASE_SEPOLIA_CHAIN_ID, SWEEP_BASE_SEPOLIA_USDC_ADDRESS, SWEEP_BASE_USDC_ADDRESS, SignerRefusalCode, TRANSFER_WITH_AUTHORIZATION_TYPES, X402PaymentHeaderValidationError, X402UnexpectedStatusError, X402_MAX_AUTHORIZATION_WINDOW_SECONDS, X402_SETTLEMENT_FORWARD_MARGIN_SECONDS, addressFromKey, buildSweepAuthorizationMessage, buildSweepTypedData, buildX402ExpectedMessage, compareNodeVersions, composeDescription, decodeBase64Json, decodeBase64Utf8, discoverMerchantMcpUrl, encodeBase64Json, encodeBase64Utf8, encodePaymentProof, havenTools, isErc7710Option, isSupportedNodeVersion, isSweepableChain, normalizePaymentRequired, parsePaymentRequired, parsePaymentRequiredResponse, resolveTokenFromAddress, sameUrl, selectErc7710PaymentOption, selectPaymentOption, selectStandardPaymentOption, selectX402SettlementScheme, signHash, signUserOpTypedDataForDelegation, sweepUsdcAddress, sweepUsdcDomain, toStandardPaymentRequirements, toolDescriptions, unsupportedNodeVersionMessage, validateStandardX402PaymentHeader, verifyPaymentReceipt, verifySignature, x402AssetTransferMethod, x402AuthorizationAmount, x402FacilitatorAddresses };
+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, DISCOVERY_MAX_BYTES, ERC7710_ASSET_TRANSFER_METHOD, HAVEN_MINIMUM_NODE_VERSION, HAVEN_SKILL_BODY_MD, HAVEN_SKILL_MD, HavenApiError, HavenClient, HavenError, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, HavenUnsupportedSignerVersionError, MERCHANT_DISCOVERY_PATHS, MerchantTimeoutError, RECEIPT_VERSION, SIGNER_UPDATE_FALLBACK, SKILL_FOLDER_NAME, SWEEP_BASE_CHAIN_ID, SWEEP_BASE_SEPOLIA_CHAIN_ID, SWEEP_BASE_SEPOLIA_USDC_ADDRESS, SWEEP_BASE_USDC_ADDRESS, SignerRefusalCode, TRANSFER_WITH_AUTHORIZATION_TYPES, X402AlreadySettledError, X402PaymentHeaderValidationError, X402UnexpectedStatusError, X402_MAX_AUTHORIZATION_WINDOW_SECONDS, X402_SETTLEMENT_FORWARD_MARGIN_SECONDS, addressFromKey, buildSweepAuthorizationMessage, buildSweepTypedData, buildX402ExpectedMessage, compareNodeVersions, composeDescription, decodeBase64Json, decodeBase64Utf8, discoverMerchantMcpUrl, encodeBase64Json, encodeBase64Utf8, encodePaymentProof, havenTools, isErc7710Option, isSupportedNodeVersion, isSweepableChain, normalizePaymentRequired, parsePaymentRequired, parsePaymentRequiredResponse, resolveTokenFromAddress, sameUrl, selectErc7710PaymentOption, selectPaymentOption, selectStandardPaymentOption, selectX402SettlementScheme, signHash, signUserOpTypedDataForDelegation, sweepUsdcAddress, sweepUsdcDomain, toStandardPaymentRequirements, toolDescriptions, unsupportedNodeVersionMessage, validateStandardX402PaymentHeader, verifyPaymentReceipt, verifySignature, x402AssetTransferMethod, x402AuthorizationAmount, x402FacilitatorAddresses };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map