@mrclrchtr/supi-web 5.0.0 → 6.0.1

package/README.md

@@ -6,6 +6,8 @@
 
 # @mrclrchtr/supi-web — Web Fetch and Context7 for Pi
 
+[![GitHub stars](https://img.shields.io/github/stars/mrclrchtr/supi)](https://github.com/mrclrchtr/supi/stargazers) [![npm downloads](https://img.shields.io/npm/dm/@mrclrchtr/supi-web)](https://www.npmjs.com/package/@mrclrchtr/supi-web)
+
 Adds web fetch and Context7 documentation tools to the [Pi coding agent](https://github.com/earendil-works/pi), without making you paste sources into chat.
 
 ## What your agent gets

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-web",
-  "version": "5.0.0",
+  "version": "6.0.1",
   "description": "Public web pages to Markdown, plus focused Context7 docs",
   "license": "MIT",
   "repository": {

package/src/docs.ts

@@ -4,334 +4,11 @@
  * API key is read automatically from the CONTEXT7_API_KEY environment variable.
  */
 
-import type {
-  AgentToolResult,
-  AgentToolUpdateCallback,
-  ExtensionAPI,
-  ExtensionContext,
-  TruncationResult,
-} from "@earendil-works/pi-coding-agent";
-import { getContext, searchLibrary } from "./context7-client.ts";
-import { getWebToolPromptSurface } from "./tool/guidance.ts";
-import { limitModelVisibleOutput } from "./tool/output.ts";
-import { renderCollapsibleTextResult, renderToolCall } from "./tool/render.ts";
-import {
-  getWebToolSpec,
-  WEB_DOCS_FETCH_TOOL_NAME,
-  WEB_DOCS_SEARCH_TOOL_NAME,
-  type WebDocsFetchInput,
-  type WebDocsSearchInput,
-} from "./tool/tool-specs.ts";
-
-interface SearchDetails extends Record<string, unknown> {
-  count: number;
-  libraryName: string;
-  truncation?: TruncationResult;
-  fullOutputPath?: string;
-}
-
-interface FetchDetails extends Record<string, unknown> {
-  libraryId: string;
-  raw: boolean;
-  chars: number;
-  lines: number;
-  truncation?: TruncationResult;
-  fullOutputPath?: string;
-}
-
-type SearchLibraryResult = Awaited<ReturnType<typeof searchLibrary>>[number];
-
-const MAX_SEARCH_RESULTS = 10;
-const MAX_DESCRIPTION_CHARS = 120;
-const MAX_VERSION_COUNT = 5;
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerWebDocsFetchTool } from "./tool/web_docs_fetch/register.ts";
+import { registerWebDocsSearchTool } from "./tool/web_docs_search/register.ts";
 
 export default function docsExtension(pi: ExtensionAPI): void {
-  const searchSpec = getWebToolSpec(WEB_DOCS_SEARCH_TOOL_NAME);
-  const searchSurface = getWebToolPromptSurface(WEB_DOCS_SEARCH_TOOL_NAME);
-  pi.registerTool({
-    name: searchSpec.name,
-    label: searchSpec.label,
-    description: searchSurface.description,
-    promptSnippet: searchSurface.promptSnippet,
-    promptGuidelines: searchSurface.promptGuidelines,
-    parameters: searchSpec.parameters,
-    execute: runSearch,
-    renderCall(args, theme) {
-      const input = (args ?? {}) as WebDocsSearchInput;
-      const libraryName = typeof input.library_name === "string" ? input.library_name : "";
-      const query = typeof input.query === "string" ? truncatePreview(input.query) : undefined;
-      return renderToolCall(searchSpec.name, libraryName, theme, query);
-    },
-    renderResult(result, { expanded, isPartial }, theme) {
-      if (isPartial) {
-        return renderCollapsibleTextResult({
-          summary: theme.fg("warning", "Searching Context7..."),
-          expanded,
-          theme,
-        });
-      }
-
-      const details = result.details as SearchDetails | undefined;
-      const summary = buildSearchSummary(details, theme);
-      const content = result.content.find((item) => item.type === "text");
-      const body =
-        details?.count === 0 ? undefined : content?.type === "text" ? content.text : undefined;
-
-      return renderCollapsibleTextResult({
-        summary,
-        body,
-        expanded,
-        theme,
-        fullOutputPath: details?.fullOutputPath,
-      });
-    },
-  });
-
-  const fetchSpec = getWebToolSpec(WEB_DOCS_FETCH_TOOL_NAME);
-  const fetchSurface = getWebToolPromptSurface(WEB_DOCS_FETCH_TOOL_NAME);
-  pi.registerTool({
-    name: fetchSpec.name,
-    label: fetchSpec.label,
-    description: fetchSurface.description,
-    promptSnippet: fetchSurface.promptSnippet,
-    promptGuidelines: fetchSurface.promptGuidelines,
-    parameters: fetchSpec.parameters,
-    execute: runFetch,
-    renderCall(args, theme) {
-      const input = (args ?? {}) as WebDocsFetchInput;
-      const libraryId = typeof input.library_id === "string" ? input.library_id : "";
-      const query = typeof input.query === "string" ? truncatePreview(input.query) : undefined;
-      return renderToolCall(fetchSpec.name, libraryId, theme, query);
-    },
-    renderResult(result, { expanded, isPartial }, theme) {
-      if (isPartial) {
-        return renderCollapsibleTextResult({
-          summary: theme.fg("warning", "Fetching Context7 docs..."),
-          expanded,
-          theme,
-        });
-      }
-
-      const details = result.details as FetchDetails | undefined;
-      const summary = buildFetchSummary(details, theme);
-      const content = result.content.find((item) => item.type === "text");
-      const body = content?.type === "text" ? content.text : undefined;
-
-      return renderCollapsibleTextResult({
-        summary,
-        body,
-        expanded,
-        theme,
-        fullOutputPath: details?.fullOutputPath,
-      });
-    },
-  });
-}
-
-// biome-ignore lint/complexity/useMaxParams: pi ToolDefinition.execute signature
-async function runSearch(
-  _toolCallId: string,
-  params: unknown,
-  signal: AbortSignal | undefined,
-  onUpdate: AgentToolUpdateCallback<Record<string, unknown>> | undefined,
-  _ctx: ExtensionContext,
-): Promise<AgentToolResult<SearchDetails>> {
-  const input = (params ?? {}) as WebDocsSearchInput;
-  const libraryName = input.library_name?.trim();
-  const query = input.query?.trim();
-
-  if (!libraryName) throw new Error("'library_name' parameter is required");
-  if (!query) throw new Error("'query' parameter is required");
-
-  onUpdate?.({
-    content: [{ type: "text", text: `Searching Context7 for ${libraryName}...` }],
-    details: { libraryName },
-  });
-
-  const requestOptions = signal ? { signal } : undefined;
-  const results = await searchLibrary(query, libraryName, requestOptions);
-
-  if (results.length === 0) {
-    return {
-      content: [
-        {
-          type: "text",
-          text: `No libraries found for "${libraryName}". Try a different search term.`,
-        },
-      ],
-      details: { count: 0, libraryName },
-    };
-  }
-
-  const markdown = formatSearchResults(libraryName, results);
-  const output = await limitModelVisibleOutput(markdown, {
-    tempPrefix: "web-docs-search",
-    suffix: ".md",
-  });
-
-  return {
-    content: [{ type: "text", text: output.text }],
-    details: {
-      count: results.length,
-      libraryName,
-      truncation: output.truncation,
-      fullOutputPath: output.fullOutputPath,
-    },
-  };
-}
-
-// biome-ignore lint/complexity/useMaxParams: pi ToolDefinition.execute signature
-async function runFetch(
-  _toolCallId: string,
-  params: unknown,
-  signal: AbortSignal | undefined,
-  onUpdate: AgentToolUpdateCallback<Record<string, unknown>> | undefined,
-  _ctx: ExtensionContext,
-): Promise<AgentToolResult<FetchDetails>> {
-  const input = (params ?? {}) as WebDocsFetchInput;
-  const libraryId = input.library_id?.trim();
-  const query = input.query?.trim();
-  const raw = Boolean(input.raw);
-
-  if (!libraryId) throw new Error("'library_id' parameter is required");
-  if (!query) throw new Error("'query' parameter is required");
-
-  onUpdate?.({
-    content: [{ type: "text", text: `Fetching Context7 docs for ${libraryId}...` }],
-    details: { libraryId, raw },
-  });
-
-  const requestOptions = signal ? { signal } : undefined;
-  const content = await getContext(query, libraryId, raw, requestOptions);
-  const textContent = typeof content === "string" ? content : JSON.stringify(content, null, 2);
-  const output = await limitModelVisibleOutput(textContent, {
-    tempPrefix: "web-docs-fetch",
-    suffix: raw ? ".json" : ".md",
-  });
-
-  return {
-    content: [{ type: "text", text: output.text }],
-    details: {
-      libraryId,
-      raw,
-      chars: textContent.length,
-      lines: textContent.split("\n").length,
-      truncation: output.truncation,
-      fullOutputPath: output.fullOutputPath,
-    },
-  };
-}
-
-function formatSearchResults(
-  libraryName: string,
-  results: Awaited<ReturnType<typeof searchLibrary>>,
-): string {
-  const visibleResults = results.slice(0, MAX_SEARCH_RESULTS);
-  const hiddenCount = results.length - visibleResults.length;
-  const rows = visibleResults.map(formatSearchRow);
-  const noun = results.length === 1 ? "library" : "libraries";
-  const hiddenNote =
-    hiddenCount > 0
-      ? [`_${hiddenCount} more omitted; refine \`library_name\` or \`query\` if needed._`, ""]
-      : [];
-
-  return [
-    `Found ${results.length} Context7 ${noun} for "${libraryName}"${hiddenCount > 0 ? `; showing top ${visibleResults.length}` : ""}:`,
-    "",
-    "| ID | Name | Trust | Bench | Snips | Versions | Description |",
-    "|---|---|---|---|---|---|---|",
-    ...rows,
-    "",
-    ...hiddenNote,
-    "> Use `web_docs_fetch` with the chosen ID.",
-  ].join("\n");
-}
-
-function formatSearchRow(lib: SearchLibraryResult): string {
-  const cells = [
-    `\`${escapeMd(lib.id)}\``,
-    escapeMd(lib.name),
-    String(lib.trustScore ?? ""),
-    String(lib.benchmarkScore ?? ""),
-    String(lib.totalSnippets ?? ""),
-    escapeMd(formatVersions(lib.versions)),
-    escapeMd(truncateCell(lib.description ?? "", MAX_DESCRIPTION_CHARS)),
-  ];
-
-  return `| ${cells.join(" | ")} |`;
-}
-
-function formatVersions(versions?: string[]): string {
-  if (!versions?.length) return "";
-  const visibleVersions = versions.slice(0, MAX_VERSION_COUNT);
-  const hiddenCount = versions.length - visibleVersions.length;
-  return `${visibleVersions.join(", ")}${hiddenCount > 0 ? `, +${hiddenCount}` : ""}`;
-}
-
-function truncateCell(text: string, maxChars: number): string {
-  const compact = text.replace(/\s+/g, " ").trim();
-  if (compact.length <= maxChars) return compact;
-  return `${compact.slice(0, maxChars - 1).trimEnd()}…`;
-}
-
-function escapeMd(text: string): string {
-  return text.replace(/\|/g, "\\|").replace(/\n/g, " ");
-}
-
-function truncatePreview(text: string, maxChars = 48): string {
-  const compact = text.replace(/\s+/g, " ").trim();
-  if (compact.length <= maxChars) return compact;
-  return `${compact.slice(0, maxChars - 1).trimEnd()}…`;
-}
-
-function buildSearchSummary(
-  details: SearchDetails | undefined,
-  theme: { fg: (color: "success" | "warning" | "dim", text: string) => string },
-): string {
-  if (!details) {
-    return theme.fg("success", "Context7 search finished");
-  }
-
-  if (details.count === 0) {
-    return [
-      theme.fg("warning", "No libraries found"),
-      theme.fg("dim", ` for ${JSON.stringify(details.libraryName)}`),
-    ].join("");
-  }
-
-  const noun = details.count === 1 ? "library" : "libraries";
-  let summary = [
-    theme.fg("success", `Found ${details.count} ${noun}`),
-    theme.fg("dim", ` for ${JSON.stringify(details.libraryName)}`),
-  ].join("");
-
-  if (details.truncation?.truncated) {
-    summary += theme.fg("warning", " [truncated]");
-  }
-
-  return summary;
-}
-
-function buildFetchSummary(
-  details: FetchDetails | undefined,
-  theme: { fg: (color: "success" | "warning" | "dim", text: string) => string },
-): string {
-  if (!details) {
-    return theme.fg("success", "Fetched Context7 docs");
-  }
-
-  const format = details.raw ? "raw JSON" : "Markdown";
-  let summary = [
-    theme.fg("success", `Fetched ${format}`),
-    theme.fg(
-      "dim",
-      ` for ${details.libraryId} (${details.chars.toLocaleString()} chars, ${details.lines.toLocaleString()} lines)`,
-    ),
-  ].join("");
-
-  if (details.truncation?.truncated) {
-    summary += theme.fg("warning", " [truncated]");
-  }
-
-  return summary;
+  registerWebDocsSearchTool(pi);
+  registerWebDocsFetchTool(pi);
 }

package/src/tool/tool-specs.ts

@@ -1,11 +1,44 @@
-import { StringEnum } from "@earendil-works/pi-ai";
-import { type Static, type TSchema, Type } from "typebox";
-import { FETCH_TIMEOUT_MAX_MS } from "../fetch.ts";
-import { MODEL_OUTPUT_LIMIT_DESCRIPTION } from "./output.ts";
+// Compatibility aggregator for the per-tool web specs and prompt surfaces.
 
-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";
+import type { TSchema } from "typebox";
+import {
+  toolDescription as docsFetchDescription,
+  promptGuidelines as docsFetchGuidelines,
+  promptSnippet as docsFetchSnippet,
+} from "./web_docs_fetch/guidance.ts";
+import {
+  WEB_DOCS_FETCH_TOOL_LABEL,
+  WEB_DOCS_FETCH_TOOL_NAME,
+  webDocsFetchParameters,
+} from "./web_docs_fetch/spec.ts";
+import {
+  toolDescription as searchDescription,
+  promptGuidelines as searchGuidelines,
+  promptSnippet as searchSnippet,
+} from "./web_docs_search/guidance.ts";
+import {
+  WEB_DOCS_SEARCH_TOOL_LABEL,
+  WEB_DOCS_SEARCH_TOOL_NAME,
+  webDocsSearchParameters,
+} from "./web_docs_search/spec.ts";
+import {
+  toolDescription as fetchDescription,
+  promptGuidelines as fetchGuidelines,
+  promptSnippet as fetchSnippet,
+  getWebFetchPromptSurface,
+} from "./web_fetch_md/guidance.ts";
+import {
+  WEB_FETCH_MD_TOOL_LABEL,
+  WEB_FETCH_MD_TOOL_NAME,
+  webFetchMdParameters,
+} from "./web_fetch_md/spec.ts";
+
+export type { WebDocsFetchInput } from "./web_docs_fetch/spec.ts";
+export { WEB_DOCS_FETCH_TOOL_NAME } from "./web_docs_fetch/spec.ts";
+export type { WebDocsSearchInput } from "./web_docs_search/spec.ts";
+export { WEB_DOCS_SEARCH_TOOL_NAME } from "./web_docs_search/spec.ts";
+export type { WebFetchMdInput, WebFetchOutputMode } from "./web_fetch_md/spec.ts";
+export { WEB_FETCH_INLINE_MAX_CHARS, WEB_FETCH_MD_TOOL_NAME } from "./web_fetch_md/spec.ts";
 
 export const WEB_TOOL_NAMES = [
   WEB_FETCH_MD_TOOL_NAME,
@@ -14,63 +47,12 @@ export const WEB_TOOL_NAMES = [
 ] 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.Integer({
-        description: "Fetch timeout (ms)",
-        default: 30_000,
-        minimum: 0,
-        maximum: FETCH_TIMEOUT_MAX_MS,
-      }),
-    ),
-  },
-  { 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>;
+/** Prompt metadata sent to pi for a single web tool. */
+export interface WebToolPromptSurface {
+  description: string;
+  promptSnippet: string;
+  promptGuidelines: string[];
+}
 
 export interface WebToolSpec {
   name: WebToolName;
@@ -84,29 +66,27 @@ export interface WebToolSpec {
 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. output_mode auto inlines <=${WEB_FETCH_INLINE_MAX_CHARS.toLocaleString()} chars else temp; inline may truncate; file returns a temp path. Links are 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,
+    label: WEB_FETCH_MD_TOOL_LABEL,
+    description: fetchDescription,
+    promptSnippet: fetchSnippet,
+    promptGuidelines: fetchGuidelines,
+    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,
+    label: WEB_DOCS_SEARCH_TOOL_LABEL,
+    description: searchDescription,
+    promptSnippet: searchSnippet,
+    promptGuidelines: searchGuidelines,
+    parameters: webDocsSearchParameters,
   },
   {
     name: WEB_DOCS_FETCH_TOOL_NAME,
-    label: "Web Docs Fetch",
-    description: `Fetch focused Context7 docs for a known Context7 library_id. Markdown by default; raw=true returns JSON snippets. Search first if unknown. ${MODEL_OUTPUT_LIMIT_DESCRIPTION}`,
-    promptSnippet: "web_docs_fetch: focused Context7 docs",
-    promptGuidelines: [
-      "Use web_docs_fetch with a known library_id and narrow query; raw only for JSON.",
-    ],
-    parameters: WebDocsFetchParameters,
+    label: WEB_DOCS_FETCH_TOOL_LABEL,
+    description: docsFetchDescription,
+    promptSnippet: docsFetchSnippet,
+    promptGuidelines: docsFetchGuidelines,
+    parameters: webDocsFetchParameters,
   },
 ] as const satisfies readonly WebToolSpec[];
 
@@ -115,3 +95,16 @@ export function getWebToolSpec(name: WebToolName): WebToolSpec {
   if (!spec) throw new Error(`Unknown web tool: ${name}`);
   return spec;
 }
+
+/** Runtime prompt surface, including environment-dependent guidance. */
+export function getWebToolPromptSurface(name: WebToolName): WebToolPromptSurface {
+  if (name === WEB_FETCH_MD_TOOL_NAME) {
+    return getWebFetchPromptSurface();
+  }
+  const spec = getWebToolSpec(name);
+  return {
+    description: spec.description,
+    promptSnippet: spec.promptSnippet,
+    promptGuidelines: [...spec.promptGuidelines],
+  };
+}

package/src/tool/web_docs_fetch/execute.ts

@@ -0,0 +1,41 @@
+import type {
+  AgentToolResult,
+  AgentToolUpdateCallback,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { getContext } from "../../context7-client.ts";
+import { limitModelVisibleOutput } from "../result.ts";
+import { buildFetchResult, type FetchDetails } from "./result.ts";
+import type { WebDocsFetchInput } from "./spec.ts";
+
+// biome-ignore lint/complexity/useMaxParams: pi ToolDefinition.execute signature
+export async function runFetch(
+  _toolCallId: string,
+  params: unknown,
+  signal: AbortSignal | undefined,
+  onUpdate: AgentToolUpdateCallback<Record<string, unknown>> | undefined,
+  _ctx: ExtensionContext,
+): Promise<AgentToolResult<FetchDetails>> {
+  const input = (params ?? {}) as WebDocsFetchInput;
+  const libraryId = input.library_id?.trim();
+  const query = input.query?.trim();
+  const raw = Boolean(input.raw);
+
+  if (!libraryId) throw new Error("'library_id' parameter is required");
+  if (!query) throw new Error("'query' parameter is required");
+
+  onUpdate?.({
+    content: [{ type: "text", text: `Fetching Context7 docs for ${libraryId}...` }],
+    details: { libraryId, raw },
+  });
+
+  const requestOptions = signal ? { signal } : undefined;
+  const content = await getContext(query, libraryId, raw, requestOptions);
+  const textContent = typeof content === "string" ? content : JSON.stringify(content, null, 2);
+  const output = await limitModelVisibleOutput(textContent, {
+    tempPrefix: "web-docs-fetch",
+    suffix: raw ? ".json" : ".md",
+  });
+
+  return buildFetchResult(libraryId, raw, textContent, output);
+}

package/src/tool/web_docs_fetch/guidance.ts

@@ -0,0 +1,9 @@
+import { MODEL_OUTPUT_LIMIT_DESCRIPTION } from "../result.ts";
+
+export const toolDescription = `Fetch focused Context7 docs for a known Context7 library_id. Markdown by default; raw=true returns JSON snippets. Search first if unknown. ${MODEL_OUTPUT_LIMIT_DESCRIPTION}`;
+
+export const promptSnippet = "web_docs_fetch: focused Context7 docs";
+
+export const promptGuidelines = [
+  "Use web_docs_fetch with a known library_id and narrow query; raw only for JSON.",
+];

package/src/tool/web_docs_fetch/register.ts

@@ -0,0 +1,16 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { promptGuidelines, promptSnippet, toolDescription } from "./guidance.ts";
+import { renderFetchCall, renderFetchResult } from "./render.ts";
+import { webDocsFetchSpec } from "./spec.ts";
+
+/** Register the web_docs_fetch tool. */
+export function registerWebDocsFetchTool(pi: ExtensionAPI): void {
+  pi.registerTool({
+    ...webDocsFetchSpec,
+    description: toolDescription,
+    promptSnippet,
+    promptGuidelines: [...promptGuidelines],
+    renderCall: renderFetchCall,
+    renderResult: renderFetchResult,
+  });
+}

package/src/tool/web_docs_fetch/render.ts

@@ -0,0 +1,70 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { renderCollapsibleTextResult, renderToolCall } from "../render.ts";
+import type { FetchDetails } from "./result.ts";
+import { WEB_DOCS_FETCH_TOOL_NAME, type WebDocsFetchInput } from "./spec.ts";
+
+/** Transcript renderer for web_docs_fetch tool calls. */
+export function renderFetchCall(args: unknown, theme: Theme) {
+  const input = (args ?? {}) as WebDocsFetchInput;
+  const libraryId = typeof input.library_id === "string" ? input.library_id : "";
+  const query = typeof input.query === "string" ? truncatePreview(input.query) : undefined;
+  return renderToolCall(WEB_DOCS_FETCH_TOOL_NAME, libraryId, theme, query);
+}
+
+/** Transcript renderer for web_docs_fetch tool results. */
+export function renderFetchResult(
+  result: { content: Array<{ type: string; text?: string }>; details?: unknown },
+  { expanded, isPartial }: { expanded: boolean; isPartial: boolean },
+  theme: Theme,
+) {
+  if (isPartial) {
+    return renderCollapsibleTextResult({
+      summary: theme.fg("warning", "Fetching Context7 docs..."),
+      expanded,
+      theme,
+    });
+  }
+
+  const details = result.details as FetchDetails | undefined;
+  const summary = buildFetchSummary(details, theme);
+  const content = result.content.find((item) => item.type === "text");
+  const body = content?.type === "text" ? content.text : undefined;
+
+  return renderCollapsibleTextResult({
+    summary,
+    body,
+    expanded,
+    theme,
+    fullOutputPath: details?.fullOutputPath,
+  });
+}
+
+function truncatePreview(text: string, maxChars = 48): string {
+  const compact = text.replace(/\s+/g, " ").trim();
+  if (compact.length <= maxChars) return compact;
+  return `${compact.slice(0, maxChars - 1).trimEnd()}…`;
+}
+
+function buildFetchSummary(
+  details: FetchDetails | undefined,
+  theme: { fg: (color: "success" | "warning" | "dim", text: string) => string },
+): string {
+  if (!details) {
+    return theme.fg("success", "Fetched Context7 docs");
+  }
+
+  const format = details.raw ? "raw JSON" : "Markdown";
+  let summary = [
+    theme.fg("success", `Fetched ${format}`),
+    theme.fg(
+      "dim",
+      ` for ${details.libraryId} (${details.chars.toLocaleString()} chars, ${details.lines.toLocaleString()} lines)`,
+    ),
+  ].join("");
+
+  if (details.truncation?.truncated) {
+    summary += theme.fg("warning", " [truncated]");
+  }
+
+  return summary;
+}