@haven_ai/sdk 0.1.4 → 0.1.6

package/dist/index.d.cts

@@ -1,3 +1,5 @@
+import { PaymentRequirements } from 'x402/types';
+
 interface HavenClientConfig {
     /** Haven API key (sk_agent_xxx) */
     apiKey: string;
@@ -144,6 +146,55 @@ interface X402AuthorizationOptions {
     /** Stable caller-supplied key for this user intent. Prevents duplicate approvals across fresh 402 quotes. */
     idempotencyKey?: string;
 }
+/**
+ * Keyless x402 construct result.
+ *
+ * Returned by `createX402Intent` — the non-custodial half of an x402 payment.
+ * It carries the unsigned funding hash (`signData.hash`, Safe → delegate EOA)
+ * plus everything the *edge* needs to build and sign the EIP-3009 merchant
+ * header itself. The construct path never signs; both delegate signatures
+ * (funding hash + merchant header) happen on the machine that holds the key.
+ */
+interface X402Intent {
+    /** Haven payment id for the funding transfer. */
+    paymentId: string;
+    status: 'pending_signature';
+    /** ISO 8601 expiry of the funding intent, if returned. */
+    expiresAt?: string;
+    /** The unsigned funding hash to sign with the delegate key (Safe → delegate EOA). */
+    signData: SignData;
+    /** The selected x402 option — the edge needs this to build the EIP-3009 header. */
+    accepted: X402PaymentOption;
+    /** Resource URL the 402 came from. */
+    resourceUrl: string;
+    /** Merchant payTo address (the final recipient of the EIP-3009 transfer). */
+    merchantTo: string;
+    /** Atomic amount the edge signer must authorize in the merchant header. */
+    amountAtomic: string;
+    /** Token contract the merchant header must pay. */
+    asset: string;
+    /** x402 network the merchant header must use. */
+    network: string;
+    /** Haven-authenticated binding over the x402 expected context. */
+    expectedAuth: X402ExpectedAuth;
+    /** Delegate EOA the funding transfer tops up (the x402 payer). */
+    fundingTo: string;
+}
+interface X402ExpectedContext {
+    paymentId: string;
+    payloadHash: string;
+    resourceUrl: string;
+    merchantTo: string;
+    amount: string;
+    asset: string;
+    network: string;
+}
+interface X402ExpectedAuth {
+    version: 1;
+    message: string;
+    signature: string;
+    signer: string;
+}
 /** Serializable HTTP request state for retrying the same x402 merchant request. */
 interface X402RequestSnapshot {
     url: string;
@@ -342,6 +393,8 @@ interface HavenAllowanceSummary {
 interface HavenPaymentReceipt {
     id: string;
     paymentId: string;
+    paymentIntentId?: string | null;
+    approvalRequestId?: string | null;
     rail: string;
     proofStatus: string;
     txHash: string;
@@ -415,20 +468,46 @@ declare const AgentPaymentNextAction: {
     readonly RequestAgainIfUserStillWantsIt: "request_again_if_user_still_wants_it";
 };
 type AgentPaymentNextAction = (typeof AgentPaymentNextAction)[keyof typeof AgentPaymentNextAction];
+/**
+ * Stable rail identifier carried on Haven agent payment responses and resume
+ * state.
+ *
+ * Two layers of vocabulary share this enum because both reach the wire:
+ *
+ *   - **Categorical rails** identify the rail family and are used as
+ *     discriminators on `PaymentResumeState`: `direct`, `x402`, `mpp`.
+ *   - **Granular rails** identify the specific protocol the backend persists
+ *     and returns on response bodies: `mpp_demo`, `mpp_crypto`,
+ *     `stripe_deposit`, `spt`. `x402` doubles as both categorical and
+ *     granular.
+ *
+ * Consumers reading the top-level `rail` field on a payment status response
+ * should treat any `mpp*` value as the MPP family; consumers reading the
+ * `rail` field on a `MppResumeState` will always see the categorical `mpp`,
+ * with the granular value on `paymentRail`.
+ */
 declare const AgentPaymentRail: {
     /** Standard Haven payment from the user's Safe through an approved delegate allowance. */
     readonly Direct: "direct";
     /** x402 HTTP 402 payment flow with a Haven funding leg and merchant retry leg. */
     readonly X402: "x402";
-    /** Machine Payment Protocol flow. */
+    /** Machine Payment Protocol family — categorical value used as a resume-state discriminator. */
     readonly Mpp: "mpp";
+    /** Haven internal MPP demo rail. Not for production traffic. */
+    readonly MppDemo: "mpp_demo";
+    /** Crypto-settled MPP rail. */
+    readonly MppCrypto: "mpp_crypto";
+    /** Stripe-deposit-backed MPP rail. */
+    readonly StripeDeposit: "stripe_deposit";
+    /** Stripe Payment Token MPP rail. */
+    readonly Spt: "spt";
 };
 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")[];
 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")[];
-declare const AGENT_PAYMENT_RAIL_VALUES: ("x402" | "mpp" | "direct")[];
+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 AgentPaymentRailDescriptions: Record<AgentPaymentRail, string>;
@@ -566,6 +645,23 @@ declare class HavenClient {
      * Returns the intent with the hash to sign.
      */
     createIntent(request: PaymentRequest): Promise<PaymentIntent>;
+    /**
+     * Keyless x402 construct.
+     *
+     * The non-custodial half of an x402 payment: posts the funding request to
+     * `/x402` and returns the unsigned funding hash plus the data the caller
+     * needs to build and sign the EIP-3009 merchant header itself. Crucially it
+     * does **not** sign — neither the funding hash nor the merchant header — so
+     * it works without a `delegateKey`. Both delegate signatures happen on the
+     * machine that holds the key (the edge); the hosted MCP server relays only.
+     *
+     * Use this from the hosted, keyless server. The all-in-one `authorizeX402`
+     * remains for local clients that hold the key.
+     *
+     * Throws (via the shared payment-state path) when the amount exceeds the
+     * on-chain allowance — there is nothing to sign until the user approves.
+     */
+    createX402Intent(paymentRequired: X402PaymentRequired, options?: X402AuthorizationOptions): Promise<X402Intent>;
     /**
      * Step 2: Sign a hash with the delegate key.
      *
@@ -723,8 +819,15 @@ declare class HavenClient {
 /**
  * Pre-built tool definitions for AI agent frameworks.
  *
- * These definitions describe the `make_payment` and `get_payment_status` tools
- * in the formats expected by Claude (Anthropic) and OpenAI.
+ * These definitions describe Haven's direct SDK tool-calling surface in the
+ * formats expected by Claude (Anthropic) and OpenAI.
+ *
+ * The agent payment surface used by these tools is shared with the
+ * `@haven_ai/mcp` server — both consume `toolDescriptions` from
+ * `./tool-descriptions.ts`. Each consumer composes its own user-visible string
+ * from the same semantic fragments, so guidance lands in both surfaces at
+ * once and a downstream test asserts the shared summary appears in every
+ * consumer description.
  *
  * Usage with Claude:
  *   const response = await anthropic.messages.create({
@@ -786,6 +889,105 @@ declare function addressFromKey(privateKey: string): string;
  */
 declare function verifySignature(hash: string, signature: string, expectedAddress: string): boolean;
 
+/**
+ * Shared semantic descriptions for Haven agent payment tools.
+ *
+ * Two surfaces in this repo expose Haven as a tool: the Claude / OpenAI
+ * function-calling tool definitions in `tools.ts` (used for direct SDK
+ * integrations) and the MCP server in `packages/mcp` (used by any MCP-speaking
+ * agent runtime). The two surfaces use different tool *names* — the SDK's
+ * tools are tuned for tool-calling conventions (`make_payment`,
+ * `authorize_x402_payment`); the MCP tools follow the MCP `haven_*` naming
+ * (`haven_pay_x402_quote`).
+ *
+ * The underlying *operations* are the same, so the descriptive prose should
+ * live in one place. Both surfaces import from this module and compose their
+ * own tool descriptions from these semantic fragments. Drift is caught by
+ * tests asserting each consumer's description string contains the shared
+ * `summary` from this module.
+ */
+interface ToolDescription {
+    /** One-line summary of the operation. Used as the first sentence of every
+     * downstream description and as a stable substring for drift tests. */
+    summary: string;
+    /** Natural-language user intents that should make an agent prefer this
+     * tool over adjacent tools. Empty or omitted when the summary is enough. */
+    selectionGuidance?: string;
+    /** Concrete behaviour the tool performs end-to-end, including which
+     * non-custodial guarantee applies. */
+    behavior: string;
+    /** What the agent should do next on error / pending-approval states.
+     * Empty string if not applicable. */
+    nextActionGuidance: string;
+}
+/**
+ * Build a single description string from the three fragments. Joined with
+ * spaces so consumers can split on the summary substring if they need to.
+ */
+declare function composeDescription(d: ToolDescription): string;
+declare const toolDescriptions: {
+    readonly quoteX402: {
+        readonly summary: "Inspect an HTTP 402 x402 paid resource without creating a Haven payment, signature, approval, or on-chain transaction.";
+        readonly behavior: "Probes the merchant directly and parses the 402 response. Pure read-only client behavior — Haven is not contacted.";
+        readonly nextActionGuidance: "";
+    };
+    readonly payX402: {
+        readonly summary: "Pay an inspected x402 quote. The delegate key signs locally; Haven only validates and relays signed, on-chain-constrained payment transactions.";
+        readonly selectionGuidance: "Do not use this for read-only allowance, budget, spend-limit, remaining-amount, reset-period, or what-can-I-spend questions; use the allowance lookup tool instead.";
+        readonly behavior: "Signs the EIP-3009 payment from the delegate wallet, asks Haven for a Safe AllowanceModule top-up if needed, and returns the merchant response or a pending-approval state.";
+        readonly nextActionGuidance: "If approval is needed, preserve the returned resume_state and wait for nextAction=retry_original_x402_request before resuming.";
+    };
+    readonly resumeX402: {
+        readonly summary: "Resume an x402 payment after the Haven wallet owner approved the funding step.";
+        readonly behavior: "Accepts either resume_state or payment_id, validates the original x402 details against the approved Haven funding, and retries the merchant request with the X-PAYMENT header. No new Haven approval is created.";
+        readonly nextActionGuidance: "Only use when get_payment_status returns nextAction=retry_original_x402_request; do not start a new merchant session.";
+    };
+    readonly quoteMpp: {
+        readonly summary: "Inspect a Haven MPP challenge or paid MPP URL without creating a Haven payment, signature, approval, or on-chain transaction.";
+        readonly behavior: "Parses an MPP challenge envelope and returns a typed quote with rail tag, amount, asset, and merchant context. Pure read-only — Haven is not contacted.";
+        readonly nextActionGuidance: "";
+    };
+    readonly payMpp: {
+        readonly summary: "Pay an inspected MPP challenge. The delegate key signs locally; Haven only validates and relays signed, on-chain-constrained payment transactions.";
+        readonly selectionGuidance: "Do not use this for read-only allowance, budget, spend-limit, remaining-amount, reset-period, or what-can-I-spend questions; use the allowance lookup tool instead.";
+        readonly behavior: "Authorizes the payment through Haven within the on-chain allowance, signs the challenge proof, and returns the proof header for retrying the original paid resource.";
+        readonly nextActionGuidance: "If approval is needed, preserve resume_state or payment_id and wait for nextAction=retry_original_x402_request before resuming.";
+    };
+    readonly resumeMpp: {
+        readonly summary: "Resume an MPP payment after the Haven wallet owner approved the funding step.";
+        readonly behavior: "Accepts either resume_state or payment_id and retries the original paid resource with the MPP proof header. No new Haven approval is created.";
+        readonly nextActionGuidance: "";
+    };
+    readonly getPaymentStatus: {
+        readonly summary: "Fetch structured Haven payment status, including phase and nextAction taxonomy for agent recovery.";
+        readonly behavior: "Accepts a payment intent or approval request id and returns the full state taxonomy (phase, nextAction, rail, amount, merchant, resource url, idempotency key, message).";
+        readonly nextActionGuidance: "";
+    };
+    readonly getResumeState: {
+        readonly summary: "Rehydrate stored x402 or MPP resume_state by payment_id.";
+        readonly behavior: "Returns the context that the agent originally received in a pending-approval response, reconstructed from Haven's database. This is context only; signing still happens locally when a resume tool is called.";
+        readonly nextActionGuidance: "";
+    };
+    readonly getAgent: {
+        readonly summary: "Return the authenticated agent identity, Haven wallet, delegate address, chain, and status.";
+        readonly behavior: "Read-only identity lookup. Useful for verifying which on-chain Safe and delegate the credential is bound to.";
+        readonly nextActionGuidance: "";
+    };
+    readonly getAllowances: {
+        readonly summary: "Return configured and on-chain allowance state for the authenticated agent. On-chain allowance is the real spend gate.";
+        readonly selectionGuidance: "Use this when the user asks about allowance, budget, spend limit, remaining amount, remaining allowance, remaining budget, daily limit, reset period, what can I spend, or what the agent can still spend.";
+        readonly behavior: "Reads the Safe AllowanceModule snapshot per token (allowance, spent, remaining, reset window). Configured amounts from Haven are returned alongside the on-chain truth.";
+        readonly nextActionGuidance: "";
+    };
+    readonly listReceipts: {
+        readonly summary: "List recent machine-payment receipts and evidence for bookkeeping.";
+        readonly selectionGuidance: "Use this for transaction history, receipts, payment evidence, or bookkeeping; use the allowance tool instead for remaining allowance, budget, spend-limit, or what-can-I-spend questions.";
+        readonly behavior: "Returns the agent's recent machine-payment receipts ordered by recency. Proof header values are not returned.";
+        readonly nextActionGuidance: "";
+    };
+};
+type SharedToolKey = keyof typeof toolDescriptions;
+
 /**
  * x402 protocol support for the Haven SDK.
  *
@@ -824,6 +1026,15 @@ declare function parsePaymentRequiredResponse(response: Response): Promise<X402P
  * 3. null — no compatible option
  */
 declare function selectPaymentOption(accepts: X402PaymentOption[]): X402PaymentOption | 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.
+ */
+declare function selectStandardPaymentOption(accepts: X402PaymentOption[]): X402PaymentOption | null;
+declare function x402AuthorizationAmount(option: X402PaymentOption): string;
+declare function buildX402ExpectedMessage(context: X402ExpectedContext): string;
+declare function toStandardPaymentRequirements(paymentRequired: X402PaymentRequired, option: X402PaymentOption): PaymentRequirements;
 /**
  * Encode a payment receipt as a base64 PAYMENT-SIGNATURE header value.
  *
@@ -847,4 +1058,4 @@ declare function parseMachinePaymentChallengeResponse(response: Response): Promi
 declare function buildMachinePaymentIdempotencyKey(challenge: MachinePaymentChallenge): string;
 declare function encodeMachinePaymentProof(receipt: Omit<MachinePaymentReceipt, 'proofHeader'>): string;
 
-export { AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, type AgentPaymentEnumSchema, AgentPaymentNextAction, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, type ClaudeTool, type HavenAgent, type HavenAllowance, type HavenAllowanceSummary, HavenApiError, HavenClient, type HavenClientConfig, HavenError, type HavenPaymentReceipt, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, type MachinePaymentChallenge, type MachinePaymentRail, type MachinePaymentReceipt, type MppAuthorizationOptions, type MppQuote, type MppResumeState, type OpenAITool, type PaymentIntent, type PaymentNextAction, type PaymentPhase, type PaymentRequest, type PaymentResult, type PaymentResumeState, type PaymentStatus, type PaymentStatusResult, type PendingApproval, type ResumeAuthorizedMppInput, type ResumeAuthorizedX402Input, type ResumeMppPaymentInput, type ResumeX402PaymentInput, type SignData, type X402AuthorizationOptions, type X402PaymentOption, type X402PaymentRequired, type X402Quote, type X402Receipt, type X402RequestSnapshot, type X402ResumeState, addressFromKey, buildMachinePaymentIdempotencyKey, encodeMachinePaymentProof, encodePaymentProof, havenTools, parseMachinePaymentChallenge, parseMachinePaymentChallengeResponse, parsePaymentRequired, parsePaymentRequiredResponse, selectPaymentOption, signHash, verifySignature };
+export { AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, type AgentPaymentEnumSchema, AgentPaymentNextAction, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, type ClaudeTool, type HavenAgent, type HavenAllowance, type HavenAllowanceSummary, HavenApiError, HavenClient, type HavenClientConfig, HavenError, type HavenPaymentReceipt, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, type MachinePaymentChallenge, type MachinePaymentRail, type MachinePaymentReceipt, type MppAuthorizationOptions, type MppQuote, type MppResumeState, type OpenAITool, type PaymentIntent, type PaymentNextAction, type PaymentPhase, type PaymentRequest, type PaymentResult, type PaymentResumeState, type PaymentStatus, type PaymentStatusResult, type PendingApproval, type ResumeAuthorizedMppInput, type ResumeAuthorizedX402Input, type ResumeMppPaymentInput, type ResumeX402PaymentInput, type SharedToolKey, type SignData, type ToolDescription, type X402AuthorizationOptions, type X402ExpectedAuth, type X402ExpectedContext, type X402Intent, type X402PaymentOption, type X402PaymentRequired, type X402Quote, type X402Receipt, type X402RequestSnapshot, type X402ResumeState, addressFromKey, buildMachinePaymentIdempotencyKey, buildX402ExpectedMessage, composeDescription, encodeMachinePaymentProof, encodePaymentProof, havenTools, parseMachinePaymentChallenge, parseMachinePaymentChallengeResponse, parsePaymentRequired, parsePaymentRequiredResponse, selectPaymentOption, selectStandardPaymentOption, signHash, toStandardPaymentRequirements, toolDescriptions, verifySignature, x402AuthorizationAmount };

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { PaymentRequirements } from 'x402/types';
+
 interface HavenClientConfig {
     /** Haven API key (sk_agent_xxx) */
     apiKey: string;
@@ -144,6 +146,55 @@ interface X402AuthorizationOptions {
     /** Stable caller-supplied key for this user intent. Prevents duplicate approvals across fresh 402 quotes. */
     idempotencyKey?: string;
 }
+/**
+ * Keyless x402 construct result.
+ *
+ * Returned by `createX402Intent` — the non-custodial half of an x402 payment.
+ * It carries the unsigned funding hash (`signData.hash`, Safe → delegate EOA)
+ * plus everything the *edge* needs to build and sign the EIP-3009 merchant
+ * header itself. The construct path never signs; both delegate signatures
+ * (funding hash + merchant header) happen on the machine that holds the key.
+ */
+interface X402Intent {
+    /** Haven payment id for the funding transfer. */
+    paymentId: string;
+    status: 'pending_signature';
+    /** ISO 8601 expiry of the funding intent, if returned. */
+    expiresAt?: string;
+    /** The unsigned funding hash to sign with the delegate key (Safe → delegate EOA). */
+    signData: SignData;
+    /** The selected x402 option — the edge needs this to build the EIP-3009 header. */
+    accepted: X402PaymentOption;
+    /** Resource URL the 402 came from. */
+    resourceUrl: string;
+    /** Merchant payTo address (the final recipient of the EIP-3009 transfer). */
+    merchantTo: string;
+    /** Atomic amount the edge signer must authorize in the merchant header. */
+    amountAtomic: string;
+    /** Token contract the merchant header must pay. */
+    asset: string;
+    /** x402 network the merchant header must use. */
+    network: string;
+    /** Haven-authenticated binding over the x402 expected context. */
+    expectedAuth: X402ExpectedAuth;
+    /** Delegate EOA the funding transfer tops up (the x402 payer). */
+    fundingTo: string;
+}
+interface X402ExpectedContext {
+    paymentId: string;
+    payloadHash: string;
+    resourceUrl: string;
+    merchantTo: string;
+    amount: string;
+    asset: string;
+    network: string;
+}
+interface X402ExpectedAuth {
+    version: 1;
+    message: string;
+    signature: string;
+    signer: string;
+}
 /** Serializable HTTP request state for retrying the same x402 merchant request. */
 interface X402RequestSnapshot {
     url: string;
@@ -342,6 +393,8 @@ interface HavenAllowanceSummary {
 interface HavenPaymentReceipt {
     id: string;
     paymentId: string;
+    paymentIntentId?: string | null;
+    approvalRequestId?: string | null;
     rail: string;
     proofStatus: string;
     txHash: string;
@@ -415,20 +468,46 @@ declare const AgentPaymentNextAction: {
     readonly RequestAgainIfUserStillWantsIt: "request_again_if_user_still_wants_it";
 };
 type AgentPaymentNextAction = (typeof AgentPaymentNextAction)[keyof typeof AgentPaymentNextAction];
+/**
+ * Stable rail identifier carried on Haven agent payment responses and resume
+ * state.
+ *
+ * Two layers of vocabulary share this enum because both reach the wire:
+ *
+ *   - **Categorical rails** identify the rail family and are used as
+ *     discriminators on `PaymentResumeState`: `direct`, `x402`, `mpp`.
+ *   - **Granular rails** identify the specific protocol the backend persists
+ *     and returns on response bodies: `mpp_demo`, `mpp_crypto`,
+ *     `stripe_deposit`, `spt`. `x402` doubles as both categorical and
+ *     granular.
+ *
+ * Consumers reading the top-level `rail` field on a payment status response
+ * should treat any `mpp*` value as the MPP family; consumers reading the
+ * `rail` field on a `MppResumeState` will always see the categorical `mpp`,
+ * with the granular value on `paymentRail`.
+ */
 declare const AgentPaymentRail: {
     /** Standard Haven payment from the user's Safe through an approved delegate allowance. */
     readonly Direct: "direct";
     /** x402 HTTP 402 payment flow with a Haven funding leg and merchant retry leg. */
     readonly X402: "x402";
-    /** Machine Payment Protocol flow. */
+    /** Machine Payment Protocol family — categorical value used as a resume-state discriminator. */
     readonly Mpp: "mpp";
+    /** Haven internal MPP demo rail. Not for production traffic. */
+    readonly MppDemo: "mpp_demo";
+    /** Crypto-settled MPP rail. */
+    readonly MppCrypto: "mpp_crypto";
+    /** Stripe-deposit-backed MPP rail. */
+    readonly StripeDeposit: "stripe_deposit";
+    /** Stripe Payment Token MPP rail. */
+    readonly Spt: "spt";
 };
 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")[];
 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")[];
-declare const AGENT_PAYMENT_RAIL_VALUES: ("x402" | "mpp" | "direct")[];
+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 AgentPaymentRailDescriptions: Record<AgentPaymentRail, string>;
@@ -566,6 +645,23 @@ declare class HavenClient {
      * Returns the intent with the hash to sign.
      */
     createIntent(request: PaymentRequest): Promise<PaymentIntent>;
+    /**
+     * Keyless x402 construct.
+     *
+     * The non-custodial half of an x402 payment: posts the funding request to
+     * `/x402` and returns the unsigned funding hash plus the data the caller
+     * needs to build and sign the EIP-3009 merchant header itself. Crucially it
+     * does **not** sign — neither the funding hash nor the merchant header — so
+     * it works without a `delegateKey`. Both delegate signatures happen on the
+     * machine that holds the key (the edge); the hosted MCP server relays only.
+     *
+     * Use this from the hosted, keyless server. The all-in-one `authorizeX402`
+     * remains for local clients that hold the key.
+     *
+     * Throws (via the shared payment-state path) when the amount exceeds the
+     * on-chain allowance — there is nothing to sign until the user approves.
+     */
+    createX402Intent(paymentRequired: X402PaymentRequired, options?: X402AuthorizationOptions): Promise<X402Intent>;
     /**
      * Step 2: Sign a hash with the delegate key.
      *
@@ -723,8 +819,15 @@ declare class HavenClient {
 /**
  * Pre-built tool definitions for AI agent frameworks.
  *
- * These definitions describe the `make_payment` and `get_payment_status` tools
- * in the formats expected by Claude (Anthropic) and OpenAI.
+ * These definitions describe Haven's direct SDK tool-calling surface in the
+ * formats expected by Claude (Anthropic) and OpenAI.
+ *
+ * The agent payment surface used by these tools is shared with the
+ * `@haven_ai/mcp` server — both consume `toolDescriptions` from
+ * `./tool-descriptions.ts`. Each consumer composes its own user-visible string
+ * from the same semantic fragments, so guidance lands in both surfaces at
+ * once and a downstream test asserts the shared summary appears in every
+ * consumer description.
  *
  * Usage with Claude:
  *   const response = await anthropic.messages.create({
@@ -786,6 +889,105 @@ declare function addressFromKey(privateKey: string): string;
  */
 declare function verifySignature(hash: string, signature: string, expectedAddress: string): boolean;
 
+/**
+ * Shared semantic descriptions for Haven agent payment tools.
+ *
+ * Two surfaces in this repo expose Haven as a tool: the Claude / OpenAI
+ * function-calling tool definitions in `tools.ts` (used for direct SDK
+ * integrations) and the MCP server in `packages/mcp` (used by any MCP-speaking
+ * agent runtime). The two surfaces use different tool *names* — the SDK's
+ * tools are tuned for tool-calling conventions (`make_payment`,
+ * `authorize_x402_payment`); the MCP tools follow the MCP `haven_*` naming
+ * (`haven_pay_x402_quote`).
+ *
+ * The underlying *operations* are the same, so the descriptive prose should
+ * live in one place. Both surfaces import from this module and compose their
+ * own tool descriptions from these semantic fragments. Drift is caught by
+ * tests asserting each consumer's description string contains the shared
+ * `summary` from this module.
+ */
+interface ToolDescription {
+    /** One-line summary of the operation. Used as the first sentence of every
+     * downstream description and as a stable substring for drift tests. */
+    summary: string;
+    /** Natural-language user intents that should make an agent prefer this
+     * tool over adjacent tools. Empty or omitted when the summary is enough. */
+    selectionGuidance?: string;
+    /** Concrete behaviour the tool performs end-to-end, including which
+     * non-custodial guarantee applies. */
+    behavior: string;
+    /** What the agent should do next on error / pending-approval states.
+     * Empty string if not applicable. */
+    nextActionGuidance: string;
+}
+/**
+ * Build a single description string from the three fragments. Joined with
+ * spaces so consumers can split on the summary substring if they need to.
+ */
+declare function composeDescription(d: ToolDescription): string;
+declare const toolDescriptions: {
+    readonly quoteX402: {
+        readonly summary: "Inspect an HTTP 402 x402 paid resource without creating a Haven payment, signature, approval, or on-chain transaction.";
+        readonly behavior: "Probes the merchant directly and parses the 402 response. Pure read-only client behavior — Haven is not contacted.";
+        readonly nextActionGuidance: "";
+    };
+    readonly payX402: {
+        readonly summary: "Pay an inspected x402 quote. The delegate key signs locally; Haven only validates and relays signed, on-chain-constrained payment transactions.";
+        readonly selectionGuidance: "Do not use this for read-only allowance, budget, spend-limit, remaining-amount, reset-period, or what-can-I-spend questions; use the allowance lookup tool instead.";
+        readonly behavior: "Signs the EIP-3009 payment from the delegate wallet, asks Haven for a Safe AllowanceModule top-up if needed, and returns the merchant response or a pending-approval state.";
+        readonly nextActionGuidance: "If approval is needed, preserve the returned resume_state and wait for nextAction=retry_original_x402_request before resuming.";
+    };
+    readonly resumeX402: {
+        readonly summary: "Resume an x402 payment after the Haven wallet owner approved the funding step.";
+        readonly behavior: "Accepts either resume_state or payment_id, validates the original x402 details against the approved Haven funding, and retries the merchant request with the X-PAYMENT header. No new Haven approval is created.";
+        readonly nextActionGuidance: "Only use when get_payment_status returns nextAction=retry_original_x402_request; do not start a new merchant session.";
+    };
+    readonly quoteMpp: {
+        readonly summary: "Inspect a Haven MPP challenge or paid MPP URL without creating a Haven payment, signature, approval, or on-chain transaction.";
+        readonly behavior: "Parses an MPP challenge envelope and returns a typed quote with rail tag, amount, asset, and merchant context. Pure read-only — Haven is not contacted.";
+        readonly nextActionGuidance: "";
+    };
+    readonly payMpp: {
+        readonly summary: "Pay an inspected MPP challenge. The delegate key signs locally; Haven only validates and relays signed, on-chain-constrained payment transactions.";
+        readonly selectionGuidance: "Do not use this for read-only allowance, budget, spend-limit, remaining-amount, reset-period, or what-can-I-spend questions; use the allowance lookup tool instead.";
+        readonly behavior: "Authorizes the payment through Haven within the on-chain allowance, signs the challenge proof, and returns the proof header for retrying the original paid resource.";
+        readonly nextActionGuidance: "If approval is needed, preserve resume_state or payment_id and wait for nextAction=retry_original_x402_request before resuming.";
+    };
+    readonly resumeMpp: {
+        readonly summary: "Resume an MPP payment after the Haven wallet owner approved the funding step.";
+        readonly behavior: "Accepts either resume_state or payment_id and retries the original paid resource with the MPP proof header. No new Haven approval is created.";
+        readonly nextActionGuidance: "";
+    };
+    readonly getPaymentStatus: {
+        readonly summary: "Fetch structured Haven payment status, including phase and nextAction taxonomy for agent recovery.";
+        readonly behavior: "Accepts a payment intent or approval request id and returns the full state taxonomy (phase, nextAction, rail, amount, merchant, resource url, idempotency key, message).";
+        readonly nextActionGuidance: "";
+    };
+    readonly getResumeState: {
+        readonly summary: "Rehydrate stored x402 or MPP resume_state by payment_id.";
+        readonly behavior: "Returns the context that the agent originally received in a pending-approval response, reconstructed from Haven's database. This is context only; signing still happens locally when a resume tool is called.";
+        readonly nextActionGuidance: "";
+    };
+    readonly getAgent: {
+        readonly summary: "Return the authenticated agent identity, Haven wallet, delegate address, chain, and status.";
+        readonly behavior: "Read-only identity lookup. Useful for verifying which on-chain Safe and delegate the credential is bound to.";
+        readonly nextActionGuidance: "";
+    };
+    readonly getAllowances: {
+        readonly summary: "Return configured and on-chain allowance state for the authenticated agent. On-chain allowance is the real spend gate.";
+        readonly selectionGuidance: "Use this when the user asks about allowance, budget, spend limit, remaining amount, remaining allowance, remaining budget, daily limit, reset period, what can I spend, or what the agent can still spend.";
+        readonly behavior: "Reads the Safe AllowanceModule snapshot per token (allowance, spent, remaining, reset window). Configured amounts from Haven are returned alongside the on-chain truth.";
+        readonly nextActionGuidance: "";
+    };
+    readonly listReceipts: {
+        readonly summary: "List recent machine-payment receipts and evidence for bookkeeping.";
+        readonly selectionGuidance: "Use this for transaction history, receipts, payment evidence, or bookkeeping; use the allowance tool instead for remaining allowance, budget, spend-limit, or what-can-I-spend questions.";
+        readonly behavior: "Returns the agent's recent machine-payment receipts ordered by recency. Proof header values are not returned.";
+        readonly nextActionGuidance: "";
+    };
+};
+type SharedToolKey = keyof typeof toolDescriptions;
+
 /**
  * x402 protocol support for the Haven SDK.
  *
@@ -824,6 +1026,15 @@ declare function parsePaymentRequiredResponse(response: Response): Promise<X402P
  * 3. null — no compatible option
  */
 declare function selectPaymentOption(accepts: X402PaymentOption[]): X402PaymentOption | 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.
+ */
+declare function selectStandardPaymentOption(accepts: X402PaymentOption[]): X402PaymentOption | null;
+declare function x402AuthorizationAmount(option: X402PaymentOption): string;
+declare function buildX402ExpectedMessage(context: X402ExpectedContext): string;
+declare function toStandardPaymentRequirements(paymentRequired: X402PaymentRequired, option: X402PaymentOption): PaymentRequirements;
 /**
  * Encode a payment receipt as a base64 PAYMENT-SIGNATURE header value.
  *
@@ -847,4 +1058,4 @@ declare function parseMachinePaymentChallengeResponse(response: Response): Promi
 declare function buildMachinePaymentIdempotencyKey(challenge: MachinePaymentChallenge): string;
 declare function encodeMachinePaymentProof(receipt: Omit<MachinePaymentReceipt, 'proofHeader'>): string;
 
-export { AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, type AgentPaymentEnumSchema, AgentPaymentNextAction, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, type ClaudeTool, type HavenAgent, type HavenAllowance, type HavenAllowanceSummary, HavenApiError, HavenClient, type HavenClientConfig, HavenError, type HavenPaymentReceipt, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, type MachinePaymentChallenge, type MachinePaymentRail, type MachinePaymentReceipt, type MppAuthorizationOptions, type MppQuote, type MppResumeState, type OpenAITool, type PaymentIntent, type PaymentNextAction, type PaymentPhase, type PaymentRequest, type PaymentResult, type PaymentResumeState, type PaymentStatus, type PaymentStatusResult, type PendingApproval, type ResumeAuthorizedMppInput, type ResumeAuthorizedX402Input, type ResumeMppPaymentInput, type ResumeX402PaymentInput, type SignData, type X402AuthorizationOptions, type X402PaymentOption, type X402PaymentRequired, type X402Quote, type X402Receipt, type X402RequestSnapshot, type X402ResumeState, addressFromKey, buildMachinePaymentIdempotencyKey, encodeMachinePaymentProof, encodePaymentProof, havenTools, parseMachinePaymentChallenge, parseMachinePaymentChallengeResponse, parsePaymentRequired, parsePaymentRequiredResponse, selectPaymentOption, signHash, verifySignature };
+export { AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, type AgentPaymentEnumSchema, AgentPaymentNextAction, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, type ClaudeTool, type HavenAgent, type HavenAllowance, type HavenAllowanceSummary, HavenApiError, HavenClient, type HavenClientConfig, HavenError, type HavenPaymentReceipt, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, type MachinePaymentChallenge, type MachinePaymentRail, type MachinePaymentReceipt, type MppAuthorizationOptions, type MppQuote, type MppResumeState, type OpenAITool, type PaymentIntent, type PaymentNextAction, type PaymentPhase, type PaymentRequest, type PaymentResult, type PaymentResumeState, type PaymentStatus, type PaymentStatusResult, type PendingApproval, type ResumeAuthorizedMppInput, type ResumeAuthorizedX402Input, type ResumeMppPaymentInput, type ResumeX402PaymentInput, type SharedToolKey, type SignData, type ToolDescription, type X402AuthorizationOptions, type X402ExpectedAuth, type X402ExpectedContext, type X402Intent, type X402PaymentOption, type X402PaymentRequired, type X402Quote, type X402Receipt, type X402RequestSnapshot, type X402ResumeState, addressFromKey, buildMachinePaymentIdempotencyKey, buildX402ExpectedMessage, composeDescription, encodeMachinePaymentProof, encodePaymentProof, havenTools, parseMachinePaymentChallenge, parseMachinePaymentChallengeResponse, parsePaymentRequired, parsePaymentRequiredResponse, selectPaymentOption, selectStandardPaymentOption, signHash, toStandardPaymentRequirements, toolDescriptions, verifySignature, x402AuthorizationAmount };