@haven_ai/sdk 0.1.23-alpha.2 → 0.1.25-alpha.0

package/dist/index.d.ts

@@ -224,6 +224,21 @@ interface X402PaymentOption {
     asset: string;
     payTo: string;
     maxTimeoutSeconds: number;
+    /**
+     * Merchant-supplied scheme metadata. Two keys are load-bearing for Haven
+     * (#1453), both from MetaMask's erc7710 x402 shape:
+     *
+     *   assetTransferMethod  — 'erc7710' marks this entry as settleable by
+     *                          redeeming a delegation chain. Absent/other means
+     *                          the standard EIP-3009 authorization.
+     *   facilitatorAddresses — who may redeem it, pinned into the settlement
+     *                          child's redeemer caveat (#1058).
+     *
+     * Left as an open record on purpose: the field is the merchant's, and
+     * narrowing it to Haven's two keys would silently drop everything else a
+     * merchant sends. Read it through `x402AssetTransferMethod` /
+     * `x402FacilitatorAddresses` rather than indexing it raw.
+     */
     extra?: Record<string, unknown>;
 }
 /** Receipt returned after a successful x402 payment. */
@@ -937,6 +952,8 @@ interface PaymentStatusResult {
     token: string;
     resourceUrl: string | null;
     merchantAddress: string | null;
+    /** Delegate EOA captured on the payment intent when it was created. */
+    payerAddress?: string | null;
     txHash: string | null;
     expiresAt: string;
     chainId: number;
@@ -976,6 +993,27 @@ interface PendingApproval extends PaymentStatusResult {
     requested?: string;
     remaining?: string | null;
 }
+/**
+ * Result of an erc7710 direct settlement (#1454).
+ *
+ * Deliberately NOT an `X402Receipt`. A 3009 receipt describes a completed
+ * two-leg payment — funding tx included — whereas here nothing has settled yet
+ * when this returns: the merchant redeems the delegation chain when the caller
+ * retries with the header. Reusing the receipt type would let a caller read
+ * `txHash` as "paid" on a payment that has not moved a cent.
+ */
+interface X402Erc7710Settlement {
+    paymentId: string;
+    /** Pass verbatim as the `X-PAYMENT` header on the merchant retry. */
+    paymentHeader: string;
+    /** The merchant address the child delegation is pinned to. */
+    merchantPayTo: string;
+    amountAtomic: string;
+    asset: string;
+    network: string;
+    /** Facilitators the child is redeemable by, when the merchant advertised any. */
+    facilitatorAddresses: string[] | null;
+}
 /** @internal */
 /** One payable service in Haven's curated merchant catalog. */
 interface HavenCatalogEntry {
@@ -1560,6 +1598,76 @@ declare class HavenClient {
      */
     payX402Quote(quote: X402Quote, options?: X402AuthorizationOptions): Promise<Response>;
     private authorizeStandardX402;
+    /**
+     * Pay a merchant through **erc7710 direct settlement** (#1454, epic #1450).
+     *
+     * The whole point of this path is what it does NOT do. There is no funding
+     * leg: the merchant redeems a delegation chain and pulls from the treasury
+     * directly, so the delegate EOA never holds the money, no sweep can strand
+     * it, and the #713 reconciliation class does not apply. It is also why this
+     * method is SMALLER than the 3009 path — the backend assembles the merchant
+     * `X-PAYMENT` header in `assembleSettlementPayload`, so the SDK builds no
+     * header locally.
+     *
+     *     authorize (payTo = the MERCHANT) → sign the child → settle → header
+     *
+     * The caller then retries the merchant with that header. **Nothing has
+     * settled when this returns** — that is why it does not return an
+     * `X402Receipt`.
+     *
+     * Requires a delegation-rail account. The backend enforces that
+     * (`validateGenericSchemeRail`), and so does this method, before building a
+     * request the backend would only reject: an error a client can explain is
+     * worth more than a 400 it has to decode.
+     *
+     * **MCP callers must pass `options.resourceUrl`.** An in-band MCP 402
+     * challenge frequently carries no `resource` object at all, so
+     * `paymentRequired.resource?.url` is undefined and the backend answers
+     * "Valid url is required". The QA scenario this path was ported from falls
+     * back to the request URL for exactly that reason — the SDK cannot, because
+     * it never saw the request. Pass it.
+     */
+    settleX402Erc7710(paymentRequired: X402PaymentRequired, options?: {
+        resourceUrl?: string;
+    }): Promise<X402Erc7710Settlement>;
+    /**
+     * The AUTHORIZE half of erc7710 settlement (#1456): select the scheme, build
+     * the request, and return the child to be signed — without signing it.
+     *
+     * Split out because the hosted topology cannot use `settleX402Erc7710()`:
+     * that method signs in-process with `delegateKey`, and hosted Haven does not
+     * have one and must not. The hosted MCP server drives these two halves with
+     * the LOCAL signer in between, so the key stays where it belongs and the
+     * request shaping stays in one place rather than being reimplemented.
+     */
+    prepareX402Erc7710(paymentRequired: X402PaymentRequired, options?: {
+        resourceUrl?: string;
+        /**
+         * The account's rail, when the caller has ALREADY read it from
+         * `GET /machine-payments/agent` — passing it skips a duplicate fetch
+         * (#1456: the hosted tool reads the agent for the delegate address
+         * anyway, and #1348 pins that path to exactly one agent round-trip).
+         *
+         * This is an optimisation, not a trust boundary: omit it and the rail is
+         * read here, and either way the backend independently refuses erc7710
+         * from a non-delegation account (`validateGenericSchemeRail`). A caller
+         * that asserted the wrong rail would build a request the backend rejects.
+         */
+        delegationRail?: boolean;
+    }): Promise<{
+        paymentId: string;
+        signData: SignData;
+        settlement: Omit<X402Erc7710Settlement, 'paymentHeader'>;
+    }>;
+    /**
+     * The SETTLE half (#1456): exchange the signed child for the merchant header.
+     *
+     * The SDK builds no header on this path — the backend assembles the MetaMask
+     * erc7710 payload in `assembleSettlementPayload`. Whoever produced the
+     * signature (an in-process delegate key, or the local edge signer over the
+     * hosted boundary) is irrelevant here.
+     */
+    submitX402Erc7710(paymentId: string, signature: string): Promise<string>;
     resumeAuthorizedX402(input: ResumeAuthorizedX402Input): Promise<X402Receipt>;
     resumeX402Payment(input: ResumeX402PaymentInput | X402ResumeState): Promise<Response>;
     /**
@@ -1650,8 +1758,18 @@ declare class HavenClient {
      * balance — otherwise it rejects with "Payment verification failed". The
      * SDK's local path already does this (see authorizeStandardX402); the hosted
      * split flow regressed when the 5→3 collapse removed the incidental
-     * inter-call latency that used to mask it. No-op when the funding tx hash or
-     * a chain RPC (chainRpcs[chainId]) is unavailable.
+     * inter-call latency that used to mask it.
+     *
+     * **NOT a no-op when the funding tx hash is absent** (#1508). The WAIT is
+     * skipped without a hash or a chain RPC, but the `GET /payments/:id` read
+     * below runs UNCONDITIONALLY — it is how the fallback hash and the chainId
+     * are obtained. That distinction is load-bearing: this method must never be
+     * called on a scheme with no funding leg, because the read itself fails once
+     * the intent reaches a status the backend maps to a non-2xx (`submitted` is a
+     * 409), turning a settled payment into a reported error. The previous wording
+     * here said "No-op when the funding tx hash ... is unavailable", and the
+     * hosted erc7710 path was written against that promise — see
+     * `deliverMerchantPayment`'s `noFundingLeg` option.
      */
     ensureFundingConfirmed(paymentId: string, fundingTxHash?: string): Promise<void>;
     completeX402MerchantCall(input: {
@@ -1660,6 +1778,16 @@ declare class HavenClient {
         paymentId: string;
         paymentHeader: string;
         mcpTransport?: X402McpTransport;
+        /**
+         * #1508: the payment settles with NO funding leg (erc7710). This method was
+         * written for EIP-3009 and encodes that lifecycle in two places — the
+         * readiness gate wants `confirmed`, and a Haven funding tx hash is
+         * mandatory. Neither is reachable on a scheme where the MERCHANT redeems
+         * the delegation chain: the intent sits at `submitted` by design, and there
+         * is no Haven-submitted transaction at all. Set this to take the
+         * no-funding-leg path through both.
+         */
+        noFundingLeg?: boolean;
     }): Promise<{
         status: number;
         ok: boolean;
@@ -1816,12 +1944,13 @@ declare function signHash(privateKey: string, hash: string): string;
  * verbatim and never reconstruct it (a second source of truth could drift
  * from the account's own rules).
  */
-declare function signUserOpTypedDataForDelegation(privateKey: string, typedData: {
+interface Eip712TypedData {
     domain: Record<string, unknown>;
     types: Record<string, unknown>;
     primaryType: string;
     message: Record<string, unknown>;
-}): Promise<string>;
+}
+declare function signUserOpTypedDataForDelegation(privateKey: string, typedData: Eip712TypedData): Promise<string>;
 /**
  * Derive the Ethereum address from a private key.
  */
@@ -1970,9 +2099,19 @@ type SharedToolKey = keyof typeof toolDescriptions;
  * this canonical string and asserts byte-for-byte equality, so the two copies
  * cannot drift.
  */
-declare const HAVEN_SKILL_MD = "---\nname: haven-pay\ndescription: Pay for things from the user's Haven wallet within their agent rules. Use when the user asks to send, pay, tip, or transfer crypto \u2014 or when a request hits an HTTP 402 (x402) paywall.\n---\n\n# Haven: pay from a Haven wallet\n\nThis skill lets the agent make payments from the user's Haven wallet through\nthe Haven MCP tools. Every payment is checked against the agent's on-chain\nbudget before money moves; payments above the remaining budget wait for the\nuser's approval in Haven.\n\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.\nTool results carry the exact next step (`next_action`, `next_tool`,\n`next_arguments`) \u2014 follow those fields first; the prose below is fallback\nand orientation, not the 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## 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 a readiness signal (`ready` / `needs_approval` /\n  `revoked`) and live remaining per-token allowance, in one shot.\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 queued for the user to approve in the Haven dashboard \u2014 this is\nnormal, not an error.\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. `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.)\n3. 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 is queued for the user's approval \u2014 tell them and check status later,\ndo 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`): `mcp__haven__haven_pay_mcp_tool` then\n`mcp__haven-signer__haven_sign` \u2192 `mcp__haven__haven_submit` \u2192\n`mcp__haven-signer__haven_x402_sign_header` \u2192\n`mcp__haven__haven_complete_mcp_tool`. Pass `payment_required`,\n`arguments`, and `mcp_transport` verbatim from the quote/prepare result.\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\nrecipient, 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, sign in the local Haven signer, and retry the original request only\nwhen the result says `retry_original_x402_request`.\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 the pay-tool result, never a\ncatalog price. `haven_discover_tools` prices are indicative\n(`price_is_indicative`) and can be stale. The pay-tool result's `amount` /\n`amount_atomic` is the amount Haven authorizes for the call \u2014 a ceiling the\nmerchant settles at or below \u2014 so present it as the most the user will pay.\n\n**Status:** `mcp__haven__haven_get_payment_status` with a `payment_id` to\ncheck on 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- `safe_to_continue: false` on a guidance block is the same 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  setup command.\n\n## Failure handling\n\nHaven tool failures are shaped like `{ success: false, code, message, ... }`\nor older `{ error, status, details? }` responses. Branch on `code` when\npresent and surface `message` or `error` verbatim. Common cases:\n\n- `pending_approval`: queued for the user's approval (see above).\n- `insufficient_funds`: the Haven wallet doesn't hold enough of that token.\n  Suggest the user add funds in the Haven dashboard.\n- `PRICE_EXCEEDS_MAX`: the live merchant price exceeded your 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. Use when the user asks to send, pay, tip, or transfer crypto \u2014 or when a request hits an HTTP 402 (x402) paywall.\n---\n\n# Haven: pay from a Haven wallet\n\nThis skill lets the agent make payments from the user's Haven wallet through\nthe Haven MCP tools. Every payment is checked against the agent's on-chain\nbudget before money moves; payments above the remaining budget wait for the\nuser's approval in Haven.\n\nHosted tools run in the `mcp__haven__` namespace. Local signing tools run in\nthe `mcp__haven-signer__` namespace and keep the delegate key on this machine.\nTool results carry the exact next step (`next_action`, `next_tool`,\n`next_arguments`) \u2014 follow those fields first; the prose below is fallback\nand orientation, not the 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## 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 a readiness signal (`ready` / `needs_approval` /\n  `revoked`) and live remaining per-token allowance, in one shot.\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 queued for the user to approve in the Haven dashboard \u2014 this is\nnormal, not an error.\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 is queued for the user's approval \u2014 tell them and check status later,\ndo 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`. Pass `payment_required`,\n`arguments`, and `mcp_transport` verbatim from the quote/prepare result.\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\nrecipient, 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, sign in the local Haven signer, and retry the original request only\nwhen the result says `retry_original_x402_request`.\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 amount\nHaven authorizes for that call \u2014 a ceiling the merchant settles at or below \u2014\nso present it as the most the user will pay.\n\n**Status:** `mcp__haven__haven_get_payment_status` with a `payment_id` to\ncheck on 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- `safe_to_continue: false` on a guidance block is the same 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  setup command.\n\n## Failure handling\n\nHaven tool failures are shaped like `{ success: false, code, message, ... }`\nor older `{ error, status, details? }` responses. Branch on `code` when\npresent and surface `message` or `error` verbatim. Common cases:\n\n- `pending_approval`: queued for the user's approval (see above).\n- `insufficient_funds`: the Haven wallet doesn't hold enough of that token.\n  Suggest the user add funds in the Haven dashboard.\n- `PRICE_EXCEEDS_MAX`: the live merchant price exceeded your 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";
 /** Directory name for the installed skill folder. */
 declare const SKILL_FOLDER_NAME = "haven-pay";
+/**
+ * The skill BODY — HAVEN_SKILL_MD with the YAML front-matter stripped.
+ *
+ * For runtimes whose instruction mechanism is a plain guidance file rather
+ * than a skills folder (Codex's global AGENTS.md, #1332), the front-matter is
+ * skill-registry metadata with no meaning and would render as a stray table.
+ * Derived mechanically from the canonical string above, never maintained by
+ * hand — the substance cannot fork per runtime.
+ */
+declare const HAVEN_SKILL_BODY_MD: string;
 
 /**
  * The Node.js floor Haven's published packages support (#1161).
@@ -2055,6 +2194,24 @@ declare function unsupportedNodeVersionMessage(options: UnsupportedNodeVersionMe
  * (see client.ts) since they need API access and signing.
  */
 
+/**
+ * Persisted, agent-scoped facts used to preflight a signed standard x402
+ * payment header. This is an integrity comparison only: it never rebuilds,
+ * modifies, persists, or submits the supplied authorization.
+ */
+interface X402PaymentHeaderContext {
+    merchantTo: string;
+    amountAtomic: string;
+    asset: string;
+    network: string;
+    resourceUrl: string;
+    payer: string;
+    chainId: number;
+}
+/** A deliberately value-free refusal for untrusted payment-header input. */
+declare class X402PaymentHeaderValidationError extends Error {
+    constructor();
+}
 /**
  * Upper bound on the MERCHANT-requested part of the EIP-3009 authorization
  * window (#715, epic #713). The x402 library sets
@@ -2085,6 +2242,7 @@ declare const X402_MAX_AUTHORIZATION_WINDOW_SECONDS = 600;
  * clamp discipline.
  */
 declare const X402_SETTLEMENT_FORWARD_MARGIN_SECONDS = 300;
+declare function normalizePaymentRequired(value: unknown): X402PaymentRequired | null;
 /**
  * Parse an HTTP 402 response into x402 PaymentRequired data.
  *
@@ -2111,12 +2269,84 @@ declare function parsePaymentRequiredResponse(response: Response): Promise<X402P
  * 3. null — no compatible option
  */
 declare function selectPaymentOption(accepts: X402PaymentOption[]): X402PaymentOption | null;
+/** The `extra.assetTransferMethod` value that marks an erc7710-settleable entry. */
+declare const ERC7710_ASSET_TRANSFER_METHOD = "erc7710";
+/**
+ * Read `extra.assetTransferMethod` defensively. `extra` is the merchant's own
+ * object, so it is untrusted shape: anything that is not the exact string is
+ * treated as "not erc7710" rather than coerced.
+ */
+declare function x402AssetTransferMethod(option: X402PaymentOption): string | null;
+/** True when the merchant advertises this entry as erc7710-settleable. */
+declare function isErc7710Option(option: X402PaymentOption): boolean;
+/**
+ * The facilitator addresses a merchant advertises for an erc7710 entry, for
+ * the #1058 redeemer pin — or `null` when it pins nothing.
+ *
+ * **An EMPTY array is `null`, not `[]`.** The backend rejects an empty
+ * `redeemers` list with a 400 (`routes/x402.ts`), and the QA scenario already
+ * treats empty as absent. Returning `[]` here would hand callers a value that
+ * means "pin to nobody" — which is not a narrower pin, it is an unbuildable
+ * delegation.
+ *
+ * Malformed entries are DROPPED rather than failing the whole option, and that
+ * asymmetry is deliberate. A pin narrowed by a merchant's typo means the
+ * facilitator that actually tries to redeem is not on the list, so redemption
+ * reverts — and erc7710 has no funding leg, so nothing moved and nothing is
+ * stranded. Refusing the option outright would instead deny a payment the
+ * remaining valid facilitators could have settled. Losing the payment is the
+ * worse outcome, precisely because the failure this issue closes (#1453) is the
+ * one where funds move BEFORE the rejection.
+ */
+declare function x402FacilitatorAddresses(option: X402PaymentOption): string[] | null;
 /**
  * Select an option that can be paid with the official x402 EIP-3009 exact
  * scheme. Haven's older tx-hash proof path can describe more networks; the
  * merchant-verified path currently needs Base USDC.
+ *
+ * **Skips erc7710-tagged entries (#1453).** It used to return the first
+ * positional match and never look at `extra.assetTransferMethod`, so a merchant
+ * that listed its erc7710 entry first made a Haven client echo that option
+ * while signing a standard EIP-3009 authorization. The merchant rejects the
+ * mismatch cleanly — but on the legacy two-leg the Safe→delegate funding
+ * transfer has already executed, so the visible result is a stranded delegate
+ * balance for the sweep to reclaim. Only our own demo merchant's ordering was
+ * holding that shut, and that pin binds our merchant, not the ones we do not
+ * control.
  */
 declare function selectStandardPaymentOption(accepts: X402PaymentOption[]): X402PaymentOption | null;
+/**
+ * Select the erc7710-settleable option, if the merchant advertises one.
+ */
+declare function selectErc7710PaymentOption(accepts: X402PaymentOption[]): X402PaymentOption | null;
+/** What a settlement-scheme decision resolved to. */
+interface X402SchemeSelection {
+    scheme: 'erc7710' | 'eip3009';
+    option: X402PaymentOption;
+    /** Redeemer pin for the settlement child; only ever set on erc7710. */
+    facilitatorAddresses: string[] | null;
+}
+/**
+ * THE preference rule, in one place (#1450 owner decision, #1453).
+ *
+ *   Prefer erc7710 whenever the account is on the delegation rail and the
+ *   merchant advertises `extra.assetTransferMethod: "erc7710"`; fall back to
+ *   the EIP-3009 bridge otherwise.
+ *
+ * Both halves of that condition are required, and the rail half is the
+ * caller's to supply — the SDK cannot see which rail an account is on from a
+ * 402 response alone. A legacy AllowanceModule account passing
+ * `delegationRail: true` would select a scheme its account cannot settle; the
+ * backend refuses that at authorize (`validateGenericSchemeRail`), which is
+ * where a rail mismatch SHOULD fail, on-chain-adjacent rather than in a client
+ * that could be lying to itself.
+ *
+ * Returns `null` when neither scheme has a payable entry — the caller decides
+ * whether that is an error or a reason to look elsewhere.
+ */
+declare function selectX402SettlementScheme(accepts: X402PaymentOption[], opts: {
+    delegationRail: boolean;
+}): X402SchemeSelection | null;
 declare function x402AuthorizationAmount(option: X402PaymentOption): string;
 /**
  * Canonical Haven-authenticated x402 expected context, recomputed byte-for-byte
@@ -2136,6 +2366,15 @@ declare function x402AuthorizationAmount(option: X402PaymentOption): string;
  */
 declare function buildX402ExpectedMessage(context: X402ExpectedContext): string;
 declare function toStandardPaymentRequirements(paymentRequired: X402PaymentRequired, option: X402PaymentOption): PaymentRequirements;
+/**
+ * Strictly validate an edge-signed EIP-3009 X-PAYMENT header against the
+ * persisted x402 intent context before a hosted relay can submit funding.
+ *
+ * The merchant/facilitator remains the final protocol verifier. This closes a
+ * separate hosted-relay integrity gap: malformed or context-mismatched input
+ * must never cause Haven to relay the funding signature first.
+ */
+declare function validateStandardX402PaymentHeader(paymentHeader: string, context: X402PaymentHeaderContext): Promise<void>;
 /**
  * Encode a payment receipt as a base64 PAYMENT-SIGNATURE header value.
  *
@@ -2230,4 +2469,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_PAYMENT_FAILURE_CODE_VALUES, AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, type AgentNextStep, type AgentPaymentEnumSchema, AgentPaymentFailureCode, AgentPaymentFailureCodeDescriptions, AgentPaymentFailureCodeSchema, AgentPaymentNextAction, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, type AgentPaymentSummary, type AgentPaymentWarning, AgentPaymentWarningCode, type AgentPurchaseSummary, type ClaudeTool, DISCOVERY_MAX_BYTES, HAVEN_MINIMUM_NODE_VERSION, HAVEN_SKILL_MD, type HavenAgent, type HavenAgentAllowanceSummary, type HavenAgentReadiness, type HavenAgentSummary, type HavenAllowance, type HavenAllowanceSummary, HavenApiError, type HavenCatalogEntry, HavenClient, type HavenClientConfig, HavenError, type HavenPaymentReceipt, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, 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 PendingApproval, 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 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, type X402AuthorizationOptions, type X402ExpectedAuth, type X402ExpectedContext, type X402Intent, type X402McpCallContext, type X402McpTransport, type X402MerchantCallContext, type X402PaymentOption, type X402PaymentRequired, type X402Quote, type X402Receipt, type X402RequestSnapshot, type X402ResumeState, X402UnexpectedStatusError, X402_MAX_AUTHORIZATION_WINDOW_SECONDS, X402_SETTLEMENT_FORWARD_MARGIN_SECONDS, addressFromKey, buildSweepAuthorizationMessage, buildSweepTypedData, buildX402ExpectedMessage, compareNodeVersions, composeDescription, decodeBase64Json, decodeBase64Utf8, discoverMerchantMcpUrl, encodeBase64Json, encodeBase64Utf8, encodePaymentProof, havenTools, isSupportedNodeVersion, isSweepableChain, parsePaymentRequired, parsePaymentRequiredResponse, resolveTokenFromAddress, sameUrl, selectPaymentOption, selectStandardPaymentOption, signHash, signUserOpTypedDataForDelegation, sweepUsdcAddress, sweepUsdcDomain, toStandardPaymentRequirements, toolDescriptions, unsupportedNodeVersionMessage, verifyPaymentReceipt, verifySignature, x402AuthorizationAmount };
+export { AGENT_PAYMENT_FAILURE_CODE_VALUES, AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, type AgentNextStep, type AgentPaymentEnumSchema, AgentPaymentFailureCode, AgentPaymentFailureCodeDescriptions, AgentPaymentFailureCodeSchema, AgentPaymentNextAction, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, type AgentPaymentSummary, type AgentPaymentWarning, AgentPaymentWarningCode, type AgentPurchaseSummary, type ClaudeTool, DISCOVERY_MAX_BYTES, ERC7710_ASSET_TRANSFER_METHOD, 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, 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 PendingApproval, 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 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, type X402AuthorizationOptions, type X402Erc7710Settlement, type X402ExpectedAuth, type X402ExpectedContext, type X402Intent, type X402McpCallContext, type X402McpTransport, type X402MerchantCallContext, type X402PaymentHeaderContext, X402PaymentHeaderValidationError, type X402PaymentOption, type X402PaymentRequired, type X402Quote, type X402Receipt, type X402RequestSnapshot, type X402ResumeState, type X402SchemeSelection, X402UnexpectedStatusError, X402_MAX_AUTHORIZATION_WINDOW_SECONDS, X402_SETTLEMENT_FORWARD_MARGIN_SECONDS, addressFromKey, buildSweepAuthorizationMessage, buildSweepTypedData, buildX402ExpectedMessage, compareNodeVersions, composeDescription, decodeBase64Json, decodeBase64Utf8, discoverMerchantMcpUrl, encodeBase64Json, encodeBase64Utf8, encodePaymentProof, havenTools, isErc7710Option, isSupportedNodeVersion, isSweepableChain, normalizePaymentRequired, parsePaymentRequired, parsePaymentRequiredResponse, resolveTokenFromAddress, sameUrl, selectErc7710PaymentOption, selectPaymentOption, selectStandardPaymentOption, selectX402SettlementScheme, signHash, signUserOpTypedDataForDelegation, sweepUsdcAddress, sweepUsdcDomain, toStandardPaymentRequirements, toolDescriptions, unsupportedNodeVersionMessage, validateStandardX402PaymentHeader, verifyPaymentReceipt, verifySignature, x402AssetTransferMethod, x402AuthorizationAmount, x402FacilitatorAddresses };