@nxuss/lemma 1.7.2 → 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";
@@ -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
@@ -114,7 +114,7 @@ const toolDefinitions = [
     },
     {
         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: {
@@ -122,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"],
         },
@@ -273,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.",
@@ -1121,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,
@@ -1306,7 +1330,7 @@ async function handleSearchMemory(args) {
         }
         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.
@@ -1347,11 +1371,15 @@ 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 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.
@@ -1361,7 +1389,9 @@ async function handleStoreMemory(args) {
             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);
@@ -1880,6 +1910,59 @@ async function handleGetProjectOnboarding(_args) {
         ],
     };
 }
+// ── 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");
@@ -2200,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`;
         });
@@ -2549,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),
             }],