context-mode 0.5.26 → 0.6.0

package/build/server.js

@@ -20,12 +20,82 @@ 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", {
@@ -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 {
@@ -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,
-        };
+        });
     }
 });
 // ─────────────────────────────────────────────────────────
@@ -541,7 +676,7 @@ server.registerTool("fetch_and_index", {
             timeout: 30_000,
         });
         if (result.exitCode !== 0) {
-            return {
+            return trackResponse("fetch_and_index", {
                 content: [
                     {
                         type: "text",
@@ -549,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",
@@ -560,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