@bitbaum/ai-kit 0.6.2 → 0.8.0

package/README.md

@@ -6,7 +6,7 @@ what to do when you're going too fast, how to share a free tier fairly between
 users, and how to fill a form from plain language.
 
 ```bash
-npm install ai-kit
+pnpm add @bitbaum/ai-kit
 ```
 
 ---
@@ -58,6 +58,95 @@ the same org-wide daily budget, so when the day runs dry every link in that
 via a text tool protocol, not native `tool_calls`. A native-only client would
 have silently lost most of the chain.
 
+### Make the call — `complete()` owns the fetch
+
+```ts
+import { complete, freeChain, usableChain, createHealthTracker } from '@bitbaum/ai-kit';
+
+export const llmHealth = createHealthTracker();
+const chain = usableChain(freeChain('MYAPP'), process.env);
+
+const { text, id } = await complete({
+  chain,
+  health: llmHealth,
+  maxTokens: 500,
+  messages: [{ role: 'user', content: 'Summarise this in one line.' }],
+});
+```
+
+For four releases this package shipped the *decisions* and told you to keep the
+fetch. The rule read well and it was wrong: measured 2026-09-05, this fleet ran
+**eight** hand-rolled clients, **two** of which told the three kinds of 429
+apart — while `ai-forms`, which ships a working route factory, had more than
+twice this package's adoption. A package that hands you a working call gets
+installed; one that hands you advice about calls does not.
+
+`complete()` is the chain walk plus the request, and it carries the parts that
+kept getting left out of the hand-rolled ones:
+
+- a **200 with empty content is a failure**, not an answer — reasoning models
+  and some vendors return exactly that, and every client that read
+  `choices[0].message.content || ''` shipped the empty string to a user;
+- a **daily** 429 marks the whole vendor dead for the walk, instead of trying
+  its other models against the same exhausted org-wide budget;
+- a **size** 429 ends the walk rather than demoting to a *smaller* ceiling,
+  which is strictly worse;
+- the vendor's response body survives into the error, so an exhausted day is
+  distinguishable from a momentary burst in a log.
+
+**`maxTokens` has a floor, and it is higher than you think.** The chain leads
+with reasoning models, which spend the budget on hidden thinking before emitting
+a visible token: `groq/openai/gpt-oss-20b` answered *empty* at 16 and correctly
+at 256 for the same one-word question. A mean budget makes a healthy model look
+dead.
+
+`tryChain` stays for a caller with a genuinely unusual request to make.
+
+### Does it work RIGHT NOW? — a probe, not a guess
+
+```ts
+// app/api/health/ai/route.ts — Next App Router, Hono, Deno and Bun all take
+// this shape directly.
+import { createAiHealthHandler, freeChain, usableChain } from '@bitbaum/ai-kit';
+import { llmHealth } from '@/lib/llm-health';
+
+const handler = createAiHealthHandler({
+  chain: usableChain(freeChain('MYAPP'), process.env),
+  health: llmHealth,
+  secret: process.env.AI_PROBE_SECRET,
+});
+
+export const GET = handler;
+```
+
+```
+GET /api/health/ai                          free. What happened last time.
+GET /api/health/ai?probe=1  + the secret    makes a real call. 200 or 503.
+```
+
+**Why a probe and not a passive read.** Absence of failure is not evidence of
+success. A tracker that has recorded nothing looks identical whether the chain
+is perfect or every key is missing — and straight after a deploy that is exactly
+the state it is in. Observed converting the first app: the deploy was green, the
+bundle provably held the new code, both keys were present, `/api/health`
+returned 200, and `llm.status` was `"unknown"`. Every available signal said
+"probably fine" and none said "works". The only paths that would have answered
+were an admin-authenticated form and two cron jobs that **email real users** —
+verifying a deploy must never require spamming somebody.
+
+**Why it is gated and cached.** A probe spends real tokens from a daily budget
+shared with the app's actual features, so an ungated one on a health route is a
+self-inflicted outage: a monitor polling every 30s would drain the allowance and
+take the AI features down with it. So a probe runs only on `?probe=1` **and**
+with the secret, a *success* is cached for 10 minutes (returned with `cached`
+and its age, because a nine-minute-old success is a different claim from a fresh
+one), and a **failure is never cached** — the whole point is the truth about
+right now.
+
+With no secret configured the route answers **501**, not an open probe: an app
+that forgets to set one gets a route that cannot spend money, rather than one
+that can.
+
 ### Is it up? — walk the chain, and know when none of it worked
 
 A chain nobody walks is a list, not a fallback. This was found sitting unused
