@haven_ai/sdk 0.1.4 → 0.1.6

package/README.md

@@ -68,6 +68,15 @@ The agent will pay a tiny amount (~0.01 EURe on Gnosis Chain), receive the demo
 | Gnosis Chain | `eip155:100` | EURe, USDC.e, xDAI |
 | Base | `eip155:8453` | USDC, ETH |
 
+## Credential Lifecycle
+
+- The Haven API key identifies the agent. It is not payment authority.
+- The delegate key signs payment payloads locally. Haven's backend never receives it.
+- On-chain Safe AllowanceModule state enforces the agent budget.
+- `getAllowances()` / `get_allowances` is the right path for budget, remaining amount, reset period, or "what can I spend?" questions.
+- If an API key is exposed or lost, rotate it from the Haven agent detail page. The new key is shown once and the old key stops working.
+- If a delegate key is exposed or lost, pause or revoke the agent and create a new signing path.
+
 ## Step-by-Step API
 
 For agents that need control over each step (e.g., external signing):
@@ -94,7 +103,7 @@ const result = await haven.waitForConfirmation(intent.paymentId)
 
 Production merchant acceptance, facilitator, settlement, fiat, or acquiring functionality needs separate product and legal review under the repo's [CASP / MiCA guardrails](../../docs/regulatory/casp-risk-guardrails.md). The hosted x402 endpoint is an internal technical demo, not a merchant settlement product.
 
