@bitbaum/ai-kit 0.6.2

package/dist/index.js

@@ -0,0 +1,70 @@
+/**
+ * ai-kit — one install for the AI layer of an app.
+ *
+ * WHAT IT IS FOR
+ * --------------
+ * An app that wants an AI feature needs several unrelated-looking decisions to
+ * go right, and getting any one wrong looks identical from the outside: the
+ * assistant is broken. This package holds all of them, so adding AI is one
+ * decision instead of many.
+ *
+ *   which model  — a fallback list ACROSS VENDORS, because a single pinned free
+ *                  model is a scheduled outage, and a smaller model at the same
+ *                  vendor draws on the same exhausted daily budget.
+ *   still there? — has the vendor retired an id we still ask for? The list is
+ *                  itself a list of pins, so it rots too. Zero tokens, so it can
+ *                  run on a schedule instead of being remembered.
+ *   walk it      — a chain nobody walks is a list, not a fallback. `tryChain`
+ *                  tries each link and stops at the first success; a
+ *                  `HealthTracker` records whether the WHOLE chain came back
+ *                  empty, so a health route can say so before a user does.
+ *   too fast?    — tell the three kinds of 429 apart. They share a status code
+ *                  and need opposite responses; only the body distinguishes them.
+ *   who gets it  — divide a fixed daily pool across active users, so the person
+ *                  who arrives at 4pm still gets a turn.
+ *   filling forms— fill a form from prose and keep talking to it, re-exported
+ *                  from `ai-forms` (see ./forms.ts for why it stays separate).
+ *
+ * WHY IT WAS RENAMED FROM ai-ration
+ * ---------------------------------
+ * Because the owner of this fleet read the name and could not tell what it did.
+ * That is not a cosmetic complaint: an unreadable name is an adoption cost paid
+ * on every single install decision, and this package had ONE adopter while the
+ * five repos that skipped it were all taken down together on 2026-08-26 by a
+ * retired model id — the exact failure the `chain` and `catalog` modules exist
+ * to prevent. "Ration" described one of five modules and buried the other four.
+ *
+ * STILL NOT INCLUDED: an HTTP client. Every app has its own calling conventions,
+ * retries and logging, and replacing those is a rewrite rather than an adoption.
+ * This supplies the decisions; the caller keeps the fetch — `tryChain` is an
+ * orchestrator, not a client: the caller's own `attempt` function makes the
+ * actual request. That rule is under review — `ai-forms`, the most-adopted
+ * package in this fleet, is the one that broke it by shipping a route factory
+ * and a hook.
+ */
+export { providerModels, withEnvPrefix, freeChain, modelCost, modelCostAt, paidModelsIn, dayCapacityTokens, usableChain, chainFrom, } from "./chain.js";
+export { checkCatalog, hasRot, deadProviders, catalogReport, } from "./catalog.js";
+export { ChainExhaustedError, tryChain, } from "./attempt.js";
+export { createHealthTracker, } from "./health.js";
+export { classifyRateLimit, retryAfterSeconds, humanizeWait, rateLimitMessage, } from "./limits.js";
+export { DAY_SECONDS, DEFAULT_BURST, fairShare, utcDayElapsed, utcDayKey, } from "./fair-share.js";
+// Form filling lives at `ai-kit/forms`, NOT here.
+//
+// It was re-exported from this root for one release, so that "adding AI" was a
+// single import as well as a single install. The first app to adopt the merged
+// package showed what that costs: `ai-forms` is ESM-only, so pulling it in from
+// this root made every consumer of the CHAIN load the forms package too — and
+// the app's Jest run, which executes CJS, died on `Unexpected token 'export'`
+// inside a module it never asked for. The fix would have been a
+// `transformIgnorePatterns` entry in that app, and in the next one, and in
+// every app thereafter: one class of breakage, paid per repo, forever.
+//
+// One install is still the promise, and the exports map already keeps it:
+//
+//     import { freeChain } from "@bitbaum/ai-kit";          // the chain
+//     import { defineFields } from "@bitbaum/ai-kit/forms"; // form filling
+//     import { useAssist } from "@bitbaum/ai-kit/react";    // the React hook
+//
+// Same dependency, same version, nothing extra to install — a consumer just
+// stops paying for the half it does not use. That is what subpath exports are
+// for, and collapsing them into the root threw the benefit away.

package/dist/limits.d.ts

@@ -0,0 +1,102 @@
+/**
+ * 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 declare function classifyRateLimit(body: string): RateLimitKind;
+/**
+ * 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 declare function retryAfterSeconds(body: string): number | null;
+/**
+ * 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 declare function humanizeWait(seconds: number | null): string | null;
+/**
+ * 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 declare function rateLimitMessage(raw: string): string;

package/dist/limits.js

@@ -0,0 +1,136 @@
+/**
+ * 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".
+ */
+/**
+ * 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) {
+    // 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) {
+    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) {
+    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) {
+    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/dist/react.d.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/dist/react.js

@@ -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/dist/registry.d.ts

@@ -0,0 +1,133 @@
+/**
+ * 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[];
+};
+/**
+ * Build a registry from entries. Throws on the first contradiction — a
+ * registry that loads is a registry whose billing boundary can be trusted.
+ */
+export declare function defineRegistry(entries: ModelEntry[]): Registry;
+/**
+ * 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 declare function freeOnly(registry: Registry, requested: string[]): {
+    allowed: string[];
+    dropped: {
+        id: string;
+        why: "paid" | "unregistered";
+    }[];
+};
+/**
+ * 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 declare function toolCapable(registry: Registry, requested: string[]): {
+    usable: string[];
+    refused: {
+        id: string;
+        protocol: ToolProtocol;
+    }[];
+};

package/dist/registry.js

@@ -0,0 +1,126 @@
+/**
+ * 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.
+ */
+/** 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) {
+    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) {
+    const seen = new Set();
+    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 = Object.freeze(entries.map((e) => ({ ...e })));
+    const find = (id, vendor) => frozen.find((e) => e.id === id && (vendor === undefined || e.vendor === vendor));
+    return {
+        entries: frozen,
+        find,
+        require(id, vendor) {
+            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) => 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, requested) {
+    const allowed = [];
+    const dropped = [];
+    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, requested) {
+    const usable = [];
+    const refused = [];
+    for (const id of requested) {
+        const entry = registry.find(id);
+        const protocol = entry?.toolProtocol ?? "unprobed";
+        if (protocol === "native" || protocol === "text")
+            usable.push(id);
+        else
+            refused.push({ id, protocol });
+    }
+    return { usable, refused };
+}

package/dist/server.d.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";

package/dist/server.js

@@ -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";