@haven_ai/sdk 0.1.3 → 0.1.5

package/dist/index.js

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from 'async_hooks';
 import { exact } from 'x402/schemes';
 import { privateKeyToAccount } from 'viem/accounts';
 import { ethers } from 'ethers';
@@ -6,6 +7,114 @@ import { createHash } from 'crypto';
 // src/client.ts
 
 // src/types.ts
+var AgentPaymentPhase = {
+  /** The agent must sign and submit the prepared payment before Haven can relay it. */
+  AgentSignatureRequired: "agent_signature_required",
+  /** Haven has received the signed payment and the agent should poll for confirmation. */
+  PaymentSubmitted: "payment_submitted",
+  /** The direct payment is confirmed; the agent does not need to do more for this payment id. */
+  PaymentConfirmed: "payment_confirmed",
+  /** The payment needs wallet owner approval in Haven before it can continue. */
+  UserApprovalRequired: "user_approval_required",
+  /** The wallet owner approved the request and still needs to complete the funding payment. */
+  UserExecutionRequired: "user_execution_required",
+  /** The funding payment was proposed and is waiting for the remaining account approvals. */
+  WaitingForAdditionalApprovals: "waiting_for_additional_approvals",
+  /** The Haven funding leg was sent; the agent can continue the merchant/protocol leg. */
+  FundingSent: "funding_sent",
+  /** The wallet owner rejected the request; the agent should stop and tell the user. */
+  Rejected: "rejected",
+  /** The payment or approval request expired before completion. */
+  Expired: "expired",
+  /** Haven could not complete the payment; the agent should stop and surface the failure. */
+  Failed: "failed"
+};
+var AgentPaymentNextAction = {
+  /** Sign with the delegate key and submit the payment to Haven. */
+  SignAndSubmitPayment: "sign_and_submit_payment",
+  /** Poll getPaymentStatus later using this payment id. */
+  CheckStatusLater: "check_status_later",
+  /** No further agent action is required for this payment id. */
+  None: "none",
+  /** Wait for the wallet owner to approve or reject the request in Haven. */
+  WaitForUserApproval: "wait_for_user_approval",
+  /** Wait for the wallet owner to finish sending the approved funding payment. */
+  WaitForUserToCompletePayment: "wait_for_user_to_complete_payment",
+  /** Resume this payment id and retry the original x402 request with the merchant payment header. */
+  RetryOriginalX402Request: "retry_original_x402_request",
+  /** Stop retrying this payment and tell the user what happened. */
+  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"
+};
+var AgentPaymentRail = {
+  /** Standard Haven payment from the user's Safe through an approved delegate allowance. */
+  Direct: "direct",
+  /** x402 HTTP 402 payment flow with a Haven funding leg and merchant retry leg. */
+  X402: "x402",
+  /** Machine Payment Protocol family — categorical value used as a resume-state discriminator. */
+  Mpp: "mpp",
+  /** Haven internal MPP demo rail. Not for production traffic. */
+  MppDemo: "mpp_demo",
+  /** Crypto-settled MPP rail. */
+  MppCrypto: "mpp_crypto",
+  /** Stripe-deposit-backed MPP rail. */
+  StripeDeposit: "stripe_deposit",
+  /** Stripe Payment Token MPP rail. */
+  Spt: "spt"
+};
+var AGENT_PAYMENT_PHASE_VALUES = Object.values(AgentPaymentPhase);
+var AGENT_PAYMENT_NEXT_ACTION_VALUES = Object.values(AgentPaymentNextAction);
+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.",
+  [AgentPaymentPhase.PaymentSubmitted]: "Haven has received the signed payment and the agent should poll for confirmation.",
+  [AgentPaymentPhase.PaymentConfirmed]: "The direct payment is confirmed; the agent does not need to do more for this payment id.",
+  [AgentPaymentPhase.UserApprovalRequired]: "The payment needs wallet owner approval in Haven before it can continue.",
+  [AgentPaymentPhase.UserExecutionRequired]: "The wallet owner approved the request and still needs to complete the funding payment.",
+  [AgentPaymentPhase.WaitingForAdditionalApprovals]: "The funding payment was proposed and is waiting for the remaining account approvals.",
+  [AgentPaymentPhase.FundingSent]: "The Haven funding leg was sent; the agent can continue the merchant/protocol leg.",
+  [AgentPaymentPhase.Rejected]: "The wallet owner rejected the request; the agent should stop and tell the user.",
+  [AgentPaymentPhase.Expired]: "The payment or approval request expired before completion.",
+  [AgentPaymentPhase.Failed]: "Haven could not complete the payment; the agent should stop and surface the failure."
+};
+var AgentPaymentNextActionDescriptions = {
+  [AgentPaymentNextAction.SignAndSubmitPayment]: "Sign with the delegate key and submit the payment to Haven.",
+  [AgentPaymentNextAction.CheckStatusLater]: "Poll getPaymentStatus later using this payment id.",
+  [AgentPaymentNextAction.None]: "No further agent action is required for this payment id.",
+  [AgentPaymentNextAction.WaitForUserApproval]: "Wait for the wallet owner to approve or reject the request in Haven.",
+  [AgentPaymentNextAction.WaitForUserToCompletePayment]: "Wait for the wallet owner to finish sending the approved funding payment.",
+  [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."
+};
+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.",
+  [AgentPaymentRail.Mpp]: "Categorical MPP rail value used as a resume-state discriminator. Response bodies carry a granular mpp_* value instead.",
+  [AgentPaymentRail.MppDemo]: "Haven internal MPP demo rail. Not for production traffic.",
+  [AgentPaymentRail.MppCrypto]: "Crypto-settled MPP rail.",
+  [AgentPaymentRail.StripeDeposit]: "Stripe-deposit-backed MPP rail.",
+  [AgentPaymentRail.Spt]: "Stripe Payment Token MPP rail."
+};
+var AgentPaymentPhaseSchema = {
+  type: "string",
+  enum: AGENT_PAYMENT_PHASE_VALUES,
+  description: "Stable Haven agent payment state phase.",
+  "x-enumDescriptions": AgentPaymentPhaseDescriptions
+};
+var AgentPaymentNextActionSchema = {
+  type: "string",
+  enum: AGENT_PAYMENT_NEXT_ACTION_VALUES,
+  description: "Stable next action an agent should take for a Haven payment state.",
+  "x-enumDescriptions": AgentPaymentNextActionDescriptions
+};
+var AgentPaymentRailSchema = {
+  type: "string",
+  enum: AGENT_PAYMENT_RAIL_VALUES,
+  description: "Stable rail identifier for Haven agent payment states.",
+  "x-enumDescriptions": AgentPaymentRailDescriptions
+};
 var HavenError = class extends Error {
   constructor(message, code, statusCode, paymentId) {
     super(message);
@@ -33,6 +142,7 @@ var HavenPaymentStateError = class extends HavenApiError {
     this.name = "HavenPaymentStateError";
   }
   state;
+  resumeState;
   get status() {
     return this.state.status;
   }
@@ -160,6 +270,10 @@ var BASE_TOKENS = {
   "0x0000000000000000000000000000000000000000": { symbol: "ETH", decimals: 18 },
   "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913": { symbol: "USDC", decimals: 6 }
 };
+var ALL_TOKENS = {
+  ...GNOSIS_TOKENS,
+  ...BASE_TOKENS
+};
 var NETWORK_TOKENS = {
   "eip155:100": GNOSIS_TOKENS,
   "eip155:8453": BASE_TOKENS,
@@ -221,6 +335,23 @@ function selectStandardPaymentOption(accepts) {
   }
   return null;
 }
+function x402AuthorizationAmount(option) {
+  return option.maxAmountRequired ?? option.amount;
+}
+function buildX402ExpectedMessage(context) {
+  return `Haven x402 expected context v1
+${stableStringify({
+    version: 1,
+    kind: "haven.x402.expected",
+    paymentId: context.paymentId,
+    payloadHash: context.payloadHash.toLowerCase(),
+    resourceUrl: context.resourceUrl,
+    merchantTo: context.merchantTo.toLowerCase(),
+    amount: context.amount,
+    asset: context.asset.toLowerCase(),
+    network: context.network
+  })}`;
+}
 function toStandardPaymentRequirements(paymentRequired, option) {
   const network = STANDARD_X402_NETWORKS[option.network];
   if (!network) {
@@ -232,7 +363,7 @@ function toStandardPaymentRequirements(paymentRequired, option) {
   return {
     scheme: "exact",
     network,
-    maxAmountRequired: option.maxAmountRequired ?? option.amount,
+    maxAmountRequired: x402AuthorizationAmount(option),
     resource: option.resource ?? paymentRequired.resource.url,
     description: option.description ?? paymentRequired.resource.description ?? "Haven x402 payment",
     mimeType: option.mimeType ?? paymentRequired.resource.mimeType ?? "application/octet-stream",
@@ -249,7 +380,7 @@ function buildX402IdempotencyKey(paymentRequired, option, now = Date.now()) {
     paymentRequired.resource.description ?? "",
     option.payTo.toLowerCase(),
     option.asset.toLowerCase(),
-    option.amount,
+    x402AuthorizationAmount(option),
     option.network,
     bucket
   ].join("|");
@@ -271,6 +402,22 @@ function encodePaymentProof(receipt) {
   };
   return btoa(JSON.stringify(payload));
 }
+function resolveTokenFromAddress(address, network) {
+  const lower = address.toLowerCase();
+  if (network && network in NETWORK_TOKENS) {
+    return NETWORK_TOKENS[network][lower] ?? null;
+  }
+  return ALL_TOKENS[lower] ?? null;
+}
+function stableStringify(value) {
+  if (value === null || typeof value !== "object") {
+    const primitive = JSON.stringify(value);
+    return primitive === void 0 ? "undefined" : primitive;
+  }
+  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(",")}}`;
+}
 function decodeBase64Json2(value, label) {
   try {
     return JSON.parse(atob(value));
@@ -380,30 +527,33 @@ function chainIdFromNetwork(network) {
   const chainId = Number(network.slice("eip155:".length));
   return Number.isFinite(chainId) ? chainId : void 0;
 }
+function chainIdOrNull(network) {
+  return chainIdFromNetwork(network) ?? null;
+}
 function phaseForStatus(status) {
-  if (status === "pending_signature") return "agent_signature_required";
-  if (status === "submitted") return "payment_submitted";
-  if (status === "confirmed") return "payment_confirmed";
-  if (status === "pending" || status === "pending_approval") return "user_approval_required";
-  if (status === "approved") return "user_execution_required";
-  if (status === "proposed") return "waiting_for_additional_approvals";
-  if (status === "executed") return "funding_sent";
-  if (status === "rejected") return "rejected";
-  if (status === "expired") return "expired";
-  if (status === "failed") return "failed";
+  if (status === "pending_signature") return AgentPaymentPhase.AgentSignatureRequired;
+  if (status === "submitted") return AgentPaymentPhase.PaymentSubmitted;
+  if (status === "confirmed") return AgentPaymentPhase.PaymentConfirmed;
+  if (status === "pending" || status === "pending_approval") return AgentPaymentPhase.UserApprovalRequired;
+  if (status === "approved") return AgentPaymentPhase.UserExecutionRequired;
+  if (status === "proposed") return AgentPaymentPhase.WaitingForAdditionalApprovals;
+  if (status === "executed") return AgentPaymentPhase.FundingSent;
+  if (status === "rejected") return AgentPaymentPhase.Rejected;
+  if (status === "expired") return AgentPaymentPhase.Expired;
+  if (status === "failed") return AgentPaymentPhase.Failed;
   return null;
 }
 function nextActionForStatus(status) {
-  if (status === "pending_signature") return "sign_and_submit_payment";
-  if (status === "submitted") return "check_status_later";
-  if (status === "confirmed") return "none";
-  if (status === "pending" || status === "pending_approval") return "wait_for_user_approval";
-  if (status === "approved") return "wait_for_user_to_complete_payment";
-  if (status === "proposed") return "wait_for_user_approval";
-  if (status === "executed") return "retry_original_x402_request";
-  if (status === "rejected") return "stop_and_tell_user";
-  if (status === "expired") return "request_again_if_user_still_wants_it";
-  if (status === "failed") return "stop_and_tell_user";
+  if (status === "pending_signature") return AgentPaymentNextAction.SignAndSubmitPayment;
+  if (status === "submitted") return AgentPaymentNextAction.CheckStatusLater;
+  if (status === "confirmed") return AgentPaymentNextAction.None;
+  if (status === "pending" || status === "pending_approval") return AgentPaymentNextAction.WaitForUserApproval;
+  if (status === "approved") return AgentPaymentNextAction.WaitForUserToCompletePayment;
+  if (status === "proposed") return AgentPaymentNextAction.WaitForUserApproval;
+  if (status === "executed") return AgentPaymentNextAction.RetryOriginalX402Request;
+  if (status === "rejected") return AgentPaymentNextAction.StopAndTellUser;
+  if (status === "expired") return AgentPaymentNextAction.RequestAgainIfUserStillWantsIt;
+  if (status === "failed") return AgentPaymentNextAction.StopAndTellUser;
   return null;
 }
 function messageForState(label, status, paymentId, nextAction) {
@@ -424,6 +574,9 @@ function messageForState(label, status, paymentId, nextAction) {
 function sameAddress(a, b) {
   return Boolean(a && b && a.toLowerCase() === b.toLowerCase());
 }
+function isMppRail(rail) {
+  return rail === "mpp" || Boolean(rail?.startsWith("mpp_"));
+}
 function decimalFromUsdcAtomic(value) {
   const amount = BigInt(value);
   const whole = amount / 1000000n;
@@ -454,6 +607,19 @@ var HavenClient = class {
   inFlightX402 = /* @__PURE__ */ new Map();
   x402ReceiptCache = /* @__PURE__ */ new Map();
   inFlightMachinePayments = /* @__PURE__ */ new Map();
+  /**
+   * 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.
+   */
+  defaultHeaders;
+  /**
+   * 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.
+   */
+  requestContext = new AsyncLocalStorage();
   /** Delegate address derived from the private key (if provided) */
   delegateAddress;
   constructor(config) {
@@ -464,10 +630,29 @@ var HavenClient = class {
     this.requestTimeout = config.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT;
     this.confirmationTimeout = config.confirmationTimeout ?? DEFAULT_CONFIRMATION_TIMEOUT;
     this.pollingInterval = config.pollingInterval ?? DEFAULT_POLLING_INTERVAL;
+    this.defaultHeaders = { ...config.defaultHeaders ?? {} };
     if (this.delegateKey) {
       this.delegateAddress = addressFromKey(this.delegateKey);
     }
   }
+  /**
+   * Run `fn` with extra Haven-API headers scoped to the async work it
+   * performs. Used by the MCP server to tag every Haven API request that
+   * a single tool dispatch makes with `X-Haven-MCP-Tool: <name>` so the
+   * backend can write an audit-log row attributing the call.
+   *
+   * The headers are held in an `AsyncLocalStorage` so overlapping
+   * dispatches do not leak headers into each other's requests. The store
+   * inherits across `await` boundaries, so any Haven API call made while
+   * `fn` is awaiting will pick up the right headers.
+   *
+   * Has no effect on outbound merchant requests (x402 / MPP) — those
+   * never go through the internal `request<T>` path that reads the
+   * context.
+   */
+  withRequestContext(headers, fn) {
+    return this.requestContext.run({ headers: { ...headers } }, fn);
+  }
   // ── High-Level API ───────────────────────────────────────────────
   /**
    * Send a payment in one call.
@@ -510,6 +695,70 @@ var HavenClient = class {
       signData: raw.sign_data
     };
   }
+  /**
+   * Keyless x402 construct.
+   *
+   * The non-custodial half of an x402 payment: posts the funding request to
+   * `/x402` and returns the unsigned funding hash plus the data the caller
+   * needs to build and sign the EIP-3009 merchant header itself. Crucially it
+   * does **not** sign — neither the funding hash nor the merchant header — so
+   * it works without a `delegateKey`. Both delegate signatures happen on the
+   * machine that holds the key (the edge); the hosted MCP server relays only.
+   *
+   * Use this from the hosted, keyless server. The all-in-one `authorizeX402`
+   * remains for local clients that hold the key.
+   *
+   * Throws (via the shared payment-state path) when the amount exceeds the
+   * on-chain allowance — there is nothing to sign until the user approves.
+   */
+  async createX402Intent(paymentRequired, options = {}) {
+    const option = selectStandardPaymentOption(paymentRequired.accepts);
+    if (!option) {
+      throw new HavenApiError(
+        "No compatible payment option found in x402 requirements. Haven supports standard x402 exact payments on Base USDC.",
+        400
+      );
+    }
+    const agent = await this.getAgent();
+    const fundingTo = agent.delegateAddress;
+    if (!fundingTo) {
+      throw new HavenApiError("Authenticated agent has no delegate address registered.", 502);
+    }
+    const idempotencyKey = options.idempotencyKey ?? buildX402IdempotencyKey(paymentRequired, option);
+    const raw = await this.post("/x402", {
+      url: paymentRequired.resource.url,
+      payTo: fundingTo,
+      merchantPayTo: option.payTo,
+      amount: x402AuthorizationAmount(option),
+      asset: option.asset,
+      network: option.network,
+      description: paymentRequired.resource.description,
+      idempotencyKey
+    });
+    if (raw.status !== "pending_signature") {
+      this.throwPaymentStateError("x402 payment", raw);
+    }
+    if (!raw.sign_data?.hash) {
+      throw new HavenApiError("No sign_hash returned from x402/authorize", 500, raw);
+    }
+    if (!raw.x402_expected_auth) {
+      throw new HavenApiError("No x402 expected-context binding returned from x402/authorize", 500, raw);
+    }
+    return {
+      paymentId: raw.payment_id,
+      status: "pending_signature",
+      expiresAt: raw.expires_at,
+      signData: raw.sign_data,
+      accepted: option,
+      resourceUrl: paymentRequired.resource.url,
+      merchantTo: raw.merchant_to ?? option.payTo,
+      amountAtomic: x402AuthorizationAmount(option),
+      asset: option.asset,
+      network: option.network,
+      expectedAuth: raw.x402_expected_auth,
+      fundingTo
+    };
+  }
   /**
    * Step 2: Sign a hash with the delegate key.
    *
@@ -562,6 +811,66 @@ var HavenClient = class {
     const raw = await this.get(`/machine-payments/${paymentId}/status`);
     return this.mapPaymentStatusResult(raw);
   }
+  /**
+   * Get the agent identity tied to this API key.
+   */
+  async getAgent() {
+    const raw = await this.get("/machine-payments/agent");
+    return {
+      id: raw.id,
+      name: raw.name,
+      status: raw.status,
+      safeAddress: raw.safe_address,
+      delegateAddress: raw.delegate_address,
+      chainId: raw.chain_id
+    };
+  }
+  /**
+   * Get configured and on-chain allowances for the authenticated agent.
+   */
+  async getAllowances() {
+    const raw = await this.get("/machine-payments/allowances");
+    return {
+      agentId: raw.agent_id,
+      safeAddress: raw.safe_address,
+      delegateAddress: raw.delegate_address,
+      chainId: raw.chain_id,
+      allowances: raw.allowances.map((allowance) => ({
+        id: allowance.id,
+        tokenAddress: allowance.token_address,
+        tokenSymbol: allowance.token_symbol,
+        configuredAmount: allowance.configured_amount,
+        resetPeriodMin: allowance.reset_period_min,
+        onchain: {
+          amount: allowance.onchain.amount,
+          spent: allowance.onchain.spent,
+          remaining: allowance.onchain.remaining,
+          effectiveSpent: allowance.onchain.effective_spent,
+          resetTimeMin: allowance.onchain.reset_time_min,
+          lastResetMin: allowance.onchain.last_reset_min,
+          nonce: allowance.onchain.nonce,
+          isResetPending: allowance.onchain.is_reset_pending
+        }
+      }))
+    };
+  }
+  /**
+   * List recent machine-payment receipts/evidence for bookkeeping.
+   */
+  async listReceipts(options = {}) {
+    const query = options.limit ? `?limit=${encodeURIComponent(String(options.limit))}` : "";
+    const raw = await this.get(`/machine-payments/receipts${query}`);
+    return raw.receipts.map((receipt) => this.mapPaymentReceipt(receipt));
+  }
+  /**
+   * Rehydrate the x402/MPP resume-state bundle for a payment id.
+   *
+   * The server returns stored protocol context only. The client still signs the
+   * merchant proof locally when resumeX402Payment() or resumeMppPayment() runs.
+   */
+  async getResumeState(paymentId) {
+    return this.get(`/payments/${paymentId}/resume_state`);
+  }
   /**
    * Poll until a payment reaches a terminal status (confirmed, failed, expired).
    */
@@ -611,17 +920,69 @@ var HavenClient = class {
     this.inFlightX402.set(idempotencyKey, promise);
     try {
       return await promise;
+    } catch (err) {
+      this.attachResumeState(err, {
+        rail: "x402",
+        paymentRequired,
+        accepted: option,
+        idempotencyKey
+      });
+      throw err;
     } finally {
       this.inFlightX402.delete(idempotencyKey);
     }
   }
+  /**
+   * Probe a paid endpoint and return its x402 quote without creating a Haven
+   * payment or approval request.
+   */
+  async quoteX402(url, init, options = {}) {
+    const initialInit = this.withX402Wallet(init, this.x402PayerAddress());
+    const request = this.snapshotX402Request(url, initialInit);
+    const response = await globalThis.fetch(url, initialInit);
+    if (response.status !== 402) {
+      throw new HavenApiError(
+        `Expected an x402 quote response with HTTP 402, got HTTP ${response.status}.`,
+        response.status || 400
+      );
+    }
+    if (response.headers.get("MACHINE-PAYMENT-CHALLENGE")) {
+      throw new HavenApiError("quoteX402 only supports standard x402 Payment Required responses.", 400);
+    }
+    const paymentRequired = await parsePaymentRequiredResponse(response);
+    return this.buildX402Quote(paymentRequired, request, options.idempotencyKey);
+  }
+  /**
+   * Pay a previously inspected x402 quote and retry the exact captured request.
+   */
+  async payX402Quote(quote, options = {}) {
+    const idempotencyKey = options.idempotencyKey ?? quote.idempotencyKey;
+    try {
+      const receipt = await this.authorizeX402(quote.paymentRequired, { idempotencyKey });
+      return this.retryX402Request(
+        quote.request.url,
+        this.requestInitFromSnapshot(quote.request),
+        quote.paymentRequired,
+        receipt
+      );
+    } catch (err) {
+      this.attachResumeState(err, {
+        rail: "x402",
+        paymentRequired: quote.paymentRequired,
+        accepted: quote.accepted,
+        idempotencyKey,
+        request: quote.request
+      });
+      throw err;
+    }
+  }
   async authorizeStandardX402(paymentRequired, option, idempotencyKey) {
     const paymentHeader = await this.createStandardX402Header(paymentRequired, option);
     const raw = await this.post("/x402", {
       url: paymentRequired.resource.url,
       payTo: this.delegateAddress,
       merchantPayTo: option.payTo,
-      amount: option.amount,
+      amount: x402AuthorizationAmount(option),
       asset: option.asset,
       network: option.network,
       description: paymentRequired.resource.description,
@@ -633,7 +994,7 @@ var HavenClient = class {
       return receipt2;
     }
     const state = this.paymentStateFromRaw("x402 payment", raw);
-    if (state?.nextAction === "retry_original_x402_request") {
+    if (state?.nextAction === AgentPaymentNextAction.RetryOriginalX402Request) {
       const receipt2 = this.mapX402ReceiptFromStatus(paymentRequired, option, paymentHeader, state);
       this.cacheX402Receipt(idempotencyKey, paymentHeader, receipt2);
       return receipt2;
@@ -681,10 +1042,18 @@ var HavenClient = class {
     return receipt;
   }
   async resumeX402Payment(input) {
-    const initialInit = this.withX402Wallet(input.init, this.x402PayerAddress());
+    const inputInit = "init" in input ? input.init : void 0;
+    const initialInit = this.withX402Wallet(
+      inputInit ?? (input.request ? this.requestInitFromSnapshot(input.request) : void 0),
+      this.x402PayerAddress()
+    );
     let paymentRequired = input.paymentRequired;
+    const url = input.url ?? input.request?.url;
     if (!paymentRequired) {
-      const response = await globalThis.fetch(input.url, initialInit);
+      if (!url) {
+        throw new HavenApiError("x402 resume requires the original URL or a captured request snapshot.", 400);
+      }
+      const response = await globalThis.fetch(url, initialInit);
       if (response.status !== 402) {
         throw new HavenApiError("Expected the original x402 request to return HTTP 402 before resuming.", 400);
       }
@@ -695,7 +1064,7 @@ var HavenClient = class {
       paymentRequired,
       idempotencyKey: input.idempotencyKey
     });
-    return this.retryX402Request(input.url, initialInit, paymentRequired, receipt);
+    return this.retryX402Request(url ?? paymentRequired.resource.url, initialInit, paymentRequired, receipt);
   }
   /**
    * Fetch wrapper that automatically handles HTTP 402 responses.
@@ -731,9 +1100,69 @@ var HavenClient = class {
       }
       return this.fetchWithMachinePayment(url, initialInit, challenge);
     }
-    const receipt = await this.authorizeX402(paymentRequired, options);
+    const request = this.snapshotX402Request(url, initialInit);
+    const option = selectStandardPaymentOption(paymentRequired.accepts);
+    const idempotencyKey = options.idempotencyKey ?? (option ? buildX402IdempotencyKey(paymentRequired, option) : void 0);
+    let receipt;
+    try {
+      receipt = await this.authorizeX402(paymentRequired, options);
+    } catch (err) {
+      if (option && idempotencyKey) {
+        this.attachResumeState(err, {
+          rail: "x402",
+          paymentRequired,
+          accepted: option,
+          idempotencyKey,
+          request
+        });
+      }
+      throw err;
+    }
     return this.retryX402Request(url, initialInit, paymentRequired, receipt);
   }
+  /**
+   * Probe a paid MPP endpoint or inspect an existing challenge without creating
+   * a Haven payment or approval request.
+   */
+  async quoteMpp(challengeOrUrl, init, options = {}) {
+    if (typeof challengeOrUrl !== "string") {
+      const request2 = this.snapshotX402Request(challengeOrUrl.resource, init);
+      return this.buildMppQuote(challengeOrUrl, request2, options.idempotencyKey);
+    }
+    const request = this.snapshotX402Request(challengeOrUrl, init);
+    const response = await globalThis.fetch(challengeOrUrl, init);
+    if (response.status !== 402) {
+      throw new HavenApiError(
+        `Expected an MPP quote response with HTTP 402, got HTTP ${response.status}.`,
+        response.status || 400
+      );
+    }
+    const challenge = await parseMachinePaymentChallengeResponse(response);
+    return this.buildMppQuote(challenge, request, options.idempotencyKey);
+  }
+  /**
+   * Pay a previously inspected MPP quote and retry the exact captured request.
+   */
+  async payMppChallenge(quote, options = {}) {
+    const idempotencyKey = options.idempotencyKey ?? quote.idempotencyKey;
+    try {
+      const receipt = await this.authorizeMachinePayment(quote.challenge, { idempotencyKey });
+      return this.retryMppRequest(
+        quote.request.url,
+        this.requestInitFromSnapshot(quote.request),
+        quote.challenge,
+        receipt
+      );
+    } catch (err) {
+      this.attachResumeState(err, {
+        rail: "mpp",
+        challenge: quote.challenge,
+        idempotencyKey,
+        request: quote.request
+      });
+      throw err;
+    }
+  }
   async retryX402Request(url, initialInit, paymentRequired, receipt) {
     if (!receipt.accepted) {
       throw new HavenApiError("No accepted x402 option was recorded for payment retry", 500);
@@ -795,7 +1224,7 @@ var HavenClient = class {
     });
     return retryResponse;
   }
-  async authorizeMachinePayment(challenge) {
+  async authorizeMachinePayment(challenge, options = {}) {
     if (!this.delegateKey) {
       throw new HavenSigningError(
         "delegateKey is required for machine payments. Pass it in the HavenClient config."
@@ -804,13 +1233,20 @@ var HavenClient = class {
     if (challenge.rail !== "mpp_demo") {
       throw new HavenApiError(`Unsupported machine payment rail: ${challenge.rail}`, 400);
     }
-    const idempotencyKey = buildMachinePaymentIdempotencyKey(challenge);
+    const idempotencyKey = options.idempotencyKey ?? buildMachinePaymentIdempotencyKey(challenge);
     const inFlight = this.inFlightMachinePayments.get(idempotencyKey);
     if (inFlight) return inFlight;
     const promise = this.authorizeMppDemoPayment(challenge, idempotencyKey);
     this.inFlightMachinePayments.set(idempotencyKey, promise);
     try {
       return await promise;
+    } catch (err) {
+      this.attachResumeState(err, {
+        rail: "mpp",
+        challenge,
+        idempotencyKey
+      });
+      throw err;
     } finally {
       this.inFlightMachinePayments.delete(idempotencyKey);
     }
@@ -837,8 +1273,56 @@ var HavenClient = class {
     }
     return this.mapMachinePaymentReceipt(challenge, raw, execResult.tx_hash, execResult);
   }
+  async resumeAuthorizedMpp(input) {
+    if (!this.delegateKey) {
+      throw new HavenSigningError(
+        "delegateKey is required for machine payments. Pass it in the HavenClient config."
+      );
+    }
+    const status = await this.getPaymentStatus(input.paymentId);
+    this.assertCanResumeMpp(status, input.challenge);
+    return this.mapMachinePaymentReceiptFromStatus(input.challenge, status);
+  }
+  async resumeMppPayment(input) {
+    const inputInit = "init" in input ? input.init : void 0;
+    const initialInit = inputInit ?? (input.request ? this.requestInitFromSnapshot(input.request) : void 0);
+    let challenge = input.challenge;
+    const url = input.url ?? input.request?.url;
+    if (!challenge) {
+      if (!url) {
+        throw new HavenApiError("MPP resume requires the original URL or a captured request snapshot.", 400);
+      }
+      const response = await globalThis.fetch(url, initialInit);
+      if (response.status !== 402) {
+        throw new HavenApiError("Expected the original MPP request to return HTTP 402 before resuming.", 400);
+      }
+      challenge = await parseMachinePaymentChallengeResponse(response);
+    }
+    const receipt = await this.resumeAuthorizedMpp({
+      paymentId: input.paymentId,
+      challenge,
+      idempotencyKey: input.idempotencyKey
+    });
+    return this.retryMppRequest(url ?? challenge.resource, initialInit, challenge, receipt);
+  }
   async fetchWithMachinePayment(url, initialInit, challenge) {
-    const receipt = await this.authorizeMachinePayment(challenge);
+    const request = this.snapshotX402Request(url, initialInit);
+    const idempotencyKey = buildMachinePaymentIdempotencyKey(challenge);
+    let receipt;
+    try {
+      receipt = await this.authorizeMachinePayment(challenge, { idempotencyKey });
+    } catch (err) {
+      this.attachResumeState(err, {
+        rail: "mpp",
+        challenge,
+        idempotencyKey,
+        request
+      });
+      throw err;
+    }
+    return this.retryMppRequest(url, initialInit, challenge, receipt);
+  }
+  async retryMppRequest(url, initialInit, challenge, receipt) {
     const retryHeaders = new Headers(initialInit?.headers);
     retryHeaders.set("MACHINE-PAYMENT-PROOF", receipt.proofHeader);
     const retryResponse = await globalThis.fetch(url, {
@@ -890,7 +1374,7 @@ var HavenClient = class {
         status
       );
     }
-    if (status.nextAction !== "retry_original_x402_request") {
+    if (status.nextAction !== AgentPaymentNextAction.RetryOriginalX402Request) {
       throw new HavenPaymentStateError(status.message, PAYMENT_STATE_STATUS_CODES[status.status] ?? 409, status);
     }
     if (!status.txHash) {
@@ -935,7 +1419,7 @@ var HavenClient = class {
       );
     }
     const approvedAmount = status.amount ? normalizeDecimal(status.amount) : "";
-    const requestedAmount = normalizeDecimal(decimalFromUsdcAtomic(option.amount));
+    const requestedAmount = normalizeDecimal(decimalFromUsdcAtomic(x402AuthorizationAmount(option)));
     if (approvedAmount && approvedAmount !== requestedAmount) {
       throw new HavenApiError(
         "x402 resume request does not match the approved amount.",
@@ -945,11 +1429,73 @@ var HavenClient = class {
       );
     }
   }
+  assertCanResumeMpp(status, challenge) {
+    if (!isMppRail(status.rail)) {
+      throw new HavenPaymentStateError(
+        `Payment ${status.paymentId} is ${status.rail}, not MPP.`,
+        409,
+        status
+      );
+    }
+    if (status.nextAction !== AgentPaymentNextAction.RetryOriginalX402Request) {
+      throw new HavenPaymentStateError(status.message, PAYMENT_STATE_STATUS_CODES[status.status] ?? 409, status);
+    }
+    if (!status.txHash) {
+      throw new HavenApiError(
+        `MPP payment ${status.paymentId} is ready to retry but has no Haven transaction hash.`,
+        502,
+        status,
+        status.paymentId
+      );
+    }
+    if (status.resourceUrl && status.resourceUrl !== challenge.resource) {
+      throw new HavenApiError(
+        "MPP resume request does not match the approved resource URL.",
+        409,
+        { status, challenge },
+        status.paymentId
+      );
+    }
+    if (status.merchantAddress && !sameAddress(status.merchantAddress, challenge.recipient)) {
+      throw new HavenApiError(
+        "MPP resume request does not match the approved merchant.",
+        409,
+        { status, challenge },
+        status.paymentId
+      );
+    }
+    if (status.chainId && status.chainId !== challenge.network.chainId) {
+      throw new HavenApiError(
+        "MPP resume request does not match the approved network.",
+        409,
+        { status, challenge },
+        status.paymentId
+      );
+    }
+    if (status.token && status.token !== challenge.asset.symbol) {
+      throw new HavenApiError(
+        "MPP resume request does not match the approved token.",
+        409,
+        { status, challenge },
+        status.paymentId
+      );
+    }
+    const approvedAmount = status.amount ? normalizeDecimal(status.amount) : "";
+    const requestedAmount = normalizeDecimal(challenge.amount.display);
+    if (approvedAmount && approvedAmount !== requestedAmount) {
+      throw new HavenApiError(
+        "MPP resume request does not match the approved amount.",
+        409,
+        { status, challenge },
+        status.paymentId
+      );
+    }
+  }
   mapX402ReceiptFromAuthorization(paymentRequired, option, paymentHeader, raw, execResult) {
     const txHash = execResult?.tx_hash ?? raw.tx_hash ?? "";
     const chainId = execResult?.chain_id ?? raw.chain_id ?? chainIdFromNetwork(option.network);
     const token = execResult?.token ?? raw.token ?? "USDC";
-    const amount = execResult?.amount ?? raw.amount ?? decimalFromUsdcAtomic(option.amount);
+    const amount = execResult?.amount ?? raw.amount ?? decimalFromUsdcAtomic(x402AuthorizationAmount(option));
     const to = execResult?.to ?? raw.to ?? this.delegateAddress ?? "";
     const explorerUrl = execResult?.explorer_url ?? raw.explorer_url ?? explorerUrlOrEmpty(chainId, txHash);
     const merchantTo = execResult?.merchant_to ?? raw.merchant_to ?? option.payTo;
@@ -982,7 +1528,7 @@ var HavenClient = class {
       paymentId: status.paymentId,
       txHash: status.txHash,
       token: status.token || "USDC",
-      amount: status.amount || decimalFromUsdcAtomic(option.amount),
+      amount: status.amount || decimalFromUsdcAtomic(x402AuthorizationAmount(option)),
       to: this.delegateAddress ?? "",
       resourceUrl: paymentRequired.resource.url,
       explorerUrl: explorerUrlOrEmpty(status.chainId, status.txHash),
@@ -1018,7 +1564,7 @@ var HavenClient = class {
         payTo: input.merchantTo ?? input.accepted.payTo
       },
       x402: {
-        amount: input.accepted.amount,
+        amount: x402AuthorizationAmount(input.accepted),
         token: input.token,
         network: input.accepted.network,
         asset: input.accepted.asset,
@@ -1071,6 +1617,33 @@ var HavenClient = class {
       proofHeader: encodeMachinePaymentProof(receiptWithoutHeader)
     };
   }
+  mapMachinePaymentReceiptFromStatus(challenge, status) {
+    if (!status.txHash) {
+      throw new HavenApiError(
+        `MPP payment ${status.paymentId} is ready to retry but has no Haven transaction hash.`,
+        502,
+        status,
+        status.paymentId
+      );
+    }
+    const receiptWithoutHeader = {
+      success: true,
+      rail: challenge.rail,
+      paymentId: status.paymentId,
+      challengeId: challenge.challengeId,
+      txHash: status.txHash,
+      token: status.token || challenge.asset.symbol,
+      amount: status.amount || challenge.amount.display,
+      to: status.merchantAddress ?? challenge.recipient,
+      resourceUrl: status.resourceUrl ?? challenge.resource,
+      explorerUrl: explorerUrlOrEmpty(status.chainId || challenge.network.chainId, status.txHash),
+      chainId: status.chainId || challenge.network.chainId
+    };
+    return {
+      ...receiptWithoutHeader,
+      proofHeader: encodeMachinePaymentProof(receiptWithoutHeader)
+    };
+  }
   async recordMerchantRetryRejected(input) {
     try {
       await this.post("/machine-payments/reconciliation-events", {
@@ -1154,16 +1727,64 @@ var HavenClient = class {
       amount,
       token,
       resourceUrl: raw.resource_url ?? null,
-      merchantAddress: raw.merchant_to ?? null,
+      merchantAddress: raw.merchant_address ?? raw.merchant_to ?? null,
       txHash: raw.tx_hash ?? null,
       expiresAt: raw.expires_at ?? "",
       chainId: raw.chain_id ?? 0,
-      message
+      message,
+      amountAtomic: raw.amount_atomic ?? raw.x402?.amount_atomic ?? raw.mpp?.amount_atomic ?? null,
+      asset: raw.asset ?? raw.x402?.asset ?? raw.mpp?.asset ?? null,
+      network: raw.network ?? raw.x402?.network ?? raw.mpp?.network ?? null,
+      description: raw.description ?? raw.x402?.description ?? raw.mpp?.description ?? null,
+      idempotencyKey: raw.idempotency_key ?? raw.x402?.idempotency_key ?? raw.mpp?.idempotency_key ?? null,
+      x402: raw.x402 ? {
+        amountAtomic: raw.x402.amount_atomic ?? raw.amount_atomic ?? null,
+        asset: raw.x402.asset ?? raw.asset ?? null,
+        network: raw.x402.network ?? raw.network ?? null,
+        resourceUrl: raw.x402.resource_url ?? raw.resource_url ?? null,
+        merchantAddress: raw.x402.merchant_address ?? raw.merchant_address ?? raw.merchant_to ?? null,
+        description: raw.x402.description ?? raw.description ?? null,
+        idempotencyKey: raw.x402.idempotency_key ?? raw.idempotency_key ?? null
+      } : void 0,
+      mpp: raw.mpp ? {
+        amountAtomic: raw.mpp.amount_atomic ?? raw.amount_atomic ?? null,
+        asset: raw.mpp.asset ?? raw.asset ?? null,
+        network: raw.mpp.network ?? raw.network ?? null,
+        resourceUrl: raw.mpp.resource_url ?? raw.resource_url ?? null,
+        merchantAddress: raw.mpp.merchant_address ?? raw.merchant_address ?? raw.merchant_to ?? null,
+        description: raw.mpp.description ?? raw.description ?? null,
+        idempotencyKey: raw.mpp.idempotency_key ?? raw.idempotency_key ?? null,
+        challengeId: raw.mpp.challenge_id ?? raw.challenge_id ?? null
+      } : void 0
     };
   }
   x402PayerAddress() {
     return this.delegateAddress ?? this.x402Wallet;
   }
+  snapshotX402Request(url, init) {
+    return {
+      url,
+      method: init?.method ?? "GET",
+      headers: Array.from(new Headers(init?.headers).entries()),
+      body: this.snapshotRequestBody(init?.body)
+    };
+  }
+  snapshotRequestBody(body) {
+    if (body == null) return void 0;
+    if (typeof body === "string") return body;
+    if (body instanceof URLSearchParams) return body.toString();
+    throw new HavenApiError(
+      "Quote helpers can only capture resumable request bodies that are strings or URLSearchParams. For streams, blobs, or binary bodies, preserve the original request yourself and call the matching resume method with fresh init.",
+      400
+    );
+  }
+  requestInitFromSnapshot(request) {
+    return {
+      method: request.method,
+      headers: request.headers,
+      body: request.body
+    };
+  }
   withX402Wallet(init, wallet = this.x402PayerAddress()) {
     if (!wallet) return init;
     const headers = new Headers(init?.headers);
@@ -1175,6 +1796,134 @@ var HavenClient = class {
       headers
     };
   }
+  buildX402Quote(paymentRequired, request, idempotencyKey) {
+    const option = selectStandardPaymentOption(paymentRequired.accepts);
+    if (!option) {
+      throw new HavenApiError(
+        "No compatible payment option found in x402 requirements. Haven supports standard x402 exact payments on Base USDC.",
+        400
+      );
+    }
+    const token = resolveTokenFromAddress(option.asset, option.network);
+    return {
+      rail: "x402",
+      idempotencyKey: idempotencyKey ?? buildX402IdempotencyKey(paymentRequired, option),
+      paymentRequired,
+      accepted: option,
+      request,
+      resourceUrl: paymentRequired.resource.url,
+      description: paymentRequired.resource.description ?? option.description ?? null,
+      mimeType: paymentRequired.resource.mimeType ?? option.mimeType ?? null,
+      amountAtomic: x402AuthorizationAmount(option),
+      amount: decimalFromUsdcAtomic(x402AuthorizationAmount(option)),
+      token: token?.symbol ?? "USDC",
+      asset: option.asset,
+      network: option.network,
+      chainId: chainIdOrNull(option.network),
+      merchantAddress: option.payTo,
+      maxTimeoutSeconds: option.maxTimeoutSeconds
+    };
+  }
+  buildX402ResumeState(input) {
+    const token = resolveTokenFromAddress(input.accepted.asset, input.accepted.network);
+    return {
+      rail: "x402",
+      paymentId: input.paymentId,
+      idempotencyKey: input.idempotencyKey,
+      paymentRequired: input.paymentRequired,
+      accepted: input.accepted,
+      url: input.request?.url ?? input.paymentRequired.resource.url,
+      request: input.request,
+      resourceUrl: input.paymentRequired.resource.url,
+      description: input.paymentRequired.resource.description ?? input.accepted.description ?? null,
+      amountAtomic: x402AuthorizationAmount(input.accepted),
+      amount: decimalFromUsdcAtomic(x402AuthorizationAmount(input.accepted)),
+      token: token?.symbol ?? "USDC",
+      asset: input.accepted.asset,
+      network: input.accepted.network,
+      chainId: chainIdOrNull(input.accepted.network),
+      merchantAddress: input.accepted.payTo
+    };
+  }
+  buildMppQuote(challenge, request, idempotencyKey) {
+    return {
+      rail: "mpp",
+      paymentRail: challenge.rail,
+      idempotencyKey: idempotencyKey ?? buildMachinePaymentIdempotencyKey(challenge),
+      challenge,
+      request,
+      resourceUrl: challenge.resource,
+      description: challenge.description ?? null,
+      amountAtomic: challenge.amount.atomic,
+      amount: challenge.amount.display,
+      token: challenge.asset.symbol,
+      asset: challenge.asset.address,
+      network: challenge.network.name,
+      chainId: challenge.network.chainId,
+      merchantAddress: challenge.recipient,
+      expiresAt: challenge.expiresAt
+    };
+  }
+  buildMppResumeState(input) {
+    const quote = this.buildMppQuote(
+      input.challenge,
+      input.request ?? this.snapshotX402Request(input.challenge.resource),
+      input.idempotencyKey
+    );
+    return {
+      rail: "mpp",
+      paymentRail: quote.paymentRail,
+      paymentId: input.paymentId,
+      idempotencyKey: quote.idempotencyKey,
+      challenge: input.challenge,
+      url: input.request?.url ?? input.challenge.resource,
+      request: input.request,
+      resourceUrl: quote.resourceUrl,
+      description: quote.description,
+      amountAtomic: quote.amountAtomic,
+      amount: quote.amount,
+      token: quote.token,
+      asset: quote.asset,
+      network: quote.network,
+      chainId: quote.chainId,
+      merchantAddress: quote.merchantAddress,
+      expiresAt: quote.expiresAt
+    };
+  }
+  attachResumeState(err, input) {
+    if (input.rail === "x402") {
+      this.attachX402ResumeState(
+        err,
+        input.paymentRequired,
+        input.accepted,
+        input.idempotencyKey,
+        input.request
+      );
+      return;
+    }
+    this.attachMppResumeState(err, input.challenge, input.idempotencyKey, input.request);
+  }
+  attachX402ResumeState(err, paymentRequired, accepted, idempotencyKey, request) {
+    if (!(err instanceof HavenPaymentStateError)) return;
+    if (err.state.rail !== "x402") return;
+    err.resumeState = this.buildX402ResumeState({
+      paymentId: err.state.paymentId,
+      paymentRequired,
+      accepted,
+      idempotencyKey,
+      request
+    });
+  }
+  attachMppResumeState(err, challenge, idempotencyKey, request) {
+    if (!(err instanceof HavenPaymentStateError)) return;
+    if (!isMppRail(err.state.rail)) return;
+    err.resumeState = this.buildMppResumeState({
+      paymentId: err.state.paymentId,
+      challenge,
+      idempotencyKey,
+      request
+    });
+  }
   // ── Tool Execution (for agent frameworks) ────────────────────────
   /**
    * Execute a tool call by name and input.
@@ -1234,9 +1983,9 @@ var HavenClient = class {
       }
     }
     if (toolName === "authorize_machine_payment") {
-      const { challenge } = input;
+      const { challenge, idempotencyKey } = input;
       try {
-        const receipt = await this.authorizeMachinePayment(challenge);
+        const receipt = await this.authorizeMachinePayment(challenge, { idempotencyKey });
         return {
           success: true,
           payment_id: receipt.paymentId,
@@ -1271,11 +2020,21 @@ var HavenClient = class {
         amount: result.amount,
         resource_url: result.resourceUrl,
         merchant_address: result.merchantAddress,
+        amount_atomic: result.amountAtomic,
+        asset: result.asset,
+        network: result.network,
+        description: result.description,
+        idempotency_key: result.idempotencyKey,
+        x402: result.x402,
+        mpp: result.mpp,
         expires_at: result.expiresAt,
         chain_id: result.chainId,
         message: result.message
       };
     }
+    if (toolName === "get_allowances") {
+      return { ...await this.getAllowances() };
+    }
     throw new Error(`Unknown tool: ${toolName}`);
   }
   toolX402PaymentRequired(input) {
@@ -1328,6 +2087,31 @@ var HavenClient = class {
         amount: err.state.amount,
         resource_url: err.state.resourceUrl,
         merchant_address: err.state.merchantAddress,
+        amount_atomic: err.state.amountAtomic,
+        asset: err.state.asset,
+        network: err.state.network,
+        description: err.state.description,
+        idempotency_key: err.state.idempotencyKey,
+        x402: err.state.x402 ? {
+          amount_atomic: err.state.x402.amountAtomic,
+          asset: err.state.x402.asset,
+          network: err.state.x402.network,
+          resource_url: err.state.x402.resourceUrl,
+          merchant_address: err.state.x402.merchantAddress,
+          description: err.state.x402.description,
+          idempotency_key: err.state.x402.idempotencyKey
+        } : void 0,
+        mpp: err.state.mpp ? {
+          amount_atomic: err.state.mpp.amountAtomic,
+          asset: err.state.mpp.asset,
+          network: err.state.mpp.network,
+          resource_url: err.state.mpp.resourceUrl,
+          merchant_address: err.state.mpp.merchantAddress,
+          description: err.state.mpp.description,
+          idempotency_key: err.state.mpp.idempotencyKey,
+          challenge_id: err.state.mpp.challengeId
+        } : void 0,
+        resume_state: err.resumeState,
         expires_at: err.state.expiresAt,
         chain_id: err.state.chainId,
         message: err.state.message,
@@ -1359,11 +2143,14 @@ var HavenClient = class {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), this.requestTimeout);
     try {
+      const contextHeaders = this.requestContext.getStore()?.headers ?? {};
       const res = await fetch(url, {
         method,
         headers: {
           "Content-Type": "application/json",
-          "Authorization": `Bearer ${this.apiKey}`
+          "Authorization": `Bearer ${this.apiKey}`,
+          ...this.defaultHeaders,
+          ...contextHeaders
         },
         body: body ? JSON.stringify(body) : void 0,
         signal: controller.signal
@@ -1420,7 +2207,50 @@ var HavenClient = class {
       txHash: raw.tx_hash,
       expiresAt: raw.expires_at,
       chainId: raw.chain_id,
-      message: raw.message
+      message: raw.message,
+      amountAtomic: raw.amount_atomic ?? raw.x402?.amount_atomic ?? null,
+      asset: raw.asset ?? raw.x402?.asset ?? null,
+      network: raw.network ?? raw.x402?.network ?? null,
+      description: raw.description ?? raw.x402?.description ?? null,
+      idempotencyKey: raw.idempotency_key ?? raw.x402?.idempotency_key ?? null,
+      x402: raw.x402 ? {
+        amountAtomic: raw.x402.amount_atomic ?? raw.amount_atomic ?? null,
+        asset: raw.x402.asset ?? raw.asset ?? null,
+        network: raw.x402.network ?? raw.network ?? null,
+        resourceUrl: raw.x402.resource_url ?? raw.resource_url,
+        merchantAddress: raw.x402.merchant_address ?? raw.merchant_address,
+        description: raw.x402.description ?? raw.description ?? null,
+        idempotencyKey: raw.x402.idempotency_key ?? raw.idempotency_key ?? null
+      } : void 0
+    };
+  }
+  mapPaymentReceipt(raw) {
+    return {
+      id: raw.id,
+      paymentId: raw.payment_id,
+      rail: raw.rail,
+      proofStatus: raw.proof_status,
+      txHash: raw.tx_hash,
+      chainId: raw.chain_id,
+      resourceUrl: raw.resource_url,
+      merchantAddress: raw.merchant_address,
+      payerAddress: raw.payer_address,
+      settlementAddress: raw.settlement_address,
+      tokenSymbol: raw.token_symbol,
+      tokenAddress: raw.token_address,
+      amountRaw: raw.amount_raw,
+      amount: raw.amount_human,
+      challengeId: raw.challenge_id,
+      idempotencyKey: raw.idempotency_key,
+      challengePayload: raw.challenge_payload,
+      selectedPayment: raw.selected_payment,
+      paymentProofHeaderName: raw.payment_proof_header_name,
+      protocolReceiptHeaderName: raw.protocol_receipt_header_name,
+      protocolReceiptPayload: raw.protocol_receipt_payload,
+      merchantStatus: raw.merchant_status,
+      confirmedAt: raw.confirmed_at,
+      createdAt: raw.created_at,
+      updatedAt: raw.updated_at
     };
   }
 };
@@ -1462,6 +2292,72 @@ async function responseSnippet(response) {
   }
 }
 
+// src/tool-descriptions.ts
+function composeDescription(d) {
+  return [d.summary, d.selectionGuidance, d.behavior, d.nextActionGuidance].filter(Boolean).join(" ");
+}
+var toolDescriptions = {
+  quoteX402: {
+    summary: "Inspect an HTTP 402 x402 paid resource without creating a Haven payment, signature, approval, or on-chain transaction.",
+    behavior: "Probes the merchant directly and parses the 402 response. Pure read-only client behavior \u2014 Haven is not contacted.",
+    nextActionGuidance: ""
+  },
+  payX402: {
+    summary: "Pay an inspected x402 quote. The delegate key signs locally; Haven only validates and relays signed, on-chain-constrained payment transactions.",
+    selectionGuidance: "Do not use this for read-only allowance, budget, spend-limit, remaining-amount, reset-period, or what-can-I-spend questions; use the allowance lookup tool instead.",
+    behavior: "Signs the EIP-3009 payment from the delegate wallet, asks Haven for a Safe AllowanceModule top-up if needed, and returns the merchant response or a pending-approval state.",
+    nextActionGuidance: "If approval is needed, preserve the returned resume_state and wait for nextAction=retry_original_x402_request before resuming."
+  },
+  resumeX402: {
+    summary: "Resume an x402 payment after the Haven wallet owner approved the funding step.",
+    behavior: "Accepts either resume_state or payment_id, validates the original x402 details against the approved Haven funding, and retries the merchant request with the X-PAYMENT header. No new Haven approval is created.",
+    nextActionGuidance: "Only use when get_payment_status returns nextAction=retry_original_x402_request; do not start a new merchant session."
+  },
+  quoteMpp: {
+    summary: "Inspect a Haven MPP challenge or paid MPP URL without creating a Haven payment, signature, approval, or on-chain transaction.",
+    behavior: "Parses an MPP challenge envelope and returns a typed quote with rail tag, amount, asset, and merchant context. Pure read-only \u2014 Haven is not contacted.",
+    nextActionGuidance: ""
+  },
+  payMpp: {
+    summary: "Pay an inspected MPP challenge. The delegate key signs locally; Haven only validates and relays signed, on-chain-constrained payment transactions.",
+    selectionGuidance: "Do not use this for read-only allowance, budget, spend-limit, remaining-amount, reset-period, or what-can-I-spend questions; use the allowance lookup tool instead.",
+    behavior: "Authorizes the payment through Haven within the on-chain allowance, signs the challenge proof, and returns the proof header for retrying the original paid resource.",
+    nextActionGuidance: "If approval is needed, preserve resume_state or payment_id and wait for nextAction=retry_original_x402_request before resuming."
+  },
+  resumeMpp: {
+    summary: "Resume an MPP payment after the Haven wallet owner approved the funding step.",
+    behavior: "Accepts either resume_state or payment_id and retries the original paid resource with the MPP proof header. No new Haven approval is created.",
+    nextActionGuidance: ""
+  },
+  getPaymentStatus: {
+    summary: "Fetch structured Haven payment status, including phase and nextAction taxonomy for agent recovery.",
+    behavior: "Accepts a payment intent or approval request id and returns the full state taxonomy (phase, nextAction, rail, amount, merchant, resource url, idempotency key, message).",
+    nextActionGuidance: ""
+  },
+  getResumeState: {
+    summary: "Rehydrate stored x402 or MPP resume_state by payment_id.",
+    behavior: "Returns the context that the agent originally received in a pending-approval response, reconstructed from Haven's database. This is context only; signing still happens locally when a resume tool is called.",
+    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.",
+    nextActionGuidance: ""
+  },
+  getAllowances: {
+    summary: "Return configured and on-chain allowance state for the authenticated agent. On-chain allowance is the real spend gate.",
+    selectionGuidance: "Use this when the user asks about allowance, budget, spend limit, remaining amount, remaining allowance, remaining budget, daily limit, reset period, what can I spend, or what the agent can still spend.",
+    behavior: "Reads the Safe AllowanceModule snapshot per token (allowance, spent, remaining, reset window). Configured amounts from Haven are returned alongside the on-chain truth.",
+    nextActionGuidance: ""
+  },
+  listReceipts: {
+    summary: "List recent machine-payment receipts and evidence for bookkeeping.",
+    selectionGuidance: "Use this for transaction history, receipts, payment evidence, or bookkeeping; use the allowance tool instead for remaining allowance, budget, spend-limit, or what-can-I-spend questions.",
+    behavior: "Returns the agent's recent machine-payment receipts ordered by recency. Proof header values are not returned.",
+    nextActionGuidance: ""
+  }
+};
+
 // src/tools.ts
 var makePaymentSchema = {
   type: "object",
@@ -1495,6 +2391,11 @@ var getPaymentStatusSchema = {
   },
   required: ["payment_id"]
 };
+var getAllowancesSchema = {
+  type: "object",
+  properties: {},
+  required: []
+};
 var authorizeX402Schema = {
   type: "object",
   properties: {
@@ -1577,11 +2478,12 @@ var authorizeMachinePaymentSchema = {
   },
   required: ["challenge"]
 };
-var MAKE_PAYMENT_DESCRIPTION = "Request and sign a payment from the user-controlled Safe within approved on-chain limits. Haven authenticates the agent, validates the signed intent, and relays the Safe AllowanceModule transaction; it does not hold keys or control funds. Gnosis Chain tokens: EURe, USDC.e, xDAI. Base tokens: USDC, ETH.";
-var GET_STATUS_DESCRIPTION = "Check the status of a previously initiated payment. Accepts payment intent IDs and approval request IDs. Returns the current status, phase, next_action, transaction hash if available, and payment details.";
-var AUTHORIZE_X402_DESCRIPTION = "Authorize payment for an HTTP 402 (Payment Required) response. When a paid API returns x402 payment requirements, use this tool to sign with the agent-owned delegate key and request a policy-limited Safe AllowanceModule top-up when needed. Haven relays signed transactions only; the agent key authorizes payment and on-chain limits enforce spend. If this returns pending_approval, tell the user it is waiting in Haven, call get_payment_status later, and use resume_x402_payment only when next_action is retry_original_x402_request. Do not loop retries while approval is pending. Use the returned payment_header as the X-PAYMENT header on the retry request when doing a manual HTTP retry.";
-var RESUME_X402_DESCRIPTION = "Resume an x402 payment after the user approved it in Haven. Use this only after get_payment_status returns next_action=retry_original_x402_request. It checks the approved payment, validates the original x402 details, and returns a merchant X-PAYMENT header without creating a new approval request.";
-var AUTHORIZE_MACHINE_PAYMENT_DESCRIPTION = "Authorize a Haven machine-payment challenge, currently for the internal MPP demo rail. The agent signs the payment, Haven relays it within the on-chain allowance, and the tool returns a proof header for the retry request.";
+var MAKE_PAYMENT_DESCRIPTION = "Request and sign a payment from the user-controlled Safe within approved on-chain limits. For read-only allowance, budget, spend-limit, remaining-amount, or reset-period questions, use get_allowances instead of making a payment. Haven authenticates the agent, validates the signed intent, and relays the Safe AllowanceModule transaction; it does not hold keys or control funds. Gnosis Chain tokens: EURe, USDC.e, xDAI. Base tokens: USDC, ETH.";
+var GET_STATUS_DESCRIPTION = toolDescriptions.getPaymentStatus.summary + " Accepts payment intent IDs and approval request IDs. Returns the current status, phase, next_action, transaction hash if available, and payment details.";
+var GET_ALLOWANCES_DESCRIPTION = composeDescription(toolDescriptions.getAllowances);
+var AUTHORIZE_X402_DESCRIPTION = composeDescription(toolDescriptions.payX402) + " In this SDK tool set, the allowance lookup tool is get_allowances. When a paid API returns x402 payment requirements, use this tool to sign with the agent-owned delegate key and request a policy-limited Safe AllowanceModule top-up when needed. Haven relays signed transactions only; the agent key authorizes payment and on-chain limits enforce spend. If this returns pending_approval, tell the user it is waiting in Haven, preserve the original merchant/MCP session and x402 details, call get_payment_status later, and use resume_x402_payment only when next_action is retry_original_x402_request. Do not start a new merchant session or loop retries while approval is pending. Use the returned payment_header as the X-PAYMENT header on the retry request when doing a manual HTTP retry.";
+var RESUME_X402_DESCRIPTION = toolDescriptions.resumeX402.summary + " Use this only after get_payment_status returns next_action=retry_original_x402_request. It checks the approved payment, validates the original x402 details, and returns a merchant X-PAYMENT header without creating a new approval request or merchant session.";
+var AUTHORIZE_MACHINE_PAYMENT_DESCRIPTION = composeDescription(toolDescriptions.payMpp) + " In this SDK tool set, the allowance lookup tool is get_allowances. Currently scoped to the internal MPP demo rail. The agent signs the payment, Haven relays it within the on-chain allowance, and the tool returns a proof header for the retry request.";
 function claudeTools() {
   return [
     {
@@ -1594,6 +2496,11 @@ function claudeTools() {
       description: GET_STATUS_DESCRIPTION,
       input_schema: getPaymentStatusSchema
     },
+    {
+      name: "get_allowances",
+      description: GET_ALLOWANCES_DESCRIPTION,
+      input_schema: getAllowancesSchema
+    },
     {
       name: "authorize_x402_payment",
       description: AUTHORIZE_X402_DESCRIPTION,
@@ -1629,6 +2536,14 @@ function openaiTools() {
         parameters: getPaymentStatusSchema
       }
     },
+    {
+      type: "function",
+      function: {
+        name: "get_allowances",
+        description: GET_ALLOWANCES_DESCRIPTION,
+        parameters: getAllowancesSchema
+      }
+    },
     {
       type: "function",
       function: {
@@ -1662,6 +2577,6 @@ var havenTools = {
   openai: openaiTools
 };
 
-export { HavenApiError, HavenClient, HavenError, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, addressFromKey, buildMachinePaymentIdempotencyKey, encodeMachinePaymentProof, encodePaymentProof, havenTools, parseMachinePaymentChallenge, parseMachinePaymentChallengeResponse, parsePaymentRequired, parsePaymentRequiredResponse, selectPaymentOption, signHash, verifySignature };
+export { AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, AgentPaymentNextAction, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, HavenApiError, HavenClient, HavenError, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, addressFromKey, buildMachinePaymentIdempotencyKey, buildX402ExpectedMessage, composeDescription, encodeMachinePaymentProof, encodePaymentProof, havenTools, parseMachinePaymentChallenge, parseMachinePaymentChallengeResponse, parsePaymentRequired, parsePaymentRequiredResponse, selectPaymentOption, selectStandardPaymentOption, signHash, toStandardPaymentRequirements, toolDescriptions, verifySignature, x402AuthorizationAmount };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map