-Haven natively supports the [x402](https://x402.org) payment protocol. When an API returns HTTP 402, the SDK evaluates the challenge against the agent's approved limits, uses the configured delegate key for the required signature, and retries automatically:
+The SDK supports [x402](https://x402.org) client flows. When an API returns HTTP 402, the SDK evaluates the challenge against the agent's approved limits, uses the configured delegate key for the required signature, and retries automatically:
 
 ```typescript
 // Automatic — fetch() intercepts 402, pays, and retries.
@@ -178,8 +187,12 @@ for (const block of response.content) {
 |------|-------------|
 | `make_payment` | Request and sign a payment from the user-controlled Safe within approved limits |
 | `get_payment_status` | Check the status of a payment intent or approval request |
+| `get_allowances` | Read configured and on-chain allowance state, including spent and remaining allowance |
 | `authorize_x402_payment` | Authorize a policy-limited x402 payment and return a payment header for an HTTP 402 resource |
 | `resume_x402_payment` | Resume an approved x402 payment and return a merchant payment header without creating a duplicate approval |
+| `authorize_machine_payment` | Authorize an internal Haven MPP demo challenge and return proof details |
+
+Use `get_allowances` for allowance, budget, spend-limit, remaining amount, reset-period, or "what can I spend?" questions. Payment tools still require the agent-held delegate key and on-chain Safe allowance state; the Haven API key identifies the agent but does not authorize spending by itself.
 
 ## Configuration
 
@@ -214,7 +227,7 @@ Every payment or approval state returned by Haven includes:
 
 - `phase`: where the Haven-side payment currently is.
 - `nextAction`: the stable action an agent should take next.
-- `rail`: which payment rail produced the state, such as `direct`, `x402`, or `mpp`.
+- `rail`: which payment rail produced the state. Categorical values (`direct`, `x402`, `mpp`) appear on resume-state discriminators; granular values (`mpp_demo`, `mpp_crypto`, `stripe_deposit`, `spt`) appear on response bodies.
 - `message`: human-readable guidance for the same state.
 
 The enum values and JSON Schema fragments are exported from `@haven_ai/sdk`:
@@ -230,22 +243,74 @@ import {
 } from '@haven_ai/sdk'
 ```
 
+### Flow diagram
+
 ```text
-agent_signature_required -> payment_submitted -> payment_confirmed
-                              |
-                              v
-user_approval_required -> user_execution_required -> funding_sent
-                              |
-                              v
-             waiting_for_additional_approvals
+                                ┌─────────────────────────┐
+                                │ agent_signature_required│
+                                └──────────┬──────────────┘
+                                           │  sign_and_submit_payment
+                                           ▼
+                                ┌─────────────────────────┐
+                                │ payment_submitted       │
+                                └──────────┬──────────────┘
+                                           │  check_status_later
+                                ┌──────────┴──────────────┐
+                                ▼                         ▼
+                  ┌────────────────────────┐  ┌──────────────────────┐
+                  │ payment_confirmed (✔)  │  │ user_approval_required│
+                  └────────────────────────┘  └──────────┬───────────┘
+                                                         │ wait_for_user_approval
+                                       ┌─────────────────┴───────────────────┐
+                                       │ single-owner Safe                   │ multisig Safe
+                                       ▼                                     ▼
+                          ┌──────────────────────────┐    ┌──────────────────────────────────┐
+                          │ user_execution_required  │    │ waiting_for_additional_approvals │
+                          └──────────┬───────────────┘    └────────────────┬─────────────────┘
+                                     │ wait_for_user_to_complete_payment   │ wait_for_user_approval
+                                     └─────────────────┬───────────────────┘
+                                                       ▼
+                                          ┌───────────────────────┐
+                                          │ funding_sent          │
+                                          └──────────┬────────────┘
+                                                     │ retry_original_x402_request (x402)
+                                                     │ none (direct)
+                                                     ▼
+                                          ┌───────────────────────┐
+                                          │ executed (✔)          │
+                                          └───────────────────────┘
+
+Terminal from any non-confirmed phase:
+   rejected → stop_and_tell_user
+   failed   → stop_and_tell_user
+   expired  → request_again_if_user_still_wants_it
 ```
 
+### `phase` reference
+
+| `phase` | Meaning | Terminal? |
+|---------|---------|-----------|
+| `agent_signature_required` | Haven prepared a payment intent; the agent must sign and submit. | no |
+| `payment_submitted` | Haven received the signed payment; the agent should poll for confirmation. | no |
+| `payment_confirmed` | Direct payment is confirmed on chain. | yes |
+| `user_approval_required` | Payment exceeds remaining on-chain allowance; wallet owner must approve in Haven. | no |
+| `user_execution_required` | Owner approved; the funding payment has not been sent yet (single-owner Safe). | no |
+| `waiting_for_additional_approvals` | Funding payment was proposed and is waiting for the remaining multisig approvals. | no |
+| `funding_sent` | Haven funding leg landed; the agent can continue the merchant/protocol leg. | no |
+| `rejected` | Owner rejected the request. | yes |
+| `expired` | Payment or approval request expired before completion. | yes |
+| `failed` | Haven could not complete the payment. | yes |
+
+The merchant settlement leg of x402 (and the MPP retry) is the agent's own request to the merchant — it does not have a Haven `phase`. The payment is `funding_sent` until the agent retries with `X-PAYMENT` (x402) or the MPP proof header; from Haven's perspective the payment becomes `executed` only after the agent successfully resumes.
+
+### `nextAction` reference
+
 | `nextAction` | What the agent should do |
 |--------------|--------------------------|
 | `sign_and_submit_payment` | Sign with the delegate key and submit the payment to Haven. |
 | `check_status_later` | Poll `getPaymentStatus(payment_id)` later. |
 | `none` | Stop polling; no more action is needed for this payment id. |
-| `wait_for_user_approval` | Tell the user the payment is waiting in Haven, then poll later. Do not create a duplicate payment. |
+| `wait_for_user_approval` | Tell the user the payment is waiting in Haven, then poll later. Do not create a duplicate payment. Same `nextAction` covers both the single-owner case (waiting for one owner to approve) and the multisig case (waiting for additional approvals after the first one). |
 | `wait_for_user_to_complete_payment` | The user approved the request; wait for them to finish the funding payment. |
 | `retry_original_x402_request` | Resume this payment id and retry the original x402 request with the merchant payment header. Do not start a new merchant session. |
 | `stop_and_tell_user` | Stop retrying and tell the user the payment failed or was rejected. |

package/dist/index.cjs

@@ -54,8 +54,16 @@ var AgentPaymentRail = {
   Direct: "direct",
   /** x402 HTTP 402 payment flow with a Haven funding leg and merchant retry leg. */
   X402: "x402",
-  /** Machine Payment Protocol flow. */
-  Mpp: "mpp"
+  /** Machine Payment Protocol family — categorical value used as a resume-state discriminator. */
+  Mpp: "mpp",
+  /** Haven internal MPP demo rail. Not for production traffic. */
+  MppDemo: "mpp_demo",
+  /** Crypto-settled MPP rail. */
+  MppCrypto: "mpp_crypto",
+  /** Stripe-deposit-backed MPP rail. */
+  StripeDeposit: "stripe_deposit",
+  /** Stripe Payment Token MPP rail. */
+  Spt: "spt"
 };
 var AGENT_PAYMENT_PHASE_VALUES = Object.values(AgentPaymentPhase);
 var AGENT_PAYMENT_NEXT_ACTION_VALUES = Object.values(AgentPaymentNextAction);
@@ -85,7 +93,11 @@ var AgentPaymentNextActionDescriptions = {
 var AgentPaymentRailDescriptions = {
   [AgentPaymentRail.Direct]: "Standard Haven payment from the user-controlled Safe through an approved delegate allowance.",
   [AgentPaymentRail.X402]: "x402 HTTP 402 payment flow with a Haven funding leg and merchant retry leg.",
-  [AgentPaymentRail.Mpp]: "Machine Payment Protocol flow."
+  [AgentPaymentRail.Mpp]: "Categorical MPP rail value used as a resume-state discriminator. Response bodies carry a granular mpp_* value instead.",
+  [AgentPaymentRail.MppDemo]: "Haven internal MPP demo rail. Not for production traffic.",
+  [AgentPaymentRail.MppCrypto]: "Crypto-settled MPP rail.",
+  [AgentPaymentRail.StripeDeposit]: "Stripe-deposit-backed MPP rail.",
+  [AgentPaymentRail.Spt]: "Stripe Payment Token MPP rail."
 };
 var AgentPaymentPhaseSchema = {
   type: "string",
@@ -325,6 +337,23 @@ function selectStandardPaymentOption(accepts) {
   }
   return null;
 }
+function x402AuthorizationAmount(option) {
+  return option.maxAmountRequired ?? option.amount;
+}
+function buildX402ExpectedMessage(context) {
+  return `Haven x402 expected context v1
+${stableStringify({
+    version: 1,
+    kind: "haven.x402.expected",
+    paymentId: context.paymentId,
+    payloadHash: context.payloadHash.toLowerCase(),
+    resourceUrl: context.resourceUrl,
+    merchantTo: context.merchantTo.toLowerCase(),
+    amount: context.amount,
+    asset: context.asset.toLowerCase(),
+    network: context.network
+  })}`;
+}
 function toStandardPaymentRequirements(paymentRequired, option) {
   const network = STANDARD_X402_NETWORKS[option.network];
   if (!network) {
@@ -336,7 +365,7 @@ function toStandardPaymentRequirements(paymentRequired, option) {
   return {
     scheme: "exact",
     network,
-    maxAmountRequired: option.maxAmountRequired ?? option.amount,
+    maxAmountRequired: x402AuthorizationAmount(option),
     resource: option.resource ?? paymentRequired.resource.url,
     description: option.description ?? paymentRequired.resource.description ?? "Haven x402 payment",
     mimeType: option.mimeType ?? paymentRequired.resource.mimeType ?? "application/octet-stream",
@@ -353,7 +382,7 @@ function buildX402IdempotencyKey(paymentRequired, option, now = Date.now()) {
     paymentRequired.resource.description ?? "",
     option.payTo.toLowerCase(),
     option.asset.toLowerCase(),
-    option.amount,
+    x402AuthorizationAmount(option),
     option.network,
     bucket
   ].join("|");
@@ -382,6 +411,15 @@ function resolveTokenFromAddress(address, network) {
   }
   return ALL_TOKENS[lower] ?? null;
 }
+function stableStringify(value) {
+  if (value === null || typeof value !== "object") {
+    const primitive = JSON.stringify(value);
+    return primitive === void 0 ? "undefined" : primitive;
+  }
+  if (Array.isArray(value)) return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+  const object = value;
+  return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(object[key])}`).join(",")}}`;
+}
 function decodeBase64Json2(value, label) {
   try {
     return JSON.parse(atob(value));
@@ -659,6 +697,70 @@ var HavenClient = class {
       signData: raw.sign_data
     };
   }
+  /**
+   * Keyless x402 construct.
+   *
+   * The non-custodial half of an x402 payment: posts the funding request to
+   * `/x402` and returns the unsigned funding hash plus the data the caller
+   * needs to build and sign the EIP-3009 merchant header itself. Crucially it
+   * does **not** sign — neither the funding hash nor the merchant header — so
+   * it works without a `delegateKey`. Both delegate signatures happen on the
+   * machine that holds the key (the edge); the hosted MCP server relays only.
+   *
+   * Use this from the hosted, keyless server. The all-in-one `authorizeX402`
+   * remains for local clients that hold the key.
+   *
+   * Throws (via the shared payment-state path) when the amount exceeds the
+   * on-chain allowance — there is nothing to sign until the user approves.
+   */
+  async createX402Intent(paymentRequired, options = {}) {
+    const option = selectStandardPaymentOption(paymentRequired.accepts);
+    if (!option) {
+      throw new HavenApiError(
+        "No compatible payment option found in x402 requirements. Haven supports standard x402 exact payments on Base USDC.",
+        400
+      );
+    }
+    const agent = await this.getAgent();
+    const fundingTo = agent.delegateAddress;
+    if (!fundingTo) {
+      throw new HavenApiError("Authenticated agent has no delegate address registered.", 502);
+    }
+    const idempotencyKey = options.idempotencyKey ?? buildX402IdempotencyKey(paymentRequired, option);
+    const raw = await this.post("/x402", {
+      url: paymentRequired.resource.url,
+      payTo: fundingTo,
+      merchantPayTo: option.payTo,
+      amount: x402AuthorizationAmount(option),
+      asset: option.asset,
+      network: option.network,
+      description: paymentRequired.resource.description,
+      idempotencyKey
+    });
+    if (raw.status !== "pending_signature") {
+      this.throwPaymentStateError("x402 payment", raw);
+    }
+    if (!raw.sign_data?.hash) {
+      throw new HavenApiError("No sign_hash returned from x402/authorize", 500, raw);
+    }
+    if (!raw.x402_expected_auth) {
+      throw new HavenApiError("No x402 expected-context binding returned from x402/authorize", 500, raw);
+    }
+    return {
+      paymentId: raw.payment_id,
+      status: "pending_signature",
+      expiresAt: raw.expires_at,
+      signData: raw.sign_data,
+      accepted: option,
+      resourceUrl: paymentRequired.resource.url,
+      merchantTo: raw.merchant_to ?? option.payTo,
+      amountAtomic: x402AuthorizationAmount(option),
+      asset: option.asset,
+      network: option.network,
+      expectedAuth: raw.x402_expected_auth,
+      fundingTo
+    };
+  }
   /**
    * Step 2: Sign a hash with the delegate key.
    *
@@ -882,7 +984,7 @@ var HavenClient = class {
       url: paymentRequired.resource.url,
       payTo: this.delegateAddress,
       merchantPayTo: option.payTo,
-      amount: option.amount,
+      amount: x402AuthorizationAmount(option),
       asset: option.asset,
       network: option.network,
       description: paymentRequired.resource.description,
@@ -1076,7 +1178,7 @@ var HavenClient = class {
       ...initialInit,
       headers: retryHeaders
     });
-    if (retryResponse.status === 402) {
+    if (!retryResponse.ok) {
       await this.recordMerchantRetryRejected({
         rail: "x402",
         paymentId: receipt.paymentId,
@@ -1089,8 +1191,8 @@ var HavenClient = class {
         }
       });
       throw new HavenApiError(
-        "x402 retry was rejected after Haven funded the delegate wallet; reconciliation may be required.",
-        402,
+        "x402 retry failed after Haven funded the delegate wallet; reconciliation may be required.",
+        retryResponse.status,
         {
           marker: "x402_retry_rejected_after_funding",
           payment_id: receipt.paymentId,
@@ -1229,7 +1331,7 @@ var HavenClient = class {
       ...initialInit,
       headers: retryHeaders
     });
-    if (retryResponse.status === 402) {
+    if (!retryResponse.ok) {
       await this.recordMerchantRetryRejected({
         rail: receipt.rail,
         paymentId: receipt.paymentId,
@@ -1241,8 +1343,8 @@ var HavenClient = class {
         }
       });
       throw new HavenApiError(
-        "Machine payment retry was rejected after Haven sent the payment.",
-        402,
+        "Machine payment retry failed after Haven sent the payment.",
+        retryResponse.status,
         {
           marker: "machine_payment_retry_rejected_after_payment",
           payment_id: receipt.paymentId,
@@ -1319,7 +1421,7 @@ var HavenClient = class {
       );
     }
     const approvedAmount = status.amount ? normalizeDecimal(status.amount) : "";
-    const requestedAmount = normalizeDecimal(decimalFromUsdcAtomic(option.amount));
+    const requestedAmount = normalizeDecimal(decimalFromUsdcAtomic(x402AuthorizationAmount(option)));
     if (approvedAmount && approvedAmount !== requestedAmount) {
       throw new HavenApiError(
         "x402 resume request does not match the approved amount.",
@@ -1395,7 +1497,7 @@ var HavenClient = class {
     const txHash = execResult?.tx_hash ?? raw.tx_hash ?? "";
     const chainId = execResult?.chain_id ?? raw.chain_id ?? chainIdFromNetwork(option.network);
     const token = execResult?.token ?? raw.token ?? "USDC";
-    const amount = execResult?.amount ?? raw.amount ?? decimalFromUsdcAtomic(option.amount);
+    const amount = execResult?.amount ?? raw.amount ?? decimalFromUsdcAtomic(x402AuthorizationAmount(option));
     const to = execResult?.to ?? raw.to ?? this.delegateAddress ?? "";
     const explorerUrl = execResult?.explorer_url ?? raw.explorer_url ?? explorerUrlOrEmpty(chainId, txHash);
     const merchantTo = execResult?.merchant_to ?? raw.merchant_to ?? option.payTo;
@@ -1428,7 +1530,7 @@ var HavenClient = class {
       paymentId: status.paymentId,
       txHash: status.txHash,
       token: status.token || "USDC",
-      amount: status.amount || decimalFromUsdcAtomic(option.amount),
+      amount: status.amount || decimalFromUsdcAtomic(x402AuthorizationAmount(option)),
       to: this.delegateAddress ?? "",
       resourceUrl: paymentRequired.resource.url,
       explorerUrl: explorerUrlOrEmpty(status.chainId, status.txHash),
@@ -1464,7 +1566,7 @@ var HavenClient = class {
         payTo: input.merchantTo ?? input.accepted.payTo
       },
       x402: {
-        amount: input.accepted.amount,
+        amount: x402AuthorizationAmount(input.accepted),
         token: input.token,
         network: input.accepted.network,
         asset: input.accepted.asset,
@@ -1714,8 +1816,8 @@ var HavenClient = class {
       resourceUrl: paymentRequired.resource.url,
       description: paymentRequired.resource.description ?? option.description ?? null,
       mimeType: paymentRequired.resource.mimeType ?? option.mimeType ?? null,
-      amountAtomic: option.amount,
-      amount: decimalFromUsdcAtomic(option.amount),
+      amountAtomic: x402AuthorizationAmount(option),
+      amount: decimalFromUsdcAtomic(x402AuthorizationAmount(option)),
       token: token?.symbol ?? "USDC",
       asset: option.asset,
       network: option.network,
@@ -1736,8 +1838,8 @@ var HavenClient = class {
       request: input.request,
       resourceUrl: input.paymentRequired.resource.url,
       description: input.paymentRequired.resource.description ?? input.accepted.description ?? null,
-      amountAtomic: input.accepted.amount,
-      amount: decimalFromUsdcAtomic(input.accepted.amount),
+      amountAtomic: x402AuthorizationAmount(input.accepted),
+      amount: decimalFromUsdcAtomic(x402AuthorizationAmount(input.accepted)),
       token: token?.symbol ?? "USDC",
       asset: input.accepted.asset,
       network: input.accepted.network,
@@ -1932,6 +2034,9 @@ var HavenClient = class {
         message: result.message
       };
     }
+    if (toolName === "get_allowances") {
+      return { ...await this.getAllowances() };
+    }
     throw new Error(`Unknown tool: ${toolName}`);
   }
   toolX402PaymentRequired(input) {
@@ -2122,7 +2227,7 @@ var HavenClient = class {
     };
   }
   mapPaymentReceipt(raw) {
-    return {
+    const receipt = {
       id: raw.id,
       paymentId: raw.payment_id,
       rail: raw.rail,
@@ -2149,6 +2254,13 @@ var HavenClient = class {
       createdAt: raw.created_at,
       updatedAt: raw.updated_at
     };
+    if ("payment_intent_id" in raw) {
+      receipt.paymentIntentId = raw.payment_intent_id ?? null;
+    }
+    if ("approval_request_id" in raw) {
+      receipt.approvalRequestId = raw.approval_request_id ?? null;
+    }
+    return receipt;
   }
 };
 function sleep(ms) {
@@ -2189,6 +2301,72 @@ async function responseSnippet(response) {
   }
 }
 
+// src/tool-descriptions.ts
+function composeDescription(d) {
+  return [d.summary, d.selectionGuidance, d.behavior, d.nextActionGuidance].filter(Boolean).join(" ");
+}
+var toolDescriptions = {
+  quoteX402: {
+    summary: "Inspect an HTTP 402 x402 paid resource without creating a Haven payment, signature, approval, or on-chain transaction.",
+    behavior: "Probes the merchant directly and parses the 402 response. Pure read-only client behavior \u2014 Haven is not contacted.",
+    nextActionGuidance: ""
+  },
+  payX402: {
+    summary: "Pay an inspected x402 quote. The delegate key signs locally; Haven only validates and relays signed, on-chain-constrained payment transactions.",
+    selectionGuidance: "Do not use this for read-only allowance, budget, spend-limit, remaining-amount, reset-period, or what-can-I-spend questions; use the allowance lookup tool instead.",
+    behavior: "Signs the EIP-3009 payment from the delegate wallet, asks Haven for a Safe AllowanceModule top-up if needed, and returns the merchant response or a pending-approval state.",
+    nextActionGuidance: "If approval is needed, preserve the returned resume_state and wait for nextAction=retry_original_x402_request before resuming."
+  },
+  resumeX402: {
+    summary: "Resume an x402 payment after the Haven wallet owner approved the funding step.",
+    behavior: "Accepts either resume_state or payment_id, validates the original x402 details against the approved Haven funding, and retries the merchant request with the X-PAYMENT header. No new Haven approval is created.",
+    nextActionGuidance: "Only use when get_payment_status returns nextAction=retry_original_x402_request; do not start a new merchant session."
+  },
+  quoteMpp: {
+    summary: "Inspect a Haven MPP challenge or paid MPP URL without creating a Haven payment, signature, approval, or on-chain transaction.",
+    behavior: "Parses an MPP challenge envelope and returns a typed quote with rail tag, amount, asset, and merchant context. Pure read-only \u2014 Haven is not contacted.",
+    nextActionGuidance: ""
+  },
+  payMpp: {
+    summary: "Pay an inspected MPP challenge. The delegate key signs locally; Haven only validates and relays signed, on-chain-constrained payment transactions.",
+    selectionGuidance: "Do not use this for read-only allowance, budget, spend-limit, remaining-amount, reset-period, or what-can-I-spend questions; use the allowance lookup tool instead.",
+    behavior: "Authorizes the payment through Haven within the on-chain allowance, signs the challenge proof, and returns the proof header for retrying the original paid resource.",
+    nextActionGuidance: "If approval is needed, preserve resume_state or payment_id and wait for nextAction=retry_original_x402_request before resuming."
+  },
+  resumeMpp: {
+    summary: "Resume an MPP payment after the Haven wallet owner approved the funding step.",
+    behavior: "Accepts either resume_state or payment_id and retries the original paid resource with the MPP proof header. No new Haven approval is created.",
+    nextActionGuidance: ""
+  },
+  getPaymentStatus: {
+    summary: "Fetch structured Haven payment status, including phase and nextAction taxonomy for agent recovery.",
+    behavior: "Accepts a payment intent or approval request id and returns the full state taxonomy (phase, nextAction, rail, amount, merchant, resource url, idempotency key, message).",
+    nextActionGuidance: ""
+  },
+  getResumeState: {
+    summary: "Rehydrate stored x402 or MPP resume_state by payment_id.",
+    behavior: "Returns the context that the agent originally received in a pending-approval response, reconstructed from Haven's database. This is context only; signing still happens locally when a resume tool is called.",
+    nextActionGuidance: ""
+  },
+  getAgent: {
+    summary: "Return the authenticated agent identity, Haven wallet, delegate address, chain, and status.",
+    behavior: "Read-only identity lookup. Useful for verifying which on-chain Safe and delegate the credential is bound to.",
+    nextActionGuidance: ""
+  },
+  getAllowances: {
+    summary: "Return configured and on-chain allowance state for the authenticated agent. On-chain allowance is the real spend gate.",
+    selectionGuidance: "Use this when the user asks about allowance, budget, spend limit, remaining amount, remaining allowance, remaining budget, daily limit, reset period, what can I spend, or what the agent can still spend.",
+    behavior: "Reads the Safe AllowanceModule snapshot per token (allowance, spent, remaining, reset window). Configured amounts from Haven are returned alongside the on-chain truth.",
+    nextActionGuidance: ""
+  },
+  listReceipts: {
+    summary: "List recent machine-payment receipts and evidence for bookkeeping.",
+    selectionGuidance: "Use this for transaction history, receipts, payment evidence, or bookkeeping; use the allowance tool instead for remaining allowance, budget, spend-limit, or what-can-I-spend questions.",
+    behavior: "Returns the agent's recent machine-payment receipts ordered by recency. Proof header values are not returned.",
+    nextActionGuidance: ""
+  }
+};
+
 // src/tools.ts
 var makePaymentSchema = {
   type: "object",
@@ -2222,6 +2400,11 @@ var getPaymentStatusSchema = {
   },
   required: ["payment_id"]
 };
+var getAllowancesSchema = {
+  type: "object",
+  properties: {},
+  required: []
+};
 var authorizeX402Schema = {
   type: "object",
   properties: {
@@ -2304,11 +2487,12 @@ var authorizeMachinePaymentSchema = {
   },
   required: ["challenge"]
 };
-var MAKE_PAYMENT_DESCRIPTION = "Request and sign a payment from the user-controlled Safe within approved on-chain limits. Haven authenticates the agent, validates the signed intent, and relays the Safe AllowanceModule transaction; it does not hold keys or control funds. Gnosis Chain tokens: EURe, USDC.e, xDAI. Base tokens: USDC, ETH.";
-var GET_STATUS_DESCRIPTION = "Check the status of a previously initiated payment. Accepts payment intent IDs and approval request IDs. Returns the current status, phase, next_action, transaction hash if available, and payment details.";
-var AUTHORIZE_X402_DESCRIPTION = "Authorize payment for an HTTP 402 (Payment Required) response. When a paid API returns x402 payment requirements, use this tool to sign with the agent-owned delegate key and request a policy-limited Safe AllowanceModule top-up when needed. Haven relays signed transactions only; the agent key authorizes payment and on-chain limits enforce spend. If this returns pending_approval, tell the user it is waiting in Haven, preserve the original merchant/MCP session and x402 details, call get_payment_status later, and use resume_x402_payment only when next_action is retry_original_x402_request. Do not start a new merchant session or loop retries while approval is pending. Use the returned payment_header as the X-PAYMENT header on the retry request when doing a manual HTTP retry.";
-var RESUME_X402_DESCRIPTION = "Resume an x402 payment after the user approved it in Haven. Use this only after get_payment_status returns next_action=retry_original_x402_request. It checks the approved payment, validates the original x402 details, and returns a merchant X-PAYMENT header without creating a new approval request or merchant session.";
-var AUTHORIZE_MACHINE_PAYMENT_DESCRIPTION = "Authorize a Haven machine-payment challenge, currently for the internal MPP demo rail. The agent signs the payment, Haven relays it within the on-chain allowance, and the tool returns a proof header for the retry request.";
+var MAKE_PAYMENT_DESCRIPTION = "Request and sign a payment from the user-controlled Safe within approved on-chain limits. For read-only allowance, budget, spend-limit, remaining-amount, or reset-period questions, use get_allowances instead of making a payment. Haven authenticates the agent, validates the signed intent, and relays the Safe AllowanceModule transaction; it does not hold keys or control funds. Gnosis Chain tokens: EURe, USDC.e, xDAI. Base tokens: USDC, ETH.";
+var GET_STATUS_DESCRIPTION = toolDescriptions.getPaymentStatus.summary + " Accepts payment intent IDs and approval request IDs. Returns the current status, phase, next_action, transaction hash if available, and payment details.";
+var GET_ALLOWANCES_DESCRIPTION = composeDescription(toolDescriptions.getAllowances);
+var AUTHORIZE_X402_DESCRIPTION = composeDescription(toolDescriptions.payX402) + " In this SDK tool set, the allowance lookup tool is get_allowances. When a paid API returns x402 payment requirements, use this tool to sign with the agent-owned delegate key and request a policy-limited Safe AllowanceModule top-up when needed. Haven relays signed transactions only; the agent key authorizes payment and on-chain limits enforce spend. If this returns pending_approval, tell the user it is waiting in Haven, preserve the original merchant/MCP session and x402 details, call get_payment_status later, and use resume_x402_payment only when next_action is retry_original_x402_request. Do not start a new merchant session or loop retries while approval is pending. Use the returned payment_header as the X-PAYMENT header on the retry request when doing a manual HTTP retry.";
+var RESUME_X402_DESCRIPTION = toolDescriptions.resumeX402.summary + " Use this only after get_payment_status returns next_action=retry_original_x402_request. It checks the approved payment, validates the original x402 details, and returns a merchant X-PAYMENT header without creating a new approval request or merchant session.";
+var AUTHORIZE_MACHINE_PAYMENT_DESCRIPTION = composeDescription(toolDescriptions.payMpp) + " In this SDK tool set, the allowance lookup tool is get_allowances. Currently scoped to the internal MPP demo rail. The agent signs the payment, Haven relays it within the on-chain allowance, and the tool returns a proof header for the retry request.";
 function claudeTools() {
   return [
     {
@@ -2321,6 +2505,11 @@ function claudeTools() {
       description: GET_STATUS_DESCRIPTION,
       input_schema: getPaymentStatusSchema
     },
+    {
+      name: "get_allowances",
+      description: GET_ALLOWANCES_DESCRIPTION,
+      input_schema: getAllowancesSchema
+    },
     {
       name: "authorize_x402_payment",
       description: AUTHORIZE_X402_DESCRIPTION,
@@ -2356,6 +2545,14 @@ function openaiTools() {
         parameters: getPaymentStatusSchema
       }
     },
+    {
+      type: "function",
+      function: {
+        name: "get_allowances",
+        description: GET_ALLOWANCES_DESCRIPTION,
+        parameters: getAllowancesSchema
+      }
+    },
     {
       type: "function",
       function: {
@@ -2409,6 +2606,8 @@ exports.HavenSigningError = HavenSigningError;
 exports.HavenTimeoutError = HavenTimeoutError;
 exports.addressFromKey = addressFromKey;
 exports.buildMachinePaymentIdempotencyKey = buildMachinePaymentIdempotencyKey;
+exports.buildX402ExpectedMessage = buildX402ExpectedMessage;
+exports.composeDescription = composeDescription;
 exports.encodeMachinePaymentProof = encodeMachinePaymentProof;
 exports.encodePaymentProof = encodePaymentProof;
 exports.havenTools = havenTools;
@@ -2417,7 +2616,11 @@ exports.parseMachinePaymentChallengeResponse = parseMachinePaymentChallengeRespo
 exports.parsePaymentRequired = parsePaymentRequired;
 exports.parsePaymentRequiredResponse = parsePaymentRequiredResponse;
 exports.selectPaymentOption = selectPaymentOption;
+exports.selectStandardPaymentOption = selectStandardPaymentOption;
 exports.signHash = signHash;
+exports.toStandardPaymentRequirements = toStandardPaymentRequirements;
+exports.toolDescriptions = toolDescriptions;
 exports.verifySignature = verifySignature;
+exports.x402AuthorizationAmount = x402AuthorizationAmount;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map