@nxuss/lemma 1.7.1 → 1.8.0

package/dist/esm/mcp/tools.js

@@ -1,7 +1,7 @@
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import fs from "fs";
 import path from "path";
-import { execSync, spawnSync } from "child_process";
+import { execSync, execFileSync, spawnSync } from "child_process";
 import os from "os";
 import axios from "axios";
 import * as ts from "typescript";
@@ -18,7 +18,7 @@ import { readTokenBudgeted } from "../utils/TokenBudgetedReader.js";
 import { bulkFileDigest } from "../utils/BulkFileDigest.js";
 import { autoContextBundle } from "../utils/AutoContextBundle.js";
 import { checkRepeat, recordOutput } from "../utils/RepeatGuard.js";
-import { saveCheckpoint, loadLatestCheckpoint, buildCheckpointSummary } from "../utils/ConversationCheckpoint.js";
+import { saveCheckpoint, loadLatestCheckpoint, loadRecentCheckpoints, buildCheckpointSummary } from "../utils/ConversationCheckpoint.js";
 import { runTestAutofix } from "../utils/TestAutofixInterceptor.js";
 import { findPattern, storePattern, getPatternStats } from "../utils/PromptPatternCache.js";
 import { runAnalysis, parseDiff } from "../pr-review/PRReviewEngine.js";
@@ -33,7 +33,7 @@ import { surgicalASTInsert } from "../utils/SurgicalASTInsert.js";
 import { getInfraToolDefinitions, getInfraToolHandlers, INFRA_TOOL_NAMES } from "../infra/mcp-tools.js";
 import { resolveToolSurface, buildToolboxCatalog } from "./tool-profiles.js";
 import { lookupStateHash, storeStateHash } from "../utils/StateHashCache.js";
-import { recordReceiptEvent, getReceiptSummary } from "../utils/TokenReceipt.js";
+import { recordReceiptEvent, getReceiptSummary, getLedgerLength } from "../utils/TokenReceipt.js";
 import { distillCommandOutput, buildDistillFooter, readRegion } from "../utils/CommandOutputDistiller.js";
 import { findMatch, reindentReplacement } from "../utils/PatchMatcher.js";
 import { searchWorkspace, groupSearchResults, parseExtensionFilter } from "../utils/WorkspaceSearch.js";
@@ -58,7 +58,7 @@ function isProUser() {
 }
 const FREE_TOOLS = new Set([
     // Cache & Memory — the hook that shows instant value
-    "smarter_cache", "state_hash_cache", "token_receipt", "search_memory", "store_memory",
+    "smarter_cache", "state_hash_cache", "token_receipt", "search_memory", "store_memory", "get_project_history",
     // Token optimization — shows what they're saving
     "token_budget", "squeeze_prompt", "turbosqueeze",
     // Utility — just enough to function
@@ -103,13 +103,18 @@ const toolDefinitions = [
             properties: {
                 query: { type: "string", description: "The natural language query" },
                 limit: { type: "number", description: "Maximum results to return", default: 5 },
+                minSimilarity: {
+                    type: "number",
+                    description: "Similarity floor (0.0-1.0) a memory must clear to be returned. Lowering this surfaces loosely related memories that are usually noise — leave it alone unless a known-relevant memory is being filtered out.",
+                    default: 0.75,
+                },
             },
             required: ["query"],
         },
     },
     {
         name: "store_memory",
-        description: "Persist a technical solution, bug fix, architecture decision, or key fact into Lemma's Brain — so future questions on the same topic (even phrased differently) don't require re-investigating the repo. Pass filePaths for anything derived from specific files (e.g. 'where is X implemented', 'how does Y work') so the memory auto-invalidates the moment those files change, instead of risking a stale answer being reused.",
+        description: "Persist a technical solution, bug fix, architecture decision, or key fact into Lemma's Brain — so future questions on the same topic (even phrased differently) don't require re-investigating the repo. Pass filePaths for anything derived from specific files (e.g. 'where is X implemented', 'how does Y work') so the memory auto-invalidates the moment those files change, instead of risking a stale answer being reused. If the answer is really about one function/class rather than the whole file, pass `symbols` instead (or in addition) so an unrelated edit elsewhere in that file doesn't stale it out. Pass outcome='failed' for an approach that was tried and did NOT work — that's just as worth remembering as a fix, so the Brain can warn 'already tried, didn't work' instead of only ever suggesting reuse.",
         inputSchema: {
             type: "object",
             properties: {
@@ -117,6 +122,19 @@ const toolDefinitions = [
                 response: { type: "string", description: "The complete technical content to memorize" },
                 provider: { type: "string", description: "Optional model provider name", default: "generic" },
                 filePaths: { type: "array", items: { type: "string" }, description: "Paths (relative to project root) this answer depends on. If any changes later, this memory is marked stale instead of being silently reused." },
+                symbols: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            filePath: { type: "string", description: "Path (relative to project root) containing the symbol" },
+                            symbolName: { type: "string", description: "Function/class/interface/type/enum/const name" },
+                        },
+                        required: ["filePath", "symbolName"],
+                    },
+                    description: "Symbols (not whole files) this answer depends on. Freshness is then judged by that symbol's own source, so edits elsewhere in the same file don't stale this memory out.",
+                },
+                outcome: { type: "string", enum: ["confirmed", "failed"], description: "Default 'confirmed' (a verified working solution). Set 'failed' to record a dead end — an approach ruled out, not one to recommend." },
             },
             required: ["query", "response"],
         },
