@bitbaum/ai-kit 0.14.0 → 0.16.0

package/dist-cjs/grounding/facts.js

@@ -63,6 +63,13 @@ exports.FACT_KINDS = {
     assignment: ["title", "assignee", "status", "due", "fee", "why"],
     document: ["title", "source", "excerpt"],
     pending_action: ["title", "type", "reasoning", "proposed_on", "id"],
+    // Retrieved from the open web rather than stored. `url` is the field that
+    // makes these checkable by a human reader, which is what separates a cited
+    // claim from a confident one. The rest are declared precisely BECAUSE search
+    // engines so often omit them: a rendered `published: <not recorded>` is what
+    // stops a model putting a year on an undated page.
+    web_result: ["title", "url", "published", "snippet", "engine"],
+    web_page: ["title", "url", "retrieved", "truncated"],
 };
 /** Field list for a kind; unknown kinds fall back to whatever the fact carries. */
 function declaredFields(kind, fallback = []) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitbaum/ai-kit",
-  "version": "0.14.0",
+  "version": "0.16.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",
@@ -63,6 +63,10 @@
       "require": "./dist-cjs/registry.js",
       "default": "./dist/registry.js"
     },
+    "./web": {
+      "types": "./dist/web/index.d.ts",
+      "default": "./dist/web/index.js"
+    },
     "./grounding": {
       "types": "./dist/grounding/index.d.ts",
       "require": "./dist-cjs/grounding/index.js",

package/src/grounding/facts.ts

@@ -80,6 +80,13 @@ export const FACT_KINDS: Record<string, readonly string[]> = {
   assignment: ["title", "assignee", "status", "due", "fee", "why"],
   document: ["title", "source", "excerpt"],
   pending_action: ["title", "type", "reasoning", "proposed_on", "id"],
+  // Retrieved from the open web rather than stored. `url` is the field that
+  // makes these checkable by a human reader, which is what separates a cited
+  // claim from a confident one. The rest are declared precisely BECAUSE search
+  // engines so often omit them: a rendered `published: <not recorded>` is what
+  // stops a model putting a year on an undated page.
+  web_result: ["title", "url", "published", "snippet", "engine"],
+  web_page: ["title", "url", "retrieved", "truncated"],
 };
 
 /** Field list for a kind; unknown kinds fall back to whatever the fact carries. */

package/src/liveness.ts

@@ -277,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;
 }
@@ -316,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 });
     }
 

package/src/web/facts.ts

