@arnilo/prism-tools 0.0.0-stage → 0.13.1

package/web/src/cache.ts

@@ -0,0 +1,151 @@
+/**
+ * One page cache for every fetch backend: session-scoped, bounded, and in process memory only.
+ *
+ * `web_fetch` returns a page in slices, so a second call for the same URL in one session must not
+ * pay for a second fetch. With `cache` config the page is kept for `ttlSeconds` and marked
+ * `cached`; without it Prism keeps the plan 192 paging memo (10 minutes, 8 pages, no annotations)
+ * through the same implementation, so there is one cache, not two. Nothing is persisted: the
+ * entries live in `prism.state.agent`, which resets at package dispose, and the `session.closed`
+ * hook drops a session's entries so one tenant's page never answers another session.
+ */
+import type { ToolsWebCacheConfig } from "./config.js";
+import { WebToolError } from "./transport.js";
+import type { FetchCache, WebDocument, WebFetchOptions } from "./types.js";
+
+/** `cache.maxEntries` default. */
+export const DEFAULT_CACHE_MAX_ENTRIES = 64;
+/** `cache.maxBytes` default: 16 MiB of Markdown per agent process. */
+export const DEFAULT_CACHE_MAX_BYTES = 16 * 1024 * 1024;
+/** Hard bounds, so a config cannot turn the cache into unbounded memory. */
+export const HARD_CACHE_TTL_SECONDS = 86_400;
+export const HARD_CACHE_MAX_ENTRIES = 4_096;
+export const HARD_CACHE_MAX_BYTES = 64 * 1024 * 1024;
+/** The anonymous paging memo kept when no `cache` is configured (plan 192's values). */
+export const MEMO_TTL_SECONDS = 600;
+export const MEMO_MAX_ENTRIES = 8;
+
+export interface ResolvedFetchCache {
+  readonly ttlMs: number;
+  readonly maxEntries: number;
+  readonly maxBytes: number;
+  /** `false` for the implicit memo: no `cached` flag, no `refresh` argument. */
+  readonly annotated: boolean;
+}
+
+interface CacheEntry {
+  readonly document: WebDocument;
+  readonly at: number;
+  readonly bytes: number;
+}
+
+/** Validates `cache`; without it the memo defaults apply, unannotated. */
+export function resolveFetchCache(config: ToolsWebCacheConfig | undefined): ResolvedFetchCache {
+  if (config === undefined)
+    return {
+      ttlMs: MEMO_TTL_SECONDS * 1_000,
+      maxEntries: MEMO_MAX_ENTRIES,
+      maxBytes: HARD_CACHE_MAX_BYTES,
+      annotated: false,
+    };
+  const ttl = config.ttlSeconds;
+  if (!Number.isSafeInteger(ttl) || ttl < 1 || ttl > HARD_CACHE_TTL_SECONDS)
+    throw new WebToolError("ERR_PRISM_WEB_INPUT", `cache.ttlSeconds must be an integer between 1 and ${HARD_CACHE_TTL_SECONDS}`);
+  const maxEntries = config.maxEntries ?? DEFAULT_CACHE_MAX_ENTRIES;
+  if (!Number.isSafeInteger(maxEntries) || maxEntries < 1 || maxEntries > HARD_CACHE_MAX_ENTRIES)
+    throw new WebToolError("ERR_PRISM_WEB_INPUT", `cache.maxEntries must be an integer between 1 and ${HARD_CACHE_MAX_ENTRIES}`);
+  const maxBytes = config.maxBytes ?? DEFAULT_CACHE_MAX_BYTES;
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > HARD_CACHE_MAX_BYTES)
+    throw new WebToolError("ERR_PRISM_WEB_INPUT", `cache.maxBytes must be an integer between 1 and ${HARD_CACHE_MAX_BYTES}`);
+  return { ttlMs: ttl * 1_000, maxEntries, maxBytes, annotated: true };
+}
+
+/**
+ * The cache itself: one LRU map keyed by session and URL, bounded by count and Markdown bytes.
+ * Insertion order is recency, so eviction is "delete the first key".
+ */
+export function createFetchCache(config: ResolvedFetchCache, now: () => number = Date.now): FetchCache {
+  const entries = new Map<string, CacheEntry>();
+  const key = (sessionId: string | undefined, url: string) => (sessionId === undefined ? undefined : `${sessionId}\u0000${url}`);
+  let bytes = 0;
+  const remove = (id: string): void => {
+    const entry = entries.get(id);
+    if (entry === undefined) return;
+    entries.delete(id);
+    bytes -= entry.bytes;
+  };
+  return {
+    annotated: config.annotated,
+    read(sessionId, url, at = now()) {
+      const id = key(sessionId, url);
+      if (id === undefined) return undefined;
+      const entry = entries.get(id);
+      if (entry === undefined) return undefined;
+      if (at - entry.at > config.ttlMs) {
+        remove(id);
+        return undefined;
+      }
+      // Touch: delete and re-insert so this page is the newest entry.
+      entries.delete(id);
+      entries.set(id, entry);
+      return { document: entry.document, ageMs: Math.max(0, at - entry.at) };
+    },
+    write(sessionId, url, document) {
+      const id = key(sessionId, url);
+      if (id === undefined) return;
+      const size = Buffer.byteLength(document.markdown, "utf8");
+      remove(id);
+      // A page larger than the whole budget is fetched again rather than evicting everything else.
+      if (size > config.maxBytes) return;
+      entries.set(id, { document, at: now(), bytes: size });
+      bytes += size;
+      for (const oldest of entries.keys()) {
+        if (entries.size <= config.maxEntries && bytes <= config.maxBytes) break;
+        remove(oldest);
+      }
+    },
+    dropSession(sessionId) {
+      const prefix = `${sessionId}\u0000`;
+      for (const id of [...entries.keys()]) if (id.startsWith(prefix)) remove(id);
+    },
+  };
+}
+
+/** The cache stores the canonical URL, never the requested one, so trailing `#fragment` is one page. */
+export function tryCanonicalUrl(url: string): string | undefined {
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") return undefined;
+    if (parsed.username || parsed.password) return undefined;
+    parsed.hash = "";
+    return parsed.toString();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Decorator over anything with a `fetch`: a hit makes no request. The adapter sees the original
+ * URL (so redirects and citations are unchanged); the cache is keyed by its canonical form.
+ */
+export function withFetchCache<T extends { fetch(url: string, options?: WebFetchOptions): Promise<WebDocument> }>(
+  target: T,
+  cache: FetchCache,
+): T {
+  return {
+    ...target,
+    async fetch(url: string, options?: WebFetchOptions): Promise<WebDocument> {
+      const sessionId = options?.sessionId;
+      const canonical = sessionId === undefined ? undefined : tryCanonicalUrl(url);
+      if (sessionId === undefined || canonical === undefined) return target.fetch(url, options);
+      if (options?.refresh !== true) {
+        const hit = cache.read(sessionId, canonical);
+        if (hit !== undefined) {
+          return cache.annotated ? { ...hit.document, cached: true, cachedAgeMs: hit.ageMs } : hit.document;
+        }
+      }
+      const document = await target.fetch(url, options);
+      cache.write(sessionId, canonical, document);
+      return document;
+    },
+  };
+}

package/web/src/config.ts

@@ -0,0 +1,210 @@
+import type { JsonObject, JsonSchema, ModelRef } from "@arnilo/prism";
+
+import type { ToolsWebDomainsConfig } from "./domains.js";
+
+import type { ObscuraWebLimits } from "./obscura/limits.js";
+import type { WebLimits } from "./types.js";
+
+/** The search/fetch backend the package operates as. `native` is fetch-only and needs no key. */
+export type ToolsWebBackend = "brave" | "exa" | "firecrawl" | "native" | "obscura" | "searxng" | "tavily" | "kagi";
+
+/** The optional second backend used for `web_fetch` when the search backend cannot fetch. */
+export interface ToolsWebFetchConfig {
+  /** `"native"` (default, keyless), `"firecrawl"`, or `"off"` to register no fetch tool. */
+  readonly backend?: "native" | "firecrawl" | "off";
+  /** `env:NAME` or `keyring:NAME`; a literal fails config validation. Required when `backend` is `"firecrawl"`. */
+  readonly apiKey?: string;
+  /** Replaces the native backend's `user-agent`; it still identifies Prism unless a host opts out. */
+  readonly userAgent?: string;
+  /** Adds the `prompt` argument: one model call answers a question from the fetched page. */
+  readonly prompt?: ToolsWebPromptConfig;
+}
+
+/** Opt-in `web_fetch` question answering: the host picks the model, the model only asks the question. */
+export interface ToolsWebPromptConfig {
+  /** The model that reads the page; resolved once at setup. */
+  readonly model: ModelRef;
+  /** Characters of page Markdown sent to it. Default 100 000. */
+  readonly maxInputChars?: number;
+  /** Output token budget for the answer. Default 1 024. */
+  readonly maxOutputTokens?: number;
+}
+
+/** Obscura backend settings. `obscura` needs no key. */
+export interface ToolsWebObscuraConfig {
+  /** Absolute path or a bare name resolved on `PATH`. Default `"obscura"`. */
+  readonly binary?: string;
+  /** Register the native `obscura_fetch`/`obscura_scrape` tools. Default `true`. */
+  readonly nativeTools?: boolean;
+  /** Bounds for the CLI-backed search/fetch/scrape children; out-of-range values fail setup. */
+  readonly limits?: Partial<ObscuraWebLimits>;
+}
+
+/** A self-hosted SearXNG instance: no key, no vendor, but an exact origin the host names. */
+export interface ToolsWebSearxngConfig {
+  /** Exact origin, e.g. `https://search.example.org`; `http://` only for a loopback hostname. */
+  readonly origin: string;
+  /** Accept a plaintext origin when its hostname is loopback. Default `false`. */
+  readonly allowLoopback?: boolean;
+}
+
+export type { ToolsWebDomainsConfig } from "./domains.js";
+
+/** Per-session page cache. Off unless configured; `ttlSeconds` is required when the object is present. */
+export interface ToolsWebCacheConfig {
+  /** How long a page stays fresh, 1–86 400 seconds. */
+  readonly ttlSeconds: number;
+  /** Maximum pages kept across sessions. Default 64. */
+  readonly maxEntries?: number;
+  /** Maximum Markdown bytes kept across sessions. Default 16 MiB. */
+  readonly maxBytes?: number;
+}
+
+/** Schema that `web_extract` asks the extract backend to fill; validated at setup, not first use. */
+export interface ToolsWebExtractConfig {
+  readonly schema: JsonObject;
+}
+
+/** Validated `packageConfig` for `@arnilo/prism-tools/web`. */
+export interface ToolsWebConfig {
+  /** Required; checked in `setup` with a naming error. */
+  readonly backend: ToolsWebBackend;
+  /** `env:NAME` or `keyring:NAME`; a literal fails config validation. Required for `brave`, `exa`, and `firecrawl`; `native` and `obscura` need none. */
+  readonly apiKey?: string;
+  /** Optional second backend for `web_fetch` when `backend` is `brave` or `exa`. */
+  readonly fetch?: ToolsWebFetchConfig;
+  /** Obscura binary settings; only read when `backend` is `"obscura"`. */
+  readonly obscura?: ToolsWebObscuraConfig;
+  /** SearXNG instance settings; only read when `backend` is `"searxng"`. */
+  readonly searxng?: ToolsWebSearxngConfig;
+  /** Register `web_extract` over this schema (needs a Firecrawl key: `apiKey`, or `fetch.apiKey`). */
+  readonly extract?: ToolsWebExtractConfig;
+  /** Host-owned allow/block lists enforced on every search result and fetch target. */
+  readonly domains?: ToolsWebDomainsConfig;
+  /** Per-session page cache for `web_fetch` and `web.fetch`; absent means the short paging memo. */
+  readonly cache?: ToolsWebCacheConfig;
+  /** Byte, retry, concurrency, and timeout bounds for the HTTP adapters. */
+  readonly limits?: WebLimits;
+}
+
+const limitProperties: Readonly<Record<string, JsonSchema>> = {
+  maxQueryBytes: { type: "number", minimum: 1 },
+  maxResults: { type: "number", minimum: 1 },
+  maxUrls: { type: "number", minimum: 1 },
+  maxRequestBytes: { type: "number", minimum: 1 },
+  maxResponseBytes: { type: "number", minimum: 1 },
+  maxMarkdownBytes: { type: "number", minimum: 1 },
+  maxExtractBytes: { type: "number", minimum: 1 },
+  maxSchemaBytes: { type: "number", minimum: 1 },
+  maxAggregateBytes: { type: "number", minimum: 1 },
+  maxJsonDepth: { type: "number", minimum: 1 },
+  maxJsonProperties: { type: "number", minimum: 1 },
+  maxRetries: { type: "number", minimum: 0 },
+  maxRateLimitDelayMs: { type: "number", minimum: 1 },
+  maxConcurrency: { type: "number", minimum: 1 },
+  maxQueued: { type: "number", minimum: 1 },
+  maxPollingAttempts: { type: "number", minimum: 1 },
+  pollingDelayMs: { type: "number", minimum: 0 },
+  timeoutMs: { type: "number", minimum: 1 },
+};
+
+const obscuraLimitProperties: Readonly<Record<string, JsonSchema>> = {
+  maxQueryBytes: { type: "number", minimum: 1 },
+  maxResults: { type: "number", minimum: 1 },
+  maxUrls: { type: "number", minimum: 1 },
+  maxConcurrency: { type: "number", minimum: 1 },
+  maxOutputBytes: { type: "number", minimum: 1 },
+  maxStderrBytes: { type: "number", minimum: 1 },
+  timeoutMs: { type: "number", minimum: 1 },
+  maxEvalBytes: { type: "number", minimum: 1 },
+};
+
+const domainList: JsonSchema = {
+  type: "array",
+  items: { type: "string", minLength: 1, maxLength: 253 },
+  maxItems: 256,
+};
+
+const secretString: JsonSchema = {
+  type: "string",
+  minLength: 1,
+  maxLength: 4096,
+  pattern: "^(env|keyring):",
+  "x-prism-secret": true,
+};
+
+/**
+ * The config schema. `backend` is deliberately not declared `required`: a required field with no
+ * default would fail package conformance, so `setup` checks it and names the field instead.
+ * `apiKey` (and `fetch.apiKey`) are ref-only secret fields; a literal fails validation.
+ */
+export const toolsWebConfigSchema: JsonSchema = {
+  type: "object",
+  properties: {
+    backend: { type: "string", enum: ["brave", "exa", "firecrawl", "native", "obscura", "searxng", "tavily", "kagi"] },
+    apiKey: secretString,
+    fetch: {
+      type: "object",
+      properties: {
+        backend: { type: "string", enum: ["native", "firecrawl", "off"], default: "native" },
+        apiKey: secretString,
+        userAgent: { type: "string", minLength: 1, maxLength: 512 },
+        prompt: {
+          type: "object",
+          properties: {
+            model: {
+              anyOf: [
+                { type: "string" },
+                {
+                  type: "object",
+                  properties: { provider: { type: "string" }, model: { type: "string" } },
+                  required: ["provider", "model"],
+                },
+              ],
+            },
+            // No `default`: a nested default would materialize `fetch.prompt` and fail its required model.
+            maxInputChars: { type: "integer", minimum: 1, maximum: 1_000_000 },
+            maxOutputTokens: { type: "integer", minimum: 1, maximum: 32_768 },
+          },
+          required: ["model"],
+        },
+      },
+    },
+    obscura: {
+      type: "object",
+      properties: {
+        binary: { type: "string", minLength: 1, maxLength: 4096 },
+        nativeTools: { type: "boolean", default: true },
+        limits: { type: "object", properties: obscuraLimitProperties },
+      },
+    },
+    searxng: {
+      type: "object",
+      properties: {
+        origin: { type: "string", minLength: 1, maxLength: 4096 },
+        allowLoopback: { type: "boolean" },
+      },
+      required: ["origin"],
+    },
+    domains: {
+      type: "object",
+      properties: { allow: domainList, block: domainList },
+    },
+    cache: {
+      type: "object",
+      properties: {
+        ttlSeconds: { type: "integer", minimum: 1, maximum: 86_400 },
+        maxEntries: { type: "integer", minimum: 1, maximum: 4_096 },
+        maxBytes: { type: "integer", minimum: 1, maximum: 67_108_864 },
+      },
+      required: ["ttlSeconds"],
+    },
+    extract: {
+      type: "object",
+      // Free-form JSON Schema: the kernel subset is checked in setup, naming `extract.schema`.
+      properties: { schema: { type: "object", additionalProperties: true } },
+      required: ["schema"],
+    },
+    limits: { type: "object", properties: limitProperties },
+  },
+};

package/web/src/controls.ts

@@ -0,0 +1,128 @@
+import type { JsonObject } from "@arnilo/prism";
+import { WebToolError } from "./transport.js";
+import type { SearchControl, SearchControls, SearchFreshness, WebSearchControlValues } from "./types.js";
+
+/** A search accepts at most this many domains on each side. */
+export const MAX_DOMAIN_CONTROLS = 10;
+export const SEARCH_FRESHNESS: readonly SearchFreshness[] = ["day", "week", "month", "year"];
+
+/** The argument name a model sees, so an error names exactly what it asked for. */
+const ARGUMENT: Record<SearchControl, string> = {
+  freshness: "freshness",
+  includeDomains: "include_domains",
+  excludeDomains: "exclude_domains",
+  country: "country",
+  language: "language",
+  offset: "offset",
+};
+
+/** A bare hostname: no scheme, path, port, wildcard, space, or operator syntax. */
+const HOSTNAME = /^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/iu;
+const CODE_2 = /^[a-z]{2}$/iu;
+
+/**
+ * Validates the controls a call asked for against one backend's support matrix. A control the
+ * backend cannot honor fails loudly, naming the argument — silently ignoring it would make results
+ * look filtered when they are not.
+ */
+export function searchControls(supports: ReadonlySet<SearchControl>, input: object, values: WebSearchControlValues = {}): SearchControls {
+  const provided = input as Record<string, unknown>;
+  const controls: { -readonly [K in keyof SearchControls]: SearchControls[K] } = {};
+  for (const control of Object.keys(ARGUMENT) as SearchControl[]) {
+    const value = provided[control];
+    if (value === undefined) continue;
+    const argument = ARGUMENT[control];
+    if (!supports.has(control)) throw invalid(`${argument} is not supported by this search backend`);
+    switch (control) {
+      case "freshness": {
+        // A backend may support `freshness` without every value; the narrowed set is what it honors.
+        const allowed = values.freshness ?? SEARCH_FRESHNESS;
+        if (!allowed.includes(value as SearchFreshness)) throw invalid(`freshness must be one of ${allowed.join(", ")}`);
+        controls.freshness = value as SearchFreshness;
+        break;
+      }
+      case "includeDomains":
+      case "excludeDomains":
+        controls[control] = domains(value, argument);
+        break;
+      case "country":
+        if (typeof value !== "string" || !CODE_2.test(value)) throw invalid("country must be a two-letter ISO 3166-1 code");
+        controls.country = value.toLowerCase();
+        break;
+      case "language":
+        if (typeof value !== "string" || !CODE_2.test(value)) throw invalid("language must be a two-letter ISO 639-1 code");
+        controls.language = value.toLowerCase();
+        break;
+      case "offset":
+        if (!Number.isSafeInteger(value) || (value as number) < 0) throw invalid("offset must be a non-negative integer");
+        controls.offset = value as number;
+        break;
+    }
+  }
+  return controls;
+}
+
+/** Reads the tool's snake_case arguments into the typed shape `searchControls` validates. */
+export function controlsFromArgs(args: JsonObject): Record<string, unknown> {
+  return {
+    freshness: args.freshness,
+    includeDomains: args.include_domains,
+    excludeDomains: args.exclude_domains,
+    country: args.country,
+    language: args.language,
+    offset: args.offset,
+  };
+}
+
+/** The `web_search` schema properties for one backend, in the model's snake_case spelling. */
+export function searchControlProperties(supports: ReadonlySet<SearchControl>, values: WebSearchControlValues = {}): JsonObject {
+  const properties: Record<string, JsonObject> = {};
+  const entry = (control: SearchControl, schema: JsonObject): void => {
+    if (supports.has(control)) properties[ARGUMENT[control]] = schema;
+  };
+  entry("freshness", {
+    type: "string",
+    enum: [...(values.freshness ?? SEARCH_FRESHNESS)],
+    description: "Only results published in this window",
+  });
+  entry("includeDomains", {
+    type: "array",
+    items: { type: "string" },
+    maxItems: MAX_DOMAIN_CONTROLS,
+    description: "Only results from these hostnames",
+  });
+  entry("excludeDomains", {
+    type: "array",
+    items: { type: "string" },
+    maxItems: MAX_DOMAIN_CONTROLS,
+    description: "Drop results from these hostnames",
+  });
+  entry("country", { type: "string", pattern: "^[A-Za-z]{2}$", description: "Two-letter country code, e.g. US" });
+  entry("language", { type: "string", pattern: "^[A-Za-z]{2}$", description: "Two-letter language code, e.g. en" });
+  entry("offset", { type: "integer", minimum: 0, description: "Result page offset" });
+  return properties as JsonObject;
+}
+
+/**
+ * Turns domain controls into the `site:`/`-site:` operators the HTML-index backends understand.
+ * The operators join the query, so they count toward every query limit the provider enforces.
+ */
+export function domainOperatorsQuery(query: string, controls: SearchControls): string {
+  const parts = [query];
+  for (const domain of controls.includeDomains ?? []) parts.push(`site:${domain}`);
+  for (const domain of controls.excludeDomains ?? []) parts.push(`-site:${domain}`);
+  return parts.join(" ");
+}
+
+function domains(value: unknown, argument: string): readonly string[] {
+  if (!Array.isArray(value) || value.length > MAX_DOMAIN_CONTROLS)
+    throw invalid(`${argument} must be an array of at most ${MAX_DOMAIN_CONTROLS} hostnames`);
+  return value.map((entry) => {
+    if (typeof entry !== "string" || !HOSTNAME.test(entry)) throw invalid(`${argument} must contain bare hostnames`);
+    return entry.toLowerCase();
+  });
+}
+
+function invalid(message: string): WebToolError {
+  return new WebToolError("ERR_PRISM_WEB_INPUT", message);
+}

package/web/src/domains.ts

@@ -0,0 +1,114 @@
+/**
+ * Host-owned domain policy: which hosts web search may show and which URLs fetch/extract may touch.
+ * Model-supplied `include_domains` is a preference, never a permission; this is the permission.
+ */
+import { normalizeHostname } from "@arnilo/prism/net";
+import { WebToolError } from "./transport.js";
+
+export interface ToolsWebDomainsConfig {
+  /** When set, only matching hosts are permitted (an empty list permits none). */
+  readonly allow?: readonly string[];
+  /** Always refused, even when `allow` matches. */
+  readonly block?: readonly string[];
+}
+
+export interface DomainPolicy {
+  /** True when `allow` was configured, so `web_search` can say results are limited. */
+  readonly restricted: boolean;
+  readonly allows: (url: string) => boolean;
+  /** Throws `ERR_PRISM_WEB_DOMAIN` naming the host when the URL is not permitted. */
+  readonly assert: (url: string) => void;
+  /** Keep only permitted rows; `filtered` counts the dropped ones. */
+  readonly filter: <T extends { readonly url: string }>(
+    rows: readonly T[],
+  ) => { readonly results: readonly T[]; readonly filtered: number };
+}
+
+const MAX_ENTRIES = 256;
+
+/** One policy, built once per package, shared by search, fetch, extract, and the `web.fetch` service. */
+export function createDomainPolicy(config: ToolsWebDomainsConfig): DomainPolicy {
+  const allow = config.allow === undefined ? undefined : compile(config.allow, "allow");
+  const block = compile(config.block ?? [], "block");
+
+  const permitted = (host: string): boolean => {
+    if (matches(host, block)) return false;
+    return allow === undefined || matches(host, allow);
+  };
+  const allows = (url: string): boolean => {
+    const host = hostOf(url);
+    // A malformed URL is not a permitted host; adapters report their own error later.
+    return host !== undefined && permitted(host);
+  };
+
+  return {
+    restricted: allow !== undefined,
+    allows,
+    assert: (url) => {
+      if (allows(url)) return;
+      const host = hostOf(url);
+      throw new WebToolError(
+        "ERR_PRISM_WEB_DOMAIN",
+        host === undefined ? "Host domain policy does not permit this URL" : `Host domain policy does not permit ${host}`,
+      );
+    },
+    filter: <T extends { readonly url: string }>(rows: readonly T[]) => {
+      const results = rows.filter((row) => allows(row.url));
+      return { results, filtered: rows.length - results.length };
+    },
+  };
+}
+
+interface Compiled {
+  readonly exact: ReadonlySet<string>;
+  readonly wildcard: ReadonlySet<string>;
+}
+
+function compile(entries: readonly string[], field: "allow" | "block"): Compiled {
+  if (entries.length > MAX_ENTRIES) throw new Error(`domains.${field} may hold at most ${MAX_ENTRIES} entries`);
+  const exact = new Set<string>();
+  const wildcard = new Set<string>();
+  for (const entry of entries) {
+    if (typeof entry !== "string") throw new Error(`domains.${field} entries must be strings`);
+    const trimmed = entry.trim();
+    const isWildcard = trimmed.startsWith("*.");
+    const hostPart = isWildcard ? trimmed.slice(2) : trimmed;
+    if (hostPart.length === 0) throw new Error(`domains.${field} contains an empty hostname`);
+    if (hostPart.includes("*"))
+      throw new Error(`domains.${field} entry ${JSON.stringify(entry)} may only use a leading "*.", not a partial wildcard`);
+    let host: string;
+    try {
+      const parsed = new URL(`https://${hostPart}`);
+      if (parsed.port !== "" || parsed.pathname !== "/" || parsed.username !== "" || parsed.search !== "" || parsed.hash !== "")
+        throw new Error("not a bare hostname");
+      host = normalizeHostname(parsed.hostname);
+    } catch {
+      throw new Error(`domains.${field} entry ${JSON.stringify(entry)} is not a bare hostname`);
+    }
+    (isWildcard ? wildcard : exact).add(host);
+  }
+  return { exact, wildcard };
+}
+
+/** Exact host, or a strict subdomain of a `*.` entry (the apex itself does not match `*.`). */
+function matches(host: string, compiled: Compiled): boolean {
+  if (compiled.exact.has(host)) return true;
+  let candidate = host;
+  while (true) {
+    const dot = candidate.indexOf(".");
+    if (dot === -1) return false;
+    candidate = candidate.slice(dot + 1);
+    if (compiled.wildcard.has(candidate)) return true;
+  }
+}
+
+function hostOf(url: string): string | undefined {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return undefined;
+  }
+  if (!/^https?:$/u.test(parsed.protocol)) return undefined;
+  return normalizeHostname(parsed.hostname);
+}

