@dbx-tools/appkit-web-search 0.3.21

package/src/schema.ts

@@ -0,0 +1,116 @@
+/**
+ * Wire-format contract for the web-search add-on: the two tool inputs a
+ * model fills in (`web_search`, `web_fetch`) and the results handed back.
+ * Pure zod + inferred types (no Node-only imports) so the tool layer, the
+ * plugin, and any future UI validate / type against one definition.
+ *
+ * `web_search` is backed by the Databricks Model Serving native web-search
+ * tool (see `provider.ts`): the model searches the web server-side and
+ * returns a synthesized answer plus the sources it used. `web_fetch` reads a
+ * single page's contents via got-scraping.
+ *
+ * Array fields intentionally avoid `.min()` / `.nonempty()`: those emit
+ * `minItems` in the JSON schema, which some Model Serving endpoints reject
+ * ("array types do not support minItems") when the schema is forwarded as a
+ * tool definition - the same constraint the email add-on documents.
+ *
+ * @module
+ */
+
+import { string } from "@dbx-tools/shared-core";
+import { z } from "zod";
+
+/** Schema for the `web_search` tool input. */
+export const webSearchRequestSchema = z.object({
+  query: z
+    .string()
+    .describe(
+      "What to search the web for, phrased as a natural-language question or request. The model searches and answers in one step.",
+    ),
+  model: z
+    .string()
+    .optional()
+    .describe(
+      string.toDescription(`
+        Optional web-search-capable model to use (a Databricks serving
+        endpoint name like "databricks-gemini-3-pro", a loose name like "gpt"
+        or "gemini", or a capability class). Defaults to the plugin's
+        configured web-search model. The web-search tool resolves its own
+        model independently of the calling agent's chat model, since not
+        every chat model supports web search.
+      `),
+    ),
+});
+
+/** A validated `web_search` request. */
+export type WebSearchRequest = z.infer<typeof webSearchRequestSchema>;
+
+/** Schema for a single source the model cited while answering. */
+export const webSearchCitationSchema = z.object({
+  url: z.string().describe("The source URL the answer drew on."),
+  title: z.string().optional().describe("The source page title, when available."),
+  snippet: z.string().optional().describe("A short excerpt from the source, when available."),
+});
+
+/** A single cited source ({@link webSearchCitationSchema}). */
+export type WebSearchCitation = z.infer<typeof webSearchCitationSchema>;
+
+/** Schema for the `web_search` tool output. */
+export const webSearchResultSchema = z.object({
+  query: z.string().describe("Echo of the query that was searched."),
+  answer: z
+    .string()
+    .describe("The model's answer, synthesized from live web results."),
+  citations: z
+    .array(webSearchCitationSchema)
+    .describe(
+      "Sources the answer drew on. When an allow-list is configured, citations whose URL is not permitted are silently omitted.",
+    ),
+  model: z.string().describe("The serving endpoint that produced the answer."),
+});
+
+/** The outcome of a `web_search` call ({@link webSearchResultSchema}). */
+export type WebSearchResult = z.infer<typeof webSearchResultSchema>;
+
+/** Schema for the `web_fetch` tool input. */
+export const webFetchRequestSchema = z.object({
+  url: z
+    .string()
+    .describe(
+      "The absolute URL to fetch (must include the scheme, e.g. https://). When an allow-list is configured, a URL it does not permit is refused.",
+    ),
+  format: z
+    .enum(["text", "html"])
+    .optional()
+    .describe(
+      string.toDescription(`
+        Return format: "text" (default) strips the page to readable plain
+        text; "html" returns the raw response body. Prefer "text" unless you
+        need the markup.
+      `),
+    ),
+  maxLength: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe(
+      "Truncate the returned content to at most this many characters (the plugin caps this at its configured limit).",
+    ),
+});
+
+/** A validated `web_fetch` request. */
+export type WebFetchRequest = z.infer<typeof webFetchRequestSchema>;
+
+/** Schema for the `web_fetch` tool output. */
+export const webFetchResultSchema = z.object({
+  url: z.string().describe("The final URL fetched (after redirects)."),
+  status: z.number().describe("HTTP status code of the response."),
+  contentType: z.string().optional().describe("Response `Content-Type`, when the server sent one."),
+  title: z.string().optional().describe("The page <title>, when one was present."),
+  content: z.string().describe("The page content in the requested format (text or html)."),
+  truncated: z.boolean().describe("True when `content` was cut off at the length cap."),
+});
+
+/** The outcome of a `web_fetch` call ({@link webFetchResultSchema}). */
+export type WebFetchResult = z.infer<typeof webFetchResultSchema>;

