@mrclrchtr/supi-web 1.14.3 → 1.15.0

package/src/web.ts

@@ -2,105 +2,143 @@
  * SuPi Web extension entry point — registers the `web_fetch_md` tool with pi.
  */
 
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
+import type {
+  AgentToolResult,
+  AgentToolUpdateCallback,
+  ExtensionAPI,
+  ExtensionContext,
+  TruncationResult,
+} from "@earendil-works/pi-coding-agent";
 import { htmlToMarkdown, wrapAsCodeBlock } from "./convert.ts";
-import { FetchError, fetchWithNegotiation, isValidHttpUrl } from "./fetch.ts";
+import { fetchWithNegotiation, isValidHttpUrl } from "./fetch.ts";
 import { writeTempFile } from "./temp-file.ts";
+import { getWebToolPromptSurface } from "./tool/guidance.ts";
+import { limitModelVisibleOutput } from "./tool/output.ts";
+import { renderCollapsibleTextResult, renderToolCall } from "./tool/render.ts";
 import {
-  buildPromptGuidelines,
-  promptSnippet,
-  toolDescription,
-} from "./tool/web-fetch-md-guidance.ts";
+  getWebToolSpec,
+  WEB_FETCH_INLINE_MAX_CHARS,
+  WEB_FETCH_MD_TOOL_NAME,
+  type WebFetchMdInput,
+  type WebFetchOutputMode,
+} from "./tool/tool-specs.ts";
 
