@haven_ai/sdk 0.0.0-dev.202609182134.2018100 → 0.0.0-dev.202609190328.55ffe63

package/README.md

@@ -79,6 +79,7 @@ shows up in your Haven dashboard activity feed.
 - The delegate key signs payment payloads locally. Haven's backend never receives it.
 - The agent's on-chain budget delegation enforces the agent budget: budget, recipient and expiry are checked by audited caveat enforcers at redemption, not by an off-chain rules engine.
 - `getAllowances()` / `get_allowances` is the right path for budget, remaining amount, reset period, or "what can I spend?" questions.
+- `checkFunds()` / `haven_check_funds` answers the different question of whether the account actually holds funds behind the budget — as a sufficiency signal (`covered` true/false/null), never as a balance.
 - 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, a delegation-rail agent is **re-keyed** rather than replaced — same agent, new signing key, budget remainder carried. See [Replacing an agent's signing key](../../docs/product/agent-key-rotation.md).
 

package/dist/index.cjs

@@ -1810,6 +1810,33 @@ var AccountReads = class {
       }))
     };
   }
+  /**
+   * #3126 — the sufficiency signal behind {@link HavenBalanceCoverage}.
+   *
+   * Deliberately NOT a balance read: the endpoint answers whether the
+   * account HOLDS at least the checked amount, as `covered
+   * true/false/null`, and never returns the balance itself. The camelCase
+   * mapping is permissive (raw fields flow through; the server owns the
+   * wire shape, pinned by the backend's `expectMatchesSpec` assertion), so
+   * an older server that has not deployed the endpoint surfaces its 404 as
+   * a thrown error rather than a fabricated answer.
+   */
+  async checkFunds(input) {
+    const query = `token=${encodeURIComponent(input.token)}&amount_atomic=${encodeURIComponent(input.amountAtomic)}`;
+    const raw = await this.transport.get(
+      `/machine-payments/balance-coverage?${query}`
+    );
+    return {
+      covered: raw.covered,
+      ...raw.coverage_error !== void 0 ? { coverageError: raw.coverage_error } : {},
+      chainId: raw.chain_id,
+      tokenAddress: raw.token_address,
+      tokenSymbol: raw.token_symbol,
+      checkedAmountAtomic: raw.checked_amount_atomic,
+      budgetRemainingAtomic: raw.budget_remaining_atomic,
+      ...raw.budget_remaining_is_from_chain !== void 0 ? { budgetRemainingIsFromChain: raw.budget_remaining_is_from_chain } : {}
+    };
+  }
   async getPostPurchaseAllowanceSummary(paymentId) {
     const unavailable = (detail, payment2 = null) => ({
       payment: payment2,
@@ -3541,6 +3568,21 @@ var HavenClient = class {
   async getAllowances() {
     return this.accountReads.getAllowances();
   }
+  /**
+   * #3126 — is the checked amount of the token actually HELD on the
+   * agent's own account?
+   *
+   * This is the companion to {@link getAllowances}, not a variant of it:
+   * allowances answer what the agent is PERMITTED to spend this period;
+   * this answers whether the account HOLDS funds behind that permission,
+   * as a sufficiency signal — `covered: true | false | null` — never as a
+   * balance. `covered: null` means the chain read failed: treat it as
+   * unverifiable, not as absence (`coverageError` says why). The account's
+   * balance itself is deliberately not returned.
+   */
+  async checkFunds(input) {
+    return this.accountReads.checkFunds(input);
+  }
   /**
    * `POST /machine-payments/budget-precheck` (#3054): ask Haven to decide —
    * server-side — whether `amountAtomic` of `token` fits the agent's
@@ -4339,10 +4381,18 @@ var toolDescriptions = {
   },
   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.",
+    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. For whether the account actually HOLDS funds behind the budget use haven_check_funds.",
     behavior: "Returns the per-token spend authority for the account: the active budget delegation (remaining = the period budget, which re-arms natively at the period boundary), each with id, onchain.remaining, remainingDisplay. An over-budget payment is declined before any money moves; nothing queues. Configured amounts from Haven are returned alongside.",
     nextActionGuidance: ""
   },
+  // #3126 — the sufficiency signal, deliberately NOT a balance tool. The
+  // constrained actor reads a boolean, never the treasury total.
+  checkFunds: {
+    summary: "Check whether the agent's account actually holds at least the given amount of a token \u2014 funds held, not spend permitted.",
+    selectionGuidance: "Use this before attempting a payment when it matters whether the money is really there: allowance answers say what you are PERMITTED to spend, never whether the account HOLDS it. For allowance, budget, spend-limit, remaining-budget, reset-period, or what-can-I-spend questions use the allowance lookup tool instead.",
+    behavior: "Returns covered: true (the account holds at least the checked amount), false (a live chain read reports less \u2014 the budget is backed by an empty account; stop and tell the user funds are missing), or null (the chain read failed \u2014 unverifiable, never treat it as absence; coverageError says why). The account balance itself is deliberately not returned: this is a sufficiency signal, not a balance read. budget_remaining_atomic is the permitted figure from the allowance lookup (the SDK spells it budgetRemainingAtomic), named so it can never be confused with holdings.",
+    nextActionGuidance: "On covered=false, do not attempt the payment \u2014 tell the user the account is short and let them fund it; on covered=null, retry the check shortly or proceed knowing the payment may fail on-chain."
+  },
   listReceipts: {
     summary: "List machine-payment receipts, newest first, by page.",
     selectionGuidance: "For transaction history or payment evidence; use the allowance tool instead for remaining allowance or what-can-I-spend questions.",
@@ -4375,13 +4425,13 @@ var toolDescriptions = {
   },
   sweep_delegate: {
     summary: "Sweep stranded USDC and/or ETH from the delegate wallet back to the originating account.",
-    selectionGuidance: "Use this when the user instructs you to recover stranded funds on the delegate wallet, or when a payment status returns nextAction=sweep_stranded_funds. Do NOT use for normal payments \u2014 use haven_pay_x402. Do NOT use to read balances only \u2014 use haven_get_allowances.",
+    selectionGuidance: "Use this when the user instructs you to recover stranded funds on the delegate wallet, or when a payment status returns nextAction=sweep_stranded_funds. Do NOT use for normal payments \u2014 use haven_pay_x402. Do NOT use to read balances only \u2014 use haven_get_allowances, or haven_check_funds for whether the account holds funds.",
     behavior: `Reads the delegate EOA's on-chain USDC and ETH balances. For each non-zero balance, signs and submits a transfer from the delegate EOA to the originating account (hardcoded destination). The delegate key signs locally \u2014 Haven never sees it and the backend never constructs signed transactions (CASP/MiCA Red Line #2). Returns tx hashes and recovered amounts. Returns an empty transfers list when nothing is stranded. Each transfer carries confirmation: "confirmed" (a receipt was seen \u2014 the funds are in the account) or "unconfirmed" (broadcast but not confirmed within 90 seconds \u2014 still in the mempool, may still land). The top-level unconfirmed flag is true when any transfer is unconfirmed.`,
     nextActionGuidance: 'If transfers is non-empty, confirm the amounts with the user. Report a transfer as recovered ONLY when its confirmation is "confirmed". For an "unconfirmed" transfer, tell the user it was submitted but not yet confirmed, give them its txHash and explorerUrl to check, and do not re-run the sweep immediately \u2014 a re-run after it lands will simply find nothing stranded.'
   },
   send: {
     summary: "Send ETH or USDC directly from the agent's Haven wallet to a recipient address.",
-    selectionGuidance: "Use this for plain transfers \u2014 refunding a user, paying a freelancer, topping up a co-agent's wallet, or moving funds between addresses. Do NOT use for x402 paid endpoints \u2014 use haven_pay_x402 instead. Do NOT use for read-only allowance, budget, or what-can-I-spend questions \u2014 use haven_get_allowances.",
+    selectionGuidance: "Use this for plain transfers \u2014 refunding a user, paying a freelancer, topping up a co-agent's wallet, or moving funds between addresses. Do NOT use for x402 paid endpoints \u2014 use haven_pay_x402 instead. Do NOT use for read-only allowance, budget, or what-can-I-spend questions \u2014 use haven_get_allowances. Do NOT use to check whether funds are held before sending \u2014 use haven_check_funds.",
     behavior: "Sends the requested amount by redeeming the agent's on-chain budget delegation, account to recipient with no funding leg. Budget, recipient and expiry are enforced on-chain while the transfer is prepared, so a request outside them is declined before any money moves and before the agent is asked to sign \u2014 it is never queued for a human to approve later. The agent's signing key signs the account's typed data; Haven never receives the key.",
     nextActionGuidance: "On a decline, report the reason to the user and ask them to grant or raise the budget in Haven \u2014 there is nothing to poll and no approval will arrive. After a successful send, poll haven_get_payment_status until nextAction=none."
   },
@@ -4850,6 +4900,13 @@ spending:
   local signer; the signer is verified by calling any signer tool.
 - \`mcp__haven__haven_get_allowances\` \u2014 detailed per-token breakdown
   (configured, spent, reset window) when you need more than the summary.
+- \`mcp__haven__haven_check_funds\` \u2014 whether the account actually HOLDS at
+  least a given amount of a token. Allowance answers above say what you are
+  permitted to spend; this one says whether the money is really there,
+  answered as \`covered\` true/false/null \u2014 never as a balance. On
+  \`covered: false\`, stop and tell the user the account is short; on
+  \`covered: null\` (the chain read failed), treat it as unverifiable rather
+  than as absence.
 
 Budgets reset on a period the user chose. If a payment exceeds the remaining
 budget it is declined before any money moves \u2014 tell the user; they can raise