@@ -0,0 +1,117 @@
+/**
+ * Web results → grounded Facts.
+ *
+ * This is the join that makes web search safe to give an agent. On its own,
+ * search makes hallucination WORSE, not better: the model now has a pile of
+ * plausible-sounding text from strangers, mixed into a context window beside
+ * the user's real data, with nothing marking which sentence came from where.
+ * The failure mode is not "the model made something up" — it is "the model
+ * attributed a real sentence to the wrong source", and that is indistinguishable
+ * from competence until someone clicks the link.
+ *
+ * The fix is the one the grounding harness already implements for database
+ * rows. Every retrieved item becomes a `Fact` with a citation handle ([F3]) and
+ * a `url` field, `verifyAnswer` then checks mechanically that every handle in
+ * the answer exists and that proper nouns and numbers in the answer appear in
+ * the evidence. A claim that cites nothing, or cites [F9] when only F1–F4 were
+ * retrieved, is caught by a string check rather than by a reviewer's judgement.
+ *
+ * Two sets come out of here on purpose:
+ *
+ *   facts    — the citable records. Short, uniform, one block per source.
+ *   evidence — the actual prose (snippets, page text). The verifier needs the
+ *              words themselves to judge whether "€4.2 billion" in the answer
+ *              was read or invented; a fact's five short fields are not enough
+ *              of a corpus for that, and passing the page text AS a fact field
+ *              would bury the citable metadata in ten thousand characters.
+ */
+import { makeFact, type Fact } from "../grounding/facts.js";
+import type { PageOutcome, WebResult } from "./types.js";
+import type { WebSearchResult } from "./search.js";
+
+/** Search hits as citable records. Order is the engine's ranking, preserved. */
+export function resultsToFacts(results: WebResult[], provider: string): Fact[] {
+  return results.map((r) =>
+    makeFact({
+      kind: "web_result",
+      subject: r.title,
+      source: `web search (${provider})`,
+      values: {
+        title: r.title,
+        url: r.url,
+        published: r.published ?? null,
+        snippet: r.snippet || null,
+        engine: r.engine ?? provider,
+      },
+    }),
+  );
+}
+
+/** One fetched page as a citable record. The prose goes to `pageEvidence`. */
+export function pageToFact(page: Extract<PageOutcome, { ok: true }>): Fact {
+  return makeFact({
+    kind: "web_page",
+    subject: page.title || page.url,
+    source: "page read",
+    values: {
+      title: page.title || null,
+      url: page.url,
+      retrieved: new Date().toISOString().slice(0, 10),
+      // Stated rather than implied: a model told the text is partial will say
+      // "the first part of the page" instead of summarising a page it half read.
+      truncated: page.truncated ? "yes — only the first part of the page was read" : "no",
+    },
+  });
+}
+
+/**
+ * The prose a claim may draw on, one block per source, each labelled with the
+ * fact id that licenses citing it.
+ *
+ * `facts` must be the ID-ASSIGNED array (post `assignFactIds`) and must line up
+ * positionally with `results`. Passing un-assigned facts produces blocks labelled
+ * `[]`, which is the bug this note exists to prevent.
+ */
+export function resultsEvidence(facts: Fact[], results: WebResult[]): string[] {
+  return results.map((r, i) => {
+    const id = facts[i]?.id ?? "";
+    const head = `${id ? `[${id}] ` : ""}${r.title} — ${r.url}`;
+    return r.snippet ? `${head}\n${r.snippet}` : head;
+  });
+}
+
+/** A fetched page's readable text as one evidence block, labelled with its id. */
+export function pageEvidence(fact: Fact, page: Extract<PageOutcome, { ok: true }>): string {
+  const head = `[${fact.id}] ${page.title || page.url} — ${page.url}`;
+  const tail = page.truncated ? "\n[…the rest of the page was not read]" : "";
+  return `${head}\n${page.text}${tail}`;
+}
+
+/**
+ * The sentence a model is shown when a lookup produced no usable answer.
+ *
+ * Written as an INSTRUCTION rather than a status code because that is what the
+ * model actually acts on, and because the two cases need opposite replies: a
+ * genuine "nothing out there" may be reported as a finding, while a backend
+ * outage may not be reported at all — the honest reply is that we could not
+ * look. Handing both to the model as `results: []` is how a broken API key
+ * becomes a confident statement about the state of the world.
+ */
+export function describeEmptySearch(outcome: WebSearchResult): string {
+  if (outcome.status === "nothing") {
+    return (
+      `The web search for "${outcome.query}" ran and returned no results. ` +
+      `You may tell the user nothing was found for that phrasing, and suggest a different one. ` +
+      `Do NOT present this as proof that the thing does not exist.`
+    );
+  }
+  const reasons = outcome.attempts
+    .map((a) => `${a.provider}: ${a.failure?.reason ?? a.outcome}`)
+    .join(" | ");
+  return (
+    `The web search for "${outcome.query}" COULD NOT BE PERFORMED (${reasons}). ` +
+    `Tell the user plainly that you could not search the web right now. ` +
+    `You must NOT say that nothing was found, that no such thing exists, or describe any web content — ` +
+    `you have not seen any.`
+  );
+}

package/src/web/index.ts

