@bitbaum/ai-kit 0.15.0 → 0.16.0

package/src/web/read.ts

@@ -0,0 +1,284 @@
+/**
+ * readPage — fetch one web page and return its readable text.
+ *
+ * This is the other half of search. A result list gives an agent titles and a
+ * sentence of snippet; almost every real question needs the page. Without a
+ * reader the agent either answers from the snippet (which is how a plausible
+ * wrong number gets into a reply) or says it cannot know, and both are worse
+ * than reading.
+ *
+ * Three things it refuses to do, each because the alternative failed somewhere:
+ *
+ * - It never follows a redirect automatically. Every hop goes back through the
+ *   SSRF guard, because a public URL that 302s to localhost is the cheapest
+ *   bypass there is.
+ * - It never returns partial bytes as though they were the page. When the cap
+ *   is hit the result says `truncated: true`, so a model summarising it can say
+ *   "the first part of the page says…" instead of implying it read the whole.
+ * - It never throws. The caller is an agent loop; an unreadable page is a fact
+ *   about the world to reason about, not an exception to unwind through.
+ *
+ * Extraction is deliberately regex-based and dependency-free. A DOM parser
+ * would read more sites (SPAs especially) at the cost of making this package
+ * depend on one, and the failure it would fix — a JS-rendered page yielding
+ * nothing — is honestly reportable: empty text with `ok: true` tells the model
+ * the page had nothing readable, which is true and useful.
+ */
+import type { PageOutcome, ReadOptions, WebFailure } from "./types.js";
+import { validateFetchTarget, type LookupFn, defaultLookup } from "./ssrf.js";
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+const DEFAULT_MAX_CHARS = 12_000;
+const DEFAULT_MAX_BYTES = 2_000_000;
+const MAX_REDIRECTS = 3;
+
+/** Content types worth extracting text from. Anything else is refused unread. */
+const READABLE_TYPES = [
+  "text/html",
+  "application/xhtml",
+  "text/plain",
+  "text/markdown",
+  "application/json",
+  "application/xml",
+  "text/xml",
+];
+
+export type ReadDeps = {
+  fetch?: typeof globalThis.fetch;
+  lookup?: LookupFn;
+};
+
+export async function readPage(
+  rawUrl: string,
+  opts: ReadOptions = {},
+  deps: ReadDeps = {},
+): Promise<PageOutcome> {
+  const doFetch = deps.fetch ?? globalThis.fetch;
+  const lookup = deps.lookup ?? defaultLookup;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const maxChars = opts.maxChars ?? DEFAULT_MAX_CHARS;
+  const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
+
+  let target = rawUrl;
+
+  for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+    const verdict = await validateFetchTarget(target, lookup);
+    if (!verdict.ok) {
+      return { ok: false, url: target, failure: { kind: "blocked", reason: verdict.reason } };
+    }
+    const url = verdict.url.toString();
+
+    let res: Response;
+    try {
+      res = await doFetch(url, {
+        method: "GET",
+        redirect: "manual",
+        signal: AbortSignal.timeout(timeoutMs),
+        headers: {
+          // Identifying the agent is the polite half of scraping and the half
+          // that lets a site block us deliberately rather than by accident.
+          "User-Agent": "ai-kit/web (+https://github.com/bitbaum/ai-kit)",
+          Accept: "text/html,application/xhtml+xml,text/plain;q=0.9,*/*;q=0.5",
+          "Accept-Language": "en,de;q=0.8",
+        },
+      });
+    } catch (err) {
+      return { ok: false, url, failure: fetchFailure(err) };
+    }
+
+    if (res.status >= 300 && res.status < 400) {
+      const location = res.headers.get("location");
+      if (!location) {
+        return {
+          ok: false,
+          url,
+          failure: { kind: "bad_response", reason: `Redirect ${res.status} with no destination.` },
+        };
+      }
+      // Resolve relative Locations against the hop we are on, then loop — the
+      // next iteration re-runs the full SSRF check on the new address.
+      target = new URL(location, url).toString();
+      continue;
+    }
+
+    if (res.status === 429) {
+      return {
+        ok: false,
+        url,
+        failure: { kind: "rate_limited", reason: "The site asked us to slow down (429)." },
+      };
+    }
+    if (res.status === 401 || res.status === 403) {
+      return {
+        ok: false,
+        url,
+        failure: { kind: "blocked", reason: `The site refused the request (${res.status}).` },
+      };
+    }
+    if (!res.ok) {
+      return {
+        ok: false,
+        url,
+        failure: { kind: "bad_response", reason: `The site answered ${res.status}.` },
+      };
+    }
+
+    const contentType = (res.headers.get("content-type") ?? "").toLowerCase();
+    if (contentType && !READABLE_TYPES.some((t) => contentType.includes(t))) {
+      return {
+        ok: false,
+        url,
+        failure: {
+          kind: "bad_response",
+          reason: `That is a ${contentType.split(";")[0]} file, not a readable page.`,
+        },
+      };
+    }
+
+    let body: string;
+    try {
+      body = await readCapped(res, maxBytes);
+    } catch (err) {
+      return { ok: false, url, failure: fetchFailure(err) };
+    }
+
+    const extracted = extractReadableText(body, maxChars);
+    return {
+      ok: true,
+      url,
+      title: extracted.title,
+      text: extracted.text,
+      truncated: extracted.truncated,
+    };
+  }
+
+  return {
+    ok: false,
+    url: target,
+    failure: { kind: "blocked", reason: `More than ${MAX_REDIRECTS} redirects.` },
+  };
+}
+
+/**
+ * Read the body but stop at `maxBytes`. Buffering `res.text()` first and
+ * slicing after would already have paid for the whole download, which is the
+ * cost the cap exists to avoid — a 400 MB file would be in memory before the
+ * limit was consulted.
+ */
+async function readCapped(res: Response, maxBytes: number): Promise<string> {
+  const reader = res.body?.getReader();
+  if (!reader) {
+    const text = await res.text();
+    return text.length > maxBytes ? text.slice(0, maxBytes) : text;
+  }
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (value) {
+      chunks.push(value);
+      total += value.byteLength;
+      if (total >= maxBytes) {
+        await reader.cancel().catch(() => {});
+        break;
+      }
+    }
+  }
+  const joined = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    joined.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new TextDecoder("utf-8", { fatal: false }).decode(joined);
+}
+
+function fetchFailure(err: unknown): WebFailure {
+  const name = err instanceof Error ? err.name : "";
+  const message = err instanceof Error ? err.message : String(err);
+  if (name === "TimeoutError" || name === "AbortError" || /timed? ?out/i.test(message)) {
+    return { kind: "timeout", reason: "The site took too long to answer." };
+  }
+  return { kind: "unreachable", reason: `The site could not be reached (${message}).` };
+}
+
+const BLOCK_TAGS = "script|style|noscript|template|svg|canvas|iframe|form|nav|footer|header|aside";
+
+export type ExtractedPage = { title: string; text: string; truncated: boolean };
+
+/**
+ * Strip a document to the text a reader would see.
+ *
+ * Order matters and is load-bearing: comments go first (they can contain
+ * unbalanced tags that desync a later pass), then whole non-content elements
+ * WITH their contents, then remaining tags, then entities. Doing entities
+ * before tag-stripping would turn an encoded `&lt;script&gt;` in page text into
+ * a real tag mid-pass.
+ */
+export function extractReadableText(html: string, maxChars = DEFAULT_MAX_CHARS): ExtractedPage {
+  const titleMatch = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+  // Collapse whitespace: stripping an inline tag leaves a space behind, so a
+  // title with any markup in it ("A <b>bold</b> title") otherwise arrives with
+  // double spaces and fails to match the same string anywhere else.
+  const title = titleMatch?.[1]
+    ? decodeEntities(stripTags(titleMatch[1])).replace(/\s+/g, " ").trim().slice(0, 300)
+    : "";
+
+  let body = html.replace(/<!--[\s\S]*?-->/g, " ");
+  body = body.replace(new RegExp(`<(${BLOCK_TAGS})\\b[^>]*>[\\s\\S]*?<\\/\\1>`, "gi"), " ");
+  // An unclosed <script> would otherwise leave its whole tail in the text.
+  body = body.replace(new RegExp(`<(${BLOCK_TAGS})\\b[^>]*>[\\s\\S]*$`, "i"), " ");
+  // Keep block boundaries as newlines so lists and paragraphs do not run
+  // together into one sentence the model then reads as a single claim.
+  body = body.replace(/<\/(p|div|li|tr|h[1-6]|section|article|br)\s*>/gi, "\n");
+  body = body.replace(/<br\s*\/?>/gi, "\n");
+  body = stripTags(body);
+  body = decodeEntities(body);
+  body = body
+    .split("\n")
+    // \u00a0 is the non-breaking space `&nbsp;` decodes to. Written as an escape,
+    // not the literal character: a raw NBSP in source is invisible to a reviewer
+    // and to a diff, which is how one survives a cleanup that silently changes
+    // what the regex matches.
+    .map((line) => line.replace(/[ \t\u00a0]+/g, " ").trim())
+    .filter((line) => line.length > 0)
+    .join("\n")
+    .replace(/\n{3,}/g, "\n\n");
+
+  const truncated = body.length > maxChars;
+  return { title, text: truncated ? body.slice(0, maxChars) : body, truncated };
+}
+
+function stripTags(input: string): string {
+  return input.replace(/<[^>]*>/g, " ");
+}
+
+const ENTITIES: Record<string, string> = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  nbsp: " ",
+  ndash: "–",
+  mdash: "—",
+  hellip: "…",
+  rsquo: "’",
+  lsquo: "‘",
+  ldquo: "“",
+  rdquo: "”",
+};
+
+function decodeEntities(input: string): string {
+  return input.replace(/&(#x?[0-9a-f]+|[a-z]+);/gi, (whole, body: string) => {
+    if (body.startsWith("#")) {
+      const code =
+        body[1]?.toLowerCase() === "x" ? parseInt(body.slice(2), 16) : Number(body.slice(1));
+      return Number.isFinite(code) && code > 0 && code <= 0x10ffff
+        ? String.fromCodePoint(code)
+        : whole;
+    }
+    return ENTITIES[body.toLowerCase()] ?? whole;
+  });
+}

