agent402-client 0.8.2 → 0.8.3

package/README.md

@@ -5,8 +5,10 @@ instance) - the buy side of [Agentic Finance](https://agent402.tools/agentic-fin
 agents paying per request over x402 or MPP. **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
 dependencies); wallet-only tools settle via an x402- or MPP-wrapped fetch you
-provide, or by card through a prepaid credits key. Results are cached, and
-retries reuse an `Idempotency-Key` so a lost response never double-charges.
+provide, or by card through a prepaid credits key. Results are cached, and every
+send carries an `Idempotency-Key` that is stable per client and per operation, so
+a retried lost response replays the paid answer on the credits and proof-of-work
+paths (the wallet path is different: see "Retries and double charges").
 
 ```bash
 npm install agent402-client
@@ -89,14 +91,32 @@ credits call reserves its price like a wallet call). A payment `fetch` still win
 when both are given, and free pure-CPU tools keep settling with proof-of-work.
 The same Bearer header also reads the balance directly, e.g. `curl -H "Authorization: Bearer a402_..." https://agent402.tools/api/credits/balance`.
 
-## Retries never double-charge
-
-Every paid call the SDK makes carries an `Idempotency-Key`, so a retry of a
-call whose response was lost replays the original result instead of paying
-again. If your x402 client attaches the standard `payment-identifier`
-extension to its payloads instead, Agent402 honours that id the same way (an
-exact retry with the same credential replays; a fresh authorization with the
-same id is a new payment).
+## Retries and double charges
+
+Every send carries an `Idempotency-Key`. By default it is derived from the
+client instance plus the operation (slug, params, output validator), so it is
+the same key when the SDK retries inside one `call()` AND when your framework
+calls `client.call(slug, params)` again after a timeout or a dropped connection.
+With `{ cache: false }` on the call, identical calls are treated as distinct
+purchases and the key is fresh per invocation. Pass `idempotencyKey` yourself to
+override either behavior. Keys are scoped to the client instance: two processes
+buying the same thing are two purchases.
+
+What the server does with it depends on how the call was paid:
+
+- **Prepaid credits and proof-of-work:** the server binds the key to the credits
+  key (or the accepted solution) plus the route and body, and replays the
+  original 200 for ten minutes. A retry of a lost response is not debited again.
+- **x402 wallet:** the server binds the key to the exact signed authorization.
+  An exact retry (same signed header, same key) replays without a second
+  settlement, and that is what the `payment-identifier` extension gives a stock
+  x402 client. A fresh `call()` through an `@x402/fetch`-wrapped fetch signs a
+  fresh authorization, which the server deliberately treats as a new payment
+  (a client-chosen id on an unverified payload is never a cross-authorization
+  dedupe). So on the wallet path a retry after a lost response can settle twice;
+  the `Idempotency-Key` cannot prevent that on its own. If that matters for your
+  workload, use a credits key for the tools you retry, or keep the signed
+  request and resend it yourself.
 
 ## Workflows (skill packs)
 
@@ -165,13 +185,13 @@ await a.topSellers({ sort: "calls", include: "all" });
 
 | Method | What |
 |---|---|
-| `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 |
+| `new Agent402({ baseUrl?, fetch?, creditsKey?, cache?, fetchImpl?, maxPerCallUsd?, dailyLimitUsd?, maxPerHostUsd?, maxResponseBytes?, outputValidator? })` | `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; `outputValidator` binds a caller-supplied delivery check |
 | `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?, maxResponseBytes? })` | 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?, outputValidator? })` | 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 |
@@ -196,6 +216,56 @@ 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.
 
+## Buyer-owned output validation
+
+A successful payment and HTTP 200 do not prove that the delivered result is
+useful. Supply a stable contract id and a local callback to enforce the exact
+output your agent needs:
+
+```js
+const a = new Agent402({
+  fetch: payFetch,
+  outputValidator: {
+    id: "unemployment-result/v1",
+    validate: (body) =>
+      typeof body.current === "number" &&
+      Array.isArray(body.history) &&
+      typeof body.source === "string",
+  },
+});
+```
+
+`validate` may return `false` or throw to reject delivery, and may be async.
+Use any local validator you prefer: Ajv, Zod, agent-payment-policy, or ordinary
+application code. The client adds no dependency and never sends the validator
+or its id to the seller.
+
+Validation runs after bounded JSON parsing and before cache admission. A
+rejected paid response throws `OutputValidationError` with `paid: true`, stays
+in `spendingSummary()`, and is never cached. Contracted cache entries are
+namespaced by a SHA-256 digest of `id` and revalidated on every hit, so a
+different contract or a caller-mutated cached object cannot bypass the check.
+The caller owns the meaning and stability of `id`; changing validation
+semantics requires a new id. A per-call validator may replace the constructor
+validator, but `null` or omission preserves the constructor policy rather than
+silently weakening it. Use a separate client when a route intentionally has no
+output contract.
+
+**Two costs worth knowing.** `validate` is awaited inside `call()`, so it is
+bounded: a validator that has not settled in **5 seconds** rejects delivery with
+`OutputValidationError` rather than hanging the call. On a paid route the money
+has already moved by then, so an indefinite hang would be the worst place to
+have one; a timeout is a rejection, because an unfinished contract is not a
+satisfied one. Override per validator with `timeoutMs`:
+
+```js
+outputValidator: { id: "big-schema/v1", validate: slowCheck, timeoutMs: 30_000 }
+```
+
+And because contracted cache entries are revalidated on **every** hit, an
+expensive validator is paid for on cache hits too, not just on the network call.
+Keep it cheap, or accept that cost knowingly.
+
 ## Spending caps (never overpay)
 
 By default the client pays whatever a tool costs. Set optional hard ceilings and a
@@ -219,9 +289,11 @@ try {
 }
 ```
 
