@providerkit/core 0.1.0 → 0.2.0

package/dist/transport.js

@@ -4,7 +4,7 @@
 //
 // Adapters keep only their per-event mapping; everything about being an HTTP
 // client lives here once.
-import { classify, isTransportFailure, ProviderError } from "./errors.js";
+import { classifyHttp, isTransportFailure, ProviderError } from "./errors.js";
 /** Join a base URL and a path without doubling or dropping the slash. */
 export function apiUrl(baseUrl, path) {
     return `${baseUrl.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`;
@@ -53,7 +53,7 @@ export function retryAfterFromHeaders(headers, now = Date.now()) {
 /** Turn a non-2xx response into the classified error every caller branches on. */
 async function errorFor(provider, res) {
     const text = await res.text().catch(() => "");
-    const kind = classify({ status: res.status, error: text }, res.status, text);
+    const kind = classifyHttp(res.status, text);
     const message = text
         ? `${provider} ${res.status}: ${text.slice(0, 500)}`
         : `${provider} ${res.status} ${res.statusText}`;
@@ -91,49 +91,58 @@ export async function postJson(opts) {
         throw await errorFor(opts.provider, res);
     return (await res.json());
 }
+/** Pull the `data:` payload out of one SSE frame, joining continuation lines
+ *  the way the spec says to. Returns null for a comment or a frame carrying
+ *  only an `event:` name. */
+function payloadOf(frame) {
+    const parts = [];
+    for (const line of frame.split("\n")) {
+        if (!line.startsWith("data:"))
+            continue;
+        parts.push(line.slice(5).replace(/^ /, ""));
+    }
+    // Gemini abandons the framing to report a mid-stream failure: the
+    // google.rpc.Status is appended as a bare JSON object with no `data:` on
+    // it. Dropped here it never reaches an adapter, and a 429 or a 503 that
+    // lands after the headers reads as an empty, successful turn. Requiring an
+    // object keeps comments and `event:`-only frames returning null.
+    if (parts.length === 0) {
+        const bare = frame.trim();
+        return bare.startsWith("{") ? bare : null;
+    }
+    const payload = parts.join("\n").trim();
+    return payload.length > 0 ? payload : null;
+}
 /**
- * POST an SSE request and yield each `data:` payload, trimmed.
+ * Yield each `data:` payload of an SSE body, trimmed — plus the bare JSON
+ * object a vendor appends outside the framing, which is only ever an error
+ * (see `payloadOf`).
  *
- * Frames are split on the blank line the spec requires, so a payload
- * containing a bare newline survives; `[DONE]` is swallowed here rather than in
- * every adapter. CRLF is normalized — some gateways send it, and a `\r` left on
- * the end of a JSON payload is a parse error nobody enjoys debugging.
+ * Frames are split on the blank line the spec requires, so a payload containing
+ * a bare newline survives; `[DONE]` is swallowed here rather than in every
+ * adapter. CRLF is normalized — some gateways send it, and a `\r` left on the
+ * end of a JSON payload is a parse error nobody enjoys debugging.
+ *
+ * Exported apart from `streamSse` because the envelope above it is the half an
+ * adopting app most often cannot take: an app with its own translated error
+ * copy, its own log levels, or its own auth refresh has to keep building the
+ * request and reading the failure itself. Framing is the half nobody should
+ * write twice — hand it a `res.body` and keep your own envelope.
  */
-export async function* streamSse(opts) {
-    const res = await send(opts);
-    if (!res.ok)
-        throw await errorFor(opts.provider, res);
-    // A 2xx with no body at all is an upstream anomaly, not a request we got
-    // wrong — worth the same retry a 5xx gets.
-    if (!res.body) {
-        throw new ProviderError(opts.provider, "overload", `${opts.provider}: empty response body`, {
-            status: res.status,
-        });
-    }
-    const reader = res.body.getReader();
+export async function* parseSseStream(body) {
+    const reader = body.getReader();
     const decoder = new TextDecoder();
     let buffer = "";
-    /** Pull the `data:` payload out of one SSE frame, joining continuation
-     *  lines the way the spec says to. Returns null for a comment or a frame
-     *  carrying only an `event:` name. */
-    function payloadOf(frame) {
-        const parts = [];
-        for (const line of frame.split("\n")) {
-            if (!line.startsWith("data:"))
-                continue;
-            parts.push(line.slice(5).replace(/^ /, ""));
-        }
-        if (parts.length === 0)
-            return null;
-        const payload = parts.join("\n").trim();
-        return payload.length > 0 ? payload : null;
-    }
     try {
         for (;;) {
             const { done, value } = await reader.read();
             if (done)
                 break;
-            buffer += decoder.decode(value, { stream: true }).replace(/\r\n/g, "\n");
+            // Normalized on the BUFFER, not on the decoded read: a network read can
+            // end between the CR and the LF, and normalizing each read separately
+            // leaves that CR stranded on the end of a payload — a JSON parse error
+            // that only ever reproduces under a particular packet split.
+            buffer = (buffer + decoder.decode(value, { stream: true })).replace(/\r\n/g, "\n");
             let boundary = buffer.indexOf("\n\n");
             while (boundary !== -1) {
                 const frame = buffer.slice(0, boundary);
@@ -154,4 +163,21 @@ export async function* streamSse(opts) {
         reader.releaseLock();
     }
 }
+/**
+ * POST an SSE request and stream its payloads: the envelope (auth, the
+ * classified error, the retry hints) plus `parseSseStream`.
+ */
+export async function* streamSse(opts) {
+    const res = await send(opts);
+    if (!res.ok)
+        throw await errorFor(opts.provider, res);
+    // A 2xx with no body at all is an upstream anomaly, not a request we got
+    // wrong — worth the same retry a 5xx gets.
+    if (!res.body) {
+        throw new ProviderError(opts.provider, "overload", `${opts.provider}: empty response body`, {
+            status: res.status,
+        });
+    }
+    yield* parseSseStream(res.body);
+}
 //# sourceMappingURL=transport.js.map

package/dist/transport.js.map

@@ -1 +1 @@
-{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,+EAA+E;AAC/E,sBAAsB;AACtB,EAAE;AACF,6EAA6E;AAC7E,0BAA0B;AAC1B,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAa9E,yEAAyE;AACzE,MAAM,UAAU,MAAM,CAAC,OAAe,EAAE,IAAY;IAClD,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,EAAE,CAAC;AACtE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAgB,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;IACtE,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAC9C,IAAI,UAAU,EAAE,CAAC;QACf,IAAI,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC;YAAE,OAAO,MAAM,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC;QAC/D,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QACpC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,GAAG,GAAG,CAAC,CAAC;IAC1D,CAAC;IACD,yEAAyE;IACzE,KAAK,MAAM,IAAI,IAAI;QACjB,mCAAmC;QACnC,oCAAoC;QACpC,kCAAkC;QAClC,4BAA4B;QAC5B,0BAA0B;QAC1B,mBAAmB;KACpB,EAAE,CAAC;QACF,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,CAAC,KAAK;YAAE,SAAS;QACrB,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACxB,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;YAC9B,wEAAwE;YACxE,6DAA6D;YAC7D,MAAM,EAAE,GAAG,OAAO,GAAG,aAAa,CAAC,CAAC,CAAC,OAAO,GAAG,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC;YAC3E,IAAI,EAAE,GAAG,CAAC;gBAAE,OAAO,EAAE,CAAC;QACxB,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC/B,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,GAAG,GAAG,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,kFAAkF;AAClF,KAAK,UAAU,QAAQ,CAAC,QAAgB,EAAE,GAAa;IACrD,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;IAC9C,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC5C,MAAM,OAAO,GAAG,IAAI;QAClB,CAAC,CAAC,GAAG,QAAQ,IAAI,GAAG,CAAC,MAAM,KAAK,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE;QACpD,CAAC,CAAC,GAAG,QAAQ,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC;IAClD,OAAO,IAAI,aAAa,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE;QAChD,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,YAAY,EAAE,qBAAqB,CAAC,GAAG,CAAC,OAAO,CAAC;QAChD,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,IAAI,SAAS;KACxC,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,IAAI,CAAC,IAAkB;IACpC,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,IAAI,UAAU,CAAC,KAAK,CAAC;IACnD,IAAI,CAAC;QACH,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE;YAC7B,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE;YAChE,IAAI,EAAE,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC;YAC3E,MAAM,EAAE,IAAI,CAAC,MAAM;SACpB,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,0EAA0E;QAC1E,mEAAmE;QACnE,2DAA2D;QAC3D,IAAI,IAAI,CAAC,MAAM,EAAE,OAAO,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC;YAAE,MAAM,GAAG,CAAC;QAChE,MAAM,IAAI,aAAa,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,oBAAoB,IAAI,CAAC,GAAG,EAAE,EAAE;YAChF,KAAK,EAAE,GAAG;SACX,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAc,IAAkB;IAC5D,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,CAAC,GAAG,CAAC,EAAE;QAAE,MAAM,MAAM,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACtD,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAM,CAAC;AACjC,CAAC;AAED;;6BAE6B;AAC7B,SAAS,SAAS,CAAC,KAAa;IAC9B,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACrC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;YAAE,SAAS;QACxC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;IAC9C,CAAC;IACD,kEAAkE;IAClE,yEAAyE;IACzE,wEAAwE;IACxE,2EAA2E;IAC3E,iEAAiE;IACjE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IAC5C,CAAC;IACD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;IACxC,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;AAC7C,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,cAAc,CAAC,IAAgC;IACpE,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;IAChC,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;IAClC,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,IAAI,CAAC;QACH,SAAS,CAAC;YACR,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;YAC5C,IAAI,IAAI;gBAAE,MAAM;YAChB,wEAAwE;YACxE,sEAAsE;YACtE,uEAAuE;YACvE,6DAA6D;YAC7D,MAAM,GAAG,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;YAEnF,IAAI,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YACtC,OAAO,QAAQ,KAAK,CAAC,CAAC,EAAE,CAAC;gBACvB,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;gBACxC,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC;gBACpC,MAAM,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;gBACjC,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,QAAQ;oBAAE,MAAM,OAAO,CAAC;gBAC5D,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YACpC,CAAC;QACH,CAAC;QACD,wEAAwE;QACxE,gEAAgE;QAChE,MAAM,IAAI,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;QAC/B,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,QAAQ;YAAE,MAAM,IAAI,CAAC;IACrD,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,WAAW,EAAE,CAAC;IACvB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,SAAS,CAAC,IAAkB;IACjD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,CAAC,GAAG,CAAC,EAAE;QAAE,MAAM,MAAM,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACtD,yEAAyE;IACzE,2CAA2C;IAC3C,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;QACd,MAAM,IAAI,aAAa,CAAC,IAAI,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC,QAAQ,uBAAuB,EAAE;YAC1F,MAAM,EAAE,GAAG,CAAC,MAAM;SACnB,CAAC,CAAC;IACL,CAAC;IACD,KAAK,CAAC,CAAC,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAClC,CAAC"}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@providerkit/core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "The layer under your agent loop: one seam for every LLM provider, plus the failure handling you only learn in production.",
   "type": "module",
   "license": "MIT",
-  "author": "Gustavo Salom\u00e9",
+  "author": "Gustavo Salomé",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",

package/src/context.ts

@@ -56,6 +56,13 @@ export function conversationTokens(messages: readonly ChatMessage[]): number {
  * that is not a guess. Estimate only when there is no reported count yet.
  */
 export function needsCompaction(inputTokens: number, contextWindow: number): boolean {
+  // A window at or below the reserve puts the threshold at zero or less, and
+  // every turn — including one that has not reported usage yet — then reads as
+  // already full. That loops: folding a history this side of its first answer
+  // changes nothing, so the next check says the same thing. Small windows are
+  // not hypothetical; a caller that learns a real ceiling from a rejection
+  // (rather than guessing one) can legitimately arrive here with 8k.
+  if (inputTokens <= 0) return false;
   return inputTokens >= contextWindow - CONTEXT_RESERVE_TOKENS;
 }
 

package/src/errors.ts

@@ -221,6 +221,12 @@ export function isTransportFailure(err: unknown): boolean {
     const message = readString(current, "message");
     if (name === "APIConnectionError" || name === "APIConnectionTimeoutError") return true;
     if (code !== undefined && TRANSPORT_CODES.has(code)) return true;
+    // undici — Node's fetch, and Bun's — parks the real reason in `code` while
+    // the thrown error says only "terminated", which is the most common way a
+    // stream dies mid-body. Its whole family shares one prefix; enumerating
+    // them ages badly, the prefix does not. UND_ERR_ABORTED is the caller's
+    // Stop wearing the same prefix, and is never ours to retry.
+    if (code?.startsWith("UND_ERR_") && code !== "UND_ERR_ABORTED") return true;
     // A bare TypeError is also what a real bug throws ("x is not a function"),
     // so the MESSAGE is checked, not just the type — misfiling one of those
     // would retry a genuine bug three times and hide it.
@@ -274,7 +280,6 @@ const QUOTA_PATTERNS: readonly RegExp[] = [
   /upgrade your plan/i,
   /quota\b[^.]{0,40}\b(?:exhausted|exceeded|will be refreshed)/i,
   /balance (?:is )?(?:too low|not enough|insufficient)/i,
-  /per\s*day|PerDay|insufficient_quota|billing/i,
   /余额不足/,
   /欠费/,
   /额度(?:不足|已用完)/,
@@ -300,6 +305,21 @@ const CONTENT_PATTERNS: readonly RegExp[] = [
   /safety|PROHIBITED_CONTENT|blocked|refusal/i,
 ];
 
+/**
+ * A throttle said in words rather than in a 429.
+ *
+ * Every other kind has body evidence; rate had only the status, which is
+ * exactly the evidence an in-band failure lacks — an SSE response is already
+ * 200 when the throttle lands, so the reason arrives as a payload with no
+ * status line at all. Checked below the status branches, so it only ever
+ * catches what would otherwise fall through to "unknown".
+ */
+const RATE_PATTERNS: readonly RegExp[] = [
+  /rate[_\s-]?limit/i,
+  /too many requests/i,
+  /RESOURCE_EXHAUSTED/,
+];
+
 /** Theirs and temporary, said in words rather than a status. Gemini reports
  *  UNAVAILABLE/INTERNAL in the body; gateways say "capacity". */
 const OVERLOAD_PATTERNS: readonly RegExp[] = [
@@ -320,6 +340,21 @@ const matches = (patterns: readonly RegExp[], text: string): boolean =>
  * entitlement beats quota beats auth — each earlier category's fix is useless
  * for the later ones.
  */
+/**
+ * The kind of a failure that arrived as an HTTP response — a status and a body,
+ * with nothing thrown.
+ *
+ * `classify` below is for a caught error, and it reads `status` and the body
+ * text off that error when they are not passed separately. A response has no
+ * error object, so callers were inventing one to fill the slot: a bare body
+ * string, the same text twice, a `{ status, error }` literal. All three are
+ * inert — nothing on them can satisfy `isAbort` or `isTransportFailure` — so
+ * they were three spellings of `undefined`.
+ */
+export function classifyHttp(status: number | undefined, body: string): ErrorKind {
+  return classify(undefined, status, body);
+}
+
 export function classify(err: unknown, status?: number, body?: string): ErrorKind {
   if (isAbort(err)) return "aborted";
   if (isTransportFailure(err)) return "network";
@@ -348,6 +383,7 @@ export function classify(err: unknown, status?: number, body?: string): ErrorKin
   // "the model is still loading" — both are worth another attempt.
   if (code === 529 || code === 409) return "overload";
   if (code !== undefined && code >= 500) return "overload";
+  if (matches(RATE_PATTERNS, text)) return "rate";
   if (matches(OVERLOAD_PATTERNS, text)) return "overload";
   if (/timed out|timeout/i.test(text)) return "timeout";
   if (code !== undefined && code >= 400) return "invalid";
@@ -380,6 +416,48 @@ export function parseRetryAfterMs(err: unknown, body?: string): number | undefin
   return Number.isNaN(date) ? undefined : Math.max(0, date - Date.now());
 }
 
+/**
+ * A failure the backend reports INSIDE an already-200 stream.
+ *
+ * The transport classified everything that failed before the body opened; this
+ * is the rest, and every streaming shape has the same hole. An SSE response
+ * commits to 200 the moment its headers go out, so a throttle, an overload, or
+ * a prompt found too long after the fact arrives as a payload in the body
+ * rather than as a status line. Left unread it matches no branch an adapter
+ * models, the loop skips it, and the turn ends as a successful zero-token
+ * completion: retry sees nothing to retry, and a key pool never rotates off an
+ * exhausted key.
+ *
+ * `error` is the vendor's own payload, whatever shape it came in — the numeric
+ * HTTP `code` Gemini and OpenRouter use, the slug OpenAI and Anthropic put in
+ * `code`/`type`, the canonical `status` name. The whole thing serializes into
+ * the searchable body, so RetryInfo's `retryDelay` is honoured wherever it sits.
+ *
+ * `unknown` is floored to "overload" rather than kept: a stream that dies after
+ * its headers is by construction a transient upstream fault, and "unknown" is
+ * never retried. Everything the body DOES name keeps its own kind — which is
+ * what tells the caller to wait, rotate a key, or compact instead of retrying
+ * a failure that will repeat.
+ */
+export function streamError(provider: string, error: unknown): ProviderError {
+  const body = JSON.stringify(error ?? {}) ?? "";
+  const status = readNumber(error, "code") ?? readNumber(error, "status");
+  const code =
+    readString(error, "code") ?? readString(error, "status") ?? readString(error, "type");
+  const kind = classifyHttp(status, body);
+  return new ProviderError(
+    provider,
+    kind === "unknown" ? "overload" : kind,
+    `${provider} stream error: ${readString(error, "message") ?? code ?? "no reason given"}`,
+    {
+      ...(status !== undefined ? { status } : {}),
+      ...(code ? { code } : {}),
+      retryAfterMs: parseRetryAfterMs(error, body),
+      body: body.slice(0, 2_000),
+    },
+  );
+}
+
 /** The loggable surface of a failure — so a dead run never reads
  *  "400 status code (no body)". */
 export function describeProviderError(err: unknown): Record<string, unknown> {

package/src/index.ts

@@ -1,12 +1,16 @@
 export * from "./types.ts";
 export * from "./errors.ts";
 export * from "./retry.ts";
+export * from "./key-pool.ts";
 export * from "./watchdog.ts";
 export * from "./usage.ts";
 export * from "./transport.ts";
+export * from "./rate-limit.ts";
 export * from "./tool-args.ts";
 export * from "./tools.ts";
 export * from "./schema.ts";
 export * from "./context.ts";
 export * from "./providers/anthropic.ts";
 export * from "./providers/openai.ts";
+export * from "./providers/responses.ts";
+export * from "./providers/gemini.ts";

package/src/key-pool.ts

@@ -0,0 +1,272 @@
+// A rotating pool of API keys for one provider.
+//
+// Rate limits are scoped per project or per account, so several keys multiply
+// throughput. Free-tier keys go first, round-robin, and the paid key last —
+// free quota burns before money. A key that answers 429 is benched for the
+// delay the provider named (Retry-After, or Gemini's RetryInfo; else a minute,
+// and an hour when the body says the balance or the daily window is gone), a
+// denied key for 12 h (durable, but key-specific — one dead key must not take
+// the pool down with it), an overload only briefly, because a sibling project's
+// key routes to a different backend.
+//
+// With ONE key there is nothing to rotate to, so NOTHING is evicted and the
+// error propagates untouched: a transient 503 must not switch a single-key
+// deployment off for a minute, where the caller's own retry is the whole
+// recovery there is.
+import { isTransient, ProviderError } from "./errors.ts";
+import type { ErrorKind } from "./errors.ts";
+import type {
+  ChatMessage,
+  Provider,
+  ProviderChunk,
+  StreamOptions,
+  ToolDefinition,
+} from "./types.ts";
+
+/** A per-minute throttle: the window it names is the next one. */
+const RATE_COOLDOWN_MS = 60_000;
+/** A balance or a daily window — minutes will not bring it back. */
+const QUOTA_COOLDOWN_MS = 60 * 60_000;
+const AUTH_COOLDOWN_MS = 12 * 60 * 60_000;
+/** The vendor's bad time, not the key's — benched only long enough for the
+ *  next call to land somewhere else. */
+const TRANSIENT_COOLDOWN_MS = 60_000;
+const MIN_EVICTION_MS = 1_000;
+const MAX_EVICTION_MS = 12 * 60 * 60_000;
+
+export type KeyTier = "free" | "paid";
+
+interface PoolKey {
+  apiKey: string;
+  tier: KeyTier;
+  /** Epoch ms until which the key is out; 0 = available. */
+  evictedUntil: number;
+}
+
+export interface KeyPoolOptions {
+  /** Free-tier keys, walked round-robin before the paid one. */
+  keys: readonly string[];
+  paidKey?: string | null;
+  /** Fires whenever a key is benched — the pool's only report, in place of a
+   *  logger a zero-dependency package has no business owning. */
+  onEvict?: (info: { tier: KeyTier; kind: ErrorKind; forMs: number }) => void;
+  /** Injected in tests, so an expiry can be exercised without waiting out a
+   *  12-hour cooldown. */
+  now?: () => number;
+}
+
+/** No key can serve right now. `retryAtMs` = when the soonest one is back. */
+export class NoAvailableKeyError extends Error {
+  readonly retryAtMs: number;
+
+  constructor(label: string, retryAtMs: number) {
+    super(`No ${label} API key available (all rate-limited or denied)`);
+    this.name = "NoAvailableKeyError";
+    this.retryAtMs = retryAtMs;
+  }
+}
+
+export class KeyPool {
+  private readonly label: string;
+  private readonly free: PoolKey[];
+  private readonly paid: PoolKey | null;
+  private readonly onEvict: KeyPoolOptions["onEvict"];
+  private readonly now: () => number;
+  private cursor = 0;
+
+  constructor(label: string, opts: KeyPoolOptions) {
+    this.label = label;
+    // A blank slot in the caller's config is not a key — an absent env var
+    // reads as "" and would otherwise be dialled once per rotation.
+    this.free = opts.keys
+      .filter(Boolean)
+      .map((apiKey): PoolKey => ({ apiKey, tier: "free", evictedUntil: 0 }));
+    this.paid = opts.paidKey ? { apiKey: opts.paidKey, tier: "paid", evictedUntil: 0 } : null;
+    this.onEvict = opts.onEvict;
+    this.now = opts.now ?? Date.now;
+    if (this.free.length === 0 && !this.paid) {
+      throw new Error(`KeyPool(${this.label}) needs at least one key`);
+    }
+  }
+
+  get size(): number {
+    return this.free.length + (this.paid ? 1 : 0);
+  }
+
+  /**
+   * Run `fn` with the next available key, rotating on key-specific and
+   * transient failures. Everything else (a bad request, a content block) throws
+   * straight through — it would fail identically on every key, and spending the
+   * pool on it only turns one bad request into an outage.
+   */
+  async with<T>(fn: (apiKey: string, tier: KeyTier) => Promise<T>): Promise<T> {
+    const candidates = this.candidates(this.now());
+    if (candidates.length === 0) throw new NoAvailableKeyError(this.label, this.nextAvailableAt());
+
+    let last: unknown;
+    for (const key of candidates) {
+      try {
+        return await fn(key.apiKey, key.tier);
+      } catch (err) {
+        last = err;
+        // The single-key rule: with nothing to rotate to, benching the only key
+        // answers NoAvailableKeyError to every call for the next minute — for a
+        // failure the caller's own retry would have absorbed.
+        const cooldown = this.size > 1 ? cooldownFor(err) : null;
+        if (cooldown === null) throw err;
+        key.evictedUntil = this.now() + cooldown.forMs;
+        this.onEvict?.({ tier: key.tier, kind: cooldown.kind, forMs: cooldown.forMs });
+      }
+    }
+
+    // Every candidate was evicted during this call.
+    if (this.candidates(this.now()).length === 0)
+      throw new NoAvailableKeyError(this.label, this.nextAvailableAt());
+    throw last;
+  }
+
+  /** Free keys round-robin from a moving cursor, then the paid key. */
+  private candidates(now: number): PoolKey[] {
+    const out: PoolKey[] = [];
+    const n = this.free.length;
+    for (let i = 0; i < n; i++) {
+      const key = this.free[(this.cursor + i) % n]!;
+      if (key.evictedUntil <= now) out.push(key);
+    }
+    if (n > 0) this.cursor = (this.cursor + 1) % n;
+    if (this.paid && this.paid.evictedUntil <= now) out.push(this.paid);
+    return out;
+  }
+
+  private nextAvailableAt(): number {
+    const all = this.paid ? [...this.free, this.paid] : this.free;
+    return Math.min(...all.map((key) => key.evictedUntil));
+  }
+}
+
+/**
+ * How long to bench a key for this failure, or null when the failure is not the
+ * key's fault — nothing is gained by rotating, and benching would spend the
+ * pool on a request that fails the same way everywhere.
+ */
+function cooldownFor(err: unknown): { kind: ErrorKind; forMs: number } | null {
+  if (!(err instanceof ProviderError)) return null;
+  const clamp = (ms: number) => Math.min(Math.max(ms, MIN_EVICTION_MS), MAX_EVICTION_MS);
+  switch (err.kind) {
+    // The three kinds that are about THIS key.
+    case "rate":
+      return { kind: err.kind, forMs: clamp(err.retryAfterMs ?? RATE_COOLDOWN_MS) };
+    case "quota":
+      return { kind: err.kind, forMs: clamp(err.retryAfterMs ?? QUOTA_COOLDOWN_MS) };
+    case "auth":
+      // 12 h, not forever: a key is also refused while a billing account is
+      // reinstated, and a pool that drops keys permanently ends up empty.
+      return { kind: err.kind, forMs: AUTH_COOLDOWN_MS };
+    default:
+      // Not the key's fault, but a sibling key is a different project on a
+      // different backend, so one more call is the cheapest way to find out —
+      // which is what an overload or a stalled request is worth. `network` is
+      // excluded deliberately: the socket died on our side and dies identically
+      // on every key, so benching for it would answer NoAvailableKeyError to
+      // what is really "no internet".
+      return isTransient(err.kind) && err.kind !== "network"
+        ? { kind: err.kind, forMs: TRANSIENT_COOLDOWN_MS }
+        : null;
+  }
+}
+
+/**
+ * Give any provider a rotating pool of keys.
+ *
+ * The subtlety is the seam's shape. `createStream` is an async generator, so
+ * CALLING it performs no I/O: the POST — and the 429 that should rotate the key
+ * — happens on the first `next()`, long after a `pool.with` wrapped around the
+ * call itself would have returned, with nothing left to rotate. So the first
+ * chunk is pulled INSIDE the pool and only the rest of the stream is consumed
+ * outside it.
+ *
+ * That line is also the honest one. Past the first chunk the answer is
+ * committed to one key, exactly as a retry is committed past its first chunk
+ * (retry.ts, rule 2): a mid-stream 429 evicts nothing and rotates nothing,
+ * because there is no way to resume a half-rendered answer on another key.
+ */
+export function withKeyPool(pool: KeyPool, factory: (apiKey: string) => Provider): Provider {
+  // The identity every key shares. Building an adapter performs no I/O — it
+  // closes over its config and nothing else — so a throwaway instance is the
+  // cheapest way to read `id` and `model` without holding a key outside the
+  // pool.
+  const identity = factory("");
+
+  return {
+    id: identity.id,
+    model: identity.model,
+
+    async *createStream(
+      messages: ChatMessage[],
+      tools: ToolDefinition[],
+      opts: StreamOptions = {},
+    ): AsyncIterable<ProviderChunk> {
+      const opened = await pool.with(async (apiKey) => {
+        // One AbortController per attempt, chained to the caller's own signal
+        // (retry.ts's rule). Finalizing a generator is not cancellation:
+        // `return()` unwinds the adapter down to `streamSse`'s finalizer, which
+        // only releases the reader's lock — the response body stays live and
+        // the request is never aborted. Without this controller an abandoned
+        // attempt keeps the provider generating the rest of the answer, holding
+        // a connection and a concurrency slot on the very key the pool is
+        // rotating away from.
+        const controller = new AbortController();
+        const onAbort = () => controller.abort(opts.signal?.reason);
+        if (opts.signal?.aborted) onAbort();
+        else opts.signal?.addEventListener("abort", onAbort, { once: true });
+
+        const stream = factory(apiKey).createStream(messages, tools, {
+          ...opts,
+          signal: controller.signal,
+        });
+        const iterator = stream[Symbol.asyncIterator]();
+        const release = async () => {
+          opts.signal?.removeEventListener("abort", onAbort);
+          await close(iterator);
+          controller.abort();
+        };
+
+        try {
+          return { iterator, first: await iterator.next(), release };
+        } catch (err) {
+          // The request failed under the pool, which is about to try the next
+          // key: release this attempt before a second one opens against the
+          // same rate limit.
+          await release();
+          throw err;
+        }
+      });
+
+      const { iterator, first, release } = opened;
+      try {
+        if (first.done) return;
+        yield first.value;
+        for (;;) {
+          const next = await iterator.next();
+          if (next.done) return;
+          yield next.value;
+        }
+      } finally {
+        // A consumer that breaks out of its loop never reaches the end of ours,
+        // and an attempt left unfinalized and un-aborted streams for the whole
+        // rest of the answer into a body nobody reads.
+        await release();
+      }
+    },
+  };
+}
+
+/** Finalize an abandoned stream. `return()` can reject on its own (an aborted
+ *  body), and that must never replace the failure being handled. */
+async function close(iterator: AsyncIterator<ProviderChunk>): Promise<void> {
+  try {
+    await iterator.return?.();
+  } catch {
+    // The request is being abandoned either way.
+  }
+}