package/src/web/search.ts

@@ -0,0 +1,129 @@
+/**
+ * webSearch — walk the provider chain and come back with one of THREE answers.
+ *
+ * The three-answer shape is the whole point of this file, and it is the same
+ * lesson the model chain in `chain.ts` learned: a list nobody walks is not a
+ * fallback, and a walk that cannot say why it ended is not an answer.
+ *
+ *   found        — results, and which backend produced them.
+ *   nothing      — at least one backend ANSWERED and had nothing. This is a
+ *                  real negative the model may state as one.
+ *   could_not    — no backend answered at all (none configured, all rate-
+ *                  limited, all unreachable). The model must NOT report this
+ *                  as "there is nothing about X"; it must say it could not
+ *                  look, and the `attempts` list says why for each backend.
+ *
+ * Collapsing the last two into `[]` is the specific bug this prevents. It has
+ * a track record: an assistant whose search silently returned nothing told a
+ * user their question had no answer on the internet, and the actual cause was
+ * an expired API key. The user cannot fix a key they were never told about,
+ * and neither can the operator, because the failure looked like a fact.
+ *
+ * Walking past an EMPTY-but-successful backend is deliberate. A self-hosted
+ * metasearch instance whose upstream engines refused it returns `{results: []}`
+ * with HTTP 200 — a success that carries no information — so the chain tries
+ * the next backend before concluding, and only reports `nothing` when every
+ * backend that answered agreed there was nothing.
+ */
+import type { SearchOptions, SearchProvider, WebEnv, WebFailure, WebResult } from "./types.js";
+import { defaultProviders } from "./providers.js";
+
+/** What one backend did, kept for the report even when a later one succeeded. */
+export type SearchAttempt = {
+  provider: string;
+  outcome: "results" | "empty" | "failed";
+  count?: number;
+  failure?: WebFailure;
+};
+
+export type WebSearchResult =
+  | {
+      status: "found";
+      results: WebResult[];
+      provider: string;
+      query: string;
+      attempts: SearchAttempt[];
+    }
+  | { status: "nothing"; query: string; attempts: SearchAttempt[] }
+  | { status: "could_not_look"; query: string; attempts: SearchAttempt[] };
+
+export type WebSearchDeps = {
+  env?: WebEnv;
+  providers?: SearchProvider[];
+  fetch?: typeof globalThis.fetch;
+};
+
+export async function webSearch(
+  query: string,
+  opts: SearchOptions = {},
+  deps: WebSearchDeps = {},
+): Promise<WebSearchResult> {
+  const trimmed = query.trim();
+  const attempts: SearchAttempt[] = [];
+
+  if (!trimmed) {
+    return { status: "could_not_look", query, attempts };
+  }
+
+  const env = deps.env ?? (process.env as WebEnv);
+  const providers = deps.providers ?? defaultProviders(env, deps.fetch ?? globalThis.fetch);
+
+  if (providers.length === 0) {
+    return {
+      status: "could_not_look",
+      query: trimmed,
+      attempts: [
+        {
+          provider: "none",
+          outcome: "failed",
+          failure: {
+            kind: "not_configured",
+            reason:
+              "No search backend is configured (set SEARXNG_URL, BRAVE_SEARCH_API_KEY or TAVILY_API_KEY).",
+          },
+        },
+      ],
+    };
+  }
+
+  let anyBackendAnswered = false;
+
+  for (const provider of providers) {
+    const outcome = await provider.search(trimmed, opts);
+    if (!outcome.ok) {
+      attempts.push({ provider: provider.name, outcome: "failed", failure: outcome.failure });
+      continue;
+    }
+    anyBackendAnswered = true;
+    if (outcome.results.length === 0) {
+      attempts.push({ provider: provider.name, outcome: "empty", count: 0 });
+      continue;
+    }
+    attempts.push({ provider: provider.name, outcome: "results", count: outcome.results.length });
+    return {
+      status: "found",
+      results: outcome.results,
+      provider: provider.name,
+      query: trimmed,
+      attempts,
+    };
+  }
+
+  return anyBackendAnswered
+    ? { status: "nothing", query: trimmed, attempts }
+    : { status: "could_not_look", query: trimmed, attempts };
+}
+
+/**
+ * One line per backend, for a log or a health route: "searxng empty; brave 6".
+ * Kept here rather than at call sites so every adopter's logs read the same.
+ */
+export function describeAttempts(attempts: SearchAttempt[]): string {
+  return attempts
+    .map((a) => {
+      if (a.outcome === "results") return `${a.provider} ${a.count}`;
+      if (a.outcome === "empty") return `${a.provider} empty`;
+      return `${a.provider} ${a.failure?.kind ?? "failed"}`;
+    })
+    .join("; ");
+}

