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

package/dist/index.d.ts

@@ -65,6 +65,11 @@ interface HavenClientConfig {
     x402Wallet?: string;
     /** Timeout in ms for individual HTTP requests (default: 30000) */
     requestTimeout?: number;
+    /** Timeout (ms) for MERCHANT-facing requests — x402/MPP probes, MCP
+     *  handshakes, paid retries. Separate from requestTimeout (Haven API):
+     *  merchants may settle on-chain synchronously, so the default is
+     *  deliberately generous. #1300. */
+    merchantTimeout?: number;
     /** Timeout in ms when polling for tx confirmation (default: 90000) */
     confirmationTimeout?: number;
     /** Polling interval in ms when waiting for confirmation (default: 3000) */
@@ -257,6 +262,29 @@ interface X402Receipt {
 interface X402AuthorizationOptions {
     /** Stable caller-supplied key for this user intent. Prevents duplicate approvals across fresh 402 quotes. */
     idempotencyKey?: string;
+    /**
+     * #1307: the merchant MCP-tool call context this quote was made against
+     * (merchant_url, tool_name, arguments, mcp_transport). Persisted on the
+     * intent so `getX402MerchantCallContext` can rehydrate it by payment_id at
+     * settle/complete time instead of the caller re-threading it. Optional —
+     * omit for a non-MCP-tool x402 merchant (plain HTTP resource).
+     */
+    mcpCallContext?: X402McpCallContext;
+    /**
+     * #1348: the agent's delegate address, when the caller already resolved it
+     * from `getAgent()` in this same flow — skips `createX402Intent`'s internal
+     * agent fetch (one full round trip on every guided purchase). Staleness
+     * caveat (#1358 review): the backend derives the funding shape by comparing
+     * `payTo` to the CURRENT delegate address, so a value made stale by a
+     * delegate rotation mid-flow is not always a clean failure — a pinned-budget
+     * agent gets a 403, but an open-budget delegation agent would route to the
+     * settlement shape with the stale address. The window is one tool call
+     * (previously sub-millisecond, now the merchant-quote duration), never
+     * externally suppliable; server-truth hardening is tracked in #1360. Only
+     * pass an address fetched in THIS flow; omit to keep the self-contained
+     * fetch.
+     */
+    delegateAddress?: string;
 }
 /**
  * Keyless x402 construct result.
@@ -352,6 +380,30 @@ interface X402McpTransport {
     handshakeRequired: boolean;
     source: 'path' | 'bazaar';
 }
+/**
+ * #1307: the merchant MCP-tool call an x402 quote was made against — carried
+ * through `createX402Intent`'s options so Haven can persist it for the
+ * settle-leg rehydration handoff (`getX402MerchantCallContext`). Convenience
+ * metadata for retrying the merchant's OWN JSON-RPC call, never payment
+ * authority.
+ */
+interface X402McpCallContext {
+    merchantUrl: string;
+    toolName: string;
+    arguments?: Record<string, unknown>;
+    mcpTransport?: X402McpTransport;
+}
+/**
+ * Response shape of `getX402MerchantCallContext` — the stored merchant call
+ * context for a payment_id, rehydrated instead of re-threaded (#1307).
+ */
+interface X402MerchantCallContext {
+    paymentId: string;
+    merchantUrl: string;
+    toolName: string;
+    arguments: Record<string, unknown>;
+    mcpTransport?: X402McpTransport;
+}
 /** Quote parsed from an HTTP 402 response without creating a Haven payment. */
 interface X402Quote {
     rail: 'x402';
@@ -366,6 +418,16 @@ interface X402Quote {
     amountAtomic: string;
     amount: string;
     token: string;
+    /**
+     * #1351: decimals for `asset` on `network`, resolved from the SAME
+     * address→token binding that produced `token` — the quote's own authority on
+     * how many atomic units one human unit is. `null` when the merchant's asset
+     * is not a token Haven recognises on that network, in which case `token` is
+     * an unverified fallback label and NO human→atomic conversion is safe.
+     * Consumers converting a human-denominated figure (a user-intent spending
+     * cap) MUST fail closed on `null` rather than assume 6.
+     */
+    decimals: number | null;
     asset: string;
     network: string;
     chainId: number | null;
@@ -516,6 +578,14 @@ interface HavenAgent {
     safeAddress: string;
     delegateAddress: string;
     chainId: number;
+    /**
+     * Which on-chain policy primitive gates this agent's spend (#1306): the
+     * legacy Safe AllowanceModule (import-only accounts) or the delegation
+     * rail's active budget delegations (#1090). Read-only reporting — the
+     * on-chain state is the actual gate either way, this only says which
+     * mechanism a caller should read/derive from.
+     */
+    executionRail: 'legacy' | 'delegation';
 }
 interface HavenAllowance {
     id: string;
@@ -532,6 +602,15 @@ interface HavenAllowance {
         lastResetMin: number;
         nonce: number;
         isResetPending: boolean;
+        /**
+         * Delegation rail only (#1319, provenance for #1145's fallback): true
+         * when `remaining` came from a live on-chain enforcer read, false when
+         * the read failed and `remaining` is the fallback full configured
+         * budget. Undefined on the legacy AllowanceModule rail, which has no
+         * fallback concept. Reporting only — the on-chain policy remains the
+         * actual spend gate either way.
+         */
+        remainingIsFromChain?: boolean;
     };
 }
 interface HavenAllowanceSummary {
@@ -541,6 +620,34 @@ interface HavenAllowanceSummary {
     chainId: number;
     allowances: HavenAllowance[];
 }
+/**
+ * Post-purchase allowance/budget summary attached to a settled x402 payment
+ * (#1310). Read-only reporting — the on-chain policy remains the actual
+ * spend gate either way, this only says what is left after the purchase.
+ *
+ * Deliberately the SAME rail-labeled field spelling as #1306's
+ * catalog-purchase preflight `allowance` block (never a new spelling),
+ * minus the preflight-only `sufficient` field: post-purchase reporting
+ * answers "what is left", not "was this purchase covered". Read through the
+ * exact same source as {@link HavenAllowanceSummary} / `haven_get_allowances`
+ * (`GET /machine-payments/allowances`; delegation-rail values are the #1090
+ * `deriveDelegationBudgets`-backed enforcer read, never `agent_allowances`),
+ * so this can never disagree with `haven_get_allowances` for the same
+ * fixture.
+ */
+interface PostPurchaseAllowanceSummary {
+    /** Which on-chain policy primitive gates this agent's spend (#1306 labeling). */
+    rail: 'legacy' | 'delegation';
+    /** Remaining atomic units, read through the same source as {@link HavenAllowance.onchain.remaining}. */
+    remaining_atomic: string;
+    /** Human-readable remaining, e.g. "4.96 USDC". Omitted when the token's decimals are unknown. */
+    remaining_display?: string;
+    token_symbol?: string;
+    token_address?: string;
+    /** Minutes — mirrors {@link HavenAllowance.resetPeriodMin} / the delegation's period. */
+    reset_period?: number;
+    source: 'allowance_module' | 'active_delegations';
+}
 /**
  * Affirmative spend-readiness for the authenticated agent, derived from the raw
  * agent status plus the remaining spend authority the backend reports per rail
@@ -701,6 +808,8 @@ declare const AgentPaymentNextAction: {
     readonly StopAndTellUser: "stop_and_tell_user";
     /** Ask again only if the user still wants the payment after expiry. */
     readonly RequestAgainIfUserStillWantsIt: "request_again_if_user_still_wants_it";
+    /** #1307: retry the SAME tool call, supplying the explicit context fields the server could not rehydrate. */
+    readonly 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.
@@ -727,6 +836,36 @@ declare const AgentPaymentFailureCode: {
     readonly PaymentWindowExpired: "PAYMENT_WINDOW_EXPIRED";
     /** The Haven funding leg succeeded, but the merchant rejected the paid retry. */
     readonly 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. */
+    readonly 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).
+     */
+    readonly MerchantCallContextUnavailable: "MERCHANT_CALL_CONTEXT_UNAVAILABLE";
+    /**
+     * #1351: the caller supplied BOTH the atomic `max_amount` and the
+     * human-denominated `max_amount_human` cap for one purchase. Haven refuses
+     * to guess which the user meant — the two differ by a factor of 10^decimals,
+     * so picking wrong is exactly the silent-overspend this cap exists to
+     * prevent. Rejected before any merchant probe, funding intent, or signature.
+     */
+    readonly AmbiguousMaxAmount: "AMBIGUOUS_MAX_AMOUNT";
+    /**
+     * #1351: a human-denominated cap was supplied, but it cannot be converted to
+     * atomic units against THIS quote — either the quote's asset has no known
+     * decimals on its network, or the cap carries more fraction digits than the
+     * asset can represent (truncating it would silently change the user's cap).
+     * The fallback is the exact atomic `max_amount`.
+     */
+    readonly MaxAmountUnconvertible: "MAX_AMOUNT_UNCONVERTIBLE";
 };
 type AgentPaymentFailureCode = (typeof AgentPaymentFailureCode)[keyof typeof AgentPaymentFailureCode];
 /**
@@ -767,12 +906,117 @@ type AgentPaymentRail = (typeof AgentPaymentRail)[keyof typeof AgentPaymentRail]
 type PaymentPhase = AgentPaymentPhase;
 type PaymentNextAction = AgentPaymentNextAction;
 declare const AGENT_PAYMENT_PHASE_VALUES: ("rejected" | "expired" | "failed" | "agent_signature_required" | "payment_submitted" | "payment_confirmed" | "user_approval_required" | "user_execution_required" | "waiting_for_additional_approvals" | "funding_sent" | "insufficient_funds" | "funded_but_unsettled")[];
-declare const AGENT_PAYMENT_NEXT_ACTION_VALUES: ("sign_and_submit_payment" | "check_status_later" | "none" | "wait_for_user_approval" | "wait_for_user_to_complete_payment" | "retry_original_x402_request" | "stop_and_tell_user" | "request_again_if_user_still_wants_it" | "payment_window_expired" | "fund_safe_or_raise_allowance" | "sweep_stranded_funds")[];
-declare const AGENT_PAYMENT_FAILURE_CODE_VALUES: ("PRICE_EXCEEDS_MAX" | "PAYMENT_WINDOW_EXPIRED" | "MERCHANT_REJECTED_AFTER_FUNDING")[];
+declare const AGENT_PAYMENT_NEXT_ACTION_VALUES: ("sign_and_submit_payment" | "check_status_later" | "none" | "wait_for_user_approval" | "wait_for_user_to_complete_payment" | "retry_original_x402_request" | "stop_and_tell_user" | "request_again_if_user_still_wants_it" | "retry_with_explicit_context" | "payment_window_expired" | "fund_safe_or_raise_allowance" | "sweep_stranded_funds")[];
+declare const AGENT_PAYMENT_FAILURE_CODE_VALUES: ("PRICE_EXCEEDS_MAX" | "PAYMENT_WINDOW_EXPIRED" | "MERCHANT_REJECTED_AFTER_FUNDING" | "MERCHANT_UNRESPONSIVE_AFTER_FUNDING" | "MERCHANT_CALL_CONTEXT_UNAVAILABLE" | "AMBIGUOUS_MAX_AMOUNT" | "MAX_AMOUNT_UNCONVERTIBLE")[];
 declare const AGENT_PAYMENT_RAIL_VALUES: ("x402" | "mpp" | "mpp_demo" | "mpp_crypto" | "stripe_deposit" | "spt" | "direct")[];
 declare const AgentPaymentPhaseDescriptions: Record<AgentPaymentPhase, string>;
 declare const AgentPaymentNextActionDescriptions: Record<AgentPaymentNextAction, string>;
 declare const AgentPaymentFailureCodeDescriptions: Record<AgentPaymentFailureCode, string>;
+/**
+ * #1308: machine-readable warning codes carried in the `warnings` array on
+ * x402 MCP tool responses. Warnings are ADVISORY — they never replace a
+ * refusal, and existing failure codes stay authoritative for errors. The
+ * legacy `cap_warning` string field is kept for compatibility; the structured
+ * entry carries the same message under MISSING_MAX_AMOUNT.
+ */
+declare const AgentPaymentWarningCode: {
+    /** No max_amount cap was supplied — the live quoted price was accepted as-is. */
+    readonly MissingMaxAmount: "MISSING_MAX_AMOUNT";
+    /** The signing window closes soon; sign promptly or re-quote with the same idempotency key. */
+    readonly QuoteExpiresSoon: "QUOTE_EXPIRES_SOON";
+    /** The merchant URL was resolved via discovery — pass the RESOLVED url forward. */
+    readonly 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.
+     */
+    readonly 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.
+     */
+    readonly 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.
+     */
+    readonly AllowanceReadOptimistic: "ALLOWANCE_READ_OPTIMISTIC";
+};
+type AgentPaymentWarningCode = (typeof AgentPaymentWarningCode)[keyof typeof AgentPaymentWarningCode];
+interface AgentPaymentWarning {
+    code: AgentPaymentWarningCode;
+    message: string;
+}
+/**
+ * #1308: the structured next-step contract on x402 MCP tool responses. It
+ * EXTENDS the existing taxonomy — `next_action` values come from
+ * AgentPaymentNextAction, never a parallel vocabulary. `next_arguments`
+ * carries the small, literally-usable arguments; bulky pass-through fields
+ * (payment_required) are named in `reason` and taken from the SAME response.
+ */
+interface AgentNextStep {
+    next_action: AgentPaymentNextAction;
+    /** Fully-qualified tool name for the next call, when one exists. */
+    next_tool?: string;
+    /** Small literal arguments for next_tool. Bulky fields are referenced by reason. */
+    next_arguments?: Record<string, unknown>;
+    /** False when the agent should stop and involve the user before continuing. */
+    safe_to_continue: boolean;
+    reason: string;
+}
+/**
+ * #1349: compact, Haven-generated reporting evidence for a completed x402
+ * merchant purchase. `status`, money fields, merchant endpoint/address, and
+ * funding transaction come from Haven payment state; `product` and
+ * `invoice_id` are optional merchant-supplied display metadata. The raw
+ * merchant result remains separate evidence and MUST NOT be used to infer
+ * settlement status.
+ */
+interface AgentPurchaseSummary {
+    /** Set only after Haven has completed the funding and merchant-settlement flow. */
+    status: 'settled';
+    product: string | null;
+    amount: string | null;
+    amount_atomic: string | null;
+    asset: string | null;
+    network: string | null;
+    merchant: {
+        address: string | null;
+        resource_url: string | null;
+    };
+    /** Merchant-supplied identifier, or null when the merchant did not supply one. */
+    invoice_id: string | null;
+    funding_tx_hash: string | null;
+    /** Optional merchant receipt reference parsed from PAYMENT-RESPONSE; not Haven settlement proof. */
+    settlement_tx_hash: string | null;
+    /** Same read-only allowance block returned at the top level, or null when unavailable. */
+    allowance: PostPurchaseAllowanceSummary | null;
+}
+/** #1308: compact reporting summary — what the agent tells the user. */
+interface AgentPaymentSummary {
+    payment_id: string;
+    status: string;
+    amount?: string;
+    amount_atomic?: string;
+    token?: string;
+    network?: string;
+    expires_at?: string;
+    product?: string;
+    /**
+     * Default reporting contract for a successful `haven_settle_mcp_tool` call.
+     * The merchant's raw `result` remains available separately as advanced
+     * evidence; do not parse it to determine whether a payment settled.
+     */
+    purchase_summary?: AgentPurchaseSummary;
+}
 declare const AgentPaymentRailDescriptions: Record<AgentPaymentRail, string>;
 declare const AgentPaymentPhaseSchema: AgentPaymentEnumSchema;
 declare const AgentPaymentNextActionSchema: AgentPaymentEnumSchema;
@@ -839,6 +1083,7 @@ interface HavenCatalogEntry {
     rail: 'x402' | 'mpp';
     protocol: 'http' | 'mcp';
     toolName: string | null;
+    toolArguments: Record<string, unknown> | null;
     priceDisplay: string | null;
     priceAtomic: string | null;
     asset: string | null;
@@ -856,6 +1101,26 @@ declare class HavenApiError extends HavenError {
     readonly body?: unknown | undefined;
     constructor(message: string, statusCode: number, body?: unknown | undefined, paymentId?: string);
 }
+/**
+ * #1300: quoteX402 hit a URL that answered something other than 402 — the
+ * typed form of "this is not the x402 endpoint". Exists so consumers (the
+ * hosted MCP's #1271 discovery trigger) can key on a class instead of
+ * message text.
+ */
+/**
+ * #1300: a merchant-facing fetch hit the client-side merchantTimeout. Typed
+ * so consumers can distinguish "merchant never answered" from a real HTTP
+ * error response — the funded-retry path routes this to verify-then-sweep
+ * guidance instead of a bare 504.
+ */
+declare class MerchantTimeoutError extends HavenApiError {
+    readonly merchantErrorCode: "merchant_timeout";
+    constructor(message: string);
+}
+declare class X402UnexpectedStatusError extends HavenApiError {
+    readonly x402ErrorCode: "unexpected_non_402_status";
+    constructor(message: string, statusCode: number);
+}
 declare class HavenPaymentStateError extends HavenApiError {
     readonly state: PaymentStatusResult;
     resumeState?: X402ResumeState | MppResumeState;
@@ -867,6 +1132,53 @@ declare class HavenPaymentStateError extends HavenApiError {
 declare class HavenSigningError extends HavenError {
     constructor(message: string);
 }
+/**
+ * Refusal codes the local signer returns when it does not recognise the
+ * VERSION of a Haven-signed binding it was asked to sign (#1309). Distinct
+ * from `AgentPaymentFailureCode`: these describe a **signer capability**
+ * problem (this install cannot evaluate what Haven sent), not a payment-domain
+ * outcome, and they never reach the backend's REST/OpenAPI surface — only the
+ * local signer's own MCP tool responses (`haven_sign` / `haven_sign_x402` /
+ * `haven_sign_sweep_delegate`). That is also why this pair does not go through
+ * the `AgentPaymentFailureCode` four-gate (sdk → backend mirror → spec →
+ * api-types): there is no backend mirror to keep in sync with.
+ */
+declare const SignerRefusalCode: {
+    /** `SUPPORTED_X402_EXPECTED_VERSIONS` in `@haven_ai/signer` does not include the received version. */
+    readonly UnsupportedExpectedContextVersion: "UNSUPPORTED_EXPECTED_CONTEXT_VERSION";
+    /** `SUPPORTED_SWEEP_BINDING_VERSIONS` in `@haven_ai/signer` does not include the received version. */
+    readonly UnsupportedSweepBindingVersion: "UNSUPPORTED_SWEEP_BINDING_VERSION";
+};
+type SignerRefusalCode = (typeof SignerRefusalCode)[keyof typeof SignerRefusalCode];
+/**
+ * Canonical recovery guidance for a stale local signer (#1309) — the ONE
+ * string both the signer's structured refusal (`fallback` field, carried by
+ * `HavenUnsupportedSignerVersionError`) and the hosted quote's advisory
+ * `signer_compatibility.fallback` (#1155) render, so an agent that meets
+ * either surface is told the identical fix. A second hand-maintained copy of
+ * this sentence is exactly how the two surfaces could start disagreeing about
+ * what to do.
+ */
+declare const SIGNER_UPDATE_FALLBACK: string;
+/**
+ * Thrown by the local signer when a Haven-signed binding (x402 expected
+ * context or sweep authorization) carries a version outside what this signer
+ * install enforces (#1143, structured as #1309). Machine-readable: `code`,
+ * `supportedVersions`, and `receivedVersion` are DERIVED from the signer's own
+ * `SUPPORTED_X402_EXPECTED_VERSIONS` / `SUPPORTED_SWEEP_BINDING_VERSIONS`
+ * constants at the throw site, never a second literal — see
+ * `assertSupportedBindingVersion` in `@haven_ai/signer`.
+ *
+ * This narrows HOW the refusal is reported. It does not weaken it: nothing is
+ * signed either way, and the version stays inside the Haven-signed binding
+ * message (callers must not "fix" a mismatch by rewriting it).
+ */
+declare class HavenUnsupportedSignerVersionError extends HavenError {
+    readonly supportedVersions: readonly number[];
+    readonly receivedVersion: number;
+    readonly fallback: string;
+    constructor(message: string, code: SignerRefusalCode, supportedVersions: readonly number[], receivedVersion: number, fallback: string);
+}
 declare class HavenTimeoutError extends HavenError {
     constructor(paymentId: string);
 }
@@ -1057,6 +1369,7 @@ declare class HavenClient {
     private readonly baseUrl;
     private readonly x402Wallet;
     private readonly requestTimeout;
+    private readonly merchantTimeout;
     private readonly confirmationTimeout;
     private readonly pollingInterval;
     private readonly chainRpcs;
@@ -1170,6 +1483,8 @@ declare class HavenClient {
      * Get the agent identity tied to this API key.
      */
     getAgent(): Promise<HavenAgent>;
+    private agentInFlight;
+    private fetchAgent;
     /**
      * One-shot "am I ready?" bootstrap: identity + live spend authority + a
      * readiness signal, in a single call. Folds {@link getAgent} and
@@ -1209,6 +1524,58 @@ declare class HavenClient {
      * Get configured and on-chain allowances for the authenticated agent.
      */
     getAllowances(): Promise<HavenAllowanceSummary>;
+    /**
+     * 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.
+     */
+    getPostPurchaseAllowanceSummary(paymentId: string): Promise<{
+        allowance: PostPurchaseAllowanceSummary | null;
+        warnings: AgentPaymentWarning[];
+        /** Same authenticated payment-state read used to resolve the settled token. */
+        payment: PaymentStatusResult | null;
+    }>;
+    /**
+     * `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.
+     */
+    getPaymentStatusWithPostPurchaseAllowance(paymentId: string): Promise<PaymentStatusResult & {
+        allowance?: PostPurchaseAllowanceSummary | null;
+        warnings?: AgentPaymentWarning[];
+    }>;
     /**
      * Discover payable services from Haven's curated merchant catalog.
      *
@@ -1218,8 +1585,19 @@ declare class HavenClient {
      */
     discoverTools(options?: {
         category?: string;
+        search?: string;
         rail?: 'x402' | 'mpp';
     }): Promise<HavenCatalogEntry[]>;
+    /**
+     * 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}.
+     */
+    getCatalogEntry(id: string): Promise<HavenCatalogEntry>;
     /**
      * List recent machine-payment receipts/evidence for bookkeeping.
      */
@@ -1262,6 +1640,17 @@ declare class HavenClient {
      * payment or approval request.
      */
     quoteX402(url: string, init?: RequestInit, options?: X402AuthorizationOptions): Promise<X402Quote>;
+    /**
+     * 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}.
+     */
+    quoteMcpX402(url: string, init?: RequestInit, options?: X402AuthorizationOptions): Promise<X402Quote>;
     /**
      * Pay a previously inspected x402 quote and retry the exact captured request.
      */
@@ -1382,6 +1771,17 @@ declare class HavenClient {
         body: unknown;
         settlementTxHash?: string;
     }>;
+    /**
+     * 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).
+     */
+    getX402MerchantCallContext(paymentId: string): Promise<X402MerchantCallContext>;
     private resolveX402MerchantCompletionContext;
     private resolveX402WalletForMerchantCall;
     authorizeMachinePayment(challenge: MachinePaymentChallenge, options?: MppAuthorizationOptions): Promise<MachinePaymentReceipt>;
@@ -1445,6 +1845,15 @@ declare class HavenClient {
     private toolError;
     private post;
     private get;
+    /**
+     * #1300: every MERCHANT-facing fetch goes through here. Haven API calls
+     * have always been bounded (request() below); the merchant probes/retries
+     * called globalThis.fetch bare, so a slow-loris merchant could hold a tool
+     * call open forever. A caller-supplied signal still applies (combined via
+     * AbortSignal.any); a timeout abort surfaces as a clear HavenApiError 504
+     * naming the URL rather than a bare AbortError.
+     */
+    private merchantFetch;
     private request;
     private mapPaymentResult;
     private mapPaymentStatusResult;
@@ -1649,16 +2058,16 @@ declare const toolDescriptions: {
         readonly nextActionGuidance: "";
     };
     readonly payMcpTool: {
-        readonly summary: "Call a named tool on an MCP merchant that requires an x402 payment, handling the full initialize → pay → retry round trip.";
+        readonly summary: "Call a named tool on an MCP merchant that requires an x402 payment, handling the full initialize → pay → retry round trip in one call.";
         readonly selectionGuidance: string;
         readonly behavior: string;
         readonly nextActionGuidance: string;
     };
     readonly discoverTools: {
-        readonly summary: "Discover payable services from Haven's curated merchant catalog — names, prices, and which pay tool to use.";
+        readonly summary: "Step 1 of a purchase: discover payable services from Haven's curated merchant catalog — names, prices, and which pay tool to use next.";
         readonly selectionGuidance: string;
         readonly behavior: string;
-        readonly nextActionGuidance: "Pick an entry and pay it with the tool named in suggested_tool, passing the entry's resource_url (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.";
+        readonly nextActionGuidance: "Pick an entry and pay it with the tool named in suggested_tool, passing the entry's resource_url, tool_name, and tool_arguments for MCP merchants. Confirm the price from the live pay-tool result (not the catalog), and pass the user's cap as max_amount_human in whole tokens (\"no more than 1 USDC\" → max_amount_human: \"1\") — never convert it to atomic units by hand (#1351).";
     };
     readonly sweep_delegate: {
         readonly summary: "Sweep stranded USDC and/or ETH from the delegate wallet back to the originating Safe.";
@@ -1694,7 +2103,7 @@ type SharedToolKey = keyof typeof toolDescriptions;
  * this canonical string and asserts byte-for-byte equality, so the two copies
  * cannot drift.
  */
-declare const HAVEN_SKILL_MD = "---\nname: haven-pay\ndescription: Pay for things from the user's Haven wallet within their agent rules. Use when the user asks to send, pay, tip, or transfer crypto \u2014 or when a request hits an HTTP 402 (x402) paywall.\n---\n\n# Haven: pay from a Haven wallet\n\nThis skill lets the agent make payments from the user's Haven wallet through\nthe Haven MCP tools. Every payment is checked against the agent's on-chain\nbudget before money moves; payments above the remaining budget wait for the\nuser's approval in Haven.\n\nHosted tools run in the `mcp__haven__` namespace. Local signing tools run in\nthe `mcp__haven-signer__` namespace and keep the delegate key on this machine.\n\n## When to use this skill\n\n- The user asks to send money, pay someone, tip, donate, or transfer tokens.\n- A request returns HTTP 402 (x402): use the Haven pay tools to settle it,\n  then retry the original request.\n\n## Identity and budget\n\nDo not guess the wallet address, network, or budget.\n\nFor instant orientation at the start of a session, read the non-secret\n`agent.json` the connector wrote to your Haven credential directory (typically\n`~/.haven/agents/<agent-id>/agent.json` \u2014 if you don't know the agent id, list\n`~/.haven/agents/` to find the folder). It\nholds your agent id, Haven wallet address, network, and *configured* per-token\nbudget, and contains no keys \u2014 the fastest way to answer \"who am I and what may\nI spend\" with no round trip. If that file is absent (some setups don't write\nit), use the tools below instead.\n\nBefore any payment, confirm the *live remaining* budget with the tools \u2014\n`agent.json` shows the configured budget, not what is left after recent\nspending:\n\n- `haven_get_agent` \u2014 the recommended first call: identity (wallet, network)\n  plus a readiness signal (`ready` / `needs_approval` / `revoked`) and live\n  remaining per-token allowance, in one shot.\n- `haven_get_allowances` \u2014 detailed per-token breakdown (configured, spent,\n  reset window) when you need more than the summary.\n\nBudgets reset on a period the user chose. If a payment exceeds the remaining\nbudget it is queued for the user to approve in the Haven dashboard \u2014 this is\nnormal, not an error.\n\n## Paying\n\n- **Direct transfer:** `haven_pay` with recipient, amount, and token.\n- **x402 paywall:** `haven_quote_x402` to get a quote, then\n  `haven_pay_x402_quote`. In the hosted setup the signing step happens in\n  the local Haven signer; follow the tool results \u2014 they tell you the next\n  action at every step. Retry the original request only when the result says\n  `retry_original_x402_request`.\n- **Paid MCP tool call:** `mcp__haven__haven_pay_mcp_tool` with the merchant\n  URL, tool name, and arguments, then finish in two calls (fast path):\n  `mcp__haven-signer__haven_sign_x402` on the local signer (pass\n  `payload_hash`, `x402_expected` as the nested `x402.expected` object, and\n  `payment_required`) returns `{ signature, payment_header }`; then\n  `mcp__haven__haven_settle_mcp_tool` (pass `payment_id`, `signature`,\n  `payment_header`, `merchant_url`, `tool_name`, `arguments`,\n  `mcp_transport`) funds and settles in one step and returns the tool result.\n  If it returns `settled: false`, funding is queued for the user's approval \u2014\n  tell them and check status later, do not re-pay. Step-by-step alternative:\n  `mcp__haven-signer__haven_sign` \u2192 `mcp__haven__haven_submit` \u2192\n  `mcp__haven-signer__haven_x402_sign_header` \u2192\n  `mcp__haven__haven_complete_mcp_tool`. Pass `payment_required`,\n  `arguments`, and `mcp_transport` verbatim from the\n  `mcp__haven__haven_pay_mcp_tool` result. The returned `expires_at` is the\n  signing window; if a tool returns `PAYMENT_WINDOW_EXPIRED`, re-run\n  `mcp__haven__haven_pay_mcp_tool` with the same\n  `idempotency_key`. Do not call the merchant yourself \u2014 Haven completes the\n  merchant leg for you.\n- **Prices:** show the user the live price from the pay-tool result, never a\n  catalog price. `haven_discover_tools` prices are indicative\n  (`price_is_indicative`) and can be stale. The pay-tool result's `amount` /\n  `amount_atomic` is the amount Haven authorizes for the call \u2014 a ceiling the\n  merchant settles at or below \u2014 so present it as the most the user will pay.\n  Pass `max_amount` (atomic units) to `haven_pay_mcp_tool` /\n  `haven_pay_x402_quote` to reject a quote whose authorized amount is above the\n  user's cap, before any funds move.\n- **Status:** `haven_get_payment_status` with a `payment_id` to check on\n  queued or in-flight payments. Do not poll in a tight loop.\n\n## Approval semantics\n\n- A result with `pending_approval` means the payment exceeded the remaining\n  budget and is waiting for the user in Haven. Tell the user, then check\n  status later.\n- Never ask the user for private keys. Signing happens only in the local Haven\n  signer; the hosted Haven tools never receive the signing key. If a tool\n  reports a missing or invalid credential, tell the user to re-run the Haven\n  setup command.\n\n## Failure handling\n\nHaven tool failures are shaped like `{ success: false, code, message, ... }`\nor older `{ error, status, details? }` responses. Branch on `code` when\npresent and surface `message` or `error` verbatim. Common cases:\n\n- `pending_approval`: queued for the user's approval (see above).\n- `insufficient_funds`: the Haven wallet doesn't hold enough of that token.\n  Suggest the user add funds in the Haven dashboard.\n- `PRICE_EXCEEDS_MAX`: the live merchant price exceeded your `max_amount`.\n  No funds moved; ask the user before retrying with a higher cap.\n- `PAYMENT_WINDOW_EXPIRED`: re-run `mcp__haven__haven_pay_mcp_tool` with the same\n  `idempotency_key`, then sign the fresh `payload_hash`.\n- `MERCHANT_REJECTED_AFTER_FUNDING`: stop retrying the merchant and use\n  `mcp__haven__haven_sweep_delegate` to recover stranded delegate funds.\n- Budget exceeded: tell the user how much remains (from\n  `haven_get_allowances`) and that they can raise the budget in Haven.\n\n## Revoke\n\nIf this agent's credential may have leaked, tell the user to pause or revoke\nthe agent in the Haven dashboard under Agents. New requests stop immediately\nfor that credential.\n";
+declare const HAVEN_SKILL_MD = "---\nname: haven-pay\ndescription: Pay for things from the user's Haven wallet within their agent rules. Use when the user asks to send, pay, tip, or transfer crypto \u2014 or when a request hits an HTTP 402 (x402) paywall.\n---\n\n# Haven: pay from a Haven wallet\n\nThis skill lets the agent make payments from the user's Haven wallet through\nthe Haven MCP tools. Every payment is checked against the agent's on-chain\nbudget before money moves; payments above the remaining budget wait for the\nuser's approval in Haven.\n\nHosted tools run in the `mcp__haven__` namespace. Local signing tools run in\nthe `mcp__haven-signer__` namespace and keep the delegate key on this machine.\nTool results carry the exact next step (`next_action`, `next_tool`,\n`next_arguments`) \u2014 follow those fields first; the prose below is fallback\nand orientation, not the source of truth.\n\n## When to use this skill\n\n- The user asks to send money, pay someone, tip, donate, or transfer tokens.\n- A request returns HTTP 402 (x402): use the Haven pay tools to settle it,\n  then retry the original request.\n\n## Identity and budget\n\nDo not guess the wallet address, network, or budget.\n\nFor instant orientation at the start of a session, read the non-secret\n`agent.json` the connector wrote to your Haven credential directory (typically\n`~/.haven/agents/<agent-id>/agent.json` \u2014 if you don't know the agent id, list\n`~/.haven/agents/` to find the folder). It\nholds your agent id, Haven wallet address, network, and *configured* per-token\nbudget, and contains no keys \u2014 the fastest way to answer \"who am I and what may\nI spend\" with no round trip. If that file is absent (some setups don't write\nit), use the tools below instead.\n\nBefore any payment, confirm the *live remaining* budget with the tools \u2014\n`agent.json` shows the configured budget, not what is left after recent\nspending:\n\n- `mcp__haven__haven_get_agent` \u2014 the recommended first call: identity\n  (wallet, network) plus a readiness signal (`ready` / `needs_approval` /\n  `revoked`) and live remaining per-token allowance, in one shot.\n- `mcp__haven__haven_get_allowances` \u2014 detailed per-token breakdown\n  (configured, spent, reset window) when you need more than the summary.\n\nBudgets reset on a period the user chose. If a payment exceeds the remaining\nbudget it is queued for the user to approve in the Haven dashboard \u2014 this is\nnormal, not an error.\n\n## Paying\n\n**Catalog purchases \u2014 the primary path for MCP merchants:**\n\n1. `mcp__haven__haven_discover_tools` to find a payable service and its\n   `catalog_id`.\n2. `mcp__haven__haven_prepare_catalog_purchase` with `catalog_id` and a\n   spending cap. A cap is REQUIRED on this tool and is best practice on every\n   paid call below too \u2014 it caps what the LIVE merchant quote may charge,\n   checked before any funding intent is created. Write it the way the user\n   said it: `max_amount_human` is whole tokens, so \"no more than 1 USDC\" is\n   `max_amount_human: \"1\"`. (`max_amount` is the atomic-unit form, where\n   \"1\" means 0.000001 USDC \u2014 do not convert by hand, and never send both.)\n3. Then FOLLOW THE RESPONSE'S GUIDANCE FIELDS: `next_action`, `next_tool`,\n   and `next_arguments` name the exact next call \u2014 act on those first; the\n   prose in this section is fallback and debugging detail. If the catalog\n   entry is missing or degraded, the response instead names\n   `mcp__haven__haven_pay_mcp_tool` (merchant URL, tool name, arguments) as\n   the manual fallback.\n\n**Signing:** `mcp__haven-signer__haven_sign_x402` with `payment_id` ONLY \u2014\nthe local signer fetches the exact signing bytes AND `payment_required`\nitself, so never relay `typed_data` or the 402 blob yourself. If the signer\nreports its fetched context carried no `payment_required` (older backend),\nre-call with `payment_required` added verbatim. Fallback for an older signer\nor backend: re-run the quote/prepare tool with the SAME `idempotency_key`\nplus `include_signing_payload=true`, then pass `payload_hash`,\n`x402_expected` (the nested `x402.expected` object), and\n`typed_data`/`typed_data_b64` through unchanged.\n\n**Settle:** `mcp__haven__haven_settle_mcp_tool` with `payment_id`,\n`signature`, and `payment_header` ONLY \u2014 Haven rehydrates the merchant call\ncontext (`merchant_url`, `tool_name`, `arguments`, `mcp_transport`)\nserver-side from `payment_id`. Pass those four fields explicitly only as a\nversion-skew fallback when Haven has no stored context for the id \u2014 both or\nnone together, never just one. If the settle result carries `settled: false`,\nfunding is queued for the user's approval \u2014 tell them and check status later,\ndo not re-pay.\n\nStep-by-step alternative (also key-safe; for an older signer or backend, or\nwhen you already have a merchant URL and tool name instead of a\n`catalog_id`): `mcp__haven__haven_pay_mcp_tool` then\n`mcp__haven-signer__haven_sign` \u2192 `mcp__haven__haven_submit` \u2192\n`mcp__haven-signer__haven_x402_sign_header` \u2192\n`mcp__haven__haven_complete_mcp_tool`. Pass `payment_required`,\n`arguments`, and `mcp_transport` verbatim from the quote/prepare result.\nThe returned `expires_at` is the signing window; if a tool returns\n`PAYMENT_WINDOW_EXPIRED`, re-run the same quote/prepare tool with the same\n`idempotency_key`. Do not call the merchant yourself \u2014 Haven completes the\nmerchant leg for you.\n\n**Direct transfer / non-MCP paywall:** `mcp__haven__haven_pay` with\nrecipient, amount, and token for a plain transfer. For an arbitrary,\nnon-MCP x402 paywall: `mcp__haven__haven_quote_x402` to get a quote, then\n`mcp__haven__haven_pay_x402_quote` \u2014 follow the result's guidance fields\nfirst, sign in the local Haven signer, and retry the original request only\nwhen the result says `retry_original_x402_request`.\n\n**Catalog tool arguments:** when `haven_discover_tools` returns\n`tool_arguments`, pass that object unchanged as the pay tool's\n`arguments` field (for example\n`tool_arguments: { \"tier\": \"50gb\" }` -> `arguments: { \"tier\": \"50gb\" }`).\n\n**Prices:** show the user the live price from the pay-tool result, never a\ncatalog price. `haven_discover_tools` prices are indicative\n(`price_is_indicative`) and can be stale. The pay-tool result's `amount` /\n`amount_atomic` is the amount Haven authorizes for the call \u2014 a ceiling the\nmerchant settles at or below \u2014 so present it as the most the user will pay.\n\n**Status:** `mcp__haven__haven_get_payment_status` with a `payment_id` to\ncheck on queued or in-flight payments. Do not poll in a tight loop.\n\n## Approval semantics\n\n- A result with `pending_approval` means the payment exceeded the remaining\n  budget and is waiting for the user in Haven. Tell the user, then check\n  status later.\n- `safe_to_continue: false` on a guidance block is the same signal in\n  machine-readable form: stop and involve the user before calling anything\n  else for this payment.\n- Never ask the user for private keys. Signing happens only in the local Haven\n  signer; the hosted Haven tools never receive the signing key. If a tool\n  reports a missing or invalid credential, tell the user to re-run the Haven\n  setup command.\n\n## Failure handling\n\nHaven tool failures are shaped like `{ success: false, code, message, ... }`\nor older `{ error, status, details? }` responses. Branch on `code` when\npresent and surface `message` or `error` verbatim. Common cases:\n\n- `pending_approval`: queued for the user's approval (see above).\n- `insufficient_funds`: the Haven wallet doesn't hold enough of that token.\n  Suggest the user add funds in the Haven dashboard.\n- `PRICE_EXCEEDS_MAX`: the live merchant price exceeded your cap. No funds\n  moved; ask the user before retrying with a higher one.\n- `AMBIGUOUS_MAX_AMOUNT`: you sent both `max_amount` and\n  `max_amount_human`. Nothing was contacted or spent \u2014 re-send with exactly\n  one (`max_amount_human` for a cap the user stated in tokens).\n- `MAX_AMOUNT_UNCONVERTIBLE`: `max_amount_human` does not fit this quote's\n  asset \u2014 unknown decimals, or more decimal places than the asset supports.\n  Round the cap, or send an exact atomic `max_amount`.\n- `PAYMENT_WINDOW_EXPIRED`: re-run the quote/prepare tool with the same\n  `idempotency_key`, then sign the fresh payload.\n- `MERCHANT_REJECTED_AFTER_FUNDING`: the merchant refused the paid retry.\n  Stop-and-sweep \u2014 stop retrying the merchant and use\n  `mcp__haven__haven_sweep_delegate` to recover stranded delegate funds.\n- `MERCHANT_UNRESPONSIVE_AFTER_FUNDING`: funding confirmed on-chain, but the\n  merchant never answered the paid retry. This is NOT proof of rejection \u2014 the\n  merchant may still settle late. Verify-then-sweep, never a blind sweep:\n  check `mcp__haven__haven_get_payment_status`, retry\n  `mcp__haven__haven_complete_mcp_tool` ONCE, and only sweep with\n  `mcp__haven__haven_sweep_delegate` if no settlement appears.\n- Budget exceeded: tell the user how much remains (from\n  `mcp__haven__haven_get_allowances`) and that they can raise the budget in\n  Haven.\n\n## Reporting after a purchase\n\nA settled `mcp__haven__haven_settle_mcp_tool` response carries\n`agent_summary.purchase_summary` and the remaining post-purchase allowance\nin `allowance` \u2014 report the product, Haven-derived payment/transaction\nfields, and what is left from those fields directly. `result` is optional\nraw merchant evidence; never use it to decide whether the purchase was paid.\nDo not call `haven_get_agent` or `haven_get_allowances` again just to\nreport a purchase you already made.\n\n## Revoke\n\nIf this agent's credential may have leaked, tell the user to pause or revoke\nthe agent in the Haven dashboard under Agents. New requests stop immediately\nfor that credential.\n";
 /** Directory name for the installed skill folder. */
 declare const SKILL_FOLDER_NAME = "haven-pay";
 
@@ -1732,7 +2141,7 @@ declare const SKILL_FOLDER_NAME = "haven-pay";
  * package. A guard test in each package asserts exactly that against its own
  * `package.json`, so the two cannot drift again silently.
  */
-declare const HAVEN_MINIMUM_NODE_VERSION = "24.0.0";
+declare const HAVEN_MINIMUM_NODE_VERSION = "22.0.0";
 /**
  * Compare two Node versions. Negative when `left` is older.
  *
@@ -1877,6 +2286,16 @@ declare function encodePaymentProof(receipt: {
     payer?: string;
     chainId?: number;
 }): string;
+/**
+ * Resolve a token symbol from a contract address.
+ *
+ * Checks all supported chains. For chain-specific resolution,
+ * pass the optional `network` CAIP-2 string (e.g. "eip155:100").
+ */
+declare function resolveTokenFromAddress(address: string, network?: string): {
+    symbol: string;
+    decimals: number;
+} | null;
 
 declare function parseMachinePaymentChallenge(response: Response): MachinePaymentChallenge;
 declare function parseMachinePaymentChallengeResponse(response: Response): Promise<MachinePaymentChallenge>;
@@ -1921,4 +2340,32 @@ declare function encodeBase64Json(value: unknown): string;
  */
 declare function decodeBase64Json<T>(value: string, label?: string): T;
 
-export { AGENT_PAYMENT_FAILURE_CODE_VALUES, AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, type AgentPaymentEnumSchema, AgentPaymentFailureCode, AgentPaymentFailureCodeDescriptions, AgentPaymentFailureCodeSchema, AgentPaymentNextAction, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, type ClaudeTool, HAVEN_MINIMUM_NODE_VERSION, HAVEN_SKILL_MD, type HavenAgent, type HavenAgentAllowanceSummary, type HavenAgentReadiness, type HavenAgentSummary, type HavenAllowance, type HavenAllowanceSummary, HavenApiError, type HavenCatalogEntry, HavenClient, type HavenClientConfig, HavenError, type HavenPaymentReceipt, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, type MachinePaymentChallenge, type MachinePaymentRail, type MachinePaymentReceipt, type MppAuthorizationOptions, type MppQuote, type MppResumeState, type OpenAITool, type PaymentFee, type PaymentIntent, type PaymentNextAction, type PaymentPhase, type PaymentReceipt, type PaymentRequest, type PaymentResult, type PaymentResumeState, type PaymentStatus, type PaymentStatusResult, type PendingApproval, RECEIPT_VERSION, type ReceiptVerification, type ResumeAuthorizedMppInput, type ResumeAuthorizedX402Input, type ResumeMppPaymentInput, type ResumeX402PaymentInput, SKILL_FOLDER_NAME, SWEEP_BASE_CHAIN_ID, SWEEP_BASE_SEPOLIA_CHAIN_ID, SWEEP_BASE_SEPOLIA_USDC_ADDRESS, SWEEP_BASE_USDC_ADDRESS, type SharedToolKey, type SignData, type SweepAuthorization, type SweepEip712Domain, type SweepEntry, type SweepExpectedAuth, type SweepPreparation, type SweepPrepareResponse, type SweepResult, type SweepSubmitResponse, type SweepSubmitResult, type SweepTypedData, TRANSFER_WITH_AUTHORIZATION_TYPES, type ToolDescription, type UnsupportedNodeVersionMessageOptions, type X402AuthorizationOptions, type X402ExpectedAuth, type X402ExpectedContext, type X402Intent, type X402McpTransport, type X402PaymentOption, type X402PaymentRequired, type X402Quote, type X402Receipt, type X402RequestSnapshot, type X402ResumeState, X402_MAX_AUTHORIZATION_WINDOW_SECONDS, X402_SETTLEMENT_FORWARD_MARGIN_SECONDS, addressFromKey, buildMachinePaymentIdempotencyKey, buildSweepAuthorizationMessage, buildSweepTypedData, buildX402ExpectedMessage, compareNodeVersions, composeDescription, decodeBase64Json, decodeBase64Utf8, encodeBase64Json, encodeBase64Utf8, encodeMachinePaymentProof, encodePaymentProof, havenTools, isSupportedNodeVersion, isSweepableChain, parseMachinePaymentChallenge, parseMachinePaymentChallengeResponse, parsePaymentRequired, parsePaymentRequiredResponse, selectPaymentOption, selectStandardPaymentOption, signHash, signUserOpTypedDataForDelegation, sweepUsdcAddress, sweepUsdcDomain, toStandardPaymentRequirements, toolDescriptions, unsupportedNodeVersionMessage, verifyPaymentReceipt, verifySignature, x402AuthorizationAmount };
+/**
+ * #1271 / #1301: bounded same-origin merchant MCP endpoint discovery.
+ *
+ * An agent handed a BASE merchant URL previously had to hand-probe /, /mcp,
+ * /sse, … until something answered 402. The demo merchant (and the #1266
+ * contract) serves a machine-readable discovery document at
+ * `/.well-known/haven-demo-merchant` (also at `/`) naming `mcp_url`. This
+ * helper fetches ONLY those two fixed same-origin paths — no redirects
+ * (`redirect: 'error'`), a 5 s timeout, a 64 KB read cap — and accepts the
+ * document's `mcp_url` ONLY when it stays on the same origin as the input.
+ * Anything else returns null and the caller reports the original probe
+ * failure. Discovery finds endpoints; it carries no payment authority and an
+ * off-origin `mcp_url` is never even fetched — this must not grow into a
+ * general network scanner (SSRF bound, per the issue).
+ *
+ * Originally hosted-only (mcp-server, #1271). Moved here in #1301 so the
+ * local/self-signed MCP package (`@haven_ai/mcp`) can share the EXACT same
+ * bounded implementation instead of re-deriving discovery semantics —
+ * behavior is byte-identical to the pre-move mcp-server copy; the #1271
+ * contract tests in packages/mcp-server/src/tools.test.ts pass unmodified
+ * against this moved implementation.
+ */
+declare const MERCHANT_DISCOVERY_PATHS: readonly ["/.well-known/haven-demo-merchant", "/"];
+declare const DISCOVERY_MAX_BYTES: number;
+declare function discoverMerchantMcpUrl(inputUrl: string): Promise<string | null>;
+/** Trailing-slash/percent-case echoes compare equal; unparseable never does. */
+declare function sameUrl(a: string, b: string): boolean;
+
+export { AGENT_PAYMENT_FAILURE_CODE_VALUES, AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, type AgentNextStep, type AgentPaymentEnumSchema, AgentPaymentFailureCode, AgentPaymentFailureCodeDescriptions, AgentPaymentFailureCodeSchema, AgentPaymentNextAction, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, type AgentPaymentSummary, type AgentPaymentWarning, AgentPaymentWarningCode, type AgentPurchaseSummary, type ClaudeTool, DISCOVERY_MAX_BYTES, HAVEN_MINIMUM_NODE_VERSION, HAVEN_SKILL_MD, type HavenAgent, type HavenAgentAllowanceSummary, type HavenAgentReadiness, type HavenAgentSummary, type HavenAllowance, type HavenAllowanceSummary, HavenApiError, type HavenCatalogEntry, HavenClient, type HavenClientConfig, HavenError, type HavenPaymentReceipt, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, HavenUnsupportedSignerVersionError, MERCHANT_DISCOVERY_PATHS, type MachinePaymentChallenge, type MachinePaymentRail, type MachinePaymentReceipt, MerchantTimeoutError, type MppAuthorizationOptions, type MppQuote, type MppResumeState, type OpenAITool, type PaymentFee, type PaymentIntent, type PaymentNextAction, type PaymentPhase, type PaymentReceipt, type PaymentRequest, type PaymentResult, type PaymentResumeState, type PaymentStatus, type PaymentStatusResult, type PendingApproval, type PostPurchaseAllowanceSummary, RECEIPT_VERSION, type ReceiptVerification, type ResumeAuthorizedMppInput, type ResumeAuthorizedX402Input, type ResumeMppPaymentInput, type ResumeX402PaymentInput, SIGNER_UPDATE_FALLBACK, SKILL_FOLDER_NAME, SWEEP_BASE_CHAIN_ID, SWEEP_BASE_SEPOLIA_CHAIN_ID, SWEEP_BASE_SEPOLIA_USDC_ADDRESS, SWEEP_BASE_USDC_ADDRESS, type SharedToolKey, type SignData, SignerRefusalCode, type SweepAuthorization, type SweepEip712Domain, type SweepEntry, type SweepExpectedAuth, type SweepPreparation, type SweepPrepareResponse, type SweepResult, type SweepSubmitResponse, type SweepSubmitResult, type SweepTypedData, TRANSFER_WITH_AUTHORIZATION_TYPES, type ToolDescription, type UnsupportedNodeVersionMessageOptions, type X402AuthorizationOptions, type X402ExpectedAuth, type X402ExpectedContext, type X402Intent, type X402McpCallContext, type X402McpTransport, type X402MerchantCallContext, type X402PaymentOption, type X402PaymentRequired, type X402Quote, type X402Receipt, type X402RequestSnapshot, type X402ResumeState, X402UnexpectedStatusError, X402_MAX_AUTHORIZATION_WINDOW_SECONDS, X402_SETTLEMENT_FORWARD_MARGIN_SECONDS, addressFromKey, buildMachinePaymentIdempotencyKey, buildSweepAuthorizationMessage, buildSweepTypedData, buildX402ExpectedMessage, compareNodeVersions, composeDescription, decodeBase64Json, decodeBase64Utf8, discoverMerchantMcpUrl, encodeBase64Json, encodeBase64Utf8, encodeMachinePaymentProof, encodePaymentProof, havenTools, isSupportedNodeVersion, isSweepableChain, parseMachinePaymentChallenge, parseMachinePaymentChallengeResponse, parsePaymentRequired, parsePaymentRequiredResponse, resolveTokenFromAddress, sameUrl, selectPaymentOption, selectStandardPaymentOption, signHash, signUserOpTypedDataForDelegation, sweepUsdcAddress, sweepUsdcDomain, toStandardPaymentRequirements, toolDescriptions, unsupportedNodeVersionMessage, verifyPaymentReceipt, verifySignature, x402AuthorizationAmount };