@haven_ai/sdk 0.1.37-alpha.0 → 0.2.0-alpha.0

package/dist/index.cjs

@@ -110,9 +110,14 @@ var AgentPaymentNextAction = {
    */
   PaymentWindowExpired: "payment_window_expired",
   /**
-   * Stop and tell the user that the originating Safe needs to be funded or
+   * Stop and tell the user that the originating account needs to be funded or
    * the agent's per-token allowance needs to be raised before the payment
    * can succeed. A user approval will not fix this state on its own.
+   *
+   * #2908: the wire twin `fund_account_or_raise_allowance`
+   * ({@link AgentPaymentNextActionAccountAlias}) means the same thing; the
+   * server keeps emitting THIS value until #2914. Compare via
+   * {@link canonicalAgentPaymentNextAction}.
    */
   FundSafeOrRaiseAllowance: "fund_safe_or_raise_allowance",
   /**
@@ -122,6 +127,19 @@ var AgentPaymentNextAction = {
    */
   SweepStrandedFunds: "sweep_stranded_funds"
 };
+var AgentPaymentNextActionAccountAlias = {
+  /** Account-vocabulary twin of `fund_safe_or_raise_allowance`; same meaning. */
+  FundAccountOrRaiseAllowance: "fund_account_or_raise_allowance"
+};
+function canonicalAgentPaymentNextAction(value) {
+  if (value === AgentPaymentNextActionAccountAlias.FundAccountOrRaiseAllowance) {
+    return AgentPaymentNextAction.FundSafeOrRaiseAllowance;
+  }
+  return value;
+}
+function isFundAccountOrRaiseAllowance(value) {
+  return value === AgentPaymentNextAction.FundSafeOrRaiseAllowance || value === AgentPaymentNextActionAccountAlias.FundAccountOrRaiseAllowance;
+}
 var AgentPaymentFailureCode = {
   /** A merchant-authoritative x402 price exceeds the caller's pre-funding max_amount cap. */
   PriceExceedsMax: "PRICE_EXCEEDS_MAX",
@@ -1128,7 +1146,10 @@ function mapPaymentStatusResult(raw) {
     rail: raw.rail,
     status: raw.status,
     phase: raw.phase,
-    nextAction: raw.next_action,
+    // #2908: the account-vocabulary alias collapses onto the canonical value
+    // so every `=== AgentPaymentNextAction.X` downstream keeps working when
+    // the server flips its emit at #2914.
+    nextAction: canonicalAgentPaymentNextAction(raw.next_action),
     amount: raw.amount,
     token: raw.token,
     resourceUrl: raw.resource_url,
@@ -1260,7 +1281,7 @@ function messageForState(label, status, paymentId, nextAction) {
 function paymentStateFromRaw(label, raw) {
   if (!raw.payment_id || !raw.status) return null;
   const phase = raw.phase ?? phaseForStatus(raw.status);
-  const nextAction = raw.next_action ?? nextActionForStatus(raw.status);
+  const nextAction = canonicalAgentPaymentNextAction(raw.next_action) ?? nextActionForStatus(raw.status);
   if (!phase || !nextAction) return null;
   const amount = raw.amount ?? raw.requested ?? "";
   const token = raw.token ?? "";
@@ -1583,6 +1604,20 @@ function verifyPaymentReceipt(receipt, recover = defaultRecover) {
   return { verified: true, recoveredSigner: recovered };
 }
 
+// src/account-naming.ts
+function readAccountAddress(raw) {
+  return raw.account_address ?? raw.safe_address ?? void 0;
+}
+function readAccountId(raw) {
+  return raw.account_id ?? raw.safe_id ?? void 0;
+}
+function accountAddressTwins(address) {
+  return { accountAddress: address, safeAddress: address };
+}
+function readX402ReceiptPayer(raw) {
+  return raw.payer ?? raw.account_address ?? raw.sign_data?.components?.payer_account ?? raw.safe_address ?? raw.sign_data?.components?.safe;
+}
+
 // src/account-reads.ts
 function safeBigInt(value) {
   try {
@@ -1641,7 +1676,10 @@ var AccountReads = class {
     const raw = await this.transport.get("/machine-payments/allowances");
     return {
       agentId: raw.agent_id,
-      safeAddress: raw.safe_address,
+      // #2908: one mapper, both names, same value — `readAccountAddress`
+      // prefers the server's `account_address` twin and falls back to
+      // `safe_address` for a pre-#2907 server.
+      ...accountAddressTwins(readAccountAddress(raw)),
       delegateAddress: raw.delegate_address,
       chainId: raw.chain_id,
       allowances: raw.allowances.map((allowance) => ({
@@ -1730,7 +1768,10 @@ var AccountReads = class {
       id: raw.id,
       name: raw.name,
       status: raw.status,
-      safeAddress: raw.safe_address,
+      // #2908: both camelCase names off whichever snake_case name the server
+      // sent (new first). The hosted MCP's `haven_get_agent` spreads this
+      // object, so this is also the hosted output's dual-emit point.
+      ...accountAddressTwins(readAccountAddress(raw)),
       delegateAddress: raw.delegate_address,
       chainId: raw.chain_id,
       executionRail: raw.execution_rail === "delegation" ? "delegation" : "legacy"
@@ -1780,7 +1821,7 @@ var DelegateSweepApi = class {
       const contract = createErc20Contract(sweepUsdcAddress(agent.chainId), ["function balanceOf(address) view returns (uint256)", "function transfer(address to, uint256 amount) returns (bool)"], wallet);
       const balance2 = await contract.balanceOf(agent.delegateAddress);
       if (balance2 > 0n) {
-        const tx = await contract.transfer(agent.safeAddress, balance2);
+        const tx = await contract.transfer(agent.accountAddress, balance2);
         const { txHash, confirmation } = await waitForSweepTx(tx);
         transfers.push({ asset: "USDC", amount: format(balance2, 6), amountAtomic: balance2.toString(), txHash, explorerUrl: this.options.buildExplorerUrl(agent.chainId, txHash), confirmation });
       }
@@ -1790,12 +1831,12 @@ var DelegateSweepApi = class {
       const fee = await provider.getFeeData();
       const send = balance - (fee.maxFeePerGas ?? fee.gasPrice ?? 1000000n) * 21000n * 2n;
       if (send > 0n) {
-        const tx = await wallet.sendTransaction({ to: agent.safeAddress, value: send });
+        const tx = await wallet.sendTransaction({ to: agent.accountAddress, value: send });
         const { txHash, confirmation } = await waitForSweepTx(tx);
         transfers.push({ asset: "ETH", amount: format(send, 18), amountAtomic: send.toString(), txHash, explorerUrl: this.options.buildExplorerUrl(agent.chainId, txHash), confirmation });
       }
     }
-    return { fromAddress: agent.delegateAddress, toAddress: agent.safeAddress, chainId: agent.chainId, transfers, unconfirmed: transfers.some((t) => t.confirmation === "unconfirmed") };
+    return { fromAddress: agent.delegateAddress, toAddress: agent.accountAddress, chainId: agent.chainId, transfers, unconfirmed: transfers.some((t) => t.confirmation === "unconfirmed") };
   }
   prepareSweep() {
     return this.options.transport.post("/machine-payments/sweep/prepare", {});
@@ -2189,7 +2230,7 @@ var X402FundingLeg = class {
     const to = execResult?.to ?? raw.to ?? this.delegateAddress ?? "";
     const explorerUrl = execResult?.explorer_url ?? raw.explorer_url ?? explorerUrlOrEmpty(chainId, txHash);
     const merchantTo = execResult?.merchant_to ?? raw.merchant_to ?? option.payTo;
-    const payer = raw.payer ?? raw.safe_address ?? raw.sign_data?.components.safe;
+    const payer = readX402ReceiptPayer(raw);
     return buildX402Receipt({
       paymentId: raw.payment_id,
       txHash,
@@ -4022,13 +4063,13 @@ var toolDescriptions = {
     summary: "Pay an inspected x402 quote. The delegate key signs locally; Haven only validates and relays signed, on-chain-constrained payment transactions.",
     selectionGuidance: "Do not use this for read-only allowance, budget, spend-limit, remaining-amount, reset-period, or what-can-I-spend questions; use the allowance lookup tool instead.",
     behavior: "Signs the payment locally and returns the merchant response. Settlement is either direct account-to-merchant with no funding leg, or a bridge that first redeems the agent's budget delegation to fund the delegate wallet for an EIP-3009 authorization. A payment outside the on-chain budget is declined before any money moves; nothing is queued for a human to approve later.",
-    nextActionGuidance: "Preserve the returned resume_state \u2014 it identifies this payment if you need to ask about it later. This tool performs the merchant retry itself, so do not wait on a signal while the call is in flight. If the process crashes after this call and a later haven_get_payment_status reports nextAction=retry_original_x402_request, Haven's funding leg confirmed but no merchant response was ever recorded \u2014 call the resume tool with the preserved resume_state or payment_id instead of paying again. If the response carries phase=insufficient_funds and nextAction=fund_safe_or_raise_allowance, the payment cannot be retried until the account is funded or the agent budget raised \u2014 stop and tell the user the shortfall reported on the response."
+    nextActionGuidance: "Preserve the returned resume_state \u2014 it identifies this payment if you need to ask about it later. This tool performs the merchant retry itself, so do not wait on a signal while the call is in flight. If the process crashes after this call and a later haven_get_payment_status reports nextAction=retry_original_x402_request, Haven's funding leg confirmed but no merchant response was ever recorded \u2014 call the resume tool with the preserved resume_state or payment_id instead of paying again. If the response carries phase=insufficient_funds and nextAction=fund_safe_or_raise_allowance (or fund_account_or_raise_allowance), the payment cannot be retried until the account is funded or the agent budget raised \u2014 stop and tell the user the shortfall reported on the response."
   },
   payX402OneShot: {
     summary: "Fetch an x402 paid HTTP resource in a single call. Handles the full probe -> pay -> retry round trip and returns the merchant response.",
     selectionGuidance: "Prefer this over the quote+pay split when the agent just wants the paid resource and does not need to inspect the price first. If you already have a quote from haven_quote_x402, use haven_pay_x402_quote instead. Do not use for read-only allowance, budget, spend-limit, remaining-amount, reset-period, or what-can-I-spend questions; use the allowance lookup tool instead.",
     behavior: "Calls the URL, parses any HTTP 402 x402 challenge, signs the payment locally, then retries the original request with the signed payment header (sent under PAYMENT-SIGNATURE, plus the legacy X-PAYMENT on the EIP-3009 path only) and returns the merchant response. Settlement is either direct account-to-merchant with no funding leg, or a bridge that first redeems the agent's budget delegation to fund the delegate wallet for an EIP-3009 authorization. A payment outside the on-chain budget is declined before any money moves; nothing is queued for a human to approve later. If the resource returns a non-402 status, returns it unchanged without contacting Haven.",
-    nextActionGuidance: "Preserve the returned resume_state or paymentId \u2014 either identifies this payment if you need to ask about it later. This tool performs the merchant retry itself, so do not wait on a signal while the call is in flight. If the process crashes after this call and a later haven_get_payment_status reports nextAction=retry_original_x402_request, Haven's funding leg confirmed but no merchant response was ever recorded \u2014 call the resume tool with the preserved resume_state or payment_id instead of paying again. If the response carries phase=insufficient_funds and nextAction=fund_safe_or_raise_allowance, the payment cannot be retried until the account is funded or the agent budget raised \u2014 stop and tell the user the shortfall reported on the response."
+    nextActionGuidance: "Preserve the returned resume_state or paymentId \u2014 either identifies this payment if you need to ask about it later. This tool performs the merchant retry itself, so do not wait on a signal while the call is in flight. If the process crashes after this call and a later haven_get_payment_status reports nextAction=retry_original_x402_request, Haven's funding leg confirmed but no merchant response was ever recorded \u2014 call the resume tool with the preserved resume_state or payment_id instead of paying again. If the response carries phase=insufficient_funds and nextAction=fund_safe_or_raise_allowance (or fund_account_or_raise_allowance), the payment cannot be retried until the account is funded or the agent budget raised \u2014 stop and tell the user the shortfall reported on the response."
   },
   resumeX402: {
     summary: "Resume an x402 payment whose Haven-side authorization already succeeded but whose merchant retry did not complete.",
@@ -4052,7 +4093,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, and per-token remaining allowance (atomic + human-readable). The recommended first call in a new session to confirm who you are and whether Haven will let you spend right now.",
     selectionGuidance: "Use this as the one-shot orientation/bootstrap at the start of a session, or whenever you need to confirm identity together with whether the agent can spend right now. For a detailed per-token breakdown (configured vs spent vs reset window) use haven_get_allowances.",
-    behavior: `Reads identity plus the live spend-authority snapshot in one shot \u2014 the agent's active on-chain budget delegation. spend_authority_readiness (readiness is a deprecated alias, same value) is "ready" when at least one token has remaining spend authority, "needs_approval" when the agent is active but has none, and "revoked" when the credential is not active. It covers hosted identity + on-chain spend authority ONLY \u2014 the hosted server cannot see the LOCAL signer, so "ready" does not mean the signer can start; verify the signer with a signer tool call or connect --doctor. An over-budget payment is declined before any money moves: there is no approval queue, so ask the owner to grant or raise the budget in Haven rather than waiting for an approval. allowances[] carries remainingAtomic and remainingDisplay per token. Identity fields (id, name, status, safeAddress, delegateAddress, chainId) are unchanged from before.`,
+    behavior: `Reads identity plus the live spend-authority snapshot in one shot \u2014 the agent's active on-chain budget delegation. spend_authority_readiness (readiness is a deprecated alias, same value) is "ready" when at least one token has remaining spend authority, "needs_approval" when the agent is active but has none, and "revoked" when the credential is not active. It covers hosted identity + on-chain spend authority ONLY \u2014 the hosted server cannot see the LOCAL signer, so "ready" does not mean the signer can start; verify the signer with a signer tool call or connect --doctor. An over-budget payment is declined before any money moves: there is no approval queue, so ask the owner to grant or raise the budget in Haven rather than waiting for an approval. allowances[] carries remainingAtomic and remainingDisplay per token. Identity fields: id, name, status, accountAddress (safeAddress: deprecated alias, same value), delegateAddress, chainId.`,
     nextActionGuidance: ""
   },
   getAllowances: {
@@ -4092,9 +4133,9 @@ var toolDescriptions = {
     nextActionGuidance: "Give the verify_token and the well-known instructions (from getCatalogSubmissionStatus) to the merchant so they can publish the proof line, then poll the submission status until it reaches verified_payable or failed."
   },
   sweep_delegate: {
-    summary: "Sweep stranded USDC and/or ETH from the delegate wallet back to the originating Safe.",
+    summary: "Sweep stranded USDC and/or ETH from the delegate wallet back to the originating account.",
     selectionGuidance: "Use this when the user instructs you to recover stranded funds on the delegate wallet, or when a payment status returns nextAction=sweep_stranded_funds. Do NOT use for normal payments \u2014 use haven_pay_x402. Do NOT use to read balances only \u2014 use haven_get_allowances.",
-    behavior: `Reads the delegate EOA's on-chain USDC and ETH balances. For each non-zero balance, signs and submits a transfer from the delegate EOA to the originating Safe (hardcoded destination). The delegate key signs locally \u2014 Haven never sees it and the backend never constructs signed transactions (CASP/MiCA Red Line #2). Returns tx hashes and recovered amounts. Returns an empty transfers list when nothing is stranded. Each transfer carries confirmation: "confirmed" (a receipt was seen \u2014 the funds are in the Safe) or "unconfirmed" (broadcast but not confirmed within 90 seconds \u2014 still in the mempool, may still land). The top-level unconfirmed flag is true when any transfer is unconfirmed.`,
+    behavior: `Reads the delegate EOA's on-chain USDC and ETH balances. For each non-zero balance, signs and submits a transfer from the delegate EOA to the originating account (hardcoded destination). The delegate key signs locally \u2014 Haven never sees it and the backend never constructs signed transactions (CASP/MiCA Red Line #2). Returns tx hashes and recovered amounts. Returns an empty transfers list when nothing is stranded. Each transfer carries confirmation: "confirmed" (a receipt was seen \u2014 the funds are in the account) or "unconfirmed" (broadcast but not confirmed within 90 seconds \u2014 still in the mempool, may still land). The top-level unconfirmed flag is true when any transfer is unconfirmed.`,
     nextActionGuidance: 'If transfers is non-empty, confirm the amounts with the user. Report a transfer as recovered ONLY when its confirmation is "confirmed". For an "unconfirmed" transfer, tell the user it was submitted but not yet confirmed, give them its txHash and explorerUrl to check, and do not re-run the sweep immediately \u2014 a re-run after it lands will simply find nothing stranded.'
   },
   send: {
@@ -4837,6 +4878,7 @@ exports.AgentPaymentFailureCode = AgentPaymentFailureCode;
 exports.AgentPaymentFailureCodeDescriptions = AgentPaymentFailureCodeDescriptions;
 exports.AgentPaymentFailureCodeSchema = AgentPaymentFailureCodeSchema;
 exports.AgentPaymentNextAction = AgentPaymentNextAction;
+exports.AgentPaymentNextActionAccountAlias = AgentPaymentNextActionAccountAlias;
 exports.AgentPaymentNextActionDescriptions = AgentPaymentNextActionDescriptions;
 exports.AgentPaymentNextActionSchema = AgentPaymentNextActionSchema;
 exports.AgentPaymentPhase = AgentPaymentPhase;
@@ -4883,10 +4925,12 @@ exports.X402_PAYMENT_HEADER_NAMES_SENT = X402_PAYMENT_HEADER_NAMES_SENT;
 exports.X402_PAYMENT_REQUIRED_HEADER_NAME = X402_PAYMENT_REQUIRED_HEADER_NAME;
 exports.X402_PAYMENT_RESPONSE_HEADER_NAME = X402_PAYMENT_RESPONSE_HEADER_NAME;
 exports.X402_SETTLEMENT_FORWARD_MARGIN_SECONDS = X402_SETTLEMENT_FORWARD_MARGIN_SECONDS;
+exports.accountAddressTwins = accountAddressTwins;
 exports.addressFromKey = addressFromKey;
 exports.buildSweepAuthorizationMessage = buildSweepAuthorizationMessage;
 exports.buildSweepTypedData = buildSweepTypedData;
 exports.buildX402ExpectedMessage = buildX402ExpectedMessage;
+exports.canonicalAgentPaymentNextAction = canonicalAgentPaymentNextAction;
 exports.compareNodeVersions = compareNodeVersions;
 exports.composeDescription = composeDescription;
 exports.connectorRerunCommand = connectorRerunCommand;
@@ -4900,11 +4944,15 @@ exports.encodePaymentProof = encodePaymentProof;
 exports.havenTools = havenTools;
 exports.isConnectorChannel = isConnectorChannel;
 exports.isErc7710Option = isErc7710Option;
+exports.isFundAccountOrRaiseAllowance = isFundAccountOrRaiseAllowance;
 exports.isSupportedNodeVersion = isSupportedNodeVersion;
 exports.isSweepableChain = isSweepableChain;
 exports.normalizePaymentRequired = normalizePaymentRequired;
 exports.parsePaymentRequired = parsePaymentRequired;
 exports.parsePaymentRequiredResponse = parsePaymentRequiredResponse;
+exports.readAccountAddress = readAccountAddress;
+exports.readAccountId = readAccountId;
+exports.readX402ReceiptPayer = readX402ReceiptPayer;
 exports.resolveConnectorChannel = resolveConnectorChannel;
 exports.resolveTokenFromAddress = resolveTokenFromAddress;
 exports.sameUrl = sameUrl;