@mrclrchtr/supi-web 1.14.3 → 1.16.0

package/src/fetch.ts

@@ -25,6 +25,7 @@ export interface FetchResult {
 /** Fetch options. */
 export interface FetchOptions {
   timeoutMs?: number;
+  signal?: AbortSignal;
 }
 
 /** Validate that a string is a real http(s) URL. */
@@ -43,29 +44,35 @@ export async function fetchWithNegotiation(
   options: FetchOptions = {},
 ): Promise<FetchResult> {
   const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const { signal } = options;
 
   // 1. Try HEAD negotiation for Markdown
-  const headResult = await tryHeadNegotiation(url, timeoutMs);
+  const headResult = await tryHeadNegotiation(url, timeoutMs, signal);
   if (headResult) return headResult;
 
   // 2. Range GET to sniff content type
-  const sniffResult = await trySniffNegotiation(url, timeoutMs);
+  const sniffResult = await trySniffNegotiation(url, timeoutMs, signal);
   if (sniffResult) return sniffResult;
 
   // 3. Try sibling .md URLs
-  const siblingResult = await trySiblingNegotiation(url, timeoutMs);
+  const siblingResult = await trySiblingNegotiation(url, timeoutMs, signal);
   if (siblingResult) return siblingResult;
 
   // 4. Full GET as HTML → convert to Markdown
-  return fetchAsHtml(url, timeoutMs);
+  return fetchAsHtml(url, timeoutMs, signal);
 }
 
-async function tryHeadNegotiation(url: string, timeoutMs: number): Promise<FetchResult | null> {
+async function tryHeadNegotiation(
+  url: string,
+  timeoutMs: number,
+  signal: AbortSignal | undefined,
+): Promise<FetchResult | null> {
   try {
     const headRes = await timedFetch(
       url,
       { method: "HEAD", redirect: "follow", headers: { "User-Agent": USER_AGENT } },
       timeoutMs,
+      signal,
     );
     if (!headRes.ok) return null;
     const ct = headRes.headers.get("content-type") || "";
@@ -75,9 +82,12 @@ async function tryHeadNegotiation(url: string, timeoutMs: number): Promise<Fetch
       url,
       { method: "GET", redirect: "follow", headers: { "User-Agent": USER_AGENT } },
       timeoutMs,
+      signal,
     );
     if (!getRes.ok)
-      throw new FetchError(`Fetch failed: ${getRes.status} ${getRes.statusText}`, getRes.status);
+      throw new FetchError(`Fetch failed: ${getRes.status} ${getRes.statusText}`, {
+        status: getRes.status,
+      });
     return {
       url: getRes.url || url,
       text: await getRes.text(),
@@ -85,12 +95,17 @@ async function tryHeadNegotiation(url: string, timeoutMs: number): Promise<Fetch
       isMarkdown: true,
       isPlainText: false,
     };
-  } catch {
+  } catch (err) {
+    if (signal?.aborted) throw err;
     return null;
   }
 }
 
-async function trySniffNegotiation(url: string, timeoutMs: number): Promise<FetchResult | null> {
+async function trySniffNegotiation(
+  url: string,
+  timeoutMs: number,
+  signal: AbortSignal | undefined,
+): Promise<FetchResult | null> {
   try {
     const sniffRes = await timedFetch(
       url,
@@ -100,109 +115,152 @@ async function trySniffNegotiation(url: string, timeoutMs: number): Promise<Fetc
         headers: { "User-Agent": USER_AGENT, Range: `bytes=0-${SNIFF_BYTES - 1}` },
       },
       timeoutMs,
+      signal,
     );
     const sniffText = await readPartialText(sniffRes, SNIFF_BYTES);
     const ct = sniffRes.headers.get("content-type") || "";
     const finalUrl = sniffRes.url || url;
 
     if (!sniffRes.ok || isHtml(sniffText)) return null;
-
-    if (
-      isMarkdownContentType(ct) ||
-      looksLikeMarkdownUrl(finalUrl) ||
-      looksLikeMarkdown(sniffText)
-    ) {
-      const fullRes = await timedFetch(
+    if (isMarkdownCandidate(ct, finalUrl, sniffText)) {
+      return fetchFullTextResult({
         url,
-        { method: "GET", redirect: "follow", headers: { "User-Agent": USER_AGENT } },
         timeoutMs,
-      );
-      if (!fullRes.ok)
-        throw new FetchError(
-          `Fetch failed: ${fullRes.status} ${fullRes.statusText}`,
-          fullRes.status,
-        );
-      return {
-        url: fullRes.url || url,
-        text: await fullRes.text(),
+        signal,
         contentType: ct,
-        isMarkdown: true,
-        isPlainText: false,
-      };
+        kind: MARKDOWN_RESPONSE_KIND,
+        headers: { "User-Agent": USER_AGENT },
+      });
     }
-
-    if (
-      isPlainTextContentType(ct) &&
-      !looksLikeMarkdownUrl(finalUrl) &&
-      !looksLikeMarkdown(sniffText)
-    ) {
-      const fullRes = await timedFetch(
+    if (isPlainTextCandidate(ct, finalUrl, sniffText)) {
+      return fetchFullTextResult({
         url,
-        { method: "GET", redirect: "follow", headers: { "User-Agent": USER_AGENT } },
         timeoutMs,
-      );
-      if (!fullRes.ok)
-        throw new FetchError(
-          `Fetch failed: ${fullRes.status} ${fullRes.statusText}`,
-          fullRes.status,
-        );
-      return {
-        url: fullRes.url || url,
-        text: await fullRes.text(),
+        signal,
         contentType: ct,
-        isMarkdown: false,
-        isPlainText: true,
-      };
+        kind: PLAIN_TEXT_RESPONSE_KIND,
+        headers: { "User-Agent": USER_AGENT },
+      });
     }
-
     return null;
-  } catch {
+  } catch (err) {
+    if (signal?.aborted) throw err;
     return null;
   }
 }
 
-async function trySiblingNegotiation(url: string, timeoutMs: number): Promise<FetchResult | null> {
+async function trySiblingNegotiation(
+  url: string,
+  timeoutMs: number,
+  signal: AbortSignal | undefined,
+): Promise<FetchResult | null> {
   for (const sibling of generateSiblingUrls(url)) {
     try {
-      const sibRes = await timedFetch(
-        sibling,
-        {
-          method: "GET",
-          redirect: "follow",
-          headers: { "User-Agent": USER_AGENT, Accept: ACCEPT_SIBLING },
-        },
-        timeoutMs,
-      );
-      const sibText = await readPartialText(sibRes, SNIFF_BYTES);
-      const sibCt = sibRes.headers.get("content-type") || "";
-      if (!sibRes.ok || isHtml(sibText) || isHtmlContentType(sibCt)) continue;
-      if (!looksLikeMarkdown(sibText) && !isMarkdownContentType(sibCt)) continue;
-
-      const fullRes = await timedFetch(
-        sibling,
-        {
-          method: "GET",
-          redirect: "follow",
-          headers: { "User-Agent": USER_AGENT, Accept: ACCEPT_SIBLING },
-        },
-        timeoutMs,
-      );
-      if (!fullRes.ok) continue;
-      return {
-        url: fullRes.url || sibling,
-        text: await fullRes.text(),
-        contentType: sibCt,
-        isMarkdown: true,
-        isPlainText: false,
-      };
-    } catch {
+      const result = await fetchMarkdownSibling(sibling, timeoutMs, signal);
+      if (result) return result;
+    } catch (err) {
+      if (signal?.aborted) throw err;
       // Try next sibling
     }
   }
   return null;
 }
 
-async function fetchAsHtml(url: string, timeoutMs: number): Promise<FetchResult> {
+async function fetchMarkdownSibling(
+  sibling: string,
+  timeoutMs: number,
+  signal: AbortSignal | undefined,
+): Promise<FetchResult | null> {
+  const headers = { "User-Agent": USER_AGENT, Accept: ACCEPT_SIBLING };
+  const sibRes = await timedFetch(
+    sibling,
+    { method: "GET", redirect: "follow", headers },
+    timeoutMs,
+    signal,
+  );
+  const sibText = await readPartialText(sibRes, SNIFF_BYTES);
+  const sibCt = sibRes.headers.get("content-type") || "";
+
+  if (!sibRes.ok || isHtml(sibText) || isHtmlContentType(sibCt)) return null;
+  if (!looksLikeMarkdown(sibText) && !isMarkdownContentType(sibCt)) return null;
+
+  const fullRes = await timedFetch(
+    sibling,
+    { method: "GET", redirect: "follow", headers },
+    timeoutMs,
+    signal,
+  );
+  if (!fullRes.ok) return null;
+  return buildFetchResult(fullRes, sibling, sibCt, MARKDOWN_RESPONSE_KIND);
+}
+
+interface ResponseKind {
+  isMarkdown: boolean;
+  isPlainText: boolean;
+}
+
+interface FetchFullTextOptions {
+  url: string;
+  timeoutMs: number;
+  signal: AbortSignal | undefined;
+  contentType: string;
+  kind: ResponseKind;
+  headers: Record<string, string>;
+}
+
+const MARKDOWN_RESPONSE_KIND = { isMarkdown: true, isPlainText: false } as const;
+const PLAIN_TEXT_RESPONSE_KIND = { isMarkdown: false, isPlainText: true } as const;
+
+async function fetchFullTextResult(options: FetchFullTextOptions): Promise<FetchResult> {
+  const fullRes = await timedFetch(
+    options.url,
+    { method: "GET", redirect: "follow", headers: options.headers },
+    options.timeoutMs,
+    options.signal,
+  );
+  if (!fullRes.ok)
+    throw new FetchError(`Fetch failed: ${fullRes.status} ${fullRes.statusText}`, {
+      status: fullRes.status,
+    });
+  return buildFetchResult(fullRes, options.url, options.contentType, options.kind);
+}
+
+async function buildFetchResult(
+  response: Response,
+  fallbackUrl: string,
+  contentType: string,
+  kind: ResponseKind,
+): Promise<FetchResult> {
+  return {
+    url: response.url || fallbackUrl,
+    text: await response.text(),
+    contentType,
+    isMarkdown: kind.isMarkdown,
+    isPlainText: kind.isPlainText,
+  };
+}
+
+function isMarkdownCandidate(contentType: string, finalUrl: string, sniffText: string): boolean {
+  return (
+    isMarkdownContentType(contentType) ||
+    looksLikeMarkdownUrl(finalUrl) ||
+    looksLikeMarkdown(sniffText)
+  );
+}
+
+function isPlainTextCandidate(contentType: string, finalUrl: string, sniffText: string): boolean {
+  return (
+    isPlainTextContentType(contentType) &&
+    !looksLikeMarkdownUrl(finalUrl) &&
+    !looksLikeMarkdown(sniffText)
+  );
+}
+
+async function fetchAsHtml(
+  url: string,
+  timeoutMs: number,
+  signal: AbortSignal | undefined,
+): Promise<FetchResult> {
   const res = await timedFetch(
     url,
     {
@@ -211,8 +269,10 @@ async function fetchAsHtml(url: string, timeoutMs: number): Promise<FetchResult>
       headers: { "User-Agent": USER_AGENT, Accept: "text/html,*/*;q=0.1" },
     },
     timeoutMs,
+    signal,
   );
-  if (!res.ok) throw new FetchError(`Fetch failed: ${res.status} ${res.statusText}`, res.status);
+  if (!res.ok)
+    throw new FetchError(`Fetch failed: ${res.status} ${res.statusText}`, { status: res.status });
   return {
     url: res.url || url,
     text: await res.text(),
@@ -223,23 +283,45 @@ async function fetchAsHtml(url: string, timeoutMs: number): Promise<FetchResult>
 }
 
 /** Error thrown on fetch failures. */
+export interface FetchErrorOptions extends ErrorOptions {
+  status?: number;
+}
+
 export class FetchError extends Error {
-  constructor(
-    message: string,
-    readonly status?: number,
-  ) {
-    super(message);
+  readonly status?: number;
+
+  constructor(message: string, options: FetchErrorOptions = {}) {
+    super(message, options);
     this.name = "FetchError";
+    this.status = options.status;
   }
 }
 
-async function timedFetch(url: string, init: RequestInit, timeoutMs: number): Promise<Response> {
+async function timedFetch(
+  url: string,
+  init: RequestInit,
+  timeoutMs: number,
+  signal?: AbortSignal,
+): Promise<Response> {
   const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let timedOut = false;
+  const abortFromParent = () => controller.abort();
+  if (signal?.aborted) abortFromParent();
+  else signal?.addEventListener("abort", abortFromParent, { once: true });
+
+  const timer = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, timeoutMs);
+
   try {
     return await fetch(url, { ...init, signal: controller.signal });
+  } catch (err) {
+    if (timedOut) throw new FetchError(`Fetch timed out after ${timeoutMs}ms`, { cause: err });
+    throw err;
   } finally {
     clearTimeout(timer);
+    signal?.removeEventListener("abort", abortFromParent);
   }
 }
 

package/src/index.ts

@@ -2,6 +2,7 @@
  * SuPi Web extension — public API exports.
  */
 
+export type { Context7RequestOptions } from "./context7-client.ts";
 export { htmlToMarkdown, wrapAsCodeBlock } from "./convert.ts";
 export { default as docsExtension } from "./docs.ts";
 export {
@@ -11,4 +12,13 @@ export {
   fetchWithNegotiation,
   isValidHttpUrl,
 } from "./fetch.ts";
+export {
+  WEB_FETCH_INLINE_MAX_CHARS,
+  WEB_TOOL_NAMES,
+  WEB_TOOL_SPECS,
+  type WebDocsFetchInput,
+  type WebDocsSearchInput,
+  type WebFetchMdInput,
+  type WebToolName,
+} from "./tool/tool-specs.ts";
 export { default } from "./web.ts";

package/src/temp-file.ts

@@ -1,21 +1,22 @@
 /**
- * Temporary file helpers for the web_fetch_md tool.
+ * Temporary file helpers for the web tools.
  */
 
 import { randomBytes } from "node:crypto";
-import { mkdtempSync, writeFileSync } from "node:fs";
+import { mkdtemp, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 
-/** Write content to a temporary file and return the absolute path. */
+/** Write content to a unique temporary file and return the absolute path. */
 export async function writeTempFile(
   content: string,
   prefix: string,
   suffix: string,
 ): Promise<string> {
-  const dir = mkdtempSync(join(tmpdir(), `${prefix}-`));
+  const dir = await mkdtemp(join(tmpdir(), `${prefix}-`));
   const hash = randomBytes(4).toString("hex");
   const filePath = join(dir, `${hash}${suffix}`);
-  writeFileSync(filePath, content, "utf8");
+  await withFileMutationQueue(filePath, () => writeFile(filePath, content, "utf8"));
   return filePath;
 }

package/src/tool/guidance.ts

@@ -0,0 +1,34 @@
+import { spawnSync } from "node:child_process";
+import { getWebToolSpec, WEB_FETCH_MD_TOOL_NAME, type WebToolName } from "./tool-specs.ts";
+
+/** Prompt metadata sent to pi for a single web tool. */
+export interface WebToolPromptSurface {
+  description: string;
+  promptSnippet: string;
+  promptGuidelines: string[];
+}
+
+/** Build prompt metadata from the shared tool specs, adding runtime-specific guidance when useful. */
+export function getWebToolPromptSurface(name: WebToolName): WebToolPromptSurface {
+  const spec = getWebToolSpec(name);
+  const promptGuidelines = [...spec.promptGuidelines];
+
+  if (name === WEB_FETCH_MD_TOOL_NAME && isGhAvailable()) {
+    promptGuidelines.push("Use `gh` CLI instead of web_fetch_md for GitHub URLs.");
+  }
+
+  return {
+    description: spec.description,
+    promptSnippet: spec.promptSnippet,
+    promptGuidelines,
+  };
+}
+
+function isGhAvailable(): boolean {
+  try {
+    const result = spawnSync("gh", ["--version"], { stdio: "ignore" });
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}

package/src/tool/output.ts

@@ -0,0 +1,50 @@
+import {
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+  formatSize,
+  type TruncationResult,
+  truncateHead,
+} from "@earendil-works/pi-coding-agent";
+import { writeTempFile } from "../temp-file.ts";
+
+/** Human-readable truncation contract shared by all model-visible web outputs. */
+export const MODEL_OUTPUT_LIMIT_DESCRIPTION = `Inline truncates at ${DEFAULT_MAX_LINES.toLocaleString()} lines/${formatSize(DEFAULT_MAX_BYTES)}; full saved to temp.`;
+
+/** Result of preparing content for a tool response visible to the model. */
+export interface ModelVisibleOutput {
+  /** Text safe to return in a tool result. */
+  text: string;
+  /** Truncation metadata when truncation happened. */
+  truncation?: TruncationResult;
+  /** Temp file containing the full, untruncated output when truncation happened. */
+  fullOutputPath?: string;
+}
+
+/** Prepare content for model-visible output, preserving full output in a temp file if truncated. */
+export async function limitModelVisibleOutput(
+  content: string,
+  options: { tempPrefix: string; suffix: string },
+): Promise<ModelVisibleOutput> {
+  const truncation = truncateHead(content, {
+    maxLines: DEFAULT_MAX_LINES,
+    maxBytes: DEFAULT_MAX_BYTES,
+  });
+
+  if (!truncation.truncated) {
+    return { text: content };
+  }
+
+  const fullOutputPath = await writeTempFile(content, options.tempPrefix, options.suffix);
+  const prefix = truncation.content.length > 0 ? `${truncation.content}\n\n` : "";
+  const notice = [
+    `[Output truncated: ${truncation.outputLines.toLocaleString()}/${truncation.totalLines.toLocaleString()} lines,`,
+    `${formatSize(truncation.outputBytes)}/${formatSize(truncation.totalBytes)}.`,
+    `Full: ${fullOutputPath}]`,
+  ].join(" ");
+
+  return {
+    text: `${prefix}${notice}`,
+    truncation,
+    fullOutputPath,
+  };
+}

package/src/tool/render.ts

@@ -0,0 +1,63 @@
+import type { ThemeColor } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+
+interface RenderTheme {
+  fg: (color: ThemeColor, text: string) => string;
+}
+
+interface CollapsibleTextResultOptions {
+  summary: string;
+  body?: string;
+  expanded: boolean;
+  theme: RenderTheme;
+  fullOutputPath?: string;
+  bodyColor?: ThemeColor;
+}
+
+export function renderToolCall(
+  name: string,
+  primary: string,
+  theme: RenderTheme,
+  secondary?: string,
+): Text {
+  let content = theme.fg("toolTitle", name);
+  if (primary) {
+    content += ` ${theme.fg("accent", primary)}`;
+  }
+  if (secondary) {
+    content += theme.fg("dim", ` — ${secondary}`);
+  }
+  return new Text(content, 0, 0);
+}
+
+/** Render a compact tool summary that expands into the full text body on demand. */
+export function renderCollapsibleTextResult({
+  summary,
+  body,
+  expanded,
+  theme,
+  fullOutputPath,
+  bodyColor = "toolOutput",
+}: CollapsibleTextResultOptions): Text {
+  const lines = [summary];
+  const bodyText = body?.trimEnd();
+
+  if (expanded && bodyText) {
+    lines.push(formatMultiline(bodyText, theme, bodyColor));
+  } else if (bodyText) {
+    lines[0] += theme.fg("dim", " (expand for output)");
+  }
+
+  if (expanded && fullOutputPath) {
+    lines.push(theme.fg("dim", `Full output: ${fullOutputPath}`));
+  }
+
+  return new Text(lines.filter(Boolean).join("\n"), 0, 0);
+}
+
+function formatMultiline(text: string, theme: RenderTheme, color: ThemeColor): string {
+  return text
+    .split("\n")
+    .map((line) => (line.length > 0 ? theme.fg(color, line) : ""))
+    .join("\n");
+}

package/src/tool/tool-specs.ts

@@ -0,0 +1,107 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { type Static, type TSchema, Type } from "typebox";
+import { MODEL_OUTPUT_LIMIT_DESCRIPTION } from "./output.ts";
+
+export const WEB_FETCH_MD_TOOL_NAME = "web_fetch_md";
+export const WEB_DOCS_SEARCH_TOOL_NAME = "web_docs_search";
+export const WEB_DOCS_FETCH_TOOL_NAME = "web_docs_fetch";
+
+export const WEB_TOOL_NAMES = [
+  WEB_FETCH_MD_TOOL_NAME,
+  WEB_DOCS_SEARCH_TOOL_NAME,
+  WEB_DOCS_FETCH_TOOL_NAME,
+] as const;
+export type WebToolName = (typeof WEB_TOOL_NAMES)[number];
+
+export const WEB_FETCH_INLINE_MAX_CHARS = 15_000;
+export const WEB_FETCH_OUTPUT_MODES = ["auto", "inline", "file"] as const;
+export type WebFetchOutputMode = (typeof WEB_FETCH_OUTPUT_MODES)[number];
+
+const OutputModeEnum = StringEnum(WEB_FETCH_OUTPUT_MODES, {
+  default: "auto",
+  description: "auto, inline, or file output",
+});
+
+const WebFetchMdParameters = Type.Object(
+  {
+    url: Type.String({ description: "Public http(s) URL" }),
+    output_mode: Type.Optional(OutputModeEnum),
+    abs_links: Type.Optional(Type.Boolean({ description: "Absolute links/images", default: true })),
+    timeout_ms: Type.Optional(Type.Number({ description: "Fetch timeout (ms)", default: 30_000 })),
+  },
+  { additionalProperties: false },
+);
+
+const WebDocsSearchParameters = Type.Object(
+  {
+    library_name: Type.String({
+      description: "Library name (e.g. react, next.js, fastapi)",
+    }),
+    query: Type.String({
+      description: "Task/question for relevance ranking",
+    }),
+  },
+  { additionalProperties: false },
+);
+
+const WebDocsFetchParameters = Type.Object(
+  {
+    library_id: Type.String({
+      description: "Context7 ID (e.g. /facebook/react); search first if unknown",
+    }),
+    query: Type.String({ description: "Specific docs question" }),
+    raw: Type.Optional(
+      Type.Boolean({
+        description: "Return JSON snippets instead of Markdown",
+        default: false,
+      }),
+    ),
+  },
+  { additionalProperties: false },
+);
+
+export type WebFetchMdInput = Static<typeof WebFetchMdParameters>;
+export type WebDocsSearchInput = Static<typeof WebDocsSearchParameters>;
+export type WebDocsFetchInput = Static<typeof WebDocsFetchParameters>;
+
+export interface WebToolSpec {
+  name: WebToolName;
+  label: string;
+  description: string;
+  promptSnippet: string;
+  promptGuidelines: readonly string[];
+  parameters: TSchema;
+}
+
+export const WEB_TOOL_SPECS = [
+  {
+    name: WEB_FETCH_MD_TOOL_NAME,
+    label: "Web Fetch",
+    description: `Fetch public http(s) URL as Markdown. Not for login/private pages; ask for allowed source. auto: inline <=${WEB_FETCH_INLINE_MAX_CHARS.toLocaleString()} chars else temp; inline: may truncate; file: temp path. Links absolute by default. ${MODEL_OUTPUT_LIMIT_DESCRIPTION}`,
+    promptSnippet: "web_fetch_md: public URL to Markdown",
+    promptGuidelines: ["Use web_fetch_md only for public http(s); ask if login/private."],
+    parameters: WebFetchMdParameters,
+  },
+  {
+    name: WEB_DOCS_SEARCH_TOOL_NAME,
+    label: "Web Docs Search",
+    description: `Search Context7 for library IDs; returns compact Markdown. ${MODEL_OUTPUT_LIMIT_DESCRIPTION}`,
+    promptSnippet: "web_docs_search: Context7 library IDs",
+    promptGuidelines: ["Use web_docs_search before web_docs_fetch if ID unknown."],
+    parameters: WebDocsSearchParameters,
+  },
+  {
+    name: WEB_DOCS_FETCH_TOOL_NAME,
+    label: "Web Docs Fetch",
+    description: `Fetch focused Context7 docs for known library_id; Markdown default, raw=true JSON snippets. Search first if unknown. ${MODEL_OUTPUT_LIMIT_DESCRIPTION}`,
+    promptSnippet: "web_docs_fetch: focused Context7 docs",
+    promptGuidelines: ["Use web_docs_fetch with known ID and narrow query; raw only for JSON."],
+    parameters: WebDocsFetchParameters,
+  },
+] as const satisfies readonly WebToolSpec[];
+
+export function getWebToolSpec(name: WebToolName): WebToolSpec {
+  const spec = WEB_TOOL_SPECS.find((candidate) => candidate.name === name);
+  if (!spec) throw new Error(`Unknown web tool: ${name}`);
+  return spec;
+}