agent402-client 0.4.2 → 0.5.0

package/README.md

@@ -82,15 +82,45 @@ await a.topSellers({ sort: "calls", include: "all" });
 
 | Method | What |
 |---|---|
-| `new Agent402({ baseUrl?, fetch?, cache?, fetchImpl? })` | `fetch` is your x402-wrapped fetch for paid tools (optional); `cache` (default `true`) memoizes deterministic results |
+| `new Agent402({ baseUrl?, fetch?, cache?, fetchImpl?, maxPerCallUsd?, dailyLimitUsd?, maxPerHostUsd? })` | `fetch` is your x402-wrapped fetch for paid tools (optional); `cache` (default `true`) memoizes deterministic results; the three USD caps set optional spending limits (see below) |
 | `await a.find(task, { k = 5 })` | Resolve a plain-language task to the best-matching tools (route, price, schema, example) |
 | `await a.findWorkflows(task, { k = 2 })` | Resolve a task to matching multi-tool workflow templates (skill packs) |
 | `await a.getWorkflowPrompt(slug, args)` | Fetch the rendered prompt messages for a skill pack with arguments substituted in |
 | `await a.topSellers({ limit?, sort?, include? })` | Live x402 leaderboard: which sellers are settling the most USDC (primarily on Base) in the last ~24h (free, no payment) |
 | `await a.call(slug, params, { idempotencyKey?, cache? })` | Call a tool; auto-pays (PoW for free tools, x402 for wallet-only); returns the JSON result |
 | `Agent402.solvePow(pow)` | Solve a proof-of-work challenge object → an `X-Pow-Solution` value |
+| `a.spendingSummary()` | Rolling-24h paid spend so far: `{ dailyUsd, calls, byHost, limits }` |
 | `a.clearCache()` | Drop the in-memory result cache |
 
