@bitbaum/ai-kit 0.6.2

package/src/limits.ts

@@ -0,0 +1,137 @@
+/**
+ * 429 classification — pure, because the kinds of 429 need OPPOSITE responses
+ * and telling them apart is the whole trick.
+ *
+ * The patterns are calibrated on Groq's wording, because Groq is the vendor that
+ * states its limits precisely enough to learn from. They are applied to every
+ * OpenAI-compatible vendor, which is safe in the direction that matters: an
+ * unrecognisable body falls through to "capacity", whose response (retry, then
+ * degrade) is the harmless one to guess. A vendor that phrases a daily cap
+ * differently is therefore treated as a momentary one — costing a wasted retry,
+ * not a wrong answer. Add its wording here when you meet it.
+ *
+ * A provider returns 429 for three unrelated conditions:
+ *
+ *   CAPACITY — "Rate limit reached ... on tokens per minute (TPM): Limit 12000,
+ *              Used 11800, Requested 400. Please try again in 3.6s"
+ *              The per-MINUTE window is momentarily spent. Waiting helps, and a
+ *              smaller model has its own per-minute budget, so stepping down
+ *              helps too.
+ *
+ *   SIZE     — "Request too large ... Limit 6000, Requested 15041, please
+ *              reduce your message size"
+ *              ONE request exceeds the entire per-minute allowance. Waiting can
+ *              never help: the window never grows big enough. And stepping down
+ *              makes it strictly WORSE, because the cheaper model has a smaller
+ *              ceiling (verified 2026-08-14: llama-3.3-70b-versatile = 12000
+ *              TPM, llama-3.1-8b-instant = 6000). The only cure is a smaller
+ *              prompt.
+ *
+ *   DAILY    — "Rate limit reached ... on tokens per day (TPD): Limit 100000,
+ *              Used 99331, Requested 4589. Please try again in 56m26.88s"
+ *              The budget for the WHOLE DAY is gone, and it is shared across the
+ *              org and across models. Every response that works for capacity is
+ *              actively harmful here: stepping down draws on the SAME exhausted
+ *              budget, and the bounded ~25s wait is nowhere near a reset
+ *              measured in tens of minutes — it just adds dead latency to a turn
+ *              that was already lost.
+ *
+ * Treating SIZE as CAPACITY is what broke Loki's tool loop for every question:
+ * an oversized prompt 429'd, the handler "helpfully" stepped down to the model
+ * with HALF the ceiling, waited 25 pointless seconds, and then gave up — so the
+ * loop fell back to a toolless path on every single turn.
+ *
+ * Treating DAILY as CAPACITY is the same mistake one level deeper, and it is why
+ * this file has three kinds rather than two: the distinction is not "which limit
+ * was hit" but "what, if anything, the caller can do about it".
+ */
+
+export type RateLimitKind = "size" | "capacity" | "daily";
+
+/**
+ * Which kind of 429 this is. Keyed on the body, because the status code alone
+ * cannot tell them apart — all three share the status, the `type`, and the
+ * `code`, and two of the three even share the phrase "tokens per minute (TPM)".
+ * The headers describe the window, not the request, so they cannot decide it
+ * either.
+ *
+ * Daily is tested FIRST: a TPD body also matches the "Rate limit reached"
+ * wording that means capacity, so the more specific limit has to win or the
+ * cheaper check silently absorbs it.
+ *
+ * Defaults to "capacity" when the body is unrecognisable: that path retries and
+ * degrades, where guessing "size" would shed context that was never the problem
+ * and guessing "daily" would give up on a turn that might well have succeeded.
+ */
+export function classifyRateLimit(body: string): RateLimitKind {
+  // Requests-per-day is the same situation as tokens-per-day: nothing the caller
+  // does before the reset can help, so it gets the same treatment.
+  if (/per day|\bTPD\b|\bRPD\b/i.test(body)) return "daily";
+  return /request too large|reduce your message size|reduce the length/i.test(body)
+    ? "size"
+    : "capacity";
+}
+
+/**
+ * The wait the provider itself named, in seconds, or null when it named none.
+ *
+ * Worth parsing rather than approximating because the honest number is the whole
+ * difference between a message a user can act on and one that wastes their time:
+ * "try again shortly" invites an immediate retry, and on a daily cap that retry
+ * is guaranteed to fail for the next hour. Groq states the real figure — the
+ * only reason not to pass it on is not having read it.
+ *
+ * Handles the two shapes the API emits: "3.6s" and "56m26.88s".
+ */
+export function retryAfterSeconds(body: string): number | null {
+  const m = /try again in\s+(?:(\d+(?:\.\d+)?)m)?(?:(\d+(?:\.\d+)?)s)?/i.exec(body);
+  if (!m || (!m[1] && !m[2])) return null;
+  return Math.ceil(Number(m[1] ?? 0) * 60 + Number(m[2] ?? 0));
+}
+
+/**
+ * That wait as something a person reads: "3s", "2 minutes", "about 1 hour".
+ *
+ * The minutes/hours boundary is 60, not 90. At 90 the singular branch below is
+ * unreachable — every value that got that far divided to at least 1.5 hours,
+ * which rounds to 2 — so "about 1 hour" could never be printed and a 90-minute
+ * wait was announced as "about 2 hours". Rounding a wait UP past the reset is
+ * the same disservice as rounding it down: both leave the reader guessing when
+ * to come back.
+ */
+export function humanizeWait(seconds: number | null): string | null {
+  if (seconds === null || !Number.isFinite(seconds) || seconds <= 0) return null;
+  if (seconds < 90) return `${Math.ceil(seconds)}s`;
+  const minutes = Math.ceil(seconds / 60);
+  if (minutes < 60) return `${minutes} minutes`;
+  const hours = Math.round(minutes / 60);
+  return `about ${hours} hour${hours === 1 ? "" : "s"}`;
+}
+
+/**
+ * What to tell the operator when a 429 ends the turn.
+ *
+ * Lives beside the classifier so every caller says the same thing, and because
+ * the message is a direct consequence of the classification: the only useful
+ * content in a rate-limit error is whether retrying can work and when. "Try
+ * again shortly" on an exhausted DAY is the failure reported as "not working" —
+ * technically a rate limit, but it invites exactly the retry that is guaranteed
+ * to fail for the next hour.
+ *
+ * Returns a CLAUSE, not a sentence, because callers embed it in their own
+ * framing ("<assistant> is offline — ..."). It therefore neither capitalises nor
+ * names the assistant, which would read double.
+ */
+export function rateLimitMessage(raw: string): string {
+  const wait = humanizeWait(retryAfterSeconds(raw));
+  switch (classifyRateLimit(raw)) {
+    case "daily":
+      return `the daily model quota is used up${wait ? ` (resets in ${wait})` : ""}`;
+    case "size":
+      // Retrying is not the fix and saying so prevents a pointless loop; the
+      // real repair (a smaller prompt) is ours to make, not the operator's.
+      return "the question needed more context than the model allows in one request";
+    case "capacity":
+      return `the model provider is rate-limited${wait ? ` (retry in ${wait})` : " — try again shortly"}`;
+  }
+}