@@ -268,6 +286,16 @@ const toolDefinitions = [
             properties: {},
         },
     },
+    {
+        name: "get_project_history",
+        description: "Answers 'what have we done in this project': merges recent git commits, session checkpoints, and The Brain's memories (decisions, fixes, prior PR reviews) for the current project into one narrative. Use this instead of piecing the same picture together from search_memory + git log + reading checkpoint files separately.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: { type: "number", description: "Max items per section (commits, checkpoints, Brain memories)", default: 10 },
+            },
+        },
+    },
     {
         name: "get_ast_hologram",
         description: "Generate a dense, token-efficient Holographic AST Map of the workspace using the TypeScript compiler. Returns structured JSON of all exported symbols with file paths and line numbers.",
@@ -1116,6 +1144,7 @@ const toolHandlers = {
     auto_context_bundle: handleAutoContextBundle,
     repeat_guard: handleRepeatGuard,
     conversation_checkpoint: handleConversationCheckpoint,
+    get_project_history: handleGetProjectHistory,
     test_autofix_interceptor: handleTestAutofixInterceptor,
     prompt_pattern_cache: handlePromptPatternCache,
     lemma_toolbox: handleToolbox,
@@ -1156,6 +1185,41 @@ async function handleToolbox(args) {
     }
     throw new Error(`Unknown action: ${action}. Use 'list', 'schema', or 'call'.`);
 }
+/** Tools whose whole job is to put file contents into the model's context. */
+const FILE_READ_TOOLS = new Set([
+    "read_workspace_file",
+    "smart_file_slice",
+    "get_symbol_surgical_context",
+    "get_ast_hologram",
+    "list_workspace_dir",
+    "search_workspace",
+    "read_token_budgeted",
+    "bulk_file_digest",
+    "import_tree_context",
+]);
+function receiptTypeForTool(name) {
+    return FILE_READ_TOOLS.has(name) ? "file_read" : "tool_call";
+}
+/**
+ * A receipt entry is only useful if it says what the call was about. Pull the most
+ * identifying argument without dragging whole file contents into the ledger.
+ */
+function receiptLabelMeta(name, args) {
+    if (!args)
+        return {};
+    const meta = {};
+    if (typeof args.filePath === "string")
+        meta.filePath = args.filePath;
+    if (typeof args.dirPath === "string")
+        meta.dirPath = args.dirPath;
+    if (typeof args.query === "string")
+        meta.query = args.query.substring(0, 100);
+    if (typeof args.command === "string")
+        meta.command = args.command.substring(0, 100);
+    if (typeof args.symbolName === "string")
+        meta.symbolName = args.symbolName;
+    return meta;
+}
 export function setupToolsHandlers(server, onToolCall) {
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: toolDefinitionsArray,
@@ -1190,7 +1254,16 @@ export function setupToolsHandlers(server, onToolCall) {
             throw new Error(`Unknown tool: ${name}`);
         }
         try {
+            // Sampled around the handler so a tool that logs its own, more specific event
+            // (a cache hit, a miss) isn't double-counted by the generic entry below.
+            const ledgerBefore = getLedgerLength();
             const result = await handler((args || {}));
+            if (getLedgerLength() === ledgerBefore) {
+                recordReceiptEvent(receiptTypeForTool(name), name, {
+                    tool: name,
+                    ...receiptLabelMeta(name, args),
+                });
+            }
             const tokensImpact = estimateTokensFromResult(result);
             onToolCall?.({
                 tool: name,
@@ -1225,26 +1298,56 @@ async function handleScrubPrivacy(args) {
     const { maskedPrompt } = scrubber.mask(text);
     return { content: [{ type: "text", text: maskedPrompt }] };
 }
+/**
+ * Minimum similarity for a stored memory to be offered for reuse. Shared by
+ * search_memory and smarter_cache so the two never disagree about whether the same
+ * query is a hit.
+ */
+const DEFAULT_MEMORY_SIMILARITY_FLOOR = 0.75;
 async function handleSearchMemory(args) {
     const query = args?.query;
     const limit = args?.limit || 5;
+    // A floor of 0 returns the nearest neighbour no matter how unrelated it is, and the
+    // formatting below then presents it as a reusable memory. Match smarter_cache's
+    // threshold so both paths agree on what counts as a hit.
+    const minSimilarity = typeof args?.minSimilarity === "number" ? args.minSimilarity : DEFAULT_MEMORY_SIMILARITY_FLOOR;
     if (!query)
         throw new Error("Query is required");
     try {
         const brain = getBrain();
-        const results = brain.search(query, limit, 0, { projectId: deriveProjectId() });
+        const results = brain.search(query, limit, minSimilarity, { projectId: deriveProjectId() });
         if (results.length === 0) {
-            return { content: [{ type: "text", text: "No relevant memories found in Lemma's Brain." }] };
+            recordReceiptEvent("reasoning", query.substring(0, 100), {
+                tool: "search_memory",
+                reason: `no memory above the ${minSimilarity} similarity floor`,
+            });
+            return {
+                content: [{
+                        type: "text",
+                        text: `No memory in Lemma's Brain scored at or above the ${(minSimilarity * 100).toFixed(0)}% similarity floor for this query. Investigate from scratch — there is nothing safe to reuse.`,
+                    }],
+            };
         }
         const fresh = results.filter((r) => r.fresh);
         const stale = results.filter((r) => !r.fresh);
-        const formatResult = (r, i) => `Result ${i + 1} (Similarity: ${(r.similarity * 100).toFixed(1)}%)\nPrompt: ${r.query.substring(0, 300)}...\nResponse: ${typeof r.response === "string" ? r.response : JSON.stringify(r.response, null, 2)}`;
+        const formatResult = (r, i) => `Result ${i + 1} (Similarity: ${(r.similarity * 100).toFixed(1)}%)${r.outcome === "failed" ? "\n⚠️ TAGGED AS A FAILED ATTEMPT — this was tried before and did NOT work. Do not repeat it; treat this as a warning, not a suggestion." : ""}\nPrompt: ${r.query.substring(0, 300)}...\nResponse: ${typeof r.response === "string" ? r.response : JSON.stringify(r.response, null, 2)}`;
         if (fresh.length > 0) {
             // Only a fresh hit (or an untracked, purely conceptual entry) counts as a real
             // avoided re-investigation — this is the only case worth crediting as savings.
             const bestFresh = fresh[0];
             const tokensSaved = Math.max(100, Math.floor(String(bestFresh.response).length / 4));
             reportSavings({ source: "cache", tokens: tokensSaved, toolName: "search_memory", query: query.substring(0, 100) });
+            recordReceiptEvent("semantic_cache_hit", query.substring(0, 100), {
+                tool: "search_memory",
+                similarity: bestFresh.similarity,
+                tokensSaved,
+            });
+        }
+        else {
+            recordReceiptEvent("reasoning", query.substring(0, 100), {
+                tool: "search_memory",
+                reason: `${stale.length} similar memory/memories found but all stale — must re-verify`,
+            });
         }
         const parts = [];
         if (fresh.length > 0) {
@@ -1268,20 +1371,27 @@ async function handleStoreMemory(args) {
     const responseText = args?.response;
     const provider = args?.provider || "generic";
     const filePaths = Array.isArray(args?.filePaths) ? args.filePaths : undefined;
+    const outcome = args?.outcome === "failed" ? "failed" : undefined;
+    const symbols = Array.isArray(args?.symbols)
+        ? args.symbols.filter((s) => s?.filePath && s?.symbolName)
+        : undefined;
     if (!query || !responseText)
         throw new Error("Query and response are required");
     try {
         const brain = getBrain();
-        const storeRes = brain.store(query, responseText, provider, 0.92, filePaths);
-        const tokensSaved = Math.max(100, Math.floor(responseText.length / 4));
-        reportSavings({
-            source: "cache",
-            tokens: tokensSaved,
-            toolName: "store_memory",
-            query: query.substring(0, 100),
+        const storeRes = brain.store(query, responseText, provider, 0.92, filePaths, undefined, outcome, symbols);
+        // Storing a memory saves nothing — it only creates the chance of a saving later.
+        // Crediting tokens here inflated the ledger on write and then credited the same
+        // answer again on every read. The saving is booked by search_memory on a fresh hit.
+        recordReceiptEvent("tool_call", `store_memory: ${query.substring(0, 100)}`, {
+            tool: "store_memory",
+            filePaths,
+            note: "memory written — no tokens saved yet",
         });
         const trackingNote = filePaths && filePaths.length > 0 ? ` Tracking freshness against ${filePaths.length} file(s) — this memory auto-invalidates if they change.` : "";
-        return { content: [{ type: "text", text: `Success: Memory stored. ${storeRes.reason}${trackingNote}` }] };
+        const symbolNote = symbols && symbols.length > 0 ? ` Tracking freshness against ${symbols.length} symbol(s) specifically — unrelated edits elsewhere in those files won't stale this out.` : "";
+        const outcomeNote = outcome === "failed" ? " Tagged as a FAILED attempt — future searches will surface it as a warning, not a suggestion." : "";
+        return { content: [{ type: "text", text: `Success: Memory stored. ${storeRes.reason}${trackingNote}${symbolNote}${outcomeNote}` }] };
     }
     catch (e) {
         logError("store_memory", e);
@@ -1800,7 +1910,60 @@ async function handleGetProjectOnboarding(_args) {
         ],
     };
 }
-function extractSymbolsWithTsCompiler(filePath, relPath) {
+// ── Project History (aggregate: git log + checkpoints + Brain) ─────
+/**
+ * "What have we done in this project" today means piecing together search_memory, git log,
+ * and manually reading .lemma/session/ checkpoint files by hand — three separate calls whose
+ * results the model has to merge itself. This does that merge in one call.
+ */
+async function handleGetProjectHistory(args) {
+    const cwd = process.cwd();
+    const limit = typeof args?.limit === "number" ? args.limit : 10;
+    try {
+        const projectId = deriveProjectId(cwd);
+        const brainEntries = getBrain()
+            .getEntriesForProject(projectId)
+            .sort((a, b) => (b.hits - a.hits) || (new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime()))
+            .slice(0, limit);
+        const checkpoints = loadRecentCheckpoints(cwd, Math.min(limit, 5));
+        let recentCommits = [];
+        try {
+            const log = execFileSync("git", ["-C", cwd, "log", `-${limit}`, "--pretty=format:%h %s (%ar)"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+            recentCommits = log.split("\n").filter(Boolean);
+        }
+        catch {
+            // Not a git repo, or no commits yet — sections below just won't include this one.
+        }
+        const parts = [`# Project history — ${path.basename(cwd)}`];
+        if (recentCommits.length > 0) {
+            parts.push(`## Recent commits\n${recentCommits.map((c) => `- ${c}`).join("\n")}`);
+        }
+        if (checkpoints.length > 0) {
+            const checkpointLines = checkpoints.map((cp) => {
+                const date = new Date(cp.timestamp).toISOString().replace("T", " ").slice(0, 16);
+                return `- **${date}** — ${cp.summary.replace(/\n+/g, " ")}`;
+            });
+            parts.push(`## Session checkpoints\n${checkpointLines.join("\n")}`);
+        }
+        if (brainEntries.length > 0) {
+            const brainLines = brainEntries.map((e) => {
+                const tag = e.outcome === "failed" ? " ⚠️ FAILED ATTEMPT" : "";
+                const snippet = e.response.length > 300 ? `${e.response.substring(0, 300)}...` : e.response;
+                return `- **${e.query}**${tag} _(${e.provider}, ${e.hits} hit(s))_\n  ${snippet}`;
+            });
+            parts.push(`## Brain memories (decisions, fixes, prior reviews)\n${brainLines.join("\n")}`);
+        }
+        if (parts.length === 1) {
+            parts.push("Nothing recorded yet — no git history, checkpoints, or Brain memories found for this project.");
+        }
+        return { content: [{ type: "text", text: parts.join("\n\n") }] };
+    }
+    catch (e) {
+        logError("get_project_history", e);
+        return { content: [{ type: "text", text: `get_project_history failed: ${e.message}` }] };
+    }
+}
+function extractSymbolsWithTsCompiler(filePath, relPath, parseErrors) {
     try {
         const src = fs.readFileSync(filePath, "utf8");
         const sourceFile = ts.createSourceFile(filePath, src, ts.ScriptTarget.Latest, true);
@@ -1808,7 +1971,10 @@ function extractSymbolsWithTsCompiler(filePath, relPath) {
         function visit(node) {
             const mods = ts.canHaveModifiers(node) ? ts.getModifiers(node) : undefined;
             const isExport = mods?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
-            if (isExport || ts.isSourceFile(node.parent)) {
+            // node.parent is undefined on the SourceFile root itself, and ts.isSourceFile()
+            // dereferences .kind without a guard — calling it unguarded threw on the very
+            // first visit(), so the catch below swallowed it and every file returned [].
+            if (isExport || (node.parent && ts.isSourceFile(node.parent))) {
                 if (ts.isFunctionDeclaration(node) && node.name) {
                     symbols.push({
                         kind: "function",
@@ -1877,10 +2043,11 @@ function extractSymbolsWithTsCompiler(filePath, relPath) {
     }
     catch (err) {
         logWarn("get_ast_hologram", `Could not parse ${relPath}: ${err}`);
+        parseErrors?.push(`${relPath}: ${err}`);
         return [];
     }
 }
-function walkDirForHologram(dir, rel, extensions) {
+function walkDirForHologram(dir, rel, extensions, stats) {
     let allSymbols = [];
     try {
         const entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -1890,18 +2057,20 @@ function walkDirForHologram(dir, rel, extensions) {
             const fullPath = path.join(dir, entry.name);
             const relPath = rel ? path.join(rel, entry.name) : entry.name;
             if (entry.isDirectory()) {
-                allSymbols = allSymbols.concat(walkDirForHologram(fullPath, relPath, extensions));
+                allSymbols = allSymbols.concat(walkDirForHologram(fullPath, relPath, extensions, stats));
             }
             else {
                 const ext = entry.name.split(".").pop() || "";
                 if (extensions.includes(ext)) {
-                    allSymbols = allSymbols.concat(extractSymbolsWithTsCompiler(fullPath, relPath));
+                    stats.filesScanned++;
+                    allSymbols = allSymbols.concat(extractSymbolsWithTsCompiler(fullPath, relPath, stats.parseErrors));
                 }
             }
         }
     }
     catch (err) {
         logWarn("get_ast_hologram", `Error walking dir ${dir}: ${err}`);
+        stats.parseErrors.push(`walk ${rel || "."}: ${err}`);
     }
     return allSymbols;
 }
@@ -1910,18 +2079,32 @@ async function handleGetAstHologram(args) {
     const extensions = args?.extensions || ["ts", "tsx", "js", "jsx"];
     const workspaceRoot = process.cwd();
     const { resolved } = safeResolvePath(workspaceRoot, dirPath);
-    const symbols = walkDirForHologram(resolved, dirPath, extensions);
+    const stats = { filesScanned: 0, parseErrors: [] };
+    const symbols = walkDirForHologram(resolved, dirPath, extensions, stats);
     const byFile = {};
     symbols.forEach((s) => {
         if (!byFile[s.file])
             byFile[s.file] = [];
         byFile[s.file].push({ kind: s.kind, name: s.name, line: s.line });
     });
+    // An empty map is reported as a failure, not as an answer: a silent "0 symbols" is
+    // indistinguishable from a working scan of an empty dir, which is how a parse bug
+    // stayed invisible here before. Say when nothing could be read.
+    const warning = stats.filesScanned === 0
+        ? `No files matching [${extensions.join(", ")}] were found under "${dirPath || "."}" — check the path and extensions.`
+        : symbols.length === 0
+            ? `Scanned ${stats.filesScanned} file(s) but extracted 0 symbols — this is very likely an extraction failure, not an empty codebase. Do not treat this as "the directory has no exports".`
+            : undefined;
     const hologram = {
         workspace: path.basename(workspaceRoot),
         scannedDir: dirPath || ".",
         totalSymbols: symbols.length,
+        filesScanned: stats.filesScanned,
         totalFiles: Object.keys(byFile).length,
+        ...(warning ? { warning } : {}),
+        ...(stats.parseErrors.length > 0
+            ? { parseErrors: stats.parseErrors.slice(0, 10), parseErrorCount: stats.parseErrors.length }
+            : {}),
         map: byFile,
     };
     return { content: [{ type: "text", text: JSON.stringify(hologram, null, 2) }] };
@@ -2100,7 +2283,7 @@ async function handleGetTelepathicHints(args) {
             const similarity = (r.similarity * 100).toFixed(1);
             const prompt = r.query || "Unknown";
             const responseContent = r.response || "";
-            hintsText += `### Hint ${i + 1} (${similarity}% match)\n`;
+            hintsText += `### Hint ${i + 1} (${similarity}% match)${r.outcome === "failed" ? " — ⚠️ FAILED ATTEMPT, do not repeat" : ""}\n`;
             hintsText += `**Memory:** ${prompt}\n\n`;
             hintsText += `${responseContent.substring(0, 400)}${responseContent.length > 400 ? "..." : ""}\n\n---\n\n`;
         });
@@ -2324,7 +2507,7 @@ async function handleCompressContext(args) {
 async function handleSmarterCache(args) {
     const query = args?.query;
     const context = args?.context || "";
-    const threshold = typeof args?.threshold === "number" ? args.threshold : 0.75;
+    const threshold = typeof args?.threshold === "number" ? args.threshold : DEFAULT_MEMORY_SIMILARITY_FLOOR;
     if (!query)
         throw new Error("query is required");
     const fullQuery = context ? `${query}\n\nContext: ${context}` : query;
@@ -2449,48 +2632,64 @@ async function handleTokenReceipt(args) {
 }
 // ── Token Budget ─────────────────────────────────────────────────
 async function handleTokenBudget(_args) {
-    const statsFile = path.join(os.homedir(), '.lemma-cache/stats.json');
     const port = getProxyPort();
-    let stats = {};
+    const schemaTokens = Math.round(getToolSchemaChars() / 4);
+    // /api/savings-breakdown serves SavingsLedger.getSnapshot() — the same ledger that
+    // already nets tokensSaved against what Lemma itself spent (MCP schema injection,
+    // tool-result bytes, cache misses). There is no separate "membership multiplier" to
+    // compute: reusing that one number keeps this tool from reporting a bigger win than
+    // the ledger the user can audit via `token_receipt` actually shows.
+    let snapshot = null;
     try {
-        stats = JSON.parse(fs.readFileSync(statsFile, 'utf8'));
+        const resp = await axios.get(`http://localhost:${port}/api/savings-breakdown`);
+        snapshot = resp.data;
     }
     catch { }
-    let ledger = [];
-    try {
-        const resp = await axios.get(`http://localhost:${port}/api/ledger`);
-        ledger = resp.data.events || [];
+    if (!snapshot) {
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        note: "El proxy de Lemma no está corriendo, así que no hay bitácora de ahorro/costo que leer — no se inventa un número aquí. Arranca el proxy para que este reporte sea real.",
+                        perTurnOverhead: { ...getToolSurfaceSummary(), schemaTokens },
+                    }, null, 2),
+                }],
+        };
     }
-    catch { }
-    const totalTokensSaved = stats.totalTokens || ledger.reduce((sum, e) => sum + (e.tokensImpact || 0), 0);
-    const monthlyTokens = stats.monthlyTokens || stats.totalTokens || 100000;
-    const multiplier = monthlyTokens > 0 ? ((monthlyTokens + totalTokensSaved) / monthlyTokens).toFixed(1) : "N/A";
-    const toolCallCount = ledger.length || stats.toolCalls || 0;
+    const { total, totalCost, net } = snapshot;
+    const ratioStr = net.ratio === Infinity ? "n/a (sin costo registrado todavía)" : `${net.ratio.toFixed(2)}x`;
     return {
         content: [{
                 type: "text",
                 text: JSON.stringify({
-                    membershipMultiplier: `${multiplier}x`,
-                    totalTokensSaved: totalTokensSaved.toLocaleString(),
-                    estimatedTokensPerMonth: monthlyTokens.toLocaleString(),
-                    effectiveBudget: (monthlyTokens + totalTokensSaved).toLocaleString(),
-                    toolCallsOptimized: toolCallCount,
-                    activeStrategies: {
-                        turboSqueeze: true,
-                        contextCompression: true,
-                        semanticCaching: true,
-                        historyPruning: true,
-                        astNavigation: true,
-                        privacyScrubbing: true,
+                    netRatio: ratioStr,
+                    note: "netRatio = tokensSaved / tokensSpent, ambos de la misma bitácora auditable que expone token_receipt. Por debajo de 1.0x, Lemma está costando más de lo que ahorra en esta sesión.",
+                    tokensSaved: total.tokensSaved.toLocaleString(),
+                    tokensSpent: totalCost.tokensSpent.toLocaleString(),
+                    netTokens: net.netTokens.toLocaleString(),
+                    netCostUSD: net.netCost.toFixed(4),
+                    breakdown: {
+                        saved: {
+                            cache: snapshot.cache?.tokensSaved ?? 0,
+                            contextSqueeze: snapshot.contextSqueeze?.tokensSaved ?? 0,
+                            historyPrune: snapshot.historyPrune?.tokensSaved ?? 0,
+                            complexityRouting: snapshot.complexityRouting?.tokensSaved ?? 0,
+                            clipboard: snapshot.clipboard?.tokensSaved ?? 0,
+                        },
+                        spent: {
+                            mcpInstructions: snapshot.costs?.mcpInstructions?.tokensSpent ?? 0,
+                            toolResult: snapshot.costs?.toolResult?.tokensSpent ?? 0,
+                            cacheMiss: snapshot.costs?.cacheMiss?.tokensSpent ?? 0,
+                        },
                     },
                     // The fixed cost of being connected, re-sent on every request of the session.
                     perTurnOverhead: {
                         ...getToolSurfaceSummary(),
-                        schemaTokens: Math.round(getToolSchemaChars() / 4),
+                        schemaTokens,
                         note: "Hidden tools stay callable via lemma_toolbox. Set mcp.toolProfile='full' in lemma.config.json to advertise all of them.",
                     },
-                    recommendations: toolCallCount === 0
-                        ? ["No se han usado tools de Lemma todavía. Asegúrate de que el agente esté usando el prompt lemma-turbomode."]
+                    recommendations: net.ratio !== Infinity && net.ratio < 1
+                        ? ["netRatio < 1.0x: revisa si search_memory/smarter_cache se están llamando antes de razonar, o si el toolProfile anuncia más tools de las que este proyecto necesita — cada schema extra es costo fijo por turno."]
                         : ["Sigue usando turbosqueeze antes de cada code block grande.", "Usa smarter_cache antes de razonar."],
                 }, null, 2),
             }],