agent402-client 0.8.20 → 0.8.22

package/README.md

@@ -166,6 +166,14 @@ What the server does with it depends on how the call was paid:
   route with the same body, from its first answer inside the replay window,
   with no second settlement, and marks it `X-Replayed-Answer: 1` (identity-bound
   routes, routes with a lasting effect and streamed calls excepted).
+- **A connection reset before any answer:** the SDK's own requests (proof-of-work,
+  credits, discovery) are resent once when the connection failed before the
+  server answered, for example on a kept-alive socket the edge had already
+  closed (`retryResets: false` turns this off). Your `payFetch` is not wrapped,
+  because a retry over a payment wrapper would sign a fresh authorization. To get
+  the same resend on the wallet path, put it under the wrapper:
+  `wrapFetchWithPayment(resetRetryFetch(distrustFetch()), client)`. The resend
+  carries the same signed header, and one authorization settles at most once.
 - **Circle Gateway batched option:** a payment the server has not had confirmed
   by Gateway yet is answered `402` with reason `settlement-pending`; the SDK
   resends the same signed header after the server's `Retry-After` (never a new
@@ -269,7 +277,7 @@ that runs as one.
 
 | Method | What |
 |---|---|
-| `new Agent402({ baseUrl?, fetch?, x402Client?, creditsKey?, gateway?, cache?, fetchImpl?, maxPerCallUsd?, dailyLimitUsd?, maxPerHostUsd?, payNetworks?, maxResponseBytes?, outputValidator?, respondAsync?, asyncTimeoutMs?, onProgress? })` | `fetch` is your x402- or MPP-wrapped fetch for paid tools (optional); `x402Client` is the `@x402/core` client that `fetch` wraps, so the caps are enforced on the payment that is signed (see below); `payNetworks` (for example `["base"]`, the names `withNetworkPreference` takes) tells the caps which chains a pre-wrapped `fetch` without an `x402Client` pays on, so a call is counted at the dearest option on those chains (when none of a 402's options is on them, the dearest of all counts); `creditsKey` is a prepaid credits key (`a402_...`) used for paid tools when no `fetch` is given; `gateway` (`{ signer, networks? }`) pays the Circle Gateway batched accept where a 402 offers one, from the signer's Gateway deposit (see above); `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; `respondAsync` (default `"auto"`), `asyncTimeoutMs` (default 15 minutes) and `onProgress` control slow routes run as jobs (see above) |
+| `new Agent402({ baseUrl?, fetch?, x402Client?, creditsKey?, gateway?, cache?, fetchImpl?, maxPerCallUsd?, dailyLimitUsd?, maxPerHostUsd?, payNetworks?, maxResponseBytes?, outputValidator?, respondAsync?, asyncTimeoutMs?, onProgress?, userAgent? })` | `fetch` is your x402- or MPP-wrapped fetch for paid tools (optional); `x402Client` is the `@x402/core` client that `fetch` wraps, so the caps are enforced on the payment that is signed (see below); `payNetworks` (for example `["base"]`, the names `withNetworkPreference` takes) tells the caps which chains a pre-wrapped `fetch` without an `x402Client` pays on, so a call is counted at the dearest option on those chains (when none of a 402's options is on them, the dearest of all counts); `creditsKey` is a prepaid credits key (`a402_...`) used for paid tools when no `fetch` is given; `gateway` (`{ signer, networks? }`) pays the Circle Gateway batched accept where a 402 offers one, from the signer's Gateway deposit (see above); `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; `respondAsync` (default `"auto"`), `asyncTimeoutMs` (default 15 minutes) and `onProgress` control slow routes run as jobs (see above); `userAgent` (`"name/version"`) is a calling package's own product token, sent before `agent402-client/<version>` in the User-Agent |
 | `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) |

package/index.js

@@ -23,6 +23,8 @@ import { quoteOf, guardSigning, networkIdsOf, acceptUsd } from "./known-assets.j
 export { KNOWN_ASSETS, NETWORK_NAMES, knownAsset, acceptUsd, networkIdsOf } from "./known-assets.js";
 import { distrustFetch } from "./tls-distrust.js";
 export { distrustFetch, distrustDispatcher, distrustCheckServerIdentity, DISTRUSTED_SPKI_SHA256 } from "./tls-distrust.js";
+export { resetRetryFetch, isConnectionReset } from "./reset-retry.js";
+import { resetRetryFetch } from "./reset-retry.js";
 import { awaitJob, shouldRequestAsync, AsyncJobPendingError, DEFAULT_ASYNC_TIMEOUT_MS } from "./async-job.js";
 export { AsyncJobPendingError } from "./async-job.js";
 
@@ -30,8 +32,13 @@ export { AsyncJobPendingError } from "./async-job.js";
 // `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.20";
+const VERSION = "0.8.22";
 const USER_AGENT = `agent402-client/${VERSION}`;
+// A package built on this SDK (an adapter) names itself first: its own
+// product token, then this one. Anything that is not one well-formed token
+// is ignored and the SDK's own token is sent alone.
+const PRODUCT_TOKEN_RE = /^[A-Za-z0-9.-]{1,40}\/[A-Za-z0-9.-]{1,20}$/;
+const userAgentOf = (product) => (typeof product === "string" && PRODUCT_TOKEN_RE.test(product) ? `${product} ${USER_AGENT}` : USER_AGENT);
 // 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
@@ -120,8 +127,12 @@ 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 through distrustFetch)
+   * @param {string} [opts.userAgent]        a calling package's own product token ("name/version"),
+   *                                         sent before agent402-client's in the User-Agent
    * @param {boolean} [opts.tlsDistrust=true] send the default fetch through distrustFetch (refuses a TLS
    *                                         chain through a distrusted intermediate CA); false sends it as is
