@aexol/spectral 0.9.58 → 0.9.60

package/CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to `@aexol/spectral` are documented here. Format follows
 
 ## [Unreleased]
 
+### Added
+
+- Added built-in `web_fetch` tool for fetching public web pages as text,
+  Markdown, or raw HTML. Includes SSRF protection, redirect handling, timeout
+  and size limits, plus unit and integration tests.
+
 ## [0.9.40] - 2026-06-22
 
 ## [0.9.39] - 2026-06-22

package/README.md

@@ -151,6 +151,49 @@ sends it anywhere. Note that `spectral serve` does **not** use this file — it
 routes inference through the backend proxy instead (see
 [How inference is routed](#how-inference-is-routed)).
 
+## Web Fetch tool
+
+Spectral ships a built-in `web_fetch` tool (enabled by default) for fetching
+public web pages and returning their content as plain text, Markdown, or raw
+HTML. It is intended for quickly reading static pages, documentation, GitHub
+repositories, JSON endpoints, and other public HTTP/HTTPS resources.
+
+### Parameters
+
+| Parameter | Type     | Default    | Description                                                                 |
+| --------- | -------- | ---------- | --------------------------------------------------------------------------- |
+| `url`     | string   | required   | Public URL to fetch. Must begin with `http://` or `https://`.               |
+| `format`  | string   | `markdown` | Output format: `text`, `markdown`, or `html`.                               |
+| `timeout` | number   | `30`       | Request timeout in seconds, clamped to the range `1`–`120`.                 |
+
+### When to use `web_fetch`
+
+Use `web_fetch` when you only need to **read** publicly available content:
+
+- Static documentation sites and README pages.
+- GitHub file, blob, or raw URLs.
+- Public JSON/XML APIs (e.g., Reddit JSON endpoints).
+- Simple marketing pages or blogs that render their main content server-side.
+
+`web_fetch` is fast, lightweight, and does not require a browser. It applies
+SSRF protection by rejecting `file://`, `ftp://`, `localhost`, and private IP
+addresses, and it limits responses to 5 MB.
+
+### When to use the Browser extension instead
+
+Use the full **Browser Automation** extension (also enabled by default) when the
+page requires a real browser:
+
+- JavaScript-rendered SPAs where the markup is produced in the browser.
+- Pages that need interaction (clicks, scrolling, form input) before the
+  relevant content appears.
+- Sites that block simple HTTP clients or require cookies / session state.
+- Screenshots, visual verification, or network-traffic inspection.
+
+The Browser extension controls a real Chromium instance via Playwright and can
+do everything `web_fetch` can, plus interaction, screenshots, and JavaScript
+evaluation.
+
 ## Multiple machines
 
 You can run `spectral serve` on as many machines as you like under one team —

package/dist/agent/index.d.ts

@@ -18,14 +18,19 @@
  *
  * Subagents use an in-process `agentLoop()` for:
  *   - Clean context isolation (fresh messages array)
- *   - Combined system prompt (main agent + subagent-specific instructions)
+ *   - Combined system prompt (shared/base prompt + subagent-specific instructions)
  *   - Tool filtering (only the tools specified in agent config)
  *   - Model selection (session model preferred, agent-configured as fallback)
  *   - Signal propagation (abort passthrough)
  *   - Access to observational memory via the recall tool
  */
 import { type ExtensionAPI } from "../sdk/coding-agent/index.js";
+import { type AgentConfig } from "./agents.js";
+import type { ServerEvent } from "../server/wire.ts";
+export declare function stripInjectedPrimaryAgentPrompt(systemPrompt: string | undefined): string | undefined;
+export declare function buildSubagentSystemPrompt(baseSystemPrompt: string | undefined, agent: Pick<AgentConfig, "name" | "systemPrompt">): string;
 export default function subagentExtension(ext: ExtensionAPI, opts?: {
     disabledAgents?: string[];
+    emitSubagentEvent?: (event: ServerEvent) => void;
 }): void;
 //# sourceMappingURL=index.d.ts.map

package/dist/agent/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAWH,OAAO,EACN,KAAK,YAAY,EAEjB,MAAM,8BAA8B,CAAC;AAsftC,MAAM,CAAC,OAAO,UAAU,iBAAiB,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,CAAC,EAAE;IAAE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CA+UvG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAYH,OAAO,EACN,KAAK,YAAY,EAEjB,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EAAE,KAAK,WAAW,EAAmC,MAAM,aAAa,CAAC;AAEhF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAsFrD,wBAAgB,+BAA+B,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CASpG;AAED,wBAAgB,yBAAyB,CACxC,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc,CAAC,GAC/C,MAAM,CAKR;AAkdD,MAAM,CAAC,OAAO,UAAU,iBAAiB,CACxC,GAAG,EAAE,YAAY,EACjB,IAAI,CAAC,EAAE;IAAE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAA;CAAE,GACpF,IAAI,CAgZN"}

package/dist/agent/index.js

@@ -18,7 +18,7 @@
  *
  * Subagents use an in-process `agentLoop()` for:
  *   - Clean context isolation (fresh messages array)
- *   - Combined system prompt (main agent + subagent-specific instructions)
+ *   - Combined system prompt (shared/base prompt + subagent-specific instructions)
  *   - Tool filtering (only the tools specified in agent config)
  *   - Model selection (session model preferred, agent-configured as fallback)
  *   - Signal propagation (abort passthrough)
@@ -40,6 +40,8 @@ import { wrapToolDefinition } from "../sdk/coding-agent/core/tools/tool-definiti
 // ---------------------------------------------------------------------------
 const MAX_PARALLEL_TASKS = 8;
 const MAX_CONCURRENCY = 4;
+const PRIMARY_AGENT_PROMPT_HEADER = "# Primary Agent:";
+const PRIMARY_AGENT_PROMPT_DELIMITER = "\n\n---\n\n";
 // ---------------------------------------------------------------------------
 // Helpers — formatting
 // ---------------------------------------------------------------------------
@@ -73,6 +75,52 @@ function formatUsageStats(usage, model) {
         parts.push(model);
     return parts.join(" ");
 }
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function textFromToolResultContent(value) {
+    if (!isRecord(value) || !Array.isArray(value.content))
+        return undefined;
+    const parts = [];
+    for (const part of value.content) {
+        if (isRecord(part) && part.type === "text" && typeof part.text === "string") {
+            parts.push(part.text);
+        }
+    }
+    const text = parts.join("").trim();
+    return text ? text : undefined;
+}
+function compactProgressMessage(value) {
+    const text = typeof value === "string" ? value.trim() : textFromToolResultContent(value);
+    if (text)
+        return text.length > 240 ? `${text.slice(0, 237)}...` : text;
+    if (isRecord(value) && typeof value.message === "string" && value.message.trim()) {
+        const message = value.message.trim();
+        return message.length > 240 ? `${message.slice(0, 237)}...` : message;
+    }
+    if (isRecord(value) && typeof value.error === "string" && value.error.trim()) {
+        const error = value.error.trim();
+        return error.length > 240 ? `${error.slice(0, 237)}...` : error;
+    }
+    return value === undefined ? undefined : "Tool progress updated";
+}
+export function stripInjectedPrimaryAgentPrompt(systemPrompt) {
+    if (!systemPrompt)
+        return systemPrompt;
+    if (!systemPrompt.startsWith(PRIMARY_AGENT_PROMPT_HEADER))
+        return systemPrompt;
+    const delimiterIndex = systemPrompt.indexOf(PRIMARY_AGENT_PROMPT_DELIMITER);
+    if (delimiterIndex === -1)
+        return undefined;
+    const basePrompt = systemPrompt.slice(delimiterIndex + PRIMARY_AGENT_PROMPT_DELIMITER.length);
+    return basePrompt.trim().length > 0 ? basePrompt : undefined;
+}
+export function buildSubagentSystemPrompt(baseSystemPrompt, agent) {
+    const sharedSystemPrompt = stripInjectedPrimaryAgentPrompt(baseSystemPrompt);
+    return sharedSystemPrompt
+        ? `${sharedSystemPrompt}\n\n---\n\nSubagent: ${agent.name}\n${agent.systemPrompt}`
+        : agent.systemPrompt;
+}
 // ---------------------------------------------------------------------------
 // Helpers — message extraction
 // ---------------------------------------------------------------------------
@@ -176,7 +224,7 @@ async function mapWithConcurrencyLimit(items, concurrency, fn) {
 // ---------------------------------------------------------------------------
 // Core — run a single subagent in-process via agentLoop
 // ---------------------------------------------------------------------------
-async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails, ext, ctx) {
+async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails, parentToolCallId, onInternalEvent, ext, ctx) {
     const normalizedAgentName = agentName.replace(/^@/, "");
     const agent = agents.find((a) => a.name === normalizedAgentName);
     if (!agent) {
@@ -192,11 +240,9 @@ async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, si
             step,
         };
     }
-    // Build combined system prompt: main agent's + subagent's
-    const mainSystemPrompt = ctx.getSystemPrompt();
-    const combinedPrompt = mainSystemPrompt
-        ? `${mainSystemPrompt}\n\n---\n\nSubagent: ${agent.name}\n${agent.systemPrompt}`
-        : agent.systemPrompt;
+    // Build combined system prompt without leaking an injected primary-agent
+    // block into the isolated subagent context.
+    const combinedPrompt = buildSubagentSystemPrompt(ctx.getSystemPrompt(), agent);
     // Apply system prompt mutation if enabled in settings (opt-in)
     let effectivePrompt = combinedPrompt;
     if (ctx.settingsManager) {
@@ -259,11 +305,19 @@ async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, si
     };
     // Accumulated streaming text from text_delta events (reset per assistant turn).
     let streamingText = "";
+    // Accumulated thinking deltas for the live subagent sheet. This stays outside
+    // final `SingleResult` so the public subagent tool_result contract is unchanged.
+    let thinkingText = "";
     const emitUpdate = () => {
         if (onUpdate) {
+            const liveResult = {
+                ...currentResult,
+                ...(streamingText ? { streamingText } : {}),
+                ...(thinkingText ? { thinkingText } : {}),
+            };
             onUpdate({
-                content: [{ type: "text", text: getFinalOutput(currentResult.messages) || streamingText || "(running...)" }],
-                details: makeDetails([currentResult]),
+                content: [{ type: "text", text: getFinalOutput(currentResult.messages) || streamingText || (thinkingText ? "(thinking...)" : "(running...)") }],
+                details: makeDetails([liveResult]),
             });
         }
     };
@@ -288,14 +342,19 @@ async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, si
                 hadError = true;
                 break;
             }
+            onInternalEvent?.(event, parentToolCallId);
             if (event.type === "message_update" && event.message?.role === "assistant") {
-                // Forward streaming text deltas so the UI can show the subagent's
-                // response as it's generated, not just the final result.
+                // Forward streaming text/thinking deltas so the UI can show the
+                // subagent process as it's generated, not just the final result.
                 const inner = event.assistantMessageEvent;
                 if (inner?.type === "text_delta" && inner.delta) {
                     streamingText += inner.delta;
                     emitUpdate();
                 }
+                else if (inner?.type === "thinking_delta" && inner.delta) {
+                    thinkingText += inner.delta;
+                    emitUpdate();
+                }
                 continue;
             }
             if (event.type === "message_end" && event.message) {
@@ -451,6 +510,66 @@ export default function subagentExtension(ext, opts) {
                 projectAgentsDir: discovery.projectAgentsDir,
                 results,
             });
+            // Forward internal subagent tool lifecycle events to the bridge so the
+            // frontend sheet can show a live activity log. text_delta streaming
+            // still flows through the existing onUpdate/subagent_progress path.
+            const emitSubagentEvent = opts?.emitSubagentEvent;
+            const subagentStepStartedAt = new Map();
+            const subagentStepArgs = new Map();
+            const emitSubagentToolProgress = emitSubagentEvent
+                ? (event, parentToolCallId) => {
+                    if (event.type === "tool_execution_start") {
+                        const startedAt = Date.now();
+                        subagentStepStartedAt.set(event.toolCallId, startedAt);
+                        subagentStepArgs.set(event.toolCallId, event.args);
+                        emitSubagentEvent({
+                            type: "subagent_tool_progress",
+                            toolCallId: parentToolCallId,
+                            stepId: event.toolCallId,
+                            name: event.toolName,
+                            args: event.args,
+                            status: "running",
+                            startedAt,
+                        });
+                    }
+                    else if (event.type === "tool_execution_update") {
+                        const startedAt = subagentStepStartedAt.get(event.toolCallId) ?? Date.now();
+                        subagentStepStartedAt.set(event.toolCallId, startedAt);
+                        subagentStepArgs.set(event.toolCallId, event.args);
+                        emitSubagentEvent({
+                            type: "subagent_tool_progress",
+                            toolCallId: parentToolCallId,
+                            stepId: event.toolCallId,
+                            name: event.toolName,
+                            args: event.args,
+                            status: "running",
+                            partialResult: event.partialResult,
+                            message: compactProgressMessage(event.partialResult),
+                            startedAt,
+                        });
+                    }
+                    else if (event.type === "tool_execution_end") {
+                        const startedAt = subagentStepStartedAt.get(event.toolCallId) ?? Date.now();
+                        const finishedAt = Date.now();
+                        const args = subagentStepArgs.get(event.toolCallId);
+                        subagentStepStartedAt.delete(event.toolCallId);
+                        subagentStepArgs.delete(event.toolCallId);
+                        emitSubagentEvent({
+                            type: "subagent_tool_progress",
+                            toolCallId: parentToolCallId,
+                            stepId: event.toolCallId,
+                            name: event.toolName,
+                            args,
+                            status: event.isError ? "error" : "success",
+                            result: event.result,
+                            isError: event.isError,
+                            message: event.isError ? compactProgressMessage(event.result) : undefined,
+                            startedAt,
+                            finishedAt,
+                        });
+                    }
+                }
+                : undefined;
             if (modeCount !== 1) {
                 const available = agents.map((a) => `${a.name} (${a.source})`).join(", ") || "none";
                 return {
@@ -513,7 +632,7 @@ export default function subagentExtension(ext, opts) {
                             }
                         }
                         : undefined;
-                    const result = await runSingleAgent(ctx.cwd, agents, step.agent, taskWithContext, step.cwd, i + 1, signal, chainUpdate, makeDetails("chain"), ext, ctx);
+                    const result = await runSingleAgent(ctx.cwd, agents, step.agent, taskWithContext, step.cwd, i + 1, signal, chainUpdate, makeDetails("chain"), _toolCallId, emitSubagentToolProgress, ext, ctx);
                     results.push(result);
                     const isError = result.exitCode !== 0 ||
                         result.stopReason === "error" ||
@@ -591,7 +710,7 @@ export default function subagentExtension(ext, opts) {
                             allResults[index] = partial.details.results[0];
                             emitParallelUpdate();
                         }
-                    }, makeDetails("parallel"), ext, ctx);
+                    }, makeDetails("parallel"), _toolCallId, emitSubagentToolProgress, ext, ctx);
                     allResults[index] = result;
                     emitParallelUpdate();
                     return result;