package/src/web/ssrf.ts

@@ -0,0 +1,175 @@
+/**
+ * SSRF guard for agent-chosen URLs.
+ *
+ * Why this is stricter than the usual "block 127.0.0.1" check. An app that
+ * fetches a URL the USER pasted has a human in the loop who can be blamed for
+ * typing it. An agent that fetches a URL it reasoned its way to from a search
+ * result has no such human: the model picks the address, and any page on the
+ * open web can hand it a link to `http://169.254.169.254/latest/meta-data/`
+ * and read the answer back out of the model's next sentence. On a box that
+ * also runs Postgres, Supabase, Caddy and eight app servers on localhost, the
+ * blast radius of one missed range is the whole fleet.
+ *
+ * So the rule here is allow-list-shaped rather than deny-list-shaped wherever
+ * it can be: http(s) only, ports 80/443 only, no credentials, and — the part
+ * that actually matters — EVERY address the hostname resolves to must be
+ * public, checked again on every redirect hop rather than once at the start.
+ *
+ * The classic bypass this closes: a hostname that resolves to a public address
+ * on the first lookup and a private one on the second (DNS rebinding), or a
+ * public URL that 302s to `http://localhost:5432`. Validating the first URL
+ * and then handing the rest to `fetch`'s automatic redirect following defeats
+ * the whole check, which is why the reader does `redirect: "manual"` and comes
+ * back through here for each hop.
+ *
+ * Pure except for DNS. No allow-list of "good" domains: a fleet whose thesis is
+ * that anyone may publish anywhere cannot ship an agent that can only read the
+ * sites we thought of.
+ */
+import { lookup as dnsLookup } from "node:dns/promises";
+import { isIP } from "node:net";
+
+/** Injectable so tests need no network and no hosts-file tricks. */
+export type LookupFn = (hostname: string) => Promise<Array<{ address: string }>>;
+
+export const defaultLookup: LookupFn = async (hostname) => {
+  const entries = await dnsLookup(hostname, { all: true, verbatim: true });
+  return entries.map((e) => ({ address: e.address }));
+};
+
+export type UrlVerdict =
+  { ok: true; url: URL; addresses: string[] } | { ok: false; reason: string };
+
+const ALLOWED_PROTOCOLS = new Set(["http:", "https:"]);
+const ALLOWED_PORTS = new Set(["", "80", "443"]);
+
+/**
+ * Is this a literal address we must never connect to?
+ *
+ * Each range is here because it addresses something that is not "the public
+ * internet" — loopback, the link-local metadata service, RFC1918, carrier NAT,
+ * benchmark and documentation nets, multicast and the reserved top of the
+ * space. A response from any of them is a response from inside the trust
+ * boundary, whatever the hostname said.
+ */
+export function isPrivateAddress(address: string): boolean {
+  const family = isIP(address);
+  if (family === 4) {
+    return isPrivateIpv4(address);
+  }
+  if (family === 6) {
+    return isPrivateIpv6(address);
+  }
+  // Not a parseable address at all. Refusing is the only safe reading: we
+  // cannot prove it is public, and "unknown" must never mean "allowed".
+  return true;
+}
+
+function isPrivateIpv4(address: string): boolean {
+  const parts = address.split(".").map((p) => Number(p));
+  if (parts.length !== 4 || parts.some((p) => !Number.isInteger(p) || p < 0 || p > 255)) {
+    return true;
+  }
+  const [a, b] = parts as [number, number, number, number];
+  if (a === 0) return true; // "this network"
+  if (a === 10) return true; // RFC1918
+  if (a === 127) return true; // loopback
+  if (a === 169 && b === 254) return true; // link-local — cloud metadata lives here
+  if (a === 172 && b >= 16 && b <= 31) return true; // RFC1918
+  if (a === 192 && b === 168) return true; // RFC1918
+  if (a === 192 && b === 0) return true; // IETF protocol assignments (incl. 192.0.0.0/24)
+  if (a === 198 && (b === 18 || b === 19)) return true; // benchmarking
+  if (a === 198 && b === 51) return true; // TEST-NET-2
+  if (a === 203 && b === 0) return true; // TEST-NET-3
+  if (a === 100 && b >= 64 && b <= 127) return true; // carrier-grade NAT
+  if (a >= 224) return true; // multicast + reserved
+  return false;
+}
+
+function isPrivateIpv6(address: string): boolean {
+  const lower = address.toLowerCase().split("%")[0] ?? "";
+
+  // IPv4-mapped (::ffff:10.0.0.1) and IPv4-compatible forms are IPv4 questions
+  // wearing an IPv6 spelling. Judge the embedded address, not the wrapper.
+  const mapped = lower.match(/^::(?:ffff:)?(\d+\.\d+\.\d+\.\d+)$/);
+  if (mapped?.[1]) {
+    return isPrivateIpv4(mapped[1]);
+  }
+
+  if (lower === "::" || lower === "::1") return true; // unspecified, loopback
+  if (lower.startsWith("fe8") || lower.startsWith("fe9")) return true; // link-local
+  if (lower.startsWith("fea") || lower.startsWith("feb")) return true; // link-local
+  if (/^f[cd]/.test(lower)) return true; // unique local (fc00::/7)
+  if (lower.startsWith("ff")) return true; // multicast
+
+  // 6to4 (2002::/16) and NAT64 (64:ff9b::/96) carry an IPv4 address inside.
+  // Left unchecked they are a clean tunnel to 127.0.0.1.
+  if (lower.startsWith("2002:")) return true;
+  if (lower.startsWith("64:ff9b:")) return true;
+
+  return false;
+}
+
+/**
+ * Validate a URL for agent fetching: shape first (cheap, no network), then
+ * resolve and judge every address behind the hostname.
+ *
+ * Returns the resolved addresses on success so the caller can log what it
+ * actually talked to — a hostname proves nothing about where the bytes came
+ * from, and the address is the thing an incident review needs.
+ */
+export async function validateFetchTarget(
+  raw: string,
+  lookup: LookupFn = defaultLookup,
+): Promise<UrlVerdict> {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    return { ok: false, reason: "That is not a valid URL." };
+  }
+
+  if (!ALLOWED_PROTOCOLS.has(url.protocol)) {
+    return { ok: false, reason: `Only http and https can be fetched, not ${url.protocol}` };
+  }
+  if (!ALLOWED_PORTS.has(url.port)) {
+    return { ok: false, reason: `Only the standard web ports are allowed, not ${url.port}.` };
+  }
+  if (url.username || url.password) {
+    return { ok: false, reason: "A URL carrying credentials is never fetched." };
+  }
+
+  const hostname = url.hostname.replace(/^\[|\]$/g, "");
+  if (!hostname) {
+    return { ok: false, reason: "That URL has no host." };
+  }
+
+  // A literal address needs no lookup — and must not get one, since a resolver
+  // asked about "127.0.0.1" will happily hand it back and the check would then
+  // be judging its own input.
+  if (isIP(hostname)) {
+    if (isPrivateAddress(hostname)) {
+      return { ok: false, reason: "That address is not on the public internet." };
+    }
+    return { ok: true, url, addresses: [hostname] };
+  }
+
+  let addresses: string[];
+  try {
+    const entries = await lookup(hostname);
+    addresses = entries.map((e) => e.address);
+  } catch {
+    return { ok: false, reason: `The host ${hostname} could not be resolved.` };
+  }
+
+  if (addresses.length === 0) {
+    return { ok: false, reason: `The host ${hostname} resolved to no addresses.` };
+  }
+  // EVERY address, not the first: a hostname with one public and one private A
+  // record is a rebinding attack with the work already done for it.
+  if (addresses.some((a) => isPrivateAddress(a))) {
+    return { ok: false, reason: `The host ${hostname} resolves inside a private network.` };
+  }
+
+  return { ok: true, url, addresses };
+}

