@bitbaum/ai-kit 0.6.2 → 0.8.0

package/src/complete.ts

@@ -0,0 +1,340 @@
+/**
+ * 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, chainFrom, freeChain, usableChain } from "./chain.js";
+import { ChainExhaustedError, type ChainAttemptFailure } from "./attempt.js";
+import type { HealthTracker } from "./health.js";
+import { classifyRateLimit, retryAfterSeconds, 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 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 } = {},
+  ) {
+    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: Link): string {
+  return `${link.provider.id}/${link.model}`;
+}
+
+function firstText(message: Record<string, unknown> | undefined): string {
+  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 as { text?: unknown }).text === "string"
+          ? (part as { text: string }).text
+          : "",
+      )
+      .join("");
+  }
+  return "";
+}
+
+function toolCallsFrom(message: Record<string, unknown> | undefined): ToolCall[] {
+  const raw = message?.tool_calls;
+  if (!Array.isArray(raw)) return [];
+  const out: ToolCall[] = [];
+  for (const entry of raw) {
+    if (!entry || typeof entry !== "object") continue;
+    const fn = (entry as { function?: { name?: unknown; arguments?: unknown } }).function;
+    if (!fn || typeof fn.name !== "string") continue;
+    out.push({
+      id: String((entry as { id?: unknown }).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: string, limit = 300): string {
+  const flat = body.replace(/\s+/g, " ").trim();
+  return flat.length > limit ? `${flat.slice(0, limit)}…` : flat;
+}
+
+async function callLink(
+  link: Link,
+  options: CompleteOptions,
+  key: string,
+): Promise<CompleteResult> {
+  const doFetch = options.fetchImpl ?? globalThis.fetch;
+  const body: Record<string, unknown> = {
+    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: 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,
+    });
+  } 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 as 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: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new LinkFailure(link, `${linkId(link)}: 200 with unparseable body — ${excerpt(text)}`, {
+      status: res.status,
+    });
+  }
+
+  const choice = (parsed as { choices?: Array<{ message?: Record<string, unknown> }> })
+    ?.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: CompleteOptions): Promise<CompleteResult> {
+  const env = options.env ?? process.env;
+  const base = options.chain ?? usableChain(options.providers ?? freeChain(), env);
+  const chain = chainFrom(options.model, base);
+
+  const failures: ChainAttemptFailure[] = [];
+  const deadProviders = new Set<string>();
+
+  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 as LinkFailure;
+      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/src/index.ts

@@ -34,13 +34,20 @@
  * 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 {
@@ -75,6 +82,16 @@ export {
   tryChain,
 } from "./attempt.js";
 
+export {
+  type ChatMessage,
+  type ToolCall,
+  type CompleteOptions,
+  type CompleteResult,
+  LinkFailure,
+  complete,
+  linkId,
+} from "./complete.js";
+
 export {
   type HealthStatus,
   type Health,
@@ -83,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;
+}