@bitbaum/ai-kit 0.6.2

package/src/catalog.ts

@@ -0,0 +1,155 @@
+/**
+ * catalog — has the vendor retired a model this chain still asks for?
+ *
+ * The chain exists because a single pinned free model is a scheduled outage.
+ * That reasoning has a hole: the chain itself is a list of pinned ids, so it
+ * rots too, and a chain whose first vendor is entirely dead is a slower version
+ * of the failure it was built to prevent.
+ *
+ * Not hypothetical. On 2026-08-25 `freeChain()` was checked against the live
+ * catalogues and FOUR of its nine ids were gone — both Groq models (the whole
+ * first vendor) and two OpenRouter ids, one of them the preferred fallback. The
+ * consumer that also used the Groq id for direct, unchained calls had been
+ * silently failing for eight days.
+ *
+ * Why this lives in the package rather than in each app: the check is the same
+ * everywhere, and the app that wrote its own first wrote it slightly
+ * differently. One implementation, shared by name and by value.
+ *
+ * Cheap on purpose — one GET /models per provider and ZERO tokens. That is what
+ * makes it schedulable, which is the whole difference between a check that runs
+ * nightly and a command someone is supposed to remember. A tool-call probe
+ * costs real tokens and cannot run on a timer; existence can.
+ */
+
+import { providerModels, type Env, type Provider } from "./chain.js";
+
+export type CatalogVerdict = {
+  provider: string;
+  /**
+   * Ids the vendor currently lists, or NULL when the catalogue could not be
+   * read (no key, network failure, non-200, unparseable body).
+   *
+   * Null is not an empty list. Treating "I could not look" as "nothing is
+   * there" reports every model as retired and invents an outage; treating it
+   * as "all fine" hides a real one. Callers must handle three states.
+   */
+  live: string[] | null;
+  /** Pinned ids confirmed present. Empty when `live` is null. */
+  present: string[];
+  /** Pinned ids the vendor no longer lists. Empty when `live` is null. */
+  missing: string[];
+  /** Pinned ids whose status is unknown because `live` is null. */
+  unchecked: string[];
+};
+
+export type CheckCatalogOptions = {
+  env?: Env;
+  /** Injectable for tests; defaults to global fetch. */
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+};
+
+/** Ids listed by one provider, or null when the catalogue could not be read. */
+async function liveIds(
+  provider: Provider,
+  key: string,
+  fetchImpl: typeof fetch,
+  timeoutMs: number,
+): Promise<string[] | null> {
+  try {
+    const res = await fetchImpl(`${provider.baseUrl.replace(/\/$/, "")}/models`, {
+      headers: { Authorization: `Bearer ${key}` },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!res.ok) return null;
+    const body = (await res.json()) as { data?: Array<{ id?: unknown }> };
+    if (!Array.isArray(body?.data)) return null;
+    const ids = body.data
+      .map((m) => (typeof m?.id === "string" ? m.id : ""))
+      .filter((id): id is string => id.length > 0);
+    // A catalogue that parses but lists nothing is a malformed answer, not a
+    // vendor with no models. Refusing it keeps a bad response from reading as
+    // total rot.
+    return ids.length > 0 ? ids : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check every model a chain would try against what its vendor still lists.
+ *
+ * Honours the same env overrides `usableChain` does, so it checks the ids this
+ * deployment would ACTUALLY call — not the library defaults an operator has
+ * already routed around.
+ */
+export async function checkCatalog(
+  chain: Provider[],
+  opts: CheckCatalogOptions = {},
+): Promise<CatalogVerdict[]> {
+  const env = opts.env ?? process.env;
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const timeoutMs = opts.timeoutMs ?? 20_000;
+
+  const out: CatalogVerdict[] = [];
+  for (const provider of chain) {
+    const pinned = providerModels(provider, env);
+    const key = env[provider.keyEnv]?.trim();
+    const live = key ? await liveIds(provider, key, fetchImpl, timeoutMs) : null;
+
+    if (!live) {
+      out.push({ provider: provider.id, live: null, present: [], missing: [], unchecked: pinned });
+      continue;
+    }
+    const set = new Set(live);
+    out.push({
+      provider: provider.id,
+      live,
+      present: pinned.filter((m) => set.has(m)),
+      missing: pinned.filter((m) => !set.has(m)),
+      unchecked: [],
+    });
+  }
+  return out;
+}
+
+/** True when any pinned id is confirmed gone. Unchecked providers do NOT count
+ *  — an unreadable catalogue is not evidence of rot. */
+export function hasRot(verdicts: CatalogVerdict[]): boolean {
+  return verdicts.some((v) => v.missing.length > 0);
+}
+
+/** True when a whole vendor's models are gone, i.e. the chain has lost a link
+ *  entirely. Worth separating: a chain that still has vendors is degraded, a
+ *  chain that has lost one is back to being a single point of failure. */
+export function deadProviders(verdicts: CatalogVerdict[]): string[] {
+  return verdicts
+    .filter((v) => v.live !== null && v.present.length === 0 && v.missing.length > 0)
+    .map((v) => v.provider);
+}
+
+/** Human-readable report. Keeps could-not-look visibly distinct from a pass. */
+export function catalogReport(verdicts: CatalogVerdict[]): string {
+  const lines: string[] = [];
+  for (const v of verdicts) {
+    if (v.live === null) {
+      lines.push(
+        `? ${v.provider}: catalogue unreadable (no key, or the request failed) — ${v.unchecked.length} id(s) UNCHECKED`,
+      );
+      for (const m of v.unchecked) lines.push(`    ? ${m}`);
+      continue;
+    }
+    for (const m of v.present) lines.push(`  ok   ${v.provider}/${m}`);
+    for (const m of v.missing) lines.push(`  GONE ${v.provider}/${m}`);
+  }
+  const dead = deadProviders(verdicts);
+  if (dead.length)
+    lines.push(
+      `\nEVERY model is gone at: ${dead.join(", ")} — the chain has lost that vendor entirely.`,
+    );
+  const unchecked = verdicts.reduce((n, v) => n + v.unchecked.length, 0);
+  if (unchecked)
+    lines.push(`\n${unchecked} id(s) could not be checked. That is not a pass for them.`);
+  return lines.join("\n");
+}

package/src/chain.ts

@@ -0,0 +1,318 @@
+/**
+ * The provider CHAIN — a list, never a pin.
+ *
+ * This exists because of a failure that repeated across several projects before
+ * anyone named it: an app picks one free model, ships, and works. Then the model
+ * is retired, or the vendor's daily budget runs out, and the app is simply down
+ * — with an error that looks like a bug in the app rather than an empty tier.
+ * A single pinned free model is not a configuration, it is a scheduled outage.
+ *
+ * Two properties do the work, and BOTH are needed:
+ *
+ *   ACROSS MODELS  — a rotted or momentarily busy model steps aside for the
+ *                    next one.
+ *   ACROSS VENDORS — the one that actually buys headroom. Stepping down to a
+ *                    smaller model at the SAME vendor draws on the SAME org-wide
+ *                    daily budget, so when the day runs dry every link in that
+ *                    "fallback" is already dead. Only a different vendor has a
+ *                    different meter.
+ *
+ * Every provider here speaks the OpenAI chat-completions shape, so adding one is
+ * a row in a table rather than a new client.
+ *
+ * ── Before pinning a model, PROBE IT ─────────────────────────────────────────
+ * A model that cannot emit a parseable tool call cannot drive a tool loop, and
+ * that is not guessable from its name, size, or docs. Of nine free models probed
+ * live for the default chain below, FIVE answered only via a text protocol and
+ * not via native `tool_calls` — so a native-only client would have silently lost
+ * most of the chain. Probe with a real tool call, not a docs page.
+ *
+ * ── Environment is passed in, never read from a global ───────────────────────
+ * Every function here takes `env`, defaulting to `process.env`. That keeps the
+ * module testable without mutating global state, and makes the override points
+ * explicit rather than discovered by grep.
+ */
+
+/** A vendor, its endpoint, and the free models worth trying on it, in order. */
+export type Provider = {
+  /** Display/debug name; also the prefix reported back as the model id. */
+  id: string;
+  baseUrl: string;
+  /** Env var holding the API key. Absent key = entry skipped, not an error. */
+  keyEnv: string;
+  /** Models to try for this provider, in order. */
+  models: string[];
+  /**
+   * Tokens this vendor's FREE tier grants per day, summed into the pool that
+   * fair-share rations. An ESTIMATE unless the vendor states it: handing out
+   * shares of capacity that turns out not to exist produces the exact wall the
+   * rationing exists to prevent, only later in the day and harder to diagnose.
+   * So estimate LOW.
+   */
+  dailyTokens: number;
+  /**
+   * Env var that REPLACES `models` when set (comma/space separated).
+   * Read at CALL time, not at import: the point of this override is routing
+   * around a model that rotted, and a value frozen at module load would need a
+   * redeploy to take effect — which is exactly the delay it exists to avoid.
+   */
+  modelsEnv?: string;
+  /** Env var overriding `dailyTokens` at call time. */
+  dailyTokensEnv?: string;
+  /**
+   * Does this vendor use ROUTED ids, where `vendor/model` names weights it
+   * resells and a `:free` suffix is the difference between free routing and a
+   * per-call charge? True for OpenRouter.
+   *
+   * It matters because the same STRING means different things at different
+   * vendors. `openai/gpt-oss-20b` bills at OpenRouter (no `:free`), while at
+   * Groq it is simply that vendor's name for a model whose cost depends on the
+   * account tier. Deciding cost from the id alone was safe only while
+   * non-routed vendors used bare ids like `llama-3.1-8b-instant`; Groq now
+   * ships vendor-prefixed ids, so the shape no longer identifies the vendor.
+   *
+   * Defaults to false: claiming an id is routed when it is not would report a
+   * free model as paid, and the reverse — assuming free — is the direction
+   * this module exists to refuse.
+   */
+  routed?: boolean;
+};
+
+export type Env = Record<string, string | undefined>;
+
+/** One attempt: a model at a provider. */
+export type Link = { provider: Provider; model: string };
+
+function readEnv(env: Env, name: string | undefined): string | undefined {
+  if (!name) return undefined;
+  return env[name]?.trim() || undefined;
+}
+
+/** Split a comma/space separated env override into model ids. */
+function modelsFromEnv(env: Env, name: string | undefined): string[] | null {
+  const raw = readEnv(env, name);
+  if (!raw) return null;
+  const models = raw.split(/[\s,]+/).filter(Boolean);
+  return models.length > 0 ? models : null;
+}
+
+/** This provider's models, honouring its env override. */
+export function providerModels(provider: Provider, env: Env = process.env): string[] {
+  return modelsFromEnv(env, provider.modelsEnv) ?? provider.models;
+}
+
+/**
+ * Build a provider row whose env var names follow one prefix.
+ *
+ * Saves each app from inventing its own naming and then documenting it: with
+ * prefix "LOKI" a provider `groq` reads LOKI_GROQ_MODELS and
+ * LOKI_GROQ_DAILY_TOKENS. The key env stays explicit because it is usually the
+ * vendor's conventional name (GROQ_API_KEY), shared with other tools.
+ */
+export function withEnvPrefix(
+  prefix: string,
+  provider: Omit<Provider, "modelsEnv" | "dailyTokensEnv">,
+): Provider {
+  const slug = provider.id.toUpperCase().replace(/[^A-Z0-9]+/g, "_");
+  return {
+    ...provider,
+    modelsEnv: `${prefix}_${slug}_MODELS`,
+    dailyTokensEnv: `${prefix}_${slug}_DAILY_TOKENS`,
+  };
+}
+
+/**
+ * A default chain of FREE models, every entry probed live on 2026-08-15 with a
+ * real tool call. Protocol each answered on:
+ *
+ *   groq/llama-3.3-70b-versatile              native
+ *   groq/llama-3.1-8b-instant                 text
+ *   openai/gpt-oss-20b:free                   native
+ *   nvidia/nemotron-3-super-120b-a12b:free    native
+ *   nvidia/nemotron-3.5-lightning:free        native
+ *   google/gemma-4-26b-a4b-it:free            text
+ *   nvidia/nemotron-3-nano-30b-a3b:free       text
+ *   cohere/north-mini-code:free               text
+ *   openrouter/free                           text
+ *
+ * Deliberately excluded, both verified rather than assumed:
+ *   google/gemma-4-31b-it:free      — "Provider returned error" on probe
+ *   nvidia/nemotron-nano-12b-v2-vl  — returns HTTP 200 with EMPTY content, which
+ *                                     a naive client reads as a successful
+ *                                     empty answer
+ *
+ * `openrouter/free` sits last on purpose: it is an auto-router across the free
+ * catalogue, so it keeps working when a specific id above it is retired. That
+ * makes it the link most likely to survive the next rot, and the least
+ * predictable in quality — exactly the right shape for a last resort.
+ *
+ * NOTE the shelf life. This list is evidence from one day, not a constant; free
+ * catalogues rot. Treat it as a starting point and re-probe.
+ */
+export function freeChain(prefix = "AI"): Provider[] {
+  return [
+    withEnvPrefix(prefix, {
+      id: "groq",
+      baseUrl: "https://api.groq.com/openai/v1",
+      keyEnv: "GROQ_API_KEY",
+      // Re-probed 2026-08-25 against the live catalog. The previous pins,
+      // `llama-3.3-70b-versatile` and `llama-3.1-8b-instant`, were BOTH gone —
+      // so this "fallback chain" led with a fully dead vendor and every caller
+      // paid two 404s before reaching OpenRouter. FleetCrown, whose direct
+      // (non-chain) calls used the same id and had no fallback at all, was
+      // silently down for eight days. Both ids below answered with a correct
+      // native tool_call when probed, which is the bar this list is held to.
+      models: ["openai/gpt-oss-120b", "openai/gpt-oss-20b"],
+      // Not a guess: Groq's own TPD refusal names it — "on tokens per day
+      // (TPD): Limit 100000". Org-wide, so every feature sharing the key draws
+      // from this same pool.
+      dailyTokens: 100_000,
+    }),
+    withEnvPrefix(prefix, {
+      id: "openrouter",
+      baseUrl: "https://openrouter.ai/api/v1",
+      keyEnv: "OPENROUTER_API_KEY",
+      // Routed ids: `:free` is the whole difference between free routing and a
+      // per-call charge for the same weights. See Provider.routed.
+      routed: true,
+      // Re-checked 2026-08-25 against the 419-model live catalog. Two entries
+      // were retired and are removed here: `openai/gpt-oss-20b:free` — which
+      // was FIRST, so the preferred fallback 404'd on every call — and
+      // `nvidia/nemotron-3-nano-30b-a3b:free`. The five below were present.
+      models: [
+        "nvidia/nemotron-3-super-120b-a12b:free",
+        "nvidia/nemotron-3.5-lightning:free",
+        "google/gemma-4-26b-a4b-it:free",
+        "cohere/north-mini-code:free",
+        "openrouter/free",
+      ],
+      // OpenRouter meters its free tier in REQUESTS per day, not tokens, and the
+      // cap depends on the account's credit balance — so this is a translation,
+      // not a published figure. Set at the low end on purpose.
+      dailyTokens: 100_000,
+    }),
+  ];
+}
+
+/** What a model id tells us about who pays. */
+export type CostVerdict = "free" | "paid" | "unknown";
+
+/**
+ * Does this model id cost money?
+ *
+ * Exists because the same mistake was found in THREE separate apps on one day,
+ * each a fallback that silently began spending when the free tier ran dry:
+ *
+ *   anthropic/claude-sonnet-5                  a premium model as the fallback
+ *   google/gemini-2.0-flash-001                the paid twin of a `:free` id
+ *   meta-llama/llama-3.3-70b-instruct          reads free; bills at 1e-7/token,
+ *                                              and its `:free` sibling has been
+ *                                              retired from the catalogue
+ *
+ * The decidable rule is narrow and stated as such. A routed id (`vendor/model`,
+ * the OpenRouter shape) is FREE only with the `:free` suffix, and PAID without
+ * it — that suffix is the entire difference between free routing and a per-call
+ * charge for the same weights. A bare id (`llama-3.1-8b-instant`) says nothing:
+ * whether it costs depends on the account's tier at that vendor, which no string
+ * can answer, so it returns "unknown" rather than guessing.
+ *
+ * Guessing "free" there would be the dangerous direction — it is what let three
+ * of these through code review.
+ *
+ * IMPORTANT: this reads the id as a ROUTED (OpenRouter-shape) id, because that
+ * is the only shape where the string decides. It is therefore wrong to apply to
+ * an id from a vendor that merely happens to prefix its own models — Groq's
+ * `openai/gpt-oss-120b` is not a routed OpenAI id, and this function would call
+ * it paid. When you know the provider, use `modelCostAt`; `paidModelsIn` does.
+ */
+export function modelCost(id: string): CostVerdict {
+  const model = id.trim();
+  if (!model) return "unknown";
+  // OpenRouter's auto-router across the free catalogue.
+  if (model === "openrouter/free") return "free";
+  if (!model.includes("/")) return "unknown";
+  return model.endsWith(":free") ? "free" : "paid";
+}
+
+/**
+ * Cost of a model AT a specific provider — the honest signature, because the
+ * same id answers differently at different vendors (see `Provider.routed`).
+ *
+ * At a non-routed vendor the id carries no cost information at all: what you
+ * pay is the account's tier there, which no string can report. That is the
+ * same "unknown" a bare id has always returned, now correct for vendor-prefixed
+ * ids too.
+ */
+export function modelCostAt(provider: Provider, model: string): CostVerdict {
+  return provider.routed ? modelCost(model) : "unknown";
+}
+
+/**
+ * Assert every model in a chain is free, for apps that must never bill.
+ *
+ * Judges each id AT ITS PROVIDER. Flagging Groq's `openai/gpt-oss-120b` as paid
+ * because it contains a slash would be a false alarm that pressures someone
+ * into "fixing" a working free model — and a guard that cries wolf gets
+ * disabled, taking the three real cases it does catch with it.
+ *
+ * Returns the offending ids rather than throwing: the caller knows whether a
+ * paid link is a bug or a deliberate, opted-in upgrade, and a library that
+ * throws on the second case forces people to route around it.
+ */
+export function paidModelsIn(chain: Provider[]): string[] {
+  return chain.flatMap((p) => p.models.filter((m) => modelCostAt(p, m) === "paid"));
+}
+
+/**
+ * The day's total budget: every provider we hold a key for.
+ *
+ * Only KEYED providers count. A vendor whose key is absent contributes nothing
+ * however generous its tier, and counting it would ration users against capacity
+ * that cannot be reached — the same failure as an optimistic estimate, just with
+ * an obvious cause.
+ */
+export function dayCapacityTokens(chain: Provider[], env: Env = process.env): number {
+  let total = 0;
+  for (const provider of chain) {
+    if (!readEnv(env, provider.keyEnv)) continue;
+    const override = Number(readEnv(env, provider.dailyTokensEnv));
+    total += Number.isFinite(override) && override >= 0 ? override : provider.dailyTokens;
+  }
+  return total;
+}
+
+/**
+ * The chain with unusable entries removed: no API key, or no models configured.
+ *
+ * A missing key is a normal deployment state — most boxes carry one vendor's
+ * key, not every vendor's — so it filters out silently rather than throwing.
+ */
+export function usableChain(chain: Provider[], env: Env = process.env): Link[] {
+  const out: Link[] = [];
+  for (const provider of chain) {
+    if (!readEnv(env, provider.keyEnv)) continue;
+    for (const model of providerModels(provider, env)) out.push({ provider, model });
+  }
+  return out;
+}
+
+/**
+ * The chain starting at `model`, or the whole chain when it names no link.
+ *
+ * Apps commonly carry a "use this model" env var. Honouring it as a STARTING
+ * POINT rather than a hard pin keeps that escape hatch while refusing to
+ * reintroduce the single point of failure this module exists to remove: an
+ * operator pinning a model should still get a fallback when that model's vendor
+ * runs dry.
+ */
+export function chainFrom(model: string | undefined, chain: Link[]): Link[] {
+  const wanted = model?.trim();
+  if (!wanted) return chain;
+  const at = chain.findIndex((l) => l.model === wanted);
+  if (at >= 0) return chain.slice(at);
+  // A model nobody advertises is still a legitimate request (a private
+  // deployment, a just-released id). Try it against the first provider that has
+  // a key, then fall through to the ordinary chain rather than dead-ending.
+  const host = chain[0];
+  return host ? [{ provider: host.provider, model: wanted }, ...chain] : [];
+}

package/src/fair-share.ts

@@ -0,0 +1,183 @@
+/**
+ * Fair-share rationing of a FIXED daily AI budget across users.
+ *
+ * Pure by design — no DB, no clock, no provider. Everything it needs arrives as
+ * arguments, so the same policy drops into any project without dragging one
+ * app's storage or model plumbing along. The caller owns "what has this user
+ * spent today"; this file owns "may they spend more".
+ *
+ * ── The problem it exists to solve ───────────────────────────────────────────
+ * Free tiers are metered per DAY and shared by everyone holding the key: one
+ * vendor grants ~100k tokens/day across a whole org, and one measured chat turn
+ * cost ~16k (one tool call, on a free model). That is about six turns a day per
+ * vendor — fewer than anyone assumes. Divided badly, the first
+ * enthusiastic user spends the entire day's budget before lunch and everyone
+ * who arrives after them meets a wall — including the person trying the product
+ * for the first time, who concludes it is broken and never returns.
+ *
+ * So the goal is not "maximise throughput", it is "every ACTIVE user gets a
+ * usable amount, every day". Those are different objectives and they favour
+ * different designs.
+ *
+ * ── Two ideas, and both are load-bearing ─────────────────────────────────────
+ *
+ * 1. SHARE — capacity / active users. Recomputed per request, so the split
+ *    tracks reality instead of a number set once in a config file. Crucially
+ *    "active" means users who actually drew today, not everyone registered:
+ *    counting dormant accounts would ration a quiet day down to nothing and
+ *    waste the budget that was meant to be generous. One user on a quiet day
+ *    correctly gets the whole thing.
+ *
+ * 2. PACING — a share alone is not enough, because a share is a whole-DAY
+ *    allowance and the day is consumed in order. Without pacing, three users
+ *    can each legitimately spend their full share by 09:00 and the fourth to
+ *    arrive finds the capacity gone even though nobody exceeded their split.
+ *    So the allowance unlocks gradually: by mid-afternoon you may have spent
+ *    about half your share, by end of day all of it. That is what actually
+ *    keeps capacity available for whoever shows up later.
+ *
+ * `burst` exists so this does not become its own wall: with pure pacing, a user
+ * at one minute past midnight would have an allowance of nearly zero. A burst
+ * makes the first turns immediate, which is the difference between "paced" and
+ * "unusable".
+ *
+ * ── What it deliberately does NOT do ─────────────────────────────────────────
+ * No clawback. A user who spent under an older, larger share when they were the
+ * only one active is not punished when a second user appears — their allowance
+ * simply stops growing until the day catches up. Taking budget back from
+ * someone who already used it is impossible anyway (the tokens are spent) and
+ * pretending otherwise would only produce confusing refusals.
+ */
+
+/** Seconds in a budget day. Provider quotas reset daily, so the day is the unit. */
+export const DAY_SECONDS = 86_400;
+
+/**
+ * Fraction of a user's share spendable immediately, before pacing has unlocked
+ * anything. Set so the first couple of turns never wait: the failure mode this
+ * guards against ("I typed one question at 9am and it refused me") is far worse
+ * than the one it risks (a slightly front-loaded day).
+ */
+export const DEFAULT_BURST = 0.25;
+
+export type ShareInput = {
+  /** Total tokens the free tiers grant for the whole day, summed across providers. */
+  dayCapacityTokens: number;
+  /**
+   * Distinct users drawing on the budget today, INCLUDING the one asking now.
+   * The caller must include the requester even on their first turn — otherwise
+   * a newcomer is rationed against a divisor that does not count them, and the
+   * day is briefly over-committed.
+   */
+  activeUsers: number;
+  /** What this user has already spent today. */
+  userSpentTokens: number;
+  /** Estimated cost of the turn being requested. */
+  costTokens: number;
+  /** How far through the budget day we are, 0..1. */
+  dayElapsed: number;
+  /** Fraction of a share usable immediately. Defaults to DEFAULT_BURST. */
+  burst?: number;
+};
+
+export type ShareReason =
+  /** Within the paced allowance. */
+  | "ok"
+  /** Within the day's share, but not yet unlocked — waiting helps. */
+  | "paced"
+  /** This user's whole share for today is committed — waiting does NOT help. */
+  | "share-spent"
+  /** There is no budget to divide at all. */
+  | "no-capacity";
+
+export type ShareDecision = {
+  allowed: boolean;
+  /** Their whole-day share, before pacing. */
+  shareTokens: number;
+  /** What they may have spent BY NOW. */
+  allowanceTokens: number;
+  reason: ShareReason;
+  /**
+   * When it is worth asking again. Present ONLY for "paced", because that is
+   * the only refusal a wait actually fixes — telling someone whose share is
+   * spent to "try again in 20 minutes" is the same lie as telling a user whose
+   * daily quota is gone to "try again shortly".
+   */
+  retryAfterSeconds?: number;
+};
+
+/** Clamp to [0, 1]; a caller's clock skew must not produce a negative allowance. */
+function clamp01(n: number): number {
+  if (!Number.isFinite(n)) return 0;
+  return Math.min(1, Math.max(0, n));
+}
+
+/**
+ * May this user spend `costTokens` right now?
+ *
+ * Recomputed per request rather than cached: `activeUsers` is the input most
+ * likely to change between two turns, and a stale divisor is exactly how a new
+ * user gets locked out of a budget that was supposed to include them.
+ */
+export function fairShare(input: ShareInput): ShareDecision {
+  const capacity = Math.max(0, input.dayCapacityTokens);
+  // A user is always at least one user. Guarding here rather than trusting the
+  // caller keeps a bad count from becoming a division by zero at the worst
+  // possible moment.
+  const users = Math.max(1, Math.floor(input.activeUsers) || 1);
+  const spent = Math.max(0, input.userSpentTokens);
+  const cost = Math.max(0, input.costTokens);
+  const burst = clamp01(input.burst ?? DEFAULT_BURST);
+  const elapsed = clamp01(input.dayElapsed);
+
+  const shareTokens = capacity / users;
+  const pace = clamp01(elapsed + burst);
+  // A share that cannot buy a SINGLE turn is a wall wearing a ration's clothes.
+  // With four active users on a 100k day and a ~10k turn, pure pacing refuses
+  // the first question of the morning and tells the user to come back in three
+  // hours — which, for someone trying the product for the first time, is
+  // indistinguishable from broken. So the allowance never sits below the cost
+  // of one turn, capped by the share: everyone gets at least one, then pacing
+  // governs the rest. Capped by `shareTokens` so this floor can never hand out
+  // more than the user's actual split.
+  const oneTurn = Math.min(shareTokens, cost);
+  const allowanceTokens = Math.min(shareTokens, Math.max(shareTokens * pace, oneTurn));
+
+  if (capacity <= 0) {
+    return { allowed: false, shareTokens: 0, allowanceTokens: 0, reason: "no-capacity" };
+  }
+
+  const wanted = spent + cost;
+  if (wanted <= allowanceTokens) {
+    return { allowed: true, shareTokens, allowanceTokens, reason: "ok" };
+  }
+
+  // Past the whole-day share: no amount of waiting unlocks more today.
+  if (wanted > shareTokens) {
+    return { allowed: false, shareTokens, allowanceTokens, reason: "share-spent" };
+  }
+
+  // Within the share but ahead of the pace — the one case a wait fixes. Solve
+  // for the elapsed fraction at which the allowance covers `wanted`.
+  const neededPace = wanted / shareTokens;
+  const neededElapsed = neededPace - burst;
+  const retryAfterSeconds = Math.max(1, Math.ceil((neededElapsed - elapsed) * DAY_SECONDS));
+  return { allowed: false, shareTokens, allowanceTokens, reason: "paced", retryAfterSeconds };
+}
+
+/**
+ * How far through the UTC day `now` is, 0..1.
+ *
+ * UTC because that is what the providers meter on; deriving it from the
+ * operator's local midnight would drift the reset away from the vendor's and
+ * hand out budget that is not there.
+ */
+export function utcDayElapsed(now: Date): number {
+  const ms = now.getTime() - Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
+  return clamp01(ms / (DAY_SECONDS * 1000));
+}
+
+/** The UTC day key (YYYY-MM-DD) a spend belongs to — the accounting bucket. */
+export function utcDayKey(now: Date): string {
+  return now.toISOString().slice(0, 10);
+}

package/src/forms.ts

@@ -0,0 +1,15 @@
+/**
+ * Form filling, re-exported from `ai-forms`.
+ *
+ * `ai-forms` is NOT absorbed. It stays its own package: it works, four apps run
+ * it, and it is a genuinely general-purpose thing that people outside this fleet
+ * can use. Swallowing it would break four repos and delete a good name off the
+ * registry to satisfy a filing system.
+ *
+ * What this subpath buys is that an app adding AI installs ONE thing. AOZ is
+ * the argument: it adopted `ai-forms`, then hand-rolled a provider layer and a
+ * chat loop, because those were two further decisions nobody made. Filling a
+ * form from prose and choosing which model fills it are the same feature to the
+ * app, so they should be one install.
+ */
+export * from "ai-forms";