package/src/scrape.ts

@@ -0,0 +1,116 @@
+/**
+ * Last-resort scraping fallback for `web_search`, used ONLY when the
+ * workspace has no Databricks web-search-capable model deployed (no GPT /
+ * Gemini serving endpoint). The native Databricks web-search tool is always
+ * preferred (see `search.ts`); this exists so the tool still returns useful
+ * results in an environment that can't run it, rather than erroring on every
+ * call.
+ *
+ * It queries DuckDuckGo's no-JS HTML endpoint through `got-scraping`
+ * (browser-like fingerprints so the request isn't blocked) via a GET with the
+ * query in the query string - a POST to the same endpoint trips DDG's bot
+ * challenge (HTTP 202), while the GET returns normal result markup. It then
+ * parses the result anchors + snippets. Unlike the native tool there is no
+ * model synthesizing an answer, so `answer` is a short lead-in over the top
+ * snippets and the substance rides in `citations` - the calling agent reads
+ * those and writes its own answer.
+ *
+ * @module
+ */
+
+import { log } from "@dbx-tools/shared-core";
+import { gotScraping } from "got-scraping";
+import type { ResolvedWebSearchConfig } from "./config";
+import type { WebSearchCitation, WebSearchRequest, WebSearchResult } from "./schema";
+
+const logger = log.logger("web-search/scrape");
+
+/** DuckDuckGo's no-JS HTML results endpoint (queried via GET). */
+const DDG_HTML_URL = "https://html.duckduckgo.com/html/";
+
+/** Strip HTML tags and decode the few entities DDG emits in titles/snippets. */
+function stripTags(html: string): string {
+  return html
+    .replace(/<[^>]+>/g, "")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#x27;|&#39;/g, "'")
+    .replace(/&nbsp;/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/**
+ * DDG wraps result URLs in a redirect (`//duckduckgo.com/l/?uddg=<encoded>`).
+ * Unwrap to the real destination; leave already-absolute URLs untouched.
+ */
+function unwrapDdgUrl(href: string): string {
+  try {
+    const u = new URL(href, "https://duckduckgo.com");
+    const target = u.searchParams.get("uddg");
+    if (target) return decodeURIComponent(target);
+    return u.protocol === "http:" || u.protocol === "https:" ? u.toString() : href;
+  } catch {
+    return href;
+  }
+}
+
+/** Parse DDG HTML result blocks into citations (title, url, snippet). */
+function parseDdgHtml(html: string): WebSearchCitation[] {
+  const citations: WebSearchCitation[] = [];
+  // Each result: an anchor with class result__a (title + href) and a snippet
+  // with class result__snippet. Match anchors, then the following snippet.
+  const anchorRe = /<a[^>]*class="[^"]*result__a[^"]*"[^>]*href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/g;
+  const snippetRe = /<a[^>]*class="[^"]*result__snippet[^"]*"[^>]*>([\s\S]*?)<\/a>/g;
+  const snippets: string[] = [];
+  let sm: RegExpExecArray | null;
+  while ((sm = snippetRe.exec(html)) !== null) snippets.push(stripTags(sm[1] ?? ""));
+  let am: RegExpExecArray | null;
+  let i = 0;
+  while ((am = anchorRe.exec(html)) !== null) {
+    const url = unwrapDdgUrl(am[1] ?? "");
+    const title = stripTags(am[2] ?? "");
+    if (!url || !title) continue;
+    const snippet = snippets[i] ?? "";
+    citations.push({ url, title, ...(snippet ? { snippet } : {}) });
+    i += 1;
+  }
+  return citations;
+}
+
+/**
+ * Run a scraping search over DuckDuckGo. Returns the same
+ * {@link WebSearchResult} shape as the native path, with `model` set to
+ * `"scrape:duckduckgo"` so callers can tell how the result was produced.
+ * Citations are filtered through the configured URL allow-list.
+ */
+export async function runScrapeSearch(
+  request: WebSearchRequest,
+  config: ResolvedWebSearchConfig,
+): Promise<WebSearchResult> {
+  const response = await gotScraping({
+    url: `${DDG_HTML_URL}?q=${encodeURIComponent(request.query)}`,
+    method: "GET",
+    timeout: { request: config.timeoutMs },
+    throwHttpErrors: false,
+    followRedirect: true,
+  });
+  const body = typeof response.body === "string" ? response.body : String(response.body ?? "");
+  const all = parseDdgHtml(body);
+  const permitted = all.filter((c) => config.allowList.allows(c.url));
+  const citations = permitted.slice(0, config.maxCitations);
+  const answer =
+    citations.length > 0
+      ? `Web results for "${request.query}" (no Databricks web-search model is deployed in this workspace, so these are unsynthesized search results - read the citations):\n\n` +
+        citations.map((c, n) => `${n + 1}. ${c.title}${c.snippet ? ` - ${c.snippet}` : ""} (${c.url})`).join("\n")
+      : `No web results found for "${request.query}".`;
+  logger.debug("scraped", {
+    query: request.query,
+    found: all.length,
+    returned: citations.length,
+    status: response.statusCode,
+  });
+  return { query: request.query, answer, citations, model: "scrape:duckduckgo" };
+}

package/src/search.ts

@@ -0,0 +1,257 @@
+/**
+ * Web search backed by the Databricks Model Serving native web-search tool.
+ *
+ * Unlike a scraping client, the search runs *inside* a model call: we POST the
+ * query to the workspace's serving endpoint with the provider's web-search
+ * tool spec attached, and the model searches the web and writes the answer.
+ * {@link runWebSearch}:
+ *
+ *   1. Resolves a web-search-capable model INDEPENDENTLY of the calling
+ *      agent's chat model (the agent may run on a model without web search).
+ *      A pinned `model` (request or config) is fuzzy-matched; otherwise the
+ *      configured fallback order (Gemini, then GPT) is walked to the first
+ *      web-search-capable endpoint that exists in the workspace. An explicit
+ *      but unsupported model is a hard error, not a silent fallback.
+ *   2. POSTs to the provider's REST surface (`/serving-endpoints/responses`
+ *      for OpenAI, `/serving-endpoints/chat/completions` for Gemini) with the
+ *      mapped tool spec, using the OBO-scoped workspace client.
+ *   3. Returns the synthesized answer plus the cited sources, with citations
+ *      silently filtered through the configured URL allow-list.
+ *
+ * @module
+ */
+
+import { error, log } from "@dbx-tools/shared-core";
+import { resolve, serving } from "@dbx-tools/model";
+import type { ResolvedWebSearchConfig } from "./config";
+import { detectWebSearchProvider, supportsWebSearch, webSearchToolSpec } from "./provider";
+import type { WebSearchCitation, WebSearchRequest, WebSearchResult } from "./schema";
+import { runScrapeSearch } from "./scrape";
+
+type WorkspaceClientLike = serving.WorkspaceClientLike;
+const logger = log.logger("web-search/search");
+const { resolveModel } = resolve;
+const { listServingEndpoints } = serving;
+
+/** Context a search needs from the caller: the OBO client + workspace host. */
+export interface WebSearchContext {
+  client: WorkspaceClientLike;
+  host: string;
+}
+
+/**
+ * Resolve a web-search-capable model against the LIVE workspace catalogue - so
+ * we never return an endpoint id that isn't actually deployed (the "endpoint
+ * does not exist" failure a hardcoded fallback id would cause). Reuses
+ * `@dbx-tools/model`'s existing catalogue + resolver rather than a custom
+ * lookup: {@link listServingEndpoints} lists the endpoints (cached), and we
+ * restrict the candidate set to the {@link supportsWebSearch} ones before
+ * {@link resolveModel} fuzzy-picks within it.
+ *
+ * Returns the chosen endpoint id, or `null` when the workspace has no
+ * web-search-capable model deployed (the caller then uses the scrape
+ * fallback). An explicit request that resolves to an unsupported / absent
+ * model throws, so a deliberate bad pin surfaces rather than silently
+ * degrading.
+ */
+async function resolveWebSearchModel(
+  ctx: WebSearchContext,
+  config: ResolvedWebSearchConfig,
+  requested: string | undefined,
+): Promise<string | null> {
+  const endpoints = await listServingEndpoints(ctx.client, ctx.host);
+  // Only deployed, web-search-capable endpoints are candidates.
+  const capable = endpoints.filter((e) => supportsWebSearch(e.name));
+  const pinned = requested ?? config.model;
+
+  if (pinned) {
+    // Resolve the explicit ask within the capable set only.
+    const { modelId } = resolveModel(capable, {
+      explicit: pinned,
+      fuzzy: config.fuzzy,
+      threshold: config.fuzzyThreshold,
+    });
+    // resolveModel returns the input verbatim on no match; require it to be a
+    // real capable endpoint so a bad pin is a clear error, not a phantom call.
+    if (!capable.some((e) => e.name === modelId) || !supportsWebSearch(modelId)) {
+      throw new Error(
+        `web-search: requested model "${pinned}" is not a deployed web-search-capable endpoint. ` +
+          `Deployed GPT/Gemini endpoints: [${capable.map((e) => e.name).join(", ") || "none"}].`,
+      );
+    }
+    return modelId;
+  }
+
+  if (capable.length === 0) return null;
+
+  // Nothing pinned: prefer the configured fallback order (Gemini, then GPT)
+  // when those ids are actually deployed; else take the best capable endpoint.
+  const { modelId } = resolveModel(capable, {
+    fallbacks: config.modelFallbacks,
+    fuzzy: config.fuzzy,
+    threshold: config.fuzzyThreshold,
+  });
+  return capable.some((e) => e.name === modelId) ? modelId : (capable[0]?.name ?? null);
+}
+
+/** POST a serving request through the OBO client and return the parsed JSON. */
+async function postServing(
+  ctx: WebSearchContext,
+  path: string,
+  body: unknown,
+): Promise<Record<string, unknown>> {
+  const res = await ctx.client.apiClient.request({
+    path,
+    method: "POST",
+    headers: new Headers({ Accept: "application/json", "Content-Type": "application/json" }),
+    raw: false,
+    payload: body,
+  });
+  return (res ?? {}) as Record<string, unknown>;
+}
+
+/* --------------------------- response extraction --------------------------- */
+
+/** Coerce an unknown to a trimmed string, or "" . */
+function str(v: unknown): string {
+  return typeof v === "string" ? v.trim() : "";
+}
+
+/**
+ * Extract answer text + citations from an OpenAI Responses API payload. The
+ * Responses API returns an `output` array of items; message items carry
+ * `content` parts with `text` and optional `annotations` (url_citation).
+ * `output_text` is the convenience aggregate when present.
+ */
+function fromResponsesPayload(payload: Record<string, unknown>): {
+  answer: string;
+  citations: WebSearchCitation[];
+} {
+  const citations: WebSearchCitation[] = [];
+  const texts: string[] = [];
+  const output = Array.isArray(payload["output"]) ? (payload["output"] as unknown[]) : [];
+  for (const item of output) {
+    const content = (item as { content?: unknown }).content;
+    if (!Array.isArray(content)) continue;
+    for (const part of content) {
+      const p = part as { text?: unknown; annotations?: unknown };
+      const text = str(p.text);
+      if (text) texts.push(text);
+      if (Array.isArray(p.annotations)) {
+        for (const ann of p.annotations) {
+          const a = ann as { url?: unknown; title?: unknown };
+          const url = str(a.url);
+          if (url) citations.push({ url, ...(str(a.title) ? { title: str(a.title) } : {}) });
+        }
+      }
+    }
+  }
+  const answer = str(payload["output_text"]) || texts.join("\n").trim();
+  return { answer, citations };
+}
+
+/**
+ * Extract answer text + citations from a Chat Completions payload (Gemini via
+ * `google_search`). The answer is `choices[0].message.content`; grounding
+ * sources, when present, surface under `choices[0].message` grounding
+ * metadata (best-effort - shapes vary, so we scan for url-bearing entries).
+ */
+function fromChatPayload(payload: Record<string, unknown>): {
+  answer: string;
+  citations: WebSearchCitation[];
+} {
+  const choices = Array.isArray(payload["choices"]) ? (payload["choices"] as unknown[]) : [];
+  const message = (choices[0] as { message?: Record<string, unknown> })?.message ?? {};
+  const answer = str(message["content"]);
+  const citations: WebSearchCitation[] = [];
+  // Best-effort grounding extraction: walk any nested object for {uri|url,title}.
+  const seen = new Set<string>();
+  const visit = (v: unknown, depth: number): void => {
+    if (depth > 6 || v === null || typeof v !== "object") return;
+    const o = v as Record<string, unknown>;
+    const url = str(o["url"]) || str(o["uri"]);
+    if (url && !seen.has(url)) {
+      seen.add(url);
+      citations.push({ url, ...(str(o["title"]) ? { title: str(o["title"]) } : {}) });
+    }
+    for (const val of Object.values(o)) {
+      if (Array.isArray(val)) val.forEach((x) => visit(x, depth + 1));
+      else if (val && typeof val === "object") visit(val, depth + 1);
+    }
+  };
+  visit(message["grounding_metadata"] ?? message["groundingMetadata"], 0);
+  return { answer, citations };
+}
+
+/**
+ * Run a web search. Prefers the Databricks native web-search tool on a
+ * deployed GPT/Gemini endpoint (synthesized answer + citations); when the
+ * workspace has no such endpoint AND the scrape fallback is enabled, falls
+ * back to a DuckDuckGo scrape so the tool still returns results instead of
+ * erroring. Citations are filtered through the configured URL allow-list.
+ */
+export async function runWebSearch(
+  request: WebSearchRequest,
+  config: ResolvedWebSearchConfig,
+  ctx: WebSearchContext,
+): Promise<WebSearchResult> {
+  const modelId = await resolveWebSearchModel(ctx, config, request.model);
+
+  if (modelId === null) {
+    // No native web-search model deployed in this workspace.
+    if (config.scrapeFallback) {
+      logger.info("no-native-model:scrape-fallback", { query: request.query });
+      return runScrapeSearch(request, config);
+    }
+    throw new Error(
+      "web-search: no web-search-capable model (GPT/Gemini) is deployed in this workspace, " +
+        "and the scrape fallback is disabled. Deploy a supported endpoint, set `model` / " +
+        "WEB_SEARCH_MODEL, or enable the fallback (WEB_SEARCH_SCRAPE_FALLBACK=1).",
+    );
+  }
+
+  const provider = detectWebSearchProvider(modelId)!; // guaranteed by resolve step
+  const spec = webSearchToolSpec(provider, config.webSearchTools);
+
+  const path =
+    spec.api === "responses"
+      ? "/serving-endpoints/responses"
+      : "/serving-endpoints/chat/completions";
+  const body =
+    spec.api === "responses"
+      ? {
+          model: modelId,
+          input: [{ role: "user", content: request.query }],
+          tools: [spec.tool],
+        }
+      : {
+          model: modelId,
+          messages: [{ role: "user", content: request.query }],
+          tools: [spec.tool],
+        };
+
+  let payload: Record<string, unknown>;
+  try {
+    payload = await postServing(ctx, path, body);
+  } catch (err) {
+    logger.warn("serving-error", { model: modelId, provider, error: error.errorMessage(err) });
+    throw err;
+  }
+
+  const { answer, citations } =
+    spec.api === "responses" ? fromResponsesPayload(payload) : fromChatPayload(payload);
+
+  const permitted = citations.filter((c) => config.allowList.allows(c.url));
+  const dropped = citations.length - permitted.length;
+  const trimmed = permitted.slice(0, config.maxCitations);
+  logger.debug("searched", {
+    query: request.query,
+    model: modelId,
+    provider,
+    citations: citations.length,
+    ...(dropped > 0 ? { filtered: dropped } : {}),
+    returned: trimmed.length,
+  });
+
+  return { query: request.query, answer, citations: trimmed, model: modelId };
+}

package/src/tool.ts

@@ -0,0 +1,144 @@
+/**
+ * The `web_search` and `web_fetch` Mastra tools.
+ *
+ * `web_search` is backed by the Databricks Model Serving native web-search
+ * tool: it resolves its own web-search-capable model (see `search.ts`) and
+ * calls the workspace serving endpoint under the caller's OBO scope, so the
+ * search runs as the requesting user and independently of the agent's chat
+ * model. `web_fetch` reads a page via got-scraping.
+ *
+ * Both are read-only and run without approval by default; each accepts an
+ * optional {@link ApprovalGate} (`approval`) that maps onto Mastra's
+ * `requireApproval`. `true` gates every call; a URL-pattern (or {@link OneOrMany}
+ * list) gates only calls whose URL matches - for `web_fetch` that is evaluated
+ * against the target URL, while `web_search` (whose result URLs aren't known
+ * before the call) treats a pattern gate as "always gate". `approval` falls
+ * back to the plugin's `approval` config when a tool omits its own.
+ *
+ * @module
+ */
+
+import { getExecutionContext } from "@databricks/appkit";
+import { string } from "@dbx-tools/shared-core";
+import { createTool } from "@mastra/core/tools";
+import { approvalMatches, type ApprovalGate } from "./config";
+import { runWebFetch } from "./fetch";
+import { getWebSearchRuntime } from "./runtime";
+import {
+  webFetchRequestSchema,
+  webFetchResultSchema,
+  webSearchRequestSchema,
+  webSearchResultSchema,
+  type WebFetchRequest,
+  type WebSearchRequest,
+} from "./schema";
+import { runWebSearch, type WebSearchContext } from "./search";
+
+/** Options shared by both web tools. */
+export interface WebSearchToolOptions {
+  /** Override the tool id. */
+  id?: string;
+  /**
+   * Approval gate for this tool, overriding the plugin's `approval`. `true`
+   * gates every call; a URL-pattern (or list) gates only matching calls;
+   * omit / `false` for no approval. See {@link ApprovalGate}.
+   */
+  approval?: ApprovalGate;
+}
+
+/** Resolve the effective gate: explicit tool option, else the plugin default. */
+function effectiveGate(opts: WebSearchToolOptions): ApprovalGate {
+  return opts.approval ?? getWebSearchRuntime().config.approval;
+}
+
+/**
+ * Resolve the OBO workspace client + host from the active AppKit execution
+ * context. Runs inside `agent.stream`'s `asUser(req)` scope, so the search
+ * hits the serving endpoint as the requesting user; outside a user context it
+ * falls back to the service principal.
+ */
+async function webSearchContext(): Promise<WebSearchContext> {
+  const ctx = getExecutionContext();
+  const host = (await ctx.client.config.getHost()).toString();
+  return { client: ctx.client, host };
+}
+
+/**
+ * Build the `web_search` tool. Spread it into the agents that should be able
+ * to search the web.
+ *
+ * @example
+ * ```ts
+ * import { webSearchTool } from "@dbx-tools/appkit-web-search";
+ * import { createAgent } from "@dbx-tools/appkit-mastra";
+ *
+ * const researcher = createAgent({
+ *   instructions: "...",
+ *   tools: () => ({ web_search: webSearchTool() }),
+ * });
+ * ```
+ */
+export function webSearchTool(opts: WebSearchToolOptions = {}) {
+  const gate = effectiveGate(opts);
+  return createTool({
+    id: opts.id ?? "web_search",
+    description: string.toDescription(`
+      Search the web for current information and get an answer synthesized from
+      live results, with the sources it used. Pass a natural-language query;
+      the search runs inside a web-search-capable model (chosen independently
+      of your own model). Optionally pass a model name to use a specific
+      web-search model. Use it whenever a question needs up-to-date or external
+      information you don't already have.
+    `),
+    inputSchema: webSearchRequestSchema,
+    outputSchema: webSearchResultSchema,
+    // A search's result URLs aren't known before the call, so a pattern gate
+    // is treated as "always gate"; boolean gates pass through.
+    ...(gate === false || gate === undefined
+      ? {}
+      : { requireApproval: () => (typeof gate === "boolean" ? gate : true) }),
+    execute: async (input) => {
+      const { config } = getWebSearchRuntime();
+      return runWebSearch(input as WebSearchRequest, config, await webSearchContext());
+    },
+  });
+}
+
+/**
+ * Build the `web_fetch` tool. Spread it into the agents that should be able
+ * to read a page's contents.
+ *
+ * @example
+ * ```ts
+ * import { webFetchTool } from "@dbx-tools/appkit-web-search";
+ *
+ * tools: () => ({ web_fetch: webFetchTool({ approval: "*.internal.example.com" }) })
+ * ```
+ */
+export function webFetchTool(opts: WebSearchToolOptions = {}) {
+  const gate = effectiveGate(opts);
+  return createTool({
+    id: opts.id ?? "web_fetch",
+    description: string.toDescription(`
+      Fetch a single web page and return its readable contents. Pass an
+      absolute URL (including https://); set format to "html" for raw markup
+      instead of extracted text. Use it to read a page returned by web_search
+      or provided by the user. Content is length-capped; fetching a URL outside
+      the configured allow-list is refused.
+    `),
+    inputSchema: webFetchRequestSchema,
+    outputSchema: webFetchResultSchema,
+    // A fetch knows its single target URL, so a pattern gate is evaluated
+    // precisely against it; boolean gates pass through.
+    ...(gate === false || gate === undefined
+      ? {}
+      : {
+          requireApproval: (input: unknown) =>
+            approvalMatches(gate, [(input as WebFetchRequest).url]),
+        }),
+    execute: async (input) => {
+      const { config } = getWebSearchRuntime();
+      return runWebFetch(input as WebFetchRequest, config);
+    },
+  });
+}

package/tsconfig.json

@@ -0,0 +1,41 @@
+// ~~ Generated by projen. To modify, edit .projenrc.js and run "pnpm exec projen".
+{
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib",
+    "alwaysStrict": true,
+    "declaration": true,
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "inlineSourceMap": true,
+    "inlineSources": true,
+    "lib": [
+      "ES2022"
+    ],
+    "module": "ESNext",
+    "noEmitOnError": false,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitAny": true,
+    "noImplicitReturns": true,
+    "noImplicitThis": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "resolveJsonModule": true,
+    "strict": true,
+    "strictNullChecks": true,
+    "strictPropertyInitialization": true,
+    "stripInternal": true,
+    "target": "ES2022",
+    "types": [
+      "node"
+    ],
+    "moduleResolution": "bundler",
+    "skipLibCheck": true
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}