+   * @param {boolean} [opts.retryResets=true] resend the SDK's own request once when its connection failed
+   *                                         before any answer (see resetRetryFetch); false sends each once
    * @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)
@@ -156,7 +167,8 @@ export class Agent402 {
   constructor({ baseUrl = "https://agent402.tools", fetch: payFetch, cache = true, fetchImpl = undefined, tlsDistrust = true,
     maxPerCallUsd = null, dailyLimitUsd = null, maxPerHostUsd = null, creditsKey = null, x402Client = null, payNetworks = null,
     maxResponseBytes = DEFAULT_MAX_RESPONSE_BYTES, outputValidator = null,
-    respondAsync = "auto", asyncTimeoutMs = DEFAULT_ASYNC_TIMEOUT_MS, onProgress = null, gateway = null } = {}) {
+    respondAsync = "auto", asyncTimeoutMs = DEFAULT_ASYNC_TIMEOUT_MS, onProgress = null, gateway = null, userAgent = null, retryResets = true } = {}) {
+    this.userAgent = userAgentOf(userAgent);
     this.respondAsync = respondAsync;
     this.gateway = normalizeGateway(gateway);
     this.asyncTimeoutMs = numOrNull(asyncTimeoutMs) ?? DEFAULT_ASYNC_TIMEOUT_MS;
@@ -167,11 +179,15 @@ export class Agent402 {
       if (typeof fetchImpl === "function" && tlsDistrust !== false) fetchImpl = distrustFetch(fetchImpl);
     }
     if (typeof fetchImpl !== "function") throw new Error("No fetch available - pass { fetchImpl } on Node < 18");
+    // The SDK's own requests resend once when the connection failed before any
+    // answer (a closed keep-alive socket). A caller's payFetch is not wrapped:
+    // retrying over a payment wrapper would sign a fresh authorization.
+    if (retryResets !== false) fetchImpl = resetRetryFetch(fetchImpl);
     this.baseUrl = String(baseUrl).replace(/\/$/, "");
     this.payFetch = payFetch || null;
     // Wrap the plain fetch so every request identifies the SDK (see USER_AGENT
     // above). Caller-supplied init.headers still win on a key collision.
-    this.f = (url, init = {}) => fetchImpl(url, { ...init, headers: { "User-Agent": USER_AGENT, ...(init.headers || {}) } });
+    this.f = (url, init = {}) => fetchImpl(url, { ...init, headers: { "User-Agent": this.userAgent, ...(init.headers || {}) } });
     this._catalog = null;
     // The wait between shed-503 retries of a discovery read (tests replace it).
     this._sleep = sleepMs;
@@ -511,7 +527,7 @@ export class Agent402 {
     const send = async (extraHeaders = {}, useFetch = this.f, { paid = false } = {}) => {
       // 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.
-      const headers = { "User-Agent": USER_AGENT, "Idempotency-Key": idem, ...extraHeaders };
+      const headers = { "User-Agent": this.userAgent, "Idempotency-Key": idem, ...extraHeaders };
       let url = `${this.baseUrl}${tool.path}`;
       // A request that can carry a payment never follows a redirect: followed,
       // it would answer a 402 from another origin with a signature to that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent402-client",
-  "version": "0.8.20",
+  "version": "0.8.22",
   "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",
@@ -12,6 +12,7 @@
     "async-job.js",
     "known-assets.js",
     "tls-distrust.js",
+    "reset-retry.js",
     "README.md"
   ],
   "engines": {

package/reset-retry.js

@@ -0,0 +1,47 @@
+// resetRetryFetch(baseFetch) returns a fetch that resends a request ONCE when
+// its connection failed before any response arrived: a kept-alive socket the
+// server's edge already closed answers the next write with ECONNRESET (or
+// undici's "other side closed"), and the request never reached the server.
+//
+// Only a transport error is retried, never an HTTP answer, and only for a
+// body that can be sent again (none, a string, bytes, URLSearchParams, a
+// Blob); a streamed body is not. The resend carries the same headers, so a
+// signed payment is resent as signed: an EIP-3009 authorization's nonce can
+// settle only once, and the server answers a re-sent signed payment from its
+// first answer, so the resend can never pay twice. Wrap it UNDER a payment
+// wrapper (wrapFetchWithPayment(resetRetryFetch(fetch), client)), never over
+// one: over a wrapper, a retry would sign a fresh authorization.
+const RESET_CODES = new Set(["ECONNRESET", "EPIPE", "UND_ERR_SOCKET", "UND_ERR_CLOSED", "ECONNABORTED"]);
+
+/** Did this fetch error fail on the connection before any response? */
+export function isConnectionReset(err) {
+  let e = err;
+  for (let i = 0; i < 5 && e; i++) {
+    if (RESET_CODES.has(e.code)) return true;
+    if (/other side closed|socket hang up/i.test(String(e.message || ""))) return true;
+    e = e.cause;
+  }
+  return false;
+}
+
+function replayableBody(body) {
+  if (body === undefined || body === null || typeof body === "string") return true;
+  if (body instanceof ArrayBuffer || ArrayBuffer.isView(body)) return true;
+  if (typeof URLSearchParams !== "undefined" && body instanceof URLSearchParams) return true;
+  if (typeof Blob !== "undefined" && body instanceof Blob) return true;
+  return false;
+}
+
+export function resetRetryFetch(baseFetch = globalThis.fetch, { pauseMs = 300 } = {}) {
+  if (typeof baseFetch !== "function") throw new Error("resetRetryFetch needs a fetch function");
+  return async function fetchWithResetRetry(input, init) {
+    try {
+      return await baseFetch(input, init);
+    } catch (e) {
+      const isRequest = typeof Request !== "undefined" && input instanceof Request;
+      if (!isConnectionReset(e) || init?.signal?.aborted || isRequest || !replayableBody(init?.body)) throw e;
+      await new Promise((r) => setTimeout(r, pauseMs));
+      return baseFetch(input, init);
+    }
+  };
+}