ai-lcr 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to `ai-lcr` are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/), and the project adheres to
+[Semantic Versioning](https://semver.org/).
+
+## [0.2.3] — 2026-06-01
+
+Release-quality and engine-correctness pass.
+
+### Fixed
+
+- **Build was red on `main`.** `media.ts` set `CallRecord.baselineUsd` but the
+  type never declared it, so `tsc`/`npm run build` failed while `npm test`
+  (which doesn't typecheck) stayed green. `baselineUsd?: number` is now part of
+  `CallRecord`. The text router leaves it `undefined`; the media router sets it.
+- **Failover used shared mutable state across concurrent requests.** The active
+  provider index was an instance field used both as the per-request loop cursor
+  and the loop's termination check. Two requests sharing one model instance
+  could clobber each other's cursor mid-flight (skipped providers, wrong
+  termination). Each request now walks providers on a fully local cursor; the
+  only shared state is a "where to start next" hint, read once and written once.
+- **Cheapest provider was never re-probed under sustained traffic.** The
+  snap-back-to-cheapest timer reset on *every* call, so with calls more frequent
+  than `resetIntervalMs` it never fired — one blip pinned you on the expensive
+  fallback indefinitely (exactly when spend is highest). The timer now measures
+  from the last *failover*, so re-probe fires under load too.
+
+### Added
+
+- **`classifyErrorKind(error)` and `RouteAttempt.kind`** (`"transient" | "auth"
+  | "billing" | "client"`). 401/403 (auth) and 402/out-of-credit (billing)
+  still fail over so the request survives — but they're now tagged distinctly
+  from transient 429/5xx, so a misconfigured key silently burning the pricey
+  fallback is something you can alert on instead of mistaking for healthy
+  routing.
+- **Continuous Integration** (`.github/workflows/ci.yml`): `build` +
+  `typecheck` + `test` on Node 20 & 22, plus a `pack-smoke` job that installs
+  the actual `npm pack` tarball into a clean directory and imports it (ESM and
+  CJS) — catching dropped exports and broken `dist` that an in-repo test can't.
+- **`prepublishOnly` gate**: `npm publish` now runs build + typecheck + test
+  first, so a red tree can't be published.
+- **Public-export surface test** (`public-api.test.ts`): pins every runtime
+  export by name, so removing one fails loudly and adding one is deliberate.
+
+## [0.2.1] — earlier
+
+- `onCall` correlated `CallRecord` + `formatCallRecord` one-liner for the text
+  router, extended to the media router (image/video).
+
+## [0.2.0] — earlier
+
+- Observability: `onCall` / `CallRecord`, `formatCallRecord`.
+
+## [0.1.x] — earlier
+
+- Dual ESM/CJS build. Media (image/video) least-cost routing with the Runware
+  and Kunavo adapters; cap-aware failover for the text router.
+
+[0.2.3]: https://github.com/victorzhrn/ai-lcr/releases/tag/v0.2.3

package/README.md

@@ -156,7 +156,7 @@ Any OpenAI-compatible endpoint works — and so does any AI SDK provider package
 
 - **Model vendors' own APIs (native):** route straight to [DeepSeek](https://platform.deepseek.com), [OpenAI](https://openai.com), [Anthropic](https://anthropic.com), [Google](https://ai.google.dev), [xAI](https://x.ai), etc. via their AI SDK provider packages — no markup, full native features. See [Route to a model vendor's own API](#route-to-a-model-vendors-own-api-native-providers).
 - **Text aggregators:** [OpenRouter](https://openrouter.ai) (widest coverage, list pricing) · [Kunavo](https://kunavo.com/?ref=victorimf) (**20% off** every model) · [TokenMart](https://thetokenmart.ai) (15–65% off, varies by model)
-- **Image / video:** [Kunavo](https://kunavo.com/?ref=victorimf) (**20% off**) · [TokenMart](https://thetokenmart.ai) · [fal.ai](https://fal.ai) · [Runware](https://runware.ai) — routing via `createMediaLCR`. Image: Kunavo + Runware + fal. Video: fal (live, via its async queue API); Kunavo's Veo poll path is implemented but unverified
+- **Image / video:** [Kunavo](https://kunavo.com/?ref=victorimf) (**20% off**) · [TokenMart](https://thetokenmart.ai) · [fal.ai](https://fal.ai) · [Runware](https://runware.ai) — image routing available via `createMediaLCR` (Kunavo + Runware adapters); video on the roadmap
 
 ## Text model pricing
 
@@ -273,8 +273,7 @@ Two OpenAI-compatible providers, same probe, same day. Cells cover both families
 - [ ] Bundled price table for zero-config pricing (drop the manual `cost` numbers)
 - [ ] Provider-quirk middleware (transparently patch known per-provider request quirks, e.g. Kunavo's ignored `max_tokens`)
 - [ ] Feed probe results into routing automatically (auto-exclude a model from a provider that fails its probe)
-- [x] Image & video model routing (`createMediaLCR`) — image via Kunavo + Runware + fal; **video live via fal** (async queue API)
-- [ ] Normalized cross-provider video price comparison + verified Kunavo/Runware video adapters
+- [ ] Image & video model routing (fal.ai / Runware / Kunavo)
 
 ## Affiliate disclosure
 

package/README.zh-CN.md

@@ -114,7 +114,7 @@ const lcr = createLCR({
 
 - **模型厂商官方 API（原生）：** 通过各自的 AI SDK provider 包直连 [DeepSeek](https://platform.deepseek.com)、[OpenAI](https://openai.com)、[Anthropic](https://anthropic.com)、[Google](https://ai.google.dev)、[xAI](https://x.ai) 等——无加价，原生特性齐全。见上方「直连模型厂商官方 API（原生 provider）」一节。
 - **文本聚合器：** [OpenRouter](https://openrouter.ai)（覆盖最广，列表定价）· [Kunavo](https://kunavo.com/?ref=victorimf)（**全模型 8 折**）· [TokenMart](https://thetokenmart.ai)（按模型 85 折–35 折不等）
-- **图像 / 视频：** [Kunavo](https://kunavo.com/?ref=victorimf)（**8 折**）· [TokenMart](https://thetokenmart.ai) · [fal.ai](https://fal.ai) · [Runware](https://runware.ai) —— 通过 `createMediaLCR` 路由。图像：Kunavo + Runware + fal。视频：fal（已可用，走其异步队列 API）；Kunavo 的 Veo 轮询路径已实现但未验证
+- **图像 / 视频：** [Kunavo](https://kunavo.com/?ref=victorimf)（**8 折**）· [TokenMart](https://thetokenmart.ai) · [fal.ai](https://fal.ai) · [Runware](https://runware.ai) —— 路由功能在路线图中
 
 ## 文本模型价格
 
@@ -229,8 +229,7 @@ API_KEY=$TOKENMART_API_KEY BASE=https://api.tokenmart.ai \
 - [ ] 内置价格表，实现零配置定价（省去手填 `cost` 数字）
 - [ ] provider 怪癖中间件（透明地修补已知怪癖，如 Kunavo 被忽略的 `max_tokens`）
 - [ ] 把 probe 结果自动接入路由（探测失败的 provider×model 自动从列表剔除）
-- [x] 图像与视频模型路由（`createMediaLCR`）—— 图像走 Kunavo + Runware + fal；**视频已可用，走 fal**（异步队列 API）
-- [ ] 归一化的跨 provider 视频价格对比 + 验证 Kunavo/Runware 视频适配器
+- [ ] 图像与视频模型路由（fal.ai / Runware / Kunavo）
 
 ## 联盟（Affiliate）披露
 

package/dist/index.cjs

@@ -21,12 +21,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   DEFAULT_REFERENCE: () => DEFAULT_REFERENCE,
-  FalMediaError: () => FalMediaError,
   MEDIA_PRICING: () => MEDIA_PRICING,
   cheapestRoute: () => cheapestRoute,
   classifyError: () => classifyError,
+  classifyErrorKind: () => classifyErrorKind,
   comparePrices: () => comparePrices,
-  createFalMediaAdapter: () => createFalMediaAdapter,
   createKunavoMediaAdapter: () => createKunavoMediaAdapter,
   createLCR: () => createLCR,
   createMediaLCR: () => createMediaLCR,
@@ -87,6 +86,16 @@ function classifyError(error) {
   const text = (e?.message ? String(e.message) : safeStringify(error)).toLowerCase();
   return RETRYABLE_PATTERNS.find((p) => text.includes(p)) ?? "error";
 }
+var AUTH_STATUS = /* @__PURE__ */ new Set([401, 403]);
+var BILLING_PATTERNS = ["insufficient", "credit", "quota", "billing", "payment required"];
+function classifyErrorKind(error) {
+  const e = error;
+  const status = e?.statusCode ?? e?.status;
+  const text = (e?.message ? String(e.message) : safeStringify(error)).toLowerCase();
+  if (typeof status === "number" && AUTH_STATUS.has(status)) return "auth";
+  if (status === 402 || BILLING_PATTERNS.some((p) => text.includes(p))) return "billing";
+  return isRetryableError(error) ? "transient" : "client";
+}
 var callSeq = 0;
 function newCallId() {
   const c = globalThis.crypto;
@@ -103,11 +112,20 @@ var LcrFallbackModel = class {
   }
   opts;
   specificationVersion = "v3";
-  index = 0;
-  lastReset = Date.now();
+  // Cross-request *hint* for where the next request starts: after a failover we
+  // remember the provider that worked so we don't re-probe a dead cheap one on
+  // every call. This is the ONLY shared mutable state — and crucially it is read
+  // once per request (snapshotted into a local cursor) and written once on
+  // settle, never used as a per-request loop bound. The within-request iteration
+  // is fully local, so concurrent requests can't corrupt each other's routing.
+  sticky = 0;
+  // When `sticky` was last advanced (a failover). The re-probe timer measures
+  // from THIS, not from the last call — so it fires under sustained traffic too,
+  // instead of being pushed forward forever by a busy stream of requests.
+  lastFailoverAt = Date.now();
   resetIntervalMs;
   get current() {
-    return this.opts.providers[this.index];
+    return this.opts.providers[this.sticky];
   }
   get modelId() {
     return this.current.model.modelId;
@@ -118,14 +136,28 @@ var LcrFallbackModel = class {
   get supportedUrls() {
     return this.current.model.supportedUrls;
   }
-  checkReset() {
-    if (this.index !== 0 && Date.now() - this.lastReset >= this.resetIntervalMs) {
-      this.index = 0;
+  /**
+   * Index a new request should start at. If we're parked on a non-cheapest
+   * provider and it's been `resetIntervalMs` since the failover, snap back to
+   * the cheapest and re-probe it — this is what lets routing recover to the
+   * cheap source even during continuous traffic.
+   */
+  startIndex() {
+    if (this.sticky !== 0 && Date.now() - this.lastFailoverAt >= this.resetIntervalMs) {
+      this.sticky = 0;
     }
-    this.lastReset = Date.now();
-  }
-  switchNext() {
-    this.index = (this.index + 1) % this.opts.providers.length;
+    return this.sticky;
+  }
+  /**
+   * A request settled on `winIndex`. Park there so the next request skips the
+   * providers we just learned are down. Stamp the failover time only when the
+   * parked provider actually CHANGES — so a steady stream of successful calls
+   * on the same fallback doesn't keep pushing the re-probe timer forward.
+   */
+  settleSticky(winIndex) {
+    if (winIndex === this.sticky) return;
+    this.sticky = winIndex;
+    this.lastFailoverAt = Date.now();
   }
   shouldRetry(error) {
     return (this.opts.shouldRetry ?? isRetryableError)(error);
@@ -139,7 +171,8 @@ var LcrFallbackModel = class {
       provider: provider.label,
       ok: false,
       latencyMs: Date.now() - attemptStart,
-      errorClass: classifyError(error)
+      errorClass: classifyError(error),
+      kind: classifyErrorKind(error)
     });
   }
   /** Winner settled: record the attempt, fire `onCost` (compat) + `onCall`. */
@@ -184,15 +217,18 @@ var LcrFallbackModel = class {
     });
   }
   async doGenerate(options) {
-    this.checkReset();
     const ctx = this.startCall();
-    const start = this.index;
+    const providers = this.opts.providers;
+    const n = providers.length;
+    const start = this.startIndex();
     let lastError;
-    for (; ; ) {
-      const provider = this.current;
+    for (let tried = 0; tried < n; tried++) {
+      const idx = (start + tried) % n;
+      const provider = providers[idx];
       const attemptStart = Date.now();
       try {
         const result = await provider.model.doGenerate(options);
+        this.settleSticky(idx);
         this.finalizeOk(ctx, provider, attemptStart, result.usage);
         return result;
       } catch (error) {
@@ -204,29 +240,30 @@ var LcrFallbackModel = class {
         }
         this.opts.onError?.(error, provider.label);
         this.recordFail(ctx, provider, attemptStart, error);
-        this.switchNext();
-        if (this.index === start) {
-          this.finalizeFail(ctx);
-          throw lastError;
-        }
       }
     }
+    this.finalizeFail(ctx);
+    throw lastError;
   }
   async doStream(options) {
-    this.checkReset();
-    return this.doStreamWithCtx(options, this.startCall());
-  }
-  // The stream's failover recursion re-enters here with the SAME `ctx`, so a
-  // mid-stream switch keeps appending to one CallRecord instead of starting a
-  // fresh one. `finalizeOk`/`finalizeFail` fire exactly once per outer request.
-  async doStreamWithCtx(options, ctx) {
+    return this.doStreamWithCtx(options, this.startCall(), this.startIndex(), 0);
+  }
+  // The stream's failover recursion re-enters here with the SAME `ctx` and a
+  // threaded-through local cursor (`idx`/`tried`), so a mid-stream switch keeps
+  // appending to one CallRecord and bounds itself on the local `tried` count —
+  // never on shared instance state. `finalizeOk`/`finalizeFail` fire exactly
+  // once per outer request.
+  async doStreamWithCtx(options, ctx, startIdx, alreadyTried) {
     const self = this;
-    const start = this.index;
+    const providers = this.opts.providers;
+    const n = providers.length;
     let result;
     let serving;
     let servingStart;
+    let idx = startIdx;
+    let tried = alreadyTried;
     for (; ; ) {
-      serving = this.current;
+      serving = providers[idx];
       servingStart = Date.now();
       try {
         result = await serving.model.doStream(options);
@@ -239,15 +276,18 @@ var LcrFallbackModel = class {
         }
         this.opts.onError?.(error, serving.label);
         this.recordFail(ctx, serving, servingStart, error);
-        this.switchNext();
-        if (this.index === start) {
+        tried++;
+        if (tried >= n) {
           this.finalizeFail(ctx);
           throw error;
         }
+        idx = (idx + 1) % n;
       }
     }
     const servingProvider = serving;
     const servingAttemptStart = servingStart;
+    const servingIdx = idx;
+    const triedBeforeServing = tried;
     let usage;
     let streamedAny = false;
     const stream = new ReadableStream({
@@ -266,20 +306,26 @@ var LcrFallbackModel = class {
             controller.enqueue(value);
             if (value.type !== "stream-start") streamedAny = true;
           }
+          self.settleSticky(servingIdx);
           self.finalizeOk(ctx, servingProvider, servingAttemptStart, usage);
           controller.close();
         } catch (error) {
           self.opts.onError?.(error, servingProvider.label);
           self.recordFail(ctx, servingProvider, servingAttemptStart, error);
           if (!streamedAny) {
-            self.switchNext();
-            if (self.index === start) {
+            const nextTried = triedBeforeServing + 1;
+            if (nextTried >= n) {
               self.finalizeFail(ctx);
               controller.error(error);
               return;
             }
             try {
-              const next = await self.doStreamWithCtx(options, ctx);
+              const next = await self.doStreamWithCtx(
+                options,
+                ctx,
+                (servingIdx + 1) % n,
+                nextTried
+              );
               const nextReader = next.stream.getReader();
               try {
                 for (; ; ) {
@@ -733,108 +779,6 @@ var RunwareMediaError = class extends Error {
   status;
 };
 
-// src/adapters/fal-media.ts
-var DEFAULT_BASE3 = "https://queue.fal.run";
-function extractOutputs(raw) {
-  if (!raw || typeof raw !== "object") return [];
-  const data = raw;
-  const out = [];
-  const pushUrl = (url, type) => {
-    if (typeof url === "string" && url.length > 0) out.push({ url, type });
-  };
-  if (Array.isArray(data.images)) {
-    for (const img of data.images) pushUrl(img?.url, "image");
-  }
-  pushUrl(data.image?.url, "image");
-  if (Array.isArray(data.videos)) {
-    for (const v of data.videos) pushUrl(v?.url, "video");
-  }
-  pushUrl(data.video?.url, "video");
-  return out;
-}
-function createFalMediaAdapter(config) {
-  const {
-    apiKey,
-    baseUrl = DEFAULT_BASE3,
-    pollIntervalMs = 3e3,
-    pollTimeoutMs = 3e5,
-    fetchImpl = fetch
-  } = config;
-  const headers = {
-    "content-type": "application/json",
-    authorization: `Key ${apiKey}`
-  };
-  return {
-    provider: "fal",
-    async run(req) {
-      const submitRes = await fetchImpl(`${baseUrl}/${req.externalId}`, {
-        method: "POST",
-        headers,
-        body: JSON.stringify(req.input)
-      });
-      if (!submitRes.ok) {
-        throw new FalMediaError(submitRes.status, await safeText2(submitRes));
-      }
-      const submit = await submitRes.json();
-      const statusUrl = submit.status_url;
-      const responseUrl = submit.response_url;
-      if (!statusUrl || !responseUrl) {
-        throw new Error(
-          `ai-lcr: fal submit for "${req.externalId}" returned no status/response URL (keys: ${Object.keys(
-            submit
-          ).join(", ")})`
-        );
-      }
-      const deadline = Date.now() + pollTimeoutMs;
-      let completed = false;
-      while (Date.now() < deadline) {
-        const statusRes = await fetchImpl(statusUrl, { headers });
-        if (!statusRes.ok) {
-          throw new FalMediaError(statusRes.status, await safeText2(statusRes));
-        }
-        const status = String((await statusRes.json()).status ?? "");
-        if (status === "COMPLETED") {
-          completed = true;
-          break;
-        }
-        await sleep2(pollIntervalMs);
-      }
-      if (!completed) {
-        throw new Error(
-          `ai-lcr: fal job for "${req.externalId}" timed out after ${pollTimeoutMs}ms`
-        );
-      }
-      const resultRes = await fetchImpl(responseUrl, { headers });
-      if (!resultRes.ok) {
-        throw new FalMediaError(resultRes.status, await safeText2(resultRes));
-      }
-      const outputs = extractOutputs(await resultRes.json());
-      if (outputs.length === 0) {
-        throw new Error(`ai-lcr: fal returned no media URL for "${req.externalId}"`);
-      }
-      return { outputs, units: outputs.length };
-    }
-  };
-}
-var FalMediaError = class extends Error {
-  constructor(status, body) {
-    super(`fal media HTTP ${status}: ${body.slice(0, 300)}`);
-    this.status = status;
-    this.name = "FalMediaError";
-  }
-  status;
-};
-function sleep2(ms) {
-  return new Promise((r) => setTimeout(r, ms));
-}
-async function safeText2(res) {
-  try {
-    return await res.text();
-  } catch {
-    return "<no body>";
-  }
-}
-
 // src/index.ts
 function isLanguageModel(entry) {
   return typeof entry.doGenerate === "function";
@@ -878,12 +822,11 @@ function createLCR(config) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEFAULT_REFERENCE,
-  FalMediaError,
   MEDIA_PRICING,
   cheapestRoute,
   classifyError,
+  classifyErrorKind,
   comparePrices,
-  createFalMediaAdapter,
   createKunavoMediaAdapter,
   createLCR,
   createMediaLCR,

package/dist/index.d.cts

@@ -5,8 +5,10 @@ import { LanguageModelV3 } from '@ai-sdk/provider';
  *
  * A LanguageModelV3 that wraps an ordered, cheapest-first list of providers:
  * it serves from the first healthy one, switches to the next on a retryable
- * error (streaming-safe), and snaps back to the cheapest after an idle window.
- * It also computes per-call cost from each provider's price and fires `onCost`.
+ * error (streaming-safe), and periodically re-probes the cheapest provider
+ * (every `resetIntervalMs` after a failover — under load too, not only when
+ * idle). It also computes per-call cost from each provider's price and fires
+ * `onCost`.
  *
  * The switching loop is adapted from `ai-fallback` (MIT, © remorses) — its
  * streaming-safe fallback approach — reimplemented here so ai-lcr owns its core
@@ -28,6 +30,17 @@ interface CostEvent {
     /** Computed from the serving provider's `cost`; 0 if no price was given. */
     costUsd: number;
 }
+/**
+ * Coarse error category for a failed attempt — distinct from `errorClass`
+ * (which is the raw status/pattern). Use it to alert: `"auth"` and `"billing"`
+ * mean a config/account problem masquerading as a healthy failover, the thing
+ * you want to page on rather than silently keep burning the pricey fallback.
+ *   - "transient": rate limit / overload / 5xx — expected, self-healing.
+ *   - "auth":      401 / 403 — a misconfigured or revoked key.
+ *   - "billing":   402 / out-of-credit / quota — account needs topping up.
+ *   - "client":    a non-retryable caller error (e.g. 400 bad request).
+ */
+type ErrorKind = "transient" | "auth" | "billing" | "client";
 /** One provider attempt within a single request. */
 interface RouteAttempt {
     /** Provider label that was tried (e.g. "tokenmart"). */
@@ -38,6 +51,8 @@ interface RouteAttempt {
     latencyMs: number;
     /** Normalized failure reason when `ok` is false (e.g. "502", "rate_limit", "timeout"). */
     errorClass?: string;
+    /** Coarse category of the failure when `ok` is false. See {@link ErrorKind}. */
+    kind?: ErrorKind;
 }
 /**
  * One settled request, with its full failover chain. Emitted exactly once per
@@ -65,10 +80,10 @@ interface CallRecord {
     /** Computed from the winner's `cost`; 0 if no price was given or the call failed. */
     costUsd: number;
     /**
-     * What the priciest configured route would have cost for this request, so
-     * `baselineUsd - costUsd` is the saving from routing cheapest-first. Set by
-     * the media router (`createMediaLCR`), where every route has a known price;
-     * omitted by the text router, which can't price a baseline per call.
+     * What the same request would have cost on the most expensive configured
+     * provider — the savings baseline (`baselineUsd - costUsd`). Set by the media
+     * router; the text router omits it (left undefined) until a per-call text
+     * baseline lands. Optional so both routers share one {@link CallRecord} shape.
      */
     baselineUsd?: number;
 }
@@ -79,6 +94,13 @@ interface CallRecord {
  * Reuses the same signals as {@link isRetryableError} — no new vocabulary.
  */
 declare function classifyError(error: unknown): string;
+/**
+ * Categorize an error for alerting. Orthogonal to {@link isRetryableError}
+ * (which decides *whether* to fail over) — this decides *how alarming* the
+ * failover is. A run of `"auth"`/`"billing"` attempts means you're silently
+ * burning the pricey fallback because a key/account is broken: page on it.
+ */
+declare function classifyErrorKind(error: unknown): ErrorKind;
 
 /**
  * Human-readable one-liner for a {@link CallRecord}.
@@ -336,53 +358,6 @@ interface RunwareMediaConfig {
 }
 declare function createRunwareMediaAdapter(config: RunwareMediaConfig): MediaAdapter;
 
-/**
- * fal media adapter — image (queue) + video (queue, async poll).
- *
- * fal serves every model through one async queue API, so a single submit→poll→
- * fetch-result path covers both image and video. That is the whole reason this
- * adapter exists: it is ai-lcr's first VIDEO-capable execution path. (The
- * Runware adapter is image-only; the Kunavo one's video poll loop is unverified.)
- *
- * Implementation note: ai-art's fal adapter uses the `@fal-ai/client` SDK, but
- * ai-lcr deliberately keeps zero provider SDKs — every adapter is raw `fetch`
- * with an injectable `fetchImpl` for testing (see runware-media, kunavo-media).
- * So this re-implements the three queue calls against fal's REST endpoints:
- *
- *   1. submit  POST https://queue.fal.run/{model}        → { request_id, status_url, response_url }
- *   2. status  GET  {status_url}                         → { status: IN_QUEUE | IN_PROGRESS | COMPLETED }
- *   3. result  GET  {response_url}                        → { images:[…] } | { video:{url} } | …
- *
- * We follow the `status_url` / `response_url` returned by submit rather than
- * rebuilding them, which sidesteps fal's sub-path quirk (a model like
- * `fal-ai/flux/schnell` submits to the full path but its status/result live
- * under the `fal-ai/flux` base).
- *
- * Auth: fal uses `Authorization: Key {FAL_KEY}` (NOT Bearer).
- *
- * Cost: fal's queue result does not carry a per-call price, so cost is left to
- * the router's normalized estimate (costCents stays undefined; `units` is the
- * output count — one image, or one clip).
- */
-
-interface FalMediaConfig {
-    apiKey: string;
-    /** Override for testing. Defaults to https://queue.fal.run. */
-    baseUrl?: string;
-    /** Video/job poll cadence (ms). Default 3000. */
-    pollIntervalMs?: number;
-    /** Max time to wait for a job before giving up (ms). Default 300000 (5m). */
-    pollTimeoutMs?: number;
-    /** Injected for testing; defaults to global fetch. */
-    fetchImpl?: typeof fetch;
-}
-declare function createFalMediaAdapter(config: FalMediaConfig): MediaAdapter;
-/** Carries the HTTP status so the router's `isRetryableError` can classify it. */
-declare class FalMediaError extends Error {
-    status: number;
-    constructor(status: number, body: string);
-}
-
 /**
  * ai-lcr — Least Cost Routing for LLMs.
  *
@@ -436,4 +411,4 @@ type LCRRouter = (modelName: string) => LanguageModelV3;
  */
 declare function createLCR(config: LCRConfig): LCRRouter;
 
-export { type CallRecord, type CostEvent, DEFAULT_REFERENCE, FalMediaError, type FormatOptions, type LCRConfig, type LCRRouter, MEDIA_PRICING, type MediaAdapter, type MediaCostEvent, type MediaGenerateRequest, type MediaGenerateResult, type MediaLCRConfig, type MediaModality, type MediaModelDef, type MediaOutput, type MediaPricing, type MediaRegistry, type MediaRoute, type MediaRunResult, type MediaUnit, type PriceComparisonRow, type ProviderCost, type ProviderEntry, type RankedRoute, type ReferenceSpec, type RouteAttempt, cheapestRoute, classifyError, comparePrices, createFalMediaAdapter, createKunavoMediaAdapter, createLCR, createMediaLCR, createRunwareMediaAdapter, formatCallRecord, normalizedCents, rankRoutes, referenceMegapixels };
+export { type CallRecord, type CostEvent, DEFAULT_REFERENCE, type ErrorKind, type FormatOptions, type LCRConfig, type LCRRouter, MEDIA_PRICING, type MediaAdapter, type MediaCostEvent, type MediaGenerateRequest, type MediaGenerateResult, type MediaLCRConfig, type MediaModality, type MediaModelDef, type MediaOutput, type MediaPricing, type MediaRegistry, type MediaRoute, type MediaRunResult, type MediaUnit, type PriceComparisonRow, type ProviderCost, type ProviderEntry, type RankedRoute, type ReferenceSpec, type RouteAttempt, cheapestRoute, classifyError, classifyErrorKind, comparePrices, createKunavoMediaAdapter, createLCR, createMediaLCR, createRunwareMediaAdapter, formatCallRecord, normalizedCents, rankRoutes, referenceMegapixels };

package/dist/index.d.ts

@@ -5,8 +5,10 @@ import { LanguageModelV3 } from '@ai-sdk/provider';
  *
  * A LanguageModelV3 that wraps an ordered, cheapest-first list of providers:
  * it serves from the first healthy one, switches to the next on a retryable
- * error (streaming-safe), and snaps back to the cheapest after an idle window.
- * It also computes per-call cost from each provider's price and fires `onCost`.
+ * error (streaming-safe), and periodically re-probes the cheapest provider
+ * (every `resetIntervalMs` after a failover — under load too, not only when
+ * idle). It also computes per-call cost from each provider's price and fires
+ * `onCost`.
  *
  * The switching loop is adapted from `ai-fallback` (MIT, © remorses) — its
  * streaming-safe fallback approach — reimplemented here so ai-lcr owns its core
@@ -28,6 +30,17 @@ interface CostEvent {
     /** Computed from the serving provider's `cost`; 0 if no price was given. */
     costUsd: number;
 }
+/**
+ * Coarse error category for a failed attempt — distinct from `errorClass`
+ * (which is the raw status/pattern). Use it to alert: `"auth"` and `"billing"`
+ * mean a config/account problem masquerading as a healthy failover, the thing
+ * you want to page on rather than silently keep burning the pricey fallback.
+ *   - "transient": rate limit / overload / 5xx — expected, self-healing.
+ *   - "auth":      401 / 403 — a misconfigured or revoked key.
+ *   - "billing":   402 / out-of-credit / quota — account needs topping up.
+ *   - "client":    a non-retryable caller error (e.g. 400 bad request).
+ */
+type ErrorKind = "transient" | "auth" | "billing" | "client";
 /** One provider attempt within a single request. */
 interface RouteAttempt {
     /** Provider label that was tried (e.g. "tokenmart"). */
@@ -38,6 +51,8 @@ interface RouteAttempt {
     latencyMs: number;
     /** Normalized failure reason when `ok` is false (e.g. "502", "rate_limit", "timeout"). */
     errorClass?: string;
+    /** Coarse category of the failure when `ok` is false. See {@link ErrorKind}. */
+    kind?: ErrorKind;
 }
 /**
  * One settled request, with its full failover chain. Emitted exactly once per
@@ -65,10 +80,10 @@ interface CallRecord {
     /** Computed from the winner's `cost`; 0 if no price was given or the call failed. */
     costUsd: number;
     /**
-     * What the priciest configured route would have cost for this request, so
-     * `baselineUsd - costUsd` is the saving from routing cheapest-first. Set by
-     * the media router (`createMediaLCR`), where every route has a known price;
-     * omitted by the text router, which can't price a baseline per call.
+     * What the same request would have cost on the most expensive configured
+     * provider — the savings baseline (`baselineUsd - costUsd`). Set by the media
+     * router; the text router omits it (left undefined) until a per-call text
+     * baseline lands. Optional so both routers share one {@link CallRecord} shape.
      */
     baselineUsd?: number;
 }
@@ -79,6 +94,13 @@ interface CallRecord {
  * Reuses the same signals as {@link isRetryableError} — no new vocabulary.
  */
 declare function classifyError(error: unknown): string;
+/**
+ * Categorize an error for alerting. Orthogonal to {@link isRetryableError}
+ * (which decides *whether* to fail over) — this decides *how alarming* the
+ * failover is. A run of `"auth"`/`"billing"` attempts means you're silently
+ * burning the pricey fallback because a key/account is broken: page on it.
+ */
+declare function classifyErrorKind(error: unknown): ErrorKind;
 
 /**
  * Human-readable one-liner for a {@link CallRecord}.
@@ -336,53 +358,6 @@ interface RunwareMediaConfig {
 }
 declare function createRunwareMediaAdapter(config: RunwareMediaConfig): MediaAdapter;
 
-/**
- * fal media adapter — image (queue) + video (queue, async poll).
- *
- * fal serves every model through one async queue API, so a single submit→poll→
- * fetch-result path covers both image and video. That is the whole reason this
- * adapter exists: it is ai-lcr's first VIDEO-capable execution path. (The
- * Runware adapter is image-only; the Kunavo one's video poll loop is unverified.)
- *
- * Implementation note: ai-art's fal adapter uses the `@fal-ai/client` SDK, but
- * ai-lcr deliberately keeps zero provider SDKs — every adapter is raw `fetch`
- * with an injectable `fetchImpl` for testing (see runware-media, kunavo-media).
- * So this re-implements the three queue calls against fal's REST endpoints:
- *
- *   1. submit  POST https://queue.fal.run/{model}        → { request_id, status_url, response_url }
- *   2. status  GET  {status_url}                         → { status: IN_QUEUE | IN_PROGRESS | COMPLETED }
- *   3. result  GET  {response_url}                        → { images:[…] } | { video:{url} } | …
- *
- * We follow the `status_url` / `response_url` returned by submit rather than
- * rebuilding them, which sidesteps fal's sub-path quirk (a model like
- * `fal-ai/flux/schnell` submits to the full path but its status/result live
- * under the `fal-ai/flux` base).
- *
- * Auth: fal uses `Authorization: Key {FAL_KEY}` (NOT Bearer).
- *
- * Cost: fal's queue result does not carry a per-call price, so cost is left to
- * the router's normalized estimate (costCents stays undefined; `units` is the
- * output count — one image, or one clip).
- */
-
-interface FalMediaConfig {
-    apiKey: string;
-    /** Override for testing. Defaults to https://queue.fal.run. */
-    baseUrl?: string;
-    /** Video/job poll cadence (ms). Default 3000. */
-    pollIntervalMs?: number;
-    /** Max time to wait for a job before giving up (ms). Default 300000 (5m). */
-    pollTimeoutMs?: number;
-    /** Injected for testing; defaults to global fetch. */
-    fetchImpl?: typeof fetch;
-}
-declare function createFalMediaAdapter(config: FalMediaConfig): MediaAdapter;
-/** Carries the HTTP status so the router's `isRetryableError` can classify it. */
-declare class FalMediaError extends Error {
-    status: number;
-    constructor(status: number, body: string);
-}
-
 /**
  * ai-lcr — Least Cost Routing for LLMs.
  *
@@ -436,4 +411,4 @@ type LCRRouter = (modelName: string) => LanguageModelV3;
  */
 declare function createLCR(config: LCRConfig): LCRRouter;
 
-export { type CallRecord, type CostEvent, DEFAULT_REFERENCE, FalMediaError, type FormatOptions, type LCRConfig, type LCRRouter, MEDIA_PRICING, type MediaAdapter, type MediaCostEvent, type MediaGenerateRequest, type MediaGenerateResult, type MediaLCRConfig, type MediaModality, type MediaModelDef, type MediaOutput, type MediaPricing, type MediaRegistry, type MediaRoute, type MediaRunResult, type MediaUnit, type PriceComparisonRow, type ProviderCost, type ProviderEntry, type RankedRoute, type ReferenceSpec, type RouteAttempt, cheapestRoute, classifyError, comparePrices, createFalMediaAdapter, createKunavoMediaAdapter, createLCR, createMediaLCR, createRunwareMediaAdapter, formatCallRecord, normalizedCents, rankRoutes, referenceMegapixels };
+export { type CallRecord, type CostEvent, DEFAULT_REFERENCE, type ErrorKind, type FormatOptions, type LCRConfig, type LCRRouter, MEDIA_PRICING, type MediaAdapter, type MediaCostEvent, type MediaGenerateRequest, type MediaGenerateResult, type MediaLCRConfig, type MediaModality, type MediaModelDef, type MediaOutput, type MediaPricing, type MediaRegistry, type MediaRoute, type MediaRunResult, type MediaUnit, type PriceComparisonRow, type ProviderCost, type ProviderEntry, type RankedRoute, type ReferenceSpec, type RouteAttempt, cheapestRoute, classifyError, classifyErrorKind, comparePrices, createKunavoMediaAdapter, createLCR, createMediaLCR, createRunwareMediaAdapter, formatCallRecord, normalizedCents, rankRoutes, referenceMegapixels };

package/dist/index.js

@@ -47,6 +47,16 @@ function classifyError(error) {
   const text = (e?.message ? String(e.message) : safeStringify(error)).toLowerCase();
   return RETRYABLE_PATTERNS.find((p) => text.includes(p)) ?? "error";
 }
+var AUTH_STATUS = /* @__PURE__ */ new Set([401, 403]);
+var BILLING_PATTERNS = ["insufficient", "credit", "quota", "billing", "payment required"];
+function classifyErrorKind(error) {
+  const e = error;
+  const status = e?.statusCode ?? e?.status;
+  const text = (e?.message ? String(e.message) : safeStringify(error)).toLowerCase();
+  if (typeof status === "number" && AUTH_STATUS.has(status)) return "auth";
+  if (status === 402 || BILLING_PATTERNS.some((p) => text.includes(p))) return "billing";
+  return isRetryableError(error) ? "transient" : "client";
+}
 var callSeq = 0;
 function newCallId() {
   const c = globalThis.crypto;
@@ -63,11 +73,20 @@ var LcrFallbackModel = class {
   }
   opts;
   specificationVersion = "v3";
-  index = 0;
-  lastReset = Date.now();
+  // Cross-request *hint* for where the next request starts: after a failover we
+  // remember the provider that worked so we don't re-probe a dead cheap one on
+  // every call. This is the ONLY shared mutable state — and crucially it is read
+  // once per request (snapshotted into a local cursor) and written once on
+  // settle, never used as a per-request loop bound. The within-request iteration
+  // is fully local, so concurrent requests can't corrupt each other's routing.
+  sticky = 0;
+  // When `sticky` was last advanced (a failover). The re-probe timer measures
+  // from THIS, not from the last call — so it fires under sustained traffic too,
+  // instead of being pushed forward forever by a busy stream of requests.
+  lastFailoverAt = Date.now();
   resetIntervalMs;
   get current() {
-    return this.opts.providers[this.index];
+    return this.opts.providers[this.sticky];
   }
   get modelId() {
     return this.current.model.modelId;
@@ -78,14 +97,28 @@ var LcrFallbackModel = class {
   get supportedUrls() {
     return this.current.model.supportedUrls;
   }
-  checkReset() {
-    if (this.index !== 0 && Date.now() - this.lastReset >= this.resetIntervalMs) {
-      this.index = 0;
+  /**
+   * Index a new request should start at. If we're parked on a non-cheapest
+   * provider and it's been `resetIntervalMs` since the failover, snap back to
+   * the cheapest and re-probe it — this is what lets routing recover to the
+   * cheap source even during continuous traffic.
+   */
+  startIndex() {
+    if (this.sticky !== 0 && Date.now() - this.lastFailoverAt >= this.resetIntervalMs) {
+      this.sticky = 0;
     }
-    this.lastReset = Date.now();
-  }
-  switchNext() {
-    this.index = (this.index + 1) % this.opts.providers.length;
+    return this.sticky;
+  }
+  /**
+   * A request settled on `winIndex`. Park there so the next request skips the
+   * providers we just learned are down. Stamp the failover time only when the
+   * parked provider actually CHANGES — so a steady stream of successful calls
+   * on the same fallback doesn't keep pushing the re-probe timer forward.
+   */
+  settleSticky(winIndex) {
+    if (winIndex === this.sticky) return;
+    this.sticky = winIndex;
+    this.lastFailoverAt = Date.now();
   }
   shouldRetry(error) {
     return (this.opts.shouldRetry ?? isRetryableError)(error);
@@ -99,7 +132,8 @@ var LcrFallbackModel = class {
       provider: provider.label,
       ok: false,
       latencyMs: Date.now() - attemptStart,
-      errorClass: classifyError(error)
+      errorClass: classifyError(error),
+      kind: classifyErrorKind(error)
     });
   }
   /** Winner settled: record the attempt, fire `onCost` (compat) + `onCall`. */
@@ -144,15 +178,18 @@ var LcrFallbackModel = class {
     });
   }
   async doGenerate(options) {
-    this.checkReset();
     const ctx = this.startCall();
-    const start = this.index;
+    const providers = this.opts.providers;
+    const n = providers.length;
+    const start = this.startIndex();
     let lastError;
-    for (; ; ) {
-      const provider = this.current;
+    for (let tried = 0; tried < n; tried++) {
+      const idx = (start + tried) % n;
+      const provider = providers[idx];
       const attemptStart = Date.now();
       try {
         const result = await provider.model.doGenerate(options);
+        this.settleSticky(idx);
         this.finalizeOk(ctx, provider, attemptStart, result.usage);
         return result;
       } catch (error) {
@@ -164,29 +201,30 @@ var LcrFallbackModel = class {
         }
         this.opts.onError?.(error, provider.label);
         this.recordFail(ctx, provider, attemptStart, error);
-        this.switchNext();
-        if (this.index === start) {
-          this.finalizeFail(ctx);
-          throw lastError;
-        }
       }
     }
+    this.finalizeFail(ctx);
+    throw lastError;
   }
   async doStream(options) {
-    this.checkReset();
-    return this.doStreamWithCtx(options, this.startCall());
-  }
-  // The stream's failover recursion re-enters here with the SAME `ctx`, so a
-  // mid-stream switch keeps appending to one CallRecord instead of starting a
-  // fresh one. `finalizeOk`/`finalizeFail` fire exactly once per outer request.
-  async doStreamWithCtx(options, ctx) {
+    return this.doStreamWithCtx(options, this.startCall(), this.startIndex(), 0);
+  }
+  // The stream's failover recursion re-enters here with the SAME `ctx` and a
+  // threaded-through local cursor (`idx`/`tried`), so a mid-stream switch keeps
+  // appending to one CallRecord and bounds itself on the local `tried` count —
+  // never on shared instance state. `finalizeOk`/`finalizeFail` fire exactly
+  // once per outer request.
+  async doStreamWithCtx(options, ctx, startIdx, alreadyTried) {
     const self = this;
-    const start = this.index;
+    const providers = this.opts.providers;
+    const n = providers.length;
     let result;
     let serving;
     let servingStart;
+    let idx = startIdx;
+    let tried = alreadyTried;
     for (; ; ) {
-      serving = this.current;
+      serving = providers[idx];
       servingStart = Date.now();
       try {
         result = await serving.model.doStream(options);
@@ -199,15 +237,18 @@ var LcrFallbackModel = class {
         }
         this.opts.onError?.(error, serving.label);
         this.recordFail(ctx, serving, servingStart, error);
-        this.switchNext();
-        if (this.index === start) {
+        tried++;
+        if (tried >= n) {
           this.finalizeFail(ctx);
           throw error;
         }
+        idx = (idx + 1) % n;
       }
     }
     const servingProvider = serving;
     const servingAttemptStart = servingStart;
+    const servingIdx = idx;
+    const triedBeforeServing = tried;
     let usage;
     let streamedAny = false;
     const stream = new ReadableStream({
@@ -226,20 +267,26 @@ var LcrFallbackModel = class {
             controller.enqueue(value);
             if (value.type !== "stream-start") streamedAny = true;
           }
+          self.settleSticky(servingIdx);
           self.finalizeOk(ctx, servingProvider, servingAttemptStart, usage);
           controller.close();
         } catch (error) {
           self.opts.onError?.(error, servingProvider.label);
           self.recordFail(ctx, servingProvider, servingAttemptStart, error);
           if (!streamedAny) {
-            self.switchNext();
-            if (self.index === start) {
+            const nextTried = triedBeforeServing + 1;
+            if (nextTried >= n) {
               self.finalizeFail(ctx);
               controller.error(error);
               return;
             }
             try {
-              const next = await self.doStreamWithCtx(options, ctx);
+              const next = await self.doStreamWithCtx(
+                options,
+                ctx,
+                (servingIdx + 1) % n,
+                nextTried
+              );
               const nextReader = next.stream.getReader();
               try {
                 for (; ; ) {
@@ -693,108 +740,6 @@ var RunwareMediaError = class extends Error {
   status;
 };
 
-// src/adapters/fal-media.ts
-var DEFAULT_BASE3 = "https://queue.fal.run";
-function extractOutputs(raw) {
-  if (!raw || typeof raw !== "object") return [];
-  const data = raw;
-  const out = [];
-  const pushUrl = (url, type) => {
-    if (typeof url === "string" && url.length > 0) out.push({ url, type });
-  };
-  if (Array.isArray(data.images)) {
-    for (const img of data.images) pushUrl(img?.url, "image");
-  }
-  pushUrl(data.image?.url, "image");
-  if (Array.isArray(data.videos)) {
-    for (const v of data.videos) pushUrl(v?.url, "video");
-  }
-  pushUrl(data.video?.url, "video");
-  return out;
-}
-function createFalMediaAdapter(config) {
-  const {
-    apiKey,
-    baseUrl = DEFAULT_BASE3,
-    pollIntervalMs = 3e3,
-    pollTimeoutMs = 3e5,
-    fetchImpl = fetch
-  } = config;
-  const headers = {
-    "content-type": "application/json",
-    authorization: `Key ${apiKey}`
-  };
-  return {
-    provider: "fal",
-    async run(req) {
-      const submitRes = await fetchImpl(`${baseUrl}/${req.externalId}`, {
-        method: "POST",
-        headers,
-        body: JSON.stringify(req.input)
-      });
-      if (!submitRes.ok) {
-        throw new FalMediaError(submitRes.status, await safeText2(submitRes));
-      }
-      const submit = await submitRes.json();
-      const statusUrl = submit.status_url;
-      const responseUrl = submit.response_url;
-      if (!statusUrl || !responseUrl) {
-        throw new Error(
-          `ai-lcr: fal submit for "${req.externalId}" returned no status/response URL (keys: ${Object.keys(
-            submit
-          ).join(", ")})`
-        );
-      }
-      const deadline = Date.now() + pollTimeoutMs;
-      let completed = false;
-      while (Date.now() < deadline) {
-        const statusRes = await fetchImpl(statusUrl, { headers });
-        if (!statusRes.ok) {
-          throw new FalMediaError(statusRes.status, await safeText2(statusRes));
-        }
-        const status = String((await statusRes.json()).status ?? "");
-        if (status === "COMPLETED") {
-          completed = true;
-          break;
-        }
-        await sleep2(pollIntervalMs);
-      }
-      if (!completed) {
-        throw new Error(
-          `ai-lcr: fal job for "${req.externalId}" timed out after ${pollTimeoutMs}ms`
-        );
-      }
-      const resultRes = await fetchImpl(responseUrl, { headers });
-      if (!resultRes.ok) {
-        throw new FalMediaError(resultRes.status, await safeText2(resultRes));
-      }
-      const outputs = extractOutputs(await resultRes.json());
-      if (outputs.length === 0) {
-        throw new Error(`ai-lcr: fal returned no media URL for "${req.externalId}"`);
-      }
-      return { outputs, units: outputs.length };
-    }
-  };
-}
-var FalMediaError = class extends Error {
-  constructor(status, body) {
-    super(`fal media HTTP ${status}: ${body.slice(0, 300)}`);
-    this.status = status;
-    this.name = "FalMediaError";
-  }
-  status;
-};
-function sleep2(ms) {
-  return new Promise((r) => setTimeout(r, ms));
-}
-async function safeText2(res) {
-  try {
-    return await res.text();
-  } catch {
-    return "<no body>";
-  }
-}
-
 // src/index.ts
 function isLanguageModel(entry) {
   return typeof entry.doGenerate === "function";
@@ -837,12 +782,11 @@ function createLCR(config) {
 }
 export {
   DEFAULT_REFERENCE,
-  FalMediaError,
   MEDIA_PRICING,
   cheapestRoute,
   classifyError,
+  classifyErrorKind,
   comparePrices,
-  createFalMediaAdapter,
   createKunavoMediaAdapter,
   createLCR,
   createMediaLCR,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-lcr",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Least Cost Routing for LLMs — route every model call to the cheapest available provider, fall back automatically, and track real cost. Built for the Vercel AI SDK.",
   "keywords": [
     "ai",
@@ -39,13 +39,15 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts --clean",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build && npm run typecheck && npm test"
   },
   "peerDependencies": {
     "ai": "^6.0.0"