@@ -614,7 +733,7 @@ export default function subagentExtension(ext, opts) {
             }
             // ── Single mode ─────────────────────────────────────────────
             if (params.agent && params.task) {
-                const result = await runSingleAgent(ctx.cwd, agents, params.agent, params.task, params.cwd, undefined, signal, onUpdate, makeDetails("single"), ext, ctx);
+                const result = await runSingleAgent(ctx.cwd, agents, params.agent, params.task, params.cwd, undefined, signal, onUpdate, makeDetails("single"), _toolCallId, emitSubagentToolProgress, ext, ctx);
                 const isError = result.exitCode !== 0 ||
                     result.stopReason === "error" ||
                     result.stopReason === "aborted";

package/dist/extensions/kanban-bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kanban-bridge.d.ts","sourceRoot":"","sources":["../../src/extensions/kanban-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAoC,MAAM,8BAA8B,CAAC;AA09BnG,wBAA8B,qBAAqB,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAoCpF"}
+{"version":3,"file":"kanban-bridge.d.ts","sourceRoot":"","sources":["../../src/extensions/kanban-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAoC,MAAM,8BAA8B,CAAC;AAg/BnG,wBAA8B,qBAAqB,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAoCpF"}

package/dist/extensions/kanban-bridge.js

@@ -188,6 +188,8 @@ async function deleteKanbanTask(opts, taskId) {
 import { getApiUrl, getConfigFile, readConfig } from "../config.js";
 import { readStudioBinding } from "../studio-binding.js";
 import { ensureAuthenticated, runOAuthFlow } from "../auth-helper.js";
+import { loadMachine } from "../relay/machine-store.js";
+import { isJwtExpired } from "../relay/registration.js";
 import { stat } from "node:fs/promises";
 import { join } from "node:path";
 // Track whether we've already attempted reauth in this session to avoid loops
@@ -245,7 +247,25 @@ async function resolveKanbanConfig(explicitProjectId, cwd) {
         }
         process.stderr.write(`[kanban-bridge] OAuth failed: ${oauthResult.reason}. Kanban calls will likely fail.\n`);
     }
-    const token = cfg.userJwt || cfg.teamApiKey || "";
+    // Prefer machine JWT (long-lived, no browser OAuth needed)
+    // Falls back to user JWT / team API key for non-serve contexts
+    let token = "";
+    let tokenSource = "";
+    const machine = await loadMachine();
+    if (machine?.machineJwt && !isJwtExpired(machine.machineJwt)) {
+        token = machine.machineJwt;
+        tokenSource = "machine-jwt";
+        process.stderr.write(`[kanban-bridge] Using machine JWT (machine: ${machine.machineName}, team: ${machine.teamId ?? "unknown"}).\n`);
+    }
+    else {
+        token = cfg.userJwt || cfg.teamApiKey || "";
+        if (cfg.userJwt) {
+            tokenSource = "user-jwt";
+        }
+        else if (cfg.teamApiKey) {
+            tokenSource = "team-api-key";
+        }
+    }
     if (!token) {
         if (!_reauthAttempted) {
             _reauthAttempted = true;

package/dist/extensions/web/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Web Fetch native extension for Spectral.
+ *
+ * Registers a single tool, `web_fetch`, which fetches a public URL and returns
+ * its content as text, markdown, or raw HTML. The model provides URLs itself;
+ * there is no search capability.
+ */
+import type { ExtensionAPI } from "../../sdk/coding-agent/index.js";
+export default function webExtension(ext: ExtensionAPI): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/extensions/web/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/extensions/web/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAGpE,wBAA8B,YAAY,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ3E"}

package/dist/extensions/web/index.js

@@ -0,0 +1,11 @@
+import { registerWebFetchTool } from "./tools/fetch.js";
+export default async function webExtension(ext) {
+    try {
+        registerWebFetchTool(ext);
+        process.stderr.write("[web] Registered web_fetch tool.\n");
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[web] Failed to register web_fetch tool: ${msg}\n`);
+    }
+}

package/dist/extensions/web/tools/fetch.d.ts

@@ -0,0 +1,3 @@
+import type { ExtensionAPI } from "../../../sdk/coding-agent/index.js";
+export declare function registerWebFetchTool(ext: ExtensionAPI): void;
+//# sourceMappingURL=fetch.d.ts.map

package/dist/extensions/web/tools/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../../../src/extensions/web/tools/fetch.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAmB,YAAY,EAAkB,MAAM,oCAAoC,CAAC;AA+BxG,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CA2D5D"}

package/dist/extensions/web/tools/fetch.js

@@ -0,0 +1,80 @@
+/**
+ * web_fetch tool definition.
+ */
+import { Type } from "typebox";
+import { truncateTail } from "../../../sdk/coding-agent/core/tools/truncate.js";
+import { fetchWebPage, WebFetchError } from "../utils/fetcher.js";
+import { convertContent } from "../utils/parser.js";
+const MAX_OUTPUT_LINES = 4000;
+const MAX_OUTPUT_BYTES = 200 * 1024; // 200 KB
+const webFetchSchema = Type.Object({
+    url: Type.String({
+        description: "The URL to fetch. Must begin with http:// or https://.",
+        pattern: "^https?://",
+    }),
+    format: Type.Optional(Type.Union([Type.Literal("text"), Type.Literal("markdown"), Type.Literal("html"), Type.Literal("json")], {
+        default: "markdown",
+        description: "Output format: text, markdown (default), html, or json.",
+    })),
+    timeout: Type.Optional(Type.Number({
+        default: 30,
+        minimum: 1,
+        maximum: 120,
+        description: "Request timeout in seconds (default 30, maximum 120).",
+    })),
+});
+export function registerWebFetchTool(ext) {
+    const tool = {
+        name: "web_fetch",
+        label: "Web Fetch",
+        description: "Fetch a public URL and return its content as readable text, markdown, raw HTML, or pretty JSON. " +
+            "Useful for reading documentation, GitHub pages, Reddit JSON endpoints, and other web content. " +
+            "Supports HTTP/HTTPS only and rejects binary content.",
+        promptSnippet: "`web_fetch { url, format?, timeout? }` — fetch a web page as markdown/text/HTML/JSON",
+        parameters: webFetchSchema,
+        async execute(_toolCallId, params, signal, _onUpdate, _ctx) {
+            const { url, format = "markdown", timeout = 30 } = params;
+            try {
+                const fetchResult = await fetchWebPage(url, {
+                    timeoutSeconds: timeout,
+                    signal,
+                });
+                const converted = await convertContent(fetchResult.content, format);
+                const truncation = truncateTail(converted, {
+                    maxLines: MAX_OUTPUT_LINES,
+                    maxBytes: MAX_OUTPUT_BYTES,
+                });
+                const output = truncation.content;
+                const truncationNotice = truncation.truncated
+                    ? `\n\n[Output truncated: exceeded ${truncation.truncatedBy === "bytes" ? `${MAX_OUTPUT_BYTES} bytes` : `${MAX_OUTPUT_LINES} lines`}. Original size: ${truncation.totalBytes} bytes, ${truncation.totalLines} lines.]`
+                    : "";
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `✓ Fetched ${fetchResult.finalUrl}\nContent-Type: ${fetchResult.contentType || "unknown"}\nFormat: ${format}\nSize: ${fetchResult.contentLengthBytes} bytes${truncationNotice}\n\n${output}`,
+                        },
+                    ],
+                    details: {
+                        isError: false,
+                        url: fetchResult.finalUrl,
+                        contentType: fetchResult.contentType,
+                        format,
+                        output,
+                        truncated: truncation.truncated,
+                        truncatedBy: truncation.truncatedBy,
+                    },
+                };
+            }
+            catch (err) {
+                const reason = err instanceof WebFetchError || err instanceof Error ? err.message : String(err);
+                const message = `Unable to fetch ${url}: ${reason}`;
+                return {
+                    content: [{ type: "text", text: `❌ ${message}` }],
+                    details: { isError: true, message },
+                };
+            }
+        },
+    };
+    ext.registerTool(tool);
+}

package/dist/extensions/web/utils/fetcher.d.ts

@@ -0,0 +1,34 @@
+export declare class WebFetchError extends Error {
+    constructor(message: string);
+}
+export interface WebFetchOptions {
+    timeoutSeconds?: number;
+    signal?: AbortSignal;
+    userAgent?: string;
+    /**
+     * Bypass SSRF private-host/IP blocking. Used only by tests that spin up a
+     * local mock HTTP server; never exposed through the `web_fetch` tool schema.
+     */
+    allowPrivateHosts?: boolean;
+}
+export interface WebFetchResult {
+    url: string;
+    finalUrl: string;
+    contentType: string;
+    content: string;
+    contentLengthBytes: number;
+}
+/**
+ * Validate a URL with SSRF protection.
+ *
+ * Throws WebFetchError for invalid URLs, non-http(s) protocols, blocked
+ * hostnames, or hostnames that resolve to private IP addresses.
+ */
+export declare function validateUrl(urlStr: string, allowPrivateHosts?: boolean): Promise<URL>;
+/** Validate that the Content-Type is readable text, not binary media. */
+export declare function validateContentType(contentType: string): void;
+/**
+ * Fetch a public URL and return its decoded text content.
+ */
+export declare function fetchWebPage(url: string, opts?: WebFetchOptions): Promise<WebFetchResult>;
+//# sourceMappingURL=fetcher.d.ts.map

package/dist/extensions/web/utils/fetcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetcher.d.ts","sourceRoot":"","sources":["../../../../src/extensions/web/utils/fetcher.ts"],"names":[],"mappings":"AASA,qBAAa,aAAc,SAAQ,KAAK;gBAC1B,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,eAAe;IAC9B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAuDD;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,MAAM,EACd,iBAAiB,UAAQ,GACxB,OAAO,CAAC,GAAG,CAAC,CAoDd;AAcD,yEAAyE;AACzE,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CA+C7D;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,eAAoB,GACzB,OAAO,CAAC,cAAc,CAAC,CAoIzB"}