@bitbaum/ai-kit 0.13.0 → 0.15.0

package/dist/liveness.d.ts

@@ -94,6 +94,36 @@ export interface LivenessOptions extends Omit<CompleteOptions, "messages" | "max
         chain: Link[];
         env?: Env;
     }>;
+    /**
+     * Make the call YOURSELF, using the app's own path. Takes precedence over
+     * `chain` and `resolveChain`.
+     *
+     * Not every app can hand over a `Link[]`. Four in this fleet cannot: one
+     * builds its chain from its own provider CLASSES, one from a registry it
+     * deliberately owns (its BYOK list includes paid ids), one talks to a single
+     * operator-configured endpoint chosen for data residency, and one keeps a
+     * provider layer that predates this package. Requiring a chain would have
+     * meant either rewriting those or leaving them with no probe at all — and
+     * "no probe" is what left seven apps unable to answer "does the AI work?"
+     * after a fleet-wide refactor.
+     *
+     * There is a second, better reason. A probe built from a chain this module
+     * assembles tests A path; `ask` tests THE path — the same function the app's
+     * real features call. That is strictly stronger evidence, and it means the
+     * probe cannot quietly drift away from the code it is meant to vouch for.
+     *
+     * Everything else still applies: it runs only on an explicit, authorised
+     * probe, a success is cached, and a failure never is. Return the text the
+     * model produced and, if you have it, the `provider/model` that served it.
+     *
+     * An empty or whitespace-only `text` is treated as a FAILURE, for the same
+     * reason `complete()` treats it as one: a 200 carrying nothing is the
+     * failure most likely to be reported as success.
+     */
+    ask?: () => Promise<{
+        text: string;
+        id?: string;
+    }>;
     /** Injected for tests. Defaults to `Date.now`. */
     now?: () => number;
 }
@@ -119,8 +149,15 @@ export interface AiHealthHandlerOptions extends LivenessOptions {
      * 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.
+     *
+     * Pass a FUNCTION to read it per request. A handler is normally built once
+     * and reused (its cache has to live somewhere), so a plain string is captured
+     * at that moment — which means the secret is whatever the environment held on
+     * the first request, and rotating it needs a process restart. A getter also
+     * makes the route testable: with a captured string, the first test that runs
+     * without a secret configured pins every later one to 501.
      */
-    secret?: string;
+    secret?: string | (() => string | undefined);
     /** Passive health to report alongside. Optional. */
     health?: HealthTracker;
 }

package/dist/liveness.js

