@dbx-tools/appkit-web-search 0.3.21

package/src/config.ts

@@ -0,0 +1,282 @@
+/**
+ * Configuration for the web-search plugin: the typed
+ * {@link WebSearchPluginConfig} (the plugin's slice of AppKit config), the
+ * JSON Schema the manifest publishes for it, and {@link resolveWebSearchConfig}
+ * which layers that config over environment defaults into the concrete
+ * {@link ResolvedWebSearchConfig} the runtime + tools read.
+ *
+ * `web_search` runs on the Databricks Model Serving native web-search tool
+ * (see `provider.ts` / `search.ts`), so the key knob is which web-search-
+ * capable model to use. It resolves independently of the calling agent's chat
+ * model: `model` (a name, loose name, or capability class) is fuzzy-matched
+ * against the workspace catalogue, and when nothing is pinned the
+ * {@link WebSearchPluginConfig.modelFallbacks} order (Gemini, then GPT, then a
+ * repo floor) picks the first web-search-capable endpoint that exists.
+ *
+ * Resolution never throws here; it just fills defaults. Precedence per field:
+ * explicit plugin config wins, then the matching environment variable, then a
+ * built-in default.
+ *
+ * Env fallbacks: `WEB_SEARCH_MODEL`, `WEB_SEARCH_MODEL_FALLBACKS`,
+ * `WEB_SEARCH_TOOLS` (JSON), `WEB_SEARCH_ALLOWED_URLS`,
+ * `WEB_SEARCH_MAX_CITATIONS`, `WEB_SEARCH_FETCH_MAX_LENGTH`,
+ * `WEB_SEARCH_TIMEOUT_MS`, `WEB_SEARCH_FUZZY`, `WEB_SEARCH_FUZZY_THRESHOLD`.
+ *
+ * @module
+ */
+
+import type { BasePluginConfig } from "@databricks/appkit";
+import { object, type OneOrMany } from "@dbx-tools/shared-core";
+import type { JSONSchema7 } from "json-schema";
+import { parseAllowedUrls, toUrlAllowList, type UrlAllowList } from "./allowlist";
+
+/**
+ * A URL-pattern gate for per-tool approval. `true` gates every call; a
+ * pattern (or list of patterns, in the {@link OneOrMany} shape used across
+ * the repo) gates only calls whose URL matches. Patterns use the same glob
+ * syntax as the allow-list (see `allowlist.ts`). Omit / `false` for no
+ * approval.
+ */
+export type ApprovalGate = boolean | OneOrMany<string> | string;
+
+/**
+ * Default web-search model preference, tried in order when no model is
+ * pinned. Gemini first, then GPT - both support the native web-search tool;
+ * a workspace typically has at least one. Each is fuzzy-matched against the
+ * live catalogue, so a close variant (e.g. `databricks-gemini-3-1-pro`) is
+ * picked when the exact id isn't present.
+ */
+export const DEFAULT_MODEL_FALLBACKS: readonly string[] = [
+  "databricks-gemini-3-pro",
+  "databricks-gemini-2-5-pro",
+  "databricks-gpt-5",
+  "databricks-gpt-5-mini",
+];
+
+/** Default cap on the number of citations returned from a single search. */
+export const DEFAULT_MAX_CITATIONS = 10;
+
+/** Default cap on characters returned from a single `web_fetch`. */
+export const DEFAULT_FETCH_MAX_LENGTH = 50_000;
+
+/** Default per-request network timeout (ms) for search + fetch. */
+export const DEFAULT_TIMEOUT_MS = 30_000;
+
+/** AppKit config accepted by the web-search plugin. */
+export interface WebSearchPluginConfig extends BasePluginConfig {
+  /**
+   * The web-search model to use by default: a Databricks serving endpoint
+   * name (`"databricks-gemini-3-pro"`), a loose name (`"gemini"`, `"gpt"`),
+   * or a capability class. Fuzzy-matched against the live catalogue. Falls
+   * back to `WEB_SEARCH_MODEL`, then the {@link modelFallbacks} order. Chosen
+   * independently of the calling agent's chat model.
+   */
+  model?: string;
+  /**
+   * Priority-ordered web-search model candidates tried when {@link model} is
+   * unset, each fuzzy-matched and checked for web-search support. Falls back
+   * to `WEB_SEARCH_MODEL_FALLBACKS` (comma/space-separated), then
+   * {@link DEFAULT_MODEL_FALLBACKS} (Gemini, then GPT).
+   */
+  modelFallbacks?: string | string[];
+  /**
+   * Provider -> tool-spec override map, merged over the built-in
+   * {@link WEB_SEARCH_PROVIDERS} defaults. Keyed by provider family
+   * (`"openai"`, `"gemini"`); each value may override the `tool` entry
+   * and/or the `api` surface. Use to change the tool shape as the platform
+   * evolves without a code change. Falls back to `WEB_SEARCH_TOOLS` parsed as
+   * JSON. This is the `WEB_SEARCH_TOOLS` setting.
+   */
+  webSearchTools?: Record<string, unknown>;
+  /**
+   * Enable fuzzy matching of loose model names against the catalogue.
+   * Defaults to `true`; falls back to `WEB_SEARCH_FUZZY`.
+   */
+  modelFuzzyMatch?: boolean;
+  /** Fuse.js fuzzy threshold. Falls back to `WEB_SEARCH_FUZZY_THRESHOLD`, then 0.4. */
+  modelFuzzyThreshold?: number;
+  /**
+   * Hard cap on the number of citations a single search returns. Falls back
+   * to `WEB_SEARCH_MAX_CITATIONS`, then {@link DEFAULT_MAX_CITATIONS}.
+   */
+  maxCitations?: number;
+  /**
+   * Hard cap on the character length of a single `web_fetch` result. Falls
+   * back to `WEB_SEARCH_FETCH_MAX_LENGTH`, then {@link DEFAULT_FETCH_MAX_LENGTH}.
+   */
+  fetchMaxLength?: number;
+  /**
+   * Per-request network timeout in ms for search + fetch. Falls back to
+   * `WEB_SEARCH_TIMEOUT_MS`, then {@link DEFAULT_TIMEOUT_MS}.
+   */
+  timeoutMs?: number;
+  /**
+   * Fall back to a DuckDuckGo scrape when the workspace has NO deployed
+   * web-search-capable model (no GPT / Gemini serving endpoint). The native
+   * Databricks tool is always preferred; this only kicks in when there is no
+   * native option, so the tool still returns results instead of erroring.
+   * Defaults to `true`; set `false` (or `WEB_SEARCH_SCRAPE_FALLBACK=0`) to
+   * require a native model and error otherwise.
+   */
+  scrapeFallback?: boolean;
+  /**
+   * Optional URL allow-list. Each entry is a glob (or bare host) tested
+   * against a URL's full `href`. When set, `web_search` silently filters
+   * citations to the permitted set and `web_fetch` refuses a disallowed URL.
+   * Accepts a `string[]` or a comma-/whitespace-separated string; falls back
+   * to `WEB_SEARCH_ALLOWED_URLS`. Omit (or leave empty) for no restriction.
+   * See `allowlist.ts`.
+   */
+  allowedUrls?: string | string[];
+  /**
+   * Approval gate applied to BOTH tools (per-tool overrides via
+   * {@link WebSearchToolOptions.approval} win). `true` gates every call;
+   * a URL-pattern (or list) gates only matching calls. Omit for no approval.
+   */
+  approval?: ApprovalGate;
+}
+
+/** Concrete, validated config the runtime + tools read. */
+export interface ResolvedWebSearchConfig {
+  /** Pinned web-search model, when configured (else undefined - use fallbacks). */
+  model?: string;
+  /** Ordered fallback model candidates (Gemini, then GPT, then a floor). */
+  modelFallbacks: readonly string[];
+  /** Provider -> tool-spec override map, merged over the built-in defaults. */
+  webSearchTools: Record<string, unknown>;
+  /** Whether to fuzzy-match loose model names. */
+  fuzzy: boolean;
+  /** Fuse.js fuzzy threshold. */
+  fuzzyThreshold: number;
+  maxCitations: number;
+  fetchMaxLength: number;
+  timeoutMs: number;
+  /** Whether to scrape-fallback when no native web-search model is deployed. */
+  scrapeFallback: boolean;
+  /** Compiled allow-list (permit-all when unconfigured). */
+  allowList: UrlAllowList;
+  /** Default per-tool approval gate. */
+  approval: ApprovalGate;
+}
+
+/** JSON Schema published on the manifest's `config.schema`. */
+export const WEB_SEARCH_CONFIG_SCHEMA: JSONSchema7 = {
+  type: "object",
+  properties: {
+    model: {
+      type: "string",
+      description:
+        "Default web-search model (endpoint name, loose name, or class). Fuzzy-matched. Env: WEB_SEARCH_MODEL.",
+    },
+    modelFallbacks: {
+      type: "array",
+      items: { type: "string" },
+      description:
+        "Ordered web-search model candidates when `model` is unset (Gemini, then GPT). Env: WEB_SEARCH_MODEL_FALLBACKS.",
+    },
+    webSearchTools: {
+      type: "object",
+      description:
+        'Provider -> tool-spec override map merged over the built-in defaults (openai -> {"type":"web_search"}, gemini -> {"google_search":{}}). Env: WEB_SEARCH_TOOLS (JSON).',
+    },
+    maxCitations: {
+      type: "number",
+      description: "Hard cap on citations returned (env: WEB_SEARCH_MAX_CITATIONS).",
+    },
+    fetchMaxLength: {
+      type: "number",
+      description: "Hard cap on web_fetch content length (env: WEB_SEARCH_FETCH_MAX_LENGTH).",
+    },
+    timeoutMs: {
+      type: "number",
+      description: "Per-request network timeout in ms (env: WEB_SEARCH_TIMEOUT_MS).",
+    },
+    allowedUrls: {
+      type: "array",
+      items: { type: "string" },
+      description:
+        'URL allow-list of globs / bare hosts (e.g. "*.databricks.com", "docs.example.com"). Also accepts a comma/space-separated string. Falls back to WEB_SEARCH_ALLOWED_URLS. Empty = unrestricted.',
+    },
+  },
+};
+
+/** Split a CSV / whitespace / array value into a trimmed, non-empty string list. */
+function toStringList(raw: string | string[] | undefined): string[] {
+  const entries = typeof raw === "string" ? raw.split(/[\s,]+/) : Array.isArray(raw) ? raw : [];
+  return [
+    ...object
+      .sequence(entries)
+      .map((e) => e.trim())
+      .filter((e) => e.length > 0)
+      .distinct()
+      .toArray(),
+  ];
+}
+
+/** Parse a positive integer env/config value, else the fallback. */
+function resolvePositiveInt(value: number | undefined, envKey: string, fallback: number): number {
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) return Math.floor(value);
+  const env = Number(process.env[envKey]);
+  return Number.isFinite(env) && env > 0 ? Math.floor(env) : fallback;
+}
+
+/** Parse the `WEB_SEARCH_TOOLS` env var (JSON), else `{}`. Bad JSON is ignored. */
+function parseToolsEnv(): Record<string, unknown> {
+  const raw = process.env["WEB_SEARCH_TOOLS"];
+  if (!raw) return {};
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    return parsed && typeof parsed === "object" ? (parsed as Record<string, unknown>) : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Resolve plugin config over environment defaults into the concrete
+ * {@link ResolvedWebSearchConfig}. Never throws - the model is resolved
+ * lazily at call time (against the live catalogue), so an unconfigured plugin
+ * resolves to sensible defaults with no restrictions.
+ */
+export function resolveWebSearchConfig(
+  config: WebSearchPluginConfig = {},
+): ResolvedWebSearchConfig {
+  const patterns = parseAllowedUrls(config.allowedUrls ?? process.env["WEB_SEARCH_ALLOWED_URLS"]);
+  const model = config.model ?? process.env["WEB_SEARCH_MODEL"];
+  const fallbacks = toStringList(config.modelFallbacks ?? process.env["WEB_SEARCH_MODEL_FALLBACKS"]);
+  const fuzzyThresholdRaw = config.modelFuzzyThreshold ?? Number(process.env["WEB_SEARCH_FUZZY_THRESHOLD"]);
+  return {
+    ...(model ? { model } : {}),
+    modelFallbacks: fallbacks.length > 0 ? fallbacks : DEFAULT_MODEL_FALLBACKS,
+    webSearchTools: { ...parseToolsEnv(), ...(config.webSearchTools ?? {}) },
+    fuzzy:
+      config.modelFuzzyMatch ?? object.toBoolean(process.env["WEB_SEARCH_FUZZY"]) ?? true,
+    fuzzyThreshold: Number.isFinite(fuzzyThresholdRaw) && fuzzyThresholdRaw ? Number(fuzzyThresholdRaw) : 0.4,
+    maxCitations: resolvePositiveInt(config.maxCitations, "WEB_SEARCH_MAX_CITATIONS", DEFAULT_MAX_CITATIONS),
+    fetchMaxLength: resolvePositiveInt(
+      config.fetchMaxLength,
+      "WEB_SEARCH_FETCH_MAX_LENGTH",
+      DEFAULT_FETCH_MAX_LENGTH,
+    ),
+    timeoutMs: resolvePositiveInt(config.timeoutMs, "WEB_SEARCH_TIMEOUT_MS", DEFAULT_TIMEOUT_MS),
+    scrapeFallback:
+      config.scrapeFallback ?? object.toBoolean(process.env["WEB_SEARCH_SCRAPE_FALLBACK"]) ?? true,
+    allowList: toUrlAllowList(patterns),
+    approval: config.approval ?? false,
+  };
+}
+
+/**
+ * Resolve an {@link ApprovalGate} against a set of candidate URLs into a
+ * concrete boolean: `true`/`false` pass through; a pattern (or list) gates
+ * when ANY candidate matches. Empty candidates with a pattern gate never
+ * match (nothing to approve). Reuses the allow-list matcher so approval
+ * globs read exactly like allow-list globs.
+ */
+export function approvalMatches(gate: ApprovalGate, urls: readonly string[]): boolean {
+  if (typeof gate === "boolean") return gate;
+  const patterns = parseAllowedUrls(typeof gate === "string" ? gate : [...gate]);
+  if (patterns.length === 0) return false;
+  const list = toUrlAllowList(patterns);
+  return urls.some((url) => list.allows(url));
+}

package/src/fetch.ts

@@ -0,0 +1,118 @@
+/**
+ * Page fetching over {@link https://www.npmjs.com/package/got-scraping | got-scraping}
+ * - a `got` wrapper that generates browser-like TLS + header fingerprints, so
+ * fetches survive the bot walls a plain `fetch` trips. {@link runWebFetch}
+ * enforces the URL allow-list (an explicit fetch of a disallowed URL is
+ * refused, not silently emptied), fetches with the plugin's timeout, and
+ * returns either the raw HTML or a readable plain-text reduction, capped at
+ * the configured length.
+ *
+ * The HTML-to-text reduction is deliberately dependency-free (strip
+ * script/style, unwrap tags, decode a handful of entities, collapse
+ * whitespace): good enough to feed a model, and it keeps the add-on's
+ * dependency surface to the two libraries the task called for.
+ *
+ * @module
+ */
+
+import { log } from "@dbx-tools/shared-core";
+import { gotScraping } from "got-scraping";
+import { assertUrlAllowed } from "./allowlist";
+import type { ResolvedWebSearchConfig } from "./config";
+import type { WebFetchRequest, WebFetchResult } from "./schema";
+
+const logger = log.logger("web-search/fetch");
+
+/** Pull the <title> text out of an HTML document, when present. */
+function extractTitle(html: string): string | undefined {
+  const match = /<title[^>]*>([\s\S]*?)<\/title>/i.exec(html);
+  const title = match?.[1] ? decodeEntities(match[1]).trim() : "";
+  return title.length > 0 ? title : undefined;
+}
+
+/** Decode the handful of HTML entities that survive tag-stripping. */
+function decodeEntities(text: string): string {
+  return text
+    .replace(/&nbsp;/g, " ")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&#(\d+);/g, (_, code) => String.fromCodePoint(Number(code)));
+}
+
+/**
+ * Reduce an HTML document to readable plain text: drop `<script>` /
+ * `<style>` / `<noscript>` blocks and HTML comments, turn block-level tags
+ * into newlines, strip the remaining tags, decode entities, and collapse
+ * runs of blank lines / trailing spaces.
+ */
+export function htmlToText(html: string): string {
+  return decodeEntities(
+    html
+      .replace(/<!--[\s\S]*?-->/g, "")
+      .replace(/<(script|style|noscript)[^>]*>[\s\S]*?<\/\1>/gi, "")
+      .replace(/<\/(p|div|section|article|li|tr|h[1-6]|header|footer|br)>/gi, "\n")
+      .replace(/<br\s*\/?>/gi, "\n")
+      .replace(/<[^>]+>/g, ""),
+  )
+    .replace(/[ \t]+\n/g, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .replace(/[ \t]{2,}/g, " ")
+    .trim();
+}
+
+/** Truncate `text` to `max` chars, reporting whether it was cut. */
+function truncate(text: string, max: number): { content: string; truncated: boolean } {
+  if (text.length <= max) return { content: text, truncated: false };
+  return { content: text.slice(0, max), truncated: true };
+}
+
+/**
+ * Fetch a single URL and return its content in the requested format.
+ *
+ * Throws when the URL is not permitted by the allow-list (the visible,
+ * correctable failure the design calls for on the fetch path). Network /
+ * HTTP errors propagate from got-scraping. The request's `maxLength` narrows
+ * (never widens) the plugin's `fetchMaxLength` cap.
+ */
+export async function runWebFetch(
+  request: WebFetchRequest,
+  config: ResolvedWebSearchConfig,
+): Promise<WebFetchResult> {
+  assertUrlAllowed(request.url, config.allowList);
+  const cap = Math.min(request.maxLength ?? config.fetchMaxLength, config.fetchMaxLength);
+
+  const response = await gotScraping({
+    url: request.url,
+    timeout: { request: config.timeoutMs },
+    throwHttpErrors: false,
+    followRedirect: true,
+  });
+
+  const body = typeof response.body === "string" ? response.body : String(response.body ?? "");
+  const contentType = response.headers["content-type"];
+  const isHtml = !contentType || /html|xml/i.test(contentType);
+  const rawContent =
+    request.format === "html" || !isHtml ? body : htmlToText(body);
+  const { content, truncated } = truncate(rawContent, cap);
+  const title = isHtml ? extractTitle(body) : undefined;
+
+  logger.debug("fetched", {
+    url: response.url,
+    status: response.statusCode,
+    bytes: body.length,
+    returned: content.length,
+    ...(truncated ? { truncated: true } : {}),
+  });
+
+  return {
+    url: response.url ?? request.url,
+    status: response.statusCode,
+    ...(contentType ? { contentType } : {}),
+    ...(title ? { title } : {}),
+    content,
+    truncated,
+  };
+}

package/src/plugin.ts

@@ -0,0 +1,87 @@
+/**
+ * AppKit plugin (registered name: `web-search`) that owns the resolved
+ * web-search runtime - the URL allow-list, result / length caps, timeout,
+ * and default approval gate the {@link webSearchTool} / {@link webFetchTool}
+ * read. Registering it resolves and logs the effective config (whether an
+ * allow-list is active, the caps) so a misconfiguration is visible in the
+ * boot logs rather than on the first search.
+ *
+ * The tools do the actual work when spread into an agent; this plugin primes
+ * the shared runtime they reuse and exposes direct {@link runWebSearch} /
+ * {@link runWebFetch} for non-agent callers.
+ *
+ * @module
+ */
+
+import { getExecutionContext, Plugin, toPlugin, type PluginManifest } from "@databricks/appkit";
+import { log } from "@dbx-tools/shared-core";
+import { WEB_SEARCH_CONFIG_SCHEMA, type WebSearchPluginConfig } from "./config";
+import { runWebFetch } from "./fetch";
+import { getWebSearchRuntime } from "./runtime";
+import type { WebFetchRequest, WebFetchResult, WebSearchRequest, WebSearchResult } from "./schema";
+import { runWebSearch, type WebSearchContext } from "./search";
+
+/**
+ * AppKit plugin that resolves and holds the web-search runtime config used
+ * by the `web_search` / `web_fetch` tools.
+ */
+export class WebSearchPlugin extends Plugin<WebSearchPluginConfig> {
+  static manifest = {
+    name: "web-search",
+    displayName: "Web Search",
+    description:
+      "Searches the web (via duck-duck-scrape) and fetches pages (via got-scraping), " +
+      "with an optional URL allow-list and per-tool approval gating.",
+    stability: "beta",
+    resources: {
+      required: [],
+      optional: [],
+    },
+    config: { schema: WEB_SEARCH_CONFIG_SCHEMA },
+  } satisfies PluginManifest<"web-search">;
+
+  private logger = log.logger(this);
+
+  /**
+   * Prime the shared runtime from this plugin's config (over env) and log
+   * the effective policy so an active allow-list / caps are obvious at boot.
+   */
+  override async setup(): Promise<void> {
+    const { config } = getWebSearchRuntime(this.config);
+    this.logger.info("ready", {
+      model: config.model ?? `fallbacks:[${config.modelFallbacks.join(", ")}]`,
+      restricted: config.allowList.restricted,
+      ...(config.allowList.restricted ? { allowedUrls: config.allowList.patterns } : {}),
+      maxCitations: config.maxCitations,
+      fetchMaxLength: config.fetchMaxLength,
+      approval: config.approval === false ? "none" : config.approval,
+    });
+  }
+
+  /** Resolve the OBO client + host from the active execution context. */
+  private async searchContext(): Promise<WebSearchContext> {
+    const ctx = getExecutionContext();
+    const host = (await ctx.client.config.getHost()).toString();
+    return { client: ctx.client, host };
+  }
+
+  override exports() {
+    return {
+      /**
+       * Run a web search directly (bypassing the agent tool). Resolves the
+       * OBO client from the active execution context and reads the shared
+       * runtime config primed at setup.
+       */
+      search: async (request: WebSearchRequest): Promise<WebSearchResult> =>
+        runWebSearch(request, getWebSearchRuntime().config, await this.searchContext()),
+      /**
+       * Fetch one URL directly (bypassing the agent tool). Enforces the
+       * configured allow-list. Reads the shared runtime config.
+       */
+      fetch: (request: WebFetchRequest): Promise<WebFetchResult> =>
+        runWebFetch(request, getWebSearchRuntime().config),
+    };
+  }
+}
+
+export const webSearch = toPlugin(WebSearchPlugin);

package/src/provider.ts

@@ -0,0 +1,90 @@
+/**
+ * Provider detection + web-search tool-spec mapping for the Databricks
+ * Model Serving native web-search tool.
+ *
+ * Databricks exposes web search as a first-party tool that runs *inside* a
+ * model call: the model searches the web and folds the results into its
+ * answer. The tool spec is provider-specific (see the Databricks docs,
+ * `machine-learning/model-serving/web-search`):
+ *
+ * - OpenAI GPT models, via the Responses API (`/serving-endpoints/responses`):
+ *   `tools: [{ "type": "web_search" }]`
+ * - Google Gemini models, via Chat Completions
+ *   (`/serving-endpoints/chat/completions`): `tools: [{ "google_search": {} }]`
+ *
+ * (Anthropic exposes it over MCP, which needs a different call shape; only
+ * GPT + Gemini are wired here, matching what the platform supports today.)
+ *
+ * The provider family is detected from the endpoint id the same way
+ * `@dbx-tools/shared-model`'s `classifyByFamily` keys off name substrings
+ * (`gpt` / `gemini` / `claude`), so a resolved endpoint like
+ * `databricks-gpt-5` or `databricks-gemini-3-pro` maps to its API shape.
+ *
+ * @module
+ */
+
+/** A web-search-capable model provider family. */
+export type WebSearchProvider = "openai" | "gemini";
+
+/** How a provider's native web-search call is shaped. */
+export interface WebSearchProviderSpec {
+  /**
+   * Which serving REST surface to call. `"responses"` posts to
+   * `/serving-endpoints/responses` (OpenAI Responses API); `"chat"` posts to
+   * `/serving-endpoints/chat/completions`.
+   */
+  api: "responses" | "chat";
+  /** The tool entry appended to the request's `tools` array. */
+  tool: Record<string, unknown>;
+}
+
+/**
+ * Built-in provider -> tool-spec map. Operators can override or extend this
+ * per provider via the plugin's `webSearchTools` config (env
+ * `WEB_SEARCH_TOOLS`), which is merged over these defaults.
+ */
+export const WEB_SEARCH_PROVIDERS: Readonly<Record<WebSearchProvider, WebSearchProviderSpec>> = {
+  openai: { api: "responses", tool: { type: "web_search" } },
+  gemini: { api: "chat", tool: { google_search: {} } },
+};
+
+/**
+ * Detect the web-search provider family for an endpoint id, or `null` when
+ * the model is not one of the web-search-capable families. Anthropic
+ * (`opus`/`sonnet`/`haiku`) is intentionally excluded - it needs an MCP call
+ * shape this module doesn't implement - so a Claude endpoint returns `null`
+ * and is treated as unsupported.
+ */
+export function detectWebSearchProvider(modelId: string): WebSearchProvider | null {
+  const n = modelId.toLowerCase();
+  // gpt-oss open-weights don't carry the hosted web-search tool; only the
+  // hosted GPT family (Responses API) does. Both contain "gpt", so exclude
+  // the open-weights explicitly.
+  if (n.includes("gpt") && !n.includes("gpt-oss")) return "openai";
+  if (n.includes("gemini")) return "gemini";
+  return null;
+}
+
+/** Whether `modelId` is a web-search-capable model. */
+export function supportsWebSearch(modelId: string): boolean {
+  return detectWebSearchProvider(modelId) !== null;
+}
+
+/**
+ * Resolve the effective {@link WebSearchProviderSpec} for a provider: the
+ * built-in default, with any operator override (the `webSearchTools` map,
+ * keyed by provider) shallow-merged over it. An override may replace just the
+ * `tool` (the common case - a new tool type) or also the `api`.
+ */
+export function webSearchToolSpec(
+  provider: WebSearchProvider,
+  overrides?: Record<string, unknown>,
+): WebSearchProviderSpec {
+  const base = WEB_SEARCH_PROVIDERS[provider];
+  const override = overrides?.[provider] as Partial<WebSearchProviderSpec> | undefined;
+  if (!override) return base;
+  return {
+    api: override.api ?? base.api,
+    tool: override.tool ?? base.tool,
+  };
+}

package/src/runtime.ts

@@ -0,0 +1,40 @@
+/**
+ * The web-search runtime: a lazily-resolved, process-wide config shared by
+ * the plugin and the `web_search` / `web_fetch` tools, so both read one
+ * resolved allow-list / cap / timeout set. The first caller (normally the
+ * plugin at setup) primes it from the plugin's config; later callers (the
+ * tools' `execute`) reuse it.
+ *
+ * Unlike the email runtime there is no connection to pool - the backend is
+ * stateless HTTP per call - so the runtime holds only the resolved config.
+ *
+ * @module
+ */
+
+import { resolveWebSearchConfig, type ResolvedWebSearchConfig, type WebSearchPluginConfig } from "./config";
+
+/** The shared resolved config. */
+export interface WebSearchRuntime {
+  config: ResolvedWebSearchConfig;
+}
+
+let runtime: WebSearchRuntime | undefined;
+
+/**
+ * Return the shared runtime, building it on first use from the supplied
+ * config layered over environment defaults. Overrides are only read when the
+ * runtime is first created, so prime it from the plugin's config at setup;
+ * subsequent calls (the tools' `execute`) pass nothing and get the same
+ * instance.
+ */
+export function getWebSearchRuntime(overrides?: WebSearchPluginConfig): WebSearchRuntime {
+  if (!runtime) {
+    runtime = { config: resolveWebSearchConfig(overrides) };
+  }
+  return runtime;
+}
+
+/** Drop the memoized runtime so the next {@link getWebSearchRuntime} rebuilds it. */
+export function resetWebSearchRuntime(): void {
+  runtime = undefined;
+}