package/web/src/exa.ts

@@ -0,0 +1,60 @@
+import { searchControls } from "./controls.js";
+import { normalizeSearchResults, providerFacts } from "./normalize.js";
+import { boundedJson, createWebTransport, WebToolError } from "./transport.js";
+import type { SearchControl, WebAdapterOptions, WebSearchAdapter } from "./types.js";
+
+const ORIGIN = "https://api.exa.ai";
+/** Exa filters domain and dates natively; it has no result paging and no language control. */
+const SUPPORTS: ReadonlySet<SearchControl> = new Set(["freshness", "includeDomains", "excludeDomains", "country"]);
+const FRESHNESS_DAYS: Readonly<Record<string, number>> = { day: 1, week: 7, month: 30, year: 365 };
+export function createExaSearch(options: WebAdapterOptions): WebSearchAdapter {
+  const transport = createWebTransport("exa", ORIGIN, options);
+  return {
+    provider: "exa",
+    limits: transport.limits,
+    supports: SUPPORTS,
+    async search(query, call = {}) {
+      return transport.run(call.signal, async (signal) => {
+        // An `offset` or `language` request fails here, naming the argument Exa cannot honor.
+        const controls = searchControls(SUPPORTS, call);
+        const normalized = query.trim();
+        if (!normalized || Buffer.byteLength(normalized) > transport.limits.maxQueryBytes)
+          throw new WebToolError("ERR_PRISM_WEB_INPUT", "Exa query is empty or exceeds byte limit");
+        const count = call.count ?? transport.limits.maxResults;
+        if (!Number.isSafeInteger(count) || count < 1 || count > transport.limits.maxResults)
+          throw new WebToolError("ERR_PRISM_WEB_INPUT", "Exa result count is invalid");
+        const body = JSON.stringify({
+          query: normalized,
+          numResults: count,
+          contents: { text: { maxCharacters: 2_000 }, highlights: { maxCharacters: 1_000 } },
+          ...(controls.includeDomains === undefined ? {} : { includeDomains: controls.includeDomains }),
+          ...(controls.excludeDomains === undefined ? {} : { excludeDomains: controls.excludeDomains }),
+          ...(controls.country === undefined ? {} : { userLocation: controls.country }),
+          ...(controls.freshness === undefined ? {} : { startPublishedDate: publishedSince(controls.freshness) }),
+        });
+        // Search is billed per request; a 429 was refused, so retrying it cannot double-bill.
+        const response = await transport.json("exa", "api_key", new URL("/search", ORIGIN), { method: "POST", body }, signal, {
+          retry: "safe-post",
+        });
+        const metadata = providerFacts(response.value, response.metadata);
+        return boundedJson(
+          {
+            provider: "exa" as const,
+            query: normalized,
+            results: normalizeSearchResults("exa", normalized, response.value, count),
+            metadata,
+            untrusted: true as const,
+          },
+          transport.limits.maxJsonDepth,
+          transport.limits.maxJsonProperties,
+          transport.limits.maxAggregateBytes,
+        );
+      });
+    },
+  };
+}
+
+/** Exa takes an ISO 8601 instant, so a freshness window becomes a lower bound on the publish date. */
+function publishedSince(freshness: string): string {
+  return new Date(Date.now() - FRESHNESS_DAYS[freshness]! * 86_400_000).toISOString();
+}