@@ -0,0 +1,70 @@
+/**
+ * ai-kit/web — the agent's eyes on the open web.
+ *
+ * Why this belongs in this package rather than in each app. Every AI product
+ * in the fleet is about to need the same four things, and each one is a
+ * distinct way to be wrong:
+ *
+ *   1. WHICH backend. Self-hosted metasearch, an independent index, an
+ *      agent-oriented API — with the same fallback-chain problem `chain.ts`
+ *      already solved for models, for the same reason: a single pinned
+ *      backend is a scheduled outage.
+ *   2. WHETHER it answered. "Found nothing" and "could not look" are different
+ *      answers, and an app that collapses them ships confident negatives it
+ *      never earned.
+ *   3. Fetching a page an AGENT chose, which is a genuinely different security
+ *      problem from fetching one a user typed — the model can be steered to a
+ *      URL by any page it reads, so the SSRF guard has to survive redirects and
+ *      DNS rebinding rather than checking a string once.
+ *   4. CITATIONS. Search without citation binding makes hallucination worse,
+ *      because now the invented sentence is surrounded by real ones.
+ *
+ * Four chances to get it wrong, times every app, is the duplication this
+ * package exists to end. The output type is deliberately `Fact` from
+ * `ai-kit/grounding` rather than a bespoke shape: retrieved web content and
+ * retrieved database rows then flow through ONE verifier, and "cite your
+ * sources" becomes a mechanical check instead of a line in a prompt.
+ *
+ * What it deliberately does not do: summarise, re-rank with an LLM, crawl,
+ * render JavaScript, or cache. The first two are the model's job and belong
+ * upstream where the app's own prompt lives; the last three are a different
+ * product with a different cost profile.
+ */
+export type {
+  WebResult,
+  WebFailure,
+  SearchOutcome,
+  PageOutcome,
+  SearchProvider,
+  SearchOptions,
+  ReadOptions,
+  WebEnv,
+} from "./types.js";
+
+export {
+  webSearch,
+  describeAttempts,
+  type WebSearchResult,
+  type SearchAttempt,
+  type WebSearchDeps,
+} from "./search.js";
+
+export { searxngProvider, braveProvider, tavilyProvider, defaultProviders } from "./providers.js";
+
+export { readPage, extractReadableText, type ReadDeps, type ExtractedPage } from "./read.js";
+
+export {
+  validateFetchTarget,
+  isPrivateAddress,
+  defaultLookup,
+  type LookupFn,
+  type UrlVerdict,
+} from "./ssrf.js";
+
+export {
+  resultsToFacts,
+  pageToFact,
+  resultsEvidence,
+  pageEvidence,
+  describeEmptySearch,
+} from "./facts.js";

package/src/web/providers.ts