@@ -79,7 +168,7 @@ const { text } = await tryChain(chain, {
 });
 ```
 
-No HTTP client here either — `attempt` makes the real request; `tryChain` only
+`attempt` makes the real request; `tryChain` only
 decides which link goes next and throws `ChainExhaustedError` (naming every
 link's failure, not just the last) when none of them work.
 
@@ -165,7 +254,7 @@ stays its own package — it works, four apps run it, and it is useful well outs
 this fleet. Swallowing it would have broken those four for the sake of a filing
 system.
 
-**Note the subpath.** Form filling is at `ai-kit/forms`, not at the root. For one
+**Note the subpath.** Form filling is at `@bitbaum/ai-kit/forms`, not at the root. For one
 release it was both, and the first app to adopt the merged package paid for it:
 `ai-forms` is ESM-only, so importing the *chain* from the root dragged the forms
 package in behind it and the app's Jest run — which executes CJS — died inside a
@@ -173,21 +262,18 @@ module it never asked for. One install is still the whole promise; the exports
 map is what keeps it, while letting a server that only wants a provider chain
 stop paying for a form library.
 
-React lives on its own subpath and is an **optional** peer, so importing `ai-kit`
-on a server never pulls in a UI library.
+React lives on its own subpath and is an **optional** peer, so importing
+`@bitbaum/ai-kit` on a server never pulls in a UI library.
 
 ---
 
 ## What it deliberately does not ship
 
-**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; you keep the fetch.
-
-That rule is under review, and honestly. `ai-forms` is the most-adopted package
-in this fleet and it is the one that broke the rule, by shipping a route factory
-and a React hook. A package that hands you a working route gets installed; one
-that hands you advice about routes does not.
+**~~An HTTP client.~~** It ships one now — see [`complete()`](#make-the-call--complete-owns-the-fetch).
+The old rule ("every app has its own calling conventions, and replacing those is
+a rewrite rather than an adoption") described this fleet's duplication
+accurately and then protected it: the conventions differed because nothing had
+ever offered to own them.
 
 **Model values.** Which ids are free, which are billed, and which your account
 may use are properties of *your* deployment. Centralise the rule, assert it
@@ -210,7 +296,7 @@ model catalogue to do it.
 ## Development
 
 ```bash
