@haven_ai/sdk 0.1.26-alpha.0 → 0.1.28-alpha.0

package/dist/index.d.cts

@@ -607,7 +607,21 @@ interface HavenAgentAllowanceSummary {
  * from a single call at session start. Superset of {@link HavenAgent}.
  */
 interface HavenAgentSummary extends HavenAgent {
+    /**
+     * @deprecated Use {@link HavenAgentSummary.spend_authority_readiness} —
+     * same value, honest name. This signal covers hosted identity + on-chain
+     * spend authority ONLY; it says nothing about the LOCAL signer, which the
+     * hosted side cannot see (verify via a signer tool or connect --doctor).
+     * Kept as an alias; removal earliest after the next release train (#1590).
+     */
     readiness: HavenAgentReadiness;
+    /**
+     * Spend-authority readiness: hosted identity + on-chain remaining spend
+     * authority. Deliberately named for what it covers — the LOCAL signer's
+     * availability is NOT included and must be verified separately (a signer
+     * tool call, or `npx @haven_ai/connect@alpha --doctor`).
+     */
+    spend_authority_readiness: HavenAgentReadiness;
     allowances: HavenAgentAllowanceSummary[];
 }
 interface HavenPaymentReceipt {
@@ -1342,32 +1356,31 @@ declare function buildSweepTypedData(auth: SweepAuthorization): SweepTypedData;
 declare function buildSweepAuthorizationMessage(auth: SweepAuthorization): string;
 
 declare class HavenClient {
-    private readonly apiKey;
     private readonly delegateKey;
-    private readonly baseUrl;
+    private readonly havenApi;
+    private readonly accountReads;
+    private readonly delegateSweep;
     private readonly x402Wallet;
-    private readonly requestTimeout;
-    private readonly merchantTimeout;
+    private readonly merchantTransport;
     private readonly confirmationTimeout;
     private readonly pollingInterval;
     private readonly chainRpcs;
     private readonly inFlightX402;
-    private readonly x402ReceiptCache;
     /**
-     * Setup-time headers configured via `HavenClientConfig.defaultHeaders`.
-     * Read-only after construction — use `withRequestContext` for per-call
-     * scoping so concurrent requests don't race on shared mutable state.
+     * The EIP-3009 funding-leg lifecycle (#1618). The facade holds a reference
+     * and delegates; it does not reimplement any of it.
      */
-    private readonly defaultHeaders;
+    private readonly fundingLeg;
     /**
-     * Async-local store for per-request context (currently: extra headers).
-     * Each `withRequestContext` invocation produces an isolated store, so
-     * overlapping async work — like two MCP tool dispatches in flight at
-     * the same time — see their own headers without stepping on each other.
+     * The erc7710 direct-settlement lifecycle (#1619). Separate from the funding
+     * leg on purpose: this scheme has no funding leg to share.
      */
-    private readonly requestContext;
-    /** Monotonic JSON-RPC id source for the MCP `initialize` handshake. */
-    private mcpRequestId;
+    private readonly erc7710;
+    /**
+     * Merchant delivery and the evidence trail behind it (#1620). Scheme-neutral
+     * on purpose — both settlement schemes finish through the same door.
+     */
+    private readonly merchantCompletion;
     /** Delegate address derived from the private key (if provided) */
     readonly delegateAddress: string | undefined;
     constructor(config: HavenClientConfig);
@@ -1460,8 +1473,6 @@ declare class HavenClient {
      * Get the agent identity tied to this API key.
      */
     getAgent(): Promise<HavenAgent>;
-    private agentInFlight;
-    private fetchAgent;
     /**
      * One-shot "am I ready?" bootstrap: identity + live spend authority + a
      * readiness signal, in a single call. Folds {@link getAgent} and
@@ -1532,7 +1543,6 @@ declare class HavenClient {
     getPostPurchaseAllowanceSummary(paymentId: string): Promise<{
         allowance: PostPurchaseAllowanceSummary | null;
         warnings: AgentPaymentWarning[];
-        /** Same authenticated payment-state read used to resolve the settled token. */
         payment: PaymentStatusResult | null;
     }>;
     /**
@@ -1633,35 +1643,16 @@ declare class HavenClient {
      * Pay a previously inspected x402 quote and retry the exact captured request.
      */
     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`.
+     * **Nothing has settled when this returns** — that is why it does not return
+     * an `X402Receipt`; the caller still has to retry the merchant with the
+     * header. **MCP callers must pass `options.resourceUrl`**, because an in-band
+     * MCP 402 challenge frequently carries no `resource` object at all.
      *
-     * 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.
+     * Both caveats, and why this scheme has no funding leg, are explained where
+     * the lifecycle lives: `x402-erc7710.ts` (#1619).
      */
     settleX402Erc7710(paymentRequired: X402PaymentRequired, options?: {
         resourceUrl?: string;
@@ -1672,24 +1663,23 @@ declare class HavenClient {
      *
      * 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.
+     * have one and must not.
      */
     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.
+         * The account's rail, when the caller has ALREADY read it — passing it
+         * skips a duplicate fetch (#1456). An optimisation, not a trust
+         * boundary: the backend independently refuses erc7710 from a
+         * non-delegation account (`validateGenericSchemeRail`).
          */
         delegationRail?: boolean;
+        /**
+         * #1547: the merchant MCP-tool call this authorization was quoted
+         * against, persisted so the settle leg can rehydrate it by payment_id
+         * (#1307).
+         */
+        mcpCallContext?: X402McpCallContext;
     }): Promise<{
         paymentId: string;
         signData: SignData;
@@ -1699,9 +1689,8 @@ declare class HavenClient {
      * 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.
+     * erc7710 payload. Whoever produced the signature (an in-process delegate
+     * key, or the local edge signer over the hosted boundary) is irrelevant.
      */
     submitX402Erc7710(paymentId: string, signature: string): Promise<string>;
     resumeAuthorizedX402(input: ResumeAuthorizedX402Input): Promise<X402Receipt>;
@@ -1730,45 +1719,6 @@ declare class HavenClient {
      * Requires `delegateKey` to be set in the client config.
      */
     fetch(url: string, init?: RequestInit, options?: X402AuthorizationOptions): Promise<Response>;
-    /**
-     * Run the MCP `initialize` handshake against a Streamable-HTTP endpoint and
-     * return the `mcp-session-id` the server assigns.
-     *
-     * Returns `undefined` whenever the endpoint is not actually an MCP server —
-     * a transport/HTTP error, a missing session id, or a JSON-RPC error in the
-     * handshake response — so the caller can fall back to plain x402.
-     */
-    private mcpInitialize;
-    /**
-     * Send the MCP `notifications/initialized` notification that completes the
-     * lifecycle handshake. Best-effort: the session is already established, so a
-     * failed notification must not abort the payment.
-     */
-    private mcpNotifyInitialized;
-    /** Read a single JSON-RPC message from an MCP response (JSON or SSE body). */
-    private readMcpMessage;
-    /** Add the MCP transport headers (session id + SSE Accept) to a request. */
-    private withMcpHeaders;
-    /**
-     * Collapse an MCP SSE response into a plain JSON response carrying the
-     * JSON-RPC `result`, so callers of `fetch()` never see raw SSE framing.
-     * Non-SSE responses pass through untouched.
-     */
-    private surfaceMcpResult;
-    private retryX402Request;
-    /**
-     * #956: capture the merchant's OWN receipt when the paid response carries
-     * one, and report it to Haven so the reporting feed can attach it next to
-     * the Haven-generated payment evidence (#498). Two supported signals on the
-     * paid response:
-     *
-     *   x-receipt-json: base64-encoded JSON receipt document (inline)
-     *   x-receipt-url:  https URL to the receipt document (reference)
-     *
-     * Strictly best-effort: absence is the normal case, and no failure here may
-     * ever affect the completed payment — the response is already paid for.
-     */
-    private reportMerchantReceipt;
     /**
      * Deliver an already-signed x402 payment header to the merchant and return
      * the merchant's response. Used by the hosted MCP server to complete the
@@ -1792,7 +1742,7 @@ declare class HavenClient {
      * and before delivering the X-PAYMENT header, so the merchant's
      * balanceOf(delegate) / transferWithAuthorization verification sees the funded
      * balance — otherwise it rejects with "Payment verification failed". The
-     * SDK's local path already does this (see authorizeStandardX402); the hosted
+     * SDK's local path already does this (see `X402FundingLeg.authorize`); the hosted
      * split flow regressed when the 5→3 collapse removed the incidental
      * inter-call latency that used to mask it.
      *
@@ -1841,16 +1791,6 @@ declare class HavenClient {
      * fallback (re-send the full context explicitly).
      */
     getX402MerchantCallContext(paymentId: string): Promise<X402MerchantCallContext>;
-    private resolveX402MerchantCompletionContext;
-    private resolveX402WalletForMerchantCall;
-    private assertCanResumeX402;
-    private mapX402ReceiptFromAuthorization;
-    private mapX402ReceiptFromStatus;
-    private buildX402Receipt;
-    private createStandardX402Header;
-    private cacheX402Receipt;
-    private recordMerchantRetryRejected;
-    private reportMachinePaymentEvidence;
     /**
      * Wait for a funding tx to be mined with ≥1 confirmation before the
      * merchant retry, eliminating the race where the merchant's
@@ -1860,39 +1800,7 @@ declare class HavenClient {
      * backend has already confirmed on-chain submission and callers accept the
      * small propagation window as a trade-off for not configuring an RPC URL.
      */
-    private waitForFundingTx;
-    /**
-     * Can the delegate EOA still fund an authorization for `amountAtomic`?
-     *
-     * #1521: the only question that separates a legitimate resume (funding
-     * confirmed, merchant never paid — the delegate still holds the money) from
-     * a replayed settled payment (funding confirmed, merchant paid, delegate
-     * spent). The intent's own `status: 'confirmed'` is identical in both.
-     *
-     * The balance is asked of the CHAIN rather than of Haven's bookkeeping on
-     * purpose: the merchant-settlement evidence record is written by this SDK
-     * *after* the merchant call, so a client that dies between the two leaves
-     * the backend believing the merchant was never paid — the exact case the
-     * discriminator has to get right. The chain cannot be behind in that way.
-     *
-     * Returns `null` — never a guess — when `chainRpcs` has no entry for the
-     * chain or the read fails. Callers must treat that as "unverifiable", not
-     * as "funded".
-     */
-    private delegateCanFund;
     private throwIfNonSignableAuthorizationState;
-    private throwPaymentStateError;
-    private paymentStateFromRaw;
-    private x402PayerAddress;
-    private snapshotX402Request;
-    private snapshotRequestBody;
-    private requestInitFromSnapshot;
-    private withX402Wallet;
-    private buildX402Quote;
-    private detectX402McpTransport;
-    private buildX402ResumeState;
-    private attachResumeState;
-    private attachX402ResumeState;
     /**
      * Execute a tool call by name and input.
      *
@@ -1906,24 +1814,8 @@ declare class HavenClient {
      * ```
      */
     executeTool(toolName: string, input: Record<string, unknown>): Promise<Record<string, unknown>>;
-    private toolX402PaymentRequired;
-    private x402ToolReceipt;
-    private toolError;
     private post;
     private get;
-    /**
-     * #1300: every MERCHANT-facing fetch goes through here. Haven API calls
-     * have always been bounded (request() below); the merchant probes/retries
-     * called globalThis.fetch bare, so a slow-loris merchant could hold a tool
-     * call open forever. A caller-supplied signal still applies (combined via
-     * AbortSignal.any); a timeout abort surfaces as a clear HavenApiError 504
-     * naming the URL rather than a bare AbortError.
-     */
-    private merchantFetch;
-    private request;
-    private mapPaymentResult;
-    private mapPaymentStatusResult;
-    private mapPaymentReceipt;
 }
 
 /**
@@ -2085,9 +1977,9 @@ declare const toolDescriptions: {
         readonly nextActionGuidance: "";
     };
     readonly getAgent: {
-        readonly summary: "Return the authenticated agent identity AND its live spend authority in one call: Haven wallet, delegate, chain, raw status, a readiness signal, and per-token remaining allowance (atomic + human-readable). The recommended first call in a new session to confirm who you are and whether you can pay right now.";
+        readonly summary: "Return the authenticated agent identity AND its live spend authority in one call: Haven wallet, delegate, chain, raw status, spend_authority_readiness, and per-token remaining allowance (atomic + human-readable). The recommended first call in a new session to confirm who you are and whether Haven will let you spend right now.";
         readonly selectionGuidance: "Use this as the one-shot orientation/bootstrap at the start of a session, or whenever you need to confirm identity together with whether the agent can spend right now. For a detailed per-token breakdown (configured vs spent vs reset window) use haven_get_allowances.";
-        readonly behavior: "Reads identity plus the live spend-authority snapshot in one shot — the on-chain AllowanceModule on the legacy rail, the active budget delegation on the delegation rail. readiness is \"ready\" when at least one token has remaining spend authority, \"needs_approval\" when the agent is active but has none, and \"revoked\" when the credential is not active. What an over-budget payment does differs by rail: on the legacy AllowanceModule rail it is queued for the wallet owner to approve in Haven; on the delegation rail there is no approval queue — an over-budget redemption reverts on-chain, so ask the owner to grant or raise the budget in Haven rather than waiting for an approval. allowances[] carries remainingAtomic and remainingDisplay per token. Identity fields (id, name, status, safeAddress, delegateAddress, chainId) are unchanged from before.";
+        readonly behavior: "Reads identity plus the live spend-authority snapshot in one shot — the on-chain AllowanceModule on the legacy rail, the active budget delegation on the delegation rail. spend_authority_readiness (readiness is a deprecated alias, same value) is \"ready\" when at least one token has remaining spend authority, \"needs_approval\" when the agent is active but has none, and \"revoked\" when the credential is not active. It covers hosted identity + on-chain spend authority ONLY — the hosted server cannot see the LOCAL signer, so \"ready\" does not mean the signer can start; verify the signer with a signer tool call or connect --doctor. What an over-budget payment does differs by rail: on the legacy AllowanceModule rail it is queued for the wallet owner to approve in Haven; on the delegation rail there is no approval queue — an over-budget redemption reverts on-chain, so ask the owner to grant or raise the budget in Haven rather than waiting for an approval. allowances[] carries remainingAtomic and remainingDisplay per token. Identity fields (id, name, status, safeAddress, delegateAddress, chainId) are unchanged from before.";
         readonly nextActionGuidance: "";
     };
     readonly getAllowances: {
@@ -2118,7 +2010,7 @@ declare const toolDescriptions: {
         readonly summary: "Step 1 of a purchase: discover payable services from Haven's curated merchant catalog — names, prices, and which pay tool to use next.";
         readonly selectionGuidance: string;
         readonly behavior: string;
-        readonly nextActionGuidance: "Pick an entry and pay it with the tool named in suggested_tool, passing the entry's resource_url, tool_name, and tool_arguments for MCP merchants. Confirm the price from the live pay-tool result (not the catalog), and pass the user's cap as max_amount_human in whole tokens (\"no more than 1 USDC\" → max_amount_human: \"1\") — never convert it to atomic units by hand (#1351).";
+        readonly nextActionGuidance: "Pick an entry and pay it with the tool named in suggested_tool, passing the entry's resource_url, tool_name, and tool_arguments for MCP merchants. Confirm the price from the live pay-tool result (not the catalog), and pass the user's cap as max_amount_human in whole tokens (\"no more than 1 USDC\" → max_amount_human: \"1\") — never convert it to atomic units by hand.";
     };
     readonly sweep_delegate: {
         readonly summary: "Sweep stranded USDC and/or ETH from the delegate wallet back to the originating Safe.";
@@ -2154,7 +2046,7 @@ type SharedToolKey = keyof typeof toolDescriptions;
  * this canonical string and asserts byte-for-byte equality, so the two copies
  * cannot drift.
  */
-declare const HAVEN_SKILL_MD = "---\nname: haven-pay\ndescription: Pay for things from the user's Haven wallet within their agent rules. Use when the user asks to send, pay, tip, or transfer crypto \u2014 or when a request hits an HTTP 402 (x402) paywall.\n---\n\n# Haven: pay from a Haven wallet\n\nThis skill lets the agent make payments from the user's Haven wallet through\nthe Haven MCP tools. Every payment is checked against the agent's on-chain\nbudget before money moves; payments above the remaining budget wait for the\nuser's approval in Haven.\n\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";
+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.\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## 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 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";
 /**