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

package/dist/index.d.ts

@@ -1,65 +1,5 @@
 import { PaymentRequirements } from 'x402/types';
 
-/**
- * Verifiable payment receipts.
- *
- * A self-contained proof bundle for a settled Haven payment that anyone can
- * verify **independently of Haven**. The anchor is the agent delegate's
- * signature over the on-chain transfer hash: recover the signer and confirm it
- * is the agent's delegate, and you have cryptographic proof the agent authorised
- * exactly this transfer — no need to trust Haven's backend. The on-chain
- * `txHash` is the settlement source of truth (verify on any explorer).
- *
- * This lives in the SDK so agents and users can verify receipts client-side
- * with zero Haven trust.
- */
-declare const RECEIPT_VERSION = "haven-receipt-1";
-interface PaymentReceipt {
-    version: typeof RECEIPT_VERSION;
-    paymentId: string;
-    payment: {
-        token: string;
-        tokenAddress: string;
-        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;
-    };
-    /** The agent's cryptographic authorisation — what makes the receipt verifiable. */
-    authorization: {
-        delegate: string;
-        signHash: string;
-        signature: string | null;
-    };
-    onChain: {
-        txHash: string | null;
-        chainId: number;
-    };
-}
-type ReceiptVerification = {
-    verified: true;
-    recoveredSigner: string;
-} | {
-    verified: false;
-    reason: 'missing_signature' | 'bad_signature' | 'signer_mismatch';
-    recoveredSigner?: string;
-};
-/**
- * Verify a receipt independently: recover the signer from the authorisation and
- * confirm it is the agent's delegate. Pure — `recover` is injectable but
- * defaults to standard ECDSA recovery, so this runs anywhere (no Haven backend).
- */
-declare function verifyPaymentReceipt(receipt: PaymentReceipt, recover?: (hash: string, signature: string) => string): ReceiptVerification;
-
 interface HavenClientConfig {
     /** Haven API key (sk_agent_xxx) */
     apiKey: string;
@@ -684,6 +624,25 @@ interface HavenAgentSummary extends HavenAgent {
     spend_authority_readiness: HavenAgentReadiness;
     allowances: HavenAgentAllowanceSummary[];
 }
+/**
+ * #2960 — one party vocabulary for "who paid" a Haven payment, additive
+ * alongside every existing lone `payer*`/`*Address` field (same discipline
+ * as the #2907 `safe`/`account` dual-emit, except these four are DISTINCT
+ * addresses, not same-value twins of one old field).
+ */
+interface PaymentParties {
+    treasuryAccount: string | null;
+    delegate: string | null;
+    delegateAccount: string | null;
+    merchant: string | null;
+}
+/** @internal wire shape of {@link PaymentParties}. */
+interface RawPaymentParties {
+    treasury_account: string | null;
+    delegate: string | null;
+    delegate_account: string | null;
+    merchant: string | null;
+}
 interface HavenPaymentReceipt {
     id: string;
     paymentId: string;
@@ -691,11 +650,28 @@ interface HavenPaymentReceipt {
     approvalRequestId?: string | null;
     rail: string;
     proofStatus: string;
+    /**
+     * @deprecated (#2998) meaning depends on the settlement scheme — the
+     * account → delegate funding transaction on eip3009, the (only) settlement
+     * transaction on erc7710. Prefer {@link fundingTxHash} / {@link settlementTxHash}, which
+     * name which is which.
+     */
     txHash: string;
+    /** The account → delegate funding transaction, relayed by Haven (#2998); null on erc7710 (no funding leg) and on retired mpp-rail rows. */
+    fundingTxHash: string | null;
+    /**
+     * The delegate → merchant settlement transaction (#2998). Trust level differs
+     * by scheme: on erc7710 it is `txHash` itself and Haven VERIFIED it on-chain
+     * before the receipt existed; on eip3009 it is the merchant's claim as relayed
+     * (PAYMENT-RESPONSE), NOT verified on-chain by Haven — cite it as such.
+     */
+    settlementTxHash: string | null;
     chainId: number;
     resourceUrl: string;
     merchantAddress: string | null;
     payerAddress: string;
+    /** #2960: additive alongside `payerAddress` above (`parties.treasury_account` only). */
+    parties?: PaymentParties;
     settlementAddress: string;
     tokenSymbol: string;
     tokenAddress: string;
@@ -887,6 +863,25 @@ declare const AgentPaymentNextAction: {
      * return those funds to the originating Safe.
      */
     readonly SweepStrandedFunds: "sweep_stranded_funds";
+    /**
+     * #2970: a `submitted` erc7710 x402 intent whose settlement window has
+     * passed with no on-chain settlement evidence Haven could verify. Distinct
+     * from {@link CheckStatusLater}, which this REPLACES once the window is
+     * past — but it is not futile: Haven's settlement sweep (120s tick) scans
+     * each candidate over its own window plus a 120s clock-skew allowance, so
+     * it can still attribute the settlement for a short while after this value
+     * first appears. Poll {@link CheckStatusLater}'s tool
+     * (`haven_get_payment_status`) once more, roughly two minutes later; if it
+     * still shows no evidence, tell the user the goods were delivered but
+     * Haven holds no verified settlement evidence for this payment. If the
+     * agent holds the merchant's real settlement transaction hash (from
+     * `PAYMENT-RESPONSE`'s `transaction` field, or a prior settle/complete
+     * result's `settlement_tx_hash`), report it with the hosted
+     * `haven_report_settlement_evidence` tool instead of waiting —
+     * `haven_report_x402_outcome` takes no hash and refuses a non-`confirmed`
+     * intent.
+     */
+    readonly AwaitingSettlementEvidence: "awaiting_settlement_evidence";
 };
 type AgentPaymentNextAction = (typeof AgentPaymentNextAction)[keyof typeof AgentPaymentNextAction];
 /**
@@ -927,12 +922,14 @@ declare const AgentPaymentFailureCode: {
     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. */
+    /** The merchant rejected the paid retry. On eip3009 the funding leg had succeeded (sweep);
+     *  on erc7710 there is no funding leg — nothing to sweep, follow the message (#2983). */
     readonly MerchantRejectedAfterFunding: "MERCHANT_REJECTED_AFTER_FUNDING";
     /** #1300 review: funding is on-chain but the merchant never ANSWERED the
      *  paid retry within the timeout. NOT proof of rejection — the merchant
-     *  holds a valid EIP-3009 authorization and may still settle late, so the
-     *  guidance is verify-then-sweep, never blind sweep. */
+     *  may still settle late, so the guidance is verify-then-act. On eip3009
+     *  the funding leg had succeeded (verify-then-sweep); on erc7710 there is
+     *  no funding leg — nothing to sweep, follow the message (#3000). */
     readonly MerchantUnresponsiveAfterFunding: "MERCHANT_UNRESPONSIVE_AFTER_FUNDING";
     /**
      * #1307: the caller omitted merchant_url/tool_name (asking Haven to
@@ -959,6 +956,16 @@ declare const AgentPaymentFailureCode: {
      * The fallback is the exact atomic `max_amount`.
      */
     readonly MaxAmountUnconvertible: "MAX_AMOUNT_UNCONVERTIBLE";
+    /**
+     * #2979: the merchant answered a `tools/call` probe with its own
+     * machine-readable "cannot settle right now" refusal (HTTP 503,
+     * `{ error: 'merchant_not_ready', reason_code, ... }`) instead of a 402
+     * challenge — e.g. its settlement wallet is out of gas. No 402 was ever
+     * issued and no payment was created; this is honest and (per
+     * `retry_after_s`, when present) usually transient, unlike a permanent
+     * endpoint miss.
+     */
+    readonly MerchantNotReady: "MERCHANT_NOT_READY";
 };
 type AgentPaymentFailureCode = (typeof AgentPaymentFailureCode)[keyof typeof AgentPaymentFailureCode];
 /**
@@ -1001,8 +1008,8 @@ 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" | "retry_with_explicit_context" | "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" | "MERCHANT_UNRESPONSIVE_AFTER_FUNDING" | "MERCHANT_CALL_CONTEXT_UNAVAILABLE" | "AMBIGUOUS_MAX_AMOUNT" | "MAX_AMOUNT_UNCONVERTIBLE")[];
+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" | "retry_with_explicit_context" | "payment_window_expired" | "fund_safe_or_raise_allowance" | "sweep_stranded_funds" | "awaiting_settlement_evidence")[];
+declare const AGENT_PAYMENT_FAILURE_CODE_VALUES: ("PRICE_EXCEEDS_MAX" | "PAYMENT_WINDOW_EXPIRED" | "MERCHANT_REJECTED_AFTER_FUNDING" | "MERCHANT_UNRESPONSIVE_AFTER_FUNDING" | "MERCHANT_CALL_CONTEXT_UNAVAILABLE" | "AMBIGUOUS_MAX_AMOUNT" | "MAX_AMOUNT_UNCONVERTIBLE" | "MERCHANT_NOT_READY")[];
 declare const AGENT_PAYMENT_RAIL_VALUES: ("x402" | "mpp_demo" | "mpp_crypto" | "stripe_deposit" | "spt" | "direct" | "mpp")[];
 declare const AgentPaymentPhaseDescriptions: Record<AgentPaymentPhase, string>;
 declare const AgentPaymentNextActionDescriptions: Record<AgentPaymentNextAction, string>;
@@ -1044,6 +1051,23 @@ declare const AgentPaymentWarningCode: {
      * guidance shown here may be optimistic.
      */
     readonly AllowanceReadOptimistic: "ALLOWANCE_READ_OPTIMISTIC";
+    /**
+     * #2991: the quote tools' `expected_settlement_scheme` prediction of what
+     * `haven_prepare_catalog_purchase` / `haven_pay_mcp_tool` will actually
+     * select could not be computed — the agent's execution rail could not be
+     * read from Haven, so `expected_settlement_scheme` is `null` rather than a
+     * guess. `accepted_scheme` (the merchant's offer) is unaffected.
+     */
+    readonly X402SchemeUnknown: "X402_SCHEME_UNKNOWN";
+    /**
+     * #2968: the merchant answered 200 and handed over goods, but Haven holds NO
+     * on-chain evidence that the payment moved. `settled: false` beside this code
+     * is not a failure — it is the absence of proof, and the two must travel
+     * together so an agent can tell "the user has the goods" apart from "the
+     * money moved". Carries the intent's `expires_at`: after that instant the
+     * settlement can no longer land at all.
+     */
+    readonly SettlementUnconfirmed: "SETTLEMENT_UNCONFIRMED";
 };
 type AgentPaymentWarningCode = (typeof AgentPaymentWarningCode)[keyof typeof AgentPaymentWarningCode];
 interface AgentPaymentWarning {
@@ -1164,6 +1188,8 @@ interface PaymentStatusResult {
     merchantAddress: string | null;
     /** Delegate EOA captured on the payment intent when it was created. */
     payerAddress?: string | null;
+    /** #2960: additive alongside `payerAddress` above (`parties.delegate` only). */
+    parties?: PaymentParties;
     txHash: string | null;
     expiresAt: string;
     chainId: number;
@@ -1241,13 +1267,21 @@ interface HavenCatalogEntry {
     verifiedAt: string | null;
     /**
      * Where the entry came from. `operator` = curated in migrations/scripts
-     * (the operator vouches; no verification badges). `ingestion` = submitted
+     * (the operator vouches for the listing; the catalog refresh probe still
+     * checks the endpoint, see `verifiedPayable`). `ingestion` = submitted
      * through the Verified Payable Directory and passed domain-ownership proof
      * plus the read-only quote probe.
      */
     source: 'operator' | 'ingestion';
-    /** True only for `ingestion` entries. See the epic's trust claim (never merchant honesty or quality). */
+    /** True only for `ingestion` entries — the one ownership claim. See the epic's trust claim (never merchant honesty or quality). */
     domainVerified: boolean;
+    /**
+     * True when Haven watched this endpoint answer a live quote (#2978): the
+     * directory probe for `ingestion` rows, the periodic catalog refresh probe
+     * for `operator` rows (`status === 'active'` with `verifiedAt` set). False
+     * for a degraded row of either source. `discoverTools({ verified:
+     * 'verified' })` filters on this field, not on `source`.
+     */
     verifiedPayable: boolean;
 }
 /** @internal */
@@ -1291,7 +1325,17 @@ declare class MerchantTimeoutError extends HavenApiError {
 }
 declare class X402UnexpectedStatusError extends HavenApiError {
     readonly x402ErrorCode: "unexpected_non_402_status";
-    constructor(message: string, statusCode: number);
+    /**
+     * #2979: `body` is the merchant's own JSON, when the non-402 response
+     * carried one — e.g. the demo merchant's `/mcp` readiness gate answers
+     * `503 { error: 'merchant_not_ready', reason_code, ... }`. Optional and
+     * best-effort: a non-JSON or unreadable body leaves this `undefined`, same
+     * as before this field existed. Consumers key on it (not on the message
+     * string) to distinguish an honest, machine-readable merchant refusal from
+     * a genuine "this is not the x402 endpoint" miss, which otherwise look
+     * identical — both are just "some non-402 status".
+     */
+    constructor(message: string, statusCode: number, body?: unknown);
 }
 /**
  * #1521: the idempotency key resolved to a payment that has already settled,
@@ -1340,6 +1384,19 @@ declare class HavenPaymentStateError extends HavenApiError {
 declare class HavenSigningError extends HavenError {
     constructor(message: string);
 }
+/**
+ * #2972: `MerchantCompletion.reportSettlementEvidence` /
+ * `HavenClient.reportSettlementEvidence` refuse a `0x00…00` settlement hash
+ * BEFORE any network call — see `isZeroSettlementTxHash`. That marker is
+ * never a real transaction (the demo merchant's own "delivered, not settled"
+ * value), so posting it to `POST /machine-payments/evidence` could only ever
+ * come back refused, at the cost of a real round trip. A typed error rather
+ * than a `HavenApiError`-shaped 400: no request was ever attempted, so there
+ * is no HTTP status or response body to carry.
+ */
+declare class HavenZeroSettlementHashError extends HavenError {
+    constructor(paymentId: string);
+}
 /**
  * Refusal codes the local signer returns when it does not recognise the
  * VERSION of a Haven-signed binding it was asked to sign (#1309). Distinct
@@ -1401,6 +1458,73 @@ declare class HavenTimeoutError extends HavenError {
     constructor(paymentId: string);
 }
 
+/**
+ * Verifiable payment receipts.
+ *
+ * A self-contained proof bundle for a settled Haven payment that anyone can
+ * verify **independently of Haven**. The anchor is the agent delegate's
+ * signature over the on-chain transfer hash: recover the signer and confirm it
+ * is the agent's delegate, and you have cryptographic proof the agent authorised
+ * exactly this transfer — no need to trust Haven's backend. The on-chain
+ * `txHash` is the settlement source of truth (verify on any explorer).
+ *
+ * This lives in the SDK so agents and users can verify receipts client-side
+ * with zero Haven trust.
+ */
+declare const RECEIPT_VERSION = "haven-receipt-1";
+interface PaymentReceipt {
+    version: typeof RECEIPT_VERSION;
+    paymentId: string;
+    payment: {
+        token: string;
+        tokenAddress: string;
+        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;
+        /**
+         * #2960: one party vocabulary for "who paid", additive alongside `safe`/
+         * `account` above (which are `parties.treasury_account` only). Optional
+         * for the window: a server from before #2960 emits neither. Ignored by
+         * `verifyPaymentReceipt`, which reads only `authorization`.
+         */
+        parties?: RawPaymentParties;
+        chainId: number;
+        settledAt: string | null;
+        resourceUrl: string | null;
+    };
+    /** The agent's cryptographic authorisation — what makes the receipt verifiable. */
+    authorization: {
+        delegate: string;
+        signHash: string;
+        signature: string | null;
+    };
+    onChain: {
+        txHash: string | null;
+        chainId: number;
+    };
+}
+type ReceiptVerification = {
+    verified: true;
+    recoveredSigner: string;
+} | {
+    verified: false;
+    reason: 'missing_signature' | 'bad_signature' | 'signer_mismatch';
+    recoveredSigner?: string;
+};
+/**
+ * Verify a receipt independently: recover the signer from the authorisation and
+ * confirm it is the agent's delegate. Pure — `recover` is injectable but
+ * defaults to standard ECDSA recovery, so this runs anywhere (no Haven backend).
+ */
+declare function verifyPaymentReceipt(receipt: PaymentReceipt, recover?: (hash: string, signature: string) => string): ReceiptVerification;
+
 /**
  * Gasless delegate-sweep primitives — the single source of truth shared by the
  * edge signer (which signs) and the Haven backend (which relays).
@@ -1616,6 +1740,38 @@ interface X402MerchantOutcomeReport {
     resourceUrl: string;
     recorded: 'reconciliation_event' | 'evidence';
 }
+/**
+ * #2970: what `reportEvidence` learned about the report it just made.
+ *
+ * `confirmed` mirrors the backend's 202 (`modules/mpp/evidence.ts`) — the
+ * intent is now `confirmed` (or was already, on the funding-leg path) with
+ * THIS hash recorded. `retryable` mirrors its 503 (`settlement_unobservable`,
+ * exhausted the retry budget above): the chain could not be read, or the
+ * transaction is not mined yet — ask again later. `refused` mirrors every
+ * terminal refusal (409 `settlement_unverified`, a validation error, an
+ * unknown payment id, or a transport failure with no HTTP status at all,
+ * reported as `statusCode: 0`) — reporting the same hash again will not
+ * change the answer.
+ */
+type EvidenceReportOutcome = {
+    outcome: 'confirmed';
+} | {
+    outcome: 'retryable';
+    statusCode: number | undefined;
+} | {
+    outcome: 'refused';
+    statusCode: number;
+};
+/**
+ * #2970: a hash of the form `0x00…00` is never a real transaction — it is the
+ * demo merchant's own "delivered, not settled" marker (`ZERO_TX_HASH` in
+ * `packages/demo-merchant-mcp/src/x402.ts`), reused rather than invented here
+ * so the hosted gate and any other consumer recognise it the same way. Treated
+ * as equivalent to "no hash was reported": there is nothing on-chain to verify,
+ * so asking the backend to look is a wasted round trip that can only ever
+ * resolve to a refusal.
+ */
+declare function isZeroSettlementTxHash(hash: string | null | undefined): boolean;
 
 declare class HavenClient {
     private readonly delegateKey;
@@ -1840,10 +1996,13 @@ declare class HavenClient {
         search?: string;
         rail?: 'x402' | 'mpp';
         /**
-         * Filter on the entry's provenance (epic #1717): `'verified'` returns
-         * only self-submitted, domain-verified, probe-verified directory
-         * entries; `'operator'` only the operator-curated ones; `'any'` (the
-         * default) returns the merged listing.
+         * `'verified'` (epic #1717, #2978) returns entries whose endpoint Haven
+         * watched answer a live quote — `verifiedPayable === true` — from
+         * EITHER source: an operator-curated row that keeps passing its
+         * periodic 402 probe, or a self-submitted row that also passed
+         * domain-ownership proof. It is not a provenance filter; `'operator'`
+         * still filters on provenance (`source === 'operator'`) regardless of
+         * badge state, and `'any'` (the default) returns the merged listing.
          */
         verified?: 'any' | 'verified' | 'operator';
     }): Promise<HavenCatalogEntry[]>;
@@ -2093,6 +2252,15 @@ declare class HavenClient {
         ok: boolean;
         body: unknown;
         settlementTxHash?: string;
+        /**
+         * #2970: what the evidence report (below) learned, when one was made.
+         * `undefined` when there was no hash to report at all — no funding tx on
+         * the erc7710 branch and no (or a zero) merchant-reported settlement hash.
+         * The hosted erc7710 settle/complete gate reads this to decide whether
+         * `settled: true` is honest; the 3009 branch's `settled: true` does not
+         * need it — see `paid-mcp-completion.ts` for why.
+         */
+        evidenceOutcome?: EvidenceReportOutcome;
     }>;
     /**
      * #2292: report the outcome of a merchant retry the AGENT performed.
@@ -2109,6 +2277,17 @@ declare class HavenClient {
         merchantStatus: number;
         merchantBody?: string;
     }): Promise<X402MerchantOutcomeReport>;
+    /**
+     * #2972: report the merchant's real settlement transaction hash for an
+     * erc7710 x402 payment — the remedy for `DELIVERED_UNSETTLED` /
+     * `SETTLEMENT_PENDING` / `awaiting_settlement_evidence` when the agent
+     * holds the hash (`PAYMENT-RESPONSE.transaction`, or a prior settle/
+     * complete result's `settlement_tx_hash`) and Haven does not. See
+     * `MerchantCompletion.reportSettlementEvidence` for the fail-closed
+     * verification this posts into (`observeErc7710Settlement`) and the
+     * client-side zero-hash refusal.
+     */
+    reportSettlementEvidence(paymentId: string, settlementTxHash: string): Promise<EvidenceReportOutcome>;
     /**
      * GET /x402/:id/merchant-call-context — the settle-leg twin of #1263's
      * sign-context fetch (#1307). Re-serves the stored merchant MCP-tool call
@@ -2296,8 +2475,8 @@ declare const toolDescriptions: {
         readonly nextActionGuidance: string;
     };
     readonly getPaymentStatus: {
-        readonly summary: "Fetch structured Haven payment status, including phase and nextAction taxonomy for agent recovery.";
-        readonly behavior: "Accepts a payment intent id and returns the full state taxonomy (phase, nextAction, rail, amount, merchant, resource url, idempotency key, message).";
+        readonly summary: "Fetch structured Haven payment status for agent recovery.";
+        readonly behavior: "State: phase, nextAction, rail, amount, merchant, resource, idempotency, message; parties: treasury/delegate/delegateAccount/merchant. awaiting_settlement_evidence: poll once, else unverified.";
         readonly nextActionGuidance: "";
     };
     readonly getResumeState: {
@@ -2359,6 +2538,11 @@ declare const toolDescriptions: {
         readonly behavior: string;
         readonly nextActionGuidance: string;
     };
+    readonly reportSettlementEvidence: {
+        readonly summary: "Report an erc7710 payment's real settlement transaction hash so Haven can verify it on-chain and confirm the payment.";
+        readonly behavior: "Pass payment_id and settlement_tx_hash (0x + 64 hex chars) — from PAYMENT-RESPONSE or a prior settlement_tx_hash. Haven verifies on-chain before confirming; a zero, mismatched, or reverted hash is refused. Your own payments only.";
+        readonly nextActionGuidance: "code DELIVERED_UNSETTLED: did not verify, do not retry — poll haven_get_payment_status. code SETTLEMENT_PENDING (retryable:true): not mined or RPC unreachable — report the same hash again shortly.";
+    };
 };
 type SharedToolKey = keyof typeof toolDescriptions;
 
@@ -2404,7 +2588,7 @@ type SharedToolKey = keyof typeof toolDescriptions;
  * live sibling constant not pulled in here; if it ever is, this applies to it
  * too (design review, #2537).
  */
-declare const HAVEN_SKILL_MD = "---\nname: haven-pay\ndescription: Pay for things from the user's Haven wallet within their agent rules, and set Haven up when it is not yet connected. Use when the user asks to send, pay, tip, or transfer crypto; when a request hits an HTTP 402 (x402) paywall; or when they ask to create a Haven account, create an agent, or connect one.\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; a payment above the remaining budget is declined \u2014\nnothing is paid past the rules the user set.\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.\nThat namespacing is Claude-family; other runtimes name the servers by their\nown config keys (Codex: `haven`, `haven_signer`). Tool results carry the\nexact next step (`next_action`, `next_tool`, `next_arguments`, plus the\nruntime-neutral `next_tool_server` + `next_tool_name` \u2014 the bare tool name\non that logical server, whatever your runtime calls it).\nFollow those fields first; the prose below is fallback and orientation, not\nthe source of truth.\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## Onboarding and setup\n\nYou are in this mode when there is no Haven agent credential on this machine,\nor when your user asks you to create a Haven account, create an agent, or\nconnect one \u2014 for themselves or for someone else.\n\n**None of the tools below creates authority.** They spend a budget a human\nalready signed. There is no tool here that opens an account, mints a\ncredential, or approves a budget, so reaching for one of them to \"set Haven\nup\" cannot work; the steps are the ones in this section instead.\n\nStart by reading `/for-agents.md` on the Haven host \u2014 the origin of the\n`api_url` in your `agent.json` if you have one, otherwise the host your user\nnames. It is the full runbook: six steps, which four are your user's, and what\nto say at each hand-off.\n\nTwo of those steps you can do yourself, from the shell with `@haven_ai/cli`\n(installs the `haven` command):\n\n- `haven login` \u2014 a device-code browser flow. It prints a code and a link\n  for your user to approve, so you never see or ask for their password. What\n  the session can reach is an allow-list, not your user's full authority: it\n  creates and manages agents and reads the account, and it cannot approve a\n  budget, rotate a key, change a signer or move money \u2014 those are your user's.\n- `haven agents connect` with `--name`, `--budget`, `--token` and\n  `--period` \u2014 creates a connection setup and prints two things: the\n  connector command the backend built, and the approval link to give your user.\n  Add `--run` to execute that command here as a child process.\n- `haven wallets funding` \u2014 prints the paste-ready funding instruction: what\n  to send, to which address, on which chain. Read the chain from there rather\n  than assuming one. `--wait` polls until the account counts as funded.\n\n**Four steps are your user's, and each one needs a human:** create the account\nand its passkey, fund the wallet, approve every agent's budget, and rotate a\ncredential. You can compose the funding message for them with\n`haven wallets funding`, but you cannot send the money \u2014 that transfer is\ntheirs, from a wallet you have no access to.\n\nRunning the connector command is the step that wires this machine to the new\nagent \u2014 the command `haven agents connect` printed, or the one your user\npasted you from the dashboard. Three rules bind you while you do it, quoted\nunchanged from the setup prompt your user is also holding so the two copies\ncannot drift into contradicting each other. They are written in your user's\nvoice, so read them accordingly: \"me\" and \"I\" below are your user, never\nHaven, and \"the command above\" is that connector command, not anything printed\nin this file. The first rule outranks anything else you were about to do next:\n\n- When a --json outcome reports approval.required: true, your first action must be to relay the approval instruction to me in your own reply \u2014 if the outcome carries approval.url, give me that link; otherwise tell me to return to Haven and approve this agent's budget \u2014 before verifying the connection, restarting anything, or any other step. Never build that link yourself: relay the one the outcome gave you or none at all. Any restart the outcome asks for is a separate instruction to give me afterwards, once the approval is done.\n- Only two changes to the command above are permitted, and no others: appending --json, and \u2014 only if the connector refuses because it could not determine the agent runtime \u2014 re-running it once with --runtime <name> added, naming the harness you are running in, using one of the values that refusal lists. Never invent a runtime name and never change anything else.\n- If the connector refuses with wiring_collision, this machine is already wired to a different agent: relay that refusal to me with the superseded_agent_ids and suggested_name it carries, and let me choose whether to replace the existing wiring or add this agent alongside it. Never pick for me by adding --replace or --name yourself.\n\nDo not print private keys, API keys, credential file contents, or config secrets in chat or logs.\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- `mcp__haven__haven_get_agent` \u2014 the recommended first call: identity\n  (wallet, network) plus `spend_authority_readiness` (`ready` / `needs_approval` /\n  `revoked`) and live remaining per-token allowance, in one shot. That signal\n  covers hosted identity and on-chain spend authority only \u2014 it cannot see the\n  local signer; the signer is verified by calling any signer tool.\n- `mcp__haven__haven_get_allowances` \u2014 detailed per-token breakdown\n  (configured, spent, 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 declined before any money moves \u2014 tell the user; they can raise\nthe budget in the Haven dashboard, or wait for the period reset.\n\n## Paying\n\n**Catalog purchases \u2014 the primary path for MCP merchants:**\n\n1. `mcp__haven__haven_discover_tools` to find a payable service and its\n   `catalog_id`.\n2. If the user needs the live price before authorizing a cap, call\n   `mcp__haven__haven_quote_catalog_purchase` with `catalog_id`. It is\n   read-only and informational only: it never reserves a price or creates a\n   payment. Tell the user its `amount` / `amount_atomic`, then choose a cap.\n3. `mcp__haven__haven_prepare_catalog_purchase` with `catalog_id` and a\n   spending cap. A cap is REQUIRED on this tool and is best practice on every\n   paid call below too \u2014 it caps what the LIVE merchant quote may charge,\n   checked before any funding intent is created. Write it the way the user\n   said it: `max_amount_human` is whole tokens, so \"no more than 1 USDC\" is\n   `max_amount_human: \"1\"`. (`max_amount` is the atomic-unit form, where\n   \"1\" means 0.000001 USDC \u2014 do not convert by hand, and never send both.)\n4. Then FOLLOW THE RESPONSE'S GUIDANCE FIELDS: `next_action`, `next_tool`,\n   and `next_arguments` name the exact next call \u2014 act on those first; the\n   prose in this section is fallback and debugging detail. If the catalog\n   entry is missing or degraded, the response instead names\n   `mcp__haven__haven_pay_mcp_tool` (merchant URL, tool name, arguments) as\n   the manual fallback.\n\n**Signing:** `mcp__haven-signer__haven_sign_x402` with `payment_id` ONLY \u2014\nthe local signer fetches the exact signing bytes AND `payment_required`\nitself, so never relay `typed_data` or the 402 blob yourself. If the signer\nreports its fetched context carried no `payment_required` (older backend),\nre-call with `payment_required` added verbatim. Fallback for an older signer\nor backend: re-run the quote/prepare tool with the SAME `idempotency_key`\nplus `include_signing_payload=true`, then pass `payload_hash`,\n`x402_expected` (the nested `x402.expected` object), and\n`typed_data`/`typed_data_b64` through unchanged.\n\n**Settle:** `mcp__haven__haven_settle_mcp_tool` with `payment_id`,\n`signature`, and `payment_header` ONLY \u2014 Haven rehydrates the merchant call\ncontext (`merchant_url`, `tool_name`, `arguments`, `mcp_transport`)\nserver-side from `payment_id`. Pass those four fields explicitly only as a\nversion-skew fallback when Haven has no stored context for the id \u2014 both or\nnone together, never just one. If the settle result carries `settled: false`,\nfunding has not confirmed \u2014 follow the result's guidance fields and check\nstatus later, do not re-pay.\n\nStep-by-step alternative (also key-safe; for an older signer or backend, or\nwhen you already have a merchant URL and tool name instead of a\n`catalog_id`): if the user needs the live price before choosing a cap, first\ncall `mcp__haven__haven_quote_mcp_tool` with that merchant URL, tool name,\nand arguments. It is informational only; then call\n`mcp__haven__haven_pay_mcp_tool` with the same inputs and the explicit cap.\nThe paid call always obtains a fresh quote before it creates any intent. Then\ncontinue `mcp__haven__haven_pay_mcp_tool` \u2192\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`. Call that last step with\n`payment_id` and the signer's `payment_header` ONLY. It does not take\n`payment_required`: Haven rehydrates the merchant call context\n(`merchant_url`, `tool_name`, `arguments`, `mcp_transport`) and the\n402 server-side from `payment_id`, exactly as at settle. Pass that context\nexplicitly only as a version-skew fallback when Haven has no stored context\nfor the id \u2014 `merchant_url` and `tool_name` both or none together, never\njust one.\nThe returned `expires_at` is the signing window; if a tool returns\n`PAYMENT_WINDOW_EXPIRED`, re-run the same quote/prepare tool with the same\n`idempotency_key`. Do not call the merchant yourself \u2014 Haven completes the\nmerchant leg for you.\n\n**Direct transfer / non-MCP paywall:** `mcp__haven__haven_pay` with\n`to`, `amount`, and `token` for a plain transfer. For an arbitrary,\nnon-MCP x402 paywall: `mcp__haven__haven_quote_x402` to get a quote, then\n`mcp__haven__haven_pay_x402_quote` \u2014 follow the result's guidance fields\nfirst and sign in the local Haven signer. On THIS path Haven does not talk to\nthe merchant: `mcp__haven-signer__haven_sign_x402` returns both\n`signature` and `payment_header`; relay `signature` with\n`mcp__haven__haven_submit`, then retry the paywalled URL yourself with\n`payment_header`. Do not pass that call's `x402_binding` to\n`mcp__haven-signer__haven_x402_sign_header` \u2014 the one-shot already spent it\nbuilding the header, so the call can only refuse. Then tell Haven what the\nmerchant answered: `mcp__haven__haven_report_x402_outcome` with the\n`payment_id`, `outcome` (`\"accepted\"` for a 2xx, else `\"rejected\"`)\nand the `merchant_status` you got. Because Haven never contacted that\nmerchant, this is the only way it can learn the purchase failed \u2014 without it a\nfailed purchase reads as complete for fifteen minutes. (The SDK's own\n`haven_pay_x402` tool does perform the merchant retry itself; that tool is\nnot part of the hosted MCP surface.) If the process\ncrashes after payment, a later `mcp__haven__haven_get_payment_status` call\nmay report `nextAction: 'retry_original_x402_request'` \u2014 only then call\n`mcp__haven__haven_resume_x402_payment` with the preserved resume state or\npayment id, instead of paying again.\n\n**Catalog tool arguments:** when `haven_discover_tools` returns\n`tool_arguments`, pass that object unchanged as the pay tool's\n`arguments` field (for example\n`tool_arguments: { \"tier\": \"50gb\" }` -> `arguments: { \"tier\": \"50gb\" }`).\n\n**Prices:** show the user the live price from a read-only quote or the pay-tool\nresult, never a catalog price. `haven_discover_tools` prices are indicative\n(`price_is_indicative`) and can be stale. A read-only quote is informational\nonly and does not reserve a price; the later paid call re-quotes and enforces\nthe cap. The pay-tool result's `amount` / `amount_atomic` is the merchant's\nown quoted price for that call \u2014 a ceiling the merchant settles at or below \u2014\nso present it as the most the user will pay. It is a price, not an approval:\nthe payment goes through only if it also fits the cap you set and the on-chain\nbudget the user signed, which is enforced on-chain rather than by Haven.\n\n**Status:** `mcp__haven__haven_get_payment_status` with a `payment_id` to\ncheck on in-flight payments. Do not poll in a tight loop.\n\n## Declines and stop signals\n\n- A payment outside the agent's rules \u2014 above the remaining budget, wrong\n  recipient, or expired budget \u2014 is declined before any money moves. Nothing\n  is queued; tell the user, who can raise the budget in Haven.\n- `safe_to_continue: false` on a guidance block is a stop signal in\n  machine-readable form: stop and involve the user before calling anything\n  else for this payment.\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  connector 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- `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 cap. No funds\n  moved; ask the user before retrying with a higher one.\n- `AMBIGUOUS_MAX_AMOUNT`: you sent both `max_amount` and\n  `max_amount_human`. Nothing was contacted or spent \u2014 re-send with exactly\n  one (`max_amount_human` for a cap the user stated in tokens).\n- `MAX_AMOUNT_UNCONVERTIBLE`: `max_amount_human` does not fit this quote's\n  asset \u2014 unknown decimals, or more decimal places than the asset supports.\n  Round the cap, or send an exact atomic `max_amount`.\n- `PAYMENT_WINDOW_EXPIRED`: re-run the quote/prepare tool with the same\n  `idempotency_key`, then sign the fresh payload.\n- `MERCHANT_REJECTED_AFTER_FUNDING`: the merchant refused the paid retry.\n  Stop-and-sweep \u2014 stop retrying the merchant and use\n  `mcp__haven__haven_sweep_delegate` to recover stranded delegate funds.\n- `MERCHANT_UNRESPONSIVE_AFTER_FUNDING`: funding confirmed on-chain, but the\n  merchant never answered the paid retry. This is NOT proof of rejection \u2014 the\n  merchant may still settle late. Verify-then-sweep, never a blind sweep:\n  check `mcp__haven__haven_get_payment_status`, retry\n  `mcp__haven__haven_complete_mcp_tool` ONCE, and only sweep with\n  `mcp__haven__haven_sweep_delegate` if no settlement appears.\n- Budget exceeded: tell the user how much remains (from\n  `mcp__haven__haven_get_allowances`) and that they can raise the budget in\n  Haven.\n\n## Reporting after a purchase\n\nA settled `mcp__haven__haven_settle_mcp_tool` response carries\n`agent_summary.purchase_summary` and the remaining post-purchase allowance\nin `allowance` \u2014 report the product, Haven-derived payment/transaction\nfields, and what is left from those fields directly. `result` is optional\nraw merchant evidence; never use it to decide whether the purchase was paid.\nDo not call `haven_get_agent` or `haven_get_allowances` again just to\nreport a purchase you already made.\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, and set Haven up when it is not yet connected. Use when the user asks to send, pay, tip, or transfer crypto; when a request hits an HTTP 402 (x402) paywall; or when they ask to create a Haven account, create an agent, or connect one.\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; a payment above the remaining budget is declined \u2014\nnothing is paid past the rules the user set.\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.\nThat namespacing is Claude-family; other runtimes name the servers by their\nown config keys (Codex: `haven`, `haven_signer`). Tool results carry the\nexact next step (`next_action`, `next_tool`, `next_arguments`, plus the\nruntime-neutral `next_tool_server` + `next_tool_name` \u2014 the bare tool name\non that logical server, whatever your runtime calls it).\nFollow those fields first; the prose below is fallback and orientation, not\nthe source of truth.\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## Onboarding and setup\n\nYou are in this mode when there is no Haven agent credential on this machine,\nor when your user asks you to create a Haven account, create an agent, or\nconnect one \u2014 for themselves or for someone else.\n\n**None of the tools below creates authority.** They spend a budget a human\nalready signed. There is no tool here that opens an account, mints a\ncredential, or approves a budget, so reaching for one of them to \"set Haven\nup\" cannot work; the steps are the ones in this section instead.\n\nStart by reading `/for-agents.md` on the Haven host \u2014 the origin of the\n`api_url` in your `agent.json` if you have one, otherwise the host your user\nnames. It is the full runbook: six steps, which four are your user's, and what\nto say at each hand-off.\n\nTwo of those steps you can do yourself, from the shell with `@haven_ai/cli`\n(installs the `haven` command):\n\n- `haven login` \u2014 a device-code browser flow. It prints a code and a link\n  for your user to approve, so you never see or ask for their password. What\n  the session can reach is an allow-list, not your user's full authority: it\n  creates and manages agents and reads the account, and it cannot approve a\n  budget, rotate a key, change a signer or move money \u2014 those are your user's.\n- `haven agents connect` with `--name`, `--budget`, `--token` and\n  `--period` \u2014 creates a connection setup and prints two things: the\n  connector command the backend built, and the approval link to give your user.\n  Add `--run` to execute that command here as a child process.\n- `haven wallets funding` \u2014 prints the paste-ready funding instruction: what\n  to send, to which address, on which chain. Read the chain from there rather\n  than assuming one. `--wait` polls until the account counts as funded.\n\n**Four steps are your user's, and each one needs a human:** create the account\nand its passkey, fund the wallet, approve every agent's budget, and rotate a\ncredential. You can compose the funding message for them with\n`haven wallets funding`, but you cannot send the money \u2014 that transfer is\ntheirs, from a wallet you have no access to.\n\nRunning the connector command is the step that wires this machine to the new\nagent \u2014 the command `haven agents connect` printed, or the one your user\npasted you from the dashboard. Three rules bind you while you do it, quoted\nunchanged from the setup prompt your user is also holding so the two copies\ncannot drift into contradicting each other. They are written in your user's\nvoice, so read them accordingly: \"me\" and \"I\" below are your user, never\nHaven, and \"the command above\" is that connector command, not anything printed\nin this file. The first rule outranks anything else you were about to do next:\n\n- When a --json outcome reports approval.required: true, your first action must be to relay the approval instruction to me in your own reply \u2014 if the outcome carries approval.url, give me that link; otherwise tell me to return to Haven and approve this agent's budget \u2014 before verifying the connection, restarting anything, or any other step. Never build that link yourself: relay the one the outcome gave you or none at all. Any restart the outcome asks for is a separate instruction to give me afterwards, once the approval is done.\n- Only two changes to the command above are permitted, and no others: appending --json, and \u2014 only if the connector refuses because it could not determine the agent runtime \u2014 re-running it once with --runtime <name> added, naming the harness you are running in, using one of the values that refusal lists. Never invent a runtime name and never change anything else.\n- If the connector refuses with wiring_collision, this machine is already wired to a different agent: relay that refusal to me with the superseded_agent_ids and suggested_name it carries, and let me choose whether to replace the existing wiring or add this agent alongside it. Never pick for me by adding --replace or --name yourself.\n\nDo not print private keys, API keys, credential file contents, or config secrets in chat or logs.\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- `mcp__haven__haven_get_agent` \u2014 the recommended first call: identity\n  (wallet, network) plus `spend_authority_readiness` (`ready` / `needs_approval` /\n  `revoked`) and live remaining per-token allowance, in one shot. That signal\n  covers hosted identity and on-chain spend authority only \u2014 it cannot see the\n  local signer; the signer is verified by calling any signer tool.\n- `mcp__haven__haven_get_allowances` \u2014 detailed per-token breakdown\n  (configured, spent, 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 declined before any money moves \u2014 tell the user; they can raise\nthe budget in the Haven dashboard, or wait for the period reset.\n\n## Paying\n\n**Catalog purchases \u2014 the primary path for MCP merchants:**\n\n1. `mcp__haven__haven_discover_tools` to find a payable service and its\n   `catalog_id`.\n2. If the user needs the live price before authorizing a cap, call\n   `mcp__haven__haven_quote_catalog_purchase` with `catalog_id`. It is\n   read-only and informational only: it never reserves a price or creates a\n   payment. Tell the user its `amount` / `amount_atomic`, then choose a cap.\n3. `mcp__haven__haven_prepare_catalog_purchase` with `catalog_id` and a\n   spending cap. A cap is REQUIRED on this tool and is best practice on every\n   paid call below too \u2014 it caps what the LIVE merchant quote may charge,\n   checked before any funding intent is created. Write it the way the user\n   said it: `max_amount_human` is whole tokens, so \"no more than 1 USDC\" is\n   `max_amount_human: \"1\"`. (`max_amount` is the atomic-unit form, where\n   \"1\" means 0.000001 USDC \u2014 do not convert by hand, and never send both.)\n4. Then FOLLOW THE RESPONSE'S GUIDANCE FIELDS: `next_action`, `next_tool`,\n   and `next_arguments` name the exact next call \u2014 act on those first; the\n   prose in this section is fallback and debugging detail. If the catalog\n   entry is missing or degraded, the response instead names\n   `mcp__haven__haven_pay_mcp_tool` (merchant URL, tool name, arguments) as\n   the manual fallback.\n\n**Signing:** `mcp__haven-signer__haven_sign_x402` with `payment_id` ONLY \u2014\nthe local signer fetches the exact signing bytes AND `payment_required`\nitself, so never relay `typed_data` or the 402 blob yourself. If the signer\nreports its fetched context carried no `payment_required` (older backend),\nre-call with `payment_required` added verbatim. Fallback for an older signer\nor backend: re-run the quote/prepare tool with the SAME `idempotency_key`\nplus `include_signing_payload=true`, then pass `payload_hash`,\n`x402_expected` (the nested `x402.expected` object), and\n`typed_data`/`typed_data_b64` through unchanged.\n\n**Settle:** `mcp__haven__haven_settle_mcp_tool` with `payment_id`,\n`signature`, and `payment_header` ONLY \u2014 Haven rehydrates the merchant call\ncontext (`merchant_url`, `tool_name`, `arguments`, `mcp_transport`)\nserver-side from `payment_id`. Pass those four fields explicitly only as a\nversion-skew fallback when Haven has no stored context for the id \u2014 both or\nnone together, never just one. If the settle result carries `settled: false`,\nfunding has not confirmed \u2014 follow the result's guidance fields and check\nstatus later, do not re-pay.\n\nStep-by-step alternative (also key-safe; for an older signer or backend, or\nwhen you already have a merchant URL and tool name instead of a\n`catalog_id`): if the user needs the live price before choosing a cap, first\ncall `mcp__haven__haven_quote_mcp_tool` with that merchant URL, tool name,\nand arguments. It is informational only; then call\n`mcp__haven__haven_pay_mcp_tool` with the same inputs and the explicit cap.\nThe paid call always obtains a fresh quote before it creates any intent. Then\ncontinue `mcp__haven__haven_pay_mcp_tool` \u2192\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`. Call that last step with\n`payment_id` and the signer's `payment_header` ONLY. It does not take\n`payment_required`: Haven rehydrates the merchant call context\n(`merchant_url`, `tool_name`, `arguments`, `mcp_transport`) and the\n402 server-side from `payment_id`, exactly as at settle. Pass that context\nexplicitly only as a version-skew fallback when Haven has no stored context\nfor the id \u2014 `merchant_url` and `tool_name` both or none together, never\njust one.\nThe returned `expires_at` is the signing window; if a tool returns\n`PAYMENT_WINDOW_EXPIRED`, re-run the same quote/prepare tool with the same\n`idempotency_key`. Do not call the merchant yourself \u2014 Haven completes the\nmerchant leg for you.\n\n**Direct transfer / non-MCP paywall:** `mcp__haven__haven_pay` with\n`to`, `amount`, and `token` for a plain transfer. For an arbitrary,\nnon-MCP x402 paywall: `mcp__haven__haven_quote_x402` to get a quote, then\n`mcp__haven__haven_pay_x402_quote` \u2014 follow the result's guidance fields\nfirst and sign in the local Haven signer. On THIS path Haven does not talk to\nthe merchant: `mcp__haven-signer__haven_sign_x402` returns both\n`signature` and `payment_header`; relay `signature` with\n`mcp__haven__haven_submit`, then retry the paywalled URL yourself with\n`payment_header`. Do not pass that call's `x402_binding` to\n`mcp__haven-signer__haven_x402_sign_header` \u2014 the one-shot already spent it\nbuilding the header, so the call can only refuse. Then tell Haven what the\nmerchant answered: `mcp__haven__haven_report_x402_outcome` with the\n`payment_id`, `outcome` (`\"accepted\"` for a 2xx, else `\"rejected\"`)\nand the `merchant_status` you got. Because Haven never contacted that\nmerchant, this is the only way it can learn the purchase failed \u2014 without it a\nfailed purchase reads as complete for fifteen minutes. (The SDK's own\n`haven_pay_x402` tool does perform the merchant retry itself; that tool is\nnot part of the hosted MCP surface.) If the process\ncrashes after payment, a later `mcp__haven__haven_get_payment_status` call\nmay report `nextAction: 'retry_original_x402_request'` \u2014 only then call\n`mcp__haven__haven_resume_x402_payment` with the preserved resume state or\npayment id, instead of paying again.\n\n**Catalog tool arguments:** when `haven_discover_tools` returns\n`tool_arguments`, pass that object unchanged as the pay tool's\n`arguments` field (for example\n`tool_arguments: { \"tier\": \"50gb\" }` -> `arguments: { \"tier\": \"50gb\" }`).\n\n**Prices:** show the user the live price from a read-only quote or the pay-tool\nresult, never a catalog price. `haven_discover_tools` prices are indicative\n(`price_is_indicative`) and can be stale. A read-only quote is informational\nonly and does not reserve a price; the later paid call re-quotes and enforces\nthe cap. The pay-tool result's `amount` / `amount_atomic` is the merchant's\nown quoted price for that call \u2014 a ceiling the merchant settles at or below \u2014\nso present it as the most the user will pay. It is a price, not an approval:\nthe payment goes through only if it also fits the cap you set and the on-chain\nbudget the user signed, which is enforced on-chain rather than by Haven.\n\n**Status:** `mcp__haven__haven_get_payment_status` with a `payment_id` to\ncheck on in-flight payments. Do not poll in a tight loop.\n\n## Declines and stop signals\n\n- A payment outside the agent's rules \u2014 above the remaining budget, wrong\n  recipient, or expired budget \u2014 is declined before any money moves. Nothing\n  is queued; tell the user, who can raise the budget in Haven.\n- `safe_to_continue: false` on a guidance block is a stop signal in\n  machine-readable form: stop and involve the user before calling anything\n  else for this payment.\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  connector 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- `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 cap. No funds\n  moved; ask the user before retrying with a higher one.\n- `AMBIGUOUS_MAX_AMOUNT`: you sent both `max_amount` and\n  `max_amount_human`. Nothing was contacted or spent \u2014 re-send with exactly\n  one (`max_amount_human` for a cap the user stated in tokens).\n- `MAX_AMOUNT_UNCONVERTIBLE`: `max_amount_human` does not fit this quote's\n  asset \u2014 unknown decimals, or more decimal places than the asset supports.\n  Round the cap, or send an exact atomic `max_amount`.\n- `PAYMENT_WINDOW_EXPIRED`: re-run the quote/prepare tool with the same\n  `idempotency_key`, then sign the fresh payload.\n- `MERCHANT_NOT_READY`: the merchant refused the quote with its own\n  \"cannot settle right now\" signal (a 503 `merchant_not_ready` with a\n  `reason_code`) instead of a 402. No payment was created. Tell the user;\n  retry later (the message carries `retry_after_s` when the merchant gave\n  one) \u2014 this is not a wrong or broken endpoint.\n- `MERCHANT_REJECTED_AFTER_FUNDING`: the merchant refused the paid retry.\n  On eip3009 (`rail` not `erc7710`): Stop-and-sweep \u2014 stop retrying the\n  merchant and use `mcp__haven__haven_sweep_delegate` to recover stranded\n  delegate funds. On erc7710 there is no funding leg and nothing to sweep:\n  follow the message \u2014 it says whether the merchant declined to settle\n  (re-quote later) or whether to check `haven_get_payment_status` after\n  the payment window first.\n- `MERCHANT_UNRESPONSIVE_AFTER_FUNDING`: the merchant never answered the paid\n  retry. This is NOT proof of rejection \u2014 the merchant may still settle late.\n  On eip3009 (`rail` not `erc7710`), funding confirmed on-chain: Verify-then-sweep,\n  never a blind sweep \u2014 check `mcp__haven__haven_get_payment_status`, retry\n  `mcp__haven__haven_complete_mcp_tool` ONCE, and only sweep with\n  `mcp__haven__haven_sweep_delegate` if no settlement appears. On erc7710\n  there is no funding leg and nothing to sweep, and\n  `mcp__haven__haven_complete_mcp_tool` has no erc7710 branch (it refuses a\n  submitted intent) \u2014 do not retry it: the merchant may still redeem the\n  settlement authorization within the payment window, so check\n  `mcp__haven__haven_get_payment_status` after that window and re-quote only\n  if it shows no settlement.\n- Budget exceeded: tell the user how much remains (from\n  `mcp__haven__haven_get_allowances`) and that they can raise the budget in\n  Haven.\n\n## Reporting after a purchase\n\nA settled `mcp__haven__haven_settle_mcp_tool` response carries\n`agent_summary.purchase_summary` and the remaining post-purchase allowance\nin `allowance` \u2014 report the product, Haven-derived payment/transaction\nfields, and what is left from those fields directly. `result` is optional\nraw merchant evidence; never use it to decide whether the purchase was paid.\nDo not call `haven_get_agent` or `haven_get_allowances` again just to\nreport a purchase you already made.\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";
 /**
@@ -3200,4 +3384,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, 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 };
+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, type EvidenceReportOutcome, 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, HavenZeroSettlementHashError, 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, isZeroSettlementTxHash, 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 };