@rahularya01/pi-essentials 0.1.0

package/src/web/http.ts

@@ -0,0 +1,238 @@
+import http from "node:http";
+import https from "node:https";
+import type { LookupAddress } from "node:dns";
+import type { Readable } from "node:stream";
+import zlib from "node:zlib";
+import { timeoutSignal } from "../security/env.ts";
+import { redirectUrl, resolveSafeUrl, SsrfError, type PinnedAddress, type SsrfPolicy } from "../security/ssrf.ts";
+
+const MAX_REDIRECTS = 5;
+const USER_AGENT = "pi-essentials/0.1 (+https://github.com/rahularya/pi-essentials)";
+
+/** Statuses after which a POST must be replayed as a GET. */
+const SEE_OTHER = new Set([301, 302, 303]);
+
+/** Compressed bytes we are willing to read for a given decompressed budget. */
+const COMPRESSION_RATIO_GUARD = 20;
+
+export interface SafeFetchOptions {
+  timeoutMs: number;
+  maxBytes: number;
+  signal?: AbortSignal;
+  headers?: Record<string, string>;
+  method?: "GET" | "POST";
+  body?: string;
+  /** Hosts the user has explicitly allowed even though they are private. */
+  allowedHosts?: ReadonlySet<string>;
+}
+
+export interface SafeFetchResult {
+  url: string;
+  status: number;
+  contentType: string;
+  charset: string;
+  body: Uint8Array;
+  truncated: boolean;
+  text(): string;
+}
+
+export function charsetFromContentType(contentType: string): string {
+  const match = /charset\s*=\s*"?([\w.:+-]+)"?/i.exec(contentType);
+  return match ? match[1].toLowerCase() : "utf-8";
+}
+
+/** Decode bytes with the declared charset, falling back to UTF-8 for unknown labels. */
+export function decodeBody(body: Uint8Array, charset: string): string {
+  try {
+    return new TextDecoder(charset, { fatal: false }).decode(body);
+  } catch {
+    return new TextDecoder("utf-8", { fatal: false }).decode(body);
+  }
+}
+
+/**
+ * A DNS resolver that only ever answers with addresses this request already
+ * validated. Node re-resolves the hostname when it connects, which would
+ * otherwise let a hostile server return a public IP to the safety check and a
+ * private one to the socket (DNS rebinding).
+ */
+export function pinnedLookup(addresses: PinnedAddress[]): NonNullable<http.RequestOptions["lookup"]> {
+  return ((
+    _hostname: string,
+    options: { all?: boolean },
+    callback: (
+      err: NodeJS.ErrnoException | null,
+      address: string | LookupAddress[],
+      family?: number,
+    ) => void,
+  ) => {
+    if (addresses.length === 0) {
+      callback(Object.assign(new Error("No validated addresses for host"), { code: "ENOTFOUND" }), "", 0);
+      return;
+    }
+    if (options?.all) {
+      callback(null, addresses.map((entry) => ({ address: entry.address, family: entry.family })));
+      return;
+    }
+    callback(null, addresses[0].address, addresses[0].family);
+  }) as NonNullable<http.RequestOptions["lookup"]>;
+}
+
+interface RawResponse {
+  status: number;
+  headers: http.IncomingHttpHeaders;
+  stream: http.IncomingMessage;
+}
+
+function sendRequest(
+  url: URL,
+  addresses: PinnedAddress[],
+  options: SafeFetchOptions,
+  method: string,
+  body: string | undefined,
+  signal: AbortSignal,
+): Promise<RawResponse> {
+  const transport = url.protocol === "https:" ? https : http;
+  const headers: Record<string, string> = {
+    "user-agent": USER_AGENT,
+    accept: "text/html,application/xhtml+xml,application/json,text/plain;q=0.9,*/*;q=0.8",
+    "accept-encoding": "gzip, br",
+    ...options.headers,
+  };
+  if (body !== undefined) {
+    headers["content-length"] = String(Buffer.byteLength(body, "utf8"));
+    headers["content-type"] ??= "application/x-www-form-urlencoded";
+  }
+
+  return new Promise<RawResponse>((resolve, reject) => {
+    const request = transport.request(
+      url,
+      {
+        method,
+        headers,
+        // TLS still verifies the certificate against the real hostname: `servername`
+        // defaults to the URL host, and only address resolution is pinned.
+        lookup: pinnedLookup(addresses),
+        signal,
+      },
+      (response) => resolve({ status: response.statusCode ?? 0, headers: response.headers, stream: response }),
+    );
+    request.on("error", reject);
+    if (body !== undefined) request.write(body);
+    request.end();
+  });
+}
+
+function decompress(response: http.IncomingMessage): Readable {
+  const encoding = String(response.headers["content-encoding"] ?? "").trim().toLowerCase();
+  if (!encoding || encoding === "identity") return response;
+  if (encoding === "gzip" || encoding === "x-gzip") return response.pipe(zlib.createGunzip());
+  if (encoding === "br") return response.pipe(zlib.createBrotliDecompress());
+  if (encoding === "deflate") return response.pipe(zlib.createUnzip());
+  // We only advertise gzip and br, so anything else is the server misbehaving.
+  response.destroy();
+  throw new Error(`Unsupported content-encoding "${encoding}"`);
+}
+
+async function readLimited(
+  response: http.IncomingMessage,
+  maxBytes: number,
+): Promise<{ body: Uint8Array; truncated: boolean }> {
+  const stream = decompress(response);
+  const chunks: Buffer[] = [];
+  let kept = 0;
+  let truncated = false;
+
+  if (stream !== response) {
+    // Only meaningful while decompressing: cap the compressed input so a
+    // decompression bomb cannot expand into unbounded memory. When the body is
+    // identity-encoded the decompressed cap below already bounds the read, and
+    // attaching a "data" listener there would race the async iteration.
+    const compressedCap = maxBytes * COMPRESSION_RATIO_GUARD;
+    let rawSeen = 0;
+    response.on("data", (chunk: Buffer) => {
+      rawSeen += chunk.byteLength;
+      if (rawSeen > compressedCap) {
+        truncated = true;
+        response.destroy();
+      }
+    });
+  }
+
+  try {
+    for await (const chunk of stream as AsyncIterable<Buffer>) {
+      const room = maxBytes - kept;
+      if (room === 0) {
+        truncated = true;
+        break;
+      }
+      if (chunk.byteLength > room) {
+        chunks.push(chunk.subarray(0, room));
+        kept += room;
+        truncated = true;
+        break;
+      }
+      chunks.push(chunk);
+      kept += chunk.byteLength;
+    }
+  } catch (error) {
+    // A destroyed stream is how we stop early; only surface real read failures.
+    if (!truncated) throw error;
+  } finally {
+    response.destroy();
+  }
+
+  return { body: new Uint8Array(Buffer.concat(chunks, kept)), truncated };
+}
+
+export async function safeFetch(rawUrl: string, options: SafeFetchOptions): Promise<SafeFetchResult> {
+  const policy: SsrfPolicy = { allowedHosts: options.allowedHosts };
+  let target = await resolveSafeUrl(rawUrl, policy);
+  const signal = timeoutSignal(options.timeoutMs, options.signal);
+  let method: string = options.method ?? "GET";
+  let body = options.body;
+
+  for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+    const response = await sendRequest(target.url, target.addresses, options, method, body, signal);
+
+    if (response.status >= 300 && response.status < 400) {
+      const location = response.headers.location;
+      response.stream.resume();
+      response.stream.destroy();
+      if (!location) throw new Error(`Redirect from ${target.url.href} was missing a Location header.`);
+      // Every hop is validated and pinned again; a redirect cannot smuggle us
+      // onto a private address.
+      target = await resolveSafeUrl(redirectUrl(target.url, location).href, policy);
+      if (method === "POST" && SEE_OTHER.has(response.status)) {
+        method = "GET";
+        body = undefined;
+      }
+      continue;
+    }
+
+    const contentType = String(response.headers["content-type"] ?? "");
+    const charset = charsetFromContentType(contentType);
+
+    if (response.status < 200 || response.status >= 300) {
+      const snippet = await readLimited(response.stream, Math.min(options.maxBytes, 2048)).catch(() => ({
+        body: new Uint8Array(),
+        truncated: false,
+      }));
+      const preview = decodeBody(snippet.body, charset).replace(/\s+/g, " ").trim().slice(0, 400);
+      throw new Error(`HTTP ${response.status} fetching ${target.url.href}${preview ? `: ${preview}` : ""}`);
+    }
+
+    const read = await readLimited(response.stream, options.maxBytes);
+    return {
+      url: target.url.href,
+      status: response.status,
+      contentType,
+      charset,
+      body: read.body,
+      truncated: read.truncated,
+      text: () => decodeBody(read.body, charset),
+    };
+  }
+
+  throw new SsrfError(`Too many redirects fetching ${rawUrl}`, "invalid-url");
+}