-npm run verify   # lint + typecheck + build + test
+pnpm run verify  # lint + typecheck + build + test
 ```
 
 MIT.

package/dist/complete.d.ts

@@ -0,0 +1,160 @@
+/**
+ * The call itself — the one thing this package refused to ship, and the reason
+ * the rest of it went unused.
+ *
+ * ── WHY THIS REVERSES A STATED RULE ──────────────────────────────────────────
+ * Every module here was written against a real outage, and every one of them is
+ * correct. None of that reached the apps that were actually failing. Measured
+ * across the fleet on 2026-09-05:
+ *
+ *   this package's decisions      adopted by 2 repos
+ *   `ai-forms`, which ships a working handler        adopted by 5 repos
+ *   hand-rolled LLM clients still in service         8, ~1400-1700 lines each
+ *
+ * The pattern is not about quality, it is about shape. `ai-forms` was adopted
+ * because `createFormAssistHandler` does the job; this package was not, because
+ * it hands back advice the caller must then wire up. The old rule — "every app
+ * has its own calling conventions, replacing them is a rewrite rather than an
+ * adoption" — describes the duplication accurately and then protects it. The
+ * conventions differ because nothing ever offered to own them.
+ *
+ * The cost of that is not theoretical. Of the 8 hand-rolled clients, 2 tell the
+ * three kinds of 429 apart; the other 6 treat a spent daily budget as a busy
+ * minute — `limits.ts` has explained why that is harmful since 2026-08-14, in a
+ * module those 6 apps do not import. `tryChain` says it plainly: a chain nobody
+ * walks is a list, not a fallback. A decision nobody calls is a comment.
+ *
+ * So: this owns the fetch. `tryChain` stays for callers with a genuinely
+ * unusual request to make; this is the answer for everyone else.
+ *
+ * ── WHAT IT KNOWS THAT A HAND-ROLLED LOOP DOES NOT ───────────────────────────
+ * Walking the chain is the easy half. Three behaviours below are the ones every
+ * hand-rolled client in this fleet got wrong, each traced to an incident:
+ *
+ *   HTTP 200 IS NOT SUCCESS. `nvidia/nemotron-nano-12b-v2-vl` returns 200 with
+ *   empty content, and `gemini-2.5-flash` does the same after a tool call — it
+ *   spends its whole budget on internal thinking and emits no text part. A
+ *   client that checks `res.ok` returns "" to the user and reports success, so
+ *   the chain never advances and health stays green through a total outage.
+ *   Empty content is a FAILURE here, and it demotes to the next link.
+ *
+ *   A DAILY 429 CONDEMNS THE WHOLE VENDOR, not one model. The budget is
+ *   org-wide and shared across models, so every remaining link at that provider
+ *   is already dead. Walking them costs a dead round trip each and reaches the
+ *   same failure. They are skipped.
+ *
+ *   A SIZE 429 ENDS THE WALK. One request exceeded the entire per-minute
+ *   allowance; the next model down has a SMALLER ceiling (measured: 12000 TPM
+ *   vs 6000), so demoting makes it strictly worse. The only cure is a shorter
+ *   prompt, and the caller is told exactly that instead of watching the chain
+ *   burn itself down to reach a worse version of the same error.
+ *
+ * ── AND ONE IT INHERITS ──────────────────────────────────────────────────────
+ * The response BODY is kept in every error. A status-only message ("groq 429")
+ * makes an exhausted day indistinguishable from a momentary burst, and the
+ * obvious remedy for the latter — wait and retry — can never work for the
+ * former. That misdiagnosis cost an hour once; it is not free to repeat.
+ */
+import { type Env, type Link, type Provider } from "./chain.js";
+import type { HealthTracker } from "./health.js";
+import { type RateLimitKind } from "./limits.js";
+/** One message in the OpenAI chat-completions shape every provider here speaks. */
+export interface ChatMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string;
+    /** Present on `role: "tool"` replies; passed through untouched. */
+    tool_call_id?: string;
+    name?: string;
+}
+/**
+ * A tool call the model asked for, normalised across the two protocols models
+ * actually answer on.
+ *
+ * Both exist in the default chain: of nine free models probed live, four
+ * answered with native `tool_calls` and five only in text. Callers get the
+ * native shape here; parsing the text protocol is the caller's business,
+ * because its convention differs per app.
+ */
+export interface ToolCall {
+    id: string;
+    name: string;
+    /** Raw JSON string as the model emitted it — NOT parsed, because a model can emit invalid JSON and the caller decides what to do about that. */
+    args: string;
+}
+export interface CompleteOptions {
+    messages: ChatMessage[];
+    /**
+     * Links to try, in order. Defaults to `usableChain(freeChain())` — every free
+     * provider that has a key in `env`.
+     */
+    chain?: Link[];
+    /** Providers to derive the chain from when `chain` is not given. */
+    providers?: Provider[];
+    /**
+     * Start the chain at this model rather than the front, falling through to the
+     * rest. The usual home for an app's "use this model" env var.
+     */
+    model?: string;
+    env?: Env;
+    health?: HealthTracker;
+    signal?: AbortSignal;
+    /**
+     * Set this GENEROUSLY, or a healthy model looks dead.
+     *
+     * The default chain leads with reasoning models, which spend this budget
+     * thinking before emitting a visible token. Set it too low and the vendor
+     * returns 200 with empty content — which this module correctly treats as a
+     * failure and demotes, so a small `maxTokens` silently walks the whole chain
+     * and reports every link broken. Measured 2026-09-05: groq/openai/gpt-oss-20b
+     * answered EMPTY at 16 and answered correctly at 256, for the same one-word
+     * question.
+     */
+    maxTokens?: number;
+    temperature?: number;
+    /** Tool definitions in the OpenAI shape; passed through untouched. */
+    tools?: unknown[];
+    /** Extra body fields for a vendor-specific parameter. Merged last, so it can override. */
+    extraBody?: Record<string, unknown>;
+    /** Called on each link's failure before moving on — e.g. to log which id rotted. */
+    onLinkFailure?: (link: Link, error: Error) => void;
+    /** Injected for tests. Defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+export interface CompleteResult {
+    /** The assistant's text. Never empty — an empty completion is treated as a failure. */
+    text: string;
+    /** `provider/model`, the id worth logging: it says which link actually served the turn. */
+    id: string;
+    link: Link;
+    toolCalls: ToolCall[];
+    /** The parsed response body, for a caller that needs a field this does not surface. */
+    raw: unknown;
+}
+/**
+ * A link failed in a way that says something about the WALK, not just this link.
+ *
+ * `kind` is what the walker acts on; it is carried on the error so a caller
+ * reading `ChainExhaustedError.failures` can see why the walk stopped where it
+ * did rather than inferring it from prose.
+ */
+export declare class LinkFailure extends Error {
+    readonly link: Link;
+    readonly status?: number;
+    readonly kind?: RateLimitKind;
+    readonly retryAfter?: number | null;
+    constructor(link: Link, message: string, init?: {
+        status?: number;
+        kind?: RateLimitKind;
+        retryAfter?: number | null;
+    });
+}
+/** `provider/model` — the id worth logging, because the model alone does not say whose meter it drew on. */
+export declare function linkId(link: Link): string;
+/**
+ * Call the first link that works, and return what it said.
+ *
+ * Throws `ChainExhaustedError` carrying every link's failure, so a log shows
+ * what was actually tried — the failure that explains an outage is usually not
+ * the last one.
+ */
+export declare function complete(options: CompleteOptions): Promise<CompleteResult>;

package/dist/complete.js

@@ -0,0 +1,237 @@
+/**
+ * The call itself — the one thing this package refused to ship, and the reason
+ * the rest of it went unused.
+ *
+ * ── WHY THIS REVERSES A STATED RULE ──────────────────────────────────────────
+ * Every module here was written against a real outage, and every one of them is
+ * correct. None of that reached the apps that were actually failing. Measured
+ * across the fleet on 2026-09-05:
+ *
+ *   this package's decisions      adopted by 2 repos
+ *   `ai-forms`, which ships a working handler        adopted by 5 repos
+ *   hand-rolled LLM clients still in service         8, ~1400-1700 lines each
+ *
+ * The pattern is not about quality, it is about shape. `ai-forms` was adopted
+ * because `createFormAssistHandler` does the job; this package was not, because
+ * it hands back advice the caller must then wire up. The old rule — "every app
+ * has its own calling conventions, replacing them is a rewrite rather than an
+ * adoption" — describes the duplication accurately and then protects it. The
+ * conventions differ because nothing ever offered to own them.
+ *
+ * The cost of that is not theoretical. Of the 8 hand-rolled clients, 2 tell the
+ * three kinds of 429 apart; the other 6 treat a spent daily budget as a busy
+ * minute — `limits.ts` has explained why that is harmful since 2026-08-14, in a
+ * module those 6 apps do not import. `tryChain` says it plainly: a chain nobody
+ * walks is a list, not a fallback. A decision nobody calls is a comment.
+ *
+ * So: this owns the fetch. `tryChain` stays for callers with a genuinely
+ * unusual request to make; this is the answer for everyone else.
+ *
+ * ── WHAT IT KNOWS THAT A HAND-ROLLED LOOP DOES NOT ───────────────────────────
+ * Walking the chain is the easy half. Three behaviours below are the ones every
+ * hand-rolled client in this fleet got wrong, each traced to an incident:
+ *
+ *   HTTP 200 IS NOT SUCCESS. `nvidia/nemotron-nano-12b-v2-vl` returns 200 with
+ *   empty content, and `gemini-2.5-flash` does the same after a tool call — it
+ *   spends its whole budget on internal thinking and emits no text part. A
+ *   client that checks `res.ok` returns "" to the user and reports success, so
+ *   the chain never advances and health stays green through a total outage.
+ *   Empty content is a FAILURE here, and it demotes to the next link.
+ *
+ *   A DAILY 429 CONDEMNS THE WHOLE VENDOR, not one model. The budget is
+ *   org-wide and shared across models, so every remaining link at that provider
+ *   is already dead. Walking them costs a dead round trip each and reaches the
+ *   same failure. They are skipped.
+ *
+ *   A SIZE 429 ENDS THE WALK. One request exceeded the entire per-minute
+ *   allowance; the next model down has a SMALLER ceiling (measured: 12000 TPM
+ *   vs 6000), so demoting makes it strictly worse. The only cure is a shorter
+ *   prompt, and the caller is told exactly that instead of watching the chain
+ *   burn itself down to reach a worse version of the same error.
+ *
+ * ── AND ONE IT INHERITS ──────────────────────────────────────────────────────
+ * The response BODY is kept in every error. A status-only message ("groq 429")
+ * makes an exhausted day indistinguishable from a momentary burst, and the
+ * obvious remedy for the latter — wait and retry — can never work for the
+ * former. That misdiagnosis cost an hour once; it is not free to repeat.
+ */
+import { chainFrom, freeChain, usableChain } from "./chain.js";
+import { ChainExhaustedError } from "./attempt.js";
+import { classifyRateLimit, retryAfterSeconds } from "./limits.js";
+/**
+ * A link failed in a way that says something about the WALK, not just this link.
+ *
+ * `kind` is what the walker acts on; it is carried on the error so a caller
+ * reading `ChainExhaustedError.failures` can see why the walk stopped where it
+ * did rather than inferring it from prose.
+ */
+export class LinkFailure extends Error {
+    link;
+    status;
+    kind;
+    retryAfter;
+    constructor(link, message, init = {}) {
+        super(message);
+        this.name = "LinkFailure";
+        this.link = link;
+        this.status = init.status;
+        this.kind = init.kind;
+        this.retryAfter = init.retryAfter;
+    }
+}
+/** `provider/model` — the id worth logging, because the model alone does not say whose meter it drew on. */
+export function linkId(link) {
+    return `${link.provider.id}/${link.model}`;
+}
+function firstText(message) {
+    if (!message)
+        return "";
+    const content = message.content;
+    if (typeof content === "string")
+        return content;
+    // Some vendors return content as an array of parts. Concatenate the text ones
+    // rather than stringifying the array, which would hand the caller JSON.
+    if (Array.isArray(content)) {
+        return content
+            .map((part) => part && typeof part === "object" && typeof part.text === "string"
+            ? part.text
+            : "")
+            .join("");
+    }
+    return "";
+}
+function toolCallsFrom(message) {
+    const raw = message?.tool_calls;
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const entry of raw) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const fn = entry.function;
+        if (!fn || typeof fn.name !== "string")
+            continue;
+        out.push({
+            id: String(entry.id ?? ""),
+            name: fn.name,
+            args: typeof fn.arguments === "string" ? fn.arguments : JSON.stringify(fn.arguments ?? {}),
+        });
+    }
+    return out;
+}
+/**
+ * Truncated so a failure message stays readable in a log line, but long enough
+ * to carry the sentence that matters: Groq states the real reset ~90 characters
+ * into a daily-cap body, and cutting before it throws away the one number the
+ * user can act on.
+ */
+function excerpt(body, limit = 300) {
+    const flat = body.replace(/\s+/g, " ").trim();
+    return flat.length > limit ? `${flat.slice(0, limit)}…` : flat;
+}
+async function callLink(link, options, key) {
+    const doFetch = options.fetchImpl ?? globalThis.fetch;
+    const body = {
+        model: link.model,
+        messages: options.messages,
+        ...(options.maxTokens === undefined ? {} : { max_tokens: options.maxTokens }),
+        ...(options.temperature === undefined ? {} : { temperature: options.temperature }),
+        ...(options.tools === undefined ? {} : { tools: options.tools }),
+        ...options.extraBody,
+    };
+    let res;
+    try {
+        res = await doFetch(`${link.provider.baseUrl}/chat/completions`, {
+            method: "POST",
+            headers: { "content-type": "application/json", authorization: `Bearer ${key}` },
+            body: JSON.stringify(body),
+            signal: options.signal,
+        });
+    }
+    catch (error) {
+        // A transport failure (DNS, TLS, abort) is not the vendor's answer, so it
+        // carries no rate-limit kind — it demotes like any other link failure.
+        throw new LinkFailure(link, `${linkId(link)}: ${error.message}`);
+    }
+    const text = await res.text();
+    if (!res.ok) {
+        if (res.status === 429) {
+            const kind = classifyRateLimit(text);
+            const retryAfter = retryAfterSeconds(text);
+            throw new LinkFailure(link, `${linkId(link)}: 429 ${kind} — ${excerpt(text)}`, {
+                status: 429,
+                kind,
+                retryAfter,
+            });
+        }
+        throw new LinkFailure(link, `${linkId(link)}: ${res.status} — ${excerpt(text)}`, {
+            status: res.status,
+        });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new LinkFailure(link, `${linkId(link)}: 200 with unparseable body — ${excerpt(text)}`, {
+            status: res.status,
+        });
+    }
+    const choice = parsed
+        ?.choices?.[0];
+    const content = firstText(choice?.message);
+    const toolCalls = toolCallsFrom(choice?.message);
+    // A 200 that carries neither text nor a tool call is an outage wearing a
+    // success code — see the header. Demote, so the chain gets its chance.
+    if (content.trim() === "" && toolCalls.length === 0) {
+        throw new LinkFailure(link, `${linkId(link)}: 200 with empty content — model produced no output`, {
+            status: res.status,
+        });
+    }
+    return { text: content, id: linkId(link), link, toolCalls, raw: parsed };
+}
+/**
+ * Call the first link that works, and return what it said.
+ *
+ * Throws `ChainExhaustedError` carrying every link's failure, so a log shows
+ * what was actually tried — the failure that explains an outage is usually not
+ * the last one.
+ */
+export async function complete(options) {
+    const env = options.env ?? process.env;
+    const base = options.chain ?? usableChain(options.providers ?? freeChain(), env);
+    const chain = chainFrom(options.model, base);
+    const failures = [];
+    const deadProviders = new Set();
+    for (const link of chain) {
+        // A daily cap already condemned this vendor earlier in the walk. Its other
+        // models draw on the same exhausted budget, so trying them buys a dead
+        // round trip and the identical error.
+        if (deadProviders.has(link.provider.id))
+            continue;
+        const key = env[link.provider.keyEnv]?.trim();
+        if (!key) {
+            failures.push({ link, message: `${linkId(link)}: no ${link.provider.keyEnv} in env` });
+            continue;
+        }
+        try {
+            const result = await callLink(link, options, key);
+            options.health?.recordSuccess();
+            return result;
+        }
+        catch (error) {
+            const failure = error;
+            failures.push({ link, message: failure.message });
+            options.onLinkFailure?.(link, failure);
+            if (failure.kind === "daily")
+                deadProviders.add(link.provider.id);
+            // Stepping down after a size 429 reaches a model with a smaller ceiling —
+            // strictly worse. Stop, and let the caller shorten the prompt.
+            if (failure.kind === "size")
+                break;
+        }
+    }
+    const exhausted = new ChainExhaustedError(failures);
+    options.health?.recordFailure(exhausted);
+    throw exhausted;
+}

package/dist/index.d.ts

@@ -34,17 +34,26 @@
  * 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.
+ * NOW INCLUDED: an HTTP client. `complete()` makes the call.
+ *
+ * The old rule was "every app has its own calling conventions, and replacing
+ * those is a rewrite rather than an adoption" — accurate about the fleet, and
+ * it protected the very duplication it described. The conventions differed
+ * because nothing ever offered to own them. Measured 2026-09-05: 8 hand-rolled
+ * clients in service, 2 of which tell the three kinds of 429 apart, while this
+ * package explained the distinction to the 2 repos that imported it.
+ * `ai-forms` — adopted by 5 — is not better code, it is code that does the job
+ * rather than advising on it. See `complete.ts` for the full argument.
+ *
+ * `tryChain` remains for a caller with a genuinely unusual request to make: it
+ * walks the chain and lets the caller keep the fetch. `complete` is the answer
+ * for everyone else.
  */
 export { type Provider, type Env, type Link, type CostVerdict, providerModels, withEnvPrefix, freeChain, modelCost, modelCostAt, paidModelsIn, dayCapacityTokens, usableChain, chainFrom, } from "./chain.js";
 export { type CatalogVerdict, type CheckCatalogOptions, checkCatalog, hasRot, deadProviders, catalogReport, } from "./catalog.js";
 export { type ChainAttemptFailure, type TryChainOptions, ChainExhaustedError, tryChain, } from "./attempt.js";
+export { type ChatMessage, type ToolCall, type CompleteOptions, type CompleteResult, LinkFailure, complete, linkId, } from "./complete.js";
 export { type HealthStatus, type Health, type HealthTrackerOptions, type HealthTracker, createHealthTracker, } from "./health.js";
+export { type LivenessResult, type LivenessOptions, type LivenessProbe, type AiHealthHandlerOptions, createLivenessProbe, createAiHealthHandler, } from "./liveness.js";
 export { type RateLimitKind, classifyRateLimit, retryAfterSeconds, humanizeWait, rateLimitMessage, } from "./limits.js";
 export { DAY_SECONDS, DEFAULT_BURST, type ShareInput, type ShareReason, type ShareDecision, fairShare, utcDayElapsed, utcDayKey, } from "./fair-share.js";

package/dist/index.js

@@ -34,18 +34,27 @@
  * 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.
+ * NOW INCLUDED: an HTTP client. `complete()` makes the call.
+ *
+ * The old rule was "every app has its own calling conventions, and replacing
+ * those is a rewrite rather than an adoption" — accurate about the fleet, and
+ * it protected the very duplication it described. The conventions differed
+ * because nothing ever offered to own them. Measured 2026-09-05: 8 hand-rolled
+ * clients in service, 2 of which tell the three kinds of 429 apart, while this
+ * package explained the distinction to the 2 repos that imported it.
+ * `ai-forms` — adopted by 5 — is not better code, it is code that does the job
+ * rather than advising on it. See `complete.ts` for the full argument.
+ *
+ * `tryChain` remains for a caller with a genuinely unusual request to make: it
+ * walks the chain and lets the caller keep the fetch. `complete` is the answer
+ * for everyone else.
  */
 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 { LinkFailure, complete, linkId, } from "./complete.js";
 export { createHealthTracker, } from "./health.js";
+export { createLivenessProbe, createAiHealthHandler, } from "./liveness.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.