@bitbaum/ai-kit 0.8.0 → 0.10.0

package/README.md

@@ -100,6 +100,28 @@ 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

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.
      *
@@ -115,6 +141,19 @@ export interface CompleteOptions {
     tools?: unknown[];
     /** Extra body fields for a vendor-specific parameter. Merged last, so it can override. */
     extraBody?: Record<string, unknown>;
+    /**
+     * Extra request headers. Merged last, so a caller can override `content-type`
+     * — but NOT `authorization`, which stays the key this module resolved.
+     *
+     * Vendors ask for these and quietly change behaviour without them:
+     * OpenRouter reads `HTTP-Referer` and `X-Title` for app attribution in its
+     * public rankings, and an app that stops sending them simply disappears from
+     * that list with no error anywhere. Without this option, adopting `complete`
+     * would mean silently dropping them, which is exactly the kind of small,
+     * invisible regression that makes a shared engine feel worse than the
+     * hand-rolled client it replaced.
+     */
+    extraHeaders?: Record<string, string>;
     /** 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`. */

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,39 @@ 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}` },
+            headers: {
+                "content-type": "application/json",
+                ...options.extraHeaders,
+                // Last on purpose. A caller may add or override any header it likes,
+                // but not this one: silently sending someone else's credential — or
+                // none — would turn a typo in a caller's header map into an auth
+                // failure blamed on the vendor.
+                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 +291,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/liveness.js

@@ -52,6 +52,15 @@ const DEFAULT_MIN_INTERVAL_MS = 10 * 60 * 1000;
  * 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." },
@@ -82,6 +91,7 @@ export function createLivenessProbe(options = {}) {
             const started = now();
             try {
                 const result = await complete({
+                    timeoutMs: PROBE_TIMEOUT_MS,
                     ...options,
                     messages: PROBE_MESSAGES,
                     maxTokens: PROBE_MAX_TOKENS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitbaum/ai-kit",
-  "version": "0.8.0",
+  "version": "0.10.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.
    *
@@ -120,6 +146,19 @@ export interface CompleteOptions {
   tools?: unknown[];
   /** Extra body fields for a vendor-specific parameter. Merged last, so it can override. */
   extraBody?: Record<string, unknown>;
+  /**
+   * Extra request headers. Merged last, so a caller can override `content-type`
+   * — but NOT `authorization`, which stays the key this module resolved.
+   *
+   * Vendors ask for these and quietly change behaviour without them:
+   * OpenRouter reads `HTTP-Referer` and `X-Title` for app attribution in its
+   * public rankings, and an app that stops sending them simply disappears from
+   * that list with no error anywhere. Without this option, adopting `complete`
+   * would mean silently dropping them, which is exactly the kind of small,
+   * invisible regression that makes a shared engine feel worse than the
+   * hand-rolled client it replaced.
+   */
+  extraHeaders?: Record<string, string>;
   /** 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`. */
@@ -164,6 +203,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 +329,40 @@ 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}` },
+      headers: {
+        "content-type": "application/json",
+        ...options.extraHeaders,
+        // Last on purpose. A caller may add or override any header it likes,
+        // but not this one: silently sending someone else's credential — or
+        // none — would turn a typo in a caller's header map into an auth
+        // failure blamed on the vendor.
+        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 +449,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/liveness.ts

@@ -89,6 +89,16 @@ const DEFAULT_MIN_INTERVAL_MS = 10 * 60 * 1000;
  */
 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." },
@@ -131,6 +141,7 @@ export function createLivenessProbe(options: LivenessOptions = {}): LivenessProb
       const started = now();
       try {
         const result = await complete({
+          timeoutMs: PROBE_TIMEOUT_MS,
           ...options,
           messages: PROBE_MESSAGES,
           maxTokens: PROBE_MAX_TOKENS,