package/src/web/index.ts

@@ -0,0 +1,214 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import type { ResolvedConfig } from "../config.ts";
+import { errorMessage, PiEssentialsError, toolFailure, toolText } from "../errors.ts";
+import { MAX_SEARCH_RESULTS } from "../security/limits.ts";
+import { SsrfError } from "../security/ssrf.ts";
+import { ActivityLog, activityWidget, fetchDetail, searchDetail } from "./activity.ts";
+import { formatPage, fetchPage, readCached } from "./fetch.ts";
+import { renderFetchCall, renderFetchResult, renderSearchCall, renderSearchResult } from "./render.ts";
+import { formatSearch, runSearch } from "./search.ts";
+
+function describeError(error: unknown): string {
+  if (error instanceof SsrfError) return `${error.message} (blocked for safety)`;
+  if (error instanceof PiEssentialsError) return error.message;
+  return errorMessage(error);
+}
+
+function optionalInteger(
+  value: number | undefined,
+  name: string,
+  minimum: number,
+  maximum = Number.MAX_SAFE_INTEGER,
+): number | undefined {
+  if (value === undefined) return undefined;
+  if (!Number.isInteger(value) || value < minimum || value > maximum) {
+    toolFailure(`${name} must be an integer from ${minimum} to ${maximum}.`, "WEB_BAD_ARGS");
+  }
+  return value;
+}
+
+export function resolveSearchCount(
+  params: { numResults?: number; limit?: number; num_search_results?: number },
+  fallback: number,
+): number {
+  const requested = params.numResults ?? params.limit ?? params.num_search_results ?? fallback;
+  return optionalInteger(requested, "result count", 1, MAX_SEARCH_RESULTS) as number;
+}
+
+/** Rows the activity panel shows before it summarizes the rest. */
+const ACTIVITY_ROWS = 6;
+
+export function registerWeb(pi: ExtensionAPI, config: ResolvedConfig): void {
+  const searchCfg = config.web.search;
+  const fetchCfg = config.web.fetch;
+  const allowedHosts = config.web.allowedHosts;
+  const activity = new ActivityLog();
+  let panelVisible = false;
+  let collapsed = false;
+
+  const renderActivity = (ctx: ExtensionContext) => {
+    if (!ctx.hasUI) return;
+    if (!panelVisible || activity.size === 0) {
+      ctx.ui.setWidget("pi-essentials-web", undefined);
+      return;
+    }
+    ctx.ui.setWidget(
+      "pi-essentials-web",
+      (_tui, theme) =>
+        new Text(activityWidget(theme, activity, { collapsed, maxRows: ACTIVITY_ROWS }).join("\n"), 0, 0),
+      { placement: "belowEditor" },
+    );
+  };
+
+  // Off by default so the panel never competes with the transcript; the
+  // shortcut brings it up when a search or fetch needs explaining.
+  pi.registerShortcut("ctrl+shift+w", {
+    description: "Show or hide the pi-essentials web activity panel",
+    handler: async (ctx) => {
+      if (!panelVisible) {
+        panelVisible = true;
+        collapsed = false;
+      } else if (!collapsed) {
+        collapsed = true;
+      } else {
+        panelVisible = false;
+        collapsed = false;
+      }
+      renderActivity(ctx);
+      if (!panelVisible) ctx.ui.notify("Web activity panel hidden", "info");
+    },
+  });
+
+  pi.registerCommand("web", {
+    description: "Show recent web_search and web_fetch activity. Usage: /web [clear]",
+    handler: async (args, ctx) => {
+      if (args.trim().toLowerCase() === "clear") {
+        activity.clear();
+        renderActivity(ctx);
+        ctx.ui.notify("Cleared web activity.", "info");
+        return;
+      }
+      if (activity.size === 0) {
+        ctx.ui.notify("No web activity yet this session.", "info");
+        return;
+      }
+      panelVisible = true;
+      collapsed = false;
+      renderActivity(ctx);
+      const rows = activity
+        .recent(activity.size)
+        .map(
+          (entry) =>
+            `${entry.ok ? "✓" : "✗"} ${entry.kind === "search" ? "SEARCH" : "FETCH "} ${entry.subject} — ${entry.detail ?? ""} (${Math.round(entry.ms)}ms)`,
+        );
+      ctx.ui.notify(rows.join("\n"), "info");
+    },
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    activity.clear();
+    panelVisible = false;
+    collapsed = false;
+    renderActivity(ctx);
+  });
+
+  pi.registerTool({
+    name: "web_search",
+    label: "Web Search",
+    description:
+      "Search the web and return titles, URLs, and snippets. Then fetch promising URLs with web_fetch.",
+    promptSnippet: "Search the public web and return cited snippets",
+    promptGuidelines: [
+      "Use web_search for current or external information, then web_fetch for pages you actually need to read.",
+      "Do not dump search HTML; prefer the returned title/url/snippet list.",
+    ],
+    parameters: Type.Object({
+      query: Type.String({ description: "Search query" }),
+      numResults: Type.Optional(
+        Type.Integer({ minimum: 1, maximum: MAX_SEARCH_RESULTS, description: `Results to return (1-${MAX_SEARCH_RESULTS})` }),
+      ),
+      limit: Type.Optional(
+        Type.Integer({ minimum: 1, maximum: MAX_SEARCH_RESULTS, description: "Alias for numResults" }),
+      ),
+      num_search_results: Type.Optional(
+        Type.Integer({ minimum: 1, maximum: MAX_SEARCH_RESULTS, description: "Alias for numResults" }),
+      ),
+    }),
+    async execute(_id, params, signal, onUpdate, ctx) {
+      const query = params.query?.trim();
+      if (!query) toolFailure("query is required.", "WEB_BAD_ARGS");
+
+      const count = resolveSearchCount(params, searchCfg.maxResults);
+
+      onUpdate?.(toolText(`Searching for "${query}"...`));
+      try {
+        const result = await activity.track(
+          "search",
+          query,
+          () => runSearch(query, searchCfg, "auto", count, signal, allowedHosts),
+          searchDetail,
+        );
+        renderActivity(ctx);
+        return toolText(formatSearch(result), { hits: result.hits, query });
+      } catch (error) {
+        renderActivity(ctx);
+        toolFailure(
+          describeError(error),
+          error instanceof PiEssentialsError ? error.code : "WEB_SEARCH_FAILED",
+        );
+      }
+    },
+    renderCall: renderSearchCall,
+    renderResult: renderSearchResult,
+  });
+
+  pi.registerTool({
+    name: "web_fetch",
+    label: "Web Fetch",
+    description:
+      "Fetch a URL and return readable markdown. Large pages are truncated; pass cacheId with offset/limit to read more. Does not execute page JavaScript.",
+    promptSnippet: "Fetch a webpage as readable markdown",
+    promptGuidelines: [
+      "Use web_fetch to read a specific URL after web_search, instead of dumping raw HTML.",
+      "If the result is truncated, call web_fetch again with the returned cacheId and an offset.",
+    ],
+    parameters: Type.Object({
+      url: Type.Optional(Type.String({ description: "http(s) URL to fetch" })),
+      cacheId: Type.Optional(Type.String({ description: "Previously returned cache id" })),
+      offset: Type.Optional(Type.Integer({ minimum: 0, description: "Character offset into the page text" })),
+      limit: Type.Optional(Type.Integer({ minimum: 1, description: "Maximum characters to return" })),
+    }),
+    async execute(_id, params, signal, onUpdate, ctx) {
+      const offset = optionalInteger(params.offset, "offset", 0);
+      const limit = optionalInteger(params.limit, "limit", 1);
+      const cacheId = params.cacheId?.trim();
+      const url = params.url?.trim();
+      if ((!cacheId && !url) || (cacheId && url)) {
+        toolFailure("Provide exactly one of url or cacheId.", "WEB_BAD_ARGS");
+      }
+
+      try {
+        if (cacheId) {
+          const cached = readCached(cacheId, offset, limit, fetchCfg.maxChars);
+          return toolText(formatPage(cached), cached);
+        }
+        onUpdate?.(toolText(`Fetching ${url}...`));
+        const page = await activity.track(
+          "fetch",
+          url as string,
+          () => fetchPage(url as string, fetchCfg, signal, { offset, limit }, allowedHosts),
+          fetchDetail,
+        );
+        renderActivity(ctx);
+        return toolText(formatPage(page), page);
+      } catch (error) {
+        renderActivity(ctx);
+        toolFailure(describeError(error), error instanceof PiEssentialsError ? error.code : "WEB_FETCH_FAILED");
+      }
+    },
+    renderCall: renderFetchCall,
+    renderResult: renderFetchResult,
+  });
+}

