@bitbaum/ai-kit 0.11.0 → 0.13.0

package/dist/complete.js

@@ -291,6 +291,25 @@ export async function complete(options) {
             options.onLinkFailure?.(link, failure);
             if (failure.kind === "daily")
                 deadProviders.add(link.provider.id);
+            // A REJECTED KEY is a verdict about the VENDOR, not the model.
+            //
+            // 401/403 says "not you". Every remaining link at this provider presents
+            // the identical credential, so walking them spends a request each to be
+            // told the same thing — and then reports "all 5 links failed", which
+            // reads as an outage at someone else's shop and sends the reader looking
+            // for one. The fact worth surfacing is that a key this app holds was
+            // refused.
+            //
+            // Crossing to the NEXT vendor still happens: that is a different key, and
+            // the whole reason the chain spans vendors.
+            //
+            // Deliberately narrow. A 404 is a retired id, a 5xx is a vendor being
+            // unwell, a capacity 429 is a busy minute — all three are answered by
+            // asking a different model, and widening this skip to cover them would
+            // quietly turn the chain back into the pin it replaced.
+            if (failure.status === 401 || failure.status === 403) {
+                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

package/dist/liveness.d.ts

@@ -39,7 +39,7 @@
  * is "does the pipe carry water", not "is the model any good".
  */
 import { type CompleteOptions } from "./complete.js";
-import type { Link } from "./chain.js";
+import type { Link, Env } from "./chain.js";
 import type { HealthTracker } from "./health.js";
 export interface LivenessResult {
     /** Did a model answer? */
@@ -78,9 +78,22 @@ export interface LivenessOptions extends Omit<CompleteOptions, "messages" | "max
      * It is called only on a real probe, never on a cache hit, so a monitor
      * polling this route does not also poll the database.
      *
+     * Return `{ chain, env }` when the KEYS move with the chain — an admin
+     * screen that stores a per-provider key alongside the model is the ordinary
+     * case, and resolving links from the database while reading credentials from
+     * a `process.env` captured at construction would have the probe report "no
+     * key" for a provider that is configured and working. Returning a bare
+     * `Link[]` keeps whatever `env` the probe was built with.
+     *
      * Takes precedence over `chain` when both are given.
      */
-    resolveChain?: () => Link[] | Promise<Link[]>;
+    resolveChain?: () => Link[] | {
+        chain: Link[];
+        env?: Env;
+    } | Promise<Link[] | {
+        chain: Link[];
+        env?: Env;
+    }>;
     /** Injected for tests. Defaults to `Date.now`. */
     now?: () => number;
 }

package/dist/liveness.js

@@ -92,11 +92,17 @@ export function createLivenessProbe(options = {}) {
             try {
                 // 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 chain = options.resolveChain ? await options.resolveChain() : options.chain;
+                const resolved = options.resolveChain ? await options.resolveChain() : options.chain;
+                const chain = Array.isArray(resolved) ? resolved : resolved?.chain;
+                // Only when the resolver supplied one. Otherwise the probe keeps the
+                // env it was built with, so a bare `Link[]` resolver behaves exactly
+                // as it did before this option grew a second shape.
+                const env = !Array.isArray(resolved) && resolved?.env !== undefined ? resolved.env : options.env;
                 const result = await complete({
                     timeoutMs: PROBE_TIMEOUT_MS,
                     ...options,
                     chain,
+                    env,
                     messages: PROBE_MESSAGES,
                     maxTokens: PROBE_MAX_TOKENS,
                     temperature: 0,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitbaum/ai-kit",
-  "version": "0.11.0",
+  "version": "0.13.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

@@ -449,6 +449,26 @@ export async function complete(options: CompleteOptions): Promise<CompleteResult
 
       if (failure.kind === "daily") deadProviders.add(link.provider.id);
 
+      // A REJECTED KEY is a verdict about the VENDOR, not the model.
+      //
+      // 401/403 says "not you". Every remaining link at this provider presents
+      // the identical credential, so walking them spends a request each to be
+      // told the same thing — and then reports "all 5 links failed", which
+      // reads as an outage at someone else's shop and sends the reader looking
+      // for one. The fact worth surfacing is that a key this app holds was
+      // refused.
+      //
+      // Crossing to the NEXT vendor still happens: that is a different key, and
+      // the whole reason the chain spans vendors.
+      //
+      // Deliberately narrow. A 404 is a retired id, a 5xx is a vendor being
+      // unwell, a capacity 429 is a busy minute — all three are answered by
+      // asking a different model, and widening this skip to cover them would
+      // quietly turn the chain back into the pin it replaced.
+      if (failure.status === 401 || failure.status === 403) {
+        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

package/src/liveness.ts

@@ -40,7 +40,7 @@
  */
 
 import { complete, type CompleteOptions } from "./complete.js";
-import type { Link } from "./chain.js";
+import type { Link, Env } from "./chain.js";
 import { ChainExhaustedError } from "./attempt.js";
 import type { HealthTracker } from "./health.js";
 
@@ -85,9 +85,17 @@ export interface LivenessOptions extends Omit<
    * It is called only on a real probe, never on a cache hit, so a monitor
    * polling this route does not also poll the database.
    *
+   * Return `{ chain, env }` when the KEYS move with the chain — an admin
+   * screen that stores a per-provider key alongside the model is the ordinary
+   * case, and resolving links from the database while reading credentials from
+   * a `process.env` captured at construction would have the probe report "no
+   * key" for a provider that is configured and working. Returning a bare
+   * `Link[]` keeps whatever `env` the probe was built with.
+   *
    * Takes precedence over `chain` when both are given.
    */
-  resolveChain?: () => Link[] | Promise<Link[]>;
+  resolveChain?: () =>
+    Link[] | { chain: Link[]; env?: Env } | Promise<Link[] | { chain: Link[]; env?: Env }>;
   /** Injected for tests. Defaults to `Date.now`. */
   now?: () => number;
 }
@@ -159,12 +167,19 @@ export function createLivenessProbe(options: LivenessOptions = {}): LivenessProb
       try {
         // 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 chain = options.resolveChain ? await options.resolveChain() : options.chain;
+        const resolved = options.resolveChain ? await options.resolveChain() : options.chain;
+        const chain = Array.isArray(resolved) ? resolved : resolved?.chain;
+        // Only when the resolver supplied one. Otherwise the probe keeps the
+        // env it was built with, so a bare `Link[]` resolver behaves exactly
+        // as it did before this option grew a second shape.
+        const env =
+          !Array.isArray(resolved) && resolved?.env !== undefined ? resolved.env : options.env;
 
         const result = await complete({
           timeoutMs: PROBE_TIMEOUT_MS,
           ...options,
           chain,
+          env,
           messages: PROBE_MESSAGES,
           maxTokens: PROBE_MAX_TOKENS,
           temperature: 0,