@@ -0,0 +1,293 @@
+/**
+ * Search backends.
+ *
+ * Three, on purpose, and in this order of preference:
+ *
+ *   searxng — self-hosted, no API key, no per-call cost, no third party told
+ *             what your users are looking for. A metasearch front end over the
+ *             engines you enable. The catch is that it is scraping on your
+ *             behalf from your own IP, so a datacenter host will sometimes be
+ *             refused by upstream engines; that failure is loud here, which is
+ *             why the chain exists.
+ *   brave   — an independent index (not a Bing or Google reseller) with a free
+ *             tier, so the fallback is not the same index the primary was
+ *             already asking.
+ *   tavily  — built for agents: it returns cleaned content rather than SERP
+ *             chrome. Last resort because it is the most expensive per call.
+ *
+ * The seam is one method wide deliberately. Every provider here also sells
+ * "AI answers", news verticals and summarisation; adopting any of those would
+ * make the backends non-interchangeable, and an interchangeable backend is the
+ * entire reason to have a seam. Summarising is the model's job and it happens
+ * upstream of this file.
+ *
+ * None of them throws. A provider that cannot answer returns a typed failure,
+ * because the chain has to tell "no results" apart from "no answer" to pick
+ * its next move — and so does the model reading the result.
+ */
+import type { SearchOutcome, SearchProvider, WebEnv, WebFailure, WebResult } from "./types.js";
+
+const DEFAULT_LIMIT = 8;
+const DEFAULT_TIMEOUT_MS = 8_000;
+const MAX_LIMIT = 20;
+
+type Fetch = typeof globalThis.fetch;
+
+function clampLimit(limit: number | undefined): number {
+  if (!limit || !Number.isFinite(limit)) return DEFAULT_LIMIT;
+  return Math.max(1, Math.min(MAX_LIMIT, Math.floor(limit)));
+}
+
+/** `site:` is spelled the same by every engine here, so it is applied once. */
+function applySite(query: string, site: string | undefined): string {
+  const trimmed = site?.trim();
+  if (!trimmed) return query;
+  return `${query} site:${trimmed.replace(/^https?:\/\//, "").replace(/\/.*$/, "")}`;
+}
+
+function transportFailure(err: unknown): WebFailure {
+  const name = err instanceof Error ? err.name : "";
+  const message = err instanceof Error ? err.message : String(err);
+  if (name === "TimeoutError" || name === "AbortError") {
+    return { kind: "timeout", reason: "The search backend did not answer in time." };
+  }
+  return { kind: "unreachable", reason: `The search backend could not be reached (${message}).` };
+}
+
+/** HTTP status → failure kind. Shared because every provider gets this wrong the same way. */
+function statusFailure(status: number, provider: string): WebFailure {
+  if (status === 429) {
+    return { kind: "rate_limited", reason: `${provider} is rate-limiting this key right now.` };
+  }
+  if (status === 401 || status === 403) {
+    return { kind: "auth", reason: `${provider} rejected the credentials (${status}).` };
+  }
+  return { kind: "bad_response", reason: `${provider} answered ${status}.` };
+}
+
+function trimResult(raw: {
+  title?: unknown;
+  url?: unknown;
+  snippet?: unknown;
+  published?: unknown;
+  engine?: unknown;
+}): WebResult | null {
+  const url = typeof raw.url === "string" ? raw.url.trim() : "";
+  if (!url || !/^https?:\/\//i.test(url)) {
+    return null;
+  }
+  const title = typeof raw.title === "string" && raw.title.trim() ? raw.title.trim() : url;
+  const snippet = typeof raw.snippet === "string" ? raw.snippet.trim().slice(0, 600) : "";
+  const published =
+    typeof raw.published === "string" && raw.published.trim() ? raw.published.trim() : undefined;
+  const engine =
+    typeof raw.engine === "string" && raw.engine.trim() ? raw.engine.trim() : undefined;
+  return {
+    title: title.slice(0, 300),
+    url,
+    snippet,
+    ...(published ? { published } : {}),
+    ...(engine ? { engine } : {}),
+  };
+}
+
+// ── SearXNG ────────────────────────────────────────────────────────────────
+// Needs `formats: [html, json]` in the instance's settings.yml — a stock
+// instance serves HTML only and answers a JSON request with 403, which is
+// reported here as an auth failure so the operator sees the real fix rather
+// than "no results".
+
+export function searxngProvider(env: WebEnv, doFetch: Fetch = globalThis.fetch): SearchProvider {
+  const base = env.SEARXNG_URL?.trim().replace(/\/+$/, "");
+  return {
+    name: "searxng",
+    configured: () => Boolean(base),
+    async search(query, opts): Promise<SearchOutcome> {
+      if (!base) {
+        return {
+          ok: false,
+          provider: "searxng",
+          query,
+          failure: { kind: "not_configured", reason: "SEARXNG_URL is not set." },
+        };
+      }
+      const url = new URL(`${base}/search`);
+      url.searchParams.set("q", applySite(query, opts.site));
+      url.searchParams.set("format", "json");
+      url.searchParams.set("safesearch", "0");
+      if (opts.lang) {
+        url.searchParams.set("language", opts.lang);
+      }
+      try {
+        const res = await doFetch(url.toString(), {
+          headers: {
+            Accept: "application/json",
+            ...(env.SEARXNG_TOKEN ? { Authorization: `Bearer ${env.SEARXNG_TOKEN}` } : {}),
+          },
+          signal: AbortSignal.timeout(opts.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+        });
+        if (!res.ok) {
+          return {
+            ok: false,
+            provider: "searxng",
+            query,
+            failure: statusFailure(res.status, "SearXNG"),
+          };
+        }
+        const body = (await res.json()) as { results?: unknown };
+        const rows = Array.isArray(body.results) ? body.results : [];
+        const results = rows
+          .map((r) => {
+            const row = r as Record<string, unknown>;
+            return trimResult({
+              title: row.title,
+              url: row.url,
+              snippet: row.content,
+              published: row.publishedDate,
+              engine: row.engine,
+            });
+          })
+          .filter((r): r is WebResult => r !== null)
+          .slice(0, clampLimit(opts.limit));
+        return { ok: true, provider: "searxng", query, results };
+      } catch (err) {
+        return { ok: false, provider: "searxng", query, failure: transportFailure(err) };
+      }
+    },
+  };
+}
+
+// ── Brave ──────────────────────────────────────────────────────────────────
+
+export function braveProvider(env: WebEnv, doFetch: Fetch = globalThis.fetch): SearchProvider {
+  const key = env.BRAVE_SEARCH_API_KEY?.trim();
+  return {
+    name: "brave",
+    configured: () => Boolean(key),
+    async search(query, opts): Promise<SearchOutcome> {
+      if (!key) {
+        return {
+          ok: false,
+          provider: "brave",
+          query,
+          failure: { kind: "not_configured", reason: "BRAVE_SEARCH_API_KEY is not set." },
+        };
+      }
+      const url = new URL("https://api.search.brave.com/res/v1/web/search");
+      url.searchParams.set("q", applySite(query, opts.site));
+      url.searchParams.set("count", String(clampLimit(opts.limit)));
+      if (opts.lang) {
+        url.searchParams.set("search_lang", opts.lang.split("-")[0] ?? opts.lang);
+      }
+      try {
+        const res = await doFetch(url.toString(), {
+          headers: { Accept: "application/json", "X-Subscription-Token": key },
+          signal: AbortSignal.timeout(opts.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+        });
+        if (!res.ok) {
+          return {
+            ok: false,
+            provider: "brave",
+            query,
+            failure: statusFailure(res.status, "Brave Search"),
+          };
+        }
+        const body = (await res.json()) as { web?: { results?: unknown } };
+        const rows = Array.isArray(body.web?.results) ? body.web.results : [];
+        const results = rows
+          .map((r) => {
+            const row = r as Record<string, unknown>;
+            return trimResult({
+              title: row.title,
+              url: row.url,
+              snippet: row.description,
+              published: row.page_age,
+              engine: "brave",
+            });
+          })
+          .filter((r): r is WebResult => r !== null);
+        return { ok: true, provider: "brave", query, results };
+      } catch (err) {
+        return { ok: false, provider: "brave", query, failure: transportFailure(err) };
+      }
+    },
+  };
+}
+
+// ── Tavily ─────────────────────────────────────────────────────────────────
+
+export function tavilyProvider(env: WebEnv, doFetch: Fetch = globalThis.fetch): SearchProvider {
+  const key = env.TAVILY_API_KEY?.trim();
+  return {
+    name: "tavily",
+    configured: () => Boolean(key),
+    async search(query, opts): Promise<SearchOutcome> {
+      if (!key) {
+        return {
+          ok: false,
+          provider: "tavily",
+          query,
+          failure: { kind: "not_configured", reason: "TAVILY_API_KEY is not set." },
+        };
+      }
+      try {
+        const res = await doFetch("https://api.tavily.com/search", {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${key}`,
+          },
+          body: JSON.stringify({
+            query: applySite(query, opts.site),
+            max_results: clampLimit(opts.limit),
+            search_depth: "basic",
+          }),
+          signal: AbortSignal.timeout(opts.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+        });
+        if (!res.ok) {
+          return {
+            ok: false,
+            provider: "tavily",
+            query,
+            failure: statusFailure(res.status, "Tavily"),
+          };
+        }
+        const body = (await res.json()) as { results?: unknown };
+        const rows = Array.isArray(body.results) ? body.results : [];
+        const results = rows
+          .map((r) => {
+            const row = r as Record<string, unknown>;
+            return trimResult({
+              title: row.title,
+              url: row.url,
+              snippet: row.content,
+              published: row.published_date,
+              engine: "tavily",
+            });
+          })
+          .filter((r): r is WebResult => r !== null);
+        return { ok: true, provider: "tavily", query, results };
+      } catch (err) {
+        return { ok: false, provider: "tavily", query, failure: transportFailure(err) };
+      }
+    },
+  };
+}
+
+/**
+ * The default chain, in preference order, filtered to what the env configures.
+ *
+ * A caller that wants a different order passes its own array — this function
+ * exists so that the common case ("use whatever we have") is one call and not
+ * a policy decision re-made in every app, which is how the fleet ended up with
+ * one model-fallback implementation per repo.
+ */
+export function defaultProviders(env: WebEnv, doFetch: Fetch = globalThis.fetch): SearchProvider[] {
+  return [
+    searxngProvider(env, doFetch),
+    braveProvider(env, doFetch),
+    tavilyProvider(env, doFetch),
+  ].filter((p) => p.configured());
+}
+
+export { DEFAULT_LIMIT, DEFAULT_TIMEOUT_MS, MAX_LIMIT };