agent402-client 0.7.0 → 0.8.1

package/README.md

@@ -23,7 +23,7 @@ const a = new Agent402();                       // → https://agent402.tools
 
 // Don't know the slug? Resolve a task in one call.
 const matches = await a.find("extract the article from a url");
-// → [{ slug: "extract", route, price, inputSchema, example, … }]
+// → [{ slug: "extract", route, price, inputSchema, example, ... }]
 
 // Call it - proof-of-work is solved automatically for free tools.
 const out = await a.call("hash", { text: "hello world", algo: "sha256" });
@@ -101,7 +101,7 @@ same id is a new payment).
 ## Workflows (skill packs)
 
 For jobs that no single tool covers - e.g. "audit a domain", "build a stock
-brief" - Agent402 ships curated multi-tool **skill packs**: 5–7 catalog tools
+brief" - Agent402 ships curated multi-tool **skill packs**: 5-7 catalog tools
 composed into a Claude-ready task template. Discover them the same way you'd
 discover a tool:
 
@@ -114,6 +114,38 @@ const { messages } = await a.getWorkflowPrompt("security-audit", { domain: "stri
 // → feed messages straight to any LLM
 ```
 
+## Cross-seller routing (neutral Smart Order Router)
+
+`find()` searches **this host's catalog only**. To rank tools across eligible
+routable seller rows in the host's **current index** (not complete ecosystem
+coverage), use `route()` - free, read-only, no wallet:
+
+```js
+const task = "screenshot webpage";
+const { query, include, results } = await a.route(task, {
+  k: 5,
+  include: "external",   // all | external | local
+  network: "robinhood",  // optional chain filter (short name or CAIP-2)
+});
+// results[]: opaque server rows - { seller, slug, url, priceUsd, executeVia?, ... }
+
+// executeVia quotes which route-execute* tier fits a row's underlying price.
+// It does NOT bind that row: the tier re-resolves an eligible match under its
+// cap at execution time (url, route, seller, and identity can differ).
+const hint = results[0]?.executeVia;
+if (hint?.tool) {
+  const { result, receipt } = await a.call(hint.tool, {
+    task: query,
+    include,
+    params: { url: "https://example.com" },  // inputs the chosen operation needs
+  }, { cache: false });  // routed externals can be dynamic; client cache is on by default
+}
+```
+
+`executeVia` is server-reported metadata only. The SDK passes discovery rows
+through unchanged, does not validate seller output, and does not guarantee
+which seller or tool the execution tier will pick.
+
 ## Discover the live x402 economy
 
 Want to see who's actually getting paid on x402 right now - not just what tools
@@ -133,16 +165,37 @@ await a.topSellers({ sort: "calls", include: "all" });
 
 | Method | What |
 |---|---|
-| `new Agent402({ baseUrl?, fetch?, creditsKey?, cache?, fetchImpl?, maxPerCallUsd?, dailyLimitUsd?, maxPerHostUsd? })` | `fetch` is your x402- or MPP-wrapped fetch for paid tools (optional); `creditsKey` is a prepaid card-credits key (`a402_...`) used for paid tools when no `fetch` is given; `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) |
+| `new Agent402({ baseUrl?, fetch?, creditsKey?, cache?, fetchImpl?, maxPerCallUsd?, dailyLimitUsd?, maxPerHostUsd?, maxResponseBytes? })` | `fetch` is your x402- or MPP-wrapped fetch for paid tools (optional); `creditsKey` is a prepaid card-credits key (`a402_...`) used for paid tools when no `fetch` is given; `cache` (default `true`) memoizes deterministic results; the three USD caps set optional spending limits (see below); `maxResponseBytes` (default 32MB, `null` to disable) refuses an oversized response body before it is parsed |
+| `await a.find(task, { k = 5 })` | Resolve a plain-language task to the best-matching tools on **this host** (route, price, schema, example) |
+| `await a.route(task, { k?, include?, network? })` | Cross-seller Smart Order Router: rank eligible/routable seller rows from the host's current index (free, read-only; opaque results may include server-reported `executeVia`) |
 | `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; your payment `fetch` or the credits key for wallet-only); returns the JSON result |
+| `await a.call(slug, params, { idempotencyKey?, cache?, maxResponseBytes? })` | Call a tool; auto-pays (PoW for free tools; your payment `fetch` or the credits key 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 |
 
+## Response size ceiling
+
+You are calling strangers and paying them, and the seller chooses the response.
+By the time `r.json()` resolves, a multi-gigabyte body is already in your
+agent's memory, so this is one of the few checks that cannot be done after the
+fact in your own code.
+
+Every call is capped at 32MB by default. The declared `content-length` is
+refused before a byte is read, and the stream is counted as it arrives, because
+`content-length` is the seller's claim about their own body.
+
+```js
+const a = new Agent402({ maxResponseBytes: 1_000_000 });   // 1MB everywhere
+await a.call("hash", { text: "x" }, { maxResponseBytes: null });  // or per call
+```
+
+An oversized body throws `ResponseTooLargeError` carrying `size`, `cap`,
+`source` and `paid`. Check `paid`: on a wallet-only tool the money moved before
+the body arrived, so a refused response is still a spend you made.
+
 ## Spending caps (never overpay)
 
 By default the client pays whatever a tool costs. Set optional hard ceilings and a
@@ -160,7 +213,7 @@ const a = new Agent402({
 });
 
 try {
-  await a.call("some-expensive-tool", { … });
+  await a.call("some-expensive-tool", { ... });
 } catch (e) {
   if (e instanceof SpendingLimitError) console.log(e.limit, e.priceUsd, e.cap);
 }

package/index.js

@@ -1,4 +1,4 @@
-// agent402-client — a tiny buyer-side client for agent402.tools (or any Agent402
+// agent402-client - a tiny buyer-side client for agent402.tools (or any Agent402
 // instance). Resolve a task to a tool, then call it with payment handled for you:
 //   - free pure-CPU tools settle with a built-in proof-of-work (no wallet, zero deps),
 //   - wallet-only tools settle via an x402-wrapped fetch you provide (@x402/fetch),
@@ -15,11 +15,16 @@
 import { createHash } from "node:crypto";
 
 // Keep in lockstep with package.json. Every request the SDK issues carries
-// `User-Agent: agent402-client/<version>` — a standard header, no extra
-// network calls — so a seller can attribute traffic (and settled payments)
+// `User-Agent: agent402-client/<version>` - a standard header, no extra
+// network calls - so a seller can attribute traffic (and settled payments)
 // to this SDK. Product token only; nothing about the caller rides along.
 const VERSION = "0.7.0";
 const USER_AGENT = `agent402-client/${VERSION}`;
+// 32MB: about a hundred times any realistic response from this catalog (the
+// largest is a base64 image at a few MB), so it cannot break a legitimate
+// caller, while still stopping the class it exists for. A ceiling that is off
+// by default protects nobody, so this one is on; pass null to disable it.
+const DEFAULT_MAX_RESPONSE_BYTES = 32 * 1024 * 1024;
 
 const leadingZeroBits = (buf) => { let n = 0; for (const b of buf) { if (b === 0) { n += 8; continue; } n += Math.clz32(b) - 24; break; } return n; };
 
@@ -35,11 +40,14 @@ export class Agent402 {
    * @param {number} [opts.maxPerHostUsd]    hard ceiling on rolling-24h paid spend to one seller host (USD)
    * @param {string} [opts.creditsKey]       a prepaid card-credits key (a402_...) from agent402.tools/credits -
    *                                         pays wallet-only tools by card when no payFetch is given
+   * @param {number|null} [opts.maxResponseBytes=33554432]
+   *        Hard ceiling on a response body, enforced BEFORE it is parsed. null disables it.
    */
   constructor({ baseUrl = "https://agent402.tools", fetch: payFetch, cache = true, fetchImpl = globalThis.fetch,
-    maxPerCallUsd = null, dailyLimitUsd = null, maxPerHostUsd = null, creditsKey = null } = {}) {
+    maxPerCallUsd = null, dailyLimitUsd = null, maxPerHostUsd = null, creditsKey = null,
+    maxResponseBytes = DEFAULT_MAX_RESPONSE_BYTES } = {}) {
     this.creditsKey = typeof creditsKey === "string" && /^a402_[A-Za-z0-9_-]{32,64}$/.test(creditsKey) ? creditsKey : null;
-    if (typeof fetchImpl !== "function") throw new Error("No fetch available — pass { fetchImpl } on Node < 18");
+    if (typeof fetchImpl !== "function") throw new Error("No fetch available - pass { fetchImpl } on Node < 18");
     this.baseUrl = String(baseUrl).replace(/\/$/, "");
     this.payFetch = payFetch || null;
     // Wrap the plain fetch so every request identifies the SDK (see USER_AGENT
@@ -50,15 +58,74 @@ export class Agent402 {
     // 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).
+    // 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
+      log: [], // [{ ts, host, usd }] - settled paid calls in the last 24h
     };
+    // A response-size ceiling, enforced before parsing. See _readJson.
+    this.maxResponseBytes = maxResponseBytes === null ? null : (numOrNull(maxResponseBytes) ?? DEFAULT_MAX_RESPONSE_BYTES);
+  }
+
+  /**
+   * Read a JSON body with a hard byte ceiling.
+   *
+   * WHY THIS LIVES IN THE SDK. Almost everything a buyer might want to check
+   * about a response, they can check themselves in their own code once they
+   * hold it. Not this one: by the time `r.json()` has resolved, a hostile or
+   * broken seller's multi-gigabyte body is already in the agent's memory. The
+   * SDK owns the fetch, so it is the only place the check can happen in time.
+   *
+   * That matters here more than in an ordinary HTTP client, because this SDK
+   * calls STRANGERS and pays them. The seller chooses the response.
+   *
+   * Two gates: the declared content-length is refused before a byte is read,
+   * and the actual stream is counted as it arrives, because content-length is
+   * the seller's claim about their own body and a missing or lying header must
+   * not be the thing standing between an agent and an OOM.
+   */
+  async _readJson(r, { maxBytes, slug, paid = false } = {}) {
+    const cap = maxBytes === undefined ? this.maxResponseBytes : (maxBytes === null ? null : numOrNull(maxBytes));
+    if (cap == null) return r.json();
+
+    const declared = Number(r.headers?.get?.("content-length"));
+    if (Number.isFinite(declared) && declared > cap) {
+      throw new ResponseTooLargeError(declared, cap, { slug, paid, source: "content-length" });
+    }
+    // A response object we cannot measure at all - no stream and no text() -
+    // is a caller-supplied stub or an exotic runtime, never a hostile seller
+    // over a real fetch (a real Response has both). Degrade to an unbounded
+    // read rather than turning "I could not measure this" into a failure of a
+    // call the caller may have already paid for.
+    if ((!r.body || typeof r.body.getReader !== "function") && typeof r.text !== "function") return r.json();
+    // No readable stream but text() is available: bound the PARSE, even though
+    // the bytes have already arrived.
+    if (!r.body || typeof r.body.getReader !== "function") {
+      const text = await r.text();
+      const size = Buffer.byteLength(text, "utf8");
+      if (size > cap) throw new ResponseTooLargeError(size, cap, { slug, paid, source: "body" });
+      return JSON.parse(text);
+    }
+    const reader = r.body.getReader();
+    const chunks = [];
+    let received = 0;
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      received += value.length;
+      if (received > cap) {
+        // Stop pulling immediately. Reading the rest to "see how big it is" is
+        // the failure this exists to prevent.
+        try { await reader.cancel(); } catch { /* already gone */ }
+        throw new ResponseTooLargeError(received, cap, { slug, paid, source: "stream" });
+      }
+      chunks.push(value);
+    }
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
   }
 
   async _loadCatalog() {
@@ -79,9 +146,39 @@ export class Agent402 {
     return (await r.json()).results || [];
   }
 
+  /**
+   * Cross-seller Smart Order Router - rank tools across eligible/routable seller
+   * rows in the host's current index (local catalog plus crawled x402/MPP sellers
+   * the router considers healthy enough to route). Free; no payment, no wallet, no
+   * proof-of-work. Coverage is whatever the host's index holds at call time, not
+   * every seller on the internet.
+   *
+   * Returns the server JSON as-is (reporting only - no validation or authorization).
+   * Each result may carry server-reported `executeVia` naming a `route-execute*`
+   * tier whose underlying cap covers that row's price. `call(executeVia.tool, ...)`
+   * re-resolves an eligible match under that tier at execution time; it does not
+   * bind the discovery row's url, route, seller, or identity.
+   *
+   * @param {string} task
+   * @param {object} [opts]
+   * @param {number} [opts.k=5]                         max results (1-25, server-bounded)
+   * @param {"all"|"external"|"local"} [opts.include="all"]
+   * @param {string} [opts.network]                       chain filter (e.g. "robinhood", "eip155:4663")
+   * @returns {Promise<{query:string, include:string, count:number, sellers:number, results:Array<object>}>}
+   */
+  async route(task, { k = 5, include = "all", network } = {}) {
+    const top = Math.min(Math.max(parseInt(k, 10) || 5, 1), 25);
+    const includeParam = include === "external" || include === "local" ? include : "all";
+    const qs = new URLSearchParams({ q: String(task ?? ""), k: String(top), include: includeParam });
+    if (network) qs.set("network", String(network));
+    const r = await this.f(`${this.baseUrl}/api/route?${qs}`);
+    if (!r.ok) throw new Error(`route failed: HTTP ${r.status}`);
+    return r.json();
+  }
+
   /**
    * Resolve a task to matching multi-tool workflow templates (skill packs).
-   * Each pack composes 5–7 catalog tools into a Claude-ready task template
+   * Each pack composes 5-7 catalog tools into a Claude-ready task template
    * for jobs that no single tool covers (e.g. audit a domain). Returns
    * `[{slug, title, tagline, toolSlugs, score, url, promptName}]` (possibly
    * empty when the lexical signal is weak). Use `getWorkflowPrompt(slug, args)`
@@ -95,7 +192,7 @@ export class Agent402 {
 
   /**
    * Fetch the rendered prompt messages for a skill pack with arguments
-   * substituted in. Same output as MCP `prompts/get` — usable directly with
+   * substituted in. Same output as MCP `prompts/get` - usable directly with
    * any LLM. `args` are passed by promptArg name (see /api/skill-packs.json).
    */
   async getWorkflowPrompt(slug, args = {}) {
@@ -106,11 +203,11 @@ export class Agent402 {
   }
 
   /**
-   * Live x402 leaderboard — the sellers earning the most USDC (or serving the
+   * Live x402 leaderboard - the sellers earning the most USDC (or serving the
    * most calls) on Base in the last ~24h, derived from on-chain USDC
    * transfers. Free; no payment, no wallet, no proof-of-work. Useful when
    * building agents that want to discover the live x402 economy beyond a
-   * single service's catalog. Hourly snapshot — safe to call freely.
+   * single service's catalog. Hourly snapshot - safe to call freely.
    *
    * @param {object} [opts]
    * @param {number} [opts.limit=10]                  max rows (1-50)
@@ -142,7 +239,7 @@ export class Agent402 {
    * Register a wallet address for Base builder code attribution. Idempotent:
    * the same wallet always returns the same code. No authentication required.
    *
-   * @param {string} walletAddress  the caller's wallet address (e.g. "0x…")
+   * @param {string} walletAddress  the caller's wallet address (e.g. "0x...")
    * @param {object} [opts]
    * @param {typeof fetch} [opts.fetchImpl]  plain fetch (defaults to global fetch)
    * @returns {Promise<{builderCode:string, walletAddress:string}>}
@@ -169,10 +266,10 @@ export class Agent402 {
    * Call a tool by slug; pays automatically (PoW for free tools, x402 for
    * wallet-only) and returns the parsed JSON result.
    */
-  async call(slug, params = {}, { idempotencyKey, cache = true } = {}) {
+  async call(slug, params = {}, { idempotencyKey, cache = true, maxResponseBytes } = {}) {
     const cat = await this._loadCatalog();
     const tool = cat.get(slug);
-    if (!tool) throw new Error(`unknown tool "${slug}" — use client.find(task) to discover one`);
+    if (!tool) throw new Error(`unknown tool "${slug}" - use client.find(task) to discover one`);
 
     const cacheKey = `${slug}:${JSON.stringify(params)}`;
     if (this._cache && cache && this._cache.has(cacheKey)) return this._cache.get(cacheKey);
@@ -180,7 +277,7 @@ export class Agent402 {
     const idem = idempotencyKey || `a402-${createHash("sha256").update(`${cacheKey}:${Date.now()}:${Math.random()}`).digest("hex").slice(0, 24)}`;
     const send = (extraHeaders = {}, useFetch = this.f) => {
       // UA set here too (not only in the this.f wrapper) so the x402 payFetch
-      // path — the one that settles real payments — always carries it.
+      // path - the one that settles real payments - always carries it.
       const headers = { "User-Agent": USER_AGENT, "Idempotency-Key": idem, ...extraHeaders };
       let url = `${this.baseUrl}${tool.path}`;
       const init = { method: tool.method, headers };
@@ -201,12 +298,12 @@ export class Agent402 {
         // configured ceiling (per-call / rolling-24h / per-host).
         const host = hostOf(this.baseUrl);
         let usd = parseUsd(tool.price);
-        // The catalog price is seller-ADVERTISED — a hostile server could under-
+        // The catalog price is seller-ADVERTISED - a hostile server could under-
         // state it and then quote more in the 402. When a cap is set, preflight
         // the 402 to learn the price the wallet will actually be asked to sign and
         // check the cap against the larger of the two. Fail-open: if the 402 can't
         // be read (FREE_MODE / non-402 / unparseable), fall back to the advertised
-        // price — never block a legitimate payment on a parse miss.
+        // price - never block a legitimate payment on a parse miss.
         if (this._spendCapsConfigured()) {
           try {
             const pre = await send();
@@ -224,9 +321,9 @@ export class Agent402 {
           const r = await send({}, this.payFetch);
           if (!r.ok) throw new Error(`call "${slug}" failed: HTTP ${r.status}`);
           this._spendSettle(reservation); // confirm the reservation as settled spend
-          return this._store(cacheKey, await r.json(), cache);
+          return this._store(cacheKey, await this._readJson(r, { maxBytes: maxResponseBytes, slug, paid: true }), cache);
         } catch (e) {
-          this._spendRelease(reservation); // roll back — nothing settled
+          this._spendRelease(reservation); // roll back - nothing settled
           throw e;
         }
       }
@@ -245,16 +342,16 @@ export class Agent402 {
           }
           if (!r.ok) throw new Error(`call "${slug}" failed: HTTP ${r.status}`);
           this._spendSettle(reservation);
-          return this._store(cacheKey, await r.json(), cache);
+          return this._store(cacheKey, await this._readJson(r, { maxBytes: maxResponseBytes, slug, paid: true }), cache);
         } catch (e) { this._spendRelease(reservation); throw e; }
       }
-      const r = await send(); // no wallet — succeeds only on a FREE_MODE instance
-      if (r.ok) return this._store(cacheKey, await r.json(), cache);
-      throw new Error(`call "${slug}" failed: HTTP ${r.status} — wallet-only tool; construct with { fetch: payFetch } (an @x402/fetch-wrapped fetch) or { creditsKey } (prepaid card credits from ${this.baseUrl}/credits)`);
+      const r = await send(); // no wallet - succeeds only on a FREE_MODE instance
+      if (r.ok) return this._store(cacheKey, await this._readJson(r, { maxBytes: maxResponseBytes, slug, paid: false }), cache);
+      throw new Error(`call "${slug}" failed: HTTP ${r.status} - wallet-only tool; construct with { fetch: payFetch } (an @x402/fetch-wrapped fetch) or { creditsKey } (prepaid card credits from ${this.baseUrl}/credits)`);
     }
 
     // Free (compute-payable) tool: succeeds plainly on a FREE_MODE instance,
-    // otherwise pay with a proof-of-work (fetched from /api/pow/challenge — the
+    // otherwise pay with a proof-of-work (fetched from /api/pow/challenge - the
     // Agent402 server signals it via the X-Pow-Challenge header, not the 402 body).
     let r = await send();
     if (!r.ok) {
@@ -262,7 +359,7 @@ export class Agent402 {
       r = await send({ "X-Pow-Solution": Agent402.solvePow(chal) });
     }
     if (!r.ok) throw new Error(`call "${slug}" failed after proof-of-work: HTTP ${r.status}`);
-    return this._store(cacheKey, await r.json(), cache);
+    return this._store(cacheKey, await this._readJson(r, { maxBytes: maxResponseBytes, slug, paid: false }), cache);
   }
 
   async _powChallenge(slug) {
@@ -281,7 +378,7 @@ export class Agent402 {
     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}`,
+        `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;
@@ -290,7 +387,7 @@ export class Agent402 {
       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}`,
+          `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 });
       }
     }
@@ -298,7 +395,7 @@ export class Agent402 {
       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}`,
+          `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 });
       }
     }
@@ -330,7 +427,7 @@ export class Agent402 {
     if (i >= 0) this._spend.log.splice(i, 1);
   }
 
-  /** Rolling-24h spend summary (settled paid calls only) — for observability. */
+  /** 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 && !e.pending);
@@ -347,6 +444,20 @@ export class Agent402 {
 
 /** Thrown when a paid call would exceed a configured spending ceiling. The call
  *  is refused BEFORE any payment is signed, so no funds move. */
+/** A response body over the ceiling, refused BEFORE it was parsed.
+ *
+ *  `paid` matters: on a wallet-only tool the money has already moved by the
+ *  time the body arrives, so a caller must be able to tell "I was charged and
+ *  the seller sent something unusable" from "nothing happened". Losing that
+ *  distinction would turn a refused response into a silently forgotten spend. */
+export class ResponseTooLargeError extends Error {
+  constructor(size, cap, { slug, paid, source } = {}) {
+    super(`response for "${slug}" is ${size} bytes, over the ${cap}-byte ceiling (${source}) - refused before parsing${paid ? "; this call WAS paid" : ""}`);
+    this.name = "ResponseTooLargeError";
+    Object.assign(this, { size, cap, slug, paid: Boolean(paid), source });
+  }
+}
+
 export class SpendingLimitError extends Error {
   constructor(message, details = {}) {
     super(message);
@@ -355,7 +466,7 @@ export class SpendingLimitError extends Error {
   }
 }
 
-// Parse the USD amount an x402 `402` challenge actually requires — the max across
+// Parse the USD amount an x402 `402` challenge actually requires - the max across
 // the offered rails. x402 is stablecoin-settled (USDC/USDG), so
 // atomic / 10^decimals ≈ USD. Returns null if the body isn't a parseable 402
 // challenge, so the caller fails open to the advertised catalog price.
@@ -383,7 +494,7 @@ function parseUsd(price) {
 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
+ * Restrict + order which chains an @x402 client will pay on (duck-typed - any
  * client version with createPaymentPayload works, zero new dependencies).
  * Multi-chain sellers list Base first, so an unmodified client effectively
  * always settles there; this makes rails like USDG on Robinhood Chain

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent402-client",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "Agent402 buyer SDK: resolve a task to a tool across 500+ pay-per-call endpoints and call it with payment handled - free via proof-of-work, or over x402 or MPP (a stock mppx fetch works) with a wallet you keep; the buy side of Agentic Finance. Caching, idempotent retries (Idempotency-Key), non-custodial, zero dependencies.",
   "type": "module",
   "main": "index.js",