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

package/dist/index.d.cts

@@ -23,7 +23,13 @@ interface PaymentReceipt {
         amount: string;
         amountSek: string | null;
         recipient: string;
+        /** @deprecated since #2907 — read `account`; removed in #2914 (the release after the naming window). Same value as `account`. */
         safe: string;
+        /**
+         * The payer's smart-account address (#2907 twin of `safe`). Optional for
+         * the window: a server from before the twin emits `safe` only.
+         */
+        account?: string;
         chainId: number;
         settledAt: string | null;
         resourceUrl: string | null;
@@ -138,7 +144,14 @@ interface SignData {
     };
     /** Breakdown of values that were hashed — useful for debugging */
     components: {
+        /** @deprecated #2908 — same value as `payer_account`; the server drops it at #2914. */
         safe: string;
+        /**
+         * #2907 — the account-vocabulary twin of `safe`: the PAYER account
+         * (the user's smart account). Not to be confused with `account`, which on
+         * the funding shapes holds the DELEGATE account address.
+         */
+        payer_account?: string;
         token: string;
         to: string;
         amount: string;
@@ -522,6 +535,15 @@ interface HavenAgent {
     id: string;
     name: string;
     status: string;
+    /**
+     * The agent's Haven account (smart account) address — #2908, the
+     * account-vocabulary name. Same value as {@link HavenAgent.safeAddress}.
+     */
+    accountAddress: string;
+    /**
+     * @deprecated #2908 — same value as {@link HavenAgent.accountAddress}.
+     * Removed in the release after the one carrying #2908 (#2914).
+     */
     safeAddress: string;
     delegateAddress: string;
     chainId: number;
@@ -563,6 +585,12 @@ interface HavenAllowance {
 }
 interface HavenAllowanceSummary {
     agentId: string;
+    /** #2908 — the account-vocabulary name; same value as `safeAddress`. */
+    accountAddress: string;
+    /**
+     * @deprecated #2908 — same value as {@link HavenAllowanceSummary.accountAddress}.
+     * Removed in the release after the one carrying #2908 (#2914).
+     */
     safeAddress: string;
     delegateAddress: string;
     chainId: number;
@@ -843,9 +871,14 @@ declare const AgentPaymentNextAction: {
      */
     readonly 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}.
      */
     readonly FundSafeOrRaiseAllowance: "fund_safe_or_raise_allowance";
     /**
@@ -856,6 +889,39 @@ declare const AgentPaymentNextAction: {
     readonly SweepStrandedFunds: "sweep_stranded_funds";
 };
 type AgentPaymentNextAction = (typeof AgentPaymentNextAction)[keyof typeof AgentPaymentNextAction];
+/**
+ * #2908 (naming epic #2906): the account-vocabulary twin of
+ * {@link AgentPaymentNextAction.FundSafeOrRaiseAllowance}. The server ACCEPTS
+ * and DOCUMENTS this value from #2907 but keeps EMITTING the old one through
+ * the compatibility window; the emitted value flips at #2914.
+ *
+ * Deliberately declared beside `AgentPaymentNextAction` rather than inside
+ * it: the backend keeps a hand-mirror of that const, parity-pinned key-for-key
+ * and value-for-value (`agent-payment-taxonomy.parity.test.ts`), and the
+ * served `x-enumDescriptions` are the SDK's strings verbatim. Both consts
+ * move together at #2914; until then this alias is how a client handles both
+ * wire values without forking the taxonomy.
+ */
+declare const AgentPaymentNextActionAccountAlias: {
+    /** Account-vocabulary twin of `fund_safe_or_raise_allowance`; same meaning. */
+    readonly FundAccountOrRaiseAllowance: "fund_account_or_raise_allowance";
+};
+type AgentPaymentNextActionAccountAlias = (typeof AgentPaymentNextActionAccountAlias)[keyof typeof AgentPaymentNextActionAccountAlias];
+/** Every `next_action` value a server may put on the wire during the #2908 window. */
+type AgentPaymentNextActionWire = AgentPaymentNextAction | AgentPaymentNextActionAccountAlias;
+/**
+ * Collapse the #2908 account-vocabulary alias onto its canonical taxonomy
+ * value, and pass every other value through untouched.
+ *
+ * This is the one seam a `switch` over `AgentPaymentNextAction` needs: a
+ * case on `FundSafeOrRaiseAllowance` matches a server that emits either
+ * spelling, and no case falls through because the alias arrived. Unknown
+ * strings are returned as-is (the SDK never invents a value), so the return
+ * type is exactly the input type widened by the canonical value.
+ */
+declare function canonicalAgentPaymentNextAction<T extends string | null | undefined>(value: T): Exclude<T, AgentPaymentNextActionAccountAlias> | typeof AgentPaymentNextAction.FundSafeOrRaiseAllowance;
+/** True for EITHER spelling of the fund-or-raise-allowance next action (#2908). */
+declare function isFundAccountOrRaiseAllowance(value: string | null | undefined): boolean;
 declare const AgentPaymentFailureCode: {
     /** A merchant-authoritative x402 price exceeds the caller's pre-funding max_amount cap. */
     readonly PriceExceedsMax: "PRICE_EXCEEDS_MAX";
@@ -992,7 +1058,15 @@ interface AgentPaymentWarning {
  * (payment_required) are named in `reason` and taken from the SAME response.
  */
 interface AgentNextStep {
-    next_action: AgentPaymentNextAction;
+    /**
+     * From `AgentPaymentNextAction`, widened by the #2908 account-vocabulary
+     * alias for the compatibility window: the hosted server keeps emitting
+     * `fund_safe_or_raise_allowance` until #2914, but a client compiled against
+     * this type must not reject `fund_account_or_raise_allowance` when the flip
+     * lands. Compare through {@link canonicalAgentPaymentNextAction} or
+     * {@link isFundAccountOrRaiseAllowance}, never by one literal.
+     */
+    next_action: AgentPaymentNextActionWire;
     /**
      * Claude-family namespaced tool name for the next call
      * (`mcp__<server>__<tool>`), when one exists.
@@ -2234,7 +2308,7 @@ declare const toolDescriptions: {
     readonly getAgent: {
         readonly 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.";
         readonly 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.";
-        readonly behavior: "Reads identity plus the live spend-authority snapshot in one shot — 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 — 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.";
+        readonly behavior: "Reads identity plus the live spend-authority snapshot in one shot — 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 — 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.";
         readonly nextActionGuidance: "";
     };
     readonly getAllowances: {
@@ -2274,7 +2348,7 @@ declare const toolDescriptions: {
         readonly 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.";
     };
     readonly sweep_delegate: {
-        readonly summary: "Sweep stranded USDC and/or ETH from the delegate wallet back to the originating Safe.";
+        readonly summary: "Sweep stranded USDC and/or ETH from the delegate wallet back to the originating account.";
         readonly selectionGuidance: string;
         readonly behavior: string;
         readonly nextActionGuidance: string;
@@ -2710,6 +2784,74 @@ interface UnsupportedNodeVersionMessageOptions {
  */
 declare function unsupportedNodeVersionMessage(options: UnsupportedNodeVersionMessageOptions): string;
 
+/**
+ * #2908 (naming epic #2906, phase 1): the account-vocabulary reads and the
+ * dual-name emissions every published package shares during the one-release
+ * compatibility window.
+ *
+ * The rule, stated once: READ both names and prefer the new; EMIT both names
+ * with the same value; WRITE only the new. The old names on server responses
+ * are removed by #2914, one release after the one that carries this module.
+ * The credential-FILE fallbacks (`safe_address` / `safeAddress` in a file on
+ * disk) are NOT part of that window — they are permanent, because a file that
+ * was written before this release never rewrites itself.
+ *
+ * Kept as tiny pure functions so a reader has exactly one fallback chain per
+ * shape and a test can mutate it: dropping the new name fails the new-shape
+ * test, dropping the old name fails the old-shape test.
+ */
+/**
+ * The account address off a snake_case server shape, new name first.
+ *
+ * `account_address` is the P0 (#2907) twin the server emits beside
+ * `safe_address`; an older server emits only `safe_address`. A missing pair
+ * resolves to `undefined` rather than an empty string so callers can tell
+ * "absent" from "blank".
+ */
+declare function readAccountAddress(raw: {
+    account_address?: string | null;
+    safe_address?: string | null;
+}): string | undefined;
+/**
+ * The account id off a snake_case server shape, new name first
+ * (`account_id`, the #2907 twin of `safe_id`).
+ */
+declare function readAccountId(raw: {
+    account_id?: string | null;
+    safe_id?: string | null;
+}): string | undefined;
+/**
+ * Both camelCase names for one address, for the SDK's public shapes (and the
+ * hosted MCP outputs that spread them). Same value under both keys; the
+ * `safeAddress` key is the deprecated one and goes at #2914.
+ */
+declare function accountAddressTwins(address: string | undefined): {
+    accountAddress: string;
+    safeAddress: string;
+};
+/**
+ * The x402 receipt's `payer` off a funding-authorization response, in the
+ * order the issue pins (#2908): the explicit `payer`, then the top-level
+ * account address (new name, then old), then the `sign_data.components`
+ * twins — `payer_account` (the #2907 twin) before `safe`.
+ *
+ * `components.account` is deliberately NOT in this chain: on the funding
+ * shapes it holds the DELEGATE account address, a different address, and
+ * reading it here would silently corrupt the receipt's payer.
+ */
+declare function readX402ReceiptPayer(raw: {
+    payer?: string;
+    account_address?: string;
+    safe_address?: string;
+    sign_data?: {
+        components?: {
+            payer_account?: string;
+            safe?: string;
+            account?: string;
+        };
+    };
+}): string | undefined;
+
 /**
  * x402 protocol support for the Haven SDK.
  *
@@ -3058,4 +3200,4 @@ declare function discoverMerchantMcpUrl(inputUrl: string): Promise<string | null
 /** Trailing-slash/percent-case echoes compare equal; unparseable never does. */
 declare function sameUrl(a: string, b: string): boolean;
 
-export { AGENT_APPROVAL_RELAY_JSON_SENTENCE, AGENT_APPROVAL_RELAY_PROSE_SENTENCE, AGENT_COMMAND_MODIFICATION_SENTENCE, AGENT_JSON_MODE_SENTENCE, AGENT_LOCAL_KEY_SENTENCE, AGENT_NETWORK_ACCESS_SENTENCE, AGENT_ONBOARDING_PROMPT, AGENT_PAYMENT_FAILURE_CODE_VALUES, AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, AGENT_README_SECTION_MD, AGENT_SECRET_HYGIENE_SENTENCE, AGENT_WIRING_COLLISION_RELAY_SENTENCE, type AgentNextStep, type AgentPaymentEnumSchema, AgentPaymentFailureCode, AgentPaymentFailureCodeDescriptions, AgentPaymentFailureCodeSchema, AgentPaymentNextAction, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, type AgentPaymentSummary, type AgentPaymentWarning, AgentPaymentWarningCode, type AgentPurchaseSummary, CONNECTOR_PACKAGE_NAME, type CatalogSubmissionAccepted, type ClaudeTool, DEFAULT_CONFIRMATION_TIMEOUT_MS, DISCOVERY_MAX_BYTES, ERC7710_ASSET_TRANSFER_METHOD, HAVEN_AGENT_RUNBOOK_MD, HAVEN_CONNECTOR_CHANNEL, HAVEN_MINIMUM_NODE_VERSION, HAVEN_SKILL_BODY_MD, HAVEN_SKILL_MD, type HavenAgent, type HavenAgentAllowanceSummary, type HavenAgentReadiness, type HavenAgentSummary, type HavenAllowance, type HavenAllowanceSummary, HavenApiError, type HavenCatalogEntry, type HavenCatalogSubmission, HavenClient, type HavenClientConfig, HavenError, type HavenPaymentReceipt, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, HavenUnsupportedSignerVersionError, MERCHANT_DISCOVERY_PATHS, type MachinePaymentRail, MerchantTimeoutError, type OpenAITool, type PaymentFee, type PaymentIntent, type PaymentNextAction, type PaymentPhase, type PaymentReceipt, type PaymentRequest, type PaymentResult, type PaymentResumeState, type PaymentStatus, type PaymentStatusResult, type PostPurchaseAllowanceSummary, RECEIPT_VERSION, type ReceiptVerification, type ResumeAuthorizedX402Input, type ResumeX402PaymentInput, SIGNER_UPDATE_FALLBACK, SKILL_FOLDER_NAME, SWEEP_BASE_CHAIN_ID, SWEEP_BASE_SEPOLIA_CHAIN_ID, SWEEP_BASE_SEPOLIA_USDC_ADDRESS, SWEEP_BASE_USDC_ADDRESS, type SharedToolKey, type SignData, SignerRefusalCode, type SweepAuthorization, type SweepConfirmation, type SweepEip712Domain, type SweepEntry, type SweepExpectedAuth, type SweepPreparation, type SweepPrepareResponse, type SweepResult, type SweepSubmitResponse, type SweepSubmitResult, type SweepTypedData, TRANSFER_WITH_AUTHORIZATION_TYPES, type ToolDescription, type UnsupportedNodeVersionMessageOptions, X402AlreadySettledError, type X402AuthorizationOptions, type X402Erc7710Settlement, type X402ExpectedAuth, type X402ExpectedContext, type X402Intent, type X402McpCallContext, type X402McpTransport, type X402MerchantCallContext, type X402MerchantOutcome, type X402MerchantOutcomeReport, type X402PaymentHeaderContext, X402PaymentHeaderValidationError, type X402PaymentOption, type X402PaymentRequired, type X402Quote, type X402Receipt, type X402RequestSnapshot, type X402ResumeState, type X402SchemeSelection, X402UnexpectedStatusError, X402_LEGACY_PAYMENT_HEADER_NAME, X402_MAX_AUTHORIZATION_WINDOW_SECONDS, X402_PAYMENT_HEADER_NAME, X402_PAYMENT_HEADER_NAMES_SENT, X402_PAYMENT_REQUIRED_HEADER_NAME, X402_PAYMENT_RESPONSE_HEADER_NAME, X402_SETTLEMENT_FORWARD_MARGIN_SECONDS, addressFromKey, buildSweepAuthorizationMessage, buildSweepTypedData, buildX402ExpectedMessage, compareNodeVersions, composeDescription, connectorRerunCommand, connectorSpec, decodeBase64Json, decodeBase64Utf8, discoverMerchantMcpUrl, encodeBase64Json, encodeBase64Utf8, encodePaymentProof, havenTools, isConnectorChannel, isErc7710Option, isSupportedNodeVersion, isSweepableChain, normalizePaymentRequired, parsePaymentRequired, parsePaymentRequiredResponse, resolveConnectorChannel, resolveTokenFromAddress, sameUrl, selectErc7710PaymentOption, selectPaymentOption, selectStandardPaymentOption, selectX402SettlementScheme, signHash, signUserOpTypedDataForDelegation, signerUpdateFallback, sweepUsdcAddress, sweepUsdcDomain, toStandardPaymentRequirements, toolDescriptions, unsupportedNodeVersionMessage, validateStandardX402PaymentHeader, verifyPaymentReceipt, verifySignature, x402AssetTransferMethod, x402AuthorizationAmount, x402FacilitatorAddresses, x402V2PaymentEnvelope };
+export { AGENT_APPROVAL_RELAY_JSON_SENTENCE, AGENT_APPROVAL_RELAY_PROSE_SENTENCE, AGENT_COMMAND_MODIFICATION_SENTENCE, AGENT_JSON_MODE_SENTENCE, AGENT_LOCAL_KEY_SENTENCE, AGENT_NETWORK_ACCESS_SENTENCE, AGENT_ONBOARDING_PROMPT, AGENT_PAYMENT_FAILURE_CODE_VALUES, AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, AGENT_README_SECTION_MD, AGENT_SECRET_HYGIENE_SENTENCE, AGENT_WIRING_COLLISION_RELAY_SENTENCE, type AgentNextStep, type AgentPaymentEnumSchema, AgentPaymentFailureCode, AgentPaymentFailureCodeDescriptions, AgentPaymentFailureCodeSchema, AgentPaymentNextAction, AgentPaymentNextActionAccountAlias, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, type AgentPaymentNextActionWire, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, type AgentPaymentSummary, type AgentPaymentWarning, AgentPaymentWarningCode, type AgentPurchaseSummary, CONNECTOR_PACKAGE_NAME, type CatalogSubmissionAccepted, type ClaudeTool, DEFAULT_CONFIRMATION_TIMEOUT_MS, DISCOVERY_MAX_BYTES, ERC7710_ASSET_TRANSFER_METHOD, HAVEN_AGENT_RUNBOOK_MD, HAVEN_CONNECTOR_CHANNEL, HAVEN_MINIMUM_NODE_VERSION, HAVEN_SKILL_BODY_MD, HAVEN_SKILL_MD, type HavenAgent, type HavenAgentAllowanceSummary, type HavenAgentReadiness, type HavenAgentSummary, type HavenAllowance, type HavenAllowanceSummary, HavenApiError, type HavenCatalogEntry, type HavenCatalogSubmission, HavenClient, type HavenClientConfig, HavenError, type HavenPaymentReceipt, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, HavenUnsupportedSignerVersionError, MERCHANT_DISCOVERY_PATHS, type MachinePaymentRail, MerchantTimeoutError, type OpenAITool, type PaymentFee, type PaymentIntent, type PaymentNextAction, type PaymentPhase, type PaymentReceipt, type PaymentRequest, type PaymentResult, type PaymentResumeState, type PaymentStatus, type PaymentStatusResult, type PostPurchaseAllowanceSummary, RECEIPT_VERSION, type ReceiptVerification, type ResumeAuthorizedX402Input, type ResumeX402PaymentInput, SIGNER_UPDATE_FALLBACK, SKILL_FOLDER_NAME, SWEEP_BASE_CHAIN_ID, SWEEP_BASE_SEPOLIA_CHAIN_ID, SWEEP_BASE_SEPOLIA_USDC_ADDRESS, SWEEP_BASE_USDC_ADDRESS, type SharedToolKey, type SignData, SignerRefusalCode, type SweepAuthorization, type SweepConfirmation, type SweepEip712Domain, type SweepEntry, type SweepExpectedAuth, type SweepPreparation, type SweepPrepareResponse, type SweepResult, type SweepSubmitResponse, type SweepSubmitResult, type SweepTypedData, TRANSFER_WITH_AUTHORIZATION_TYPES, type ToolDescription, type UnsupportedNodeVersionMessageOptions, X402AlreadySettledError, type X402AuthorizationOptions, type X402Erc7710Settlement, type X402ExpectedAuth, type X402ExpectedContext, type X402Intent, type X402McpCallContext, type X402McpTransport, type X402MerchantCallContext, type X402MerchantOutcome, type X402MerchantOutcomeReport, type X402PaymentHeaderContext, X402PaymentHeaderValidationError, type X402PaymentOption, type X402PaymentRequired, type X402Quote, type X402Receipt, type X402RequestSnapshot, type X402ResumeState, type X402SchemeSelection, X402UnexpectedStatusError, X402_LEGACY_PAYMENT_HEADER_NAME, X402_MAX_AUTHORIZATION_WINDOW_SECONDS, X402_PAYMENT_HEADER_NAME, X402_PAYMENT_HEADER_NAMES_SENT, X402_PAYMENT_REQUIRED_HEADER_NAME, X402_PAYMENT_RESPONSE_HEADER_NAME, X402_SETTLEMENT_FORWARD_MARGIN_SECONDS, accountAddressTwins, addressFromKey, buildSweepAuthorizationMessage, buildSweepTypedData, buildX402ExpectedMessage, canonicalAgentPaymentNextAction, compareNodeVersions, composeDescription, connectorRerunCommand, connectorSpec, decodeBase64Json, decodeBase64Utf8, discoverMerchantMcpUrl, encodeBase64Json, encodeBase64Utf8, encodePaymentProof, havenTools, isConnectorChannel, isErc7710Option, isFundAccountOrRaiseAllowance, isSupportedNodeVersion, isSweepableChain, normalizePaymentRequired, parsePaymentRequired, parsePaymentRequiredResponse, readAccountAddress, readAccountId, readX402ReceiptPayer, resolveConnectorChannel, resolveTokenFromAddress, sameUrl, selectErc7710PaymentOption, selectPaymentOption, selectStandardPaymentOption, selectX402SettlementScheme, signHash, signUserOpTypedDataForDelegation, signerUpdateFallback, sweepUsdcAddress, sweepUsdcDomain, toStandardPaymentRequirements, toolDescriptions, unsupportedNodeVersionMessage, validateStandardX402PaymentHeader, verifyPaymentReceipt, verifySignature, x402AssetTransferMethod, x402AuthorizationAmount, x402FacilitatorAddresses, x402V2PaymentEnvelope };

package/dist/index.d.ts

@@ -23,7 +23,13 @@ interface PaymentReceipt {
         amount: string;
         amountSek: string | null;
         recipient: string;
+        /** @deprecated since #2907 — read `account`; removed in #2914 (the release after the naming window). Same value as `account`. */
         safe: string;
+        /**
+         * The payer's smart-account address (#2907 twin of `safe`). Optional for
+         * the window: a server from before the twin emits `safe` only.
+         */
+        account?: string;
         chainId: number;
         settledAt: string | null;
         resourceUrl: string | null;
@@ -138,7 +144,14 @@ interface SignData {
     };
     /** Breakdown of values that were hashed — useful for debugging */
     components: {
+        /** @deprecated #2908 — same value as `payer_account`; the server drops it at #2914. */
         safe: string;
+        /**
+         * #2907 — the account-vocabulary twin of `safe`: the PAYER account
+         * (the user's smart account). Not to be confused with `account`, which on
+         * the funding shapes holds the DELEGATE account address.
+         */
+        payer_account?: string;
         token: string;
         to: string;
         amount: string;
@@ -522,6 +535,15 @@ interface HavenAgent {
     id: string;
     name: string;
     status: string;
+    /**
+     * The agent's Haven account (smart account) address — #2908, the
+     * account-vocabulary name. Same value as {@link HavenAgent.safeAddress}.
+     */
+    accountAddress: string;
+    /**
+     * @deprecated #2908 — same value as {@link HavenAgent.accountAddress}.
+     * Removed in the release after the one carrying #2908 (#2914).
+     */
     safeAddress: string;
     delegateAddress: string;
     chainId: number;
@@ -563,6 +585,12 @@ interface HavenAllowance {
 }
 interface HavenAllowanceSummary {
     agentId: string;
+    /** #2908 — the account-vocabulary name; same value as `safeAddress`. */
+    accountAddress: string;
+    /**
+     * @deprecated #2908 — same value as {@link HavenAllowanceSummary.accountAddress}.
+     * Removed in the release after the one carrying #2908 (#2914).
+     */
     safeAddress: string;
     delegateAddress: string;
     chainId: number;
@@ -843,9 +871,14 @@ declare const AgentPaymentNextAction: {
      */
     readonly 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}.
      */
     readonly FundSafeOrRaiseAllowance: "fund_safe_or_raise_allowance";
     /**
@@ -856,6 +889,39 @@ declare const AgentPaymentNextAction: {
     readonly SweepStrandedFunds: "sweep_stranded_funds";
 };
 type AgentPaymentNextAction = (typeof AgentPaymentNextAction)[keyof typeof AgentPaymentNextAction];
+/**
+ * #2908 (naming epic #2906): the account-vocabulary twin of
+ * {@link AgentPaymentNextAction.FundSafeOrRaiseAllowance}. The server ACCEPTS
+ * and DOCUMENTS this value from #2907 but keeps EMITTING the old one through
+ * the compatibility window; the emitted value flips at #2914.
+ *
+ * Deliberately declared beside `AgentPaymentNextAction` rather than inside
+ * it: the backend keeps a hand-mirror of that const, parity-pinned key-for-key
+ * and value-for-value (`agent-payment-taxonomy.parity.test.ts`), and the
+ * served `x-enumDescriptions` are the SDK's strings verbatim. Both consts
+ * move together at #2914; until then this alias is how a client handles both
+ * wire values without forking the taxonomy.
+ */
+declare const AgentPaymentNextActionAccountAlias: {
+    /** Account-vocabulary twin of `fund_safe_or_raise_allowance`; same meaning. */
+    readonly FundAccountOrRaiseAllowance: "fund_account_or_raise_allowance";
+};
+type AgentPaymentNextActionAccountAlias = (typeof AgentPaymentNextActionAccountAlias)[keyof typeof AgentPaymentNextActionAccountAlias];
+/** Every `next_action` value a server may put on the wire during the #2908 window. */
+type AgentPaymentNextActionWire = AgentPaymentNextAction | AgentPaymentNextActionAccountAlias;
+/**
+ * Collapse the #2908 account-vocabulary alias onto its canonical taxonomy
+ * value, and pass every other value through untouched.
+ *
+ * This is the one seam a `switch` over `AgentPaymentNextAction` needs: a
+ * case on `FundSafeOrRaiseAllowance` matches a server that emits either
+ * spelling, and no case falls through because the alias arrived. Unknown
+ * strings are returned as-is (the SDK never invents a value), so the return
+ * type is exactly the input type widened by the canonical value.
+ */
+declare function canonicalAgentPaymentNextAction<T extends string | null | undefined>(value: T): Exclude<T, AgentPaymentNextActionAccountAlias> | typeof AgentPaymentNextAction.FundSafeOrRaiseAllowance;
+/** True for EITHER spelling of the fund-or-raise-allowance next action (#2908). */
+declare function isFundAccountOrRaiseAllowance(value: string | null | undefined): boolean;
 declare const AgentPaymentFailureCode: {
     /** A merchant-authoritative x402 price exceeds the caller's pre-funding max_amount cap. */
     readonly PriceExceedsMax: "PRICE_EXCEEDS_MAX";
@@ -992,7 +1058,15 @@ interface AgentPaymentWarning {
  * (payment_required) are named in `reason` and taken from the SAME response.
  */
 interface AgentNextStep {
-    next_action: AgentPaymentNextAction;
+    /**
+     * From `AgentPaymentNextAction`, widened by the #2908 account-vocabulary
+     * alias for the compatibility window: the hosted server keeps emitting
+     * `fund_safe_or_raise_allowance` until #2914, but a client compiled against
+     * this type must not reject `fund_account_or_raise_allowance` when the flip
+     * lands. Compare through {@link canonicalAgentPaymentNextAction} or
+     * {@link isFundAccountOrRaiseAllowance}, never by one literal.
+     */
+    next_action: AgentPaymentNextActionWire;
     /**
      * Claude-family namespaced tool name for the next call
      * (`mcp__<server>__<tool>`), when one exists.
@@ -2234,7 +2308,7 @@ declare const toolDescriptions: {
     readonly getAgent: {
         readonly 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.";
         readonly 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.";
-        readonly behavior: "Reads identity plus the live spend-authority snapshot in one shot — 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 — 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.";
+        readonly behavior: "Reads identity plus the live spend-authority snapshot in one shot — 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 — 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.";
         readonly nextActionGuidance: "";
     };
     readonly getAllowances: {
@@ -2274,7 +2348,7 @@ declare const toolDescriptions: {
         readonly 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.";
     };
     readonly sweep_delegate: {
-        readonly summary: "Sweep stranded USDC and/or ETH from the delegate wallet back to the originating Safe.";
+        readonly summary: "Sweep stranded USDC and/or ETH from the delegate wallet back to the originating account.";
         readonly selectionGuidance: string;
         readonly behavior: string;
         readonly nextActionGuidance: string;
@@ -2710,6 +2784,74 @@ interface UnsupportedNodeVersionMessageOptions {
  */
 declare function unsupportedNodeVersionMessage(options: UnsupportedNodeVersionMessageOptions): string;
 
+/**
+ * #2908 (naming epic #2906, phase 1): the account-vocabulary reads and the
+ * dual-name emissions every published package shares during the one-release
+ * compatibility window.
+ *
+ * The rule, stated once: READ both names and prefer the new; EMIT both names
+ * with the same value; WRITE only the new. The old names on server responses
+ * are removed by #2914, one release after the one that carries this module.
+ * The credential-FILE fallbacks (`safe_address` / `safeAddress` in a file on
+ * disk) are NOT part of that window — they are permanent, because a file that
+ * was written before this release never rewrites itself.
+ *
+ * Kept as tiny pure functions so a reader has exactly one fallback chain per
+ * shape and a test can mutate it: dropping the new name fails the new-shape
+ * test, dropping the old name fails the old-shape test.
+ */
+/**
+ * The account address off a snake_case server shape, new name first.
+ *
+ * `account_address` is the P0 (#2907) twin the server emits beside
+ * `safe_address`; an older server emits only `safe_address`. A missing pair
+ * resolves to `undefined` rather than an empty string so callers can tell
+ * "absent" from "blank".
+ */
+declare function readAccountAddress(raw: {
+    account_address?: string | null;
+    safe_address?: string | null;
+}): string | undefined;
+/**
+ * The account id off a snake_case server shape, new name first
+ * (`account_id`, the #2907 twin of `safe_id`).
+ */
+declare function readAccountId(raw: {
+    account_id?: string | null;
+    safe_id?: string | null;
+}): string | undefined;
+/**
+ * Both camelCase names for one address, for the SDK's public shapes (and the
+ * hosted MCP outputs that spread them). Same value under both keys; the
+ * `safeAddress` key is the deprecated one and goes at #2914.
+ */
+declare function accountAddressTwins(address: string | undefined): {
+    accountAddress: string;
+    safeAddress: string;
+};
+/**
+ * The x402 receipt's `payer` off a funding-authorization response, in the
+ * order the issue pins (#2908): the explicit `payer`, then the top-level
+ * account address (new name, then old), then the `sign_data.components`
+ * twins — `payer_account` (the #2907 twin) before `safe`.
+ *
+ * `components.account` is deliberately NOT in this chain: on the funding
+ * shapes it holds the DELEGATE account address, a different address, and
+ * reading it here would silently corrupt the receipt's payer.
+ */
+declare function readX402ReceiptPayer(raw: {
+    payer?: string;
+    account_address?: string;
+    safe_address?: string;
+    sign_data?: {
+        components?: {
+            payer_account?: string;
+            safe?: string;
+            account?: string;
+        };
+    };
+}): string | undefined;
+
 /**
  * x402 protocol support for the Haven SDK.
  *
@@ -3058,4 +3200,4 @@ declare function discoverMerchantMcpUrl(inputUrl: string): Promise<string | null
 /** Trailing-slash/percent-case echoes compare equal; unparseable never does. */
 declare function sameUrl(a: string, b: string): boolean;
 
-export { AGENT_APPROVAL_RELAY_JSON_SENTENCE, AGENT_APPROVAL_RELAY_PROSE_SENTENCE, AGENT_COMMAND_MODIFICATION_SENTENCE, AGENT_JSON_MODE_SENTENCE, AGENT_LOCAL_KEY_SENTENCE, AGENT_NETWORK_ACCESS_SENTENCE, AGENT_ONBOARDING_PROMPT, AGENT_PAYMENT_FAILURE_CODE_VALUES, AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, AGENT_README_SECTION_MD, AGENT_SECRET_HYGIENE_SENTENCE, AGENT_WIRING_COLLISION_RELAY_SENTENCE, type AgentNextStep, type AgentPaymentEnumSchema, AgentPaymentFailureCode, AgentPaymentFailureCodeDescriptions, AgentPaymentFailureCodeSchema, AgentPaymentNextAction, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, type AgentPaymentSummary, type AgentPaymentWarning, AgentPaymentWarningCode, type AgentPurchaseSummary, CONNECTOR_PACKAGE_NAME, type CatalogSubmissionAccepted, type ClaudeTool, DEFAULT_CONFIRMATION_TIMEOUT_MS, DISCOVERY_MAX_BYTES, ERC7710_ASSET_TRANSFER_METHOD, HAVEN_AGENT_RUNBOOK_MD, HAVEN_CONNECTOR_CHANNEL, HAVEN_MINIMUM_NODE_VERSION, HAVEN_SKILL_BODY_MD, HAVEN_SKILL_MD, type HavenAgent, type HavenAgentAllowanceSummary, type HavenAgentReadiness, type HavenAgentSummary, type HavenAllowance, type HavenAllowanceSummary, HavenApiError, type HavenCatalogEntry, type HavenCatalogSubmission, HavenClient, type HavenClientConfig, HavenError, type HavenPaymentReceipt, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, HavenUnsupportedSignerVersionError, MERCHANT_DISCOVERY_PATHS, type MachinePaymentRail, MerchantTimeoutError, type OpenAITool, type PaymentFee, type PaymentIntent, type PaymentNextAction, type PaymentPhase, type PaymentReceipt, type PaymentRequest, type PaymentResult, type PaymentResumeState, type PaymentStatus, type PaymentStatusResult, type PostPurchaseAllowanceSummary, RECEIPT_VERSION, type ReceiptVerification, type ResumeAuthorizedX402Input, type ResumeX402PaymentInput, SIGNER_UPDATE_FALLBACK, SKILL_FOLDER_NAME, SWEEP_BASE_CHAIN_ID, SWEEP_BASE_SEPOLIA_CHAIN_ID, SWEEP_BASE_SEPOLIA_USDC_ADDRESS, SWEEP_BASE_USDC_ADDRESS, type SharedToolKey, type SignData, SignerRefusalCode, type SweepAuthorization, type SweepConfirmation, type SweepEip712Domain, type SweepEntry, type SweepExpectedAuth, type SweepPreparation, type SweepPrepareResponse, type SweepResult, type SweepSubmitResponse, type SweepSubmitResult, type SweepTypedData, TRANSFER_WITH_AUTHORIZATION_TYPES, type ToolDescription, type UnsupportedNodeVersionMessageOptions, X402AlreadySettledError, type X402AuthorizationOptions, type X402Erc7710Settlement, type X402ExpectedAuth, type X402ExpectedContext, type X402Intent, type X402McpCallContext, type X402McpTransport, type X402MerchantCallContext, type X402MerchantOutcome, type X402MerchantOutcomeReport, type X402PaymentHeaderContext, X402PaymentHeaderValidationError, type X402PaymentOption, type X402PaymentRequired, type X402Quote, type X402Receipt, type X402RequestSnapshot, type X402ResumeState, type X402SchemeSelection, X402UnexpectedStatusError, X402_LEGACY_PAYMENT_HEADER_NAME, X402_MAX_AUTHORIZATION_WINDOW_SECONDS, X402_PAYMENT_HEADER_NAME, X402_PAYMENT_HEADER_NAMES_SENT, X402_PAYMENT_REQUIRED_HEADER_NAME, X402_PAYMENT_RESPONSE_HEADER_NAME, X402_SETTLEMENT_FORWARD_MARGIN_SECONDS, addressFromKey, buildSweepAuthorizationMessage, buildSweepTypedData, buildX402ExpectedMessage, compareNodeVersions, composeDescription, connectorRerunCommand, connectorSpec, decodeBase64Json, decodeBase64Utf8, discoverMerchantMcpUrl, encodeBase64Json, encodeBase64Utf8, encodePaymentProof, havenTools, isConnectorChannel, isErc7710Option, isSupportedNodeVersion, isSweepableChain, normalizePaymentRequired, parsePaymentRequired, parsePaymentRequiredResponse, resolveConnectorChannel, resolveTokenFromAddress, sameUrl, selectErc7710PaymentOption, selectPaymentOption, selectStandardPaymentOption, selectX402SettlementScheme, signHash, signUserOpTypedDataForDelegation, signerUpdateFallback, sweepUsdcAddress, sweepUsdcDomain, toStandardPaymentRequirements, toolDescriptions, unsupportedNodeVersionMessage, validateStandardX402PaymentHeader, verifyPaymentReceipt, verifySignature, x402AssetTransferMethod, x402AuthorizationAmount, x402FacilitatorAddresses, x402V2PaymentEnvelope };
+export { AGENT_APPROVAL_RELAY_JSON_SENTENCE, AGENT_APPROVAL_RELAY_PROSE_SENTENCE, AGENT_COMMAND_MODIFICATION_SENTENCE, AGENT_JSON_MODE_SENTENCE, AGENT_LOCAL_KEY_SENTENCE, AGENT_NETWORK_ACCESS_SENTENCE, AGENT_ONBOARDING_PROMPT, AGENT_PAYMENT_FAILURE_CODE_VALUES, AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, AGENT_README_SECTION_MD, AGENT_SECRET_HYGIENE_SENTENCE, AGENT_WIRING_COLLISION_RELAY_SENTENCE, type AgentNextStep, type AgentPaymentEnumSchema, AgentPaymentFailureCode, AgentPaymentFailureCodeDescriptions, AgentPaymentFailureCodeSchema, AgentPaymentNextAction, AgentPaymentNextActionAccountAlias, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, type AgentPaymentNextActionWire, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, type AgentPaymentSummary, type AgentPaymentWarning, AgentPaymentWarningCode, type AgentPurchaseSummary, CONNECTOR_PACKAGE_NAME, type CatalogSubmissionAccepted, type ClaudeTool, DEFAULT_CONFIRMATION_TIMEOUT_MS, DISCOVERY_MAX_BYTES, ERC7710_ASSET_TRANSFER_METHOD, HAVEN_AGENT_RUNBOOK_MD, HAVEN_CONNECTOR_CHANNEL, HAVEN_MINIMUM_NODE_VERSION, HAVEN_SKILL_BODY_MD, HAVEN_SKILL_MD, type HavenAgent, type HavenAgentAllowanceSummary, type HavenAgentReadiness, type HavenAgentSummary, type HavenAllowance, type HavenAllowanceSummary, HavenApiError, type HavenCatalogEntry, type HavenCatalogSubmission, HavenClient, type HavenClientConfig, HavenError, type HavenPaymentReceipt, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, HavenUnsupportedSignerVersionError, MERCHANT_DISCOVERY_PATHS, type MachinePaymentRail, MerchantTimeoutError, type OpenAITool, type PaymentFee, type PaymentIntent, type PaymentNextAction, type PaymentPhase, type PaymentReceipt, type PaymentRequest, type PaymentResult, type PaymentResumeState, type PaymentStatus, type PaymentStatusResult, type PostPurchaseAllowanceSummary, RECEIPT_VERSION, type ReceiptVerification, type ResumeAuthorizedX402Input, type ResumeX402PaymentInput, SIGNER_UPDATE_FALLBACK, SKILL_FOLDER_NAME, SWEEP_BASE_CHAIN_ID, SWEEP_BASE_SEPOLIA_CHAIN_ID, SWEEP_BASE_SEPOLIA_USDC_ADDRESS, SWEEP_BASE_USDC_ADDRESS, type SharedToolKey, type SignData, SignerRefusalCode, type SweepAuthorization, type SweepConfirmation, type SweepEip712Domain, type SweepEntry, type SweepExpectedAuth, type SweepPreparation, type SweepPrepareResponse, type SweepResult, type SweepSubmitResponse, type SweepSubmitResult, type SweepTypedData, TRANSFER_WITH_AUTHORIZATION_TYPES, type ToolDescription, type UnsupportedNodeVersionMessageOptions, X402AlreadySettledError, type X402AuthorizationOptions, type X402Erc7710Settlement, type X402ExpectedAuth, type X402ExpectedContext, type X402Intent, type X402McpCallContext, type X402McpTransport, type X402MerchantCallContext, type X402MerchantOutcome, type X402MerchantOutcomeReport, type X402PaymentHeaderContext, X402PaymentHeaderValidationError, type X402PaymentOption, type X402PaymentRequired, type X402Quote, type X402Receipt, type X402RequestSnapshot, type X402ResumeState, type X402SchemeSelection, X402UnexpectedStatusError, X402_LEGACY_PAYMENT_HEADER_NAME, X402_MAX_AUTHORIZATION_WINDOW_SECONDS, X402_PAYMENT_HEADER_NAME, X402_PAYMENT_HEADER_NAMES_SENT, X402_PAYMENT_REQUIRED_HEADER_NAME, X402_PAYMENT_RESPONSE_HEADER_NAME, X402_SETTLEMENT_FORWARD_MARGIN_SECONDS, accountAddressTwins, addressFromKey, buildSweepAuthorizationMessage, buildSweepTypedData, buildX402ExpectedMessage, canonicalAgentPaymentNextAction, compareNodeVersions, composeDescription, connectorRerunCommand, connectorSpec, decodeBase64Json, decodeBase64Utf8, discoverMerchantMcpUrl, encodeBase64Json, encodeBase64Utf8, encodePaymentProof, havenTools, isConnectorChannel, isErc7710Option, isFundAccountOrRaiseAllowance, isSupportedNodeVersion, isSweepableChain, normalizePaymentRequired, parsePaymentRequired, parsePaymentRequiredResponse, readAccountAddress, readAccountId, readX402ReceiptPayer, resolveConnectorChannel, resolveTokenFromAddress, sameUrl, selectErc7710PaymentOption, selectPaymentOption, selectStandardPaymentOption, selectX402SettlementScheme, signHash, signUserOpTypedDataForDelegation, signerUpdateFallback, sweepUsdcAddress, sweepUsdcDomain, toStandardPaymentRequirements, toolDescriptions, unsupportedNodeVersionMessage, validateStandardX402PaymentHeader, verifyPaymentReceipt, verifySignature, x402AssetTransferMethod, x402AuthorizationAmount, x402FacilitatorAddresses, x402V2PaymentEnvelope };