@zeldrisho/pi-web-search 0.9.0 → 0.11.0

package/src/brave.ts

@@ -6,24 +6,15 @@ export { normalizeResultFilter, validateProviderRequest } from "./request-valida
 
 export type Provider = "brave";
 
-export type Freshness = "day" | "week" | "month" | "year";
-
 export type SafesearchMode = "off" | "moderate" | "strict";
 
-export type SearchMode = "web" | "context";
-
-/** Relevance threshold for the LLM context endpoint. */
-export type ContextThresholdMode = "strict" | "balanced" | "lenient" | "disabled";
+export type SearchMode = "web" | "answers";
 
-/** Token-budget preset for the LLM context endpoint (coding-oriented). */
-export type ContextDepth = "quick" | "standard" | "deep";
-
-/** Allowed Brave `result_filter` values. */
 export type ResultFilterValue = (typeof SEARCH_RESULT_FILTER_VALUES)[number];
 
 export type ResultQuality = "high" | "medium" | "low";
 
-/** Query metadata Brave echoes back (spellcheck, operators, pagination hints). */
+/** Neutral query metadata echoed by Brave, not a measure of correctness. */
 export interface BraveQueryMeta {
   altered?: string;
   cleaned?: string;
@@ -36,35 +27,19 @@ export interface BraveQueryMeta {
 }
 
 interface BraveQuery {
-  original?: string;
   altered?: string;
   cleaned?: string;
   spellcheck_off?: boolean;
   show_strict_warning?: boolean;
   more_results_available?: boolean;
-  search_operators?: {
-    applied?: boolean;
-    cleaned_query?: string;
-    sites?: string[];
-  };
+  search_operators?: { applied?: boolean; cleaned_query?: string; sites?: string[] };
 }
 
-/** Normalized provider response: results plus echoed query metadata. */
 export interface SearchResponse {
   results: SearchResult[];
   meta: BraveQueryMeta;
 }
 
-/**
- * Parses Brave's echoed `query` object into neutral evidence metadata.
- *
- * The response body is already decoded to the `BraveQuery` contract by
- * `requestJson` at the transport boundary, so this maps known fields without
- * re-narrowing their representation.
- *
- * @param query - The raw `query` object from a Brave response
- * @returns Normalized metadata; empty when Brave echoes nothing
- */
 export function parseQueryMeta(query: BraveQuery | undefined): BraveQueryMeta {
   if (!query) return {};
   const meta: BraveQueryMeta = {};
@@ -79,15 +54,15 @@ export function parseQueryMeta(query: BraveQuery | undefined): BraveQueryMeta {
 
   if (query.more_results_available !== undefined)
     meta.moreResultsAvailable = query.more_results_available;
-  const operators = query.search_operators;
 
-  if (operators) {
-    if (operators.applied !== undefined) meta.operatorsApplied = operators.applied;
+  if (query.search_operators?.applied !== undefined)
+    meta.operatorsApplied = query.search_operators.applied;
 
-    if (operators.cleaned_query) meta.cleanedQuery = operators.cleaned_query;
+  if (query.search_operators?.cleaned_query)
+    meta.cleanedQuery = query.search_operators.cleaned_query;
 
-    if (Array.isArray(operators.sites)) meta.operatorSites = [...operators.sites];
-  }
+  if (Array.isArray(query.search_operators?.sites))
+    meta.operatorSites = [...query.search_operators.sites];
 
   return meta;
 }
@@ -96,144 +71,50 @@ export interface SearchResult {
   title: string;
   url: string;
   snippet: string;
-  /** Honest-evidence hint about how useful the result is likely to be as a citation. */
+  /** Coarse source-content hint, not calibrated confidence or authority. */
   quality: ResultQuality;
 }
 
-interface BraveWebResult {
-  title?: string;
-  url?: string;
-  description?: string;
-  extra_snippets?: string[];
-}
-
 interface BraveWebResponse {
-  web?: { results?: BraveWebResult[] };
-}
-
-interface BraveSnippet {
-  caption?: string;
-  table?: Array<Record<string, string>>;
-}
-
-interface BraveContextResult {
-  title?: string;
-  url?: string;
-  snippets?: string[];
-}
-
-interface BraveContextResponse {
-  grounding?: { generic?: BraveContextResult[] };
+  web?: {
+    results?: Array<{
+      title?: string;
+      url?: string;
+      description?: string;
+      extra_snippets?: string[];
+    }>;
+  };
+  query?: BraveQuery;
 }
 
-/** Every search option Brave accepts across both modes; per-mode support is enforced by validation. */
 export interface ProviderRequestExtras {
   country?: string;
   safesearch?: SafesearchMode;
-  spellcheck?: boolean;
-  /** Single Goggle URL or inline definition (`$discard`, `$site=`, `boost=`). */
   goggles?: string;
   extraSnippets?: boolean;
   operators?: boolean;
-  /** Comma-separated `result_filter` values (e.g. `web,discussions,faq`). */
   resultFilter?: string;
   offset?: number;
   uiLang?: string;
-  /** Custom freshness range (`YYYY-MM-DDtoYYYY-MM-DD`); exclusive with `freshness`. */
   dateRange?: string;
-  threshold?: ContextThresholdMode;
-  depth?: ContextDepth;
 }
 
-/** Web-mode search options. */
-export interface WebSearchExtras {
-  country?: string;
-  safesearch?: SafesearchMode;
-  spellcheck?: boolean;
-  /** Single Goggle URL or inline definition (`$discard`, `$site=`, `boost=`). */
-  goggles?: string;
-  extraSnippets?: boolean;
-  operators?: boolean;
-  /** Comma-separated `result_filter` values (e.g. `web,discussions,faq`). */
-  resultFilter?: string;
-  offset?: number;
-  uiLang?: string;
-  /** Custom freshness range (`YYYY-MM-DDtoYYYY-MM-DD`); exclusive with `freshness`. */
-  dateRange?: string;
-}
+export type WebSearchExtras = ProviderRequestExtras;
 
-/** Context-mode search options. */
-export interface ContextSearchExtras {
-  country?: string;
-  safesearch?: SafesearchMode;
-  spellcheck?: boolean;
-  /** Single Goggle URL or inline definition (`$discard`, `$site=`, `boost=`). */
-  goggles?: string;
-  threshold?: ContextThresholdMode;
-  depth?: ContextDepth;
-}
-
-/**
- * Classifies a search result by how much usable, sourced information it carries.
- *
- * @param result - The result title and snippet to assess
- * @returns A coarse quality hint for weighting citations
- */
 export function classifyResultQuality(result: { title: string; snippet: string }): ResultQuality {
   if (!result.title && !result.snippet) return "low";
 
   if (result.snippet.length >= 80) return "high";
 
-  if (result.title || result.snippet) return "medium";
-
-  return "low";
-}
-
-const CONTEXT_DEPTH_BUDGETS = {
-  quick: { tokens: 2_048, snippets: 15, tokensPerUrl: 1_024, snippetsPerUrl: 3 },
-  standard: { tokens: 8_192, snippets: 30, tokensPerUrl: 2_048, snippetsPerUrl: 5 },
-  deep: { tokens: 16_384, snippets: 50, tokensPerUrl: 4_096, snippetsPerUrl: 8 },
-} satisfies Record<
-  ContextDepth,
-  { tokens: number; snippets: number; tokensPerUrl: number; snippetsPerUrl: number }
->;
-
-const BRAVE_MAX_EXTRA_SNIPPETS = 5;
-
-/**
- * Maps `freshness`/`dateRange` tool options to Brave's `freshness` parameter.
- *
- * @param freshness - The named recency bucket, if any
- * @param dateRange - The custom date range, if any (exclusive with `freshness`)
- * @returns The Brave `freshness` value
- * @throws If both options are set at once
- */
-export function mapFreshness(
-  freshness: Freshness | undefined,
-  dateRange: string | undefined,
-): string | undefined {
-  if (freshness && dateRange) {
-    throw new Error("Search freshness and dateRange are mutually exclusive; set only one.");
-  }
-
-  if (dateRange) return dateRange;
-
-  if (freshness) return { day: "pd", week: "pw", month: "pm", year: "py" }[freshness];
-
-  return undefined;
+  return "medium";
 }
 
-/**
- * Normalizes an HTTP or HTTPS URL and limits the result to 2,048 characters.
- *
- * @param value - The URL text to normalize
- * @returns The normalized URL, or an empty string for invalid values or unsupported protocols
- */
-function normalizeUrl(value: string): string {
+/** Only normalized HTTP(S) URLs are exposed as source links. */
+export function normalizeUrl(value: string): string {
   try {
     const url = new URL(value);
 
-    return url.protocol === "http:" || url.protocol === "https:"
+    return (url.protocol === "http:" || url.protocol === "https:") && !url.username && !url.password
       ? url.toString().slice(0, 2048)
       : "";
   } catch {
@@ -241,69 +122,10 @@ function normalizeUrl(value: string): string {
   }
 }
 
-function escapeMarkdownLinkText(value: string): string {
-  return value.replace(/([\\[\]])/g, "\\$1");
-}
-
-function escapeMarkdownCell(value: string): string {
-  return value.replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/\r?\n/g, "<br>");
-}
-
-/** Renders a structured Brave snippet as a bounded Markdown table when possible. */
-function structuredSnippetToMarkdown(value: BraveSnippet): string | undefined {
-  const table = value.table;
-
-  if (!table || table.length === 0) return undefined;
-
-  const rows = table.filter(Boolean);
-  const headers = [...new Set(rows.flatMap((row) => Object.keys(row)))];
-
-  if (headers.length === 0) return undefined;
-
-  const caption = value.caption ? `**${escapeMarkdownLinkText(value.caption)}**\n\n` : "";
-  const header = `| ${headers.map(escapeMarkdownCell).join(" | ")} |`;
-  const separator = `| ${headers.map(() => "---").join(" | ")} |`;
-
-  const body = rows
-    .map((row) => `| ${headers.map((key) => escapeMarkdownCell(String(row[key]))).join(" | ")} |`)
-    .join("\n");
-
-  return `${caption}${header}\n${separator}\n${body}`;
-}
-
-/** Converts a Brave structured snippet payload to bounded, display-safe Markdown. */
-function braveSnippetToMarkdown(value: string): string {
-  try {
-    const snippet = value.trim();
-
-    if (!snippet) return "";
-    const parsed: BraveSnippet = JSON.parse(snippet);
-    const rendered = structuredSnippetToMarkdown(parsed);
-
-    if (rendered !== undefined) return rendered.slice(0, 8000);
-
-    return `\`\`\`json\n${JSON.stringify(parsed)}\n\`\`\``.slice(0, 8000);
-  } catch {
-    return String(value)
-      .replace(/\r\n/g, "\n")
-      .replace(/\n{4,}/g, "\n\n\n")
-      .slice(0, 8000);
-  }
-}
-
-/**
- * Searches the Brave web index for matching results.
- *
- * @param query - The search query
- * @param count - The requested number of results (1-20 in web mode)
- * @param apiKey - The resolved Brave subscription token (never logged or echoed)
- * @param extras - Optional web-mode filters: country, safesearch, operators, spellcheck, result filter, goggles, pagination, freshness range
- * @returns Normalized web search results plus echoed query metadata
- */
+/** Searches Brave's web index; does not invoke Answers or fetch result URLs. */
 export async function searchBraveWeb(
   query: string,
   count: number,
-  freshness: Freshness | undefined,
   language: string | undefined,
   signal: AbortSignal | undefined,
   apiKey: string,
@@ -324,9 +146,6 @@ export async function searchBraveWeb(
 
   if (extras.operators !== undefined) url.searchParams.set("operators", String(extras.operators));
 
-  if (extras.spellcheck !== undefined)
-    url.searchParams.set("spellcheck", String(extras.spellcheck));
-
   if (extras.resultFilter)
     url.searchParams.set("result_filter", normalizeResultFilter(extras.resultFilter));
 
@@ -335,17 +154,13 @@ export async function searchBraveWeb(
   if (extras.offset !== undefined) url.searchParams.set("offset", String(extras.offset));
 
   if (extras.uiLang) url.searchParams.set("ui_lang", extras.uiLang);
-  const mappedFreshness = mapFreshness(freshness, extras.dateRange);
 
-  if (mappedFreshness) url.searchParams.set("freshness", mappedFreshness);
+  if (extras.dateRange) url.searchParams.set("freshness", extras.dateRange);
 
-  const data = await requestJson<BraveWebResponse & { query?: BraveQuery }>(
+  const data = await requestJson<BraveWebResponse>(
     url,
     {
-      headers: {
-        Accept: "application/json",
-        "X-Subscription-Token": apiKey,
-      },
+      headers: { Accept: "application/json", "X-Subscription-Token": apiKey },
     },
     signal,
   );
@@ -357,13 +172,12 @@ export async function searchBraveWeb(
 
       if (extras.extraSnippets && item.extra_snippets?.length) {
         const additional = item.extra_snippets
-          .slice(0, BRAVE_MAX_EXTRA_SNIPPETS)
+          .slice(0, 5)
           .map((value) => normalizeText(value ?? "", 300))
           .filter(Boolean);
 
-        if (additional.length) {
+        if (additional.length)
           snippet = normalizeText([snippet, ...additional].filter(Boolean).join("\n\n"), 2000);
-        }
       }
 
       return {
@@ -376,80 +190,3 @@ export async function searchBraveWeb(
     meta: parseQueryMeta(data.query),
   };
 }
-
-/**
- * Searches Brave's context API and maps grounding results to normalized search results.
- *
- * @param apiKey - The resolved Brave subscription token (never logged or echoed)
- * @param extras - Optional context-mode tuning: country, safesearch, spellcheck, goggles, relevance threshold, token-budget depth
- * @returns Search results containing normalized titles and URLs with deduplicated Markdown snippets, plus echoed query metadata.
- */
-export async function searchBraveContext(
-  query: string,
-  count: number,
-  freshness: Freshness | undefined,
-  language: string | undefined,
-  signal: AbortSignal | undefined,
-  apiKey: string,
-  extras: ContextSearchExtras = {},
-): Promise<SearchResponse> {
-  validateProviderRequest(query, count, "context", extras);
-  const budget = CONTEXT_DEPTH_BUDGETS[extras.depth ?? "quick"];
-
-  const url = new URL("https://api.search.brave.com/res/v1/llm/context");
-  url.searchParams.set("q", query);
-  url.searchParams.set("count", String(count));
-  url.searchParams.set("maximum_number_of_urls", String(count));
-  url.searchParams.set("maximum_number_of_tokens", String(budget.tokens));
-  url.searchParams.set("maximum_number_of_snippets", String(budget.snippets));
-  url.searchParams.set("maximum_number_of_tokens_per_url", String(budget.tokensPerUrl));
-  url.searchParams.set("maximum_number_of_snippets_per_url", String(budget.snippetsPerUrl));
-  url.searchParams.set("context_threshold_mode", extras.threshold ?? "strict");
-
-  if (language) url.searchParams.set("search_lang", language);
-
-  if (extras.country) url.searchParams.set("country", extras.country.toUpperCase());
-
-  if (extras.safesearch) url.searchParams.set("safesearch", extras.safesearch);
-
-  if (extras.spellcheck !== undefined)
-    url.searchParams.set("spellcheck", String(extras.spellcheck));
-
-  if (extras.goggles) url.searchParams.set("goggles", extras.goggles);
-
-  if (freshness)
-    url.searchParams.set(
-      "freshness",
-      { day: "pd", week: "pw", month: "pm", year: "py" }[freshness],
-    );
-
-  const data = await requestJson<BraveContextResponse & { query?: BraveQuery }>(
-    url,
-    {
-      headers: {
-        Accept: "application/json",
-        "X-Subscription-Token": apiKey,
-      },
-    },
-    signal,
-  );
-
-  return {
-    results: (data.grounding?.generic ?? []).map((item) => {
-      const snippets = [
-        ...new Set((item.snippets ?? []).map(braveSnippetToMarkdown).filter(Boolean)),
-      ];
-
-      const title = normalizeText(item.title ?? "", 300);
-      const snippet = snippets.slice(0, budget.snippetsPerUrl).join("\n\n");
-
-      return {
-        title,
-        url: normalizeUrl(item.url ?? ""),
-        snippet,
-        quality: classifyResultQuality({ title, snippet }),
-      };
-    }),
-    meta: parseQueryMeta(data.query),
-  };
-}

package/src/credentials.ts

@@ -10,7 +10,7 @@ export interface ResolvedApiKey {
   source: ApiKeySource;
 }
 
-const KEY_NAME = "BRAVE_SEARCH_API_KEY";
+export type ApiKeyName = "BRAVE_SEARCH_API_KEY" | "BRAVE_ANSWERS_API_KEY";
 
 const MAX_DOT_ENV_BYTES = 64 * 1024;
 
@@ -20,9 +20,12 @@ const MAX_DOT_ENV_BYTES = 64 * 1024;
  * Only the extracted value is used; file contents are never echoed into
  * errors or tool output.
  */
-export function extractKeyValue(text: string): string | undefined {
+export function extractKeyValue(
+  text: string,
+  keyName: ApiKeyName = "BRAVE_SEARCH_API_KEY",
+): string | undefined {
   for (const line of text.split(/\r?\n/)) {
-    const match = line.match(/^\s*BRAVE_SEARCH_API_KEY\s*=\s*(.*)$/);
+    const match = line.match(new RegExp(`^\\s*${keyName}\\s*=\\s*(.*)$`));
 
     if (!match) continue;
     let value = match[1].trim();
@@ -47,7 +50,7 @@ export function extractKeyValue(text: string): string | undefined {
  * @param path - Path to the .env file
  * @returns The extracted API key or undefined if file cannot be read or key is not found
  */
-async function readDotEnvKey(path: string): Promise<string | undefined> {
+async function readDotEnvKey(path: string, keyName: ApiKeyName): Promise<string | undefined> {
   let handle: Awaited<ReturnType<typeof open>> | undefined;
 
   try {
@@ -55,7 +58,7 @@ async function readDotEnvKey(path: string): Promise<string | undefined> {
     const buffer = Buffer.alloc(MAX_DOT_ENV_BYTES);
     const { bytesRead } = await handle.read(buffer, 0, MAX_DOT_ENV_BYTES, 0);
 
-    return extractKeyValue(buffer.toString("utf8", 0, bytesRead));
+    return extractKeyValue(buffer.toString("utf8", 0, bytesRead), keyName);
   } catch {
     return undefined;
   } finally {
@@ -71,16 +74,19 @@ async function readDotEnvKey(path: string): Promise<string | undefined> {
  * @param cwd - The workspace directory whose `.env` is consulted second
  * @returns The key and its source, or `undefined` when no source provides one
  */
-export async function resolveApiKey(cwd: string): Promise<ResolvedApiKey | undefined> {
-  const fromEnvironment = process.env[KEY_NAME];
+export async function resolveApiKey(
+  cwd: string,
+  keyName: ApiKeyName = "BRAVE_SEARCH_API_KEY",
+): Promise<ResolvedApiKey | undefined> {
+  const fromEnvironment = process.env[keyName];
 
   if (fromEnvironment) return { key: fromEnvironment, source: "environment" };
 
-  const fromWorkspace = await readDotEnvKey(join(cwd, ".env"));
+  const fromWorkspace = await readDotEnvKey(join(cwd, ".env"), keyName);
 
   if (fromWorkspace) return { key: fromWorkspace, source: "workspace .env" };
 
-  const fromAgent = await readDotEnvKey(join(getAgentDir(), ".env"));
+  const fromAgent = await readDotEnvKey(join(getAgentDir(), ".env"), keyName);
 
   if (fromAgent) return { key: fromAgent, source: "agent .env" };
 

package/src/index.ts

@@ -18,16 +18,20 @@ export {
   type SearchTruncationDetails,
 } from "./search";
 
-export type { BraveQueryMeta, ContextDepth, ContextThresholdMode, SearchResponse } from "./brave";
+export type { BraveQueryMeta, SearchMode, SearchResponse } from "./brave";
+
+export type { BraveAnswer } from "./answers";
 
 export const webSearchParameters = Type.Object({
   query: Type.String({
     minLength: 1,
     maxLength: SEARCH_WEB_MAX_QUERY_CHARACTERS,
   }),
-  freshness: Type.Optional(StringEnum(["day", "week", "month", "year"] as const)),
-  spellcheck: Type.Optional(
-    Type.Boolean({ description: "Set false for exact identifiers/error strings." }),
+  mode: Type.Optional(
+    StringEnum(["web", "answers"] as const, {
+      description:
+        '"web" (default): links and snippets. "answers": AI-generated answer with citations; requires Brave Answers plan.',
+    }),
   ),
 });
 
@@ -35,7 +39,7 @@ export const webSearchParameters = Type.Object({
  * Pi web search extension that registers the web_search tool.
  *
  * Provides a tool for searching the public web using Brave Search API with
- * support for both compact web results and extracted context modes.
+ * support for compact web results and explicitly selected generated answers.
  *
  * @param pi - The extension API instance
  */
@@ -46,7 +50,8 @@ export default function (pi: ExtensionAPI) {
   pi.registerTool({
     name: "web_search",
     label: "Web Search",
-    description: "Search the public web (links + snippets). Read a result with web_fetch.",
+    description:
+      "Search the public web (links + snippets), or select answers for a generated, cited response. Verify sources with web_fetch.",
     parameters: webSearchParameters,
 
     renderCall(args, theme) {

package/src/limits.ts

@@ -4,23 +4,12 @@ export const SEARCH_DEFAULT_RESULT_COUNT = 5;
 /** Minimum allowed result count. */
 export const SEARCH_MIN_RESULT_COUNT = 1;
 
-/**
- * Maximum allowed result count at the schema level (superset of both modes).
- * Web mode is limited to {@link SEARCH_WEB_MAX_RESULT_COUNT} and context mode
- * to {@link SEARCH_CONTEXT_MAX_RESULT_COUNT}; the tighter per-mode limit is
- * enforced at runtime because the provider rejects union schemas.
- */
-export const SEARCH_MAX_RESULT_COUNT = 50;
+/** Maximum allowed web result count; Answers does not accept a result count. */
+export const SEARCH_MAX_RESULT_COUNT = 20;
 
 /** Maximum result count for web-mode search (Brave allows 1-20). */
 export const SEARCH_WEB_MAX_RESULT_COUNT = 20;
 
-/** Maximum result count for context-mode search (Brave allows 1-50). */
-export const SEARCH_CONTEXT_MAX_RESULT_COUNT = 50;
-
-/** Maximum query length for context-based search (characters). */
-export const SEARCH_CONTEXT_MAX_QUERY_CHARACTERS = 400;
-
 /** Maximum query length for web search (characters). */
 export const SEARCH_WEB_MAX_QUERY_CHARACTERS = 400;
 

package/src/provider.ts

@@ -12,6 +12,8 @@ const SEARCH_ERROR_EXCERPT_BYTES = 8_192;
  * @returns Normalized text, truncated with ellipsis if needed
  */
 export function normalizeText(value: string, maxLength: number): string {
+  if (maxLength <= 0) return "";
+
   const text = value
     .replace(/<[^>]*>/g, " ")
     .replace(/\s+/g, " ")
@@ -103,19 +105,19 @@ async function readResponseText(
 }
 
 /**
- * Performs an HTTP request and parses the response as JSON with timeout and size limits.
+ * Performs an HTTP request and reads bounded text with timeout and size limits.
  *
  * @param url - URL to request
  * @param init - Fetch request init options
  * @param signal - Optional abort signal for cancellation
- * @returns Promise resolving to the parsed JSON response
+ * @returns Promise resolving to the bounded response text
  * @throws {Error} When request times out, is cancelled, or response is too large
  */
-export async function requestJson<T>(
+export async function requestText(
   url: string | URL,
   init: RequestInit,
   signal: AbortSignal | undefined,
-): Promise<T> {
+): Promise<string> {
   const controller = new AbortController();
   let timedOut = false;
 
@@ -127,6 +129,8 @@ export async function requestJson<T>(
   const cancel = () => controller.abort();
   signal?.addEventListener("abort", cancel, { once: true });
 
+  if (signal?.aborted) controller.abort();
+
   try {
     const response = await fetch(url, { ...init, signal: controller.signal });
 
@@ -145,8 +149,7 @@ export async function requestJson<T>(
       throw new Error(`Search provider returned HTTP ${response.status}${body ? `: ${body}` : ""}`);
     }
 
-    // SAFETY: the caller supplies the expected response shape T; JSON.parse yields the decoded document.
-    return JSON.parse(await readResponseText(response, SEARCH_MAX_RESPONSE_BYTES)) as T;
+    return await readResponseText(response, SEARCH_MAX_RESPONSE_BYTES);
   } catch (error) {
     if (timedOut)
       throw new Error(`Web search timed out after ${REQUEST_TIMEOUT_MS / 1000} seconds.`);
@@ -158,3 +161,13 @@ export async function requestJson<T>(
     signal?.removeEventListener("abort", cancel);
   }
 }
+
+/** Uses the shared bounded transport to decode a provider JSON response. */
+export async function requestJson<T>(
+  url: string | URL,
+  init: RequestInit,
+  signal: AbortSignal | undefined,
+): Promise<T> {
+  // SAFETY: callers supply the expected provider shape; transport bounds the decoded document.
+  return JSON.parse(await requestText(url, init, signal)) as T;
+}