@bitbaum/ai-kit 0.7.0 → 0.9.0

package/README.md

@@ -58,6 +58,117 @@ 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.
+
+**Every link gets its own deadline** (`timeoutMs`, default 30s). A vendor that
+accepts the connection and then never answers is the most common partial outage
+there is, and it is the one a fallback chain is least able to survive: without a
+deadline `await fetch` never returns, link two is never reached, and the chain
+that exists to survive an outage becomes the thing holding the request open.
+
+Note it is *per link*, and that it is not the same thing as `signal`:
+
+```ts
+// ✗ WRONG — link one spends the whole budget, links two and three inherit an
+//   already-aborted signal, and the "fallback" reports every vendor broken.
+complete({ chain, signal: AbortSignal.timeout(10_000), messages });
+
+// ✓ RIGHT — each link gets ten seconds; `signal` stays what it should be,
+//   the caller going away.
+complete({ chain, timeoutMs: 10_000, signal: request.signal, messages });
+```
+
+When the caller's `signal` aborts, the walk stops rather than touring the
+remaining vendors: the request nobody is waiting for should not spend the daily
+budget, nor report "every vendor failed" about vendors that were never asked.
+
+`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 +190,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.
 
@@ -180,14 +291,11 @@ React lives on its own subpath and is an **optional** peer, so importing
 
 ## 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

package/dist/complete.d.ts

@@ -97,7 +97,33 @@ export interface CompleteOptions {
     model?: string;
     env?: Env;
     health?: HealthTracker;
+    /**
+     * The CALLER's cancellation, covering the whole walk. When this aborts, the
+     * walk stops — the caller has gone, so trying the next vendor on their behalf
+     * is work nobody is waiting for.
+     *
+     * Do not use this as a timeout. See `timeoutMs`.
+     */
     signal?: AbortSignal;
+    /**
+     * How long ONE link may take before it is abandoned and the next is tried.
+     * Default 30s. Set 0 to wait forever (not advised).
+     *
+     * Per LINK, and that is the whole point. A vendor that accepts the connection
+     * and then never answers is the most common partial outage there is, and it
+     * is the one a fallback chain is least able to survive: without a deadline,
+     * `await fetch` simply never returns and link two is never reached. A chain
+     * that cannot time out is not a fallback for the failure mode it most needs
+     * to cover.
+     *
+     * It is deliberately NOT the caller's `signal`. A caller who passes a 10s
+     * budget as `signal` has the first link spend all of it, and links two
+     * onward inherit a signal that is already aborted — so the "fallback" fails
+     * instantly and reports every vendor broken when only the first was slow.
+     * Handing each link its own budget is the only shape in which a deadline and
+     * a fallback can both be true.
+     */
+    timeoutMs?: number;
     /**
      * Set this GENEROUSLY, or a healthy model looks dead.
      *

package/dist/complete.js

@@ -79,6 +79,53 @@ export class LinkFailure extends Error {
         this.retryAfter = init.retryAfter;
     }
 }
+/**
+ * Long enough that a slow-but-working reasoning model finishes, short enough
+ * that a hung vendor does not hold a request open until something upstream
+ * gives up on it.
+ */
+const DEFAULT_TIMEOUT_MS = 30_000;
+/**
+ * One link's deadline, composed with the caller's cancellation.
+ *
+ * Hand-rolled rather than `AbortSignal.any`, which landed in Node 20.3 — this
+ * package supports Node >= 20, and a helper that works on 20.0 costs eight
+ * lines while an engines bump costs every consumer a decision.
+ */
+function linkDeadline(caller, timeoutMs) {
+    if (timeoutMs <= 0) {
+        return { signal: caller, timedOut: false, timeoutMs, dispose() { } };
+    }
+    const controller = new AbortController();
+    const state = { timedOut: false };
+    // Deliberately NOT unref'd. It is tempting — a stray timer holding a process
+    // open is a real nuisance — but this one is always cleared in `dispose`, so
+    // there is nothing to save, and an unref'd timer stops firing whenever
+    // nothing else keeps the loop alive. That turns the deadline into a deadline
+    // that sometimes does not happen, which is worse than none at all.
+    const timer = setTimeout(() => {
+        state.timedOut = true;
+        controller.abort(new Error(`link timeout after ${timeoutMs}ms`));
+    }, timeoutMs);
+    const onCallerAbort = () => controller.abort(caller?.reason);
+    if (caller) {
+        if (caller.aborted)
+            controller.abort(caller.reason);
+        else
+            caller.addEventListener("abort", onCallerAbort, { once: true });
+    }
+    return {
+        signal: controller.signal,
+        get timedOut() {
+            return state.timedOut;
+        },
+        timeoutMs,
+        dispose() {
+            clearTimeout(timer);
+            caller?.removeEventListener("abort", onCallerAbort);
+        },
+    };
+}
 /** `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}`;
@@ -139,20 +186,31 @@ async function callLink(link, options, key) {
         ...(options.tools === undefined ? {} : { tools: options.tools }),
         ...options.extraBody,
     };
+    const deadline = linkDeadline(options.signal, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
     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,
+            signal: deadline.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.
+        //
+        // Name a timeout as a timeout. "The operation was aborted" in a log is
+        // indistinguishable from a caller cancelling, and the two want opposite
+        // reactions from whoever reads it.
+        if (deadline.timedOut) {
+            throw new LinkFailure(link, `${linkId(link)}: no response within ${deadline.timeoutMs}ms — abandoned, trying the next link`);
+        }
         throw new LinkFailure(link, `${linkId(link)}: ${error.message}`);
     }
+    finally {
+        deadline.dispose();
+    }
     const text = await res.text();
     if (!res.ok) {
         if (res.status === 429) {
@@ -225,6 +283,12 @@ export async function complete(options) {
             options.onLinkFailure?.(link, failure);
             if (failure.kind === "daily")
                 deadProviders.add(link.provider.id);
+            // The caller cancelled — the request they were waiting on is gone. Walking
+            // the rest of the chain now would spend their daily budget on an answer
+            // nobody will read, and would report "every vendor failed" about vendors
+            // that were never asked.
+            if (options.signal?.aborted)
+                break;
             // 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")

package/dist/index.d.ts

@@ -54,5 +54,6 @@ export { type CatalogVerdict, type CheckCatalogOptions, checkCatalog, hasRot, de
 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

@@ -54,6 +54,7 @@ export { checkCatalog, hasRot, deadProviders, catalogReport, } from "./catalog.j
 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.

package/dist/liveness.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Can this deployment reach a model RIGHT NOW?
+ *
+ * ── The gap this closes ──────────────────────────────────────────────────────
+ * A health route that reports `createHealthTracker().getHealth()` reports what
+ * happened the last time the app happened to call a model. Straight after a
+ * deploy that is `"unknown"` — no calls yet — and "unknown" is what it stays
+ * until real traffic arrives. So the one question a deploy needs answered ("did
+ * I just ship a working AI path?") is exactly the one it cannot answer.
+ *
+ * Observed 2026-09-05, converting the first app to `complete()`: the deploy was
+ * green, the bundle provably contained the new code, both keys were present,
+ * `/api/health` returned 200 — and `llm.status` was `"unknown"`. Every signal
+ * available said "probably fine". The only paths that would have produced a
+ * real answer were an admin-authenticated form and two cron jobs that EMAIL
+ * REAL USERS. Verifying a deploy must never require spamming somebody.
+ *
+ * ── Why it is 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.
+ * The only thing that distinguishes them is making a call — so this makes one,
+ * deliberately, on demand.
+ *
+ * ── Why it must be gated and cached ──────────────────────────────────────────
+ * This spends real tokens from a free daily budget shared across the whole org.
+ * An ungated probe on a health route is a self-inflicted outage: a monitor
+ * polling every 30s would drain a 100k/day allowance and take the app's actual
+ * AI features down with it. So:
+ *
+ *   - a probe runs ONLY when asked for explicitly (`?probe=1`) AND the caller
+ *     proves it is allowed to (a secret), never on an ordinary health poll;
+ *   - a successful probe is CACHED for `minIntervalMs` (default 10 minutes),
+ *     so even an authorised caller in a retry loop cannot burn the budget. The
+ *     cached answer is returned with `cached: true` and the age, because a
+ *     nine-minute-old success is a different claim from a fresh one and the
+ *     reader deserves to know which they got.
+ *
+ * The prompt is deliberately tiny — a handful of tokens — because the question
+ * is "does the pipe carry water", not "is the model any good".
+ */
+import { type CompleteOptions } from "./complete.js";
+import type { HealthTracker } from "./health.js";
+export interface LivenessResult {
+    /** Did a model answer? */
+    ok: boolean;
+    /** `provider/model` that served it, when one did. */
+    servedBy?: string;
+    /** What the model actually said, trimmed — proof of a real generation, not a 200. */
+    answer?: string;
+    /** Round-trip milliseconds for a fresh probe. */
+    ms?: number;
+    /** True when this is a remembered result rather than a call made just now. */
+    cached: boolean;
+    /** Age of a cached result, in milliseconds. */
+    cachedAgeMs?: number;
+    /** Every link's failure, when the whole chain was exhausted. */
+    failures?: string[];
+    /** Why no call was attempted at all (no keys, no links). */
+    skipped?: string;
+}
+export interface LivenessOptions extends Omit<CompleteOptions, "messages" | "maxTokens" | "temperature"> {
+    /**
+     * Don't call again within this window; return the last successful result.
+     * Default 10 minutes. Set 0 to disable caching — only for a test.
+     */
+    minIntervalMs?: number;
+    /** Injected for tests. Defaults to `Date.now`. */
+    now?: () => number;
+}
+export interface LivenessProbe {
+    /** Make a call (or return a cached success). */
+    run(): Promise<LivenessResult>;
+    /** Forget any cached success — the next `run` will really call. */
+    reset(): void;
+}
+/**
+ * Build a probe with its own cache.
+ *
+ * The cache lives on the instance rather than in a module global so that two
+ * apps in one process, or a test, cannot silently share (and satisfy) each
+ * other's probe.
+ */
+export declare function createLivenessProbe(options?: LivenessOptions): LivenessProbe;
+export interface AiHealthHandlerOptions extends LivenessOptions {
+    /**
+     * Shared secret authorising a probe. Compared against the `x-probe-secret`
+     * header or a `secret` query parameter.
+     *
+     * When absent, the handler NEVER probes — it only reports passive health.
+     * That default is deliberate: an app that forgets to configure a secret gets
+     * a route that cannot spend money, rather than an open endpoint that can.
+     */
+    secret?: string;
+    /** Passive health to report alongside. Optional. */
+    health?: HealthTracker;
+}
+/**
+ * A framework-neutral `Request -> Response` handler for an AI health route.
+ *
+ * Web-standard on purpose: Next's App Router, Hono, Deno and Bun all accept
+ * this shape directly, so adopting it is an export line rather than a port.
+ *
+ *   GET /api/health/ai              passive — what happened last time. Free.
+ *   GET /api/health/ai?probe=1      makes a real call. Requires the secret.
+ *
+ * A probe without a valid secret is 401 and does NOT fall back to probing.
+ *
+ * Status codes are chosen so an uptime monitor can watch this URL directly:
+ * 200 when the answer is good, 503 when a probe was attempted and the chain
+ * could not answer.
+ */
+export declare function createAiHealthHandler(options?: AiHealthHandlerOptions): (request: Request) => Promise<Response>;

package/dist/liveness.js

@@ -0,0 +1,208 @@
+/**
+ * Can this deployment reach a model RIGHT NOW?
+ *
+ * ── The gap this closes ──────────────────────────────────────────────────────
+ * A health route that reports `createHealthTracker().getHealth()` reports what
+ * happened the last time the app happened to call a model. Straight after a
+ * deploy that is `"unknown"` — no calls yet — and "unknown" is what it stays
+ * until real traffic arrives. So the one question a deploy needs answered ("did
+ * I just ship a working AI path?") is exactly the one it cannot answer.
+ *
+ * Observed 2026-09-05, converting the first app to `complete()`: the deploy was
+ * green, the bundle provably contained the new code, both keys were present,
+ * `/api/health` returned 200 — and `llm.status` was `"unknown"`. Every signal
+ * available said "probably fine". The only paths that would have produced a
+ * real answer were an admin-authenticated form and two cron jobs that EMAIL
+ * REAL USERS. Verifying a deploy must never require spamming somebody.
+ *
+ * ── Why it is 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.
+ * The only thing that distinguishes them is making a call — so this makes one,
+ * deliberately, on demand.
+ *
+ * ── Why it must be gated and cached ──────────────────────────────────────────
+ * This spends real tokens from a free daily budget shared across the whole org.
+ * An ungated probe on a health route is a self-inflicted outage: a monitor
+ * polling every 30s would drain a 100k/day allowance and take the app's actual
+ * AI features down with it. So:
+ *
+ *   - a probe runs ONLY when asked for explicitly (`?probe=1`) AND the caller
+ *     proves it is allowed to (a secret), never on an ordinary health poll;
+ *   - a successful probe is CACHED for `minIntervalMs` (default 10 minutes),
+ *     so even an authorised caller in a retry loop cannot burn the budget. The
+ *     cached answer is returned with `cached: true` and the age, because a
+ *     nine-minute-old success is a different claim from a fresh one and the
+ *     reader deserves to know which they got.
+ *
+ * The prompt is deliberately tiny — a handful of tokens — because the question
+ * is "does the pipe carry water", not "is the model any good".
+ */
+import { complete } from "./complete.js";
+import { ChainExhaustedError } from "./attempt.js";
+const DEFAULT_MIN_INTERVAL_MS = 10 * 60 * 1000;
+/**
+ * The budget the probe asks for.
+ *
+ * NOT small, despite the tiny prompt. The chain leads with REASONING models,
+ * which spend this on hidden thinking before emitting a visible token: measured
+ * 2026-09-05, groq/openai/gpt-oss-20b answered EMPTY at 16 and correctly at 256
+ * for the same one-word question. An empty completion is a failure here (see
+ * complete.ts), so a mean budget would make a perfectly healthy deployment
+ * report itself dead — the exact false alarm this module exists to prevent.
+ */
+const PROBE_MAX_TOKENS = 256;
+/**
+ * Tighter than `complete`'s 30s default, per link.
+ *
+ * A monitor asking "is the AI up?" gives up long before a chain of 30-second
+ * links has finished being patient — and a health route that takes a minute to
+ * answer "down" has not answered at all, it has just become a second outage.
+ * Ten seconds is far above the ~1s a healthy free-tier link measures.
+ */
+const PROBE_TIMEOUT_MS = 10_000;
+/** A question with one short right answer, cheap to ask and easy to sanity-check. */
+const PROBE_MESSAGES = [
+    { role: "system", content: "Answer with a single word, no punctuation." },
+    { role: "user", content: "What colour is a clear midday sky? Answer in one word." },
+];
+/**
+ * Build a probe with its own cache.
+ *
+ * The cache lives on the instance rather than in a module global so that two
+ * apps in one process, or a test, cannot silently share (and satisfy) each
+ * other's probe.
+ */
+export function createLivenessProbe(options = {}) {
+    const minIntervalMs = options.minIntervalMs ?? DEFAULT_MIN_INTERVAL_MS;
+    const now = options.now ?? Date.now;
+    let lastOk = null;
+    return {
+        reset() {
+            lastOk = null;
+        },
+        async run() {
+            if (lastOk && minIntervalMs > 0) {
+                const age = now() - lastOk.at;
+                if (age < minIntervalMs) {
+                    return { ...lastOk.result, cached: true, cachedAgeMs: age };
+                }
+            }
+            const started = now();
+            try {
+                const result = await complete({
+                    timeoutMs: PROBE_TIMEOUT_MS,
+                    ...options,
+                    messages: PROBE_MESSAGES,
+                    maxTokens: PROBE_MAX_TOKENS,
+                    temperature: 0,
+                });
+                const answer = result.text.trim();
+                const fresh = {
+                    ok: true,
+                    servedBy: result.id,
+                    answer,
+                    ms: now() - started,
+                    cached: false,
+                };
+                lastOk = { at: now(), result: fresh };
+                return fresh;
+            }
+            catch (error) {
+                // A failure is deliberately NOT cached. Caching it would keep reporting
+                // an outage after the vendor recovered, and the whole point is to tell
+                // the truth about right now.
+                if (error instanceof ChainExhaustedError) {
+                    return {
+                        ok: false,
+                        cached: false,
+                        ms: now() - started,
+                        failures: error.failures.map((f) => f.message),
+                        ...(error.failures.length === 0
+                            ? { skipped: "No usable link — every provider is missing its key or has no models." }
+                            : {}),
+                    };
+                }
+                return {
+                    ok: false,
+                    cached: false,
+                    ms: now() - started,
+                    failures: [error instanceof Error ? error.message : String(error)],
+                };
+            }
+        },
+    };
+}
+/**
+ * A framework-neutral `Request -> Response` handler for an AI health route.
+ *
+ * Web-standard on purpose: Next's App Router, Hono, Deno and Bun all accept
+ * this shape directly, so adopting it is an export line rather than a port.
+ *
+ *   GET /api/health/ai              passive — what happened last time. Free.
+ *   GET /api/health/ai?probe=1      makes a real call. Requires the secret.
+ *
+ * A probe without a valid secret is 401 and does NOT fall back to probing.
+ *
+ * Status codes are chosen so an uptime monitor can watch this URL directly:
+ * 200 when the answer is good, 503 when a probe was attempted and the chain
+ * could not answer.
+ */
+export function createAiHealthHandler(options = {}) {
+    const { secret, health, ...probeOptions } = options;
+    const probe = createLivenessProbe(probeOptions);
+    return async function handler(request) {
+        const url = new URL(request.url);
+        const wantsProbe = url.searchParams.get("probe") === "1";
+        const offered = request.headers.get("x-probe-secret") ?? url.searchParams.get("secret") ?? undefined;
+        const passive = health ? { health: health.getHealth() } : {};
+        if (!wantsProbe) {
+            return json(200, { probed: false, ...passive });
+        }
+        // No secret configured means probing is switched off, which is a different
+        // answer from "your secret is wrong" — say so, rather than implying the
+        // caller could retry with a better credential.
+        if (!secret) {
+            return json(501, {
+                probed: false,
+                error: "Probing is not configured on this deployment (no secret set).",
+                ...passive,
+            });
+        }
+        if (!offered || !timingSafeEqual(offered, secret)) {
+            return json(401, { probed: false, error: "Bad or missing probe secret.", ...passive });
+        }
+        const result = await probe.run();
+        // Record into passive health too, so one probe also answers the next
+        // ordinary health poll — otherwise the probe's knowledge dies with it.
+        if (health) {
+            if (result.ok)
+                health.recordSuccess();
+            else
+                health.recordFailure(new Error(result.failures?.join("; ") ?? "probe failed"));
+        }
+        return json(result.ok ? 200 : 503, {
+            probed: true,
+            ...result,
+            ...(health ? { health: health.getHealth() } : {}),
+        });
+    };
+}
+function json(status, body) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "content-type": "application/json", "cache-control": "no-store" },
+    });
+}
+/**
+ * Constant-time comparison, so a wrong secret cannot be discovered one
+ * character at a time by timing the 401.
+ */
+function timingSafeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i += 1)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitbaum/ai-kit",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "One install for the AI layer of an app: which model to call, what to do when the vendor retires it, how to walk the fallback chain and know when none of it worked, how to read the three kinds of 429, a fair daily budget across users, headless AI form filling — and now the model registry (one SSOT for every callable id, with the paid/free boundary as a field) and the grounding harness (facts, contract, deterministic fabrication check).",
   "license": "MIT",
   "author": "Mao Nakamoto",

package/src/complete.ts

@@ -102,7 +102,33 @@ export interface CompleteOptions {
   model?: string;
   env?: Env;
   health?: HealthTracker;
+  /**
+   * The CALLER's cancellation, covering the whole walk. When this aborts, the
+   * walk stops — the caller has gone, so trying the next vendor on their behalf
+   * is work nobody is waiting for.
+   *
+   * Do not use this as a timeout. See `timeoutMs`.
+   */
   signal?: AbortSignal;
+  /**
+   * How long ONE link may take before it is abandoned and the next is tried.
+   * Default 30s. Set 0 to wait forever (not advised).
+   *
+   * Per LINK, and that is the whole point. A vendor that accepts the connection
+   * and then never answers is the most common partial outage there is, and it
+   * is the one a fallback chain is least able to survive: without a deadline,
+   * `await fetch` simply never returns and link two is never reached. A chain
+   * that cannot time out is not a fallback for the failure mode it most needs
+   * to cover.
+   *
+   * It is deliberately NOT the caller's `signal`. A caller who passes a 10s
+   * budget as `signal` has the first link spend all of it, and links two
+   * onward inherit a signal that is already aborted — so the "fallback" fails
+   * instantly and reports every vendor broken when only the first was slow.
+   * Handing each link its own budget is the only shape in which a deadline and
+   * a fallback can both be true.
+   */
+  timeoutMs?: number;
   /**
    * Set this GENEROUSLY, or a healthy model looks dead.
    *
@@ -164,6 +190,66 @@ export class LinkFailure extends Error {
   }
 }
 
+/**
+ * Long enough that a slow-but-working reasoning model finishes, short enough
+ * that a hung vendor does not hold a request open until something upstream
+ * gives up on it.
+ */
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+interface LinkDeadline {
+  signal: AbortSignal | undefined;
+  /** True when THIS link's own clock fired, rather than the caller cancelling. */
+  readonly timedOut: boolean;
+  readonly timeoutMs: number;
+  /** Always call. An uncleared timer keeps the event loop alive. */
+  dispose(): void;
+}
+
+/**
+ * One link's deadline, composed with the caller's cancellation.
+ *
+ * Hand-rolled rather than `AbortSignal.any`, which landed in Node 20.3 — this
+ * package supports Node >= 20, and a helper that works on 20.0 costs eight
+ * lines while an engines bump costs every consumer a decision.
+ */
+function linkDeadline(caller: AbortSignal | undefined, timeoutMs: number): LinkDeadline {
+  if (timeoutMs <= 0) {
+    return { signal: caller, timedOut: false, timeoutMs, dispose() {} };
+  }
+
+  const controller = new AbortController();
+  const state = { timedOut: false };
+
+  // Deliberately NOT unref'd. It is tempting — a stray timer holding a process
+  // open is a real nuisance — but this one is always cleared in `dispose`, so
+  // there is nothing to save, and an unref'd timer stops firing whenever
+  // nothing else keeps the loop alive. That turns the deadline into a deadline
+  // that sometimes does not happen, which is worse than none at all.
+  const timer = setTimeout(() => {
+    state.timedOut = true;
+    controller.abort(new Error(`link timeout after ${timeoutMs}ms`));
+  }, timeoutMs);
+
+  const onCallerAbort = () => controller.abort(caller?.reason);
+  if (caller) {
+    if (caller.aborted) controller.abort(caller.reason);
+    else caller.addEventListener("abort", onCallerAbort, { once: true });
+  }
+
+  return {
+    signal: controller.signal,
+    get timedOut() {
+      return state.timedOut;
+    },
+    timeoutMs,
+    dispose() {
+      clearTimeout(timer);
+      caller?.removeEventListener("abort", onCallerAbort);
+    },
+  };
+}
+
 /** `provider/model` — the id worth logging, because the model alone does not say whose meter it drew on. */
 export function linkId(link: Link): string {
   return `${link.provider.id}/${link.model}`;
@@ -230,18 +316,32 @@ async function callLink(
     ...options.extraBody,
   };
 
+  const deadline = linkDeadline(options.signal, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+
   let res: Response;
   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,
+      signal: deadline.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.
+    //
+    // Name a timeout as a timeout. "The operation was aborted" in a log is
+    // indistinguishable from a caller cancelling, and the two want opposite
+    // reactions from whoever reads it.
+    if (deadline.timedOut) {
+      throw new LinkFailure(
+        link,
+        `${linkId(link)}: no response within ${deadline.timeoutMs}ms — abandoned, trying the next link`,
+      );
+    }
     throw new LinkFailure(link, `${linkId(link)}: ${(error as Error).message}`);
+  } finally {
+    deadline.dispose();
   }
 
   const text = await res.text();
@@ -328,6 +428,12 @@ export async function complete(options: CompleteOptions): Promise<CompleteResult
 
       if (failure.kind === "daily") deadProviders.add(link.provider.id);
 
+      // The caller cancelled — the request they were waiting on is gone. Walking
+      // the rest of the chain now would spend their daily budget on an answer
+      // nobody will read, and would report "every vendor failed" about vendors
+      // that were never asked.
+      if (options.signal?.aborted) break;
+
       // 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;

package/src/index.ts

@@ -100,6 +100,15 @@ export {
   createHealthTracker,
 } from "./health.js";
 
+export {
+  type LivenessResult,
+  type LivenessOptions,
+  type LivenessProbe,
+  type AiHealthHandlerOptions,
+  createLivenessProbe,
+  createAiHealthHandler,
+} from "./liveness.js";
+
 export {
   type RateLimitKind,
   classifyRateLimit,

package/src/liveness.ts

@@ -0,0 +1,279 @@
+/**
+ * Can this deployment reach a model RIGHT NOW?
+ *
+ * ── The gap this closes ──────────────────────────────────────────────────────
+ * A health route that reports `createHealthTracker().getHealth()` reports what
+ * happened the last time the app happened to call a model. Straight after a
+ * deploy that is `"unknown"` — no calls yet — and "unknown" is what it stays
+ * until real traffic arrives. So the one question a deploy needs answered ("did
+ * I just ship a working AI path?") is exactly the one it cannot answer.
+ *
+ * Observed 2026-09-05, converting the first app to `complete()`: the deploy was
+ * green, the bundle provably contained the new code, both keys were present,
+ * `/api/health` returned 200 — and `llm.status` was `"unknown"`. Every signal
+ * available said "probably fine". The only paths that would have produced a
+ * real answer were an admin-authenticated form and two cron jobs that EMAIL
+ * REAL USERS. Verifying a deploy must never require spamming somebody.
+ *
+ * ── Why it is 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.
+ * The only thing that distinguishes them is making a call — so this makes one,
+ * deliberately, on demand.
+ *
+ * ── Why it must be gated and cached ──────────────────────────────────────────
+ * This spends real tokens from a free daily budget shared across the whole org.
+ * An ungated probe on a health route is a self-inflicted outage: a monitor
+ * polling every 30s would drain a 100k/day allowance and take the app's actual
+ * AI features down with it. So:
+ *
+ *   - a probe runs ONLY when asked for explicitly (`?probe=1`) AND the caller
+ *     proves it is allowed to (a secret), never on an ordinary health poll;
+ *   - a successful probe is CACHED for `minIntervalMs` (default 10 minutes),
+ *     so even an authorised caller in a retry loop cannot burn the budget. The
+ *     cached answer is returned with `cached: true` and the age, because a
+ *     nine-minute-old success is a different claim from a fresh one and the
+ *     reader deserves to know which they got.
+ *
+ * The prompt is deliberately tiny — a handful of tokens — because the question
+ * is "does the pipe carry water", not "is the model any good".
+ */
+
+import { complete, type CompleteOptions } from "./complete.js";
+import { ChainExhaustedError } from "./attempt.js";
+import type { HealthTracker } from "./health.js";
+
+export interface LivenessResult {
+  /** Did a model answer? */
+  ok: boolean;
+  /** `provider/model` that served it, when one did. */
+  servedBy?: string;
+  /** What the model actually said, trimmed — proof of a real generation, not a 200. */
+  answer?: string;
+  /** Round-trip milliseconds for a fresh probe. */
+  ms?: number;
+  /** True when this is a remembered result rather than a call made just now. */
+  cached: boolean;
+  /** Age of a cached result, in milliseconds. */
+  cachedAgeMs?: number;
+  /** Every link's failure, when the whole chain was exhausted. */
+  failures?: string[];
+  /** Why no call was attempted at all (no keys, no links). */
+  skipped?: string;
+}
+
+export interface LivenessOptions extends Omit<
+  CompleteOptions,
+  "messages" | "maxTokens" | "temperature"
+> {
+  /**
+   * Don't call again within this window; return the last successful result.
+   * Default 10 minutes. Set 0 to disable caching — only for a test.
+   */
+  minIntervalMs?: number;
+  /** Injected for tests. Defaults to `Date.now`. */
+  now?: () => number;
+}
+
+const DEFAULT_MIN_INTERVAL_MS = 10 * 60 * 1000;
+
+/**
+ * The budget the probe asks for.
+ *
+ * NOT small, despite the tiny prompt. The chain leads with REASONING models,
+ * which spend this on hidden thinking before emitting a visible token: measured
+ * 2026-09-05, groq/openai/gpt-oss-20b answered EMPTY at 16 and correctly at 256
+ * for the same one-word question. An empty completion is a failure here (see
+ * complete.ts), so a mean budget would make a perfectly healthy deployment
+ * report itself dead — the exact false alarm this module exists to prevent.
+ */
+const PROBE_MAX_TOKENS = 256;
+
+/**
+ * Tighter than `complete`'s 30s default, per link.
+ *
+ * A monitor asking "is the AI up?" gives up long before a chain of 30-second
+ * links has finished being patient — and a health route that takes a minute to
+ * answer "down" has not answered at all, it has just become a second outage.
+ * Ten seconds is far above the ~1s a healthy free-tier link measures.
+ */
+const PROBE_TIMEOUT_MS = 10_000;
+
+/** A question with one short right answer, cheap to ask and easy to sanity-check. */
+const PROBE_MESSAGES = [
+  { role: "system" as const, content: "Answer with a single word, no punctuation." },
+  { role: "user" as const, content: "What colour is a clear midday sky? Answer in one word." },
+];
+
+export interface LivenessProbe {
+  /** Make a call (or return a cached success). */
+  run(): Promise<LivenessResult>;
+  /** Forget any cached success — the next `run` will really call. */
+  reset(): void;
+}
+
+/**
+ * Build a probe with its own cache.
+ *
+ * The cache lives on the instance rather than in a module global so that two
+ * apps in one process, or a test, cannot silently share (and satisfy) each
+ * other's probe.
+ */
+export function createLivenessProbe(options: LivenessOptions = {}): LivenessProbe {
+  const minIntervalMs = options.minIntervalMs ?? DEFAULT_MIN_INTERVAL_MS;
+  const now = options.now ?? Date.now;
+
+  let lastOk: { at: number; result: LivenessResult } | null = null;
+
+  return {
+    reset() {
+      lastOk = null;
+    },
+
+    async run(): Promise<LivenessResult> {
+      if (lastOk && minIntervalMs > 0) {
+        const age = now() - lastOk.at;
+        if (age < minIntervalMs) {
+          return { ...lastOk.result, cached: true, cachedAgeMs: age };
+        }
+      }
+
+      const started = now();
+      try {
+        const result = await complete({
+          timeoutMs: PROBE_TIMEOUT_MS,
+          ...options,
+          messages: PROBE_MESSAGES,
+          maxTokens: PROBE_MAX_TOKENS,
+          temperature: 0,
+        });
+
+        const answer = result.text.trim();
+        const fresh: LivenessResult = {
+          ok: true,
+          servedBy: result.id,
+          answer,
+          ms: now() - started,
+          cached: false,
+        };
+        lastOk = { at: now(), result: fresh };
+        return fresh;
+      } catch (error) {
+        // A failure is deliberately NOT cached. Caching it would keep reporting
+        // an outage after the vendor recovered, and the whole point is to tell
+        // the truth about right now.
+        if (error instanceof ChainExhaustedError) {
+          return {
+            ok: false,
+            cached: false,
+            ms: now() - started,
+            failures: error.failures.map((f) => f.message),
+            ...(error.failures.length === 0
+              ? { skipped: "No usable link — every provider is missing its key or has no models." }
+              : {}),
+          };
+        }
+        return {
+          ok: false,
+          cached: false,
+          ms: now() - started,
+          failures: [error instanceof Error ? error.message : String(error)],
+        };
+      }
+    },
+  };
+}
+
+export interface AiHealthHandlerOptions extends LivenessOptions {
+  /**
+   * Shared secret authorising a probe. Compared against the `x-probe-secret`
+   * header or a `secret` query parameter.
+   *
+   * When absent, the handler NEVER probes — it only reports passive health.
+   * That default is deliberate: an app that forgets to configure a secret gets
+   * a route that cannot spend money, rather than an open endpoint that can.
+   */
+  secret?: string;
+  /** Passive health to report alongside. Optional. */
+  health?: HealthTracker;
+}
+
+/**
+ * A framework-neutral `Request -> Response` handler for an AI health route.
+ *
+ * Web-standard on purpose: Next's App Router, Hono, Deno and Bun all accept
+ * this shape directly, so adopting it is an export line rather than a port.
+ *
+ *   GET /api/health/ai              passive — what happened last time. Free.
+ *   GET /api/health/ai?probe=1      makes a real call. Requires the secret.
+ *
+ * A probe without a valid secret is 401 and does NOT fall back to probing.
+ *
+ * Status codes are chosen so an uptime monitor can watch this URL directly:
+ * 200 when the answer is good, 503 when a probe was attempted and the chain
+ * could not answer.
+ */
+export function createAiHealthHandler(
+  options: AiHealthHandlerOptions = {},
+): (request: Request) => Promise<Response> {
+  const { secret, health, ...probeOptions } = options;
+  const probe = createLivenessProbe(probeOptions);
+
+  return async function handler(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    const wantsProbe = url.searchParams.get("probe") === "1";
+    const offered =
+      request.headers.get("x-probe-secret") ?? url.searchParams.get("secret") ?? undefined;
+
+    const passive = health ? { health: health.getHealth() } : {};
+
+    if (!wantsProbe) {
+      return json(200, { probed: false, ...passive });
+    }
+
+    // No secret configured means probing is switched off, which is a different
+    // answer from "your secret is wrong" — say so, rather than implying the
+    // caller could retry with a better credential.
+    if (!secret) {
+      return json(501, {
+        probed: false,
+        error: "Probing is not configured on this deployment (no secret set).",
+        ...passive,
+      });
+    }
+    if (!offered || !timingSafeEqual(offered, secret)) {
+      return json(401, { probed: false, error: "Bad or missing probe secret.", ...passive });
+    }
+
+    const result = await probe.run();
+    // Record into passive health too, so one probe also answers the next
+    // ordinary health poll — otherwise the probe's knowledge dies with it.
+    if (health) {
+      if (result.ok) health.recordSuccess();
+      else health.recordFailure(new Error(result.failures?.join("; ") ?? "probe failed"));
+    }
+    return json(result.ok ? 200 : 503, {
+      probed: true,
+      ...result,
+      ...(health ? { health: health.getHealth() } : {}),
+    });
+  };
+}
+
+function json(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json", "cache-control": "no-store" },
+  });
+}
+
+/**
+ * Constant-time comparison, so a wrong secret cannot be discovered one
+ * character at a time by timing the 401.
+ */
+function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i += 1) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}