@haven_ai/sdk 0.1.14-alpha.0 → 0.1.16-alpha.0

package/dist/index.d.cts

@@ -109,6 +109,7 @@ interface X402PaymentRequired {
     };
     accepts: X402PaymentOption[];
     error?: string;
+    extensions?: Record<string, unknown>;
 }
 /** A single payment option from x402 PaymentRequired. */
 interface X402PaymentOption {
@@ -173,6 +174,8 @@ interface X402AuthorizationOptions {
 interface X402Intent {
     /** Haven payment id for the funding transfer. */
     paymentId: string;
+    /** Stable key used to create or refresh this x402 funding intent. */
+    idempotencyKey: string;
     status: 'pending_signature';
     /** ISO 8601 expiry of the funding intent, if returned. */
     expiresAt?: string;
@@ -203,6 +206,8 @@ interface X402ExpectedContext {
     amount: string;
     asset: string;
     network: string;
+    /** Optional ISO expiry for the funding/quote window. When present, it is bound into the Haven-authenticated context. */
+    expiresAt?: string;
 }
 interface X402ExpectedAuth {
     version: 1;
@@ -217,6 +222,10 @@ interface X402RequestSnapshot {
     headers: [string, string][];
     body?: string;
 }
+interface X402McpTransport {
+    handshakeRequired: boolean;
+    source: 'path' | 'bazaar';
+}
 /** Quote parsed from an HTTP 402 response without creating a Haven payment. */
 interface X402Quote {
     rail: 'x402';
@@ -224,6 +233,7 @@ interface X402Quote {
     paymentRequired: X402PaymentRequired;
     accepted: X402PaymentOption;
     request: X402RequestSnapshot;
+    mcpTransport?: X402McpTransport;
     resourceUrl: string;
     description: string | null;
     mimeType: string | null;
@@ -405,6 +415,44 @@ interface HavenAllowanceSummary {
     chainId: number;
     allowances: HavenAllowance[];
 }
+/**
+ * Affirmative spend-readiness for the authenticated agent, derived from the raw
+ * agent status plus the on-chain remaining allowance:
+ * - `ready`         — active and at least one token has remaining on-chain allowance.
+ * - `needs_approval`— active but no remaining allowance to auto-spend; payments
+ *                     will be queued for the wallet owner to approve in Haven.
+ * - `revoked`       — the agent's status is not `active`; nothing auto-executes.
+ *
+ * Note: a hard-paused/disabled credential is rejected by the API before this
+ * call returns, so it surfaces as an API error rather than `revoked`. `revoked`
+ * is reached when the request authenticates but the agent status is non-active.
+ *
+ * Wallet token balance is intentionally NOT folded in here: the on-chain
+ * remaining allowance is the gate Haven enforces, and insufficient wallet
+ * funding surfaces at pay time as INSUFFICIENT_FUNDS.
+ */
+type HavenAgentReadiness = 'ready' | 'needs_approval' | 'revoked';
+/** Compact, agent-facing per-token spend authority for the bootstrap summary. */
+interface HavenAgentAllowanceSummary {
+    tokenSymbol: string;
+    /** Live on-chain remaining allowance in atomic units. */
+    remainingAtomic: string;
+    /** Human-readable remaining, e.g. "4.96 USDC". */
+    remainingDisplay: string;
+    /** Configured allowance amount (atomic) the owner granted. */
+    configuredAmount: string;
+    resetPeriodMin: number;
+    isResetPending: boolean;
+}
+/**
+ * One-shot "am I ready?" bootstrap: identity + live spend authority + a
+ * readiness signal, so an agent can answer "who am I and can I pay right now"
+ * from a single call at session start. Superset of {@link HavenAgent}.
+ */
+interface HavenAgentSummary extends HavenAgent {
+    readiness: HavenAgentReadiness;
+    allowances: HavenAgentAllowanceSummary[];
+}
 interface HavenPaymentReceipt {
     id: string;
     paymentId: string;
@@ -520,6 +568,11 @@ declare const AgentPaymentNextAction: {
     readonly StopAndTellUser: "stop_and_tell_user";
     /** Ask again only if the user still wants the payment after expiry. */
     readonly RequestAgainIfUserStillWantsIt: "request_again_if_user_still_wants_it";
+    /**
+     * The x402 funding/quote window expired. Re-quote the same logical merchant
+     * operation with the same idempotency key to stay double-charge-safe.
+     */
+    readonly PaymentWindowExpired: "payment_window_expired";
     /**
      * Stop and tell the user that the originating Safe needs to be funded or
      * the agent's per-token allowance needs to be raised before the payment
@@ -534,6 +587,15 @@ declare const AgentPaymentNextAction: {
     readonly SweepStrandedFunds: "sweep_stranded_funds";
 };
 type AgentPaymentNextAction = (typeof AgentPaymentNextAction)[keyof typeof AgentPaymentNextAction];
+declare const AgentPaymentFailureCode: {
+    /** A merchant-authoritative x402 price exceeds the caller's pre-funding max_amount cap. */
+    readonly PriceExceedsMax: "PRICE_EXCEEDS_MAX";
+    /** The x402 funding/quote window expired before the signer or hosted settle step could finish. */
+    readonly PaymentWindowExpired: "PAYMENT_WINDOW_EXPIRED";
+    /** The Haven funding leg succeeded, but the merchant rejected the paid retry. */
+    readonly MerchantRejectedAfterFunding: "MERCHANT_REJECTED_AFTER_FUNDING";
+};
+type AgentPaymentFailureCode = (typeof AgentPaymentFailureCode)[keyof typeof AgentPaymentFailureCode];
 /**
  * Stable rail identifier carried on Haven agent payment responses and resume
  * state.
@@ -572,13 +634,16 @@ type AgentPaymentRail = (typeof AgentPaymentRail)[keyof typeof AgentPaymentRail]
 type PaymentPhase = AgentPaymentPhase;
 type PaymentNextAction = AgentPaymentNextAction;
 declare const AGENT_PAYMENT_PHASE_VALUES: ("rejected" | "expired" | "failed" | "agent_signature_required" | "payment_submitted" | "payment_confirmed" | "user_approval_required" | "user_execution_required" | "waiting_for_additional_approvals" | "funding_sent" | "insufficient_funds" | "funded_but_unsettled")[];
-declare const AGENT_PAYMENT_NEXT_ACTION_VALUES: ("sign_and_submit_payment" | "check_status_later" | "none" | "wait_for_user_approval" | "wait_for_user_to_complete_payment" | "retry_original_x402_request" | "stop_and_tell_user" | "request_again_if_user_still_wants_it" | "fund_safe_or_raise_allowance" | "sweep_stranded_funds")[];
+declare const AGENT_PAYMENT_NEXT_ACTION_VALUES: ("sign_and_submit_payment" | "check_status_later" | "none" | "wait_for_user_approval" | "wait_for_user_to_complete_payment" | "retry_original_x402_request" | "stop_and_tell_user" | "request_again_if_user_still_wants_it" | "payment_window_expired" | "fund_safe_or_raise_allowance" | "sweep_stranded_funds")[];
+declare const AGENT_PAYMENT_FAILURE_CODE_VALUES: ("PRICE_EXCEEDS_MAX" | "PAYMENT_WINDOW_EXPIRED" | "MERCHANT_REJECTED_AFTER_FUNDING")[];
 declare const AGENT_PAYMENT_RAIL_VALUES: ("x402" | "mpp" | "mpp_demo" | "mpp_crypto" | "stripe_deposit" | "spt" | "direct")[];
 declare const AgentPaymentPhaseDescriptions: Record<AgentPaymentPhase, string>;
 declare const AgentPaymentNextActionDescriptions: Record<AgentPaymentNextAction, string>;
+declare const AgentPaymentFailureCodeDescriptions: Record<AgentPaymentFailureCode, string>;
 declare const AgentPaymentRailDescriptions: Record<AgentPaymentRail, string>;
 declare const AgentPaymentPhaseSchema: AgentPaymentEnumSchema;
 declare const AgentPaymentNextActionSchema: AgentPaymentEnumSchema;
+declare const AgentPaymentFailureCodeSchema: AgentPaymentEnumSchema;
 declare const AgentPaymentRailSchema: AgentPaymentEnumSchema;
 interface PaymentStatusResult {
     paymentId: string;
@@ -671,6 +736,166 @@ declare class HavenTimeoutError extends HavenError {
     constructor(paymentId: string);
 }
 
+/**
+ * Gasless delegate-sweep primitives — the single source of truth shared by the
+ * edge signer (which signs) and the Haven backend (which relays).
+ *
+ * A stranded delegate EOA holds USDC but no ETH, so a raw ERC-20 transfer can't
+ * pay for its own gas. Instead the delegate signs an *off-chain* EIP-3009
+ * `TransferWithAuthorization` and the Haven relayer submits it on-chain and pays
+ * gas. The relayer is only a gas payer: it holds no allowance and is never a
+ * spender, so a relayer compromise cannot move user funds.
+ *
+ * Framework-neutral on purpose: `buildSweepTypedData` returns a plain
+ * `{ domain, types, primaryType, message }` that both viem
+ * (`signTypedData`/`recoverTypedDataAddress`) and ethers v6
+ * (`signTypedData`/`verifyTypedData`) accept, so the signer (viem) and backend
+ * (ethers) stay in lockstep without sharing a crypto library.
+ */
+/** Base mainnet. The only chain Haven sweeps today. */
+declare const SWEEP_BASE_CHAIN_ID = 8453;
+/** Canonical Circle USDC on Base (FiatTokenV2_2). */
+declare const SWEEP_BASE_USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+/** EIP-712 `TransferWithAuthorization` struct, per EIP-3009. */
+declare const TRANSFER_WITH_AUTHORIZATION_TYPES: {
+    readonly TransferWithAuthorization: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "value";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validAfter";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validBefore";
+        readonly type: "uint256";
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }];
+};
+interface SweepEip712Domain {
+    name: string;
+    version: string;
+    chainId: number;
+    verifyingContract: string;
+}
+/**
+ * A fully-specified EIP-3009 authorization. All amounts/times are decimal
+ * strings (JSON-safe) and `nonce` is a 0x-prefixed 32-byte hex value. `token`
+ * and `chainId` are carried explicitly so the signer can assert they are
+ * canonical before signing.
+ */
+interface SweepAuthorization {
+    /** Delegate EOA the funds are swept FROM. */
+    from: string;
+    /** Originating Safe the funds are swept TO. */
+    to: string;
+    /** Atomic USDC amount (decimal string). */
+    value: string;
+    /** Unix seconds the authorization becomes valid (decimal string, usually "0"). */
+    validAfter: string;
+    /** Unix seconds the authorization expires (decimal string). */
+    validBefore: string;
+    /** Random 0x-prefixed 32-byte hex nonce. */
+    nonce: string;
+    /** USDC contract address. */
+    token: string;
+    /** Chain id (8453 today). */
+    chainId: number;
+}
+/**
+ * Haven's signature over the sweep authorization context, signed with the same
+ * binding key the x402 expected-context uses. Lets the edge signer verify the
+ * authorization actually came from Haven (and wasn't crafted by a compromised
+ * hosted server pointing `to` at an attacker) before it signs.
+ */
+interface SweepExpectedAuth {
+    version: 1;
+    message: string;
+    signature: string;
+    signer: string;
+}
+/** What `POST /machine-payments/sweep/prepare` returns when funds are stranded. */
+interface SweepPreparation {
+    authorization: SweepAuthorization;
+    expectedAuth: SweepExpectedAuth;
+}
+/** Wire response from `POST /machine-payments/sweep/prepare` (snake_case). */
+interface SweepPrepareResponse {
+    /** Present and true when the delegate holds nothing to recover. */
+    nothing_stranded?: boolean;
+    /** The authorization to sign — absent when nothing is stranded. */
+    authorization?: SweepAuthorization;
+    /** Haven's binding over the authorization — absent when nothing is stranded. */
+    expected_auth?: SweepExpectedAuth;
+    asset?: string;
+    amount?: string;
+    amount_atomic?: string;
+    chain_id: number;
+    sign_instructions?: string;
+    message?: string;
+}
+/** Wire response from `POST /machine-payments/sweep/submit` (snake_case). */
+interface SweepSubmitResponse {
+    tx_hash: string;
+    asset: string;
+    amount: string;
+    amount_atomic: string;
+    from_address: string;
+    to_address: string;
+    chain_id: number;
+    explorer_url: string;
+    idempotent_replay?: boolean;
+}
+/** Result of a submitted gasless sweep. */
+interface SweepSubmitResult {
+    txHash: string;
+    amount: string;
+    amountAtomic: string;
+    asset: string;
+    fromAddress: string;
+    toAddress: string;
+    chainId: number;
+    explorerUrl: string;
+}
+interface SweepTypedData {
+    domain: SweepEip712Domain;
+    types: typeof TRANSFER_WITH_AUTHORIZATION_TYPES;
+    primaryType: 'TransferWithAuthorization';
+    message: {
+        from: string;
+        to: string;
+        value: bigint;
+        validAfter: bigint;
+        validBefore: bigint;
+        nonce: string;
+    };
+}
+/** Resolve the canonical USDC contract for a sweepable chain, or throw. */
+declare function sweepUsdcAddress(chainId: number): string;
+/** Resolve the USDC EIP-712 domain for a sweepable chain, or throw. */
+declare function sweepUsdcDomain(chainId: number): SweepEip712Domain;
+/**
+ * Build the EIP-712 typed data for an authorization, validating that the token
+ * and chain are canonical (the domain's `verifyingContract` must match the
+ * authorization's `token`). Returns bigint-valued fields so both viem and
+ * ethers v6 sign/recover identically.
+ */
+declare function buildSweepTypedData(auth: SweepAuthorization): SweepTypedData;
+/**
+ * Canonical, deterministic string the backend signs and the signer re-derives
+ * for the authorization binding. The `Haven sweep authorization v1` namespace
+ * (and `kind`) is distinct from the x402 expected-context namespace so an x402
+ * binding can never be replayed as a sweep authorization even though they share
+ * a signing key.
+ */
+declare function buildSweepAuthorizationMessage(auth: SweepAuthorization): string;
+
 declare class HavenClient {
     private readonly apiKey;
     private readonly delegateKey;
@@ -780,6 +1005,14 @@ declare class HavenClient {
      * Get the agent identity tied to this API key.
      */
     getAgent(): Promise<HavenAgent>;
+    /**
+     * One-shot "am I ready?" bootstrap: identity + live spend authority + a
+     * readiness signal, in a single call. Folds {@link getAgent} and
+     * {@link getAllowances} together and derives a {@link HavenAgentReadiness}
+     * so an agent can answer "who am I and can I pay right now" at session start
+     * without two round trips and manual assembly.
+     */
+    getAgentSummary(): Promise<HavenAgentSummary>;
     /**
      * Sweep stranded USDC and ETH from the delegate EOA back to the originating Safe.
      *
@@ -790,6 +1023,23 @@ declare class HavenClient {
      * Requires `chainRpcs` to be set for the agent's chain in `HavenClientConfig`.
      */
     sweepDelegate(): Promise<SweepResult>;
+    /**
+     * Hosted (keyless) split-signer sweep — step 1 of 2.
+     *
+     * Asks the backend to build a gasless EIP-3009 sweep authorization for the
+     * delegate's stranded USDC. Returns `nothing_stranded` when the delegate is
+     * empty, otherwise an `authorization` + Haven `expected_auth` to hand to the
+     * edge signer's `haven_sign_sweep_delegate`. No key is required on this client.
+     */
+    prepareSweep(): Promise<SweepPrepareResponse>;
+    /**
+     * Hosted (keyless) split-signer sweep — step 2 of 2.
+     *
+     * Relays the delegate-signed authorization. The Haven relayer submits the
+     * on-chain `transferWithAuthorization` and pays gas; this client never holds
+     * the key.
+     */
+    submitSweep(authorization: SweepAuthorization, signature: string): Promise<SweepSubmitResponse>;
     /**
      * Get configured and on-chain allowances for the authenticated agent.
      */
@@ -913,27 +1163,39 @@ declare class HavenClient {
      * amount/merchant/nonce-bound EIP-3009 authorization the edge signer already
      * produced — the hosted server cannot mint or reuse signing authority.
      *
-     * When the URL is MCP-shaped (`/mcp` path), runs a fresh `initialize`
+     * When the URL is MCP-shaped (`/mcp` path) or the quote-time transport context
+     * says the merchant was Bazaar-discoverable, runs a fresh `initialize`
      * handshake (the quote-time session is gone once funding confirms; the x402
      * challenge is stateless w.r.t. the MCP session, so a fresh session is
      * accepted), threads the session + wallet headers, sets `X-PAYMENT`, and
      * collapses an SSE JSON-RPC response to its `result`.
-     *
-     * Limitation: detects MCP only by the `/mcp` path convention, not the
-     * Coinbase Bazaar `extensions.bazaar` 402 signal that `fetch()` also honors.
-     * A Bazaar-discoverable merchant on a non-`/mcp` URL would need the standard
-     * `fetch()` path. All current MCP-tool merchants use the `/mcp` convention.
      */
+    /**
+     * Wait for a payment's Safe→delegate funding tx to reach ≥1 on-chain
+     * confirmation. The hosted x402 completion path MUST call this after funding
+     * and before delivering the X-PAYMENT header, so the merchant's
+     * balanceOf(delegate) / transferWithAuthorization verification sees the funded
+     * balance — otherwise it rejects with "Payment verification failed". The
+     * SDK's local path already does this (see authorizeStandardX402); the hosted
+     * split flow regressed when the 5→3 collapse removed the incidental
+     * inter-call latency that used to mask it. No-op when the funding tx hash or
+     * a chain RPC (chainRpcs[chainId]) is unavailable.
+     */
+    ensureFundingConfirmed(paymentId: string, fundingTxHash?: string): Promise<void>;
     completeX402MerchantCall(input: {
         url: string;
         init?: RequestInit;
+        paymentId: string;
         paymentHeader: string;
+        mcpTransport?: X402McpTransport;
     }): Promise<{
         status: number;
         ok: boolean;
         body: unknown;
         settlementTxHash?: string;
     }>;
+    private resolveX402MerchantCompletionContext;
+    private resolveX402WalletForMerchantCall;
     authorizeMachinePayment(challenge: MachinePaymentChallenge, options?: MppAuthorizationOptions): Promise<MachinePaymentReceipt>;
     private authorizeMppDemoPayment;
     resumeAuthorizedMpp(input: ResumeAuthorizedMppInput): Promise<MachinePaymentReceipt>;
@@ -970,6 +1232,7 @@ declare class HavenClient {
     private requestInitFromSnapshot;
     private withX402Wallet;
     private buildX402Quote;
+    private detectX402McpTransport;
     private buildX402ResumeState;
     private buildMppQuote;
     private buildMppResumeState;
@@ -1159,8 +1422,9 @@ declare const toolDescriptions: {
         readonly nextActionGuidance: "";
     };
     readonly getAgent: {
-        readonly summary: "Return the authenticated agent identity, Haven wallet, delegate address, chain, and status.";
-        readonly behavior: "Read-only identity lookup. Useful for verifying which on-chain Safe and delegate the credential is bound to.";
+        readonly 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.";
+        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 on-chain AllowanceModule snapshot in one shot. readiness is \"ready\" when at least one token has remaining on-chain allowance, \"needs_approval\" when the agent is active but has no remaining allowance to auto-spend (payments will be queued for the wallet owner to approve in Haven), and \"revoked\" when the credential is not active. allowances[] carries remainingAtomic and remainingDisplay per token. Identity fields (id, name, status, safeAddress, delegateAddress, chainId) are unchanged from before.";
         readonly nextActionGuidance: "";
     };
     readonly getAllowances: {
@@ -1185,7 +1449,7 @@ declare const toolDescriptions: {
         readonly summary: "Discover payable services from Haven's curated merchant catalog — names, prices, and which pay tool to use.";
         readonly selectionGuidance: string;
         readonly behavior: string;
-        readonly nextActionGuidance: "Pick an entry, confirm the price with the user if it is non-trivial, and pay it with the tool named in suggested_tool, passing the entry's resource_url (and tool_name for MCP merchants).";
+        readonly nextActionGuidance: "Pick an entry and pay it with the tool named in suggested_tool, passing the entry's resource_url (and tool_name for MCP merchants). Confirm the price from the live pay-tool result (not the catalog), and pass max_amount when the user has a cap.";
     };
     readonly sweep_delegate: {
         readonly summary: "Sweep stranded USDC and/or ETH from the delegate wallet back to the originating Safe.";
@@ -1207,10 +1471,12 @@ type SharedToolKey = keyof typeof toolDescriptions;
  *
  * This SDK file is the single source of truth for the generic, secret-free
  * skill content: no wallet address, no budget numbers, no per-agent values.
- * The agent learns its identity and live budget at runtime via the
- * `haven_get_agent` / `haven_get_allowances` MCP tools, so the same file works
- * for every user. `packages/connect` imports this directly to auto-install the
- * skill into runtime skills folders.
+ * The agent learns its live budget at runtime via the `haven_get_agent` /
+ * `haven_get_allowances` MCP tools, and can read identity + configured budget
+ * for fast first-turn orientation from the non-secret `agent.json` the
+ * connector writes (see `packages/connect/src/storage.ts`), so the same file
+ * works for every user. `packages/connect` imports this directly to
+ * auto-install the skill into runtime skills folders.
  *
  * `packages/frontend/src/lib/agent-skill-bundle.ts` keeps a deliberately
  * decoupled inline copy (the download fallback): frontend has zero
@@ -1219,7 +1485,7 @@ type SharedToolKey = keyof typeof toolDescriptions;
  * this canonical string and asserts byte-for-byte equality, so the two copies
  * cannot drift.
  */
-declare const HAVEN_SKILL_MD = "---\nname: haven-pay\ndescription: Pay for things from the user's Haven wallet within their agent rules. Use when the user asks to send, pay, tip, or transfer crypto \u2014 or when a request hits an HTTP 402 (x402) paywall.\n---\n\n# Haven: pay from a Haven wallet\n\nThis skill lets the agent make payments from the user's Haven wallet through\nthe Haven MCP tools. Every payment is checked against the agent's on-chain\nbudget before money moves; payments above the remaining budget wait for the\nuser's approval in Haven.\n\n## When to use this skill\n\n- The user asks to send money, pay someone, tip, donate, or transfer tokens.\n- A request returns HTTP 402 (x402): use the Haven pay tools to settle it,\n  then retry the original request.\n\n## Identity and budget come from the tools \u2014 never assume them\n\nDo not guess the wallet address, network, or budget. Read them live:\n\n- `haven_get_agent` \u2014 agent identity, Haven wallet address, network.\n- `haven_get_allowances` \u2014 current per-token budgets and what remains.\n\nBudgets reset on a period the user chose. If a payment exceeds the remaining\nbudget it is queued for the user to approve in the Haven dashboard \u2014 this is\nnormal, not an error.\n\n## Paying\n\n- **Direct transfer:** `haven_pay` with recipient, amount, and token.\n- **x402 paywall:** `haven_quote_x402` to get a quote, then\n  `haven_pay_x402_quote`. In the hosted setup the signing step happens in\n  the local Haven signer; follow the tool results \u2014 they tell you the next\n  action at every step. Retry the original request only when the result says\n  `retry_original_x402_request`.\n- **Paid MCP tool call:** `haven_pay_mcp_tool` with the merchant URL, tool\n  name, and arguments. Then follow the returned steps: `haven_sign` the\n  funding hash, `haven_submit` the signature, `haven_x402_sign_header` to\n  build the payment header, and finally `haven_complete_mcp_tool` to settle\n  with the merchant and get the tool result. Pass `payment_required` and\n  `arguments` through verbatim from the `haven_pay_mcp_tool` result. Do not\n  call the merchant yourself \u2014 Haven completes the merchant leg for you.\n- **Status:** `haven_get_payment_status` with a `payment_id` to check on\n  queued or in-flight payments. Do not poll in a tight loop.\n\n## Approval semantics\n\n- A result with `pending_approval` means the payment exceeded the remaining\n  budget and is waiting for the user in Haven. Tell the user, then check\n  status later.\n- Never ask the user for private keys and never try to sign anything\n  yourself \u2014 Haven signs. If a tool reports a missing or invalid credential,\n  tell the user to re-run the Haven setup command.\n\n## Failure handling\n\nHaven errors are shaped `{ error, status, details? }` and written for\nhumans \u2014 surface the message verbatim. Common cases:\n\n- `pending_approval`: queued for the user's approval (see above).\n- `insufficient_funds`: the Haven wallet doesn't hold enough of that token.\n  Suggest the user add funds in the Haven dashboard.\n- Budget exceeded: tell the user how much remains (from\n  `haven_get_allowances`) and that they can raise the budget in Haven.\n\n## Revoke\n\nIf this agent's credential may have leaked, tell the user to pause or revoke\nthe agent in the Haven dashboard under Agents. New requests stop immediately\nfor that credential.\n";
+declare const HAVEN_SKILL_MD = "---\nname: haven-pay\ndescription: Pay for things from the user's Haven wallet within their agent rules. Use when the user asks to send, pay, tip, or transfer crypto \u2014 or when a request hits an HTTP 402 (x402) paywall.\n---\n\n# Haven: pay from a Haven wallet\n\nThis skill lets the agent make payments from the user's Haven wallet through\nthe Haven MCP tools. Every payment is checked against the agent's on-chain\nbudget before money moves; payments above the remaining budget wait for the\nuser's approval in Haven.\n\nHosted tools run in the `mcp__haven__` namespace. Local signing tools run in\nthe `mcp__haven-signer__` namespace and keep the delegate key on this machine.\n\n## When to use this skill\n\n- The user asks to send money, pay someone, tip, donate, or transfer tokens.\n- A request returns HTTP 402 (x402): use the Haven pay tools to settle it,\n  then retry the original request.\n\n## Identity and budget\n\nDo not guess the wallet address, network, or budget.\n\nFor instant orientation at the start of a session, read the non-secret\n`agent.json` the connector wrote to your Haven credential directory (typically\n`~/.haven/agents/<agent-id>/agent.json` \u2014 if you don't know the agent id, list\n`~/.haven/agents/` to find the folder). It\nholds your agent id, Haven wallet address, network, and *configured* per-token\nbudget, and contains no keys \u2014 the fastest way to answer \"who am I and what may\nI spend\" with no round trip. If that file is absent (some setups don't write\nit), use the tools below instead.\n\nBefore any payment, confirm the *live remaining* budget with the tools \u2014\n`agent.json` shows the configured budget, not what is left after recent\nspending:\n\n- `haven_get_agent` \u2014 the recommended first call: identity (wallet, network)\n  plus a readiness signal (`ready` / `needs_approval` / `revoked`) and live\n  remaining per-token allowance, in one shot.\n- `haven_get_allowances` \u2014 detailed per-token breakdown (configured, spent,\n  reset window) when you need more than the summary.\n\nBudgets reset on a period the user chose. If a payment exceeds the remaining\nbudget it is queued for the user to approve in the Haven dashboard \u2014 this is\nnormal, not an error.\n\n## Paying\n\n- **Direct transfer:** `haven_pay` with recipient, amount, and token.\n- **x402 paywall:** `haven_quote_x402` to get a quote, then\n  `haven_pay_x402_quote`. In the hosted setup the signing step happens in\n  the local Haven signer; follow the tool results \u2014 they tell you the next\n  action at every step. Retry the original request only when the result says\n  `retry_original_x402_request`.\n- **Paid MCP tool call:** `mcp__haven__haven_pay_mcp_tool` with the merchant\n  URL, tool name, and arguments, then finish in two calls (fast path):\n  `mcp__haven-signer__haven_sign_x402` on the local signer (pass\n  `payload_hash`, `x402_expected` as the nested `x402.expected` object, and\n  `payment_required`) returns `{ signature, payment_header }`; then\n  `mcp__haven__haven_settle_mcp_tool` (pass `payment_id`, `signature`,\n  `payment_header`, `merchant_url`, `tool_name`, `arguments`,\n  `mcp_transport`) funds and settles in one step and returns the tool result.\n  If it returns `settled: false`, funding is queued for the user's approval \u2014\n  tell them and check status later, do not re-pay. Step-by-step alternative:\n  `mcp__haven-signer__haven_sign` \u2192 `mcp__haven__haven_submit` \u2192\n  `mcp__haven-signer__haven_x402_sign_header` \u2192\n  `mcp__haven__haven_complete_mcp_tool`. Pass `payment_required`,\n  `arguments`, and `mcp_transport` verbatim from the\n  `mcp__haven__haven_pay_mcp_tool` result. The returned `expires_at` is the\n  signing window; if a tool returns `PAYMENT_WINDOW_EXPIRED`, re-run\n  `mcp__haven__haven_pay_mcp_tool` with the same\n  `idempotency_key`. Do not call the merchant yourself \u2014 Haven completes the\n  merchant leg for you.\n- **Prices:** show the user the live price from the pay-tool result, never a\n  catalog price. `haven_discover_tools` prices are indicative\n  (`price_is_indicative`) and can be stale. The pay-tool result's `amount` /\n  `amount_atomic` is the amount Haven authorizes for the call \u2014 a ceiling the\n  merchant settles at or below \u2014 so present it as the most the user will pay.\n  Pass `max_amount` (atomic units) to `haven_pay_mcp_tool` /\n  `haven_pay_x402_quote` to reject a quote whose authorized amount is above the\n  user's cap, before any funds move.\n- **Status:** `haven_get_payment_status` with a `payment_id` to check on\n  queued or in-flight payments. Do not poll in a tight loop.\n\n## Approval semantics\n\n- A result with `pending_approval` means the payment exceeded the remaining\n  budget and is waiting for the user in Haven. Tell the user, then check\n  status later.\n- Never ask the user for private keys. Signing happens only in the local Haven\n  signer; the hosted Haven tools never receive the signing key. If a tool\n  reports a missing or invalid credential, tell the user to re-run the Haven\n  setup command.\n\n## Failure handling\n\nHaven tool failures are shaped like `{ success: false, code, message, ... }`\nor older `{ error, status, details? }` responses. Branch on `code` when\npresent and surface `message` or `error` verbatim. Common cases:\n\n- `pending_approval`: queued for the user's approval (see above).\n- `insufficient_funds`: the Haven wallet doesn't hold enough of that token.\n  Suggest the user add funds in the Haven dashboard.\n- `PRICE_EXCEEDS_MAX`: the live merchant price exceeded your `max_amount`.\n  No funds moved; ask the user before retrying with a higher cap.\n- `PAYMENT_WINDOW_EXPIRED`: re-run `mcp__haven__haven_pay_mcp_tool` with the same\n  `idempotency_key`, then sign the fresh `payload_hash`.\n- `MERCHANT_REJECTED_AFTER_FUNDING`: stop retrying the merchant and use\n  `mcp__haven__haven_sweep_delegate` to recover stranded delegate funds.\n- Budget exceeded: tell the user how much remains (from\n  `haven_get_allowances`) and that they can raise the budget in Haven.\n\n## Revoke\n\nIf this agent's credential may have leaked, tell the user to pause or revoke\nthe agent in the Haven dashboard under Agents. New requests stop immediately\nfor that credential.\n";
 /** Directory name for the installed skill folder. */
 declare const SKILL_FOLDER_NAME = "haven-pay";
 
@@ -1331,4 +1597,4 @@ declare function encodeBase64Json(value: unknown): string;
  */
 declare function decodeBase64Json<T>(value: string, label?: string): T;
 
-export { AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, type AgentPaymentEnumSchema, AgentPaymentNextAction, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, type ClaudeTool, HAVEN_SKILL_MD, type HavenAgent, type HavenAllowance, type HavenAllowanceSummary, HavenApiError, type HavenCatalogEntry, HavenClient, type HavenClientConfig, HavenError, type HavenPaymentReceipt, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, type MachinePaymentChallenge, type MachinePaymentRail, type MachinePaymentReceipt, type MppAuthorizationOptions, type MppQuote, type MppResumeState, type OpenAITool, type PaymentIntent, type PaymentNextAction, type PaymentPhase, type PaymentRequest, type PaymentResult, type PaymentResumeState, type PaymentStatus, type PaymentStatusResult, type PendingApproval, type ResumeAuthorizedMppInput, type ResumeAuthorizedX402Input, type ResumeMppPaymentInput, type ResumeX402PaymentInput, SKILL_FOLDER_NAME, type SharedToolKey, type SignData, type SweepEntry, type SweepResult, type ToolDescription, type X402AuthorizationOptions, type X402ExpectedAuth, type X402ExpectedContext, type X402Intent, type X402PaymentOption, type X402PaymentRequired, type X402Quote, type X402Receipt, type X402RequestSnapshot, type X402ResumeState, addressFromKey, buildMachinePaymentIdempotencyKey, buildX402ExpectedMessage, composeDescription, decodeBase64Json, decodeBase64Utf8, encodeBase64Json, encodeBase64Utf8, encodeMachinePaymentProof, encodePaymentProof, havenTools, parseMachinePaymentChallenge, parseMachinePaymentChallengeResponse, parsePaymentRequired, parsePaymentRequiredResponse, selectPaymentOption, selectStandardPaymentOption, signHash, toStandardPaymentRequirements, toolDescriptions, verifySignature, x402AuthorizationAmount };
+export { AGENT_PAYMENT_FAILURE_CODE_VALUES, AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, type AgentPaymentEnumSchema, AgentPaymentFailureCode, AgentPaymentFailureCodeDescriptions, AgentPaymentFailureCodeSchema, AgentPaymentNextAction, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, type ClaudeTool, HAVEN_SKILL_MD, type HavenAgent, type HavenAgentAllowanceSummary, type HavenAgentReadiness, type HavenAgentSummary, type HavenAllowance, type HavenAllowanceSummary, HavenApiError, type HavenCatalogEntry, HavenClient, type HavenClientConfig, HavenError, type HavenPaymentReceipt, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, type MachinePaymentChallenge, type MachinePaymentRail, type MachinePaymentReceipt, type MppAuthorizationOptions, type MppQuote, type MppResumeState, type OpenAITool, type PaymentIntent, type PaymentNextAction, type PaymentPhase, type PaymentRequest, type PaymentResult, type PaymentResumeState, type PaymentStatus, type PaymentStatusResult, type PendingApproval, type ResumeAuthorizedMppInput, type ResumeAuthorizedX402Input, type ResumeMppPaymentInput, type ResumeX402PaymentInput, SKILL_FOLDER_NAME, SWEEP_BASE_CHAIN_ID, SWEEP_BASE_USDC_ADDRESS, type SharedToolKey, type SignData, type SweepAuthorization, 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 X402AuthorizationOptions, type X402ExpectedAuth, type X402ExpectedContext, type X402Intent, type X402McpTransport, type X402PaymentOption, type X402PaymentRequired, type X402Quote, type X402Receipt, type X402RequestSnapshot, type X402ResumeState, addressFromKey, buildMachinePaymentIdempotencyKey, buildSweepAuthorizationMessage, buildSweepTypedData, buildX402ExpectedMessage, composeDescription, decodeBase64Json, decodeBase64Utf8, encodeBase64Json, encodeBase64Utf8, encodeMachinePaymentProof, encodePaymentProof, havenTools, parseMachinePaymentChallenge, parseMachinePaymentChallengeResponse, parsePaymentRequired, parsePaymentRequiredResponse, selectPaymentOption, selectStandardPaymentOption, signHash, sweepUsdcAddress, sweepUsdcDomain, toStandardPaymentRequirements, toolDescriptions, verifySignature, x402AuthorizationAmount };