@haven_ai/sdk 0.1.15-alpha.0 → 0.1.17-alpha.0

package/dist/index.cjs

@@ -531,6 +531,7 @@ function stableStringify(value) {
     const primitive = JSON.stringify(value);
     return primitive === void 0 ? "undefined" : primitive;
   }
+  if (value instanceof Date) return JSON.stringify(value.toISOString());
   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(",")}}`;
@@ -632,11 +633,24 @@ var DEFAULT_REQUEST_TIMEOUT = 3e4;
 var DEFAULT_CONFIRMATION_TIMEOUT = 9e4;
 var DEFAULT_POLLING_INTERVAL = 3e3;
 function formatAtomicAmount(atomic, decimals) {
+  if (atomic < 0n) return "0.0";
   const s = atomic.toString().padStart(decimals + 1, "0");
   const intPart = s.slice(0, s.length - decimals) || "0";
   const fracPart = s.slice(s.length - decimals).replace(/0+$/, "") || "0";
   return `${intPart}.${fracPart}`;
 }
+function safeBigInt(value) {
+  try {
+    return BigInt(value);
+  } catch {
+    return 0n;
+  }
+}
+function deriveReadiness(status, allowances) {
+  if (status !== "active") return "revoked";
+  const hasSpendable = allowances.some((a) => safeBigInt(a.remainingAtomic) > 0n);
+  return hasSpendable ? "ready" : "needs_approval";
+}
 var MCP_PROTOCOL_VERSION = "2025-06-18";
 var MCP_ACCEPT = "application/json, text/event-stream";
 var MCP_CLIENT_INFO = { name: "haven-sdk", version: "1" };
@@ -1003,6 +1017,32 @@ var HavenClient = class {
       chainId: raw.chain_id
     };
   }
+  /**
+   * One-shot "am I ready?" bootstrap: identity + live spend authority + a
+   * readiness signal, in a single call. Folds {@link getAgent} and
+   * {@link getAllowances} together and derives a {@link HavenAgentReadiness}
+   * so an agent can answer "who am I and can I pay right now" at session start
+   * without two round trips and manual assembly.
+   */
+  async getAgentSummary() {
+    const [agent, allowanceSummary] = await Promise.all([
+      this.getAgent(),
+      this.getAllowances()
+    ]);
+    const allowances = allowanceSummary.allowances.map((a) => {
+      const token = resolveTokenFromAddress(a.tokenAddress);
+      const remainingDisplay = token ? `${formatAtomicAmount(safeBigInt(a.onchain.remaining), token.decimals)} ${a.tokenSymbol}` : `${a.onchain.remaining} ${a.tokenSymbol} (atomic; unknown decimals)`;
+      return {
+        tokenSymbol: a.tokenSymbol,
+        remainingAtomic: a.onchain.remaining,
+        remainingDisplay,
+        configuredAmount: a.configuredAmount,
+        resetPeriodMin: a.resetPeriodMin,
+        isResetPending: a.onchain.isResetPending
+      };
+    });
+    return { ...agent, readiness: deriveReadiness(agent.status, allowances), allowances };
+  }
   /**
    * Sweep stranded USDC and ETH from the delegate EOA back to the originating Safe.
    *
@@ -1686,6 +1726,21 @@ var HavenClient = class {
    * accepted), threads the session + wallet headers, sets `X-PAYMENT`, and
    * collapses an SSE JSON-RPC response to its `result`.
    */
+  /**
+   * Wait for a payment's Safe→delegate funding tx to reach ≥1 on-chain
+   * confirmation. The hosted x402 completion path MUST call this after funding
+   * and before delivering the X-PAYMENT header, so the merchant's
+   * balanceOf(delegate) / transferWithAuthorization verification sees the funded
+   * balance — otherwise it rejects with "Payment verification failed". The
+   * SDK's local path already does this (see authorizeStandardX402); the hosted
+   * split flow regressed when the 5→3 collapse removed the incidental
+   * inter-call latency that used to mask it. No-op when the funding tx hash or
+   * a chain RPC (chainRpcs[chainId]) is unavailable.
+   */
+  async ensureFundingConfirmed(paymentId, fundingTxHash) {
+    const status = await this.getPaymentStatus(paymentId);
+    await this.waitForFundingTx(fundingTxHash ?? status.txHash ?? void 0, status.chainId);
+  }
   async completeX402MerchantCall(input) {
     const evidenceContext = await this.resolveX402MerchantCompletionContext({
       paymentId: input.paymentId,
@@ -2961,8 +3016,9 @@ var toolDescriptions = {
     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.",
+    summary: "Return the authenticated agent identity AND its live spend authority in one call: Haven wallet, delegate, chain, raw status, a readiness signal, and per-token remaining allowance (atomic + human-readable). The recommended first call in a new session to confirm who you are and whether you can pay right now.",
+    selectionGuidance: "Use this as the one-shot orientation/bootstrap at the start of a session, or whenever you need to confirm identity together with whether the agent can spend right now. For a detailed per-token breakdown (configured vs spent vs reset window) use haven_get_allowances.",
+    behavior: 'Reads identity plus the on-chain AllowanceModule snapshot in one shot. readiness is "ready" when at least one token has remaining on-chain allowance, "needs_approval" when the agent is active but has no remaining allowance to auto-spend (payments will be queued for the wallet owner to approve in Haven), and "revoked" when the credential is not active. allowances[] carries remainingAtomic and remainingDisplay per token. Identity fields (id, name, status, safeAddress, delegateAddress, chainId) are unchanged from before.',
     nextActionGuidance: ""
   },
   getAllowances: {
@@ -3263,12 +3319,28 @@ the \`mcp__haven-signer__\` namespace and keep the delegate key on this machine.
 - A request returns HTTP 402 (x402): use the Haven pay tools to settle it,
   then retry the original request.
 
-## Identity and budget come from the tools \u2014 never assume them
+## Identity and budget
+
+Do not guess the wallet address, network, or budget.
+
+For instant orientation at the start of a session, read the non-secret
+\`agent.json\` the connector wrote to your Haven credential directory (typically
+\`~/.haven/agents/<agent-id>/agent.json\` \u2014 if you don't know the agent id, list
+\`~/.haven/agents/\` to find the folder). It
+holds your agent id, Haven wallet address, network, and *configured* per-token
+budget, and contains no keys \u2014 the fastest way to answer "who am I and what may
+I spend" with no round trip. If that file is absent (some setups don't write
+it), use the tools below instead.
 
-Do not guess the wallet address, network, or budget. Read them live:
+Before any payment, confirm the *live remaining* budget with the tools \u2014
+\`agent.json\` shows the configured budget, not what is left after recent
+spending:
 
-- \`haven_get_agent\` \u2014 agent identity, Haven wallet address, network.
-- \`haven_get_allowances\` \u2014 current per-token budgets and what remains.
+- \`haven_get_agent\` \u2014 the recommended first call: identity (wallet, network)
+  plus a readiness signal (\`ready\` / \`needs_approval\` / \`revoked\`) and live
+  remaining per-token allowance, in one shot.
+- \`haven_get_allowances\` \u2014 detailed per-token breakdown (configured, spent,
+  reset window) when you need more than the summary.
 
 Budgets reset on a period the user chose. If a payment exceeds the remaining
 budget it is queued for the user to approve in the Haven dashboard \u2014 this is