@haven_ai/sdk 0.1.36-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,
@@ -3184,7 +3225,8 @@ var HavenClient = class {
    * Sign a payment's `sign_data` with the correct scheme for its rail.
    *
    * Dispatching on the server-provided scheme means a caller never has to
-   * know which rail an account is on; an unknown scheme is a hard error,
+   * know which rail an account is on; an unknown scheme — or an absent one,
+   * since the legacy AllowanceModule rail retired (#2850) — is a hard error,
    * never a guessed signature. The session rail's 'eip191_userop' is retired
    * (#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.
@@ -3218,7 +3260,9 @@ var HavenClient = class {
       return signSettlementDelegationTypedData(this.delegateKey, signData.typed_data);
     }
     if (scheme === void 0) {
-      return signHash(this.delegateKey, signData.hash);
+      throw new HavenSigningError(
+        "sign_data.signature_scheme is required \u2014 the legacy AllowanceModule rail that signed the bare hash is retired (#2850). Refusing to guess a signing scheme."
+      );
     }
     throw new HavenSigningError(
       `Unknown sign_data.signature_scheme '${scheme}' \u2014 refusing to guess a signing scheme. Update @haven_ai/sdk.`
@@ -3348,8 +3392,10 @@ var HavenClient = class {
    * allowance/budget summary a settle response carries.
    *
    * #1310/#1311 parity: this is the ONE home for logic that was duplicated
-   * verbatim in `packages/mcp-server/src/tools.ts` and `packages/mcp/src/tools.ts`
-   * (both hosted and local `haven_get_payment_status` handlers) — extracted
+   * verbatim in the hosted and local `haven_get_payment_status` handlers —
+   * `packages/mcp-server/src/tools/state-direct-recovery.ts` since #2809 (it
+   * was `packages/mcp-server/src/tools.ts` when this was written) and
+   * `packages/mcp/src/tools.ts` — extracted
    * here because both packages already depend on `@haven_ai/sdk` and call
    * methods on a `HavenClient` instance, so this needed no new dependency
    * edge. `funded_but_unsettled` is deliberately excluded: that phase means
@@ -4017,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.",
@@ -4047,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: {
@@ -4087,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: {
@@ -4348,7 +4394,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.
-2. **HUMAN \u2014 fund it.** USDC only, no ETH: Haven sponsors the gas. \`haven wallets funding\` prints the address, the amount **and which chain** in one place; without a CLI session, the dashboard's funding card shows the address and amount and its Receive-funds screen names the chain. Read the chain off whichever you used and put it in your message \u2014 never assume one: a testnet deployment and production both call themselves Haven.
+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.
 5. **HUMAN \u2014 approve the budget** with their passkey, in the Haven tab they created the agent in: it advances to the approval step by itself once your run registers.
@@ -4832,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;
@@ -4878,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;
@@ -4895,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;