package/src/react.ts

@@ -0,0 +1,8 @@
+/**
+ * The React form hook, re-exported from `ai-forms/react`.
+ *
+ * Kept on its own subpath so importing `ai-kit` on a server never pulls React
+ * in. `react` is an OPTIONAL peer for exactly this reason: an app using only
+ * the provider chain should not be asked to install a UI library.
+ */
+export * from "ai-forms/react";

package/src/registry.ts

@@ -0,0 +1,207 @@
+/**
+ * The model REGISTRY — one SSOT for every model id an app may call.
+ *
+ * This module exists because the fleet paid for its absence twice, in two
+ * different currencies:
+ *
+ *   OUTAGE — on 2026-08-18 Groq removed `llama-3.3-70b-versatile` and one app
+ *   kept asking for it for eight days. A rot checker already existed, but it
+ *   probed only the chains it knew about; the id that died was pinned
+ *   elsewhere. A checker that does not enumerate its subjects cannot report
+ *   the one it never knew about. The registry IS the enumeration: a model id
+ *   is callable only if it appears here, and the catalog check walks exactly
+ *   this list.
+ *
+ *   MONEY — three apps silently billed real money on fallback, because the
+ *   only thing separating the free variant from the paid one was a `:free`
+ *   suffix on the id string. A billing boundary that lives in a naming
+ *   convention is one typo away from a paid call. Here it is a FIELD, and the
+ *   validator refuses an entry whose flag contradicts its own cost or suffix —
+ *   so the contradiction is a build failure, not an invoice.
+ *
+ * What deliberately does NOT live here: which model to PREFER (that is the
+ * chain's job), UI presentation (labels, badges — app concern), and anything
+ * that knows where data lives. Same boundary as the rest of this package:
+ * meaning in core, adapters in the app.
+ *
+ * ── Vendor vs author ─────────────────────────────────────────────────────────
+ * A registry row is a CALLABLE id at a VENDOR — the place a request goes —
+ * because that is the unit that rots, meters, and bills. The AUTHOR (who
+ * trained it) is metadata. The two were conflated in one app's registry
+ * ("provider: Anthropic" on a row served by OpenRouter), which made "who do we
+ * pay" unanswerable by query. Here they are separate fields.
+ */
+
+/**
+ * How a model answered a live tool-call probe. "unprobed" is a real value, not
+ * a default to ignore: of nine free models probed for the default chain, FIVE
+ * answered only via a text protocol — not guessable from name, size, or docs.
+ * A loop that needs tools should refuse "none" and treat "unprobed" as a
+ * to-do, never as "probably native".
+ */
+export type ToolProtocol = "native" | "text" | "none" | "unprobed";
+
+export type ModelTier = "free" | "economy" | "standard" | "premium";
+
+export type ModelCapability =
+  "text" | "vision" | "function_calling" | "json_mode" | "streaming" | "transcribe";
+
+export type ModelEntry = {
+  /** The id sent on the wire — exactly as the vendor expects it. */
+  id: string;
+  /** Where the call goes (groq, openrouter, together, ollama, …). */
+  vendor: string;
+  /** Who trained it (Anthropic, Meta, Moonshot, …) — metadata, never routing. */
+  author?: string;
+  /** Display name for pickers. Optional: an engine-only entry needs none. */
+  name?: string;
+  /**
+   * THE billing boundary. Required, no default: making the author write
+   * `paid: false` is the whole point — a forgotten field must fail the build,
+   * not silently ride a naming convention.
+   */
+  paid: boolean;
+  /** USD per 1M tokens. Free entries may omit (treated as 0). */
+  inputCostPer1M?: number;
+  outputCostPer1M?: number;
+  contextWindow?: number;
+  maxOutputTokens?: number;
+  tier?: ModelTier;
+  capabilities?: ModelCapability[];
+  /** Verdict of a live tool-call probe. Absent = "unprobed". */
+  toolProtocol?: ToolProtocol;
+  /**
+   * Whether the model accepts a non-default `temperature`. Absent = true.
+   * Current Anthropic frontier models reject non-default sampling params, so
+   * callers must omit the param for entries that say false.
+   */
+  supportsTemperature?: boolean;
+  /**
+   * What breaks when this id stops existing — the text a rot report shows.
+   * Borrowed from the eight-day outage: the fastest diagnosis is the registry
+   * row saying which feature just died.
+   */
+  usedFor?: string;
+  /** Which endpoint shape this id is called on. Default "chat". */
+  kind?: "chat" | "transcribe";
+};
+
+export type Registry = {
+  entries: readonly ModelEntry[];
+  /** Lookup by wire id (optionally scoped to a vendor when ids collide). */
+  find(id: string, vendor?: string): ModelEntry | undefined;
+  /**
+   * The entry, or a THROW naming what depends on it. "A model id is callable
+   * only if it appears here" is only true if the miss is loud.
+   */
+  require(id: string, vendor?: string): ModelEntry;
+  /** Every wire id at one vendor — the enumeration a catalog check walks. */
+  idsForVendor(vendor: string): string[];
+  vendors(): string[];
+  /** Entries the free tier may serve. The platform-key guard filters on THIS. */
+  freeEntries(): ModelEntry[];
+  /** Entries only reachable through someone's money (credits or BYOK). */
+  paidEntries(): ModelEntry[];
+};
+
+/** A `:free`-suffixed id claiming to be paid, or a "free" entry with a price —
+ *  each one is the 2026 billing incident waiting to recur. */
+function validateEntry(e: ModelEntry): string | null {
+  if (!e.id.trim()) return "entry has an empty id";
+  if (!e.vendor.trim()) return `"${e.id}": empty vendor`;
+  const cost = (e.inputCostPer1M ?? 0) + (e.outputCostPer1M ?? 0);
+  if (!e.paid && cost > 0) {
+    return `"${e.id}": declared free but carries a cost (${cost}/1M) — the flag or the price is lying`;
+  }
+  if (e.paid && e.id.endsWith(":free")) {
+    return `"${e.id}": declared paid but the id says :free — the flag or the id is lying`;
+  }
+  return null;
+}
+
+/**
+ * Build a registry from entries. Throws on the first contradiction — a
+ * registry that loads is a registry whose billing boundary can be trusted.
+ */
+export function defineRegistry(entries: ModelEntry[]): Registry {
+  const seen = new Set<string>();
+  for (const e of entries) {
+    const problem = validateEntry(e);
+    if (problem) throw new Error(`ai-kit registry: ${problem}`);
+    const key = `${e.vendor}:${e.id}`;
+    if (seen.has(key)) {
+      throw new Error(
+        `ai-kit registry: duplicate entry ${key} — two rows for one callable id is two sources of truth`,
+      );
+    }
+    seen.add(key);
+  }
+  const frozen: readonly ModelEntry[] = Object.freeze(entries.map((e) => ({ ...e })));
+
+  const find = (id: string, vendor?: string): ModelEntry | undefined =>
+    frozen.find((e) => e.id === id && (vendor === undefined || e.vendor === vendor));
+
+  return {
+    entries: frozen,
+    find,
+    require(id: string, vendor?: string): ModelEntry {
+      const hit = find(id, vendor);
+      if (!hit) {
+        const scope = vendor ? ` at ${vendor}` : "";
+        throw new Error(
+          `ai-kit registry: "${id}"${scope} is not registered — a model id is callable only if it appears in the registry (add it with its paid flag, or stop calling it)`,
+        );
+      }
+      return hit;
+    },
+    idsForVendor: (vendor: string) => frozen.filter((e) => e.vendor === vendor).map((e) => e.id),
+    vendors: () => [...new Set(frozen.map((e) => e.vendor))],
+    freeEntries: () => frozen.filter((e) => !e.paid),
+    paidEntries: () => frozen.filter((e) => e.paid),
+  };
+}
+
+/**
+ * The platform-key guard: the ids from `requested` that a platform-funded
+ * call may serve. Registered-and-free passes; paid is dropped; an UNKNOWN id
+ * is dropped too — an id nobody registered has an unknown price, and "unknown"
+ * spends someone's money only when a person decides it does.
+ *
+ * Returns the dropped ids alongside, because a silently narrowed chain reads
+ * as "covered everything" when it didn't.
+ */
+export function freeOnly(
+  registry: Registry,
+  requested: string[],
+): { allowed: string[]; dropped: { id: string; why: "paid" | "unregistered" }[] } {
+  const allowed: string[] = [];
+  const dropped: { id: string; why: "paid" | "unregistered" }[] = [];
+  for (const id of requested) {
+    const entry = registry.find(id);
+    if (!entry) dropped.push({ id, why: "unregistered" });
+    else if (entry.paid) dropped.push({ id, why: "paid" });
+    else allowed.push(id);
+  }
+  return { allowed, dropped };
+}
+
+/**
+ * A tool-driving chain may only contain models that can drive a tool loop.
+ * "unprobed" entries are reported, not silently trusted — the probe table is
+ * one `npm run probe:models` away, and a chain built on guesses loses turns
+ * exactly on the models most likely to serve free traffic.
+ */
+export function toolCapable(
+  registry: Registry,
+  requested: string[],
+): { usable: string[]; refused: { id: string; protocol: ToolProtocol }[] } {
+  const usable: string[] = [];
+  const refused: { id: string; protocol: ToolProtocol }[] = [];
+  for (const id of requested) {
+    const entry = registry.find(id);
+    const protocol: ToolProtocol = entry?.toolProtocol ?? "unprobed";
+    if (protocol === "native" || protocol === "text") usable.push(id);
+    else refused.push({ id, protocol });
+  }
+  return { usable, refused };
+}

package/src/server.ts

@@ -0,0 +1,10 @@
+/**
+ * The form-assist route factory, re-exported from `ai-forms/server`.
+ *
+ * This is the piece that explains the fleet's adoption numbers. `ai-forms` is
+ * the most-adopted shared package here, and it is also the only one that ships
+ * real machinery rather than decisions alone — AOZ imports this factory and the
+ * React hook, and nothing else. A package that hands you a working route gets
+ * installed; one that hands you advice about routes does not.
+ */
+export * from "ai-forms/server";