@haven_ai/sdk 0.1.9 → 0.1.10-alpha.0

package/dist/index.d.cts

@@ -24,6 +24,21 @@ interface HavenClientConfig {
      * standard HTTP and never carry Haven-internal headers.
      */
     defaultHeaders?: Record<string, string>;
+    /**
+     * JSON-RPC RPC URLs keyed by EIP-155 chain ID.
+     *
+     * When provided for a chain, the SDK waits for ≥1 on-chain confirmation of
+     * the AllowanceModule funding tx before retrying the merchant. This prevents
+     * the race where the merchant's `balanceOf(delegate)` call runs before the
+     * funding block has propagated to the merchant's RPC node.
+     *
+     * Without this option the SDK proceeds as soon as Haven's backend confirms
+     * submission (backward-compatible default). Set it to a reliable RPC
+     * endpoint (e.g. Alchemy / Infura) for production usage.
+     *
+     * @example { 8453: 'https://mainnet.base.org' }
+     */
+    chainRpcs?: Record<number, string>;
 }
 interface PaymentRequest {
     /** Token symbol: "EURe", "USDC.e", or "xDAI" */
@@ -419,6 +434,30 @@ interface HavenPaymentReceipt {
     createdAt: string;
     updatedAt: string;
 }
+/** One transferred asset in a delegate sweep. */
+interface SweepEntry {
+    /** 'USDC' or 'ETH' */
+    asset: string;
+    /** Human-readable amount swept (e.g. "0.12") */
+    amount: string;
+    /** Atomic amount swept */
+    amountAtomic: string;
+    /** Transaction hash of the sweep transfer */
+    txHash: string;
+    /** Block explorer URL for the tx */
+    explorerUrl: string;
+}
+/** Result of a `sweepDelegate()` call. */
+interface SweepResult {
+    /** Address funds were swept FROM */
+    fromAddress: string;
+    /** Address funds were swept TO (always the originating Safe) */
+    toAddress: string;
+    /** Chain the sweep occurred on */
+    chainId: number;
+    /** One entry per transferred asset. Empty when nothing was stranded. */
+    transfers: SweepEntry[];
+}
 type PaymentStateKind = 'payment_intent' | 'approval_request';
 interface AgentPaymentEnumSchema {
     type: 'string';
@@ -455,6 +494,13 @@ declare const AgentPaymentPhase: {
      * funds or the agent's per-token allowance needs to be raised first.
      */
     readonly InsufficientFunds: "insufficient_funds";
+    /**
+     * Haven's funding leg (Safe → delegate) confirmed on-chain, but the
+     * merchant rejected the x402 retry. The delegate wallet may hold stranded
+     * USDC that was never settled to the merchant. The agent should stop, tell
+     * the user, and wait for the sweep flow to reclaim the funds.
+     */
+    readonly FundedButUnsettled: "funded_but_unsettled";
 };
 type AgentPaymentPhase = (typeof AgentPaymentPhase)[keyof typeof AgentPaymentPhase];
 declare const AgentPaymentNextAction: {
@@ -480,6 +526,12 @@ declare const AgentPaymentNextAction: {
      * can succeed. A user approval will not fix this state on its own.
      */
     readonly FundSafeOrRaiseAllowance: "fund_safe_or_raise_allowance";
+    /**
+     * The delegate wallet may hold funds that were sent from the Safe but never
+     * settled to the merchant. The wallet owner should initiate a sweep to
+     * return those funds to the originating Safe.
+     */
+    readonly SweepStrandedFunds: "sweep_stranded_funds";
 };
 type AgentPaymentNextAction = (typeof AgentPaymentNextAction)[keyof typeof AgentPaymentNextAction];
 /**
@@ -519,8 +571,8 @@ declare const AgentPaymentRail: {
 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")[];
-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")[];
+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_RAIL_VALUES: ("x402" | "mpp" | "mpp_demo" | "mpp_crypto" | "stripe_deposit" | "spt" | "direct")[];
 declare const AgentPaymentPhaseDescriptions: Record<AgentPaymentPhase, string>;
 declare const AgentPaymentNextActionDescriptions: Record<AgentPaymentNextAction, string>;
@@ -576,6 +628,24 @@ interface PendingApproval extends PaymentStatusResult {
     requested?: string;
     remaining?: string | null;
 }
+/** @internal */
+/** One payable service in Haven's curated merchant catalog. */
+interface HavenCatalogEntry {
+    id: string;
+    name: string;
+    description: string;
+    category: string;
+    resourceUrl: string;
+    rail: 'x402' | 'mpp';
+    protocol: 'http' | 'mcp';
+    toolName: string | null;
+    priceDisplay: string | null;
+    priceAtomic: string | null;
+    asset: string | null;
+    network: string | null;
+    status: 'active' | 'degraded' | 'delisted';
+    verifiedAt: string | null;
+}
 declare class HavenError extends Error {
     readonly code: string;
     readonly statusCode?: number | undefined;
@@ -609,6 +679,7 @@ declare class HavenClient {
     private readonly requestTimeout;
     private readonly confirmationTimeout;
     private readonly pollingInterval;
+    private readonly chainRpcs;
     private readonly inFlightX402;
     private readonly x402ReceiptCache;
     private readonly inFlightMachinePayments;
@@ -625,6 +696,8 @@ declare class HavenClient {
      * the same time — see their own headers without stepping on each other.
      */
     private readonly requestContext;
+    /** Monotonic JSON-RPC id source for the MCP `initialize` handshake. */
+    private mcpRequestId;
     /** Delegate address derived from the private key (if provided) */
     readonly delegateAddress: string | undefined;
     constructor(config: HavenClientConfig);
@@ -707,10 +780,31 @@ declare class HavenClient {
      * Get the agent identity tied to this API key.
      */
     getAgent(): Promise<HavenAgent>;
+    /**
+     * Sweep stranded USDC and ETH from the delegate EOA back to the originating Safe.
+     *
+     * The delegate key held by this client signs and submits the transfer transactions
+     * directly — Haven's backend never handles the key or constructs signed txs
+     * (CASP/MiCA Red Line #2). Funds always go to the Safe linked to this agent.
+     *
+     * Requires `chainRpcs` to be set for the agent's chain in `HavenClientConfig`.
+     */
+    sweepDelegate(): Promise<SweepResult>;
     /**
      * Get configured and on-chain allowances for the authenticated agent.
      */
     getAllowances(): Promise<HavenAllowanceSummary>;
+    /**
+     * Discover payable services from Haven's curated merchant catalog.
+     *
+     * Read-only: returns catalog entries (price, rail, protocol) so an agent
+     * can choose a service and pay it with the regular payment tools in the
+     * same session. Never creates payments or signatures.
+     */
+    discoverTools(options?: {
+        category?: string;
+        rail?: 'x402' | 'mpp';
+    }): Promise<HavenCatalogEntry[]>;
     /**
      * List recent machine-payment receipts/evidence for bookkeeping.
      */
@@ -761,9 +855,44 @@ declare class HavenClient {
      * const data = await response.json()
      * ```
      *
+     * **MCP-over-x402 auto-handshake (issue #315):** when the endpoint is
+     * MCP-shaped — the URL path ends in `/mcp`, or the 402 body carries a
+     * Coinbase Bazaar `extensions.bazaar` block — the SDK runs the MCP
+     * `initialize` handshake, threads the resulting `mcp-session-id`,
+     * `Accept: application/json, text/event-stream`, and `x402-wallet` headers
+     * through every request, and collapses SSE responses to the JSON-RPC
+     * `result`. The caller just passes `(url, { body })` and never sees the
+     * protocol plumbing. A non-MCP server (handshake error / no session id)
+     * falls back to standard x402 behaviour.
+     *
      * Requires `delegateKey` to be set in the client config.
      */
     fetch(url: string, init?: RequestInit, options?: X402AuthorizationOptions): Promise<Response>;
+    /**
+     * Run the MCP `initialize` handshake against a Streamable-HTTP endpoint and
+     * return the `mcp-session-id` the server assigns.
+     *
+     * Returns `undefined` whenever the endpoint is not actually an MCP server —
+     * a transport/HTTP error, a missing session id, or a JSON-RPC error in the
+     * handshake response — so the caller can fall back to plain x402.
+     */
+    private mcpInitialize;
+    /**
+     * Send the MCP `notifications/initialized` notification that completes the
+     * lifecycle handshake. Best-effort: the session is already established, so a
+     * failed notification must not abort the payment.
+     */
+    private mcpNotifyInitialized;
+    /** Read a single JSON-RPC message from an MCP response (JSON or SSE body). */
+    private readMcpMessage;
+    /** Add the MCP transport headers (session id + SSE Accept) to a request. */
+    private withMcpHeaders;
+    /**
+     * Collapse an MCP SSE response into a plain JSON response carrying the
+     * JSON-RPC `result`, so callers of `fetch()` never see raw SSE framing.
+     * Non-SSE responses pass through untouched.
+     */
+    private surfaceMcpResult;
     /**
      * Probe a paid MPP endpoint or inspect an existing challenge without creating
      * a Haven payment or approval request.
@@ -791,6 +920,16 @@ declare class HavenClient {
     private mapMachinePaymentReceiptFromStatus;
     private recordMerchantRetryRejected;
     private reportMachinePaymentEvidence;
+    /**
+     * Wait for a funding tx to be mined with ≥1 confirmation before the
+     * merchant retry, eliminating the race where the merchant's
+     * `balanceOf(delegate)` runs before the funding block propagates.
+     *
+     * Skipped when `chainRpcs` does not include the chain; in that case Haven's
+     * backend has already confirmed on-chain submission and callers accept the
+     * small propagation window as a trade-off for not configuring an RPC URL.
+     */
+    private waitForFundingTx;
     private throwIfNonSignableAuthorizationState;
     private throwPaymentStateError;
     private paymentStateFromRaw;
@@ -1005,9 +1144,54 @@ declare const toolDescriptions: {
         readonly behavior: "Returns the agent's recent machine-payment receipts ordered by recency. Proof header values are not returned.";
         readonly nextActionGuidance: "";
     };
+    readonly payMcpTool: {
+        readonly summary: "Call a named tool on an MCP merchant that requires an x402 payment, handling the full initialize → pay → retry round trip.";
+        readonly selectionGuidance: string;
+        readonly behavior: string;
+        readonly nextActionGuidance: string;
+    };
+    readonly discoverTools: {
+        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 sweep_delegate: {
+        readonly summary: "Sweep stranded USDC and/or ETH from the delegate wallet back to the originating Safe.";
+        readonly selectionGuidance: string;
+        readonly behavior: string;
+        readonly nextActionGuidance: "If transfers is non-empty, confirm the amounts with the user. No further action required — funds are on their way back to the Safe.";
+    };
+    readonly send: {
+        readonly summary: "Send ETH or USDC directly from the agent's Haven wallet to a recipient address.";
+        readonly selectionGuidance: string;
+        readonly behavior: string;
+        readonly nextActionGuidance: string;
+    };
 };
 type SharedToolKey = keyof typeof toolDescriptions;
 
+/**
+ * The generic Haven payment skill — canonical copy.
+ *
+ * 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.
+ *
+ * `packages/frontend/src/lib/agent-skill-bundle.ts` keeps a deliberately
+ * decoupled inline copy (the download fallback): frontend has zero
+ * `@haven_ai/*` dependencies so it can deploy standalone on Vercel without an
+ * unpublished SDK export. A parity test in that package's test suite imports
+ * 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- **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";
+/** Directory name for the installed skill folder. */
+declare const SKILL_FOLDER_NAME = "haven-pay";
+
 /**
  * x402 protocol support for the Haven SDK.
  *
@@ -1078,4 +1262,42 @@ declare function parseMachinePaymentChallengeResponse(response: Response): Promi
 declare function buildMachinePaymentIdempotencyKey(challenge: MachinePaymentChallenge): string;
 declare function encodeMachinePaymentProof(receipt: Omit<MachinePaymentReceipt, 'proofHeader'>): string;
 
-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, type HavenAgent, type HavenAllowance, type HavenAllowanceSummary, HavenApiError, 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, type SharedToolKey, type SignData, 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, encodeMachinePaymentProof, encodePaymentProof, havenTools, parseMachinePaymentChallenge, parseMachinePaymentChallengeResponse, parsePaymentRequired, parsePaymentRequiredResponse, selectPaymentOption, selectStandardPaymentOption, signHash, toStandardPaymentRequirements, toolDescriptions, verifySignature, x402AuthorizationAmount };
+/**
+ * Runtime-agnostic base64 helpers — the single source of truth for the wire
+ * encoding shared by the SDK and the edge signer (#325).
+ *
+ * Why this module exists: the SDK used `atob`/`btoa` (Web globals) while the
+ * signer used `Buffer` (Node-only). Both worked because both currently run in
+ * Node ≥ 16, but the duplication was a latent wire-incompatibility — and the
+ * signer is headed for non-Node runtimes (browsers, Cloudflare Workers) where
+ * `Buffer` does not exist (#314).
+ *
+ * Encoding contract:
+ * - Output is ALWAYS standard base64 (`+`, `/`, padded). The x402 protocol's
+ *   reference implementation validates headers against
+ *   `/^[A-Za-z0-9+/]*={0,2}$/` — URL-safe output would be rejected.
+ * - Decoding is tolerant: URL-safe input (`-`, `_`, unpadded) is normalized
+ *   before decoding, since third-party merchants are not guaranteed to be as
+ *   strict as the reference implementation.
+ * - UTF-8 throughout. Naive `btoa(JSON.stringify(...))` throws on any
+ *   non-Latin-1 character (e.g. a merchant description with an emoji or
+ *   non-ASCII name); these helpers route through TextEncoder/TextDecoder on
+ *   the Web path so multibyte characters round-trip identically on both
+ *   runtimes.
+ */
+/** Encode a UTF-8 string as standard base64. */
+declare function encodeBase64Utf8(value: string): string;
+/** Decode standard or URL-safe base64 to a UTF-8 string. */
+declare function decodeBase64Utf8(value: string): string;
+/** Encode a JSON-serializable value as a standard-base64 string. */
+declare function encodeBase64Json(value: unknown): string;
+/**
+ * Decode a base64 JSON payload.
+ *
+ * Pass a `label` to get a wrapped error message instead of the raw
+ * JSON/base64 error — call sites parsing untrusted merchant headers use this
+ * to produce actionable failures.
+ */
+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 };

package/dist/index.d.ts

@@ -24,6 +24,21 @@ interface HavenClientConfig {
      * standard HTTP and never carry Haven-internal headers.
      */
     defaultHeaders?: Record<string, string>;
+    /**
+     * JSON-RPC RPC URLs keyed by EIP-155 chain ID.
+     *
+     * When provided for a chain, the SDK waits for ≥1 on-chain confirmation of
+     * the AllowanceModule funding tx before retrying the merchant. This prevents
+     * the race where the merchant's `balanceOf(delegate)` call runs before the
+     * funding block has propagated to the merchant's RPC node.
+     *
+     * Without this option the SDK proceeds as soon as Haven's backend confirms
+     * submission (backward-compatible default). Set it to a reliable RPC
+     * endpoint (e.g. Alchemy / Infura) for production usage.
+     *
+     * @example { 8453: 'https://mainnet.base.org' }
+     */
+    chainRpcs?: Record<number, string>;
 }
 interface PaymentRequest {
     /** Token symbol: "EURe", "USDC.e", or "xDAI" */
@@ -419,6 +434,30 @@ interface HavenPaymentReceipt {
     createdAt: string;
     updatedAt: string;
 }
+/** One transferred asset in a delegate sweep. */
+interface SweepEntry {
+    /** 'USDC' or 'ETH' */
+    asset: string;
+    /** Human-readable amount swept (e.g. "0.12") */
+    amount: string;
+    /** Atomic amount swept */
+    amountAtomic: string;
+    /** Transaction hash of the sweep transfer */
+    txHash: string;
+    /** Block explorer URL for the tx */
+    explorerUrl: string;
+}
+/** Result of a `sweepDelegate()` call. */
+interface SweepResult {
+    /** Address funds were swept FROM */
+    fromAddress: string;
+    /** Address funds were swept TO (always the originating Safe) */
+    toAddress: string;
+    /** Chain the sweep occurred on */
+    chainId: number;
+    /** One entry per transferred asset. Empty when nothing was stranded. */
+    transfers: SweepEntry[];
+}
 type PaymentStateKind = 'payment_intent' | 'approval_request';
 interface AgentPaymentEnumSchema {
     type: 'string';
@@ -455,6 +494,13 @@ declare const AgentPaymentPhase: {
      * funds or the agent's per-token allowance needs to be raised first.
      */
     readonly InsufficientFunds: "insufficient_funds";
+    /**
+     * Haven's funding leg (Safe → delegate) confirmed on-chain, but the
+     * merchant rejected the x402 retry. The delegate wallet may hold stranded
+     * USDC that was never settled to the merchant. The agent should stop, tell
+     * the user, and wait for the sweep flow to reclaim the funds.
+     */
+    readonly FundedButUnsettled: "funded_but_unsettled";
 };
 type AgentPaymentPhase = (typeof AgentPaymentPhase)[keyof typeof AgentPaymentPhase];
 declare const AgentPaymentNextAction: {
@@ -480,6 +526,12 @@ declare const AgentPaymentNextAction: {
      * can succeed. A user approval will not fix this state on its own.
      */
     readonly FundSafeOrRaiseAllowance: "fund_safe_or_raise_allowance";
+    /**
+     * The delegate wallet may hold funds that were sent from the Safe but never
+     * settled to the merchant. The wallet owner should initiate a sweep to
+     * return those funds to the originating Safe.
+     */
+    readonly SweepStrandedFunds: "sweep_stranded_funds";
 };
 type AgentPaymentNextAction = (typeof AgentPaymentNextAction)[keyof typeof AgentPaymentNextAction];
 /**
@@ -519,8 +571,8 @@ declare const AgentPaymentRail: {
 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")[];
-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")[];
+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_RAIL_VALUES: ("x402" | "mpp" | "mpp_demo" | "mpp_crypto" | "stripe_deposit" | "spt" | "direct")[];
 declare const AgentPaymentPhaseDescriptions: Record<AgentPaymentPhase, string>;
 declare const AgentPaymentNextActionDescriptions: Record<AgentPaymentNextAction, string>;
@@ -576,6 +628,24 @@ interface PendingApproval extends PaymentStatusResult {
     requested?: string;
     remaining?: string | null;
 }
+/** @internal */
+/** One payable service in Haven's curated merchant catalog. */
+interface HavenCatalogEntry {
+    id: string;
+    name: string;
+    description: string;
+    category: string;
+    resourceUrl: string;
+    rail: 'x402' | 'mpp';
+    protocol: 'http' | 'mcp';
+    toolName: string | null;
+    priceDisplay: string | null;
+    priceAtomic: string | null;
+    asset: string | null;
+    network: string | null;
+    status: 'active' | 'degraded' | 'delisted';
+    verifiedAt: string | null;
+}
 declare class HavenError extends Error {
     readonly code: string;
     readonly statusCode?: number | undefined;
@@ -609,6 +679,7 @@ declare class HavenClient {
     private readonly requestTimeout;
     private readonly confirmationTimeout;
     private readonly pollingInterval;
+    private readonly chainRpcs;
     private readonly inFlightX402;
     private readonly x402ReceiptCache;
     private readonly inFlightMachinePayments;
@@ -625,6 +696,8 @@ declare class HavenClient {
      * the same time — see their own headers without stepping on each other.
      */
     private readonly requestContext;
+    /** Monotonic JSON-RPC id source for the MCP `initialize` handshake. */
+    private mcpRequestId;
     /** Delegate address derived from the private key (if provided) */
     readonly delegateAddress: string | undefined;
     constructor(config: HavenClientConfig);
@@ -707,10 +780,31 @@ declare class HavenClient {
      * Get the agent identity tied to this API key.
      */
     getAgent(): Promise<HavenAgent>;
+    /**
+     * Sweep stranded USDC and ETH from the delegate EOA back to the originating Safe.
+     *
+     * The delegate key held by this client signs and submits the transfer transactions
+     * directly — Haven's backend never handles the key or constructs signed txs
+     * (CASP/MiCA Red Line #2). Funds always go to the Safe linked to this agent.
+     *
+     * Requires `chainRpcs` to be set for the agent's chain in `HavenClientConfig`.
+     */
+    sweepDelegate(): Promise<SweepResult>;
     /**
      * Get configured and on-chain allowances for the authenticated agent.
      */
     getAllowances(): Promise<HavenAllowanceSummary>;
+    /**
+     * Discover payable services from Haven's curated merchant catalog.
+     *
+     * Read-only: returns catalog entries (price, rail, protocol) so an agent
+     * can choose a service and pay it with the regular payment tools in the
+     * same session. Never creates payments or signatures.
+     */
+    discoverTools(options?: {
+        category?: string;
+        rail?: 'x402' | 'mpp';
+    }): Promise<HavenCatalogEntry[]>;
     /**
      * List recent machine-payment receipts/evidence for bookkeeping.
      */
@@ -761,9 +855,44 @@ declare class HavenClient {
      * const data = await response.json()
      * ```
      *
+     * **MCP-over-x402 auto-handshake (issue #315):** when the endpoint is
+     * MCP-shaped — the URL path ends in `/mcp`, or the 402 body carries a
+     * Coinbase Bazaar `extensions.bazaar` block — the SDK runs the MCP
+     * `initialize` handshake, threads the resulting `mcp-session-id`,
+     * `Accept: application/json, text/event-stream`, and `x402-wallet` headers
+     * through every request, and collapses SSE responses to the JSON-RPC
+     * `result`. The caller just passes `(url, { body })` and never sees the
+     * protocol plumbing. A non-MCP server (handshake error / no session id)
+     * falls back to standard x402 behaviour.
+     *
      * Requires `delegateKey` to be set in the client config.
      */
     fetch(url: string, init?: RequestInit, options?: X402AuthorizationOptions): Promise<Response>;
+    /**
+     * Run the MCP `initialize` handshake against a Streamable-HTTP endpoint and
+     * return the `mcp-session-id` the server assigns.
+     *
+     * Returns `undefined` whenever the endpoint is not actually an MCP server —
+     * a transport/HTTP error, a missing session id, or a JSON-RPC error in the
+     * handshake response — so the caller can fall back to plain x402.
+     */
+    private mcpInitialize;
+    /**
+     * Send the MCP `notifications/initialized` notification that completes the
+     * lifecycle handshake. Best-effort: the session is already established, so a
+     * failed notification must not abort the payment.
+     */
+    private mcpNotifyInitialized;
+    /** Read a single JSON-RPC message from an MCP response (JSON or SSE body). */
+    private readMcpMessage;
+    /** Add the MCP transport headers (session id + SSE Accept) to a request. */
+    private withMcpHeaders;
+    /**
+     * Collapse an MCP SSE response into a plain JSON response carrying the
+     * JSON-RPC `result`, so callers of `fetch()` never see raw SSE framing.
+     * Non-SSE responses pass through untouched.
+     */
+    private surfaceMcpResult;
     /**
      * Probe a paid MPP endpoint or inspect an existing challenge without creating
      * a Haven payment or approval request.
@@ -791,6 +920,16 @@ declare class HavenClient {
     private mapMachinePaymentReceiptFromStatus;
     private recordMerchantRetryRejected;
     private reportMachinePaymentEvidence;
+    /**
+     * Wait for a funding tx to be mined with ≥1 confirmation before the
+     * merchant retry, eliminating the race where the merchant's
+     * `balanceOf(delegate)` runs before the funding block propagates.
+     *
+     * Skipped when `chainRpcs` does not include the chain; in that case Haven's
+     * backend has already confirmed on-chain submission and callers accept the
+     * small propagation window as a trade-off for not configuring an RPC URL.
+     */
+    private waitForFundingTx;
     private throwIfNonSignableAuthorizationState;
     private throwPaymentStateError;
     private paymentStateFromRaw;
@@ -1005,9 +1144,54 @@ declare const toolDescriptions: {
         readonly behavior: "Returns the agent's recent machine-payment receipts ordered by recency. Proof header values are not returned.";
         readonly nextActionGuidance: "";
     };
+    readonly payMcpTool: {
+        readonly summary: "Call a named tool on an MCP merchant that requires an x402 payment, handling the full initialize → pay → retry round trip.";
+        readonly selectionGuidance: string;
+        readonly behavior: string;
+        readonly nextActionGuidance: string;
+    };
+    readonly discoverTools: {
+        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 sweep_delegate: {
+        readonly summary: "Sweep stranded USDC and/or ETH from the delegate wallet back to the originating Safe.";
+        readonly selectionGuidance: string;
+        readonly behavior: string;
+        readonly nextActionGuidance: "If transfers is non-empty, confirm the amounts with the user. No further action required — funds are on their way back to the Safe.";
+    };
+    readonly send: {
+        readonly summary: "Send ETH or USDC directly from the agent's Haven wallet to a recipient address.";
+        readonly selectionGuidance: string;
+        readonly behavior: string;
+        readonly nextActionGuidance: string;
+    };
 };
 type SharedToolKey = keyof typeof toolDescriptions;
 
+/**
+ * The generic Haven payment skill — canonical copy.
+ *
+ * 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.
+ *
+ * `packages/frontend/src/lib/agent-skill-bundle.ts` keeps a deliberately
+ * decoupled inline copy (the download fallback): frontend has zero
+ * `@haven_ai/*` dependencies so it can deploy standalone on Vercel without an
+ * unpublished SDK export. A parity test in that package's test suite imports
+ * 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- **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";
+/** Directory name for the installed skill folder. */
+declare const SKILL_FOLDER_NAME = "haven-pay";
+
 /**
  * x402 protocol support for the Haven SDK.
  *
@@ -1078,4 +1262,42 @@ declare function parseMachinePaymentChallengeResponse(response: Response): Promi
 declare function buildMachinePaymentIdempotencyKey(challenge: MachinePaymentChallenge): string;
 declare function encodeMachinePaymentProof(receipt: Omit<MachinePaymentReceipt, 'proofHeader'>): string;
 
-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, type HavenAgent, type HavenAllowance, type HavenAllowanceSummary, HavenApiError, 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, type SharedToolKey, type SignData, 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, encodeMachinePaymentProof, encodePaymentProof, havenTools, parseMachinePaymentChallenge, parseMachinePaymentChallengeResponse, parsePaymentRequired, parsePaymentRequiredResponse, selectPaymentOption, selectStandardPaymentOption, signHash, toStandardPaymentRequirements, toolDescriptions, verifySignature, x402AuthorizationAmount };
+/**
+ * Runtime-agnostic base64 helpers — the single source of truth for the wire
+ * encoding shared by the SDK and the edge signer (#325).
+ *
+ * Why this module exists: the SDK used `atob`/`btoa` (Web globals) while the
+ * signer used `Buffer` (Node-only). Both worked because both currently run in
+ * Node ≥ 16, but the duplication was a latent wire-incompatibility — and the
+ * signer is headed for non-Node runtimes (browsers, Cloudflare Workers) where
+ * `Buffer` does not exist (#314).
+ *
+ * Encoding contract:
+ * - Output is ALWAYS standard base64 (`+`, `/`, padded). The x402 protocol's
+ *   reference implementation validates headers against
+ *   `/^[A-Za-z0-9+/]*={0,2}$/` — URL-safe output would be rejected.
+ * - Decoding is tolerant: URL-safe input (`-`, `_`, unpadded) is normalized
+ *   before decoding, since third-party merchants are not guaranteed to be as
+ *   strict as the reference implementation.
+ * - UTF-8 throughout. Naive `btoa(JSON.stringify(...))` throws on any
+ *   non-Latin-1 character (e.g. a merchant description with an emoji or
+ *   non-ASCII name); these helpers route through TextEncoder/TextDecoder on
+ *   the Web path so multibyte characters round-trip identically on both
+ *   runtimes.
+ */
+/** Encode a UTF-8 string as standard base64. */
+declare function encodeBase64Utf8(value: string): string;
+/** Decode standard or URL-safe base64 to a UTF-8 string. */
+declare function decodeBase64Utf8(value: string): string;
+/** Encode a JSON-serializable value as a standard-base64 string. */
+declare function encodeBase64Json(value: unknown): string;
+/**
+ * Decode a base64 JSON payload.
+ *
+ * Pass a `label` to get a wrapped error message instead of the raw
+ * JSON/base64 error — call sites parsing untrusted merchant headers use this
+ * to produce actionable failures.
+ */
+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 };