@kenkaiiii/ggcoder 5.48.0 → 5.49.1

package/dist/tools/tool-search.js

@@ -1,4 +1,6 @@
 import { z } from "zod";
+import { resolveToolSchema } from "@kenkaiiii/gg-ai";
+import { CONTEXT_LIMITS } from "../core/context-limits.js";
 const ToolSearchParams = z.object({
     query: z
         .string()
@@ -15,7 +17,7 @@ const ToolSearchParams = z.object({
  * learns *now* whether the capability really exists, instead of promoting a
  * tool that will fail on first call. Returns undefined for already-live tools.
  */
-export function createToolSearchTool(catalog, onPromote, resolveCached) {
+export function createToolSearchTool(catalog, onPromote, resolveCached, limits = CONTEXT_LIMITS) {
     return {
         name: "tool_search",
         description: "Load a tool that is listed as available on demand. Searches the catalog of " +
@@ -31,7 +33,26 @@ export function createToolSearchTool(catalog, onPromote, resolveCached) {
                     ? "No tools matched and the catalog is empty — every catalog tool is already available."
                     : `No tools matched "${query}". Still in the catalog: ${remaining.join(", ")}`;
             }
-            const promoted = catalog.promote(matches.map((t) => t.name));
+            // Schema budget, fail closed: a tool whose serialized input schema exceeds
+            // the budget is NOT promoted — promoting it would bill those bytes on every
+            // subsequent request. The user can raise contextLimits.mcpToolSchemaBytes.
+            const oversized = [];
+            const promotable = [];
+            for (const tool of matches) {
+                const bytes = Buffer.byteLength(JSON.stringify(resolveToolSchema(tool)), "utf8");
+                if (bytes > limits.mcpToolSchemaBytes)
+                    oversized.push({ name: tool.name, bytes });
+                else
+                    promotable.push(tool);
+            }
+            if (promotable.length === 0) {
+                const details = oversized
+                    .map((t) => `- ${t.name}: schema is ${Math.round(t.bytes / 1024)}KB (budget ${Math.round(limits.mcpToolSchemaBytes / 1024)}KB)`)
+                    .join("\n");
+                return (`No tools promoted — every match exceeds the schema byte budget.\n${details}\n` +
+                    `Raise the contextLimits.mcpToolSchemaBytes setting if this tool is trusted.`);
+            }
+            const promoted = catalog.promote(promotable.map((t) => t.name));
             onPromote(promoted);
             const unavailable = new Map();
             if (resolveCached) {
@@ -48,7 +69,11 @@ export function createToolSearchTool(catalog, onPromote, resolveCached) {
             }
             const lines = available.map((t) => `- ${t.name}: ${t.description.split("\n")[0].slice(0, 200)}`);
             const body = `${available.length} tool(s) now available:\n${lines.join("\n")}`;
-            return failures.length > 0 ? `${body}\n\nUnreachable:\n${failures.join("\n")}` : body;
+            const refused = oversized.length > 0
+                ? `\n\nRefused (schema byte budget):\n${oversized.map((t) => `- ${t.name} (${Math.round(t.bytes / 1024)}KB schema)`).join("\n")}\nRaise the contextLimits.mcpToolSchemaBytes setting if a refused tool is trusted.`
+                : "";
+            const unreachable = failures.length > 0 ? `\n\nUnreachable:\n${failures.join("\n")}` : "";
+            return `${body}${refused}${unreachable}`;
         },
     };
 }

package/dist/tools/tool-search.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-search.js","sourceRoot":"","sources":["../../src/tools/tool-search.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tool-search.js","sourceRoot":"","sources":["../../src/tools/tool-search.ts"],"names":[],"mappings":"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"}

package/dist/tools/tool-search.test.js

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 import { z } from "zod";
+import { resolveContextLimits } from "../core/context-limits.js";
 import { DeferredToolCatalog } from "../core/mcp/deferred-catalog.js";
 import { createToolSearchTool } from "./tool-search.js";
 const CONTEXT = {};
@@ -65,5 +66,62 @@ describe("tool_search", () => {
         const tool = createToolSearchTool(catalog, () => { });
         expect(await search(tool, "design screenshots")).toContain("1 tool(s) now available");
     });
+    it("refuses promotion of a tool whose schema exceeds the byte budget", async () => {
+        const catalog = new DeferredToolCatalog();
+        const huge = z.object({
+            blob: z.string().describe("x".repeat(200 * 1024)), // 200KB serialized schema
+        });
+        catalog.add([
+            {
+                name: "mcp__big__blob",
+                description: "fetch design screenshots",
+                parameters: huge,
+                execute: async () => "ok",
+            },
+            stub("mcp__figma__get_screens", "fetch design screenshots"),
+        ]);
+        const promotedNames = [];
+        const tool = createToolSearchTool(catalog, (tools) => promotedNames.push(...tools.map((t) => t.name)));
+        const result = await search(tool, "design screenshots");
+        // The fit tool promoted; the oversized one was refused and named.
+        expect(result).toContain("1 tool(s) now available");
+        expect(result).toContain("mcp__figma__get_screens");
+        expect(result).toContain("Refused (schema byte budget)");
+        expect(result).toContain("mcp__big__blob");
+        expect(result).toContain("contextLimits.mcpToolSchemaBytes");
+        expect(promotedNames).toEqual(["mcp__figma__get_screens"]);
+        // Refused tool stays in the catalog, not the live toolset.
+        expect(catalog.names()).toContain("mcp__big__blob");
+    });
+    it("fails closed when EVERY match exceeds the schema budget", async () => {
+        const catalog = new DeferredToolCatalog();
+        catalog.add([
+            {
+                name: "mcp__big__blob",
+                description: "fetch design screenshots",
+                parameters: z.object({ blob: z.string().describe("x".repeat(200 * 1024)) }),
+                execute: async () => "ok",
+            },
+        ]);
+        const promotedNames = [];
+        const tool = createToolSearchTool(catalog, (tools) => promotedNames.push(...tools.map((t) => t.name)));
+        const result = await search(tool, "design screenshots");
+        expect(result).toContain("No tools promoted");
+        expect(result).toContain("mcp__big__blob");
+        expect(promotedNames).toEqual([]);
+    });
+    it("honors a raised schema budget from limits", async () => {
+        const catalog = new DeferredToolCatalog();
+        catalog.add([
+            {
+                name: "mcp__big__blob",
+                description: "fetch design screenshots",
+                parameters: z.object({ blob: z.string().describe("x".repeat(8 * 1024)) }), // ~8KB
+                execute: async () => "ok",
+            },
+        ]);
+        const tool = createToolSearchTool(catalog, () => { }, undefined, resolveContextLimits({ mcpToolSchemaBytes: 16 * 1024 }));
+        expect(await search(tool, "design screenshots")).toContain("1 tool(s) now available");
+    });
 });
 //# sourceMappingURL=tool-search.test.js.map

package/dist/tools/tool-search.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-search.test.js","sourceRoot":"","sources":["../../src/tools/tool-search.test.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tool-search.test.js","sourceRoot":"","sources":["../../src/tools/tool-search.test.ts"],"names":[],"mappings":"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"}

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

@@ -7,6 +7,11 @@ import { type GetNetworkPolicy } from "../core/network-guard.js";
  */
 export declare function isBlockedUrl(urlString: string): boolean;
 export declare function htmlToCleanText(html: string): string;
+/** A hyperlink shown in an outline render as `anchor text [number]`. */
+export interface OutlineLink {
+    number: number;
+    url: string;
+}
 type LlmsCandidateKind = "llms" | "llms-full" | "llms-ctx" | "page-md";
 interface LlmsCandidate {
     url: string;
@@ -20,11 +25,13 @@ export declare function createWebFetchTool(getNetworkPolicy?: GetNetworkPolicy):
 declare const parameters: z.ZodObject<{
     url: z.ZodOptional<z.ZodString>;
     urls: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    follow: z.ZodOptional<z.ZodNumber>;
     max_length: z.ZodOptional<z.ZodNumber>;
     format: z.ZodOptional<z.ZodEnum<{
         text: "text";
         html: "html";
         markdown: "markdown";
+        outline: "outline";
     }>>;
     prefer_llms_txt: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;

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

@@ -1 +1 @@
-{"version":3,"file":"web-fetch.d.ts","sourceRoot":"","sources":["../../src/tools/web-fetch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,qBAAqB,CAAC;AAIlE,OAAO,EAAkB,KAAK,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjF;;;GAGG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CA0CvD;AAmGD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAYpD;AAwBD,KAAK,iBAAiB,GAAG,MAAM,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,CAAC;AAEvE,UAAU,aAAa;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,iBAAiB,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;CAClB;AA8HD,wBAAsB,eAAe,CACnC,QAAQ,EAAE,QAAQ,EAClB,QAAQ,SAAqB,GAC5B,OAAO,CAAC,UAAU,CAAC,CA2BrB;AAqLD,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,aAAa,EAAE,CAuCnF;AA2ED,wBAAgB,kBAAkB,CAChC,gBAAgB,CAAC,EAAE,gBAAgB,GAClC,SAAS,CAAC,OAAO,UAAU,CAAC,CAuC9B;AA0BD,QAAA,MAAM,UAAU;;;;;;;;;;iBAoBZ,CAAC"}
+{"version":3,"file":"web-fetch.d.ts","sourceRoot":"","sources":["../../src/tools/web-fetch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,qBAAqB,CAAC;AAIlE,OAAO,EAAkB,KAAK,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjF;;;GAGG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CA0CvD;AAmGD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAYpD;AAcD,wEAAwE;AACxE,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;CACb;AA6MD,KAAK,iBAAiB,GAAG,MAAM,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,CAAC;AAEvE,UAAU,aAAa;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,iBAAiB,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAkID,wBAAsB,eAAe,CACnC,QAAQ,EAAE,QAAQ,EAClB,QAAQ,SAAqB,GAC5B,OAAO,CAAC,UAAU,CAAC,CA2BrB;AAwLD,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,aAAa,EAAE,CAuCnF;AA2HD,wBAAgB,kBAAkB,CAChC,gBAAgB,CAAC,EAAE,gBAAgB,GAClC,SAAS,CAAC,OAAO,UAAU,CAAC,CA8E9B;AA0BD,QAAA,MAAM,UAAU;;;;;;;;;;;;iBAyCb,CAAC"}

package/dist/tools/web-fetch.js

@@ -142,6 +142,184 @@ export function htmlToCleanText(html) {
         .replace(/\n{3,}/g, "\n\n")
         .trim();
 }
+// ── Outline rendering (compact numbered view) ────────────────
+/** Hard cap on how many links one tool call will number. */
+const MAX_OUTLINE_LINKS = 100;
+/** ~500 tokens of body: the whole point of the outline format. */
+const OUTLINE_DEFAULT_MAX_LENGTH = 2000;
+/** Per-session render cache size (pages, not bytes). */
+const MAX_CACHED_PAGES = 32;
+const OUTLINE_INDEX_HEADER = "Links (fetch one with `follow`):";
+const BLOCKED_URL_MESSAGE = "Error: URL blocked — requests to private/internal network addresses are not allowed.";
+/**
+ * Allocates the small stable numbers that replace hyperlinks in an outline
+ * render. Scoped to a single tool call, deduped by absolute URL, and capped at
+ * {@link MAX_OUTLINE_LINKS} so a link-farm page cannot grow the index (or the
+ * session's follow map) without bound.
+ */
+class LinkNumbers {
+    byUrl = new Map();
+    used = new Set();
+    ordered = [];
+    next = 1;
+    get size() {
+        return this.byUrl.size;
+    }
+    /** Adopt the numbers baked into a cached render so they stay resolvable. */
+    reserve(links) {
+        for (const link of links) {
+            if (this.used.has(link.number))
+                continue;
+            this.used.add(link.number);
+            this.byUrl.set(link.url, link.number);
+            this.ordered.push(link);
+        }
+    }
+    /** Number for `url`, or null once the per-call cap is reached. */
+    numberFor(url) {
+        const existing = this.byUrl.get(url);
+        if (existing !== undefined)
+            return existing;
+        if (this.byUrl.size >= MAX_OUTLINE_LINKS)
+            return null;
+        while (this.used.has(this.next))
+            this.next++;
+        const number = this.next++;
+        this.used.add(number);
+        this.byUrl.set(url, number);
+        this.ordered.push({ number, url });
+        return number;
+    }
+    all() {
+        return this.ordered;
+    }
+}
+/** Absolute http(s) form of `href` relative to `base`, or null if unusable. */
+function absoluteHttpUrl(href, base) {
+    const trimmed = href.trim();
+    if (!trimmed || trimmed.startsWith("#"))
+        return null;
+    let resolved;
+    try {
+        resolved = new URL(trimmed, base);
+    }
+    catch {
+        return null;
+    }
+    if (resolved.protocol !== "http:" && resolved.protocol !== "https:")
+        return null;
+    // Fragments only move within a page we already have: drop them so anchors
+    // into the same document collapse onto one number, and spend no number at
+    // all on links back into the page being rendered.
+    resolved.hash = "";
+    let self;
+    try {
+        self = new URL(base);
+    }
+    catch {
+        return resolved.toString();
+    }
+    self.hash = "";
+    if (resolved.href === self.href)
+        return null;
+    return resolved.href;
+}
+const MARKDOWN_LINK = /(!?)\[([^\]]*)\]\(\s*<?([^)<>\s]*)>?(?:\s+"[^"]*")?\s*\)/g;
+const HTML_ANCHOR = /<a\b[^>]*\bhref\s*=\s*["']([^"']*)["'][^>]*>([\s\S]*?)<\/a>/gi;
+/** Rewrite markdown links to `text [n]`; drop images, which carry no text. */
+function numberMarkdownLinks(markdown, base, numbers) {
+    return markdown.replace(MARKDOWN_LINK, (_match, image, text, href) => {
+        if (image)
+            return "";
+        const url = absoluteHttpUrl(href, base);
+        if (!url)
+            return text;
+        const number = numbers.numberFor(url);
+        return number === null ? text : `${text} [${number}]`;
+    });
+}
+/** Same rewrite for raw HTML, used when the markdown extractor is unavailable. */
+function numberHtmlAnchors(html, base, numbers) {
+    return html.replace(HTML_ANCHOR, (_match, href, inner) => {
+        const url = absoluteHttpUrl(decodeHTMLEntities(href), base);
+        if (!url)
+            return inner;
+        const number = numbers.numberFor(url);
+        return number === null ? inner : `${inner} [${number}]`;
+    });
+}
+function compactBlankLines(text) {
+    return text
+        .split("\n")
+        .map((line) => line.replace(/[ \t]+$/, ""))
+        .join("\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}
+/**
+ * Render a fetched document as main content with every hyperlink replaced by a
+ * number, followed by a compact number → absolute URL index. The body reuses
+ * the existing `max_length` budget; only links still visible in the (possibly
+ * truncated) body are indexed.
+ */
+async function renderOutline(text, isHtml, finalUrl, opts) {
+    const numbers = opts.numbers ?? new LinkNumbers();
+    let heading = "";
+    let body;
+    if (!isHtml) {
+        body = numberMarkdownLinks(text, finalUrl, numbers);
+    }
+    else {
+        let extracted;
+        try {
+            extracted = await extractToMarkdown(text, finalUrl);
+        }
+        catch {
+            extracted = null;
+        }
+        if (extracted) {
+            heading = extracted.title ? `# ${extracted.title}\n\n` : "";
+            body = numberMarkdownLinks(extracted.markdown, finalUrl, numbers);
+        }
+        else {
+            body = htmlToCleanText(numberHtmlAnchors(removeBoilerplateElements(text), finalUrl, numbers));
+        }
+    }
+    const rendered = truncate(compactBlankLines(heading + body), opts.maxLength);
+    const shown = numbers.all().filter((link) => rendered.includes(`[${link.number}]`));
+    let output = rendered;
+    if (shown.length > 0) {
+        const index = shown.map((link) => `[${link.number}] ${link.url}`).join("\n");
+        output += `\n\n${OUTLINE_INDEX_HEADER}\n${index}`;
+        if (numbers.size >= MAX_OUTLINE_LINKS) {
+            output += `\n[link index truncated at ${MAX_OUTLINE_LINKS}; further links left as plain text]`;
+        }
+    }
+    opts.onRender?.(finalUrl, output, [...shown]);
+    return output;
+}
+function cacheKey(url, maxLength) {
+    return `${maxLength}\u0000${url}`;
+}
+function cacheGet(cache, key) {
+    const hit = cache.get(key);
+    if (!hit)
+        return undefined;
+    // Re-insert so Map iteration order stays least-recently-used first.
+    cache.delete(key);
+    cache.set(key, hit);
+    return hit;
+}
+function cacheSet(cache, key, entry) {
+    cache.delete(key);
+    cache.set(key, entry);
+    while (cache.size > MAX_CACHED_PAGES) {
+        const oldest = cache.keys().next();
+        if (oldest.done)
+            break;
+        cache.delete(oldest.value);
+    }
+}
 // ── Fetch configuration ──────────────────────────────────────
 const MAX_REDIRECTS = 5;
 const MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
@@ -165,7 +343,7 @@ const DEFAULT_LLMS_CANDIDATE_LIMIT = 6;
  * error string describing why the fetch could not complete.
  */
 function headersForFormat(format, honestUserAgent = false) {
-    const accept = format === "html"
+    const accept = format === "html" || format === "outline"
         ? "text/html,application/xhtml+xml;q=0.9,*/*;q=0.5"
         : format === "markdown"
             ? "text/markdown,text/plain;q=0.9,text/html;q=0.8,*/*;q=0.5"
@@ -324,6 +502,9 @@ async function processHtmlOrText(response, text, opts) {
         /application\/octet-stream|binary\/octet-stream|text\/plain/i.test(response.contentType);
     const isHtml = response.contentType.includes("html") ||
         (genericContentType && /^(?:<!doctype\s+html|<html\b|<head\b|<body\b)/i.test(prefix));
+    if (opts.format === "outline") {
+        return await renderOutline(text, isHtml, response.finalUrl, opts);
+    }
     if (opts.format === "html") {
         return truncate(text, opts.maxLength);
     }
@@ -352,7 +533,7 @@ async function processHtmlOrText(response, text, opts) {
  */
 async function fetchAndProcess(url, opts, signal) {
     if (isBlockedUrl(url)) {
-        return "Error: URL blocked — requests to private/internal network addresses are not allowed.";
+        return BLOCKED_URL_MESSAGE;
     }
     try {
         const result = await fetchOne(url, signal, opts.format, opts.getNetworkPolicy);
@@ -519,27 +700,98 @@ async function tryLlmsResource(url, opts, signal) {
     return probes.find((probe) => probe !== null) ?? null;
 }
 async function fetchWithPreferredDocs(url, opts, signal) {
-    if (opts.format !== "html" && opts.preferLlmsTxt && !isBlockedUrl(url) && isDocish(url)) {
+    if (opts.format !== "html" &&
+        opts.format !== "outline" &&
+        opts.preferLlmsTxt &&
+        !isBlockedUrl(url) &&
+        isDocish(url)) {
         const llms = await tryLlmsResource(url, opts, signal);
         if (llms)
             return llms;
     }
     return await fetchAndProcess(url, opts, signal);
 }
+/**
+ * Outline-mode wrapper around {@link fetchWithPreferredDocs} that serves
+ * repeat views of a page from the per-session cache. The URL is re-validated
+ * *before* the cache is consulted, so a cached render can never resurrect a
+ * host the current SSRF/allowlist policy forbids.
+ */
+async function fetchPage(url, opts, signal, cache) {
+    if (opts.format !== "outline")
+        return await fetchWithPreferredDocs(url, opts, signal);
+    if (isBlockedUrl(url))
+        return BLOCKED_URL_MESSAGE;
+    const policyError = checkUrlPolicy(url, opts.getNetworkPolicy);
+    if (policyError)
+        return `Error: ${policyError}`;
+    const requestKey = cacheKey(url, opts.maxLength);
+    const hit = cacheGet(cache, requestKey);
+    if (hit) {
+        opts.numbers?.reserve(hit.links);
+        return hit.text;
+    }
+    let rendered;
+    const result = await fetchWithPreferredDocs(url, {
+        ...opts,
+        onRender: (finalUrl, text, links) => {
+            rendered = { text, links };
+            // Keyed by the post-redirect URL, plus the requested URL below.
+            cacheSet(cache, cacheKey(finalUrl, opts.maxLength), rendered);
+        },
+    }, signal);
+    if (rendered)
+        cacheSet(cache, requestKey, rendered);
+    return result;
+}
 export function createWebFetchTool(getNetworkPolicy) {
+    // Per-session state, both bounded: the render cache evicts least-recently
+    // used pages past MAX_CACHED_PAGES, and the follow map is replaced (not
+    // grown) by each outline call, itself capped at MAX_OUTLINE_LINKS entries.
+    const pageCache = new Map();
+    let followTargets = new Map();
     return {
         name: "web_fetch",
         description: "Fetch and read web page content. Accepts a single `url` or a `urls` array (up to 10, " +
-            "fetched concurrently). Returns clean Markdown by default (`format`: markdown|text|html) via " +
-            "main-content extraction. Extracts text from PDFs, follows safe redirects automatically, and " +
-            "prefers a site's curated /llms.txt for docs pages when available.",
+            "fetched concurrently). Returns clean Markdown by default (`format`: markdown|text|html|outline) " +
+            "via main-content extraction. Extracts text from PDFs, follows safe redirects automatically, and " +
+            "prefers a site's curated /llms.txt for docs pages when available.\n" +
+            '`format: "outline"` is the cheap mode: main content only, every hyperlink replaced by a ' +
+            "number (`anchor text [12]`) with a numbered URL index at the end, and a small default " +
+            "`max_length`. Use it when hunting for the right page; then pass `follow: 12` " +
+            "(instead of `url`) to fetch link 12 from the last outline. Repeat views of a page in the " +
+            "same session are served from cache. Outline mode skips the /llms.txt probe.",
         parameters,
         async execute(args, context) {
-            const maxLength = args.max_length ?? 10000;
             const format = args.format ?? "markdown";
+            const maxLength = args.max_length ?? (format === "outline" ? OUTLINE_DEFAULT_MAX_LENGTH : 10000);
             const preferLlmsTxt = args.prefer_llms_txt !== false;
+            const numbers = format === "outline" ? new LinkNumbers() : undefined;
+            // A followed link is attacker-controlled page content: it resolves to a
+            // plain URL here and then travels the exact same validation path as a
+            // user-supplied one (isBlockedUrl + allowlist + per-redirect-hop checks).
+            let followUrl;
+            if (args.follow !== undefined) {
+                followUrl = followTargets.get(args.follow);
+                if (!followUrl) {
+                    return followTargets.size === 0
+                        ? 'Error: no numbered links available — fetch a page with format: "outline" first.'
+                        : `Error: link [${args.follow}] is not in the last outline (known: ${[...followTargets.keys()].join(", ")}).`;
+                }
+            }
+            // Every outline render replaces the follow map, even when the page had no
+            // links: keeping the previous page's numbers would make `follow: 3` fetch
+            // from a page the user already moved past, while the error text and the
+            // tool description both promise "the last outline". Non-outline fetches
+            // leave the map alone, so a markdown read does not discard usable numbers.
+            const remember = (output) => {
+                if (numbers) {
+                    followTargets = new Map(numbers.all().map((link) => [link.number, link.url]));
+                }
+                return output;
+            };
             // Multi-URL path: bounded-concurrency pool, per-URL budget, ordered output.
-            if (args.urls && args.urls.length > 0) {
+            if (!followUrl && args.urls && args.urls.length > 0) {
                 const urls = args.urls;
                 const perUrlBudget = Math.max(PER_URL_MIN_BUDGET, Math.floor(maxLength / urls.length));
                 const opts = {
@@ -547,16 +799,17 @@ export function createWebFetchTool(getNetworkPolicy) {
                     format,
                     preferLlmsTxt,
                     getNetworkPolicy,
+                    numbers,
                 };
-                const sections = await runPool(urls, MAX_CONCURRENCY, (u) => fetchWithPreferredDocs(u, opts, context.signal));
-                return urls.map((u, i) => `## ${u}\n${sections[i]}`).join("\n\n");
+                const sections = await runPool(urls, MAX_CONCURRENCY, (u) => fetchPage(u, opts, context.signal, pageCache));
+                return remember(urls.map((u, i) => `## ${u}\n${sections[i]}`).join("\n\n"));
             }
-            const url = args.url;
+            const url = followUrl ?? args.url;
             if (!url) {
-                return "Error: provide either `url` or `urls`.";
+                return "Error: provide either `url`, `urls`, or `follow`.";
             }
-            const opts = { maxLength, format, preferLlmsTxt, getNetworkPolicy };
-            return await fetchWithPreferredDocs(url, opts, context.signal);
+            const opts = { maxLength, format, preferLlmsTxt, getNetworkPolicy, numbers };
+            return remember(await fetchPage(url, opts, context.signal, pageCache));
         },
     };
 }
@@ -585,17 +838,28 @@ const parameters = z
         .max(MAX_URLS)
         .optional()
         .describe(`Fetch multiple URLs concurrently (up to ${MAX_URLS}); returns a sectioned digest`),
-    max_length: z.number().optional().describe("Maximum characters to return (default: 10000)"),
+    follow: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Fetch link N from the most recent outline render, instead of `url`. " +
+        "Followed links are SSRF/allowlist-checked exactly like a supplied URL."),
+    max_length: z
+        .number()
+        .optional()
+        .describe(`Maximum characters to return (default: 10000; ${OUTLINE_DEFAULT_MAX_LENGTH} for outline)`),
     format: z
-        .enum(["markdown", "text", "html"])
+        .enum(["markdown", "text", "html", "outline"])
         .optional()
-        .describe("Output format: markdown (default, main-content extraction), text, or html"),
+        .describe("Output format: markdown (default, main-content extraction), text, html, or outline " +
+        `(compact main content with each link replaced by a number plus a numbered URL index, ` +
+        `capped at ${MAX_OUTLINE_LINKS} links — cheapest; follow links with \`follow\`)`),
     prefer_llms_txt: z
         .boolean()
         .optional()
         .describe("Prefer a site's curated /llms.txt for documentation pages (default: true)"),
 })
-    .refine((v) => Boolean(v.url) !== Boolean(v.urls && v.urls.length > 0), {
-    message: "Provide exactly one of `url` or `urls`.",
-});
+    .refine((v) => [Boolean(v.url), Boolean(v.urls && v.urls.length > 0), v.follow !== undefined].filter(Boolean)
+    .length === 1, { message: "Provide exactly one of `url`, `urls`, or `follow`." });
 //# sourceMappingURL=web-fetch.js.map