-const TOOL_NAME = "web_fetch_md";
-const TOOL_LABEL = "Web Fetch";
-const INLINE_MAX_CHARS = 15_000;
-
-const OutputModeEnum = Type.Union(
-  [Type.Literal("auto"), Type.Literal("inline"), Type.Literal("file")],
-  { default: "auto", description: "Output mode: auto, inline, or file" },
-);
+interface WebFetchDetails extends Record<string, unknown> {
+  chars: number;
+  lines: number;
+  url: string;
+  outputMode: WebFetchOutputMode;
+  filePath?: string;
+  truncation?: TruncationResult;
+  fullOutputPath?: string;
+}
 
 export default function webExtension(pi: ExtensionAPI): void {
+  const spec = getWebToolSpec(WEB_FETCH_MD_TOOL_NAME);
+  const surface = getWebToolPromptSurface(WEB_FETCH_MD_TOOL_NAME);
+
   pi.registerTool({
-    name: TOOL_NAME,
-    label: TOOL_LABEL,
-    description: toolDescription,
-    promptSnippet,
-    promptGuidelines: buildPromptGuidelines(),
-    parameters: Type.Object({
-      url: Type.String({ description: "http(s) URL to fetch" }),
-      output_mode: Type.Optional(OutputModeEnum),
-      abs_links: Type.Optional(
-        Type.Boolean({ description: "Absolutize relative links/images", default: true }),
-      ),
-      timeout_ms: Type.Optional(
-        Type.Number({ description: "Fetch timeout in milliseconds", default: 30_000 }),
-      ),
-    }),
+    name: spec.name,
+    label: spec.label,
+    description: surface.description,
+    promptSnippet: surface.promptSnippet,
+    promptGuidelines: surface.promptGuidelines,
+    parameters: spec.parameters,
     execute: runWebFetch,
+    renderCall(args, theme) {
+      const input = (args ?? {}) as WebFetchMdInput;
+      const url = typeof input.url === "string" ? input.url : "";
+      const outputMode = typeof input.output_mode === "string" ? input.output_mode : undefined;
+      return renderToolCall(spec.name, url, theme, outputMode);
+    },
+    renderResult(result, { expanded, isPartial }, theme) {
+      if (isPartial) {
+        return renderCollapsibleTextResult({
+          summary: theme.fg("warning", "Fetching web content..."),
+          expanded,
+          theme,
+        });
+      }
+
+      const details = result.details as WebFetchDetails | undefined;
+      const summary = buildWebFetchSummary(details, theme);
+      const content = result.content.find((item) => item.type === "text");
+      const body = details?.filePath
+        ? undefined
+        : 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 runWebFetch(
   _toolCallId: string,
-  params: Record<string, unknown>,
-  _signal: AbortSignal | undefined,
-  _onUpdate: unknown,
-  _ctx: unknown,
-): Promise<{
-  content: { type: "text"; text: string }[];
-  details: Record<string, unknown>;
-  isError?: boolean;
-}> {
-  const url = String(params.url || "").trim();
+  params: unknown,
+  signal: AbortSignal | undefined,
+  onUpdate: AgentToolUpdateCallback<Record<string, unknown>> | undefined,
+  _ctx: ExtensionContext,
+): Promise<AgentToolResult<WebFetchDetails>> {
+  const input = (params ?? {}) as WebFetchMdInput;
+  const url = String(input.url || "").trim();
   if (!isValidHttpUrl(url)) {
-    return {
-      content: [{ type: "text", text: `Error: URL must be http(s): ${url}` }],
-      isError: true,
-      details: { invalidUrl: url },
-    } as const;
+    throw new Error(`URL must be http(s): ${url}`);
   }
 
-  const outputMode = (params.output_mode as "auto" | "inline" | "file" | undefined) ?? "auto";
-  const absLinks = (params.abs_links as boolean | undefined) ?? true;
-  const timeoutMs = typeof params.timeout_ms === "number" ? params.timeout_ms : 30_000;
-
-  try {
-    const result = await fetchWithNegotiation(url, { timeoutMs });
-    const markdown = await resolveMarkdown(result, absLinks);
-    const lines = markdown.split("\n").length;
-    const chars = markdown.length;
-
-    const useFile = outputMode === "file" || (outputMode === "auto" && chars > INLINE_MAX_CHARS);
-
-    if (useFile) {
-      const filePath = await writeTempFile(markdown, "web-fetch-md", ".md");
-      return {
-        content: [
-          {
-            type: "text",
-            text: `Content written to ${filePath} (${chars.toLocaleString()} chars, ${lines.toLocaleString()} lines). Use the read tool to access it.`,
-          },
-        ],
-        details: { filePath, chars, lines, url: result.url },
-      };
-    }
+  const outputMode = input.output_mode ?? "auto";
+  const absLinks = input.abs_links ?? true;
+  const timeoutMs = typeof input.timeout_ms === "number" ? input.timeout_ms : 30_000;
 
+  onUpdate?.({
+    content: [{ type: "text", text: `Fetching ${url}...` }],
+    details: { url, outputMode },
+  });
+
+  const result = await fetchWithNegotiation(url, { timeoutMs, signal });
+  const markdown = await resolveMarkdown(result, absLinks);
+  const lines = markdown.split("\n").length;
+  const chars = markdown.length;
+  const details: WebFetchDetails = { chars, lines, url: result.url, outputMode };
+
+  if (shouldReturnFile(outputMode, chars)) {
+    const filePath = await writeTempFile(markdown, "web-fetch-md", ".md");
     return {
-      content: [{ type: "text", text: markdown }],
-      details: { chars, lines, url: result.url },
-    };
-  } catch (err) {
-    const message = err instanceof FetchError ? err.message : `Unexpected error: ${String(err)}`;
-    return {
-      content: [{ type: "text", text: `Error: ${message}` }],
-      isError: true,
-      details: { url, error: String(err) },
+      content: [
+        {
+          type: "text",
+          text: `Content written to ${filePath} (${chars.toLocaleString()} chars, ${lines.toLocaleString()} lines). Use the read tool to access it.`,
+        },
+      ],
+      details: { ...details, filePath },
     };
   }
+
+  const output = await limitModelVisibleOutput(markdown, {
+    tempPrefix: "web-fetch-md",
+    suffix: ".md",
+  });
+
+  return {
+    content: [{ type: "text", text: output.text }],
+    details: {
+      ...details,
+      truncation: output.truncation,
+      fullOutputPath: output.fullOutputPath,
+    },
+  };
+}
+
+function shouldReturnFile(outputMode: WebFetchOutputMode, chars: number): boolean {
+  return outputMode === "file" || (outputMode === "auto" && chars > WEB_FETCH_INLINE_MAX_CHARS);
 }
 
 async function resolveMarkdown(
@@ -111,3 +149,37 @@ async function resolveMarkdown(
   if (result.isPlainText) return wrapAsCodeBlock(result.text, result.url);
   return htmlToMarkdown(result.text, result.url, { absLinks });
 }
+
+function buildWebFetchSummary(
+  details: WebFetchDetails | undefined,
+  theme: { fg: (color: "success" | "warning" | "dim", text: string) => string },
+): string {
+  if (!details) {
+    return theme.fg("success", "Fetched web content");
+  }
+
+  if (details.filePath) {
+    return [
+      theme.fg("success", "Saved Markdown to "),
+      theme.fg("dim", details.filePath),
+      theme.fg(
+        "dim",
+        ` (${details.chars.toLocaleString()} chars, ${details.lines.toLocaleString()} lines)`,
+      ),
+    ].join("");
+  }
+
+  let summary = [
+    theme.fg("success", "Fetched Markdown"),
+    theme.fg(
+      "dim",
+      ` (${details.chars.toLocaleString()} chars, ${details.lines.toLocaleString()} lines)`,
+    ),
+  ].join("");
+
+  if (details.truncation?.truncated) {
+    summary += theme.fg("warning", " [truncated]");
+  }
+
+  return summary;
+}

package/src/tool/web-docs-fetch-guidance.ts

@@ -1,11 +0,0 @@
-// Prompt guidance and tool description for the web_docs_fetch tool.
-
-export const toolDescription = `Retrieve focused Context7 docs for a known library ID. Returns Markdown by default, or JSON snippets when \`raw: true\`.`;
-
-export const promptSnippet = "web_docs_fetch — retrieve focused Context7 docs";
-
-export const promptGuidelines = [
-  "Use web_docs_fetch once the Context7 `library_id` is known; otherwise call web_docs_search first.",
-  "Use web_docs_fetch only with Context7 library IDs such as `/facebook/react`, and ask a specific `query`.",
-  "Use web_docs_fetch with `raw: true` only when you need JSON snippet objects instead of Markdown.",
-];

package/src/tool/web-docs-search-guidance.ts

@@ -1,10 +0,0 @@
-// Prompt guidance and tool description for the web_docs_search tool.
-
-export const toolDescription = `Search Context7 for library IDs before fetching docs. Returns a Markdown table of matching libraries and metadata.`;
-
-export const promptSnippet = "web_docs_search — find Context7 library IDs before web_docs_fetch";
-
-export const promptGuidelines = [
-  "Use web_docs_search before web_docs_fetch when the Context7 `library_id` is unknown.",
-  "Use web_docs_search with both `library_name` and a descriptive `query`, then choose the best `library_id`.",
-];

package/src/tool/web-fetch-md-guidance.ts

@@ -1,41 +0,0 @@
-import { spawnSync } from "node:child_process";
-
-// Prompt guidance and tool description for the web_fetch_md tool.
-
-const INLINE_MAX_CHARS = 15_000;
-
-export const toolDescription = `Fetch a web page and convert it to Markdown.
-
-Use web_fetch_md only for public \`http://\` or \`https://\` URLs. If a page is private or access-controlled, ask for another source.
-
-Output modes:
-- \`auto\` (default): inline up to ${INLINE_MAX_CHARS.toLocaleString()} chars, otherwise return a temp file path
-- \`inline\`: always inline
-- \`file\`: always return a temp file path
-
-Links and images default to absolute; use \`abs_links: false\` to keep relative paths.`;
-
-export const promptSnippet = "web_fetch_md — fetch a public URL as Markdown";
-
-function isGhAvailable(): boolean {
-  try {
-    const result = spawnSync("gh", ["--version"], { stdio: "ignore" });
-    return result.status === 0;
-  } catch {
-    return false;
-  }
-}
-
-export function buildPromptGuidelines(): string[] {
-  const guidelines = [
-    "Use web_fetch_md only for public `http://` or `https://` pages; if a page is private or access-controlled, ask for an allowed source.",
-    "Use web_fetch_md with `output_mode: auto` by default; use `inline` for in-context Markdown and `file` for a temp path.",
-    "Use web_fetch_md with `abs_links: false` only when you want relative links or images.",
-  ];
-  if (isGhAvailable()) {
-    guidelines.push(
-      "Use bash with the `gh` CLI instead of web_fetch_md for GitHub URLs when `gh` is available.",
-    );
-  }
-  return guidelines;
-}