+## Spending caps (never overpay)
+
+By default the client pays whatever a tool costs. Set optional hard ceilings and a
+call that would exceed one is **refused before any payment is signed** (it throws
+`SpendingLimitError` — no funds move):
+
+```js
+import { Agent402, SpendingLimitError } from "agent402-client";
+
+const a = new Agent402({
+  fetch: payFetch,
+  maxPerCallUsd: 0.05,   // reject any single call priced above $0.05
+  dailyLimitUsd: 5,      // rolling-24h ceiling across all sellers
+  maxPerHostUsd: 1,      // rolling-24h ceiling per seller host
+});
+
+try {
+  await a.call("some-expensive-tool", { … });
+} catch (e) {
+  if (e instanceof SpendingLimitError) console.log(e.limit, e.priceUsd, e.cap);
+}
+```
+
+Only **settled** paid calls count against the rolling window — a blocked or failed
+call never consumes budget. Free proof-of-work calls are never counted. Omit a cap
+(or leave it `null`) for no limit; with none set, behavior is unchanged. This is a
+buyer-side circuit breaker against a malicious or misconfigured `402` that quotes an
+inflated price.
+
 - **Zero dependencies** for the free/proof-of-work path (uses `node:crypto`).
 - **Non-custodial:** paid settlement is your `@x402/fetch` + wallet; this client never sees your key.
 - MIT licensed. Part of [Agent402](https://github.com/MikeyPetrillo/Agent402).

package/index.js

@@ -23,14 +23,30 @@ export class Agent402 {
    * @param {typeof fetch} [opts.fetch]      an x402-wrapped fetch for wallet-only tools (optional)
    * @param {boolean} [opts.cache=true]      cache results in memory (deterministic tools)
    * @param {typeof fetch} [opts.fetchImpl]  plain fetch (defaults to global fetch)
+   * @param {number} [opts.maxPerCallUsd]    hard ceiling on a single paid call (USD); over → SpendingLimitError before paying
+   * @param {number} [opts.dailyLimitUsd]    hard ceiling on rolling-24h paid spend (USD)
+   * @param {number} [opts.maxPerHostUsd]    hard ceiling on rolling-24h paid spend to one seller host (USD)
    */
-  constructor({ baseUrl = "https://agent402.tools", fetch: payFetch, cache = true, fetchImpl = globalThis.fetch } = {}) {
+  constructor({ baseUrl = "https://agent402.tools", fetch: payFetch, cache = true, fetchImpl = globalThis.fetch,
+    maxPerCallUsd = null, dailyLimitUsd = null, maxPerHostUsd = null } = {}) {
     if (typeof fetchImpl !== "function") throw new Error("No fetch available — pass { fetchImpl } on Node < 18");
     this.baseUrl = String(baseUrl).replace(/\/$/, "");
     this.payFetch = payFetch || null;
     this.f = fetchImpl;
     this._catalog = null;
     this._cache = cache ? new Map() : null;
+    // Spending policy (defends the x402 "wallet drain via uncapped spending"
+    // failure mode): optional hard ceilings enforced BEFORE any payment is
+    // signed. A malicious or misconfigured 402 that quotes an inflated price is
+    // refused instead of paid. null = no limit (default — behavior unchanged).
+    // Amounts commit to the rolling window only on a settled paid call, so a
+    // failed/blocked call never counts against the budget.
+    this._spend = {
+      maxPerCall: numOrNull(maxPerCallUsd),
+      daily: numOrNull(dailyLimitUsd),
+      perHost: numOrNull(maxPerHostUsd),
+      log: [], // [{ ts, host, usd }] — settled paid calls in the last 24h
+    };
   }
 
   async _loadCatalog() {
@@ -167,8 +183,14 @@ export class Agent402 {
     // Wallet-only tool → settle in USDC via the provided x402 fetch.
     if (!tool.computePayable) {
       if (this.payFetch) {
+        // Spending policy: refuse to pay BEFORE signing if the quoted price
+        // breaks a configured ceiling (per-call / rolling-24h / per-host).
+        const usd = parseUsd(tool.price);
+        const host = hostOf(this.baseUrl);
+        this._spendCheck(host, usd, slug);
         const r = await send({}, this.payFetch);
         if (!r.ok) throw new Error(`call "${slug}" failed: HTTP ${r.status}`);
+        this._spendCommit(host, usd); // record spend only once the call actually settled
         return this._store(cacheKey, await r.json(), cache);
       }
       const r = await send(); // no wallet — succeeds only on a FREE_MODE instance
@@ -196,7 +218,72 @@ export class Agent402 {
 
   _store(key, val, cache) { if (this._cache && cache) this._cache.set(key, val); return val; }
   clearCache() { this._cache?.clear(); }
+
+  /** Throw SpendingLimitError if paying `usd` to `host` now would break a cap.
+   *  Prunes the rolling 24h window first; a null cap is unlimited. */
+  _spendCheck(host, usd, slug) {
+    const s = this._spend;
+    if (s.maxPerCall == null && s.daily == null && s.perHost == null) return;
+    if (s.maxPerCall != null && usd > s.maxPerCall) {
+      throw new SpendingLimitError(
+        `refusing to pay $${usd} for "${slug}" — exceeds maxPerCallUsd $${s.maxPerCall}`,
+        { limit: "maxPerCallUsd", slug, priceUsd: usd, cap: s.maxPerCall });
+    }
+    const cutoff = Date.now() - 24 * 60 * 60 * 1000;
+    s.log = s.log.filter((e) => e.ts >= cutoff);
+    if (s.daily != null) {
+      const spent = s.log.reduce((a, e) => a + e.usd, 0);
+      if (spent + usd > s.daily) {
+        throw new SpendingLimitError(
+          `refusing to pay $${usd} for "${slug}" — would bring 24h spend to $${(spent + usd).toFixed(6)}, over dailyLimitUsd $${s.daily}`,
+          { limit: "dailyLimitUsd", slug, priceUsd: usd, spent, cap: s.daily });
+      }
+    }
+    if (s.perHost != null) {
+      const spentHost = s.log.filter((e) => e.host === host).reduce((a, e) => a + e.usd, 0);
+      if (spentHost + usd > s.perHost) {
+        throw new SpendingLimitError(
+          `refusing to pay $${usd} for "${slug}" — would bring 24h spend to ${host} to $${(spentHost + usd).toFixed(6)}, over maxPerHostUsd $${s.perHost}`,
+          { limit: "maxPerHostUsd", slug, host, priceUsd: usd, spent: spentHost, cap: s.perHost });
+      }
+    }
+  }
+
+  /** Record a settled paid call against the rolling budget. */
+  _spendCommit(host, usd) { if (usd > 0) this._spend.log.push({ ts: Date.now(), host, usd }); }
+
+  /** Rolling-24h spend summary (settled paid calls only) — for observability. */
+  spendingSummary() {
+    const cutoff = Date.now() - 24 * 60 * 60 * 1000;
+    const log = this._spend.log.filter((e) => e.ts >= cutoff);
+    const byHost = {};
+    for (const e of log) byHost[e.host] = Number(((byHost[e.host] || 0) + e.usd).toFixed(6));
+    return {
+      dailyUsd: Number(log.reduce((a, e) => a + e.usd, 0).toFixed(6)),
+      calls: log.length,
+      byHost,
+      limits: { maxPerCallUsd: this._spend.maxPerCall, dailyLimitUsd: this._spend.daily, maxPerHostUsd: this._spend.perHost },
+    };
+  }
+}
+
+/** Thrown when a paid call would exceed a configured spending ceiling. The call
+ *  is refused BEFORE any payment is signed, so no funds move. */
+export class SpendingLimitError extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.name = "SpendingLimitError";
+    Object.assign(this, details);
+  }
+}
+
+function numOrNull(v) { if (v == null) return null; const n = Number(v); return Number.isFinite(n) && n >= 0 ? n : null; }
+function parseUsd(price) {
+  if (typeof price === "number") return Number.isFinite(price) ? price : 0;
+  const n = Number(String(price ?? "").replace(/[^0-9.]/g, ""));
+  return Number.isFinite(n) ? n : 0;
 }
+function hostOf(url) { try { return new URL(url).host; } catch { return String(url); } }
 
 /**
  * Restrict + order which chains an @x402 client will pay on (duck-typed — any

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent402-client",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Buyer-side SDK for Agent402.Tools (x402): resolve a task to a tool across 1,350 pay-per-call endpoints and call it with payment handled for you — free tools settle via built-in proof-of-work (no wallet), wallet-only tools via your x402 fetch — with a withNetworkPreference helper to pick the settlement chain (USDC on Base/Solana/Polygon/Arbitrum or USDG on Robinhood Chain). Caching, idempotent retries, cross-seller Smart Order Router.",
   "type": "module",
   "main": "index.js",