@@ -90,6 +90,26 @@ export function createLivenessProbe(options = {}) {
             }
             const started = now();
             try {
+                if (options.ask) {
+                    const asked = await options.ask();
+                    const text = asked.text.trim();
+                    // Same rule as `complete()`: a 200 carrying nothing is not an answer.
+                    // Without this, an app whose own path returns "" on failure — several
+                    // do, by design, so callers can degrade — would report itself healthy
+                    // on exactly the outage this route exists to catch.
+                    if (text === "") {
+                        throw new Error("the app's own path returned empty content — no output was produced");
+                    }
+                    const fresh = {
+                        ok: true,
+                        ...(asked.id ? { servedBy: asked.id } : {}),
+                        answer: text,
+                        ms: now() - started,
+                        cached: false,
+                    };
+                    lastOk = { at: now(), result: fresh };
+                    return fresh;
+                }
                 // Resolved here, not at construction, and only on a real probe — so a
                 // monitor polling this route does not also poll whatever backs it.
                 const resolved = options.resolveChain ? await options.resolveChain() : options.chain;
@@ -169,17 +189,20 @@ export function createAiHealthHandler(options = {}) {
         if (!wantsProbe) {
             return json(200, { probed: false, ...passive });
         }
+        // Read per request when a getter was given, so rotating the secret does not
+        // need a restart and a route built before the env was set is not stuck.
+        const expected = typeof secret === "function" ? secret() : secret;
         // 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) {
+        if (!expected) {
             return json(501, {
                 probed: false,
                 error: "Probing is not configured on this deployment (no secret set).",
                 ...passive,
             });
         }
-        if (!offered || !timingSafeEqual(offered, secret)) {
+        if (!offered || !timingSafeEqual(offered, expected)) {
             return json(401, { probed: false, error: "Bad or missing probe secret.", ...passive });
         }
         const result = await probe.run();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitbaum/ai-kit",
-  "version": "0.13.0",
+  "version": "0.15.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/liveness.ts

@@ -96,6 +96,33 @@ export interface LivenessOptions extends Omit<
    */
   resolveChain?: () =>
     Link[] | { chain: Link[]; env?: Env } | Promise<Link[] | { chain: Link[]; env?: Env }>;
+  /**
+   * Make the call YOURSELF, using the app's own path. Takes precedence over
+   * `chain` and `resolveChain`.
+   *
+   * Not every app can hand over a `Link[]`. Four in this fleet cannot: one
+   * builds its chain from its own provider CLASSES, one from a registry it
+   * deliberately owns (its BYOK list includes paid ids), one talks to a single
+   * operator-configured endpoint chosen for data residency, and one keeps a
+   * provider layer that predates this package. Requiring a chain would have
+   * meant either rewriting those or leaving them with no probe at all — and
+   * "no probe" is what left seven apps unable to answer "does the AI work?"
+   * after a fleet-wide refactor.
+   *
+   * There is a second, better reason. A probe built from a chain this module
+   * assembles tests A path; `ask` tests THE path — the same function the app's
+   * real features call. That is strictly stronger evidence, and it means the
+   * probe cannot quietly drift away from the code it is meant to vouch for.
+   *
+   * Everything else still applies: it runs only on an explicit, authorised
+   * probe, a success is cached, and a failure never is. Return the text the
+   * model produced and, if you have it, the `provider/model` that served it.
+   *
+   * An empty or whitespace-only `text` is treated as a FAILURE, for the same
+   * reason `complete()` treats it as one: a 200 carrying nothing is the
+   * failure most likely to be reported as success.
+   */
+  ask?: () => Promise<{ text: string; id?: string }>;
   /** Injected for tests. Defaults to `Date.now`. */
   now?: () => number;
 }
@@ -165,6 +192,27 @@ export function createLivenessProbe(options: LivenessOptions = {}): LivenessProb
 
       const started = now();
       try {
+        if (options.ask) {
+          const asked = await options.ask();
+          const text = asked.text.trim();
+          // Same rule as `complete()`: a 200 carrying nothing is not an answer.
+          // Without this, an app whose own path returns "" on failure — several
+          // do, by design, so callers can degrade — would report itself healthy
+          // on exactly the outage this route exists to catch.
+          if (text === "") {
+            throw new Error("the app's own path returned empty content — no output was produced");
+          }
+          const fresh: LivenessResult = {
+            ok: true,
+            ...(asked.id ? { servedBy: asked.id } : {}),
+            answer: text,
+            ms: now() - started,
+            cached: false,
+          };
+          lastOk = { at: now(), result: fresh };
+          return fresh;
+        }
+
         // Resolved here, not at construction, and only on a real probe — so a
         // monitor polling this route does not also poll whatever backs it.
         const resolved = options.resolveChain ? await options.resolveChain() : options.chain;
@@ -229,8 +277,15 @@ export interface AiHealthHandlerOptions extends LivenessOptions {
    * 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.
+   *
+   * Pass a FUNCTION to read it per request. A handler is normally built once
+   * and reused (its cache has to live somewhere), so a plain string is captured
+   * at that moment — which means the secret is whatever the environment held on
+   * the first request, and rotating it needs a process restart. A getter also
+   * makes the route testable: with a captured string, the first test that runs
+   * without a secret configured pins every later one to 501.
    */
-  secret?: string;
+  secret?: string | (() => string | undefined);
   /** Passive health to report alongside. Optional. */
   health?: HealthTracker;
 }
@@ -268,17 +323,21 @@ export function createAiHealthHandler(
       return json(200, { probed: false, ...passive });
     }
 
+    // Read per request when a getter was given, so rotating the secret does not
+    // need a restart and a route built before the env was set is not stuck.
+    const expected = typeof secret === "function" ? secret() : secret;
+
     // 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) {
+    if (!expected) {
       return json(501, {
         probed: false,
         error: "Probing is not configured on this deployment (no secret set).",
         ...passive,
       });
     }
-    if (!offered || !timingSafeEqual(offered, secret)) {
+    if (!offered || !timingSafeEqual(offered, expected)) {
       return json(401, { probed: false, error: "Bad or missing probe secret.", ...passive });
     }