package/src/web/providers/brave.ts

@@ -0,0 +1,27 @@
+import { safeFetch } from "../http.ts";
+import { parseJson, SEARCH_MAX_BYTES, toHits, type SearchFn } from "./types.ts";
+
+export function searchBrave(apiKey: string): SearchFn {
+  return async ({ query, count, timeoutMs, signal, allowedHosts }) => {
+    const url = `https://api.search.brave.com/res/v1/web/search?q=${encodeURIComponent(query)}&count=${count}`;
+    const response = await safeFetch(url, {
+      timeoutMs,
+      maxBytes: SEARCH_MAX_BYTES,
+      signal,
+      allowedHosts,
+      headers: {
+        accept: "application/json",
+        "X-Subscription-Token": apiKey,
+      },
+    });
+    const json = parseJson<{
+      web?: { results?: Array<{ title?: string; url?: string; description?: string }> };
+    }>(response.text(), "Brave");
+    const hits = toHits(
+      (json.web?.results ?? []).map((r) => ({ title: r.title, url: r.url, snippet: r.description })),
+      count,
+      "brave",
+    );
+    return { provider: "brave", query, hits };
+  };
+}

package/src/web/providers/duckduckgo.ts

@@ -0,0 +1,60 @@
+import { parseHTML } from "linkedom";
+import { safeFetch } from "../http.ts";
+import { cleanSnippet, SEARCH_MAX_BYTES, toHits, type SearchFn } from "./types.ts";
+
+/** DuckDuckGo wraps outbound links in /l/?uddg=<encoded>. Unwrap them. */
+export function decodeDdgUrl(href: string): string {
+  try {
+    const url = new URL(href, "https://html.duckduckgo.com");
+    const uddg = url.searchParams.get("uddg");
+    return uddg ?? url.href;
+  } catch {
+    return href;
+  }
+}
+
+const RESULT_SELECTOR = ".result, .web-result, .links_main";
+const AD_SELECTOR = ".result--ad, .results--ads, .badge--ad";
+
+export const searchDuckDuckGo: SearchFn = async ({ query, count, timeoutMs, signal, allowedHosts }) => {
+  const target = `https://html.duckduckgo.com/html/?q=${encodeURIComponent(query)}`;
+  const response = await safeFetch(target, {
+    timeoutMs,
+    maxBytes: SEARCH_MAX_BYTES,
+    signal,
+    allowedHosts,
+    headers: { accept: "text/html" },
+  });
+  const { document } = parseHTML(response.text());
+
+  const rows: Array<{ title: string; url: string; snippet: string }> = [];
+  for (const node of Array.from(document.querySelectorAll(RESULT_SELECTOR))) {
+    const el = node as Element;
+    if (el.matches?.(AD_SELECTOR) || el.querySelector(AD_SELECTOR)) continue;
+    // Prefer the real result anchor; `querySelector` with a list returns document
+    // order, not selector priority, so try each selector in turn.
+    const link =
+      el.querySelector("a.result__a") ??
+      el.querySelector("a.result-link") ??
+      el.querySelector("h2 a") ??
+      el.querySelector("a[href]");
+    const href = link?.getAttribute("href");
+    const title = cleanSnippet(link?.textContent ?? "");
+    if (!href || !title) continue;
+    const url = decodeDdgUrl(href);
+    if (!/^https?:\/\//i.test(url)) continue;
+    const snippet = cleanSnippet(
+      el.querySelector(".result__snippet")?.textContent ??
+        el.querySelector(".result-snippet")?.textContent ??
+        el.querySelector(".snippet")?.textContent ??
+        "",
+    );
+    rows.push({ title, url, snippet });
+  }
+
+  if (rows.length === 0) {
+    const blocked = /anomaly|unusual traffic|captcha/i.test(response.text().slice(0, 4000));
+    if (blocked) throw new Error("DuckDuckGo rejected the request (rate limited). Configure another search provider.");
+  }
+  return { provider: "duckduckgo", query, hits: toHits(rows, count, "duckduckgo") };
+};

package/src/web/providers/exa.ts

@@ -0,0 +1,29 @@
+import { safeFetch } from "../http.ts";
+import { parseJson, SEARCH_MAX_BYTES, toHits, type SearchFn } from "./types.ts";
+
+export function searchExa(apiKey: string): SearchFn {
+  return async ({ query, count, timeoutMs, signal, allowedHosts }) => {
+    const response = await safeFetch("https://api.exa.ai/search", {
+      timeoutMs,
+      maxBytes: SEARCH_MAX_BYTES,
+      signal,
+      allowedHosts,
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        accept: "application/json",
+        "x-api-key": apiKey,
+      },
+      body: JSON.stringify({ query, numResults: count, type: "auto", contents: { text: { maxCharacters: 400 } } }),
+    });
+    const json = parseJson<{
+      results?: Array<{ title?: string; url?: string; text?: string; snippet?: string }>;
+    }>(response.text(), "Exa");
+    const hits = toHits(
+      (json.results ?? []).map((r) => ({ title: r.title, url: r.url, snippet: r.snippet ?? r.text })),
+      count,
+      "exa",
+    );
+    return { provider: "exa", query, hits };
+  };
+}

