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

package/dist/index.cjs

@@ -63,6 +63,11 @@ var AgentPaymentNextAction = {
   StopAndTellUser: "stop_and_tell_user",
   /** Ask again only if the user still wants the payment after expiry. */
   RequestAgainIfUserStillWantsIt: "request_again_if_user_still_wants_it",
+  /**
+   * The x402 funding/quote window expired. Re-quote the same logical merchant
+   * operation with the same idempotency key to stay double-charge-safe.
+   */
+  PaymentWindowExpired: "payment_window_expired",
   /**
    * Stop and tell the user that the originating Safe needs to be funded or
    * the agent's per-token allowance needs to be raised before the payment
@@ -76,6 +81,14 @@ var AgentPaymentNextAction = {
    */
   SweepStrandedFunds: "sweep_stranded_funds"
 };
+var AgentPaymentFailureCode = {
+  /** A merchant-authoritative x402 price exceeds the caller's pre-funding max_amount cap. */
+  PriceExceedsMax: "PRICE_EXCEEDS_MAX",
+  /** The x402 funding/quote window expired before the signer or hosted settle step could finish. */
+  PaymentWindowExpired: "PAYMENT_WINDOW_EXPIRED",
+  /** The Haven funding leg succeeded, but the merchant rejected the paid retry. */
+  MerchantRejectedAfterFunding: "MERCHANT_REJECTED_AFTER_FUNDING"
+};
 var AgentPaymentRail = {
   /** Standard Haven payment from the user's Safe through an approved delegate allowance. */
   Direct: "direct",
@@ -94,6 +107,7 @@ var AgentPaymentRail = {
 };
 var AGENT_PAYMENT_PHASE_VALUES = Object.values(AgentPaymentPhase);
 var AGENT_PAYMENT_NEXT_ACTION_VALUES = Object.values(AgentPaymentNextAction);
+var AGENT_PAYMENT_FAILURE_CODE_VALUES = Object.values(AgentPaymentFailureCode);
 var AGENT_PAYMENT_RAIL_VALUES = Object.values(AgentPaymentRail);
 var AgentPaymentPhaseDescriptions = {
   [AgentPaymentPhase.AgentSignatureRequired]: "The agent must sign and submit the prepared payment before Haven can relay it.",
@@ -118,9 +132,15 @@ var AgentPaymentNextActionDescriptions = {
   [AgentPaymentNextAction.RetryOriginalX402Request]: "Resume this payment id and retry the original x402 request with the merchant payment header.",
   [AgentPaymentNextAction.StopAndTellUser]: "Stop retrying this payment and tell the user what happened.",
   [AgentPaymentNextAction.RequestAgainIfUserStillWantsIt]: "Ask again only if the user still wants the payment after expiry.",
+  [AgentPaymentNextAction.PaymentWindowExpired]: "The x402 funding/quote window expired. Re-quote with the same idempotency key before asking the signer to build a merchant payment header again.",
   [AgentPaymentNextAction.FundSafeOrRaiseAllowance]: "Stop and tell the user that the originating Safe needs to be funded or the agent allowance raised before the payment can succeed.",
   [AgentPaymentNextAction.SweepStrandedFunds]: "Tell the user that funds may be stranded in the delegate wallet and prompt them to initiate a sweep in Haven to return them to the originating Safe."
 };
+var AgentPaymentFailureCodeDescriptions = {
+  [AgentPaymentFailureCode.PriceExceedsMax]: "The merchant-authoritative x402 amount exceeds the caller's max_amount cap. No funding transfer was created; ask the user before retrying with a larger cap.",
+  [AgentPaymentFailureCode.PaymentWindowExpired]: "The x402 funding/quote window expired before the signer or hosted settle step could finish. Re-quote via haven_pay_mcp_tool with the same idempotency key to avoid duplicate funding.",
+  [AgentPaymentFailureCode.MerchantRejectedAfterFunding]: "The Haven funding leg succeeded, but the merchant rejected the paid retry. Stop retrying the merchant and reconcile stranded delegate funds with haven_sweep_delegate."
+};
 var AgentPaymentRailDescriptions = {
   [AgentPaymentRail.Direct]: "Standard Haven payment from the user-controlled Safe through an approved delegate allowance.",
   [AgentPaymentRail.X402]: "x402 HTTP 402 payment flow with a Haven funding leg and merchant retry leg.",
@@ -142,6 +162,12 @@ var AgentPaymentNextActionSchema = {
   description: "Stable next action an agent should take for a Haven payment state.",
   "x-enumDescriptions": AgentPaymentNextActionDescriptions
 };
+var AgentPaymentFailureCodeSchema = {
+  type: "string",
+  enum: AGENT_PAYMENT_FAILURE_CODE_VALUES,
+  description: "Stable machine-readable failure codes for Haven agent payment recovery paths.",
+  "x-enumDescriptions": AgentPaymentFailureCodeDescriptions
+};
 var AgentPaymentRailSchema = {
   type: "string",
   enum: AGENT_PAYMENT_RAIL_VALUES,
@@ -329,7 +355,8 @@ function normalizePaymentRequired(value) {
     x402Version: candidate.x402Version,
     resource,
     accepts,
-    error: candidate.error
+    error: candidate.error,
+    ...candidate.extensions && typeof candidate.extensions === "object" ? { extensions: candidate.extensions } : {}
   };
 }
 var SUPPORTED_X402_NETWORKS = {
@@ -425,8 +452,7 @@ function x402AuthorizationAmount(option) {
   return amount;
 }
 function buildX402ExpectedMessage(context) {
-  return `Haven x402 expected context v1
-${stableStringify({
+  const payload = {
     version: 1,
     kind: "haven.x402.expected",
     paymentId: context.paymentId,
@@ -436,7 +462,12 @@ ${stableStringify({
     amount: context.amount,
     asset: context.asset.toLowerCase(),
     network: context.network
-  })}`;
+  };
+  if (context.expiresAt) {
+    payload.expiresAt = context.expiresAt;
+  }
+  return `Haven x402 expected context v1
+${stableStringify(payload)}`;
 }
 function toStandardPaymentRequirements(paymentRequired, option) {
   const network = STANDARD_X402_NETWORKS[option.network];
@@ -500,6 +531,7 @@ function stableStringify(value) {
     const primitive = JSON.stringify(value);
     return primitive === void 0 ? "undefined" : primitive;
   }
+  if (value instanceof Date) return JSON.stringify(value.toISOString());
   if (Array.isArray(value)) return `[${value.map((item) => stableStringify(item)).join(",")}]`;
   const object = value;
   return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(object[key])}`).join(",")}}`;
@@ -601,11 +633,24 @@ var DEFAULT_REQUEST_TIMEOUT = 3e4;
 var DEFAULT_CONFIRMATION_TIMEOUT = 9e4;
 var DEFAULT_POLLING_INTERVAL = 3e3;
 function formatAtomicAmount(atomic, decimals) {
+  if (atomic < 0n) return "0.0";
   const s = atomic.toString().padStart(decimals + 1, "0");
   const intPart = s.slice(0, s.length - decimals) || "0";
   const fracPart = s.slice(s.length - decimals).replace(/0+$/, "") || "0";
   return `${intPart}.${fracPart}`;
 }
+function safeBigInt(value) {
+  try {
+    return BigInt(value);
+  } catch {
+    return 0n;
+  }
+}
+function deriveReadiness(status, allowances) {
+  if (status !== "active") return "revoked";
+  const hasSpendable = allowances.some((a) => safeBigInt(a.remainingAtomic) > 0n);
+  return hasSpendable ? "ready" : "needs_approval";
+}
 var MCP_PROTOCOL_VERSION = "2025-06-18";
 var MCP_ACCEPT = "application/json, text/event-stream";
 var MCP_CLIENT_INFO = { name: "haven-sdk", version: "1" };
@@ -892,6 +937,7 @@ var HavenClient = class {
     }
     return {
       paymentId: raw.payment_id,
+      idempotencyKey,
       status: "pending_signature",
       expiresAt: raw.expires_at,
       signData: raw.sign_data,
@@ -971,6 +1017,32 @@ var HavenClient = class {
       chainId: raw.chain_id
     };
   }
+  /**
+   * One-shot "am I ready?" bootstrap: identity + live spend authority + a
+   * readiness signal, in a single call. Folds {@link getAgent} and
+   * {@link getAllowances} together and derives a {@link HavenAgentReadiness}
+   * so an agent can answer "who am I and can I pay right now" at session start
+   * without two round trips and manual assembly.
+   */
+  async getAgentSummary() {
+    const [agent, allowanceSummary] = await Promise.all([
+      this.getAgent(),
+      this.getAllowances()
+    ]);
+    const allowances = allowanceSummary.allowances.map((a) => {
+      const token = resolveTokenFromAddress(a.tokenAddress);
+      const remainingDisplay = token ? `${formatAtomicAmount(safeBigInt(a.onchain.remaining), token.decimals)} ${a.tokenSymbol}` : `${a.onchain.remaining} ${a.tokenSymbol} (atomic; unknown decimals)`;
+      return {
+        tokenSymbol: a.tokenSymbol,
+        remainingAtomic: a.onchain.remaining,
+        remainingDisplay,
+        configuredAmount: a.configuredAmount,
+        resetPeriodMin: a.resetPeriodMin,
+        isResetPending: a.onchain.isResetPending
+      };
+    });
+    return { ...agent, readiness: deriveReadiness(agent.status, allowances), allowances };
+  }
   /**
    * Sweep stranded USDC and ETH from the delegate EOA back to the originating Safe.
    *
@@ -1043,6 +1115,30 @@ var HavenClient = class {
       transfers
     };
   }
+  /**
+   * Hosted (keyless) split-signer sweep — step 1 of 2.
+   *
+   * Asks the backend to build a gasless EIP-3009 sweep authorization for the
+   * delegate's stranded USDC. Returns `nothing_stranded` when the delegate is
+   * empty, otherwise an `authorization` + Haven `expected_auth` to hand to the
+   * edge signer's `haven_sign_sweep_delegate`. No key is required on this client.
+   */
+  async prepareSweep() {
+    return this.post("/machine-payments/sweep/prepare", {});
+  }
+  /**
+   * Hosted (keyless) split-signer sweep — step 2 of 2.
+   *
+   * Relays the delegate-signed authorization. The Haven relayer submits the
+   * on-chain `transferWithAuthorization` and pays gas; this client never holds
+   * the key.
+   */
+  async submitSweep(authorization, signature) {
+    return this.post("/machine-payments/sweep/submit", {
+      authorization,
+      signature
+    });
+  }
   /**
    * Get configured and on-chain allowances for the authenticated agent.
    */
@@ -1198,7 +1294,8 @@ var HavenClient = class {
       throw new HavenApiError("quoteX402 only supports standard x402 Payment Required responses.", 400);
     }
     const paymentRequired = await parsePaymentRequiredResponse(response);
-    return this.buildX402Quote(paymentRequired, request, options.idempotencyKey);
+    const mcpTransport = await this.detectX402McpTransport(url, paymentRequired, response);
+    return this.buildX402Quote(paymentRequired, request, options.idempotencyKey, mcpTransport);
   }
   /**
    * Pay a previously inspected x402 quote and retry the exact captured request.
@@ -1403,12 +1500,11 @@ var HavenClient = class {
    * 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.
    */
-  async mcpInitialize(url, init) {
+  async mcpInitialize(url, init, wallet = this.x402PayerAddress()) {
     try {
       const headers = new Headers(init?.headers);
       headers.set("Content-Type", "application/json");
       headers.set("Accept", MCP_ACCEPT);
-      const wallet = this.x402PayerAddress();
       if (wallet && !headers.has("x402-wallet")) headers.set("x402-wallet", wallet);
       const response = await globalThis.fetch(url, {
         method: "POST",
@@ -1429,7 +1525,7 @@ var HavenClient = class {
       if (!sessionId) return void 0;
       const message = await this.readMcpMessage(response);
       if (message && "error" in message) return void 0;
-      await this.mcpNotifyInitialized(url, init, sessionId);
+      await this.mcpNotifyInitialized(url, init, sessionId, wallet);
       return sessionId;
     } catch {
       return void 0;
@@ -1440,13 +1536,12 @@ var HavenClient = class {
    * lifecycle handshake. Best-effort: the session is already established, so a
    * failed notification must not abort the payment.
    */
-  async mcpNotifyInitialized(url, init, sessionId) {
+  async mcpNotifyInitialized(url, init, sessionId, wallet = this.x402PayerAddress()) {
     try {
       const headers = new Headers(init?.headers);
       headers.set("Content-Type", "application/json");
       headers.set("Accept", MCP_ACCEPT);
       headers.set("mcp-session-id", sessionId);
-      const wallet = this.x402PayerAddress();
       if (wallet && !headers.has("x402-wallet")) headers.set("x402-wallet", wallet);
       await globalThis.fetch(url, {
         method: "POST",
@@ -1624,30 +1719,48 @@ var HavenClient = class {
    * amount/merchant/nonce-bound EIP-3009 authorization the edge signer already
    * produced — the hosted server cannot mint or reuse signing authority.
    *
-   * When the URL is MCP-shaped (`/mcp` path), runs a fresh `initialize`
+   * When the URL is MCP-shaped (`/mcp` path) or the quote-time transport context
+   * says the merchant was Bazaar-discoverable, runs a fresh `initialize`
    * handshake (the quote-time session is gone once funding confirms; the x402
    * challenge is stateless w.r.t. the MCP session, so a fresh session is
    * accepted), threads the session + wallet headers, sets `X-PAYMENT`, and
    * collapses an SSE JSON-RPC response to its `result`.
-   *
-   * Limitation: detects MCP only by the `/mcp` path convention, not the
-   * Coinbase Bazaar `extensions.bazaar` 402 signal that `fetch()` also honors.
-   * A Bazaar-discoverable merchant on a non-`/mcp` URL would need the standard
-   * `fetch()` path. All current MCP-tool merchants use the `/mcp` convention.
    */
+  /**
+   * Wait for a payment's Safe→delegate funding tx to reach ≥1 on-chain
+   * confirmation. The hosted x402 completion path MUST call this after funding
+   * and before delivering the X-PAYMENT header, so the merchant's
+   * balanceOf(delegate) / transferWithAuthorization verification sees the funded
+   * balance — otherwise it rejects with "Payment verification failed". The
+   * SDK's local path already does this (see authorizeStandardX402); the hosted
+   * split flow regressed when the 5→3 collapse removed the incidental
+   * inter-call latency that used to mask it. No-op when the funding tx hash or
+   * a chain RPC (chainRpcs[chainId]) is unavailable.
+   */
+  async ensureFundingConfirmed(paymentId, fundingTxHash) {
+    const status = await this.getPaymentStatus(paymentId);
+    await this.waitForFundingTx(fundingTxHash ?? status.txHash ?? void 0, status.chainId);
+  }
   async completeX402MerchantCall(input) {
+    const evidenceContext = await this.resolveX402MerchantCompletionContext({
+      paymentId: input.paymentId,
+      url: input.url
+    });
+    const shouldHandshakeMcp = isMcpUrl(input.url) || input.mcpTransport?.handshakeRequired === true;
+    const x402Wallet = shouldHandshakeMcp ? await this.resolveX402WalletForMerchantCall() : this.x402PayerAddress();
     let mcpSessionId;
-    if (isMcpUrl(input.url)) {
-      mcpSessionId = await this.mcpInitialize(input.url, input.init);
+    if (shouldHandshakeMcp) {
+      mcpSessionId = await this.mcpInitialize(input.url, input.init, x402Wallet);
     }
-    let requestInit = this.withX402Wallet(input.init, this.x402PayerAddress()) ?? {};
+    let requestInit = this.withX402Wallet(input.init, x402Wallet) ?? {};
     if (mcpSessionId) requestInit = this.withMcpHeaders(requestInit, mcpSessionId);
     const headers = new Headers(requestInit.headers);
     headers.set("X-PAYMENT", input.paymentHeader);
     requestInit = { ...requestInit, headers };
     const response = await globalThis.fetch(input.url, requestInit);
     const surfaced = mcpSessionId ? await this.surfaceMcpResult(response) : response;
-    const settlement = parseMerchantSettlement(surfaced.headers.get("PAYMENT-RESPONSE"));
+    const protocolReceiptHeader = surfaced.headers.get("PAYMENT-RESPONSE") ?? void 0;
+    const settlement = parseMerchantSettlement(protocolReceiptHeader ?? null);
     const text = await surfaced.text();
     let body;
     try {
@@ -1655,6 +1768,35 @@ var HavenClient = class {
     } catch {
       body = text;
     }
+    if (!surfaced.ok) {
+      await this.recordMerchantRetryRejected({
+        rail: "x402",
+        paymentId: evidenceContext.paymentId,
+        txHash: evidenceContext.txHash,
+        resourceUrl: evidenceContext.resourceUrl,
+        merchant: {
+          merchant_status: surfaced.status,
+          merchant_status_text: surfaced.statusText,
+          merchant_headers: Object.fromEntries(surfaced.headers.entries()),
+          merchant_body: text
+        },
+        details: {
+          merchant_to: evidenceContext.merchantAddress
+        }
+      });
+    } else {
+      await this.reportMachinePaymentEvidence({
+        paymentId: evidenceContext.paymentId,
+        rail: "x402",
+        txHash: evidenceContext.txHash,
+        resourceUrl: evidenceContext.resourceUrl,
+        merchantStatus: surfaced.status,
+        paymentProofHeaderName: "X-PAYMENT",
+        paymentProofHeader: input.paymentHeader,
+        protocolReceiptHeaderName: protocolReceiptHeader ? "PAYMENT-RESPONSE" : void 0,
+        protocolReceiptHeader
+      });
+    }
     return {
       status: surfaced.status,
       ok: surfaced.ok,
@@ -1662,6 +1804,53 @@ var HavenClient = class {
       settlementTxHash: settlement.settlementTxHash ?? void 0
     };
   }
+  async resolveX402MerchantCompletionContext(input) {
+    const status = await this.getPaymentStatus(input.paymentId);
+    if (status.rail !== "x402") {
+      throw new HavenPaymentStateError(
+        `Payment ${status.paymentId} is ${status.rail}, not x402.`,
+        409,
+        status
+      );
+    }
+    const readyForMerchantCompletion = status.nextAction === AgentPaymentNextAction.RetryOriginalX402Request || status.kind === "payment_intent" && status.status === "confirmed" && status.phase === AgentPaymentPhase.PaymentConfirmed && status.nextAction === AgentPaymentNextAction.None;
+    if (!readyForMerchantCompletion) {
+      throw new HavenPaymentStateError(status.message, PAYMENT_STATE_STATUS_CODES[status.status] ?? 409, status);
+    }
+    if (!status.txHash) {
+      throw new HavenApiError(
+        `x402 payment ${status.paymentId} is ready for merchant completion but has no Haven transaction hash.`,
+        502,
+        status,
+        status.paymentId
+      );
+    }
+    const approvedResourceUrl = status.resourceUrl ?? status.x402?.resourceUrl ?? null;
+    if (approvedResourceUrl && approvedResourceUrl !== input.url) {
+      throw new HavenApiError(
+        "x402 merchant completion does not match the approved resource URL.",
+        409,
+        { status, url: input.url },
+        status.paymentId
+      );
+    }
+    return {
+      paymentId: status.paymentId,
+      txHash: status.txHash,
+      resourceUrl: approvedResourceUrl ?? input.url,
+      merchantAddress: status.merchantAddress ?? status.x402?.merchantAddress ?? null
+    };
+  }
+  async resolveX402WalletForMerchantCall() {
+    const localWallet = this.x402PayerAddress();
+    if (localWallet) return localWallet;
+    try {
+      const agent = await this.getAgent();
+      return agent.delegateAddress ?? void 0;
+    } catch {
+      return void 0;
+    }
+  }
   async authorizeMachinePayment(challenge, options = {}) {
     if (!this.delegateKey) {
       throw new HavenSigningError(
@@ -2259,7 +2448,7 @@ var HavenClient = class {
       headers
     };
   }
-  buildX402Quote(paymentRequired, request, idempotencyKey) {
+  buildX402Quote(paymentRequired, request, idempotencyKey, mcpTransport) {
     const option = selectStandardPaymentOption(paymentRequired.accepts);
     if (!option) {
       throw new HavenApiError(
@@ -2274,6 +2463,7 @@ var HavenClient = class {
       paymentRequired,
       accepted: option,
       request,
+      ...mcpTransport ? { mcpTransport } : {},
       resourceUrl: paymentRequired.resource.url,
       description: paymentRequired.resource.description ?? option.description ?? null,
       mimeType: paymentRequired.resource.mimeType ?? option.mimeType ?? null,
@@ -2287,6 +2477,18 @@ var HavenClient = class {
       maxTimeoutSeconds: option.maxTimeoutSeconds
     };
   }
+  async detectX402McpTransport(url, paymentRequired, response) {
+    if (isMcpUrl(url)) {
+      return { handshakeRequired: true, source: "path" };
+    }
+    if (paymentRequired.extensions?.bazaar != null) {
+      return { handshakeRequired: true, source: "bazaar" };
+    }
+    if (await responseHasBazaarExtension(response)) {
+      return { handshakeRequired: true, source: "bazaar" };
+    }
+    return void 0;
+  }
   buildX402ResumeState(input) {
     const token = resolveTokenFromAddress(input.accepted.asset, input.accepted.network);
     return {
@@ -2814,8 +3016,9 @@ var toolDescriptions = {
     nextActionGuidance: ""
   },
   getAgent: {
-    summary: "Return the authenticated agent identity, Haven wallet, delegate address, chain, and status.",
-    behavior: "Read-only identity lookup. Useful for verifying which on-chain Safe and delegate the credential is bound to.",
+    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.",
+    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.",
+    behavior: 'Reads identity plus the on-chain AllowanceModule snapshot in one shot. readiness is "ready" when at least one token has remaining on-chain allowance, "needs_approval" when the agent is active but has no remaining allowance to auto-spend (payments will be queued for the wallet owner to approve in Haven), and "revoked" when the credential is not active. allowances[] carries remainingAtomic and remainingDisplay per token. Identity fields (id, name, status, safeAddress, delegateAddress, chainId) are unchanged from before.',
     nextActionGuidance: ""
   },
   getAllowances: {
@@ -2839,8 +3042,8 @@ var toolDescriptions = {
   discoverTools: {
     summary: "Discover payable services from Haven's curated merchant catalog \u2014 names, prices, and which pay tool to use.",
     selectionGuidance: "Use this when the user asks what the agent can buy, pay for, or which paid services exist \u2014 or when you need a resource URL for a service the user described. Do NOT use for balance, budget, or spend-limit questions \u2014 use haven_get_allowances. Do NOT use to pay \u2014 each returned entry names the pay tool to use next.",
-    behavior: "Read-only lookup against Haven's curated catalog. Entries are periodically re-verified against the live merchant; degraded entries are flagged. Returns name, description, price, rail, resource URL, and a suggested_tool field naming the exact Haven pay tool for that entry. Never creates a payment, signature, or approval.",
-    nextActionGuidance: "Pick an entry, confirm the price with the user if it is non-trivial, and pay it with the tool named in suggested_tool, passing the entry's resource_url (and tool_name for MCP merchants)."
+    behavior: "Read-only lookup against Haven's curated catalog. Entries are periodically re-verified against the live merchant; degraded entries are flagged. Returns name, description, price, rail, resource URL, and a suggested_tool field naming the exact Haven pay tool for that entry. The catalog price (price_display/price_atomic, marked price_is_indicative) is a last-verified hint, NOT authoritative \u2014 the real price comes from the merchant's live 402 at pay time. Never creates a payment, signature, or approval.",
+    nextActionGuidance: "Pick an entry and pay it with the tool named in suggested_tool, passing the entry's resource_url (and tool_name for MCP merchants). Confirm the price from the live pay-tool result (not the catalog), and pass max_amount when the user has a cap."
   },
   sweep_delegate: {
     summary: "Sweep stranded USDC and/or ETH from the delegate wallet back to the originating Safe.",
@@ -3107,18 +3310,37 @@ the Haven MCP tools. Every payment is checked against the agent's on-chain
 budget before money moves; payments above the remaining budget wait for the
 user's approval in Haven.
 
+Hosted tools run in the \`mcp__haven__\` namespace. Local signing tools run in
+the \`mcp__haven-signer__\` namespace and keep the delegate key on this machine.
+
 ## When to use this skill
 
 - The user asks to send money, pay someone, tip, donate, or transfer tokens.
 - A request returns HTTP 402 (x402): use the Haven pay tools to settle it,
   then retry the original request.
 
-## Identity and budget come from the tools \u2014 never assume them
+## Identity and budget
+
+Do not guess the wallet address, network, or budget.
 
-Do not guess the wallet address, network, or budget. Read them live:
+For instant orientation at the start of a session, read the non-secret
+\`agent.json\` the connector wrote to your Haven credential directory (typically
+\`~/.haven/agents/<agent-id>/agent.json\` \u2014 if you don't know the agent id, list
+\`~/.haven/agents/\` to find the folder). It
+holds your agent id, Haven wallet address, network, and *configured* per-token
+budget, and contains no keys \u2014 the fastest way to answer "who am I and what may
+I spend" with no round trip. If that file is absent (some setups don't write
+it), use the tools below instead.
 
-- \`haven_get_agent\` \u2014 agent identity, Haven wallet address, network.
-- \`haven_get_allowances\` \u2014 current per-token budgets and what remains.
+Before any payment, confirm the *live remaining* budget with the tools \u2014
+\`agent.json\` shows the configured budget, not what is left after recent
+spending:
+
+- \`haven_get_agent\` \u2014 the recommended first call: identity (wallet, network)
+  plus a readiness signal (\`ready\` / \`needs_approval\` / \`revoked\`) and live
+  remaining per-token allowance, in one shot.
+- \`haven_get_allowances\` \u2014 detailed per-token breakdown (configured, spent,
+  reset window) when you need more than the summary.
 
 Budgets reset on a period the user chose. If a payment exceeds the remaining
 budget it is queued for the user to approve in the Haven dashboard \u2014 this is
@@ -3132,13 +3354,33 @@ normal, not an error.
   the local Haven signer; follow the tool results \u2014 they tell you the next
   action at every step. Retry the original request only when the result says
   \`retry_original_x402_request\`.
-- **Paid MCP tool call:** \`haven_pay_mcp_tool\` with the merchant URL, tool
-  name, and arguments. Then follow the returned steps: \`haven_sign\` the
-  funding hash, \`haven_submit\` the signature, \`haven_x402_sign_header\` to
-  build the payment header, and finally \`haven_complete_mcp_tool\` to settle
-  with the merchant and get the tool result. Pass \`payment_required\` and
-  \`arguments\` through verbatim from the \`haven_pay_mcp_tool\` result. Do not
-  call the merchant yourself \u2014 Haven completes the merchant leg for you.
+- **Paid MCP tool call:** \`mcp__haven__haven_pay_mcp_tool\` with the merchant
+  URL, tool name, and arguments, then finish in two calls (fast path):
+  \`mcp__haven-signer__haven_sign_x402\` on the local signer (pass
+  \`payload_hash\`, \`x402_expected\` as the nested \`x402.expected\` object, and
+  \`payment_required\`) returns \`{ signature, payment_header }\`; then
+  \`mcp__haven__haven_settle_mcp_tool\` (pass \`payment_id\`, \`signature\`,
+  \`payment_header\`, \`merchant_url\`, \`tool_name\`, \`arguments\`,
+  \`mcp_transport\`) funds and settles in one step and returns the tool result.
+  If it returns \`settled: false\`, funding is queued for the user's approval \u2014
+  tell them and check status later, do not re-pay. Step-by-step alternative:
+  \`mcp__haven-signer__haven_sign\` \u2192 \`mcp__haven__haven_submit\` \u2192
+  \`mcp__haven-signer__haven_x402_sign_header\` \u2192
+  \`mcp__haven__haven_complete_mcp_tool\`. Pass \`payment_required\`,
+  \`arguments\`, and \`mcp_transport\` verbatim from the
+  \`mcp__haven__haven_pay_mcp_tool\` result. The returned \`expires_at\` is the
+  signing window; if a tool returns \`PAYMENT_WINDOW_EXPIRED\`, re-run
+  \`mcp__haven__haven_pay_mcp_tool\` with the same
+  \`idempotency_key\`. Do not call the merchant yourself \u2014 Haven completes the
+  merchant leg for you.
+- **Prices:** show the user the live price from the pay-tool result, never a
+  catalog price. \`haven_discover_tools\` prices are indicative
+  (\`price_is_indicative\`) and can be stale. The pay-tool result's \`amount\` /
+  \`amount_atomic\` is the amount Haven authorizes for the call \u2014 a ceiling the
+  merchant settles at or below \u2014 so present it as the most the user will pay.
+  Pass \`max_amount\` (atomic units) to \`haven_pay_mcp_tool\` /
+  \`haven_pay_x402_quote\` to reject a quote whose authorized amount is above the
+  user's cap, before any funds move.
 - **Status:** \`haven_get_payment_status\` with a \`payment_id\` to check on
   queued or in-flight payments. Do not poll in a tight loop.
 
@@ -3147,18 +3389,26 @@ normal, not an error.
 - A result with \`pending_approval\` means the payment exceeded the remaining
   budget and is waiting for the user in Haven. Tell the user, then check
   status later.
-- Never ask the user for private keys and never try to sign anything
-  yourself \u2014 Haven signs. If a tool reports a missing or invalid credential,
-  tell the user to re-run the Haven setup command.
+- Never ask the user for private keys. Signing happens only in the local Haven
+  signer; the hosted Haven tools never receive the signing key. If a tool
+  reports a missing or invalid credential, tell the user to re-run the Haven
+  setup command.
 
 ## Failure handling
 
-Haven errors are shaped \`{ error, status, details? }\` and written for
-humans \u2014 surface the message verbatim. Common cases:
+Haven tool failures are shaped like \`{ success: false, code, message, ... }\`
+or older \`{ error, status, details? }\` responses. Branch on \`code\` when
+present and surface \`message\` or \`error\` verbatim. Common cases:
 
 - \`pending_approval\`: queued for the user's approval (see above).
 - \`insufficient_funds\`: the Haven wallet doesn't hold enough of that token.
   Suggest the user add funds in the Haven dashboard.
+- \`PRICE_EXCEEDS_MAX\`: the live merchant price exceeded your \`max_amount\`.
+  No funds moved; ask the user before retrying with a higher cap.
+- \`PAYMENT_WINDOW_EXPIRED\`: re-run \`mcp__haven__haven_pay_mcp_tool\` with the same
+  \`idempotency_key\`, then sign the fresh \`payload_hash\`.
+- \`MERCHANT_REJECTED_AFTER_FUNDING\`: stop retrying the merchant and use
+  \`mcp__haven__haven_sweep_delegate\` to recover stranded delegate funds.
 - Budget exceeded: tell the user how much remains (from
   \`haven_get_allowances\`) and that they can raise the budget in Haven.
 
@@ -3170,9 +3420,105 @@ for that credential.
 `;
 var SKILL_FOLDER_NAME = "haven-pay";
 
+// src/sweep.ts
+var SWEEP_BASE_CHAIN_ID = 8453;
+var SWEEP_BASE_USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+var USDC_EIP712_DOMAIN_BY_CHAIN = {
+  [SWEEP_BASE_CHAIN_ID]: {
+    name: "USD Coin",
+    version: "2",
+    chainId: SWEEP_BASE_CHAIN_ID,
+    verifyingContract: SWEEP_BASE_USDC_ADDRESS
+  }
+};
+var USDC_ADDRESS_BY_CHAIN = {
+  [SWEEP_BASE_CHAIN_ID]: SWEEP_BASE_USDC_ADDRESS
+};
+var TRANSFER_WITH_AUTHORIZATION_TYPES = {
+  TransferWithAuthorization: [
+    { name: "from", type: "address" },
+    { name: "to", type: "address" },
+    { name: "value", type: "uint256" },
+    { name: "validAfter", type: "uint256" },
+    { name: "validBefore", type: "uint256" },
+    { name: "nonce", type: "bytes32" }
+  ]
+};
+function sweepUsdcAddress(chainId) {
+  const address = USDC_ADDRESS_BY_CHAIN[chainId];
+  if (!address) {
+    throw new HavenSigningError(
+      `Sweep is only supported on Base (chainId ${SWEEP_BASE_CHAIN_ID}). Got chainId ${chainId}.`
+    );
+  }
+  return address;
+}
+function sweepUsdcDomain(chainId) {
+  const domain = USDC_EIP712_DOMAIN_BY_CHAIN[chainId];
+  if (!domain) {
+    throw new HavenSigningError(
+      `Sweep is only supported on Base (chainId ${SWEEP_BASE_CHAIN_ID}). Got chainId ${chainId}.`
+    );
+  }
+  return domain;
+}
+function sameAddress2(a, b) {
+  return a.toLowerCase() === b.toLowerCase();
+}
+function buildSweepTypedData(auth) {
+  const domain = sweepUsdcDomain(auth.chainId);
+  const expectedToken = sweepUsdcAddress(auth.chainId);
+  if (!sameAddress2(auth.token, expectedToken)) {
+    throw new HavenSigningError(
+      `Sweep token ${auth.token} is not the canonical USDC contract for chain ${auth.chainId}.`
+    );
+  }
+  if (!/^0x[0-9a-fA-F]{64}$/.test(auth.nonce)) {
+    throw new HavenSigningError("Sweep nonce must be a 0x-prefixed 32-byte hex string.");
+  }
+  return {
+    domain,
+    types: TRANSFER_WITH_AUTHORIZATION_TYPES,
+    primaryType: "TransferWithAuthorization",
+    message: {
+      from: auth.from,
+      to: auth.to,
+      value: BigInt(auth.value),
+      validAfter: BigInt(auth.validAfter),
+      validBefore: BigInt(auth.validBefore),
+      nonce: auth.nonce
+    }
+  };
+}
+function buildSweepAuthorizationMessage(auth) {
+  return `Haven sweep authorization v1
+${stableStringify2({
+    version: 1,
+    kind: "haven.sweep.authorization",
+    from: auth.from.toLowerCase(),
+    to: auth.to.toLowerCase(),
+    value: auth.value,
+    validAfter: auth.validAfter,
+    validBefore: auth.validBefore,
+    nonce: auth.nonce.toLowerCase(),
+    token: auth.token.toLowerCase(),
+    chainId: auth.chainId
+  })}`;
+}
+function stableStringify2(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map((item) => stableStringify2(item)).join(",")}]`;
+  const object = value;
+  return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${stableStringify2(object[key])}`).join(",")}}`;
+}
+
+exports.AGENT_PAYMENT_FAILURE_CODE_VALUES = AGENT_PAYMENT_FAILURE_CODE_VALUES;
 exports.AGENT_PAYMENT_NEXT_ACTION_VALUES = AGENT_PAYMENT_NEXT_ACTION_VALUES;
 exports.AGENT_PAYMENT_PHASE_VALUES = AGENT_PAYMENT_PHASE_VALUES;
 exports.AGENT_PAYMENT_RAIL_VALUES = AGENT_PAYMENT_RAIL_VALUES;
+exports.AgentPaymentFailureCode = AgentPaymentFailureCode;
+exports.AgentPaymentFailureCodeDescriptions = AgentPaymentFailureCodeDescriptions;
+exports.AgentPaymentFailureCodeSchema = AgentPaymentFailureCodeSchema;
 exports.AgentPaymentNextAction = AgentPaymentNextAction;
 exports.AgentPaymentNextActionDescriptions = AgentPaymentNextActionDescriptions;
 exports.AgentPaymentNextActionSchema = AgentPaymentNextActionSchema;
@@ -3190,8 +3536,13 @@ exports.HavenPaymentStateError = HavenPaymentStateError;
 exports.HavenSigningError = HavenSigningError;
 exports.HavenTimeoutError = HavenTimeoutError;
 exports.SKILL_FOLDER_NAME = SKILL_FOLDER_NAME;
+exports.SWEEP_BASE_CHAIN_ID = SWEEP_BASE_CHAIN_ID;
+exports.SWEEP_BASE_USDC_ADDRESS = SWEEP_BASE_USDC_ADDRESS;
+exports.TRANSFER_WITH_AUTHORIZATION_TYPES = TRANSFER_WITH_AUTHORIZATION_TYPES;
 exports.addressFromKey = addressFromKey;
 exports.buildMachinePaymentIdempotencyKey = buildMachinePaymentIdempotencyKey;
+exports.buildSweepAuthorizationMessage = buildSweepAuthorizationMessage;
+exports.buildSweepTypedData = buildSweepTypedData;
 exports.buildX402ExpectedMessage = buildX402ExpectedMessage;
 exports.composeDescription = composeDescription;
 exports.decodeBase64Json = decodeBase64Json;
@@ -3208,6 +3559,8 @@ exports.parsePaymentRequiredResponse = parsePaymentRequiredResponse;
 exports.selectPaymentOption = selectPaymentOption;
 exports.selectStandardPaymentOption = selectStandardPaymentOption;
 exports.signHash = signHash;
+exports.sweepUsdcAddress = sweepUsdcAddress;
+exports.sweepUsdcDomain = sweepUsdcDomain;
 exports.toStandardPaymentRequirements = toStandardPaymentRequirements;
 exports.toolDescriptions = toolDescriptions;
 exports.verifySignature = verifySignature;