-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.
+Only **settled** paid calls count against the rolling window. A call refused or
+failed before settlement never consumes budget. A paid HTTP-success response
+that later fails byte, JSON, or output validation remains settled spend. Free
+proof-of-work calls are never counted. Omit a cap (or leave it `null`) for no
+limit; with none set, behavior is unchanged.
 
 **What the caps check.** When a cap is set, the client preflights the `402` and
 checks the ceiling against the **larger** of the advertised price (from the

package/index.js

@@ -2,8 +2,13 @@
 // 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),
-// results are cached (tools are deterministic), and retries reuse an
-// Idempotency-Key so a lost response never double-charges.
+// results are cached (tools are deterministic), and every send carries an
+// Idempotency-Key that is stable per client instance and per operation while
+// caching is on, so a retry of a lost response (inside call() or by the caller
+// invoking call() again) replays the paid answer on the credits and PoW paths
+// instead of paying twice. A wallet buyer's fresh call() signs a fresh
+// authorization, which the server treats as a new payment by design - see
+// README "Retries and double charges".
 //
 //   import { Agent402 } from "agent402-client";
 //   const a = new Agent402();                       // free tier, proof-of-work
@@ -12,13 +17,13 @@
 //
 //   // paid tools: pass an x402-wrapped fetch (your wallet signs)
 //   const a = new Agent402({ fetch: payFetch });
-import { createHash } from "node:crypto";
+import { createHash, randomBytes } 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)
 // to this SDK. Product token only; nothing about the caller rides along.
-const VERSION = "0.8.2";
+const VERSION = "0.8.3";
 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