package/src/web/providers/jina.ts

@@ -0,0 +1,25 @@
+import { safeFetch } from "../http.ts";
+import { parseJson, SEARCH_MAX_BYTES, toHits, type SearchFn } from "./types.ts";
+
+export function searchJina(apiKey?: string): SearchFn {
+  return async ({ query, count, timeoutMs, signal, allowedHosts }) => {
+    const headers: Record<string, string> = { accept: "application/json" };
+    if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
+    const response = await safeFetch(`https://s.jina.ai/?q=${encodeURIComponent(query)}`, {
+      timeoutMs,
+      maxBytes: SEARCH_MAX_BYTES,
+      signal,
+      allowedHosts,
+      headers,
+    });
+    const json = parseJson<{
+      data?: Array<{ title?: string; url?: string; description?: string; content?: string }>;
+    }>(response.text(), "Jina");
+    const hits = toHits(
+      (json.data ?? []).map((r) => ({ title: r.title, url: r.url, snippet: r.description ?? r.content })),
+      count,
+      "jina",
+    );
+    return { provider: "jina", query, hits };
+  };
+}

package/src/web/providers/searxng.ts

@@ -0,0 +1,29 @@
+import { safeFetch } from "../http.ts";
+import { parseJson, SEARCH_MAX_BYTES, toHits, type SearchFn } from "./types.ts";
+
+export function searchSearxng(baseUrl: string): SearchFn {
+  return async ({ query, count, timeoutMs, signal, allowedHosts }) => {
+    const url = new URL(baseUrl);
+    url.pathname = `${url.pathname.replace(/\/+$/, "")}/search`;
+    url.search = "";
+    url.hash = "";
+    url.searchParams.set("q", query);
+    url.searchParams.set("format", "json");
+    const response = await safeFetch(url.toString(), {
+      timeoutMs,
+      maxBytes: SEARCH_MAX_BYTES,
+      signal,
+      allowedHosts,
+      headers: { accept: "application/json" },
+    });
+    const json = parseJson<{
+      results?: Array<{ title?: string; url?: string; content?: string }>;
+    }>(response.text(), "SearXNG");
+    const hits = toHits(
+      (json.results ?? []).map((r) => ({ title: r.title, url: r.url, snippet: r.content })),
+      count,
+      "searxng",
+    );
+    return { provider: "searxng", query, hits };
+  };
+}

package/src/web/providers/tavily.ts

@@ -0,0 +1,31 @@
+import { safeFetch } from "../http.ts";
+import { parseJson, SEARCH_MAX_BYTES, toHits, type SearchFn } from "./types.ts";
+
+export function searchTavily(apiKey: string): SearchFn {
+  return async ({ query, count, timeoutMs, signal, allowedHosts }) => {
+    const response = await safeFetch("https://api.tavily.com/search", {
+      timeoutMs,
+      maxBytes: SEARCH_MAX_BYTES,
+      signal,
+      allowedHosts,
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        accept: "application/json",
+        Authorization: `Bearer ${apiKey}`,
+      },
+      // `api_key` is Tavily's legacy field and the Bearer header is the current
+      // form; sending both keeps old and new deployments working.
+      body: JSON.stringify({ api_key: apiKey, query, max_results: count, search_depth: "basic" }),
+    });
+    const json = parseJson<{
+      results?: Array<{ title?: string; url?: string; content?: string }>;
+    }>(response.text(), "Tavily");
+    const hits = toHits(
+      (json.results ?? []).map((r) => ({ title: r.title, url: r.url, snippet: r.content })),
+      count,
+      "tavily",
+    );
+    return { provider: "tavily", query, hits };
+  };
+}