@haven_ai/sdk 0.8.0-alpha.0 → 0.9.0-alpha.0

package/dist/{base64-znjJJQqu.d.cts → types-CrszUJ7Z.d.cts}

@@ -1,5 +1,129 @@
-import { PaymentRequirements } from 'x402/types';
-import { Hex, Address } from 'viem';
+/**
+ * #3747: the hosted merchant-egress policy.
+ *
+ * Hosted Haven sends requests to merchant URLs agents choose. This module is
+ * the STRING-LEVEL policy those requests run under when the embedder opts in
+ * (`HavenClientConfig.merchantEgress`, set by `createHostedHavenClient`):
+ * https only, no IP-literal hosts, no local or internal names, re-checked GET
+ * redirects, and per-use budgets (timeouts, a response byte cap enforced
+ * WHILE reading — never after buffering).
+ *
+ * Scope and limits, stated plainly:
+ *
+ *  - The policy is checked before every request and every redirect hop, but
+ *    it is a string check. A public host name whose DNS ANSWER points at
+ *    private space is NOT blocked here — that needs the resolution-time
+ *    checks parked in #3742–#3744 (owner-accepted residual, 2026-10-07).
+ *  - Without `merchantEgress`, NOTHING in the SDK changes: no `redirect:
+ *    'manual'`, no body capping, no extra refusals. SDK, local-MCP and
+ *    embedder callers keep today's behaviour byte for byte.
+ *  - The policy is network policy, not spend control. It never gates a
+ *    payment's authority — the on-chain allowance stays the real control
+ *    (CASP: off-chain policy is never the spend control).
+ */
+/** Which merchant use a budget applies to, so each use's timeout is pinnable. */
+type MerchantEgressUse = 'quote' | 'mcpSession' | 'discovery' | 'delivery';
+interface MerchantEgressTimeouts {
+    /** Quote probes (`quoteX402`, resume probes) — short. */
+    quote?: number;
+    /** MCP session setup (`initialize`) — short. */
+    mcpSession?: number;
+    /** Discovery fetches — short (the #1271 budget is 5s). */
+    discovery?: number;
+    /** Paid delivery — finite (today's default is 300s). */
+    delivery?: number;
+}
+interface MerchantEgressPolicy {
+    /**
+     * Refuse a URL before any request (or redirect hop) connects. Throws
+     * `MerchantEgressRefusedError` with `beforeRequest: true`; the transport
+     * re-marks hop-time refusals as mid-flight.
+     */
+    assertUrl(url: string): void;
+    /**
+     * Response byte cap, enforced while the body is being read (the stream
+     * errors mid-read) — never by buffering first. `undefined` = no cap.
+     */
+    maxResponseBytes?: number;
+    /**
+     * How many GET redirects may be followed; EVERY hop is re-asserted against
+     * `assertUrl` before it connects. A redirect on any other method is
+     * refused outright. `undefined` = no redirect following.
+     */
+    maxGetRedirects?: number;
+    /** Per-use timeouts (ms). The effective deadline is `min(this, merchantTimeout)`. */
+    timeouts?: MerchantEgressTimeouts;
+    /**
+     * Per-use response byte caps (#3747 spec review), enforced while the body
+     * is being read. A use absent here falls back to `maxResponseBytes`.
+     */
+    responseByteCaps?: Partial<Record<MerchantEgressUse, number>>;
+}
+type MerchantEgressRefusalReason = 'url_not_allowed' | 'redirect_on_non_get' | 'redirect_missing_location' | 'redirect_invalid_location' | 'redirect_budget_exceeded';
+declare const MERCHANT_EGRESS_REFUSED_CODE = "MERCHANT_EGRESS_REFUSED";
+/**
+ * The policy refused a merchant request. `beforeRequest` is true when the
+ * refusal happened BEFORE any request of that merchant use was sent (nothing
+ * is on the wire); false when it happened mid-flight — the initial request
+ * was already sent (a redirect answered, a hop refused, a body mid-read),
+ * which after a PAID delivery means the payment header may have been
+ * delivered and the money is in the verify-then-sweep state (#1300).
+ */
+declare class MerchantEgressRefusedError extends HavenError {
+    readonly url: string;
+    readonly refusal: MerchantEgressRefusalReason;
+    readonly beforeRequest: boolean;
+    constructor(message: string, url: string, refusal: MerchantEgressRefusalReason, beforeRequest: boolean);
+}
+declare const MERCHANT_EGRESS_RESPONSE_CAP_CODE = "MERCHANT_EGRESS_RESPONSE_CAP";
+/**
+ * A response body grew past `maxResponseBytes` WHILE it was being read —
+ * the read was aborted mid-stream, never buffered past the cap. Always
+ * mid-flight: the request was already sent.
+ */
+declare class MerchantEgressResponseCapError extends HavenError {
+    readonly url: string | undefined;
+    readonly limitBytes: number;
+    constructor(message: string, limitBytes: number, url?: string);
+}
+/**
+ * The strict hosted string check: https (any port), no IP literals (v4 or
+ * v6 — `URL` normalises the exotic spellings to these two shapes before this
+ * runs, as #3112 established for the retry-target check), no `localhost`, no
+ * single-label host, none of the internal/reserved suffixes. `true` for
+ * exactly the URLs a hosted merchant request may connect to.
+ */
+declare function isPublicHttpsMerchantUrl(url: string): boolean;
+/** Human-readable reason a URL failed `isPublicHttpsMerchantUrl`. */
+declare function publicHttpsMerchantUrlRefusal(url: string): string;
+/**
+ * The `assertUrl` half of the strict hosted policy: throws
+ * `MerchantEgressRefusedError` (beforeRequest: true) unless the URL is a
+ * public https URL. Message names the offending URL (agent-chosen input —
+ * never a RESOLVED address; this policy never resolves DNS).
+ */
+declare function assertPublicHttpsMerchantUrl(url: string): void;
+/** #1271's discovery budget, reused as the floor for hosted discovery reads. */
+declare const HOSTED_DISCOVERY_TIMEOUT_MS = 5000;
+/** Hosted per-use timeouts: short probes, finite paid delivery. */
+declare const HOSTED_EGRESS_TIMEOUTS: Required<MerchantEgressTimeouts>;
+/** Hosted per-use byte caps (#3747 spec review, owner-delegated values). */
+declare const HOSTED_RESPONSE_BYTE_CAPS: Required<Record<MerchantEgressUse, number>>;
+/** Hosted GET-redirect budget: every hop re-checked against the URL rules. */
+declare const HOSTED_MAX_GET_REDIRECTS = 3;
+/**
+ * The strict hosted policy `createHostedHavenClient` installs. Deliberately
+ * exported so the budgets are pinnable in tests and a deployment can build
+ * its own variant beside it.
+ */
+declare function strictMerchantEgressPolicy(): MerchantEgressPolicy;
+/**
+ * Read a response body as text with a byte cap enforced WHILE reading: the
+ * moment the stream grows past `maxBytes` the read is cancelled and a
+ * `MerchantEgressResponseCapError` is thrown — nothing is buffered past the
+ * cap, and a body that never ends cannot hold the read open.
+ */
+declare function readBodyCapped(response: Response, maxBytes: number): Promise<string>;
 
 interface HavenClientConfig {
     /** Haven API key (sk_agent_xxx) */
@@ -17,6 +141,16 @@ interface HavenClientConfig {
      *  merchants may settle on-chain synchronously, so the default is
      *  deliberately generous. #1300. */
     merchantTimeout?: number;
+    /**
+     * #3747: optional string-level merchant-egress policy. When set, EVERY
+     * merchant request (and every redirect hop) is checked against it before
+     * connecting; GET redirects are followed `manual` with re-checked hops;
+     * response bodies are capped WHILE being read; per-use timeouts apply.
+     * Absent — the SDK, local-MCP and embedder default — behaviour is
+     * unchanged. This is network policy, never spend control: the on-chain
+     * allowance remains the real control. See `merchant-egress.ts`.
+     */
+    merchantEgress?: MerchantEgressPolicy;
     /** Timeout in ms when polling for tx confirmation (default: 90000) */
     confirmationTimeout?: number;
     /** Polling interval in ms when waiting for confirmation (default: 3000) */
@@ -441,6 +575,13 @@ interface X402McpCallContext {
     toolName: string;
     arguments?: Record<string, unknown>;
     mcpTransport?: X402McpTransport;
+    /**
+     * #3781: Haven's own catalog row name, when the purchase came from a
+     * catalog entry — persisted with the context so a settle can report the
+     * catalog row's name as the display product. Optional — omit for a direct
+     * `haven_pay_mcp_tool` call. Haven-derived, never merchant content (#1349).
+     */
+    catalogName?: string;
 }
 /**
  * Response shape of `getX402MerchantCallContext` — the stored merchant call
@@ -452,6 +593,28 @@ interface X402MerchantCallContext {
     toolName: string;
     arguments: Record<string, unknown>;
     mcpTransport?: X402McpTransport;
+    /** #3781: the catalog row's name, when the purchase came from a catalog entry. */
+    catalogName?: string;
+}
+/**
+ * Response shape of `findX402IntentByIdempotencyKey` — the read-only state of
+ * the caller's own x402 intent for an idempotency key (#3739).
+ */
+interface X402IntentByKey {
+    paymentId: string;
+    status: string;
+    /** `null` when the stored row does not say (never guessed). */
+    settlementScheme: 'erc7710' | 'eip3009' | null;
+    resourceUrl: string | null;
+    expiresAt: string | null;
+    /** True only for a `pending_signature` intent whose `expiresAt` is still in the future. */
+    windowOpen: boolean;
+    taskBudgetId: string | null;
+    /** Atomic amount, as a string. */
+    amountAtomic: string;
+    /** #3739 review: token contract of `amountAtomic`, so a whole-token cap can be converted. */
+    asset: string | null;
+    network: string;
 }
 /** Quote parsed from an HTTP 402 response without creating a Haven payment. */
 interface X402Quote {
@@ -559,6 +722,19 @@ interface HavenAllowance {
     tokenSymbol: string;
     configuredAmount: string;
     resetPeriodMin: number;
+    /**
+     * #3731: whether the account's balance can back THIS row's WHOLE remaining
+     * period budget. `false` is a heads-up to mention to the user, never a
+     * refusal — a budget larger than the balance is a normal setup (an owner
+     * may top up weekly) and says nothing certain about the next payment;
+     * `null` when unverifiable (the chain read failed, or `remaining` was not
+     * read live — `onchain.remainingIsFromChain` false). Always present: any
+     * non-boolean wire value, including an absent one, maps to `null` rather
+     * than `undefined`. The key is absent on the WIRE when the remaining is 0
+     * (`balance >= 0` would be a vacuous true). Rows for one token are each
+     * compared alone — they do not add up. Never a balance figure.
+     */
+    fundsCoverRemaining: boolean | null;
     /**
      * #3518: this budget's SCOPE, so an agent holding more than one budget
      * for a token can name the merchant-locked one before paying. The
@@ -767,9 +943,13 @@ interface HavenBalanceCoverage {
  * call returns, so it surfaces as an API error rather than `revoked`. `revoked`
  * is reached when the request authenticates but the agent status is non-active.
  *
- * Wallet token balance is intentionally NOT folded in here: the on-chain
- * remaining allowance is the gate Haven enforces, and insufficient wallet
- * funding surfaces at pay time as INSUFFICIENT_FUNDS.
+ * Wallet token balance is intentionally NOT folded into the readiness value
+ * itself — `ready` stays an AUTHORITY signal (installed consumers switch on
+ * its value set) — but the account's ability to back it is reported beside
+ * it: the allowances rows carry `fundsCoverRemaining` (#3731), null when
+ * unverifiable, and an underfunded prepare surfaces at pay time as
+ * `PREPARE_REVERTED` with `revert_cause: "insufficient_balance"`, never
+ * `INSUFFICIENT_FUNDS`.
  */
 type HavenAgentReadiness = 'ready' | 'needs_approval' | 'revoked';
 /**
@@ -798,6 +978,14 @@ interface HavenAgentAllowanceSummary {
     configuredAmount: string;
     resetPeriodMin: number;
     isResetPending: boolean;
+    /**
+     * #3731: the {@link HavenAllowance.fundsCoverRemaining} projection —
+     * whether the account's balance can back this row's whole remaining
+     * period budget. `false` is a heads-up to mention to the user, not a
+     * refusal; `null` when unverifiable. Same provenance rule as the detailed
+     * read: any non-boolean wire value maps to `null`, never `undefined`.
+     */
+    fundsCoverRemaining: boolean | null;
 }
 /**
  * One-shot "am I ready?" bootstrap: identity + live spend authority + a
@@ -1811,6 +1999,20 @@ interface HavenCatalogEntry {
     protocol: 'http' | 'mcp';
     toolName: string | null;
     toolArguments: Record<string, unknown> | null;
+    /**
+     * #3769: the row's declared JSON Schema for a per-call MCP tool's caller
+     * arguments — `haven_prepare_catalog_purchase` validates an `arguments`
+     * input against it. NULL/absent on a fixed-SKU row, which refuses caller
+     * arguments. OPTIONAL on purpose: an installed SDK may face a backend
+     * predating #3769.
+     */
+    toolArgumentsSchema?: Record<string, unknown> | null;
+    /** #3769: the HTTP method a plain-HTTP resource needs (null = GET). OPTIONAL like the schema above. */
+    httpMethod?: string | null;
+    /** #3769: the body encoding of `bodyExample` — 'json' today. OPTIONAL like the schema above. */
+    bodyType?: string | null;
+    /** #3769: an example body the row's discovery hint carries. OPTIONAL like the schema above. */
+    bodyExample?: Record<string, unknown> | null;
     priceDisplay: string | null;
     priceAtomic: string | null;
     asset: string | null;
@@ -2094,1304 +2296,4 @@ declare class HavenTimeoutError extends HavenError {
     constructor(paymentId: string);
 }
 
-/**
- * Gasless delegate-sweep primitives — the single source of truth shared by the
- * edge signer (which signs) and the Haven backend (which relays).
- *
- * A stranded delegate EOA holds USDC but no ETH, so a raw ERC-20 transfer can't
- * pay for its own gas. Instead the delegate signs an *off-chain* EIP-3009
- * `TransferWithAuthorization` and the Haven relayer submits it on-chain and pays
- * gas. The relayer is only a gas payer: it holds no allowance and is never a
- * spender, so a relayer compromise cannot move user funds.
- *
- * Framework-neutral on purpose: `buildSweepTypedData` returns a plain
- * `{ domain, types, primaryType, message }` that both viem
- * (`signTypedData`/`recoverTypedDataAddress`) and ethers v6
- * (`signTypedData`/`verifyTypedData`) accept, so the signer (viem) and backend
- * (ethers) stay in lockstep without sharing a crypto library.
- */
-/** Base mainnet. The only chain Haven sweeps today. */
-declare const SWEEP_BASE_CHAIN_ID = 8453;
-/** Base Sepolia testnet — used by the dev environment / QA harness. */
-declare const SWEEP_BASE_SEPOLIA_CHAIN_ID = 84532;
-/** Canonical Circle USDC on Base (FiatTokenV2_2). */
-declare const SWEEP_BASE_USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
-/** Circle's canonical Base Sepolia testnet USDC. */
-declare const SWEEP_BASE_SEPOLIA_USDC_ADDRESS = "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
-/** True when the gasless sweep supports a chain (its USDC domain + address are known). */
-declare function isSweepableChain(chainId: number): boolean;
-/** EIP-712 `TransferWithAuthorization` struct, per EIP-3009. */
-declare const TRANSFER_WITH_AUTHORIZATION_TYPES: {
-    readonly TransferWithAuthorization: readonly [{
-        readonly name: "from";
-        readonly type: "address";
-    }, {
-        readonly name: "to";
-        readonly type: "address";
-    }, {
-        readonly name: "value";
-        readonly type: "uint256";
-    }, {
-        readonly name: "validAfter";
-        readonly type: "uint256";
-    }, {
-        readonly name: "validBefore";
-        readonly type: "uint256";
-    }, {
-        readonly name: "nonce";
-        readonly type: "bytes32";
-    }];
-};
-interface SweepEip712Domain {
-    name: string;
-    version: string;
-    chainId: number;
-    verifyingContract: string;
-}
-/**
- * A fully-specified EIP-3009 authorization. All amounts/times are decimal
- * strings (JSON-safe) and `nonce` is a 0x-prefixed 32-byte hex value. `token`
- * and `chainId` are carried explicitly so the signer can assert they are
- * canonical before signing.
- */
-interface SweepAuthorization {
-    /** Delegate EOA the funds are swept FROM. */
-    from: string;
-    /** The agent's Haven account the funds are swept TO. */
-    to: string;
-    /** Atomic USDC amount (decimal string). */
-    value: string;
-    /** Unix seconds the authorization becomes valid (decimal string, usually "0"). */
-    validAfter: string;
-    /** Unix seconds the authorization expires (decimal string). */
-    validBefore: string;
-    /** Random 0x-prefixed 32-byte hex nonce. */
-    nonce: string;
-    /** USDC contract address. */
-    token: string;
-    /** Chain id (8453 today). */
-    chainId: number;
-}
-/**
- * Haven's signature over the sweep authorization context, signed with the same
- * binding key the x402 expected-context uses. Lets the edge signer verify the
- * authorization actually came from Haven (and wasn't crafted by a compromised
- * hosted server pointing `to` at an attacker) before it signs.
- */
-interface SweepExpectedAuth {
-    /**
-     * Currently always 1. Typed as `number` for the same reason as
-     * `X402ExpectedAuth.version` (#1143): it is inbound, so a stale signer must be
-     * able to *receive* an unknown version in order to report it. The signer's
-     * `SUPPORTED_SWEEP_BINDING_VERSIONS` is the authority on what it will sign.
-     */
-    version: number;
-    message: string;
-    signature: string;
-    signer: string;
-}
-/** What `POST /machine-payments/sweep/prepare` returns when funds are stranded. */
-interface SweepPreparation {
-    authorization: SweepAuthorization;
-    expectedAuth: SweepExpectedAuth;
-}
-/** Wire response from `POST /machine-payments/sweep/prepare` (snake_case). */
-interface SweepPrepareResponse {
-    /** Present and true when the delegate holds nothing to recover. */
-    nothing_stranded?: boolean;
-    /**
-     * Present and true when the stranded balance is below the sweep floor (#700):
-     * it is left on the delegate as dust rather than recovered, because the gas to
-     * sweep it would exceed its value. `min_usdc` carries the configured floor. No
-     * `authorization` is built.
-     */
-    below_min?: boolean;
-    min_usdc?: string;
-    /** The authorization to sign — absent when nothing is stranded or below the floor. */
-    authorization?: SweepAuthorization;
-    /** Haven's binding over the authorization — absent when nothing is stranded. */
-    expected_auth?: SweepExpectedAuth;
-    asset?: string;
-    amount?: string;
-    amount_atomic?: string;
-    chain_id: number;
-    sign_instructions?: string;
-    message?: string;
-}
-/** Wire response from `POST /machine-payments/sweep/submit` (snake_case). */
-interface SweepSubmitResponse {
-    tx_hash: string;
-    asset: string;
-    amount: string;
-    amount_atomic: string;
-    from_address: string;
-    to_address: string;
-    chain_id: number;
-    explorer_url: string;
-    idempotent_replay?: boolean;
-}
-/** Result of a submitted gasless sweep. */
-interface SweepSubmitResult {
-    txHash: string;
-    amount: string;
-    amountAtomic: string;
-    asset: string;
-    fromAddress: string;
-    toAddress: string;
-    chainId: number;
-    explorerUrl: string;
-}
-interface SweepTypedData {
-    domain: SweepEip712Domain;
-    types: typeof TRANSFER_WITH_AUTHORIZATION_TYPES;
-    primaryType: 'TransferWithAuthorization';
-    message: {
-        from: string;
-        to: string;
-        value: bigint;
-        validAfter: bigint;
-        validBefore: bigint;
-        nonce: string;
-    };
-}
-/** Resolve the canonical USDC contract for a sweepable chain, or throw. */
-declare function sweepUsdcAddress(chainId: number): string;
-/** Resolve the USDC EIP-712 domain for a sweepable chain, or throw. */
-declare function sweepUsdcDomain(chainId: number): SweepEip712Domain;
-/**
- * Build the EIP-712 typed data for an authorization, validating that the token
- * and chain are canonical (the domain's `verifyingContract` must match the
- * authorization's `token`). Returns bigint-valued fields so both viem and
- * ethers v6 sign/recover identically.
- */
-declare function buildSweepTypedData(auth: SweepAuthorization): SweepTypedData;
-/**
- * Canonical, deterministic string the backend signs and the signer re-derives
- * for the authorization binding. The `Haven sweep authorization v1` namespace
- * (and `kind`) is distinct from the x402 expected-context namespace so an x402
- * binding can never be replayed as a sweep authorization even though they share
- * a signing key.
- */
-declare function buildSweepAuthorizationMessage(auth: SweepAuthorization): string;
-
-/**
- * Client identity on Haven API requests (#3303, epic #3302).
- *
- * Every published Haven client names itself with one header,
- * `X-Haven-Client: <package>/<version>`, so the backend can tell an outdated
- * client what to run — a `client_update` hint on its responses, or, only below
- * a minimum the deployment has explicitly set, a 426 `client_outdated` refusal
- * at the payment-initiating routes (the signer: at sign-context). The backend's
- * table and decision live in `@haven_ai/core`'s `client-compat.ts`; this module
- * is the client half and deliberately holds no thresholds.
- *
- * Deliberately free of any other SDK import so `@haven_ai/sdk/edge` (the
- * signer's ethers-free entry) can re-export it.
- */
-/**
- * This SDK's own version. Owned by `scripts/release-bump.mjs`, which rewrites
- * it with the package version on every release — never hand-edit it.
- */
-declare const SDK_VERSION = "0.8.0-alpha.0";
-/** The request header every published Haven client sends. */
-declare const HAVEN_CLIENT_HEADER = "X-Haven-Client";
-/** `<package>/<version>` — the value of {@link HAVEN_CLIENT_HEADER}. */
-declare function havenClientIdentity(pkg: string, version: string): string;
-/** What a bare SDK embedder sends when it names no package of its own. */
-declare const SDK_CLIENT_IDENTITY: string;
-/**
- * The `client_update` object the backend attaches to a response when this
- * client is behind (`required: false`) or below a set minimum
- * (`required: true`). Every field is the backend's; the SDK never computes one.
- */
-interface HavenClientUpdate {
-    package: string;
-    current: string;
-    recommended: string | null;
-    min_version: string | null;
-    required: boolean;
-    upgrade_command: string;
-    notes_url: string | null;
-}
-/** Narrow an unknown response field to a {@link HavenClientUpdate}, or undefined. */
-declare function readClientUpdate(value: unknown): HavenClientUpdate | undefined;
-
-/**
- * #3101 (epic #3105, slice 2/5): the typed next-step builder.
- *
- * Every hosted payment tool ends by naming the agent's next tool and its
- * arguments (#1308). Until this module, the tool was a free string and the
- * arguments a `Record<string, unknown>`, so nothing tied the keys to the tool
- * named beside them — three sites handed `{ payment_id: null }` to a tool
- * whose `payment_id` is a required string, and the compiler could not see it.
- *
- * The builder is generic over a TARGET MAP the caller supplies: bare tool
- * name → { role, validate }. It is deliberately schema-library-agnostic (the
- * SDK carries no zod): the hosted server derives each target's argument type
- * from its own zod shape and passes a `validate` closure; this module only
- * needs to know the role (to render `mcp__<server>__<tool>`) and how to say
- * whether arguments parse. Keyed on the bare name + role (decision 1) so the
- * namespaced string is rendered in exactly one place and the runtime-neutral
- * `next_tool_server` / `next_tool_name` / `next_tool_server_role` fields are
- * derived from the same input rather than parsed back out of a literal.
- *
- * Decisions 3 and 8: `nextTool` is REQUIRED on the input and may be `null` —
- * a site that forgets it is a compile error; a site with no next tool says
- * why, and the wire omits `next_tool` and carries `next_tool_omitted_reason`.
- * `next_tool` is never null on the wire.
- */
-type NextToolServerRole = 'hosted' | 'signer';
-/** The DEFAULT server name each role is wired under (#1588, #2550). */
-declare const NEXT_TOOL_SERVER_NAMES: Record<NextToolServerRole, string>;
-/** Default server name → role. An unknown server yields no role rather than a guess (#2550). */
-declare const NEXT_TOOL_SERVER_ROLES: Record<string, NextToolServerRole>;
-/** Renders the Claude-family namespaced tool name — the one string clients have followed since #1308. */
-declare function renderNextTool(role: NextToolServerRole, name: string): string;
-/** Parses a namespaced literal back into its parts; `role` is absent for an unknown server. */
-declare function parseNextTool(literal: string): {
-    server: string;
-    name: string;
-    role?: NextToolServerRole;
-} | null;
-/**
- * One target the builder may hand off to. `TArgs` is the argument type the
- * caller derived from the tool's declared schema; `validate` is the runtime
- * twin of that type and returns `null` when the arguments parse, else why not.
- */
-interface NextStepTarget<TArgs> {
-    role: NextToolServerRole;
-    validate: (input: unknown) => string | null;
-    /** Phantom carrier for the argument type; never read at runtime. */
-    readonly _args?: TArgs;
-}
-type NextStepTargets = Record<string, NextStepTarget<unknown>>;
-/** The argument type a target carries. */
-type NextStepArguments<Targets extends NextStepTargets, T extends keyof Targets> = Targets[T] extends NextStepTarget<infer A> ? A : never;
-/**
- * The handoff half of a next step: a registered tool with arguments that
- * tool accepts, or no tool with the reason. A discriminated union over the
- * target map's keys, so a wrong key, a missing required key, an unregistered
- * tool name and an omitted `nextTool` are each a compile error at the site.
- */
-type NextStepHandoff<Targets extends NextStepTargets> = {
-    [T in keyof Targets & string]: {
-        nextTool: T;
-        nextArguments: NextStepArguments<Targets, T>;
-    };
-}[keyof Targets & string] | {
-    nextTool: null;
-    nextToolOmittedReason: string;
-};
-type NextStepInput<Targets extends NextStepTargets> = NextStepHandoff<Targets> & {
-    nextAction: AgentPaymentNextAction;
-    safeToContinue: boolean;
-    reason: string;
-};
-/** The wire shape: `AgentNextStep` (its `next_tool` family) — never a null `next_tool`. */
-type NextStep = AgentNextStep;
-/**
- * Per-`next_action` default tool (decision 9): the tool a site names unless it
- * has a reason to override. Only actions with ONE sensible target are listed;
- * `retry_original_x402_request` is absent because its only live emitter names
- * no tool on purpose (the agent's own HTTP retry); `sign_and_submit_payment`
- * is absent because the signer tool
- * depends on the settlement scheme (`haven_sign` for erc7710 delegations,
- * `haven_sign_x402` for the EIP-3009 bridge) and a wrong default there would be
- * worse than none.
- */
-declare const DEFAULT_NEXT_TOOL_BY_ACTION: {
-    readonly check_status_later: "haven_get_payment_status";
-    readonly sweep_stranded_funds: "haven_sweep_delegate";
-};
-declare function defaultNextToolFor(action: AgentPaymentNextAction): string | undefined;
-/**
- * Builds a `nextStep` function bound to a target map. The returned function
- * renders the wire fields from the bare name + role, and re-validates the
- * arguments at runtime: on a mismatch it FAILS SAFE — omits the tool and says
- * why in `next_tool_omitted_reason` — rather than throwing out of a handler
- * that has already moved money. The compile-time twin makes that branch
- * unreachable from typed sites; it exists for callers that bypass the types.
- */
-declare function createNextStepBuilder<Targets extends NextStepTargets>(targets: Targets): (input: NextStepInput<Targets>) => NextStep;
-
-/**
- * The npm dist-tag the published Haven packages tell a user to re-run (#2423,
- * slice 3 of epic #2420).
- *
- * ## Why a constant and not a literal
- *
- * Roughly a dozen user- and agent-facing strings across `@haven_ai/sdk`,
- * `@haven_ai/signer`, `@haven_ai/connect` and the hosted MCP server say some
- * form of "re-run `npx @haven_ai/connect@alpha`". Every one of them was a
- * hard-coded literal, which is correct only for a build published under the
- * `alpha` dist-tag. Once `dev`-branch snapshots publish under a `dev` tag
- * (#2421), a snapshot build telling its tester to re-run `@alpha` would hand
- * them the production connector — silently replacing the very build they are
- * testing. So the tag becomes one build-time constant and every hint derives
- * from it.
- *
- * ## Who writes it
- *
- * `scripts/release-bump.mjs` rewrites {@link HAVEN_CONNECTOR_CHANNEL} from the
- * version it is bumping to, using exactly the rule `.github/workflows/publish.yml`
- * uses to pick the `--tag` for that same version:
- *
- * | version | dist-tag / channel |
- * |---|---|
- * | `0.1.34-alpha.0` | `alpha` |
- * | `0.0.0-dev.202609021200.abc1234` | `dev` |
- * | `0.2.0` | `latest` |
- *
- * One rule, two consumers. `scripts/ci/connector-channel-agreement.test.mjs`
- * executes the workflow's own shell and the bump script's own function over the
- * same version table and fails if they ever disagree.
- *
- * ## Build-time here, run-time there
- *
- * A published tarball cannot read a deployment's environment, so for the
- * published packages the channel is baked in at release time. A surface that is
- * *deployed* rather than published has no release at which to bake anything in,
- * so it reads the `HAVEN_CONNECTOR_CHANNEL` environment variable and falls back
- * to this constant. Two surfaces do that: the hosted MCP server
- * (`packages/mcp-server/src/connector-channel.ts`) and, since slice 2 (#2422),
- * the backend's connector handout (`parseConnectorChannel` in
- * `packages/backend/src/config.ts`). All three readers share one variable name,
- * one default and one validation pattern, and that agreement is EXECUTED rather
- * than asserted: `packages/backend/src/__tests__/connector-channel.test.ts`
- * runs this module's `resolveConnectorChannel` and the backend's
- * `parseConnectorChannel` over the same input table and fails if they ever
- * diverge.
- *
- * **This says nothing about how any environment is configured.** Setting the
- * variable anywhere is an operator action (epic #2420, operator step 3); no
- * code here can observe it and none of this comment asserts it has happened.
- */
-/** The published connector package. Never varies; only its tag does. */
-declare const CONNECTOR_PACKAGE_NAME = "@haven_ai/connect";
-/**
- * The npm dist-tag this build's re-run hints name.
- *
- * **Do not hand-edit.** `scripts/release-bump.mjs` owns this literal the same
- * way it owns `CONNECTOR_VERSION` and its siblings, and
- * `scripts/release-bump.test.mjs` fails if the two drift.
- */
-declare const HAVEN_CONNECTOR_CHANNEL = "alpha";
-/** True when `value` is a well-formed dist-tag. */
-declare function isConnectorChannel(value: string): boolean;
-/**
- * Resolve a channel from a deployment's `HAVEN_CONNECTOR_CHANNEL`.
- *
- * - unset, empty or whitespace ⇒ `fallback` (dashboards store a cleared
- *   variable as `""`, and that must land on the production-safe value);
- * - well-formed ⇒ itself;
- * - anything else ⇒ **throws**. It does not quietly fall back: a typo such as
- *   `dve` would then land on the production channel, and the environment would
- *   look fixed while reproducing the exact defect this slice removes.
- *
- * Well-formed-but-wrong (`dve` again) is *not* caught here and cannot be — it
- * fails later at `npx`, where the error names the package. Stated rather than
- * implied.
- */
-declare function resolveConnectorChannel(raw: string | undefined | null, fallback?: string): string;
-/** `@haven_ai/connect@<channel>` — the spec an `npx` invocation names. */
-declare function connectorSpec(channel?: string): string;
-/**
- * The re-run command every hint embeds.
- *
- * `connectorRerunCommand()` → `npx @haven_ai/connect@alpha`
- * `connectorRerunCommand('--doctor')` → `npx @haven_ai/connect@alpha --doctor`
- *
- * `args` is appended verbatim so each call site keeps its own flags and its own
- * surrounding sentence. The wording of those sentences is deliberately NOT
- * moved here: several are inside signer refusal messages that users and agents
- * pattern-match on, and this change is meant to move the channel token and
- * nothing else.
- */
-declare function connectorRerunCommand(args?: string, options?: {
-    channel?: string;
-    npxFlags?: string;
-}): string;
-/**
- * The command every UPGRADE hint names (#3412): `npx -y @haven_ai/connect@<channel> --doctor`.
- *
- * A bare connector re-run is a SETUP command — on a machine that is already
- * set up it stops at "Missing --setup <hv_setup_...> setup token", so an
- * outdated signer, local MCP or connector told to "re-run the connector" was
- * handed a dead end. The flagless doctor works as pasted on an existing
- * install (#3210: it resolves the runtime from the setup record), diagnoses an
- * outdated signer, and prints the exact `--doctor --repair` line for the agent
- * it describes — with `--credentials-dir` whenever more than one agent lives on
- * the machine, so the repair cannot land on a different agent.
- *
- * `-y` because an upgrade hint is often run by an agent in a non-interactive
- * shell. `@haven_ai/core`'s `upgradeCommandFor` (the backend's
- * `client_update.upgrade_command`) cannot import this package, so it carries a
- * copy; `packages/backend/src/__tests__/connector-upgrade-command-parity.test.ts`
- * fails if the two ever disagree. Setup-time hints (identity restore,
- * mid-setup retry) legitimately stay on {@link connectorRerunCommand}.
- */
-declare function connectorUpgradeCommand(options?: {
-    channel?: string;
-}): string;
-
-/**
- * The Node.js floor Haven's published packages support (#1161).
- *
- * ## Why this lives in the SDK
- *
- * Three packages need to enforce the same floor — `connect` (at setup),
- * `signer` and `mcp` (at startup) — and `@haven_ai/sdk` is the only dependency
- * all three already share. A copy per package is how the floor drifted in the
- * first place: `engines` said `>=24` everywhere while connect's runtime manifest
- * enforced `20.0.0`, so a connect run on Node v23 passed the guard, installed
- * the signer, and signed a real payment. Two numbers for one fact is one number
- * too many.
- *
- * Each consumer still owns its own refusal — the error type, the exit code, the
- * wording of "what to do next" — because a library must never terminate its
- * host process. This module only answers *is this version supported* and *what
- * should we tell the user*.
- *
- * ## Why a floor is enforced at all
- *
- * `engines` is advisory: npm emits `EBADENGINE` and installs anyway unless the
- * user happens to have `engine-strict` set. For a normal library that is a
- * reasonable default. For the **signer** it is not — it holds the delegate key
- * and produces every payment signature, so a subtle runtime incompatibility
- * shows up as a wrong or missing signature on a money path. "It seemed to work"
- * is precisely the evidence that cannot be relied on there.
- */
-/**
- * The minimum supported Node.js version, as `major.minor.patch`.
- *
- * MUST equal the `engines.node` floor declared by every published Haven
- * 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 = "22.0.0";
-/**
- * Compare two Node versions. Negative when `left` is older.
- *
- * An unparseable version parses to `0.0.0` and therefore compares as older than
- * any real floor — fail-closed. A version string Haven cannot read is not
- * evidence of a supported runtime, and treating it as one would reopen exactly
- * the hole this module closes.
- */
-declare function compareNodeVersions(left: string, right: string): number;
-declare function isSupportedNodeVersion(nodeVersion?: string, minimumNodeVersion?: string): boolean;
-interface UnsupportedNodeVersionMessageOptions {
-    /**
-     * What is being refused, in the user's terms — "Haven setup", "The Haven
-     * signer". Leads the message so the reader knows what just stopped.
-     */
-    subject: string;
-    nodeVersion?: string;
-    minimumNodeVersion?: string;
-    /** Appended verbatim as the closing line. Used for the re-run instruction. */
-    retryHint?: string;
-}
-/**
- * The refusal text.
- *
- * Names the detected version, the required version, and **how to fix it** — the
- * previous message stopped after the two version numbers, which tells a user
- * they are stuck without telling them how to get unstuck. The version-manager
- * lines are the fix for nearly everyone; the closing caveat is there because the
- * runtime that *spawns* the signer is frequently not the shell that was
- * upgraded, and a desktop app can keep launching the old Node long after
- * `node -v` in a terminal says otherwise.
- */
-declare function unsupportedNodeVersionMessage(options: UnsupportedNodeVersionMessageOptions): string;
-
-/**
- * x402 protocol support for the Haven SDK.
- *
- * Provides:
- * - parsePaymentRequired() — extract payment requirements from a 402 response
- * - parsePaymentRequiredResponse() — async parser with JSON body fallback
- * - encodePaymentProof()   — encode a receipt as a PAYMENT-SIGNATURE header
- *
- * The main authorizeX402() and fetchWithPayment() are methods on HavenClient
- * (see client.ts) since they need API access and signing.
- */
-
-/**
- * Persisted, agent-scoped facts used to preflight a signed standard x402
- * payment header. This is an integrity comparison only: it never rebuilds,
- * modifies, persists, or submits the supplied authorization.
- */
-interface X402PaymentHeaderContext {
-    merchantTo: string;
-    amountAtomic: string;
-    asset: string;
-    network: string;
-    resourceUrl: string;
-    payer: string;
-    chainId: number;
-}
-/** A deliberately value-free refusal for untrusted payment-header input. */
-declare class X402PaymentHeaderValidationError extends Error {
-    constructor();
-}
-/**
- * Upper bound on the MERCHANT-requested part of the EIP-3009 authorization
- * window (#715, epic #713). The x402 library sets
- * `validBefore = now + maxTimeoutSeconds` straight from the MERCHANT's 402
- * challenge — without a cap, a malicious or sloppy merchant can request a
- * year-long window and a leaked signed authorization stays spendable that
- * whole time. 600 s is generous for any facilitator settle (typical is
- * 30–60 s). This cap applies only to the signed authorization, never to the
- * advertised requirements echoed in `accepted`. A merchant requiring more
- * than the bounded lifetime can still reject at verification; preserving its
- * offer does not widen Haven's signing policy.
- */
-declare const X402_MAX_AUTHORIZATION_WINDOW_SECONDS = 600;
-/**
- * Forward margin ADDED on top of the (clamped) merchant timeout when the
- * authorization is actually signed (#1256). The x402 verify rule requires
- * `validBefore ≥ now + maxTimeoutSeconds` AT THE FACILITATOR — but the
- * upstream library computes `validBefore = now + maxTimeoutSeconds` at
- * SIGNING time, leaving zero forward margin. Haven's flow guarantees elapsed
- * time between the two (the funding UserOp confirms before the merchant
- * retry, ~1 min plus latency), so every purchase against a merchant whose
- * `maxTimeoutSeconds` exceeded that latency failed structurally — measured
- * live on Base mainnet: Anchor requires 300 s, and 226 s remained at verify.
- *
- * 300 s covers funding + retry latency with room to spare. The #715 exposure
- * ceiling becomes clamped-timeout + margin ≤ 900 s total forward — a
- * deliberate widening from 600 s, recorded on #1256: an authorization that
- * cannot pass verify protects no one, and 900 s is still bounded by the same
- * clamp discipline.
- */
-declare const X402_SETTLEMENT_FORWARD_MARGIN_SECONDS = 300;
-declare function normalizePaymentRequired(value: unknown): X402PaymentRequired | null;
-/**
- * The x402 wire header names, in one place (#2289).
- *
- * v2 renamed all three; v1's only name was `X-PAYMENT`, used in BOTH
- * directions. Haven had adopted the v2 names for everything it *reads* and
- * kept the v1 name for the one thing it *writes*, which is how a strict v2
- * merchant came to never see a payment header at all.
- *
- * The 2026-08-31 owner decision was to send both outbound names on every
- * retry rather than switch on `x402Version`: a v1 merchant ignores the name it
- * does not know, a v2 merchant ignores the legacy one, and no version
- * heuristic has to be right for a payment to land.
- *
- * **That is no longer unconditional (#2341).** It held while the cost of a
- * spare header was zero, and on the EIP-3009 bridge it still is. On erc7710 it
- * is not: that header carries a whole delegation chain, and duplicating it
- * overflowed the merchant's header limit — HTTP 431, every erc7710 settlement
- * refused. `x402PaymentHeaderNamesFor` below is the live rule; read it rather
- * than this paragraph, which records why the simpler rule was right first.
- */
-/** v2 client→server payment payload. The name a strict v2 merchant reads. */
-declare const X402_PAYMENT_HEADER_NAME = "PAYMENT-SIGNATURE";
-/** v1 client→server payment payload; still accepted by most v2 merchants. */
-declare const X402_LEGACY_PAYMENT_HEADER_NAME = "X-PAYMENT";
-/** v2 server→client payment requirements. */
-declare const X402_PAYMENT_REQUIRED_HEADER_NAME = "PAYMENT-REQUIRED";
-/** v2 server→client settlement receipt. */
-declare const X402_PAYMENT_RESPONSE_HEADER_NAME = "PAYMENT-RESPONSE";
-/**
- * Both wire names, v2 first — the value an EIP-3009 retry actually sends.
- *
- * **Not the general answer any more (#2341), and not what a recorder should
- * reach for.** This was the evidence record's `paymentProofHeaderName` while
- * both names always went on the wire; erc7710 now sends one, so a recorder
- * still reading this constant would log a legacy header that was never sent —
- * exactly the drift the previous wording promised it prevented. Use
- * `x402PaymentHeaderNamesSent(paymentHeader)`. Kept exported because it is a
- * published surface and removing it would break consumers.
- */
-declare const X402_PAYMENT_HEADER_NAMES_SENT = "PAYMENT-SIGNATURE, X-PAYMENT";
-/**
- * The x402 v2 payment envelope: `{x402Version, resource?, accepted, payload,
- * extensions?}` per the spec's PaymentPayload (§5.2.2).
- *
- * The `resource` and `extensions` echoes are the #2361 fix, and they are not
- * optional politeness: the spec makes the extensions echo a MUST ("the client
- * must include at least the info received"), and CoinGecko's facilitator was
- * live-bisected rejecting the echo-less envelope with a bare 400 while
- * accepting the identical signature and `accepted`/`payload` bytes with the
- * echoes added (#2360, Base mainnet, 2026-09-01). Both objects are echoed
- * VERBATIM from the merchant's 402 — never reconstructed — and omitted when
- * the challenge carries none, which keeps the envelope byte-identical to the
- * pre-#2361 shape for echo-less merchants (Ampersend and Soundside settled
- * that shape live, so omission is the proven-compatible default).
- *
- * The `accepted` wrap itself is #303's shape and predates this helper — see
- * the #300/#303 history before "fixing" it: scheme/network live INSIDE
- * `accepted` in v2, never at the top level.
- */
-declare function x402V2PaymentEnvelope(paymentRequired: Pick<X402PaymentRequired, 'x402Version' | 'resource' | 'extensions'>, accepted: X402PaymentOption, payload: unknown): Record<string, unknown>;
-/**
- * Parse an HTTP 402 response into x402 PaymentRequired data.
- *
- * Supports:
- * - v2: PAYMENT-REQUIRED header (base64 JSON)
- * - v1 fallback: X-PAYMENT header or response body
- */
-declare function parsePaymentRequired(response: Response): X402PaymentRequired;
-/**
- * Parse an HTTP 402 response into x402 PaymentRequired data.
- *
- * Soundside and other Bazaar-style MCP endpoints return the PaymentRequired
- * object in the JSON body, while older Haven demos and many x402 examples use
- * base64 headers. This keeps the synchronous header parser intact and adds the
- * body fallback needed for those endpoints.
- */
-declare function parsePaymentRequiredResponse(response: Response): Promise<X402PaymentRequired>;
-/**
- * Select the best payment option from the x402 accepts array.
- *
- * Preference order:
- * 1. Option on a Haven-supported network with a known token
- * 2. Any option on a Haven-supported network
- * 3. null — no compatible option
- */
-declare function selectPaymentOption(accepts: X402PaymentOption[]): X402PaymentOption | null;
-/** The `extra.assetTransferMethod` value that marks an erc7710-settleable entry. */
-declare const ERC7710_ASSET_TRANSFER_METHOD = "erc7710";
-/**
- * Read `extra.assetTransferMethod` defensively. `extra` is the merchant's own
- * object, so it is untrusted shape: anything that is not the exact string is
- * treated as "not erc7710" rather than coerced.
- */
-declare function x402AssetTransferMethod(option: X402PaymentOption): string | null;
-/** True when the merchant advertises this entry as erc7710-settleable. */
-declare function isErc7710Option(option: X402PaymentOption): boolean;
-/**
- * The facilitator addresses a merchant advertises for an erc7710 entry, for
- * the #1058 redeemer pin — or `null` when it pins nothing.
- *
- * **An EMPTY array is `null`, not `[]`.** The backend rejects an empty
- * `redeemers` list with a 400 (`routes/x402.ts`), and the QA scenario already
- * treats empty as absent. Returning `[]` here would hand callers a value that
- * means "pin to nobody" — which is not a narrower pin, it is an unbuildable
- * delegation.
- *
- * Malformed entries are DROPPED rather than failing the whole option, and that
- * asymmetry is deliberate. A pin narrowed by a merchant's typo means the
- * facilitator that actually tries to redeem is not on the list, so redemption
- * reverts — and erc7710 has no funding leg, so nothing moved and nothing is
- * stranded. Refusing the option outright would instead deny a payment the
- * remaining valid facilitators could have settled. Losing the payment is the
- * worse outcome, precisely because the failure this issue closes (#1453) is the
- * one where funds move BEFORE the rejection.
- */
-declare function x402FacilitatorAddresses(option: X402PaymentOption): string[] | null;
-/**
- * Select an option that can be paid with the official x402 EIP-3009 exact
- * scheme. Haven's older tx-hash proof path can describe more networks; the
- * merchant-verified path currently needs Base USDC.
- *
- * **Skips erc7710-tagged entries (#1453).** It used to return the first
- * positional match and never look at `extra.assetTransferMethod`, so a merchant
- * that listed its erc7710 entry first made a Haven client echo that option
- * while signing a standard EIP-3009 authorization. The merchant rejects the
- * mismatch cleanly — but on the two-leg bridge the account→delegate funding
- * transfer has already executed, so the visible result is a stranded delegate
- * balance for the sweep to reclaim. Only our own demo merchant's ordering was
- * holding that shut, and that pin binds our merchant, not the ones we do not
- * control.
- */
-declare function selectStandardPaymentOption(accepts: X402PaymentOption[]): X402PaymentOption | null;
-/**
- * Select the erc7710-settleable option, if the merchant advertises one.
- */
-declare function selectErc7710PaymentOption(accepts: X402PaymentOption[]): X402PaymentOption | null;
-/** What a settlement-scheme decision resolved to. */
-interface X402SchemeSelection {
-    scheme: 'erc7710' | 'eip3009';
-    option: X402PaymentOption;
-    /** Redeemer pin for the settlement child; only ever set on erc7710. */
-    facilitatorAddresses: string[] | null;
-}
-/**
- * THE preference rule, in one place (#1450 owner decision, #1453).
- *
- *   Prefer erc7710 whenever the account is on the delegation rail and the
- *   merchant advertises `extra.assetTransferMethod: "erc7710"`; fall back to
- *   the EIP-3009 bridge otherwise.
- *
- * Both halves of that condition are required, and the rail half is the
- * caller's to supply — the SDK cannot see which rail an account is on from a
- * 402 response alone. A legacy AllowanceModule account passing
- * `delegationRail: true` would select a scheme its account cannot settle; the
- * backend refuses that at authorize with the #1986 retired-rail 410 (#2245 —
- * previously a scheme-specific 400 that wrongly implied the legacy rail could
- * still settle via EIP-3009), which is where a rail mismatch SHOULD fail,
- * on-chain-adjacent rather than in a client that could be lying to itself.
- *
- * Returns `null` when neither scheme has a payable entry — the caller decides
- * whether that is an error or a reason to look elsewhere.
- */
-declare function selectX402SettlementScheme(accepts: X402PaymentOption[], opts: {
-    delegationRail: boolean;
-}): X402SchemeSelection | null;
-declare function x402AuthorizationAmount(option: X402PaymentOption): string;
-/**
- * Canonical Haven-authenticated x402 expected context, recomputed byte-for-byte
- * by the edge signer before it signs anything.
- *
- * **Two versions, and the version is derived — never passed in (#1138).**
- * `typedDataHash` present ⇒ v2, absent ⇒ v1. A v1 message is byte-identical to
- * what shipped before, so existing signers keep verifying legacy-rail bindings
- * unchanged.
- *
- * The version lives in both the header line and the payload so neither can be
- * reinterpreted as the other: a v2 context cannot be replayed as a v1 one that
- * drops the typed-data commitment, and a v1 context cannot be presented as v2.
- * That downgrade is exactly the attack the digest exists to stop — see
- * `assertExpectedBinding` in `@haven_ai/signer`, which refuses to raw-sign a
- * hash under a v2 binding and refuses to sign typed data without one.
- */
-declare function buildX402ExpectedMessage(context: X402ExpectedContext): string;
-declare function toStandardPaymentRequirements(paymentRequired: X402PaymentRequired, option: X402PaymentOption): PaymentRequirements;
-/**
- * Strictly validate an edge-signed EIP-3009 X-PAYMENT header against the
- * persisted x402 intent context before a hosted relay can submit funding.
- *
- * The merchant/facilitator remains the final protocol verifier. This closes a
- * separate hosted-relay integrity gap: malformed or context-mismatched input
- * must never cause Haven to relay the funding signature first.
- */
-declare function validateStandardX402PaymentHeader(paymentHeader: string, context: X402PaymentHeaderContext): Promise<void>;
-/**
- * Encode a payment receipt as a base64 PAYMENT-SIGNATURE header value.
- *
- * This follows the x402 v2 protocol — the server's facilitator will
- * verify the on-chain transaction referenced by tx_hash.
- */
-declare function encodePaymentProof(receipt: {
-    txHash: string;
-    paymentId: string;
-    token: string;
-    amount: string;
-    to: string;
-    resourceUrl?: string;
-    accepted?: X402PaymentOption;
-    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:8453").
- */
-declare function resolveTokenFromAddress(address: string, network?: string): {
-    symbol: string;
-    decimals: number;
-} | null;
-/**
- * #3410: token decimals from a SYMBOL + CHAIN — the same registry
- * `resolveTokenFromAddress` reads, keyed the other way. The address-based
- * resolver needs the token's contract address, which the consent seed path
- * (setup-time credential files) does not carry; the symbol and chain it does
- * carry. Null when the symbol is not registered on that chain (unknown or
- * custom tokens) — callers must fall back to an explicit atomic label rather
- * than reading an atomic amount as whole tokens.
- */
-declare function resolveTokenBySymbol(chainId: number, symbol: string): {
-    symbol: string;
-    decimals: number;
-} | null;
-
-/**
- * #3271: the integrity check every client runs before signing a direct
- * delegation-rail payment's typed data.
- *
- * A direct payment (`POST /payments`, surfaced as `haven_send` / `haven_pay`)
- * is signed as the HybridDeleGator's EIP-712 `PackedUserOperation`, and Haven
- * returns two things for it: that typed data, and `payload_hash` — the
- * ERC-4337 v0.7 UserOperation hash of the same operation. Nothing used to tie
- * the two together at signing time. The typed data is multi-KB and reaches the
- * signer through a language model when it is relayed by hand, so one corrupted
- * character produced a valid-looking signature over the wrong digest, and the
- * first sign of it was `AA24 signature error` from the bundler (#3271,
- * reproduced on dev 2026-09-24).
- *
- * This recomputes the v0.7 hash from the typed data's own message and domain
- * and refuses unless it equals `payload_hash`, and it pins the parts of the
- * typed data the hash does NOT cover (domain name/version/verifyingContract,
- * the field list, the EntryPoint). It is a CORRUPTION check: the caller supplies
- * both values, so it proves they describe the same operation, never that Haven
- * prepared it. Provenance is the byte-free sign context (`payment_id`); what a
- * delegate key will sign at all is `assertBoundDirectPaymentUserOp`
- * (`direct-payment-guard.ts`, #3272 / #3283), which every caller of this check
- * — `HavenClient.signForData` and the signer's `haven_sign` — runs next.
- *
- * Pure viem, no ethers: `@haven_ai/sdk/edge` re-exports it for the edge signer,
- * and `edge-imports.test.ts` pins that graph.
- */
-/** Version of the direct-payment sign context (`GET /payments/:id/sign-context`). */
-declare const DIRECT_SIGN_CONTEXT_VERSION = 1;
-/**
- * #3419: version of the task-budget sign context (`GET
- * /task-budgets/:id/sign-context`), the sign-then-submit envelope every
- * `haven_sign { task_budget_id }` call fetches. The backend emits it
- * (`task-budget-service.ts`, `task_sign_context_version: 1`); the signer
- * derives its enforced set `SUPPORTED_TASK_SIGN_CONTEXT_VERSIONS` from this
- * constant — never a second literal — and the hosted/local task-budget
- * handoffs report it in `signer_compatibility.task_sign_context_version`.
- * The signer could not carry the single source itself (a published package
- * cannot host a constant the backend also serves), so it lives beside the
- * other binding constants here, exactly as `DIRECT_SIGN_CONTEXT_VERSION` does.
- */
-declare const TASK_SIGN_CONTEXT_VERSION = 1;
-/** The ERC-4337 v0.7 EntryPoint — the only one the delegation rail submits to. */
-declare const ENTRY_POINT_V07 = "0x0000000071727De22E5E9d8BAf0edAc6f37da032";
-/**
- * The HybridDeleGator EIP-712 domain constants and the `PackedUserOperation`
- * field list, vendored from `@metamask/smart-accounts-kit`
- * (`contracts.HybridDeleGator.constants`, `SIGNABLE_USER_OP_TYPED_DATA`) so the
- * published packages need no runtime dependency on the kit. Pinned equal to the
- * kit's values by `userop-binding.test.ts`.
- */
-declare const HYBRID_DELEGATOR_DOMAIN_NAME = "HybridDeleGator";
-declare const HYBRID_DELEGATOR_DOMAIN_VERSION = "1";
-declare const PACKED_USER_OPERATION_FIELDS: ReadonlyArray<{
-    name: string;
-    type: string;
-}>;
-/** Refusal raised when UserOperation typed data (a direct payment, or the SDK's x402 funding leg) does not match its `payload_hash`. */
-declare class HavenUserOpBindingError extends HavenError {
-    constructor(message: string);
-}
-/** True when the typed data is a `PackedUserOperation` (the direct-payment shape). */
-declare function isPackedUserOperationTypedData(value: unknown): boolean;
-/**
- * Compute the ERC-4337 v0.7 UserOperation hash from a HybridDeleGator
- * `PackedUserOperation` typed-data object — the value Haven returns as
- * `payload_hash` for a direct payment (`getUserOperationHash`, entryPoint 0.7).
- */
-declare function packedUserOperationHash(typedData: unknown): Hex;
-/**
- * Refuse (throw `HavenUserOpBindingError`) unless this `PackedUserOperation`
- * typed data is the operation `payloadHash` names, in the HybridDeleGator
- * domain of its own sender, against the v0.7 EntryPoint. Returns the
- * recomputed hash.
- */
-declare function assertUserOpTypedDataBinding(typedData: unknown, payloadHash: string): Hex;
-
-/**
- * The counterfactual HybridDeleGator account address for an owner EOA (#3272).
- *
- * `haven_sign`'s unbound branch (`@haven_ai/signer`'s `tools.ts`) and, since
- * #3283, `HavenClient.signForData` (`direct-payment-guard.ts`) sign a
- * `PackedUserOperation`
- * only when its `sender` (== `domain.verifyingContract`) is THIS SIGNER'S OWN
- * delegate account — never any other HybridDeleGator, and never a third
- * party's. Haven provisions that account counterfactually at signup (#970):
- * it may have zero on-chain transactions, so the signer must be able to
- * compute its address OFFLINE, from nothing but the delegate key's own
- * address.
- *
- * This is exactly what `@metamask/smart-accounts-kit`'s
- * `getCounterfactualAccountData` computes for
- * `implementation: 'Hybrid'`, `deployParams: [owner, [], [], []]` (no passkey
- * co-owners — the only shape Haven's signup flow provisions), `deploySalt:
- * '0x'`: CREATE2 of an `ERC1967Proxy(HybridDeleGatorImpl, initialize(owner,
- * [], [], []))` behind the `SimpleFactory`.
- *
- * VENDORED, NOT IMPORTED. `@metamask/smart-accounts-kit` is a devDependency
- * only (see `package.json`) — this package installs on users' machines and
- * must not carry it at runtime. The constants below (the factory and
- * implementation addresses, the `ERC1967Proxy` bytecode) are copied from the
- * kit's pinned environment / `@metamask/delegation-abis`' bytecode export,
- * exactly like `settlement-child.ts` vendors the DelegationManager and caveat
- * enforcer addresses for the same reason. Cross-checked against the kit by
- * `packages/signer/src/delegate-account.pins.test.ts`, including against the real, on-chain
- * `direct-payment-userop.json` fixture.
- */
-
-/**
- * SimpleFactory — deterministically deployed, so Base and Base Sepolia share
- * the address (matches `packages/backend/src/rails/delegation-contracts.ts`'s
- * `simpleFactory` pin for both chains).
- */
-declare const SIMPLE_FACTORY_ADDRESS: Address;
-/**
- * HybridDeleGator implementation — matches `delegation-contracts.ts`'s
- * `hybridDeleGatorImpl` pin for both chains.
- */
-declare const HYBRID_DELEGATOR_IMPLEMENTATION: Address;
-/**
- * Derive the counterfactual HybridDeleGator account address for `owner`, with
- * no passkey co-owners — the only shape Haven's signup flow provisions
- * (#970). Pure and offline: no RPC call, no dependency on the account having
- * been deployed. Verified byte-for-byte against
- * `@metamask/smart-accounts-kit`'s `getCounterfactualAccountData` by
- * `packages/signer/src/delegate-account.pins.test.ts`, including against a real Base Sepolia payload served by the dev backend
- * (`direct-payment-userop.json`).
- */
-declare function deriveDelegateAccountAddress(owner: Address): Address;
-
-/**
- * Independent verification of an erc7710 x402 settlement child (#1455).
- *
- * Moved from `@haven_ai/signer` into the SDK by #3283 (epic #3284) so the
- * signer and `HavenClient.signForData` run ONE verifier. The signer checks the
- * child against the Haven-signed expected context; the SDK checks it against
- * the merchant's own 402, which Haven does not produce.
- *
- * WHY THIS EXISTS. `assertExpectedBinding` proves Haven *declared* a payload:
- * the expected context is signed by `HAVEN_X402_BINDING_SIGNER` and commits to
- * the digest of the exact bytes being signed. That is a real property, and it
- * is not this one. It says nothing about what the payload MEANS.
- *
- * A backend that declared `merchantTo = the real merchant` while pinning a
- * different payee in the child's `AllowedCalldata` caveat would produce a
- * perfectly consistent pair: the declaration binds the digest, the digest is
- * the child's, and the child pays someone else. The signature is the authority
- * here — the merchant's facilitator redeems it and pulls from the treasury — so
- * the signer has to re-derive the meaning locally or it is a pass-through with
- * extra steps.
- *
- * ADDRESSES ARE PINNED HERE ON PURPOSE. Reading the enforcer map from Haven
- * would make the check circular: an attacker who can pick which contract counts
- * as "the payee enforcer" can satisfy any comparison. Taking
- * `@metamask/smart-accounts-kit` as a runtime dependency was the other option
- * and was rejected — this package installs on users' machines. The constants
- * below are snapshot-pinned and cross-checked against the kit by a test
- * (`packages/signer/src/settlement-child.pins.test.ts`), the same pattern
- * `packages/core/src/chains.ts` uses against its registry.
- *
- * EXTRA CAVEATS ARE ALLOWED, and that is deliberate — verified, not assumed
- * (#1455 review challenged it directly).
- *
- * `DelegationManager.redeemDelegations` loops every caveat of every delegation
- * and calls `beforeHook` on each, with no break and no try/catch: a single
- * revert aborts the whole redemption, and nothing lets one caveat cause another
- * to be skipped. Top-level caveats are therefore strictly AND-ed, so one this
- * file does not recognise can only add a constraint, never remove one.
- *
- * The specific challenge was `LogicalOrWrapperEnforcer`, whose terms encode
- * several caveat GROUPS and whose own security notice warns that "the redeemer
- * can select the least restrictive group, bypassing stricter requirements in
- * other groups". That warning is about groups INSIDE the wrapper — it binds
- * whoever authors wrapper terms. The wrapper is itself one caveat among the
- * delegation's, so it is AND-ed with the four required below and cannot unlock
- * them.
- *
- * The shape that WOULD be dangerous is the inverse: a required caveat hidden
- * inside a wrapper group instead of sitting at top level, where the redeemer
- * could select a group that omits it. This file scans top-level caveats and
- * refuses on absence, so that child is refused for lacking the caveat — which
- * is the correct outcome and is pinned by a test.
- */
-/** DelegationManager, the EIP-712 `verifyingContract` for a delegation. */
-declare const DELEGATION_MANAGER = "0xdb9B1e94B5b69Df7e401DDbedE43491141047dB3";
-/**
- * Caveat enforcers, by role. Deterministically deployed, so Base and Base
- * Sepolia share addresses — verified for both chains by the pin test.
- */
-declare const CAVEAT_ENFORCERS: {
-    readonly erc20TransferAmount: "0xf100b0819427117EcF76Ed94B358B1A5b5C6D2Fc";
-    readonly allowedCalldata: "0xc2b0d624c1c4319760C96503BA27C347F3260f55";
-    readonly timestamp: "0x1046bb45C8d673d4ea75321280DB34899413c069";
-    readonly redeemer: "0xE144b0b2618071B4E56f746313528a669c7E65c5";
-};
-/** The backend's own ceiling (`MAX_SETTLEMENT_WINDOW_SECONDS`), enforced again here. */
-declare const MAX_SETTLEMENT_WINDOW_SECONDS = 600;
-interface SettlementChildTypedData {
-    domain: {
-        name?: string;
-        version?: string;
-        chainId?: number | string;
-        verifyingContract?: string;
-    };
-    types: Record<string, unknown>;
-    primaryType: string;
-    message: Record<string, unknown>;
-}
-/**
- * True when this typed data is a delegation — the shape that must never be
- * signed unbound. Excludes a SELF-delegation (`delegate === delegator`,
- * #3329): that is the shape of a task-budget child
- * (`task-budget-guards.ts`'s `isTaskChildTypedData`), a DIFFERENT typed-data
- * class verified by a different function against a different expectation. A
- * real settlement child's `delegate` is always a facilitator or
- * `ANY_BENEFICIARY` — never this account's own address — so narrowing here
- * costs this verifier nothing and keeps the two classes from ever
- * overlapping.
- */
-declare function isSettlementChildTypedData(value: unknown): value is SettlementChildTypedData;
-/**
- * Map an x402 network string to a chain id. Local on purpose (#1455 review):
- * the chain must come from Haven's SIGNED `network` field, never from the
- * payload under verification — see `verifySettlementChild`.
- */
-declare function chainIdForNetwork(network: string | undefined): number | undefined;
-interface SettlementChildExpectation {
-    merchantTo: string;
-    amount: string;
-    asset: string;
-    /**
-     * Derived from the expected context's SIGNED `network`, never from
-     * `typedData.domain.chainId`. Comparing the payload's own claim against
-     * itself is a check that cannot fail — which is exactly what shipped in the
-     * first draft of this file's call site, and what the review caught.
-     */
-    chainId: number;
-    /** ISO timestamp; the child must not outlive it. */
-    expiresAt?: string;
-    /**
-     * #3283 / #3281 criterion 8: the signer's OWN derived delegate account.
-     * When set, the child's `delegator` must be exactly this account — the
-     * child is a re-delegation of this agent's budget, never a grant from some
-     * other account the key happens to control.
-     */
-    delegatorAccount?: string;
-    /**
-     * #3283: the facilitator addresses the merchant's 402 advertised
-     * (`extra.facilitatorAddresses`). When non-empty, the child must carry a
-     * `RedeemerEnforcer` caveat pinning exactly this set — otherwise the child
-     * is a bearer instrument any party could redeem within its bounds.
-     */
-    redeemers?: readonly string[];
-}
-/** `@metamask/delegation-core`'s `ROOT_AUTHORITY` — a delegation chained to nothing. */
-declare const ROOT_AUTHORITY: string;
-/**
- * Verify a settlement child implements what the expected context declares.
- * Throws `HavenSigningError` on any disagreement; returns nothing on success.
- *
- * `now` is injectable so the expiry checks are testable without faking clocks.
- */
-declare function verifySettlementChild(typedData: SettlementChildTypedData, expected: SettlementChildExpectation, now?: number): void;
-
-/** Wire code for a typed-data payload outside the signable allowlist. */
-declare const TYPED_DATA_NOT_ALLOWED: "TYPED_DATA_NOT_ALLOWED";
-/**
- * A typed-data payload was refused before signing because it is not a shape
- * a delegate key may sign. Nothing was signed. `@haven_ai/signer` subclasses
- * this to attach its MCP next step; the `code` is the same on both.
- */
-declare class HavenTypedDataRefusedError extends HavenSigningError {
-    readonly code: typeof TYPED_DATA_NOT_ALLOWED;
-    constructor(message: string);
-}
-/**
- * Chains the delegation rail has PINNED delegation contracts for
- * (`packages/backend/src/rails/delegation-contracts.ts`) — the only chains a
- * direct-payment UserOp may be scoped to. No other chain has a pinned
- * DelegationManager/enforcer set, so every other chain is deliberately
- * excluded even where the delegate account itself could exist.
- */
-declare const DIRECT_PAYMENT_CHAIN_IDS: ReadonlySet<number>;
-/** The DeleGator's single-execution `execute((address,uint256,bytes))` — selector `0x5c1c6dcd`. */
-declare const EXECUTE_ABI: readonly [{
-    readonly type: "function";
-    readonly name: "execute";
-    readonly inputs: readonly [{
-        readonly name: "_execution";
-        readonly type: "tuple";
-        readonly components: readonly [{
-            readonly name: "target";
-            readonly type: "address";
-        }, {
-            readonly name: "value";
-            readonly type: "uint256";
-        }, {
-            readonly name: "callData";
-            readonly type: "bytes";
-        }];
-    }];
-    readonly outputs: readonly [];
-    readonly stateMutability: "payable";
-}];
-/**
- * The content + provenance allowlist (#3272 criteria 1–2). Call ONLY after
- * `assertUserOpTypedDataBinding` has already proven `typedData` is a
- * well-formed `PackedUserOperation` matching its own hash — this function
- * trusts `typedData.domain`/`message` are shaped correctly and checks only
- * what they SAY. Throws `HavenTypedDataRefusedError` (never returns) on any
- * disagreement.
- */
-declare function assertBoundDirectPaymentUserOp(typedData: Record<string, unknown>, delegateAddress: string): void;
-
-/**
- * The settlement-child half of the same surface (#3283): verify an erc7710
- * child against `expectation` (from somewhere Haven did not write — the
- * merchant's 402 in the SDK, the Haven-signed expected context in the
- * signer), AND that it is re-delegated from this key's OWN account. Throws
- * `HavenTypedDataRefusedError` (code `TYPED_DATA_NOT_ALLOWED`) on any
- * disagreement.
- */
-declare function assertOwnSettlementChild(typedData: unknown, expectation: SettlementChildExpectation, delegateAddress: string): void;
-/**
- * #3281 (epic #3284, criterion 5): pin WHERE an x402 EIP-3009 funding leg's
- * redemption sends the money. The funding leg is always
- * `transfer(<delegate EOA>, <amount>)` of the quoted token
- * (`delegation-authorize.ts` → `prepareDelegationPayment(agent, token,
- * payTo = the delegate EOA, amountRaw)`), so the single execution must be
- * exactly `encodePacked(asset, 0, transfer(delegateAddress, amount))`.
- *
- * `delegateAddress` is the signing key's OWN address — local, not from Haven —
- * so even a compromised Haven can at most move budget into the agent's own
- * EOA (the hot-delegate residual the sweep returns), never to an attacker.
- * `asset` and `amount` keep the leg consistent with what is being paid. Two
- * callers, two sources: the signer's x402 arm (#3281) passes the Haven-signed
- * expected context's; `HavenClient.signForData` (#3375) passes the 402 option
- * the SDK is paying, never the `/x402` response.
- *
- * Call ONLY after `assertBoundDirectPaymentUserOp` has passed on the same
- * typed data (it proves the `execute` → `redeemDelegations` shape this reads).
- * Throws `HavenTypedDataRefusedError` on any disagreement.
- */
-declare function assertFundingLegPaysDelegate(typedData: Record<string, unknown>, expected: {
-    delegateAddress: string;
-    asset: string;
-    amount: string;
-}): void;
-
-/**
- * Task budgets (#3329): independent verification of a task child delegation
- * and its close UserOp, mirroring `settlement-child.ts` / `direct-payment-
- * guard.ts` for a DIFFERENT typed-data class.
- *
- * A task budget's child is a SELF-delegation: the agent's own delegate
- * account grants itself a narrower, time-boxed slice of its budget
- * delegation (`delegate === delegator === the agent's own account`), chained
- * under the budget via `authority`. That is what separates it from an x402
- * settlement child, whose `delegate` is a facilitator/ANY_BENEFICIARY — never
- * the agent's own account. `isSettlementChildTypedData` (`settlement-
- * child.ts`) was narrowed to return `false` for a self-delegated payload so
- * the two classes cannot be confused by either verifier; this file is the
- * task-child counterpart, verified against a different expectation
- * (`GET /task-budgets/:id/sign-context`, never a merchant's 402).
- *
- * Two shapes, two functions:
- *  - `assertOwnTaskChild` verifies the `Delegation` typed data signed to OPEN
- *    a task budget.
- *  - `assertOwnTaskBudgetCloseUserOp` verifies the `PackedUserOperation`
- *    typed data signed to CLOSE one early (an on-chain
- *    `disableDelegation(child)` call from the agent's own account) — an
- *    authority-REDUCING action only, never a grant.
- *
- * `hashDelegation` below reproduces `@metamask/smart-accounts-kit/utils`'s
- * struct hash (via `@metamask/delegation-core`) byte-for-byte, WITHOUT taking
- * the kit as a runtime dependency (this package installs on users' machines —
- * same reasoning `delegate-account.ts` and `settlement-child.ts` give for
- * their own vendored constants). `DELEGATION_TYPEHASH` / `CAVEAT_TYPEHASH`
- * are pinned literals, cross-checked against the kit's own `hashDelegation`
- * by a test vector in `task-budget-guards.test.ts` (which imports the kit
- * ONLY in that test file).
- */
-
-/** The backend's own ceiling (`MAX_TASK_BUDGET_TTL_SECONDS`), enforced again here. */
-declare const MAX_TASK_BUDGET_TTL_SECONDS = 86400;
-interface TaskChildTypedData {
-    domain: {
-        name?: string;
-        version?: string;
-        chainId?: number | string;
-        verifyingContract?: string;
-    };
-    types: Record<string, unknown>;
-    primaryType: string;
-    message: Record<string, unknown>;
-}
-/**
- * True when this typed data is a task-budget child: a `Delegation` whose
- * `delegate` equals its own `delegator` (self-delegation). This is the ONLY
- * shape distinguishing it from an x402 settlement child (whose `delegate` is
- * a facilitator or `ANY_BENEFICIARY`) — `isSettlementChildTypedData` is
- * narrowed to return `false` for this same shape so the two verifiers never
- * overlap.
- */
-declare function isTaskChildTypedData(value: unknown): value is TaskChildTypedData;
-interface TaskChildExpectation {
-    chainId: number;
-    tokenAddress: string;
-    maxAmountAtomic: string;
-    recipientAddress: string | null;
-    /** unix seconds — the `TimestampEnforcer`'s `beforeThreshold`. */
-    expiresAt: number;
-    parentDelegationHash: string;
-}
-/**
- * Verify a task-budget child delegation is EXACTLY what
- * `GET /task-budgets/:id/sign-context` (purpose `open`) declared, AND that
- * both `delegate` and `delegator` are this signer's OWN account. Throws
- * `HavenTypedDataRefusedError` (never returns) on any disagreement.
- */
-declare function assertOwnTaskChild(typedData: unknown, expected: TaskChildExpectation, delegateAddress: string, now?: number): void;
-interface TaskBudgetCloseExpectation {
-    /** The child delegation's own struct hash (`agent_task_budgets.delegation_hash`). */
-    delegationHash: string;
-}
-/**
- * Verify a task-budget close UserOp is EXACTLY an on-chain
- * `disableDelegation(child)` call from the agent's own delegate account —
- * authority-REDUCING only, never a grant. Throws `HavenTypedDataRefusedError`
- * (never returns) on any disagreement.
- */
-declare function assertOwnTaskBudgetCloseUserOp(typedData: Record<string, unknown>, expected: TaskBudgetCloseExpectation, delegateAddress: string): void;
-/**
- * `@metamask/delegation-core`'s `DELEGATION_TYPEHASH` — pinned, cross-checked
- * against the kit by a test vector in `task-budget-guards.test.ts`.
- */
-declare const DELEGATION_TYPEHASH: Hex;
-/** `@metamask/delegation-core`'s `CAVEAT_TYPEHASH` — pinned, same cross-check. */
-declare const CAVEAT_TYPEHASH: Hex;
-interface DelegationForHashing {
-    delegate: Address;
-    delegator: Address;
-    authority: Hex;
-    caveats: readonly {
-        enforcer: Address;
-        terms: Hex;
-    }[];
-    salt: bigint;
-}
-/**
- * Reproduces `@metamask/smart-accounts-kit/utils`'s `hashDelegation`
- * byte-for-byte, WITHOUT the kit at runtime (see the file header). Ignores
- * `signature` — the kit's own `hashDelegation` does the same (it hashes with
- * `signature: '0x'` regardless of what the caller passes).
- */
-declare function hashDelegation(delegation: DelegationForHashing): Hex;
-
-/**
- * Runtime-agnostic base64 helpers — the single source of truth for the wire
- * encoding shared by the SDK and the edge signer (#325).
- *
- * Why this module exists: the SDK used `atob`/`btoa` (Web globals) while the
- * signer used `Buffer` (Node-only). Both worked because both currently run in
- * Node ≥ 16, but the duplication was a latent wire-incompatibility — and the
- * signer is headed for non-Node runtimes (browsers, Cloudflare Workers) where
- * `Buffer` does not exist (#314).
- *
- * Encoding contract:
- * - Output is ALWAYS standard base64 (`+`, `/`, padded). The x402 protocol's
- *   reference implementation validates headers against
- *   `/^[A-Za-z0-9+/]*={0,2}$/` — URL-safe output would be rejected.
- * - Decoding is tolerant: URL-safe input (`-`, `_`, unpadded) is normalized
- *   before decoding, since third-party merchants are not guaranteed to be as
- *   strict as the reference implementation.
- * - UTF-8 throughout. Naive `btoa(JSON.stringify(...))` throws on any
- *   non-Latin-1 character (e.g. a merchant description with an emoji or
- *   non-ASCII name); these helpers route through TextEncoder/TextDecoder on
- *   the Web path so multibyte characters round-trip identically on both
- *   runtimes.
- */
-/** Encode a UTF-8 string as standard base64. */
-declare function encodeBase64Utf8(value: string): string;
-/** Decode standard or URL-safe base64 to a UTF-8 string. */
-declare function decodeBase64Utf8(value: string): string;
-/** Encode a JSON-serializable value as a standard-base64 string. */
-declare function encodeBase64Json(value: unknown): string;
-/**
- * Decode a base64 JSON payload.
- *
- * Pass a `label` to get a wrapped error message instead of the raw
- * JSON/base64 error — call sites parsing untrusted merchant headers use this
- * to produce actionable failures.
- */
-declare function decodeBase64Json<T>(value: string, label?: string): T;
-
-export { AgentPaymentFailureCodeSchema as $, type AgentPaymentWarning as A, type BudgetPrecheckResult as B, type CloseTaskBudgetResult as C, type X402Erc7710Settlement as D, type X402McpCallContext as E, type SignData as F, type ResumeAuthorizedX402Input as G, type HavenClientConfig as H, type ResumeX402PaymentInput as I, type X402ResumeState as J, type X402McpTransport as K, type X402MerchantCallContext as L, HavenError as M, AGENT_PAYMENT_FAILURE_CODE_VALUES as N, type OpenTaskBudgetResult as O, type PaymentRequest as P, AGENT_PAYMENT_NEXT_ACTION_VALUES as Q, type RawPaymentParties as R, type SweepResult as S, type TaskBudgetSignContext as T, AGENT_PAYMENT_PHASE_VALUES as U, AGENT_PAYMENT_RAIL_VALUES as V, type AgentNextStep as W, type X402PaymentRequired as X, type AgentPaymentEnumSchema as Y, AgentPaymentFailureCode as Z, AgentPaymentFailureCodeDescriptions as _, type HavenClientUpdate as a, SignerRefusalCode as a$, AgentPaymentNextAction as a0, AgentPaymentNextActionDescriptions as a1, AgentPaymentNextActionSchema as a2, AgentPaymentPhase as a3, AgentPaymentPhaseDescriptions as a4, AgentPaymentPhaseSchema as a5, AgentPaymentRail as a6, AgentPaymentRailDescriptions as a7, AgentPaymentRailSchema as a8, type AgentPaymentSummary as a9, HavenZeroSettlementHashError as aA, MAX_TASK_BUDGET_TTL_SECONDS as aB, type MachinePaymentRail as aC, MerchantTimeoutError as aD, NEXT_TOOL_SERVER_NAMES as aE, NEXT_TOOL_SERVER_ROLES as aF, type NextStep as aG, type NextStepArguments as aH, type NextStepHandoff as aI, type NextStepInput as aJ, type NextStepTarget as aK, type NextStepTargets as aL, type NextToolServerRole as aM, PACKED_USER_OPERATION_FIELDS as aN, type PaymentFee as aO, type PaymentNextAction as aP, type PaymentPhase as aQ, type PaymentStatus as aR, ROOT_AUTHORITY as aS, SDK_CLIENT_IDENTITY as aT, SDK_VERSION as aU, SIGNER_UPDATE_FALLBACK as aV, SWEEP_BASE_CHAIN_ID as aW, SWEEP_BASE_SEPOLIA_CHAIN_ID as aX, SWEEP_BASE_SEPOLIA_USDC_ADDRESS as aY, SWEEP_BASE_USDC_ADDRESS as aZ, type SettlementChildExpectation as a_, AgentPaymentWarningCode as aa, type AgentPurchaseSummary as ab, CONNECTOR_PACKAGE_NAME as ac, type CatalogSubmissionAccepted as ad, DEFAULT_CONFIRMATION_TIMEOUT_MS as ae, DEFAULT_NEXT_TOOL_BY_ACTION as af, DIRECT_SIGN_CONTEXT_VERSION as ag, ENTRY_POINT_V07 as ah, ERC7710_ASSET_TRANSFER_METHOD as ai, HAVEN_CLIENT_HEADER as aj, HAVEN_CONNECTOR_CHANNEL as ak, HAVEN_MINIMUM_NODE_VERSION as al, HYBRID_DELEGATOR_DOMAIN_NAME as am, HYBRID_DELEGATOR_DOMAIN_VERSION as an, type HavenAgentAllowanceSummary as ao, type HavenAgentReadiness as ap, type HavenAllowance as aq, HavenApiError as ar, type HavenCatalogMerchant as as, type HavenListScope as at, HavenPaymentStateError as au, HavenSigningError as av, HavenTimeoutError as aw, HavenTypedDataRefusedError as ax, HavenUnsupportedSignerVersionError as ay, HavenUserOpBindingError as az, type PaymentResult as b, parsePaymentRequiredResponse as b$, type SweepConfirmation as b0, type SweepEip712Domain as b1, type SweepEntry as b2, type SweepExpectedAuth as b3, type SweepPreparation as b4, type SweepSubmitResult as b5, type SweepTypedData as b6, TASK_SIGN_CONTEXT_VERSION as b7, TRANSFER_WITH_AUTHORIZATION_TYPES as b8, TYPED_DATA_NOT_ALLOWED as b9, buildSweepAuthorizationMessage as bA, buildSweepTypedData as bB, buildX402ExpectedMessage as bC, compareNodeVersions as bD, connectorRerunCommand as bE, connectorSpec as bF, connectorUpgradeCommand as bG, createNextStepBuilder as bH, decodeBase64Json as bI, decodeBase64Utf8 as bJ, defaultNextToolFor as bK, deriveDelegateAccountAddress as bL, encodeBase64Json as bM, encodeBase64Utf8 as bN, encodePaymentProof as bO, hashDelegation as bP, havenClientIdentity as bQ, isConnectorChannel as bR, isErc7710Option as bS, isPackedUserOperationTypedData as bT, isSupportedNodeVersion as bU, isSweepableChain as bV, isTaskChildTypedData as bW, normalizePaymentRequired as bX, packedUserOperationHash as bY, parseNextTool as bZ, parsePaymentRequired as b_, type TaskBudgetCloseExpectation as ba, type TaskChildExpectation as bb, type TaskChildTypedData as bc, type UnsupportedNodeVersionMessageOptions as bd, X402AlreadySettledError as be, X402Erc7710AlreadySettledError as bf, type X402ExpectedAuth as bg, type X402ExpectedContext as bh, type X402PaymentHeaderContext as bi, X402PaymentHeaderValidationError as bj, type X402PaymentOption as bk, type X402RequestSnapshot as bl, type X402SchemeSelection as bm, X402TaskBudgetMismatchError as bn, X402UnexpectedStatusError as bo, X402_LEGACY_PAYMENT_HEADER_NAME as bp, X402_MAX_AUTHORIZATION_WINDOW_SECONDS as bq, X402_PAYMENT_HEADER_NAME as br, X402_PAYMENT_HEADER_NAMES_SENT as bs, X402_PAYMENT_REQUIRED_HEADER_NAME as bt, X402_PAYMENT_RESPONSE_HEADER_NAME as bu, X402_SETTLEMENT_FORWARD_MARGIN_SECONDS as bv, assertBoundDirectPaymentUserOp as bw, assertOwnTaskBudgetCloseUserOp as bx, assertOwnTaskChild as by, assertUserOpTypedDataBinding as bz, type PaymentIntent as c, readClientUpdate as c0, renderNextTool as c1, resolveConnectorChannel as c2, resolveTokenBySymbol as c3, resolveTokenFromAddress as c4, selectErc7710PaymentOption as c5, selectPaymentOption as c6, selectStandardPaymentOption as c7, selectX402SettlementScheme as c8, signerUpdateFallback as c9, sweepUsdcAddress as ca, sweepUsdcDomain as cb, toStandardPaymentRequirements as cc, unsupportedNodeVersionMessage as cd, validateStandardX402PaymentHeader as ce, verifySettlementChild as cf, x402AssetTransferMethod as cg, x402AuthorizationAmount as ch, x402FacilitatorAddresses as ci, x402V2PaymentEnvelope as cj, type DelegationForHashing as ck, CAVEAT_ENFORCERS as cl, CAVEAT_TYPEHASH as cm, DELEGATION_MANAGER as cn, DELEGATION_TYPEHASH as co, DIRECT_PAYMENT_CHAIN_IDS as cp, EXECUTE_ABI as cq, HYBRID_DELEGATOR_IMPLEMENTATION as cr, MAX_SETTLEMENT_WINDOW_SECONDS as cs, SIMPLE_FACTORY_ADDRESS as ct, type SettlementChildTypedData as cu, assertFundingLegPaysDelegate as cv, assertOwnSettlementChild as cw, chainIdForNetwork as cx, isSettlementChildTypedData as cy, type X402AuthorizationOptions as d, type X402Intent as e, type PaymentStatusResult as f, type HavenAgent as g, type HavenAgentSummary as h, type SweepPrepareResponse as i, type SweepAuthorization as j, type SweepSubmitResponse as k, type HavenAllowanceSummary as l, type HavenBalanceCoverage as m, type PostPurchaseAllowanceSummary as n, type HavenCatalogEntry as o, type HavenCatalogSubmission as p, type HavenPaymentReceipt as q, type HavenPaymentReceiptsPage as r, type HavenTaskBudget as s, type SubmitTaskBudgetResult as t, type SubmitSubBudgetResult as u, type HavenPendingSubBudgetSignature as v, type CloseSubBudgetResult as w, type PaymentResumeState as x, type X402Receipt as y, type X402Quote as z };
+export { AgentPaymentNextActionSchema as $, type AgentPaymentWarning as A, type BudgetPrecheckResult as B, type CloseTaskBudgetResult as C, type X402ResumeState as D, type X402McpTransport as E, type X402MerchantCallContext as F, type X402IntentByKey as G, type HavenClientConfig as H, HavenError as I, AGENT_PAYMENT_FAILURE_CODE_VALUES as J, AGENT_PAYMENT_NEXT_ACTION_VALUES as K, AGENT_PAYMENT_PHASE_VALUES as L, type MerchantEgressPolicy as M, AGENT_PAYMENT_RAIL_VALUES as N, type OpenTaskBudgetResult as O, type PaymentRequest as P, type AgentNextStep as Q, type ResumeAuthorizedX402Input as R, type SweepResult as S, type TaskBudgetSignContext as T, type AgentPaymentEnumSchema as U, AgentPaymentFailureCode as V, AgentPaymentFailureCodeDescriptions as W, type X402PaymentRequired as X, AgentPaymentFailureCodeSchema as Y, AgentPaymentNextAction as Z, AgentPaymentNextActionDescriptions as _, type PaymentResult as a, AgentPaymentPhase as a0, AgentPaymentPhaseDescriptions as a1, AgentPaymentPhaseSchema as a2, AgentPaymentRail as a3, AgentPaymentRailDescriptions as a4, AgentPaymentRailSchema as a5, type AgentPaymentSummary as a6, AgentPaymentWarningCode as a7, type AgentPurchaseSummary as a8, type CatalogSubmissionAccepted as a9, type PaymentNextAction as aA, type PaymentPhase as aB, type PaymentStatus as aC, SIGNER_UPDATE_FALLBACK as aD, SignerRefusalCode as aE, type SweepConfirmation as aF, type SweepEntry as aG, X402AlreadySettledError as aH, X402Erc7710AlreadySettledError as aI, type X402ExpectedAuth as aJ, type X402ExpectedContext as aK, type X402PaymentOption as aL, type X402RequestSnapshot as aM, X402TaskBudgetMismatchError as aN, X402UnexpectedStatusError as aO, assertPublicHttpsMerchantUrl as aP, isPublicHttpsMerchantUrl as aQ, publicHttpsMerchantUrlRefusal as aR, readBodyCapped as aS, signerUpdateFallback as aT, strictMerchantEgressPolicy as aU, type RawPaymentParties as aV, DEFAULT_CONFIRMATION_TIMEOUT_MS as aa, HOSTED_DISCOVERY_TIMEOUT_MS as ab, HOSTED_EGRESS_TIMEOUTS as ac, HOSTED_MAX_GET_REDIRECTS as ad, HOSTED_RESPONSE_BYTE_CAPS as ae, type HavenAgentAllowanceSummary as af, type HavenAgentReadiness as ag, type HavenAllowance as ah, HavenApiError as ai, type HavenCatalogMerchant as aj, type HavenListScope as ak, HavenPaymentStateError as al, HavenSigningError as am, HavenTimeoutError as an, HavenUnsupportedSignerVersionError as ao, HavenZeroSettlementHashError as ap, MERCHANT_EGRESS_REFUSED_CODE as aq, MERCHANT_EGRESS_RESPONSE_CAP_CODE as ar, type MachinePaymentRail as as, type MerchantEgressRefusalReason as at, MerchantEgressRefusedError as au, MerchantEgressResponseCapError as av, type MerchantEgressTimeouts as aw, type MerchantEgressUse as ax, MerchantTimeoutError as ay, type PaymentFee as az, type PaymentIntent as b, type X402AuthorizationOptions as c, type X402Intent as d, type PaymentStatusResult as e, type HavenAgent as f, type HavenAgentSummary as g, type HavenAllowanceSummary as h, type HavenBalanceCoverage as i, type PostPurchaseAllowanceSummary as j, type HavenCatalogEntry as k, type HavenCatalogSubmission as l, type HavenPaymentReceipt as m, type HavenPaymentReceiptsPage as n, type HavenTaskBudget as o, type SubmitTaskBudgetResult as p, type SubmitSubBudgetResult as q, type HavenPendingSubBudgetSignature as r, type CloseSubBudgetResult as s, type PaymentResumeState as t, type X402Receipt as u, type X402Quote as v, type X402Erc7710Settlement as w, type X402McpCallContext as x, type SignData as y, type ResumeX402PaymentInput as z };