@@ -42,10 +47,13 @@ export class Agent402 {
    *                                         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.
+   * @param {{id:string, validate:function}} [opts.outputValidator]
+   *        Optional buyer-owned result validator. `id` namespaces cache entries;
+   *        `validate` may return false or throw to reject delivery.
    */
   constructor({ baseUrl = "https://agent402.tools", fetch: payFetch, cache = true, fetchImpl = globalThis.fetch,
     maxPerCallUsd = null, dailyLimitUsd = null, maxPerHostUsd = null, creditsKey = null,
-    maxResponseBytes = DEFAULT_MAX_RESPONSE_BYTES } = {}) {
+    maxResponseBytes = DEFAULT_MAX_RESPONSE_BYTES, outputValidator = null } = {}) {
     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");
     this.baseUrl = String(baseUrl).replace(/\/$/, "");
@@ -55,6 +63,14 @@ export class Agent402 {
     this.f = (url, init = {}) => fetchImpl(url, { ...init, headers: { "User-Agent": USER_AGENT, ...(init.headers || {}) } });
     this._catalog = null;
     this._cache = cache ? new Map() : null;
+    // Salt for the default Idempotency-Key: one per client instance, so the key
+    // for (slug, params) is stable across call() invocations on THIS client
+    // (an agent framework retrying a lost response gets the replay) and still
+    // distinct between sessions (two processes buying the same thing are two
+    // purchases). Issue #1126: the old default mixed Date.now() + Math.random()
+    // per invocation, which protected retries inside one call() and nothing
+    // the header promised beyond it.
+    this._idemSalt = randomBytes(12).toString("hex");
     // 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
@@ -69,6 +85,9 @@ export class Agent402 {
     };
     // A response-size ceiling, enforced before parsing. See _readJson.
     this.maxResponseBytes = maxResponseBytes === null ? null : (numOrNull(maxResponseBytes) ?? DEFAULT_MAX_RESPONSE_BYTES);
+    // Buyer-owned delivery policy. The callback stays entirely local and may
+    // use Ajv, Zod, agent-payment-policy, or ordinary application code.
+    this.outputValidator = normalizeOutputValidator(outputValidator, "constructor");
   }
 
   /**
@@ -266,15 +285,41 @@ 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, maxResponseBytes } = {}) {
+  async call(slug, params = {}, { idempotencyKey, cache = true, maxResponseBytes, outputValidator } = {}) {
+    // Resolve and validate the buyer-owned contract before catalog fetch,
+    // credential access, payment preflight, or any other network action.
+    const validator = outputValidator == null
+      ? this.outputValidator
+      : normalizeOutputValidator(outputValidator, "call");
     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`);
 
-    const cacheKey = `${slug}:${JSON.stringify(params)}`;
-    if (this._cache && cache && this._cache.has(cacheKey)) return this._cache.get(cacheKey);
+    const cacheKey = resultCacheKey(slug, params, validator);
+    if (this._cache && cache && this._cache.has(cacheKey)) {
+      const stored = this._cache.get(cacheKey);
+      // Callers receive the stored object by reference and may mutate it.
+      // Revalidate contracted hits so a now-invalid object cannot pass merely
+      // because it was valid before the caller changed it.
+      try {
+        await this._assertOutput(slug, stored, validator, { paid: false, cacheHit: true });
+      } catch (error) {
+        this._cache.delete(cacheKey);
+        throw error;
+      }
+      return stored;
+    }
 
-    const idem = idempotencyKey || `a402-${createHash("sha256").update(`${cacheKey}:${Date.now()}:${Math.random()}`).digest("hex").slice(0, 24)}`;
+    // Default key = stable per (client instance, slug, params, validator) while
+    // caching is on: the SDK already treats that tuple as one operation (a
+    // second identical call is served from cache without payment), so the
+    // idempotency key agrees with the cache key instead of contradicting it.
+    // With { cache: false } the caller has said identical calls are distinct
+    // purchases, so the key is fresh per invocation, as before. An explicit
+    // idempotencyKey always wins.
+    const idem = idempotencyKey || (cache
+      ? `a402-${createHash("sha256").update(`${this._idemSalt}:${cacheKey}`).digest("hex").slice(0, 24)}`
+      : `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.
@@ -317,13 +362,17 @@ export class Agent402 {
         // can't each observe the pre-commit total and collectively blow a rolling
         // cap; release the reservation if the call doesn't settle.
         const reservation = this._spendReserve(host, usd, slug);
+        let settled = false;
         try {
           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 this._readJson(r, { maxBytes: maxResponseBytes, slug, paid: true }), cache);
+          settled = true;
+          return this._deliverResponse(slug, r, cacheKey, cache, validator, { maxResponseBytes, paid: true });
         } catch (e) {
-          this._spendRelease(reservation); // roll back - nothing settled
+          // An invalid or oversized paid HTTP-success body is failed delivery,
+          // not a rollback of money that already moved.
+          if (!settled) this._spendRelease(reservation);
           throw e;
         }
       }
@@ -334,6 +383,7 @@ export class Agent402 {
         const host = hostOf(this.baseUrl);
         const usd = parseUsd(tool.price);
         const reservation = this._spendReserve(host, usd, slug);
+        let settled = false;
         try {
           const r = await send({ Authorization: `Bearer ${this.creditsKey}` });
           if (r.status === 402) {
@@ -342,11 +392,12 @@ export class Agent402 {
           }
           if (!r.ok) throw new Error(`call "${slug}" failed: HTTP ${r.status}`);
           this._spendSettle(reservation);
-          return this._store(cacheKey, await this._readJson(r, { maxBytes: maxResponseBytes, slug, paid: true }), cache);
-        } catch (e) { this._spendRelease(reservation); throw e; }
+          settled = true;
+          return this._deliverResponse(slug, r, cacheKey, cache, validator, { maxResponseBytes, paid: true });
+        } catch (e) { if (!settled) 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 this._readJson(r, { maxBytes: maxResponseBytes, slug, paid: false }), cache);
+      if (r.ok) return this._deliverResponse(slug, r, cacheKey, cache, validator, { maxResponseBytes, paid: false });
       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)`);
     }
 
@@ -359,7 +410,30 @@ 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 this._readJson(r, { maxBytes: maxResponseBytes, slug, paid: false }), cache);
+    return this._deliverResponse(slug, r, cacheKey, cache, validator, { maxResponseBytes, paid: false });
+  }
+
+  async _assertOutput(slug, body, validator, { paid = false, cacheHit = false } = {}) {
+    if (!validator) return body;
+    try {
+      // BOUNDED. The validator is caller-owned code we await inside call(), so
+      // one that never settles hangs the buyer's call forever - and on a paid
+      // route the money has already moved by the time it runs, which makes an
+      // indefinite hang the worst possible place to have one. A timeout is a
+      // REJECTION, not a pass: an unfinished contract has not been satisfied.
+      const result = await withValidatorTimeout(validator.validate(body), validator.timeoutMs ?? OUTPUT_VALIDATOR_TIMEOUT_MS, validator.id);
+      if (result === false) throw new Error("validator returned false");
+      return body;
+    } catch (cause) {
+      throw new OutputValidationError(`output for "${slug}" failed buyer validator "${validator.id}"${paid ? "; this call WAS paid" : ""}`,
+        { slug, contractId: validator.id, paid, cacheHit, cause });
+    }
+  }
+
+  async _deliverResponse(slug, response, cacheKey, cache, validator, { maxResponseBytes, paid } = {}) {
+    const body = await this._readJson(response, { maxBytes: maxResponseBytes, slug, paid });
+    await this._assertOutput(slug, body, validator, { paid });
+    return this._store(cacheKey, body, cache);
   }
 
   async _powChallenge(slug) {
@@ -458,6 +532,16 @@ export class ResponseTooLargeError extends Error {
   }
 }
 
+/** A buyer-owned validator rejected the delivered body. `paid` records whether
+ * this invocation had already settled before validation ran. */
+export class OutputValidationError extends Error {
+  constructor(message, { slug, contractId, paid, cacheHit, cause } = {}) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.name = "OutputValidationError";
+    Object.assign(this, { slug, contractId, paid: Boolean(paid), cacheHit: Boolean(cacheHit) });
+  }
+}
+
 export class SpendingLimitError extends Error {
   constructor(message, details = {}) {
     super(message);
@@ -493,6 +577,56 @@ function parseUsd(price) {
 }
 function hostOf(url) { try { return new URL(url).host; } catch { return String(url); } }
 
+const OUTPUT_VALIDATOR_ID_MAX_CHARS = 256;
+// How long a buyer-owned validator may take before delivery is refused.
+const OUTPUT_VALIDATOR_TIMEOUT_MS = 5_000;
+
+function normalizeOutputValidator(value, where) {
+  if (value == null) return null;
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError(`${where} outputValidator must be null or { id, validate }`);
+  }
+  const id = value.id;
+  if (typeof id !== "string" || id.trim() !== id || id.length < 1 || id.length > OUTPUT_VALIDATOR_ID_MAX_CHARS) {
+    throw new TypeError(`${where} outputValidator.id must be a nonempty trimmed string of at most ${OUTPUT_VALIDATOR_ID_MAX_CHARS} characters`);
+  }
+  if (typeof value.validate !== "function") {
+    throw new TypeError(`${where} outputValidator.validate must be a function`);
+  }
+  // Opt-in per-validator override; anything unusable falls back to the default
+  // rather than silently disabling the bound.
+  const t = Number(value.timeoutMs);
+  const timeoutMs = Number.isFinite(t) && t > 0 ? t : OUTPUT_VALIDATOR_TIMEOUT_MS;
+  return Object.freeze({ id, validate: value.validate, timeoutMs });
+}
+
+/** Reject if the caller's validator has not settled in `ms`. The timer is
+ *  cleared on both paths so a fast validator leaves nothing pending (an
+ *  un-cleared timer would hold the event loop open on a short-lived script). */
+function withValidatorTimeout(promise, ms, id) {
+  let timer;
+  return Promise.race([
+    Promise.resolve(promise),
+    new Promise((_, reject) => {
+      // NOT unref'd: an unref'd timer lets a short-lived script exit before the
+      // rejection fires, so the buyer gets a silent process exit instead of an
+      // OutputValidationError - which is the failure this bound exists to
+      // prevent. clearTimeout in finally() is what stops it lingering.
+      timer = setTimeout(() => reject(new Error(`validator ${JSON.stringify(id)} did not settle within ${ms}ms`)), ms);
+    }),
+  ]).finally(() => clearTimeout(timer));
+}
+
+function resultCacheKey(slug, params, validator) {
+  const requestKey = `${slug}:${JSON.stringify(params)}`;
+  if (!validator) return requestKey;
+  // The caller supplies a stable semantic identity because function source is
+  // neither stable nor meaningful. Hashing keeps arbitrary labels out of map
+  // keys and avoids an unbounded readable cache-key surface.
+  const digest = createHash("sha256").update(validator.id, "utf8").digest("hex");
+  return `${requestKey}#output-validator/v1/${digest}`;
+}
+
 /**
  * Restrict + order which chains an @x402 client will pay on (duck-typed - any
  * client version with createPaymentPayload works, zero new dependencies).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent402-client",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "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",