@haven_ai/sdk 0.1.21-alpha.0 → 0.1.22-alpha.0

package/dist/index.cjs

@@ -64,6 +64,8 @@ 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",
+  /** #1307: retry the SAME tool call, supplying the explicit context fields the server could not rehydrate. */
+  RetryWithExplicitContext: "retry_with_explicit_context",
   /**
    * The x402 funding/quote window expired. Re-quote the same logical merchant
    * operation with the same idempotency key to stay double-charge-safe.
@@ -88,7 +90,21 @@ var AgentPaymentFailureCode = {
   /** 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"
+  MerchantRejectedAfterFunding: "MERCHANT_REJECTED_AFTER_FUNDING",
+  /** #1300 review: funding is on-chain but the merchant never ANSWERED the
+   *  paid retry within the timeout. NOT proof of rejection — the merchant
+   *  holds a valid EIP-3009 authorization and may still settle late, so the
+   *  guidance is verify-then-sweep, never blind sweep. */
+  MerchantUnresponsiveAfterFunding: "MERCHANT_UNRESPONSIVE_AFTER_FUNDING",
+  /**
+   * #1307: the caller omitted merchant_url/tool_name (asking Haven to
+   * rehydrate the stored MCP merchant-call context by payment_id), but no
+   * usable context was stored for this intent — either it was never an
+   * MCP-tool quote, or the stored context is incomplete. The fallback is
+   * mechanical: re-send merchant_url, tool_name, arguments, and
+   * mcp_transport explicitly (the version-skew path).
+   */
+  MerchantCallContextUnavailable: "MERCHANT_CALL_CONTEXT_UNAVAILABLE"
 };
 var AgentPaymentRail = {
   /** Standard Haven payment from the user's Safe through an approved delegate allowance. */
@@ -135,12 +151,46 @@ var AgentPaymentNextActionDescriptions = {
   [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.RetryWithExplicitContext]: "Retry the same tool call, this time passing merchant_url, tool_name, arguments, and mcp_transport explicitly \u2014 the server had no stored context to rehydrate for this payment id.",
   [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."
+  [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.",
+  [AgentPaymentFailureCode.MerchantUnresponsiveAfterFunding]: "The Haven funding leg succeeded, but the merchant did not answer the paid retry before the timeout. The merchant may still settle late \u2014 check haven_get_payment_status (and retry haven_complete_mcp_tool once) BEFORE sweeping; sweep only if no settlement appears.",
+  [AgentPaymentFailureCode.MerchantCallContextUnavailable]: "merchant_url/tool_name were omitted and no stored merchant call context is available for this payment_id. Re-send merchant_url, tool_name, arguments, and mcp_transport explicitly."
+};
+var AgentPaymentWarningCode = {
+  /** No max_amount cap was supplied — the live quoted price was accepted as-is. */
+  MissingMaxAmount: "MISSING_MAX_AMOUNT",
+  /** The signing window closes soon; sign promptly or re-quote with the same idempotency key. */
+  QuoteExpiresSoon: "QUOTE_EXPIRES_SOON",
+  /** The merchant URL was resolved via discovery — pass the RESOLVED url forward. */
+  MerchantUrlDiscovered: "MERCHANT_URL_DISCOVERED",
+  /**
+   * #1306: the catalog's last-verified price_atomic differs from the LIVE
+   * merchant quote for a guided catalog purchase. The catalog price is only
+   * ever indicative; the live quote in the same response is authoritative.
+   */
+  CatalogPriceDiffers: "CATALOG_PRICE_DIFFERS",
+  /**
+   * #1306: the rail-aware allowance/budget pre-check could not be read (RPC
+   * failure, etc). `sufficient` is reported as null rather than a fabricated
+   * true/false — the on-chain policy remains the actual gate either way.
+   */
+  AllowanceCheckUnavailable: "ALLOWANCE_CHECK_UNAVAILABLE",
+  /**
+   * #1319: the delegation-rail read itself SUCCEEDED, but the remaining
+   * figure it returned is the #1145 fallback (the full configured budget)
+   * rather than a live ERC20PeriodTransferEnforcer read — `sufficient` is a
+   * real true/false, just computed from an optimistic number. Distinct from
+   * {@link AgentPaymentWarningCode.AllowanceCheckUnavailable}, which fires
+   * when the read failed outright and `sufficient` degrades to null. The
+   * on-chain policy re-checks at redemption either way; this only says the
+   * guidance shown here may be optimistic.
+   */
+  AllowanceReadOptimistic: "ALLOWANCE_READ_OPTIMISTIC"
 };
 var AgentPaymentRailDescriptions = {
   [AgentPaymentRail.Direct]: "Standard Haven payment from the user-controlled Safe through an approved delegate allowance.",
@@ -195,6 +245,20 @@ var HavenApiError = class extends HavenError {
   }
   body;
 };
+var MerchantTimeoutError = class extends HavenApiError {
+  merchantErrorCode = "merchant_timeout";
+  constructor(message) {
+    super(message, 504);
+    this.name = "MerchantTimeoutError";
+  }
+};
+var X402UnexpectedStatusError = class extends HavenApiError {
+  x402ErrorCode = "unexpected_non_402_status";
+  constructor(message, statusCode) {
+    super(message, statusCode);
+    this.name = "X402UnexpectedStatusError";
+  }
+};
 var HavenPaymentStateError = class extends HavenApiError {
   constructor(message, statusCode, state, body) {
     super(message, statusCode, body, state.paymentId);
@@ -219,6 +283,25 @@ var HavenSigningError = class extends HavenError {
     this.name = "HavenSigningError";
   }
 };
+var SignerRefusalCode = {
+  /** `SUPPORTED_X402_EXPECTED_VERSIONS` in `@haven_ai/signer` does not include the received version. */
+  UnsupportedExpectedContextVersion: "UNSUPPORTED_EXPECTED_CONTEXT_VERSION",
+  /** `SUPPORTED_SWEEP_BINDING_VERSIONS` in `@haven_ai/signer` does not include the received version. */
+  UnsupportedSweepBindingVersion: "UNSUPPORTED_SWEEP_BINDING_VERSION"
+};
+var SIGNER_UPDATE_FALLBACK = "Update @haven_ai/signer by rerunning `npx @haven_ai/connect@alpha`, which reinstalls the pinned MCP runtime, then retry the same signing call. Nothing was signed or spent \u2014 the quote or payment this version came from is unaffected and does not need to be re-quoted.";
+var HavenUnsupportedSignerVersionError = class extends HavenError {
+  constructor(message, code, supportedVersions, receivedVersion, fallback) {
+    super(message, code);
+    this.supportedVersions = supportedVersions;
+    this.receivedVersion = receivedVersion;
+    this.fallback = fallback;
+    this.name = "HavenUnsupportedSignerVersionError";
+  }
+  supportedVersions;
+  receivedVersion;
+  fallback;
+};
 var HavenTimeoutError = class extends HavenError {
   constructor(paymentId) {
     super(
@@ -697,6 +780,8 @@ function explorerUrlOrEmpty(chainId, txHash) {
   return txHash ? buildExplorerUrl(chainId, txHash) : "";
 }
 var DEFAULT_REQUEST_TIMEOUT = 3e4;
+var DEFAULT_MERCHANT_TIMEOUT = 3e5;
+var NOTIFY_TIMEOUT = 1e4;
 var DEFAULT_CONFIRMATION_TIMEOUT = 9e4;
 var DEFAULT_POLLING_INTERVAL = 3e3;
 function formatAtomicAmount(atomic, decimals) {
@@ -860,12 +945,32 @@ function x402TypedDataDigest(typedData) {
     );
   }
 }
+function mapCatalogEntry(entry) {
+  return {
+    id: entry.id,
+    name: entry.name,
+    description: entry.description,
+    category: entry.category,
+    resourceUrl: entry.resource_url,
+    rail: entry.rail,
+    protocol: entry.protocol,
+    toolName: entry.tool_name,
+    toolArguments: entry.tool_arguments ?? null,
+    priceDisplay: entry.price_display,
+    priceAtomic: entry.price_atomic,
+    asset: entry.asset,
+    network: entry.network,
+    status: entry.status,
+    verifiedAt: entry.verified_at
+  };
+}
 var HavenClient = class {
   apiKey;
   delegateKey;
   baseUrl;
   x402Wallet;
   requestTimeout;
+  merchantTimeout;
   confirmationTimeout;
   pollingInterval;
   chainRpcs;
@@ -895,6 +1000,7 @@ var HavenClient = class {
     this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
     this.x402Wallet = config.x402Wallet;
     this.requestTimeout = config.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT;
+    this.merchantTimeout = config.merchantTimeout ?? DEFAULT_MERCHANT_TIMEOUT;
     this.confirmationTimeout = config.confirmationTimeout ?? DEFAULT_CONFIRMATION_TIMEOUT;
     this.pollingInterval = config.pollingInterval ?? DEFAULT_POLLING_INTERVAL;
     this.chainRpcs = config.chainRpcs ?? {};
@@ -1002,7 +1108,9 @@ var HavenClient = class {
       asset: option.asset,
       network: option.network,
       description: paymentRequired.resource.description,
-      idempotencyKey
+      idempotencyKey,
+      // #1307: persisted so the settle leg can rehydrate it by payment_id.
+      ...options.mcpCallContext ? { mcpCallContext: options.mcpCallContext } : {}
     });
     if (raw.status !== "pending_signature") {
       this.throwPaymentStateError("x402 payment", raw);
@@ -1141,7 +1249,12 @@ var HavenClient = class {
       status: raw.status,
       safeAddress: raw.safe_address,
       delegateAddress: raw.delegate_address,
-      chainId: raw.chain_id
+      chainId: raw.chain_id,
+      // Defensive normalization, not trust: the backend contract is exactly
+      // 'legacy' | 'delegation' (#1306), but an older/mismatched backend
+      // during a rollout window should degrade to the wider legacy bucket
+      // rather than propagate an unrecognized string.
+      executionRail: raw.execution_rail === "delegation" ? "delegation" : "legacy"
     };
   }
   /**
@@ -1291,11 +1404,108 @@ var HavenClient = class {
           resetTimeMin: allowance.onchain.reset_time_min,
           lastResetMin: allowance.onchain.last_reset_min,
           nonce: allowance.onchain.nonce,
-          isResetPending: allowance.onchain.is_reset_pending
+          isResetPending: allowance.onchain.is_reset_pending,
+          remainingIsFromChain: allowance.onchain.remaining_is_from_chain
         }
       }))
     };
   }
+  /**
+   * Post-purchase allowance/budget summary for a settled payment (#1310).
+   *
+   * Reuses the EXACT rail-aware read path {@link getAllowances} / #1306's
+   * catalog-purchase preflight `allowance` block use — `GET
+   * /machine-payments/allowances`, with delegation-rail values coming from
+   * the #1090 `deriveDelegationBudgets`-backed enforcer read, never
+   * `agent_allowances` — so this can never disagree with
+   * {@link getAllowances} for the same fixture. The settled token is
+   * resolved from {@link getPaymentStatus} so callers pass only
+   * `paymentId`, never a second haven_get_agent-style round trip.
+   *
+   * NEVER throws: any failed read (status lookup, agent lookup, or the
+   * allowance/budget lookup itself) degrades to `{ allowance: null,
+   * warnings: [ALLOWANCE_CHECK_UNAVAILABLE] }` rather than converting a
+   * successful settlement into a failure — the on-chain policy remains the
+   * actual spend gate regardless of whether this report can be produced.
+   *
+   * Freshness caveat (#1319): the delegation rail's on-chain enforcer read
+   * can silently fall back to the optimistic full period budget without
+   * throwing when the RPC read itself fails (#1145's fund-safe design,
+   * unchanged here). {@link getAllowances}'s `onchain.remainingIsFromChain`
+   * now carries that provenance on the wire, and the #1306 catalog-purchase
+   * preflight (`haven_prepare_catalog_purchase`) surfaces it as a warning —
+   * this summary does not (yet). `remaining_atomic` here reflects the last
+   * successful chain read, not a guaranteed-live one, and callers should not
+   * phrase it as guaranteed-fresh.
+   */
+  async getPostPurchaseAllowanceSummary(paymentId) {
+    const unavailable = (detail) => ({
+      allowance: null,
+      warnings: [
+        {
+          code: AgentPaymentWarningCode.AllowanceCheckUnavailable,
+          message: `Could not read the post-purchase allowance/budget for payment ${paymentId} (${detail}). The payment itself succeeded \u2014 the on-chain policy remains the actual spend gate; this only affects the remaining-budget figure reported here.`
+        }
+      ]
+    });
+    try {
+      const [status, agent, allowanceSummary] = await Promise.all([
+        this.getPaymentStatus(paymentId),
+        this.getAgent(),
+        this.getAllowances()
+      ]);
+      const tokenAddress = status.asset ?? status.x402?.asset ?? null;
+      if (!tokenAddress) {
+        return unavailable("the settled payment does not carry a resolvable token address");
+      }
+      const rail = agent.executionRail;
+      const source = rail === "delegation" ? "active_delegations" : "allowance_module";
+      const match = allowanceSummary.allowances.find(
+        (a) => a.tokenAddress.toLowerCase() === tokenAddress.toLowerCase()
+      );
+      if (!match) {
+        return unavailable("no allowance/budget row matches the settled token");
+      }
+      const token = resolveTokenFromAddress(match.tokenAddress);
+      const remainingDisplay = token ? `${formatAtomicAmount(safeBigInt(match.onchain.remaining), token.decimals)} ${match.tokenSymbol}` : void 0;
+      return {
+        allowance: {
+          rail,
+          remaining_atomic: match.onchain.remaining,
+          ...remainingDisplay ? { remaining_display: remainingDisplay } : {},
+          token_symbol: match.tokenSymbol,
+          token_address: match.tokenAddress,
+          reset_period: match.resetPeriodMin,
+          source
+        },
+        warnings: []
+      };
+    } catch (err) {
+      return unavailable(err instanceof Error ? err.message : String(err));
+    }
+  }
+  /**
+   * `haven_get_payment_status` convenience: fetch status and, for a
+   * genuinely SETTLED x402 payment, attach the same post-purchase
+   * allowance/budget summary a settle response carries.
+   *
+   * #1310/#1311 parity: this is the ONE home for logic that was duplicated
+   * verbatim in `packages/mcp-server/src/tools.ts` and `packages/mcp/src/tools.ts`
+   * (both hosted and local `haven_get_payment_status` handlers) — extracted
+   * here because both packages already depend on `@haven_ai/sdk` and call
+   * methods on a `HavenClient` instance, so this needed no new dependency
+   * edge. `funded_but_unsettled` is deliberately excluded: that phase means
+   * the merchant did NOT accept the retry. Every other phase/rail returns
+   * the status untouched.
+   */
+  async getPaymentStatusWithPostPurchaseAllowance(paymentId) {
+    const status = await this.getPaymentStatus(paymentId);
+    if (status.rail === AgentPaymentRail.X402 && status.phase === AgentPaymentPhase.PaymentConfirmed) {
+      const { allowance, warnings } = await this.getPostPurchaseAllowanceSummary(paymentId);
+      return { ...status, allowance, ...warnings.length > 0 ? { warnings } : {} };
+    }
+    return status;
+  }
   /**
    * Discover payable services from Haven's curated merchant catalog.
    *
@@ -1309,22 +1519,20 @@ var HavenClient = class {
     if (options.rail) params.set("rail", options.rail);
     const query = params.size > 0 ? `?${params.toString()}` : "";
     const raw = await this.get(`/catalog${query}`);
-    return raw.entries.map((entry) => ({
-      id: entry.id,
-      name: entry.name,
-      description: entry.description,
-      category: entry.category,
-      resourceUrl: entry.resource_url,
-      rail: entry.rail,
-      protocol: entry.protocol,
-      toolName: entry.tool_name,
-      priceDisplay: entry.price_display,
-      priceAtomic: entry.price_atomic,
-      asset: entry.asset,
-      network: entry.network,
-      status: entry.status,
-      verifiedAt: entry.verified_at
-    }));
+    return raw.entries.map(mapCatalogEntry);
+  }
+  /**
+   * Fetch one curated catalog entry by id (#1306).
+   *
+   * Chain-scoped for free by the backend's SQL when the client is
+   * agent-authenticated (#1299): an unknown id and an id curated for a
+   * DIFFERENT chain than this agent's both 404 identically — this method does
+   * not (and must not) re-filter by chain in JS. Read-only, like
+   * {@link discoverTools}.
+   */
+  async getCatalogEntry(id) {
+    const raw = await this.get(`/catalog/${encodeURIComponent(id)}`);
+    return mapCatalogEntry(raw);
   }
   /**
    * List recent machine-payment receipts/evidence for bookkeeping.
@@ -1423,9 +1631,9 @@ var HavenClient = class {
   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);
+    const response = await this.merchantFetch(url, initialInit);
     if (response.status !== 402) {
-      throw new HavenApiError(
+      throw new X402UnexpectedStatusError(
         `Expected an x402 quote response with HTTP 402, got HTTP ${response.status}.`,
         response.status || 400
       );
@@ -1437,6 +1645,34 @@ var HavenClient = class {
     const mcpTransport = await this.detectX402McpTransport(url, paymentRequired, response);
     return this.buildX402Quote(paymentRequired, request, options.idempotencyKey, mcpTransport);
   }
+  /**
+   * Probe an MCP tool for its x402 quote without creating a payment.
+   *
+   * Unlike the generic {@link quoteX402} helper, this completes the
+   * Streamable-HTTP MCP lifecycle before sending the unpaid `tools/call`.
+   * Hosted MCP uses this path while remaining keyless: it resolves only the
+   * agent's public delegate address for `x402-wallet`; signing remains local.
+   * It refuses before the quote when the merchant does not establish a session;
+   * callers that need a plain x402 endpoint must use {@link quoteX402}.
+   */
+  async quoteMcpX402(url, init, options = {}) {
+    const wallet = await this.resolveX402WalletForMerchantCall();
+    const sessionId = await this.mcpInitialize(url, init, wallet);
+    if (!sessionId) {
+      throw new HavenApiError(
+        "The merchant did not establish an MCP session before the x402 quote. No payment was created.",
+        502,
+        { mcpSessionNotEstablished: true }
+      );
+    }
+    let requestInit = this.withX402Wallet(init, wallet);
+    requestInit = this.withMcpHeaders(requestInit, sessionId);
+    const quote = await this.quoteX402(url, requestInit, options);
+    return {
+      ...quote,
+      mcpTransport: quote.mcpTransport ?? { handshakeRequired: true, source: "path" }
+    };
+  }
   /**
    * Pay a previously inspected x402 quote and retry the exact captured request.
    */
@@ -1542,7 +1778,7 @@ var HavenClient = class {
       if (!url) {
         throw new HavenApiError("x402 resume requires the original URL or a captured request snapshot.", 400);
       }
-      const response = await globalThis.fetch(url, initialInit);
+      const response = await this.merchantFetch(url, initialInit);
       if (response.status !== 402) {
         throw new HavenApiError("Expected the original x402 request to return HTTP 402 before resuming.", 400);
       }
@@ -1585,7 +1821,7 @@ var HavenClient = class {
     }
     let requestInit = this.withX402Wallet(init, this.x402PayerAddress());
     if (mcpSessionId) requestInit = this.withMcpHeaders(requestInit, mcpSessionId);
-    const response = await globalThis.fetch(url, requestInit);
+    const response = await this.merchantFetch(url, requestInit);
     if (response.status !== 402) {
       return mcpSessionId ? this.surfaceMcpResult(response) : response;
     }
@@ -1646,7 +1882,7 @@ var HavenClient = class {
       headers.set("Content-Type", "application/json");
       headers.set("Accept", MCP_ACCEPT);
       if (wallet && !headers.has("x402-wallet")) headers.set("x402-wallet", wallet);
-      const response = await globalThis.fetch(url, {
+      const response = await this.merchantFetch(url, {
         method: "POST",
         headers,
         body: JSON.stringify({
@@ -1683,11 +1919,15 @@ var HavenClient = class {
       headers.set("Accept", MCP_ACCEPT);
       headers.set("mcp-session-id", sessionId);
       if (wallet && !headers.has("x402-wallet")) headers.set("x402-wallet", wallet);
-      await globalThis.fetch(url, {
-        method: "POST",
-        headers,
-        body: JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" })
-      });
+      await this.merchantFetch(
+        url,
+        {
+          method: "POST",
+          headers,
+          body: JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" })
+        },
+        NOTIFY_TIMEOUT
+      );
     } catch {
     }
   }
@@ -1753,7 +1993,7 @@ var HavenClient = class {
       return this.buildMppQuote(challengeOrUrl, request2, options.idempotencyKey);
     }
     const request = this.snapshotX402Request(challengeOrUrl, init);
-    const response = await globalThis.fetch(challengeOrUrl, init);
+    const response = await this.merchantFetch(challengeOrUrl, init);
     if (response.status !== 402) {
       throw new HavenApiError(
         `Expected an MPP quote response with HTTP 402, got HTTP ${response.status}.`,
@@ -1795,7 +2035,7 @@ var HavenClient = class {
     }
     const retryHeaders = new Headers(initialInit?.headers);
     retryHeaders.set("X-PAYMENT", receipt.paymentHeader);
-    const retryResponse = await globalThis.fetch(url, {
+    const retryResponse = await this.merchantFetch(url, {
       ...initialInit,
       headers: retryHeaders
     });
@@ -1928,7 +2168,7 @@ var HavenClient = class {
     const headers = new Headers(requestInit.headers);
     headers.set("X-PAYMENT", input.paymentHeader);
     requestInit = { ...requestInit, headers };
-    const response = await globalThis.fetch(input.url, requestInit);
+    const response = await this.merchantFetch(input.url, requestInit);
     const surfaced = mcpSessionId ? await this.surfaceMcpResult(response) : response;
     const protocolReceiptHeader = surfaced.headers.get("PAYMENT-RESPONSE") ?? void 0;
     const settlement = parseMerchantSettlement(protocolReceiptHeader ?? null);
@@ -1976,6 +2216,33 @@ var HavenClient = class {
       settlementTxHash: settlement.settlementTxHash ?? void 0
     };
   }
+  /**
+   * GET /x402/:id/merchant-call-context — the settle-leg twin of #1263's
+   * sign-context fetch (#1307). Re-serves the stored merchant MCP-tool call
+   * context (merchant_url, tool_name, arguments, mcp_transport) recorded at
+   * quote time, so `haven_settle_mcp_tool` / `haven_complete_mcp_tool` can
+   * omit those fields and let Haven rehydrate them by payment_id instead of
+   * the caller re-threading them. Throws `HavenApiError` (404 unknown/foreign
+   * payment_id, 409 no stored context, 410 expired) — the caller decides the
+   * fallback (re-send the full context explicitly).
+   */
+  async getX402MerchantCallContext(paymentId) {
+    const raw = await this.get(
+      `/x402/${paymentId}/merchant-call-context`
+    );
+    return {
+      paymentId: raw.payment_id,
+      merchantUrl: raw.merchant_url,
+      toolName: raw.tool_name,
+      arguments: raw.arguments ?? {},
+      ...raw.mcp_transport ? {
+        mcpTransport: {
+          handshakeRequired: raw.mcp_transport.handshake_required,
+          source: raw.mcp_transport.source
+        }
+      } : {}
+    };
+  }
   async resolveX402MerchantCompletionContext(input) {
     const status = await this.getPaymentStatus(input.paymentId);
     if (status.rail !== "x402") {
@@ -2091,7 +2358,7 @@ var HavenClient = class {
       if (!url) {
         throw new HavenApiError("MPP resume requires the original URL or a captured request snapshot.", 400);
       }
-      const response = await globalThis.fetch(url, initialInit);
+      const response = await this.merchantFetch(url, initialInit);
       if (response.status !== 402) {
         throw new HavenApiError("Expected the original MPP request to return HTTP 402 before resuming.", 400);
       }
@@ -2124,7 +2391,7 @@ var HavenClient = class {
   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, {
+    const retryResponse = await this.merchantFetch(url, {
       ...initialInit,
       headers: retryHeaders
     });
@@ -2976,6 +3243,26 @@ var HavenClient = class {
   async get(path) {
     return this.request("GET", path);
   }
+  /**
+   * #1300: every MERCHANT-facing fetch goes through here. Haven API calls
+   * have always been bounded (request() below); the merchant probes/retries
+   * called globalThis.fetch bare, so a slow-loris merchant could hold a tool
+   * call open forever. A caller-supplied signal still applies (combined via
+   * AbortSignal.any); a timeout abort surfaces as a clear HavenApiError 504
+   * naming the URL rather than a bare AbortError.
+   */
+  async merchantFetch(url, init = {}, timeoutMs = this.merchantTimeout) {
+    const timeoutSignal = AbortSignal.timeout(timeoutMs);
+    const signal = init.signal ? AbortSignal.any([init.signal, timeoutSignal]) : timeoutSignal;
+    try {
+      return await globalThis.fetch(url, { ...init, signal });
+    } catch (err) {
+      if (timeoutSignal.aborted) {
+        throw new MerchantTimeoutError(`Merchant request timed out after ${timeoutMs}ms: ${url}`);
+      }
+      throw err;
+    }
+  }
   async request(method, path, body) {
     const url = `${this.baseUrl}${path}`;
     const controller = new AbortController();
@@ -3229,16 +3516,16 @@ var toolDescriptions = {
     nextActionGuidance: ""
   },
   payMcpTool: {
-    summary: "Call a named tool on an MCP merchant that requires an x402 payment, handling the full initialize \u2192 pay \u2192 retry round trip.",
+    summary: "Call a named tool on an MCP merchant that requires an x402 payment, handling the full initialize \u2192 pay \u2192 retry round trip in one call.",
     selectionGuidance: "Use this when the agent wants to call a specific tool on an MCP merchant (e.g. Soundside, Coinbase Bazaar) and payment is required. Prefer this over haven_pay_x402 when you know the merchant_url and tool_name \u2014 it builds the JSON-RPC envelope internally. Use haven_pay_x402 for arbitrary HTTP resources. Do NOT use for read-only allowance or budget questions \u2014 use haven_get_allowances.",
-    behavior: "Builds the JSON-RPC tools/call envelope, runs the MCP Streamable-HTTP initialize handshake automatically (if the endpoint is MCP-shaped), pays any HTTP 402 x402 challenge through Haven's AllowanceModule path, and retries the request. Returns the JSON-RPC result (the actual merchant output) on success. Amounts within the on-chain allowance execute automatically; over-allowance transfers are queued as pending_approval.",
+    behavior: "Builds the JSON-RPC tools/call envelope, runs the MCP Streamable-HTTP initialize handshake automatically (if the endpoint is MCP-shaped), pays any HTTP 402 x402 challenge through Haven's AllowanceModule path, and retries the request, returning the JSON-RPC result (the actual merchant output) on success. Amounts within the on-chain allowance execute automatically; over-allowance transfers are queued as pending_approval \u2014 follow the response's nextAction when present.",
     nextActionGuidance: "If pending_approval is returned, preserve payment_id and resume_state and wait for the wallet owner to approve in Haven. Use haven_resume_x402_payment once nextAction=retry_original_x402_request."
   },
   discoverTools: {
-    summary: "Discover payable services from Haven's curated merchant catalog \u2014 names, prices, and which pay tool to use.",
+    summary: "Step 1 of a purchase: discover payable services from Haven's curated merchant catalog \u2014 names, prices, and which pay tool to use next.",
     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. 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."
+    behavior: "Use each entry's suggested_tool field first \u2014 it names the exact next call. Read-only lookup against Haven's curated catalog; entries are periodically re-verified against the live merchant and degraded entries are flagged. Returns name, description, price, rail, resource URL, tool_name, tool_arguments, and suggested_tool. 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, tool_name, and tool_arguments 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.",
@@ -3507,6 +3794,9 @@ 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.
+Tool results carry the exact next step (\`next_action\`, \`next_tool\`,
+\`next_arguments\`) \u2014 follow those fields first; the prose below is fallback
+and orientation, not the source of truth.
 
 ## When to use this skill
 
@@ -3531,11 +3821,11 @@ 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.
+- \`mcp__haven__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.
+- \`mcp__haven__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
@@ -3543,47 +3833,79 @@ normal, not an error.
 
 ## Paying
 
-- **Direct transfer:** \`haven_pay\` with recipient, amount, and token.
-- **x402 paywall:** \`haven_quote_x402\` to get a quote, then
-  \`haven_pay_x402_quote\`. In the hosted setup the signing step happens in
-  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:** \`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.
+**Catalog purchases \u2014 the primary path for MCP merchants:**
+
+1. \`mcp__haven__haven_discover_tools\` to find a payable service and its
+   \`catalog_id\`.
+2. \`mcp__haven__haven_prepare_catalog_purchase\` with \`catalog_id\` and
+   \`max_amount\`. \`max_amount\` (atomic units) is REQUIRED on this tool, and
+   is best practice on every paid call below too \u2014 it caps what the LIVE
+   merchant quote may charge, checked before any funding intent is created.
+3. Then FOLLOW THE RESPONSE'S GUIDANCE FIELDS: \`next_action\`, \`next_tool\`,
+   and \`next_arguments\` name the exact next call \u2014 act on those first; the
+   prose in this section is fallback and debugging detail. If the catalog
+   entry is missing or degraded, the response instead names
+   \`mcp__haven__haven_pay_mcp_tool\` (merchant URL, tool name, arguments) as
+   the manual fallback.
+
+**Signing:** \`mcp__haven-signer__haven_sign_x402\` with \`payment_id\` and
+\`payment_required\` ONLY \u2014 the local signer fetches the exact signing bytes
+itself, so never relay \`typed_data\` yourself. Fallback for an older signer
+or backend: re-run the quote/prepare tool with the SAME \`idempotency_key\`
+plus \`include_signing_payload=true\`, then pass \`payload_hash\`,
+\`x402_expected\` (the nested \`x402.expected\` object), and
+\`typed_data\`/\`typed_data_b64\` through unchanged.
+
+**Settle:** \`mcp__haven__haven_settle_mcp_tool\` with \`payment_id\`,
+\`signature\`, and \`payment_header\` ONLY \u2014 Haven rehydrates the merchant call
+context (\`merchant_url\`, \`tool_name\`, \`arguments\`, \`mcp_transport\`)
+server-side from \`payment_id\`. Pass those four fields explicitly only as a
+version-skew fallback when Haven has no stored context for the id \u2014 both or
+none together, never just one. If the settle result carries \`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 (also key-safe; for an older signer or backend, or
+when you already have a merchant URL and tool name instead of a
+\`catalog_id\`): \`mcp__haven__haven_pay_mcp_tool\` then
+\`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 quote/prepare result.
+The returned \`expires_at\` is the signing window; if a tool returns
+\`PAYMENT_WINDOW_EXPIRED\`, re-run the same quote/prepare tool with the same
+\`idempotency_key\`. Do not call the merchant yourself \u2014 Haven completes the
+merchant leg for you.
+
+**Direct transfer / non-MCP paywall:** \`mcp__haven__haven_pay\` with
+recipient, amount, and token for a plain transfer. For an arbitrary,
+non-MCP x402 paywall: \`mcp__haven__haven_quote_x402\` to get a quote, then
+\`mcp__haven__haven_pay_x402_quote\` \u2014 follow the result's guidance fields
+first, sign in the local Haven signer, and retry the original request only
+when the result says \`retry_original_x402_request\`.
+
+**Catalog tool arguments:** when \`haven_discover_tools\` returns
+\`tool_arguments\`, pass that object unchanged as the pay tool's
+\`arguments\` field (for example
+\`tool_arguments: { "tier": "50gb" }\` -> \`arguments: { "tier": "50gb" }\`).
+
+**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.
+
+**Status:** \`mcp__haven__haven_get_payment_status\` with a \`payment_id\` to
+check on queued or in-flight payments. Do not poll in a tight loop.
 
 ## Approval semantics
 
 - 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.
+- \`safe_to_continue: false\` on a guidance block is the same signal in
+  machine-readable form: stop and involve the user before calling anything
+  else for this payment.
 - 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
@@ -3600,12 +3922,28 @@ present and surface \`message\` or \`error\` verbatim. Common cases:
   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
+- \`PAYMENT_WINDOW_EXPIRED\`: re-run the quote/prepare tool with the same
+  \`idempotency_key\`, then sign the fresh payload.
+- \`MERCHANT_REJECTED_AFTER_FUNDING\`: the merchant refused the paid retry.
+  Stop-and-sweep \u2014 stop retrying the merchant and use
   \`mcp__haven__haven_sweep_delegate\` to recover stranded delegate funds.
+- \`MERCHANT_UNRESPONSIVE_AFTER_FUNDING\`: funding confirmed on-chain, but the
+  merchant never answered the paid retry. This is NOT proof of rejection \u2014 the
+  merchant may still settle late. Verify-then-sweep, never a blind sweep:
+  check \`mcp__haven__haven_get_payment_status\`, retry
+  \`mcp__haven__haven_complete_mcp_tool\` ONCE, and only sweep with
+  \`mcp__haven__haven_sweep_delegate\` if no settlement appears.
 - Budget exceeded: tell the user how much remains (from
-  \`haven_get_allowances\`) and that they can raise the budget in Haven.
+  \`mcp__haven__haven_get_allowances\`) and that they can raise the budget in
+  Haven.
+
+## Reporting after a purchase
+
+A settled \`mcp__haven__haven_settle_mcp_tool\` response carries
+\`agent_summary\` and the remaining post-purchase allowance in \`allowance\` \u2014
+report the amount paid and what is left from those fields directly. Do not
+call \`haven_get_agent\` or \`haven_get_allowances\` again just to report a
+purchase you already made.
 
 ## Revoke
 
@@ -3759,6 +4097,50 @@ function stableStringify2(value) {
   return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${stableStringify2(object[key])}`).join(",")}}`;
 }
 
+// src/merchant-discovery.ts
+var MERCHANT_DISCOVERY_PATHS = ["/.well-known/haven-demo-merchant", "/"];
+var DISCOVERY_MAX_BYTES = 64 * 1024;
+async function discoverMerchantMcpUrl(inputUrl) {
+  let input;
+  try {
+    input = new URL(inputUrl);
+  } catch {
+    return null;
+  }
+  for (const path of MERCHANT_DISCOVERY_PATHS) {
+    try {
+      const res = await globalThis.fetch(`${input.origin}${path}`, {
+        method: "GET",
+        headers: { accept: "application/json" },
+        redirect: "error",
+        signal: AbortSignal.timeout(5e3)
+      });
+      if (!res.ok) continue;
+      const contentLength = Number(res.headers.get("content-length") ?? 0);
+      if (contentLength > DISCOVERY_MAX_BYTES) continue;
+      const text = await res.text();
+      if (text.length > DISCOVERY_MAX_BYTES) continue;
+      const doc = JSON.parse(text);
+      if (typeof doc.mcp_url !== "string") continue;
+      const resolved = new URL(doc.mcp_url);
+      if (resolved.origin !== input.origin) continue;
+      return resolved.toString();
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+function sameUrl(a, b) {
+  try {
+    const ua = new URL(a);
+    const ub = new URL(b);
+    return ua.origin === ub.origin && ua.pathname.replace(/\/+$/, "") === ub.pathname.replace(/\/+$/, "");
+  } catch {
+    return false;
+  }
+}
+
 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;
@@ -3775,6 +4157,8 @@ exports.AgentPaymentPhaseSchema = AgentPaymentPhaseSchema;
 exports.AgentPaymentRail = AgentPaymentRail;
 exports.AgentPaymentRailDescriptions = AgentPaymentRailDescriptions;
 exports.AgentPaymentRailSchema = AgentPaymentRailSchema;
+exports.AgentPaymentWarningCode = AgentPaymentWarningCode;
+exports.DISCOVERY_MAX_BYTES = DISCOVERY_MAX_BYTES;
 exports.HAVEN_MINIMUM_NODE_VERSION = HAVEN_MINIMUM_NODE_VERSION;
 exports.HAVEN_SKILL_MD = HAVEN_SKILL_MD;
 exports.HavenApiError = HavenApiError;
@@ -3783,13 +4167,19 @@ exports.HavenError = HavenError;
 exports.HavenPaymentStateError = HavenPaymentStateError;
 exports.HavenSigningError = HavenSigningError;
 exports.HavenTimeoutError = HavenTimeoutError;
+exports.HavenUnsupportedSignerVersionError = HavenUnsupportedSignerVersionError;
+exports.MERCHANT_DISCOVERY_PATHS = MERCHANT_DISCOVERY_PATHS;
+exports.MerchantTimeoutError = MerchantTimeoutError;
 exports.RECEIPT_VERSION = RECEIPT_VERSION;
+exports.SIGNER_UPDATE_FALLBACK = SIGNER_UPDATE_FALLBACK;
 exports.SKILL_FOLDER_NAME = SKILL_FOLDER_NAME;
 exports.SWEEP_BASE_CHAIN_ID = SWEEP_BASE_CHAIN_ID;
 exports.SWEEP_BASE_SEPOLIA_CHAIN_ID = SWEEP_BASE_SEPOLIA_CHAIN_ID;
 exports.SWEEP_BASE_SEPOLIA_USDC_ADDRESS = SWEEP_BASE_SEPOLIA_USDC_ADDRESS;
 exports.SWEEP_BASE_USDC_ADDRESS = SWEEP_BASE_USDC_ADDRESS;
+exports.SignerRefusalCode = SignerRefusalCode;
 exports.TRANSFER_WITH_AUTHORIZATION_TYPES = TRANSFER_WITH_AUTHORIZATION_TYPES;
+exports.X402UnexpectedStatusError = X402UnexpectedStatusError;
 exports.X402_MAX_AUTHORIZATION_WINDOW_SECONDS = X402_MAX_AUTHORIZATION_WINDOW_SECONDS;
 exports.X402_SETTLEMENT_FORWARD_MARGIN_SECONDS = X402_SETTLEMENT_FORWARD_MARGIN_SECONDS;
 exports.addressFromKey = addressFromKey;
@@ -3801,6 +4191,7 @@ exports.compareNodeVersions = compareNodeVersions;
 exports.composeDescription = composeDescription;
 exports.decodeBase64Json = decodeBase64Json;
 exports.decodeBase64Utf8 = decodeBase64Utf8;
+exports.discoverMerchantMcpUrl = discoverMerchantMcpUrl;
 exports.encodeBase64Json = encodeBase64Json;
 exports.encodeBase64Utf8 = encodeBase64Utf8;
 exports.encodeMachinePaymentProof = encodeMachinePaymentProof;
@@ -3812,6 +4203,7 @@ exports.parseMachinePaymentChallenge = parseMachinePaymentChallenge;
 exports.parseMachinePaymentChallengeResponse = parseMachinePaymentChallengeResponse;
 exports.parsePaymentRequired = parsePaymentRequired;
 exports.parsePaymentRequiredResponse = parsePaymentRequiredResponse;
+exports.sameUrl = sameUrl;
 exports.selectPaymentOption = selectPaymentOption;
 exports.selectStandardPaymentOption = selectStandardPaymentOption;
 exports.signHash = signHash;