context-mode 0.5.25 → 0.6.0

package/build/server.js

@@ -5,7 +5,7 @@ import { z } from "zod";
 import { PolyglotExecutor } from "./executor.js";
 import { ContentStore } from "./store.js";
 import { detectRuntimes, getRuntimeSummary, getAvailableLanguages, hasBunRuntime, } from "./runtime.js";
-const VERSION = "0.5.25";
+const VERSION = "0.5.26";
 const runtimes = detectRuntimes();
 const available = getAvailableLanguages(runtimes);
 const server = new McpServer({
@@ -20,17 +20,87 @@ function getStore() {
         _store = new ContentStore();
     return _store;
 }
+// ─────────────────────────────────────────────────────────
+// Session stats — track context consumption per tool
+// ─────────────────────────────────────────────────────────
+const sessionStats = {
+    calls: {},
+    bytesReturned: {},
+    bytesIndexed: 0,
+    sessionStart: Date.now(),
+};
+function trackResponse(toolName, response) {
+    const bytes = response.content.reduce((sum, c) => sum + Buffer.byteLength(c.text), 0);
+    sessionStats.calls[toolName] = (sessionStats.calls[toolName] || 0) + 1;
+    sessionStats.bytesReturned[toolName] =
+        (sessionStats.bytesReturned[toolName] || 0) + bytes;
+    return response;
+}
+function trackIndexed(bytes) {
+    sessionStats.bytesIndexed += bytes;
+}
 // Build description dynamically based on detected runtimes
 const langList = available.join(", ");
 const bunNote = hasBunRuntime()
     ? " (Bun detected — JS/TS runs 3-5x faster)"
     : "";
 // ─────────────────────────────────────────────────────────
+// Helper: smart snippet extraction — returns windows around
+// matching query terms instead of dumb truncation
+// ─────────────────────────────────────────────────────────
+function extractSnippet(content, query, maxLen = 1500) {
+    if (content.length <= maxLen)
+        return content;
+    const terms = query
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((t) => t.length > 2);
+    const lower = content.toLowerCase();
+    // Find all positions where query terms appear
+    const positions = [];
+    for (const term of terms) {
+        let idx = lower.indexOf(term);
+        while (idx !== -1) {
+            positions.push(idx);
+            idx = lower.indexOf(term, idx + 1);
+        }
+    }
+    // No term matches — return start (BM25 matched on stems/variants)
+    if (positions.length === 0) {
+        return content.slice(0, maxLen) + "\n…";
+    }
+    // Sort positions, merge overlapping windows
+    positions.sort((a, b) => a - b);
+    const WINDOW = 300;
+    const windows = [];
+    for (const pos of positions) {
+        const start = Math.max(0, pos - WINDOW);
+        const end = Math.min(content.length, pos + WINDOW);
+        if (windows.length > 0 && start <= windows[windows.length - 1][1]) {
+            windows[windows.length - 1][1] = end;
+        }
+        else {
+            windows.push([start, end]);
+        }
+    }
+    // Collect windows until maxLen
+    const parts = [];
+    let total = 0;
+    for (const [start, end] of windows) {
+        if (total >= maxLen)
+            break;
+        const part = content.slice(start, Math.min(end, start + (maxLen - total)));
+        parts.push((start > 0 ? "…" : "") + part + (end < content.length ? "…" : ""));
+        total += part.length;
+    }
+    return parts.join("\n\n");
+}
+// ─────────────────────────────────────────────────────────
 // Tool: execute
 // ─────────────────────────────────────────────────────────
 server.registerTool("execute", {
     title: "Execute Code",
-    description: `Execute code in a sandboxed subprocess. Only stdout enters context — raw data stays in the subprocess. Use instead of bash/cat when output would exceed 20 lines.${bunNote} Available: ${langList}.`,
+    description: `Execute code in a sandboxed subprocess. Only stdout enters context — raw data stays in the subprocess. Use instead of bash/cat when output would exceed 20 lines.${bunNote} Available: ${langList}.\n\nPREFER THIS OVER BASH for: API calls (gh, curl, aws), test runners (npm test, pytest), git queries (git log, git diff), data processing, and ANY CLI command that may produce large output. Bash should only be used for file mutations, git writes, and navigation.`,
     inputSchema: z.object({
         language: z
             .enum([
@@ -59,14 +129,14 @@ server.registerTool("execute", {
             .optional()
             .describe("What you're looking for in the output. When provided and output is large (>5KB), " +
             "indexes output into knowledge base and returns section titles + previews — not full content. " +
-            "Use search() to retrieve specific sections. Example: 'failing tests', 'HTTP 500 errors'." +
+            "Use search(queries: [...]) to retrieve specific sections. Example: 'failing tests', 'HTTP 500 errors'." +
             "\n\nTIP: Use specific technical terms, not just concepts. Check 'Searchable terms' in the response for available vocabulary."),
     }),
 }, async ({ language, code, timeout, intent }) => {
     try {
         const result = await executor.execute({ language, code, timeout });
         if (result.timedOut) {
-            return {
+            return trackResponse("execute", {
                 content: [
                     {
                         type: "text",
@@ -74,48 +144,50 @@ server.registerTool("execute", {
                     },
                 ],
                 isError: true,
-            };
+            });
         }
         if (result.exitCode !== 0) {
             const output = `Exit code: ${result.exitCode}\n\nstdout:\n${result.stdout}\n\nstderr:\n${result.stderr}`;
             if (intent && intent.trim().length > 0 && Buffer.byteLength(output) > INTENT_SEARCH_THRESHOLD) {
-                return {
+                trackIndexed(Buffer.byteLength(output));
+                return trackResponse("execute", {
                     content: [
                         { type: "text", text: intentSearch(output, intent, `execute:${language}:error`) },
                     ],
                     isError: true,
-                };
+                });
             }
-            return {
+            return trackResponse("execute", {
                 content: [
                     { type: "text", text: output },
                 ],
                 isError: true,
-            };
+            });
         }
         const stdout = result.stdout || "(no output)";
         // Intent-driven search: if intent provided and output is large enough
         if (intent && intent.trim().length > 0 && Buffer.byteLength(stdout) > INTENT_SEARCH_THRESHOLD) {
-            return {
+            trackIndexed(Buffer.byteLength(stdout));
+            return trackResponse("execute", {
                 content: [
                     { type: "text", text: intentSearch(stdout, intent, `execute:${language}`) },
                 ],
-            };
+            });
         }
-        return {
+        return trackResponse("execute", {
             content: [
                 { type: "text", text: stdout },
             ],
-        };
+        });
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        return {
+        return trackResponse("execute", {
             content: [
                 { type: "text", text: `Runtime error: ${message}` },
             ],
             isError: true,
-        };
+        });
     }
 });
 // ─────────────────────────────────────────────────────────
@@ -123,12 +195,13 @@ server.registerTool("execute", {
 // ─────────────────────────────────────────────────────────
 function indexStdout(stdout, source) {
     const store = getStore();
+    trackIndexed(Buffer.byteLength(stdout));
     const indexed = store.index({ content: stdout, source });
     return {
         content: [
             {
                 type: "text",
-                text: `Indexed ${indexed.totalChunks} sections (${indexed.codeChunks} with code) from: ${indexed.label}\nUse search() to query this content. Use source: "${indexed.label}" to scope results.`,
+                text: `Indexed ${indexed.totalChunks} sections (${indexed.codeChunks} with code) from: ${indexed.label}\nUse search(queries: ["..."]) to query this content. Use source: "${indexed.label}" to scope results.`,
             },
         ],
     };
@@ -205,7 +278,7 @@ function intentSearch(stdout, intent, source, maxResults = 5) {
             lines.push(`Searchable terms: ${distinctiveTerms.join(", ")}`);
         }
         lines.push("");
-        lines.push("Use search() to retrieve full content of any section.");
+        lines.push("Use search(queries: [...]) to retrieve full content of any section.");
         return lines.join("\n");
     }
     finally {
@@ -217,7 +290,7 @@ function intentSearch(stdout, intent, source, maxResults = 5) {
 // ─────────────────────────────────────────────────────────
 server.registerTool("execute_file", {
     title: "Execute File Processing",
-    description: "Read a file and process it without loading contents into context. The file is read into a FILE_CONTENT variable inside the sandbox. Only your printed summary enters context.",
+    description: "Read a file and process it without loading contents into context. The file is read into a FILE_CONTENT variable inside the sandbox. Only your printed summary enters context.\n\nPREFER THIS OVER Read/cat for: log files, data files (CSV, JSON, XML), large source files for analysis, and any file where you need to extract specific information rather than read the entire content.",
     inputSchema: z.object({
         path: z
             .string()
@@ -259,7 +332,7 @@ server.registerTool("execute_file", {
             timeout,
         });
         if (result.timedOut) {
-            return {
+            return trackResponse("execute_file", {
                 content: [
                     {
                         type: "text",
@@ -267,47 +340,49 @@ server.registerTool("execute_file", {
                     },
                 ],
                 isError: true,
-            };
+            });
         }
         if (result.exitCode !== 0) {
             const output = `Error processing ${path} (exit ${result.exitCode}):\n${result.stderr || result.stdout}`;
             if (intent && intent.trim().length > 0 && Buffer.byteLength(output) > INTENT_SEARCH_THRESHOLD) {
-                return {
+                trackIndexed(Buffer.byteLength(output));
+                return trackResponse("execute_file", {
                     content: [
                         { type: "text", text: intentSearch(output, intent, `file:${path}:error`) },
                     ],
                     isError: true,
-                };
+                });
             }
-            return {
+            return trackResponse("execute_file", {
                 content: [
                     { type: "text", text: output },
                 ],
                 isError: true,
-            };
+            });
         }
         const stdout = result.stdout || "(no output)";
         if (intent && intent.trim().length > 0 && Buffer.byteLength(stdout) > INTENT_SEARCH_THRESHOLD) {
-            return {
+            trackIndexed(Buffer.byteLength(stdout));
+            return trackResponse("execute_file", {
                 content: [
                     { type: "text", text: intentSearch(stdout, intent, `file:${path}`) },
                 ],
-            };
+            });
         }
-        return {
+        return trackResponse("execute_file", {
             content: [
                 { type: "text", text: stdout },
             ],
-        };
+        });
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        return {
+        return trackResponse("execute_file", {
             content: [
                 { type: "text", text: `Runtime error: ${message}` },
             ],
             isError: true,
-        };
+        });
     }
 });
 // ─────────────────────────────────────────────────────────
@@ -343,7 +418,7 @@ server.registerTool("index", {
     }),
 }, async ({ content, path, source }) => {
     if (!content && !path) {
-        return {
+        return trackResponse("index", {
             content: [
                 {
                     type: "text",
@@ -351,100 +426,160 @@ server.registerTool("index", {
                 },
             ],
             isError: true,
-        };
+        });
     }
     try {
+        // Track the raw bytes being indexed (content or file)
+        if (content)
+            trackIndexed(Buffer.byteLength(content));
+        else if (path) {
+            try {
+                const fs = await import("fs");
+                trackIndexed(fs.readFileSync(path).byteLength);
+            }
+            catch { /* ignore — file read errors handled by store */ }
+        }
         const store = getStore();
         const result = store.index({ content, path, source });
-        return {
+        return trackResponse("index", {
             content: [
                 {
                     type: "text",
-                    text: `Indexed ${result.totalChunks} sections (${result.codeChunks} with code) from: ${result.label}\nUse search() to query this content. Use source: "${result.label}" to scope results.`,
+                    text: `Indexed ${result.totalChunks} sections (${result.codeChunks} with code) from: ${result.label}\nUse search(queries: ["..."]) to query this content. Use source: "${result.label}" to scope results.`,
                 },
             ],
-        };
+        });
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        return {
+        return trackResponse("index", {
             content: [
                 { type: "text", text: `Index error: ${message}` },
             ],
             isError: true,
-        };
+        });
     }
 });
 // ─────────────────────────────────────────────────────────
-// Tool: search
+// Tool: search — progressive throttling
 // ─────────────────────────────────────────────────────────
+// Track search calls per 60-second window for progressive throttling
+let searchCallCount = 0;
+let searchWindowStart = Date.now();
+const SEARCH_WINDOW_MS = 60_000;
+const SEARCH_MAX_RESULTS_AFTER = 3; // after 3 calls: 1 result per query
+const SEARCH_BLOCK_AFTER = 8; // after 8 calls: refuse, demand batching
 server.registerTool("search", {
     title: "Search Indexed Content",
-    description: "Search previously indexed content using BM25 full-text search. " +
-        "Returns the top matching chunks with heading context and full content. " +
-        "Use after 'index' to retrieve specific documentation sections, code examples, or API details on demand.\n\n" +
-        "WHEN TO USE:\n" +
-        "- Find specific code examples ('useEffect cleanup pattern')\n" +
-        "- Look up API signatures ('Supabase RLS policy syntax')\n" +
-        "- Get configuration details ('Tailwind responsive breakpoints')\n" +
-        "- Find migration steps ('App Router data fetching')\n\n" +
-        "SEARCH TIPS:\n" +
-        "- Queries use OR semantics — results matching more terms rank higher via BM25\n" +
-        "- Use 2-4 specific technical terms per query for best results\n" +
-        "- Use 'source' parameter to scope search to a specific indexed source (partial match)\n" +
-        "- Check 'Searchable terms' from execute/execute_file results for available vocabulary\n" +
-        "- For broad topics, send multiple focused searches in parallel\n\n" +
-        "Returns exact content — not summaries. Each result includes heading hierarchy and full section text.",
+    description: "Search indexed content. Pass ALL search questions as queries array in ONE call.\n\n" +
+        "TIPS: 2-4 specific terms per query. Use 'source' to scope results.",
     inputSchema: z.object({
-        query: z.string().describe("Natural language search query"),
+        queries: z
+            .array(z.string())
+            .optional()
+            .describe("Array of search queries. Batch ALL questions in one call."),
         limit: z
             .number()
             .optional()
             .default(3)
-            .describe("Maximum results to return (default: 3)"),
+            .describe("Results per query (default: 3)"),
         source: z
             .string()
             .optional()
-            .describe("Filter results to a specific indexed source (partial match). " +
-            "Use the source label from index/fetch_and_index response."),
+            .describe("Filter to a specific indexed source (partial match)."),
     }),
-}, async ({ query, limit, source }) => {
+}, async (params) => {
     try {
         const store = getStore();
-        const results = store.search(query, limit, source);
-        if (results.length === 0) {
+        const raw = params;
+        // Normalize: accept both query (string) and queries (array)
+        const queryList = [];
+        if (Array.isArray(raw.queries) && raw.queries.length > 0) {
+            queryList.push(...raw.queries);
+        }
+        else if (typeof raw.query === "string" && raw.query.length > 0) {
+            queryList.push(raw.query);
+        }
+        if (queryList.length === 0) {
+            return trackResponse("search", {
+                content: [{ type: "text", text: "Error: provide query or queries." }],
+                isError: true,
+            });
+        }
+        const { limit = 3, source } = params;
+        // Progressive throttling: track calls in time window
+        const now = Date.now();
+        if (now - searchWindowStart > SEARCH_WINDOW_MS) {
+            searchCallCount = 0;
+            searchWindowStart = now;
+        }
+        searchCallCount++;
+        // After SEARCH_BLOCK_AFTER calls: refuse
+        if (searchCallCount > SEARCH_BLOCK_AFTER) {
+            return trackResponse("search", {
+                content: [{
+                        type: "text",
+                        text: `BLOCKED: ${searchCallCount} search calls in ${Math.round((now - searchWindowStart) / 1000)}s. ` +
+                            "You're flooding context. STOP making individual search calls. " +
+                            "Use batch_execute(commands, queries) for your next research step.",
+                    }],
+                isError: true,
+            });
+        }
+        // Determine per-query result limit based on throttle level
+        const effectiveLimit = searchCallCount > SEARCH_MAX_RESULTS_AFTER
+            ? 1 // after 3 calls: only 1 result per query
+            : Math.min(limit, 2); // normal: max 2
+        const MAX_TOTAL = 40 * 1024; // 40KB total cap
+        let totalSize = 0;
+        const sections = [];
+        for (const q of queryList) {
+            if (totalSize > MAX_TOTAL) {
+                sections.push(`## ${q}\n(output cap reached)\n`);
+                continue;
+            }
+            const results = store.search(q, effectiveLimit, source);
+            if (results.length === 0) {
+                sections.push(`## ${q}\nNo results found.`);
+                continue;
+            }
+            const formatted = results
+                .map((r, i) => {
+                const header = `--- [${r.source}] ---`;
+                const heading = `### ${r.title}`;
+                const snippet = extractSnippet(r.content, q);
+                return `${header}\n${heading}\n\n${snippet}`;
+            })
+                .join("\n\n");
+            sections.push(`## ${q}\n\n${formatted}`);
+            totalSize += formatted.length;
+        }
+        let output = sections.join("\n\n---\n\n");
+        // Add throttle warning after threshold
+        if (searchCallCount >= SEARCH_MAX_RESULTS_AFTER) {
+            output += `\n\n⚠ search call #${searchCallCount}/${SEARCH_BLOCK_AFTER} in this window. ` +
+                `Results limited to ${effectiveLimit}/query. ` +
+                `Batch queries: search(queries: ["q1","q2","q3"]) or use batch_execute.`;
+        }
+        if (output.trim().length === 0) {
             const sources = store.listSources();
             const sourceList = sources.length > 0
                 ? `\nIndexed sources: ${sources.map((s) => `"${s.label}" (${s.chunkCount} sections)`).join(", ")}`
                 : "";
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `No results found for: "${query}"${source ? ` in source "${source}"` : ""}.${sourceList}`,
-                    },
-                ],
-            };
+            return trackResponse("search", {
+                content: [{ type: "text", text: `No results found.${sourceList}` }],
+            });
         }
-        const formatted = results
-            .map((r, i) => {
-            const header = `--- Result ${i + 1} [${r.source}] (${r.contentType}) ---`;
-            const heading = `## ${r.title}`;
-            return `${header}\n${heading}\n\n${r.content}`;
-        })
-            .join("\n\n");
-        return {
-            content: [{ type: "text", text: formatted }],
-        };
+        return trackResponse("search", {
+            content: [{ type: "text", text: output }],
+        });
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        return {
-            content: [
-                { type: "text", text: `Search error: ${message}` },
-            ],
+        return trackResponse("search", {
+            content: [{ type: "text", text: `Search error: ${message}` }],
             isError: true,
-        };
+        });
     }
 });
 // ─────────────────────────────────────────────────────────
@@ -521,7 +656,8 @@ server.registerTool("fetch_and_index", {
     title: "Fetch & Index URL",
     description: "Fetches URL content, converts HTML to markdown, and indexes into the searchable knowledge base. " +
         "Raw content never enters context — only a brief confirmation is returned.\n\n" +
-        "Use INSTEAD of WebFetch/Context7 when you need to reference web documentation later via search.\n\n" +
+        "PREFER THIS OVER WebFetch when you need to reference web documentation later via search. " +
+        "WebFetch loads entire page content into context; this tool indexes it and lets you search() on-demand.\n\n" +
         "After fetching, use 'search' to retrieve specific sections on-demand.",
     inputSchema: z.object({
         url: z.string().describe("The URL to fetch and index"),
@@ -540,7 +676,7 @@ server.registerTool("fetch_and_index", {
             timeout: 30_000,
         });
         if (result.exitCode !== 0) {
-            return {
+            return trackResponse("fetch_and_index", {
                 content: [
                     {
                         type: "text",
@@ -548,10 +684,10 @@ server.registerTool("fetch_and_index", {
                     },
                 ],
                 isError: true,
-            };
+            });
         }
         if (!result.stdout || result.stdout.trim().length === 0) {
-            return {
+            return trackResponse("fetch_and_index", {
                 content: [
                     {
                         type: "text",
@@ -559,20 +695,216 @@ server.registerTool("fetch_and_index", {
                     },
                 ],
                 isError: true,
-            };
+            });
         }
-        // Index the markdown into FTS5
-        return indexStdout(result.stdout, source ?? url);
+        // Index the markdown into FTS5 (indexStdout already calls trackIndexed)
+        return trackResponse("fetch_and_index", indexStdout(result.stdout, source ?? url));
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        return {
+        return trackResponse("fetch_and_index", {
             content: [
                 { type: "text", text: `Fetch error: ${message}` },
             ],
             isError: true,
-        };
+        });
+    }
+});
+// ─────────────────────────────────────────────────────────
+// Tool: batch_execute
+// ─────────────────────────────────────────────────────────
+server.registerTool("batch_execute", {
+    title: "Batch Execute & Search",
+    description: "Execute multiple commands in ONE call, auto-index all output, and search with multiple queries. " +
+        "Returns search results directly — no follow-up calls needed.\n\n" +
+        "THIS IS THE PRIMARY TOOL. Use this instead of multiple execute() calls.\n\n" +
+        "One batch_execute call replaces 30+ execute calls + 10+ search calls.\n" +
+        "Provide all commands to run and all queries to search — everything happens in one round trip.",
+    inputSchema: z.object({
+        commands: z
+            .array(z.object({
+            label: z
+                .string()
+                .describe("Section header for this command's output (e.g., 'README', 'Package.json', 'Source Tree')"),
+            command: z
+                .string()
+                .describe("Shell command to execute"),
+        }))
+            .min(1)
+            .describe("Commands to execute as a batch. Each runs sequentially, output is labeled with the section header."),
+        queries: z
+            .array(z.string())
+            .min(1)
+            .describe("Search queries to extract information from indexed output. Use 5-8 comprehensive queries. " +
+            "Each returns top 5 matching sections with full content. " +
+            "This is your ONLY chance — put ALL your questions here. No follow-up calls needed."),
+        timeout: z
+            .number()
+            .optional()
+            .default(60000)
+            .describe("Max execution time in ms (default: 60s)"),
+    }),
+}, async ({ commands, queries, timeout }) => {
+    try {
+        // Build batch script with markdown section headers for proper chunking
+        const script = commands
+            .map((c) => {
+            const safeLabel = c.label.replace(/'/g, "'\\''");
+            return `echo '# ${safeLabel}'\necho ''\n${c.command} 2>&1\necho ''`;
+        })
+            .join("\n");
+        const result = await executor.execute({
+            language: "shell",
+            code: script,
+            timeout,
+        });
+        if (result.timedOut) {
+            return trackResponse("batch_execute", {
+                content: [
+                    {
+                        type: "text",
+                        text: `Batch timed out after ${timeout}ms. Partial output:\n${result.stdout?.slice(0, 2000) || "(none)"}`,
+                    },
+                ],
+                isError: true,
+            });
+        }
+        const stdout = result.stdout || "(no output)";
+        const totalBytes = Buffer.byteLength(stdout);
+        const totalLines = stdout.split("\n").length;
+        // Track indexed bytes (raw data that stays in sandbox)
+        trackIndexed(totalBytes);
+        // Index into knowledge base — markdown heading chunking splits by # labels
+        const store = getStore();
+        const source = `batch:${commands
+            .map((c) => c.label)
+            .join(",")
+            .slice(0, 80)}`;
+        const indexed = store.index({ content: stdout, source });
+        // Build section inventory — direct query by source_id (no FTS5 MATCH needed)
+        const allSections = store.getChunksBySource(indexed.sourceId);
+        const inventory = ["## Indexed Sections", ""];
+        const sectionTitles = [];
+        for (const s of allSections) {
+            const bytes = Buffer.byteLength(s.content);
+            inventory.push(`- ${s.title} (${(bytes / 1024).toFixed(1)}KB)`);
+            sectionTitles.push(s.title);
+        }
+        // Run all search queries — 3 results each, smart snippets
+        // Three-tier fallback: scoped → boosted → global
+        const MAX_OUTPUT = 80 * 1024; // 80KB total output cap
+        const queryResults = [];
+        let outputSize = 0;
+        for (const query of queries) {
+            if (outputSize > MAX_OUTPUT) {
+                queryResults.push(`## ${query}\n(output cap reached — use search(queries: ["${query}"]) for details)\n`);
+                continue;
+            }
+            // Tier 1: scoped search (within this batch's source)
+            let results = store.search(query, 3, source);
+            // Tier 2: boosted with section titles
+            if (results.length === 0 && sectionTitles.length > 0) {
+                const boosted = `${query} ${sectionTitles.join(" ")}`;
+                results = store.search(boosted, 3, source);
+            }
+            // Tier 3: global fallback (no source filter)
+            if (results.length === 0) {
+                results = store.search(query, 3);
+            }
+            queryResults.push(`## ${query}`);
+            queryResults.push("");
+            if (results.length > 0) {
+                for (const r of results) {
+                    const snippet = extractSnippet(r.content, query);
+                    queryResults.push(`### ${r.title}`);
+                    queryResults.push(snippet);
+                    queryResults.push("");
+                    outputSize += snippet.length + r.title.length;
+                }
+            }
+            else {
+                queryResults.push("No matching sections found.");
+                queryResults.push("");
+            }
+        }
+        // Get searchable terms for edge cases where follow-up is needed
+        const distinctiveTerms = store.getDistinctiveTerms
+            ? store.getDistinctiveTerms(indexed.sourceId)
+            : [];
+        const output = [
+            `Executed ${commands.length} commands (${totalLines} lines, ${(totalBytes / 1024).toFixed(1)}KB). ` +
+                `Indexed ${indexed.totalChunks} sections. Searched ${queries.length} queries.`,
+            "",
+            ...inventory,
+            "",
+            ...queryResults,
+            distinctiveTerms.length > 0
+                ? `\nSearchable terms for follow-up: ${distinctiveTerms.join(", ")}`
+                : "",
+        ].join("\n");
+        return trackResponse("batch_execute", {
+            content: [{ type: "text", text: output }],
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return trackResponse("batch_execute", {
+            content: [
+                {
+                    type: "text",
+                    text: `Batch execution error: ${message}`,
+                },
+            ],
+            isError: true,
+        });
+    }
+});
+// ─────────────────────────────────────────────────────────
+// Tool: stats
+// ─────────────────────────────────────────────────────────
+server.registerTool("stats", {
+    title: "Session Statistics",
+    description: "Returns context consumption statistics for the current session. " +
+        "Shows total bytes returned to context, breakdown by tool, call counts, " +
+        "estimated token usage, and context savings ratio.",
+    inputSchema: z.object({}),
+}, async () => {
+    const totalBytesReturned = Object.values(sessionStats.bytesReturned).reduce((sum, b) => sum + b, 0);
+    const estimatedTokens = Math.round(totalBytesReturned / 4);
+    const totalCalls = Object.values(sessionStats.calls).reduce((sum, c) => sum + c, 0);
+    const uptimeMs = Date.now() - sessionStats.sessionStart;
+    const uptimeMin = (uptimeMs / 60_000).toFixed(1);
+    const lines = [
+        `## Context Mode Session Stats`,
+        "",
+        `Session uptime: ${uptimeMin} min`,
+        `Total tool calls: ${totalCalls}`,
+        `Total bytes returned to context: ${totalBytesReturned.toLocaleString()} (${(totalBytesReturned / 1024).toFixed(1)}KB)`,
+        `Estimated tokens consumed: ~${estimatedTokens.toLocaleString()} (bytes/4)`,
+        `Total bytes indexed (stayed in sandbox): ${sessionStats.bytesIndexed.toLocaleString()} (${(sessionStats.bytesIndexed / 1024).toFixed(1)}KB)`,
+    ];
+    if (sessionStats.bytesIndexed > 0) {
+        const savingsRatio = sessionStats.bytesIndexed / Math.max(totalBytesReturned, 1);
+        lines.push(`Context savings ratio: ${savingsRatio.toFixed(1)}x (${((1 - 1 / Math.max(savingsRatio, 1)) * 100).toFixed(0)}% reduction)`);
+    }
+    lines.push("", "### Per-Tool Breakdown", "");
+    lines.push("| Tool | Calls | Bytes Returned | Est. Tokens |");
+    lines.push("|------|------:|---------------:|------------:|");
+    const toolNames = new Set([
+        ...Object.keys(sessionStats.calls),
+        ...Object.keys(sessionStats.bytesReturned),
+    ]);
+    for (const tool of Array.from(toolNames).sort()) {
+        const calls = sessionStats.calls[tool] || 0;
+        const bytes = sessionStats.bytesReturned[tool] || 0;
+        const tokens = Math.round(bytes / 4);
+        lines.push(`| ${tool} | ${calls} | ${bytes.toLocaleString()} (${(bytes / 1024).toFixed(1)}KB) | ~${tokens.toLocaleString()} |`);
     }
+    const text = lines.join("\n");
+    // Track the stats tool itself
+    return trackResponse("stats", {
+        content: [{ type: "text", text }],
+    });
 });
 // ─────────────────────────────────────────────────────────
 // Server startup