package/src/web/types.ts

@@ -0,0 +1,89 @@
+/**
+ * Web module types — the three answers a lookup can give.
+ *
+ * The distinction this file exists to preserve: "I found nothing" and "I could
+ * not look" are DIFFERENT answers, and collapsing them is how an agent comes to
+ * report a confident negative it never earned. A search whose provider was
+ * rate-limited returns zero results, exactly like a search for a phrase nobody
+ * has ever written; if both arrive as `[]`, the model says "there is nothing
+ * about X on the web" in both cases, and one of those sentences is a lie.
+ *
+ * So every outcome here is a tagged union with `ok`, and the failure branch
+ * carries a `reason` the model is shown verbatim. Nothing in this module
+ * throws — a lookup failing is an ordinary result, not an exception, because
+ * the caller is an agent loop that must keep going either way.
+ */
+
+/** One result from a search engine. Snippets are the engine's, never rewritten. */
+export type WebResult = {
+  title: string;
+  url: string;
+  /** The engine's own summary of the page. May be empty. */
+  snippet: string;
+  /** ISO date when the engine reports one. Absent is normal, not an error. */
+  published?: string;
+  /** Which upstream engine surfaced it, where the provider tells us. */
+  engine?: string;
+};
+
+/** Why a lookup could not be performed. Shown to the model, so phrase for reading. */
+export type WebFailure =
+  | { kind: "not_configured"; reason: string }
+  | { kind: "rate_limited"; reason: string }
+  | { kind: "auth"; reason: string }
+  | { kind: "timeout"; reason: string }
+  | { kind: "blocked"; reason: string }
+  | { kind: "unreachable"; reason: string }
+  | { kind: "bad_response"; reason: string };
+
+export type SearchOutcome =
+  | { ok: true; results: WebResult[]; provider: string; query: string }
+  | { ok: false; failure: WebFailure; provider: string; query: string };
+
+export type PageOutcome =
+  | {
+      ok: true;
+      url: string;
+      title: string;
+      /** Readable text, tags stripped, whitespace collapsed. */
+      text: string;
+      /** True when `text` hit the character cap and the tail was dropped. */
+      truncated: boolean;
+    }
+  | { ok: false; url: string; failure: WebFailure };
+
+/**
+ * A search backend. Deliberately one method: everything else a provider might
+ * offer (news verticals, autocomplete, "AI answers") is a different product
+ * decision and belongs to the caller, not to a seam whose whole job is to make
+ * the backends interchangeable.
+ */
+export type SearchProvider = {
+  /** Stable id used in logs, Fact sources and the chain's report: "searxng". */
+  readonly name: string;
+  /** False when the env it needs is absent — the chain skips it without a call. */
+  configured(): boolean;
+  search(query: string, opts: SearchOptions): Promise<SearchOutcome>;
+};
+
+export type SearchOptions = {
+  /** Upper bound on results. Providers may return fewer; none may return more. */
+  limit?: number;
+  /** Per-provider deadline in milliseconds. */
+  timeoutMs?: number;
+  /** Restrict to one site, e.g. "docs.python.org". Applied as the engine allows. */
+  site?: string;
+  /** Language hint, BCP-47-ish ("en", "de-CH"). Best-effort per provider. */
+  lang?: string;
+};
+
+export type ReadOptions = {
+  timeoutMs?: number;
+  /** Character cap on extracted text. */
+  maxChars?: number;
+  /** Bytes to read off the wire before giving up on an oversized document. */
+  maxBytes?: number;
+};
+
+/** Env bag. Defaults to `process.env`; injectable so tests need no globals. */
+export type WebEnv = Record<string, string | undefined>;