@bitbaum/ai-kit 0.7.0 → 0.8.0

package/README.md

@@ -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.
 
@@ -180,14 +269,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/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,198 @@
+/**
+ * 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;
+/** 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({
+                    ...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.8.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/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,268 @@
+/**
+ * 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;
+
+/** 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({
+          ...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;
+}