@nxuss/lemma 1.6.0 → 1.7.1

package/dist/esm/mcp/tools.js

@@ -5,39 +5,40 @@ import { execSync, spawnSync } from "child_process";
 import os from "os";
 import axios from "axios";
 import * as ts from "typescript";
-import { SemanticScrubber } from "../security/SemanticScrubber";
-import { ComplexityRouter } from "../proxy/ComplexityRouter";
-import { squeezeCode, squeezePrompt, pruneHistoryMessages, generateAstDiff } from "../utils/ContextSqueezer";
-import { reportSavings, reportCost } from "../utils/reportSavings";
-import { getProxyPort, safeResolvePath, logError, logWarn, estimateTokensFromResult, isCommandAllowed, loadAllowedCommands } from "./utils";
-import { computeFingerprint } from "../utils/FileFingerprint";
-import { analyzeBlameHeat } from "../utils/GitBlameHeat";
-import { analyzeTypeCoverage } from "../utils/TypeCoverage";
-import { buildImportTree } from "../utils/ImportTreeContext";
-import { readTokenBudgeted } from "../utils/TokenBudgetedReader";
-import { bulkFileDigest } from "../utils/BulkFileDigest";
-import { autoContextBundle } from "../utils/AutoContextBundle";
-import { checkRepeat, recordOutput } from "../utils/RepeatGuard";
-import { saveCheckpoint, loadLatestCheckpoint, buildCheckpointSummary } from "../utils/ConversationCheckpoint";
-import { runTestAutofix } from "../utils/TestAutofixInterceptor";
-import { findPattern, storePattern, getPatternStats } from "../utils/PromptPatternCache";
-import { runAnalysis, parseDiff } from "../pr-review/PRReviewEngine";
-import { ReviewStore } from "../pr-review/ReviewStore";
-import { runPRReview } from "../pr-review/reviewRunner";
-import { getBrain } from "../subconscious/TheBrainV2";
-import { collapseContext } from "../utils/ContextCollapser";
-import { getSymbolSurgicalContext } from "../utils/SymbolSurgicalContext";
-import { compressWormhole } from "../utils/WormholeCompressor";
-import { generateExecutiveReport } from "../utils/ExecutiveReport";
-import { surgicalASTInsert } from "../utils/SurgicalASTInsert";
-import { getInfraToolDefinitions, getInfraToolHandlers, INFRA_TOOL_NAMES } from "../infra/mcp-tools";
-import { lookupStateHash, storeStateHash } from "../utils/StateHashCache";
-import { recordReceiptEvent, getReceiptSummary } from "../utils/TokenReceipt";
-import { distillCommandOutput, buildDistillFooter, readRegion } from "../utils/CommandOutputDistiller";
-import { findMatch, reindentReplacement } from "../utils/PatchMatcher";
-import { searchWorkspace, groupSearchResults, parseExtensionFilter } from "../utils/WorkspaceSearch";
-import { checkAlreadySent, recordSent } from "../utils/ReadWorkspaceCache";
-import { getCachedSearch, setCachedSearch } from "../utils/SearchCache";
+import { SemanticScrubber } from "../security/SemanticScrubber.js";
+import { ComplexityRouter } from "../proxy/ComplexityRouter.js";
+import { squeezeCode, squeezePrompt, pruneHistoryMessages, generateAstDiff } from "../utils/ContextSqueezer.js";
+import { reportSavings, reportCost } from "../utils/reportSavings.js";
+import { getProxyPort, safeResolvePath, logError, logWarn, estimateTokensFromResult, isCommandAllowed, loadAllowedCommands } from "./utils.js";
+import { computeFingerprint } from "../utils/FileFingerprint.js";
+import { analyzeBlameHeat } from "../utils/GitBlameHeat.js";
+import { analyzeTypeCoverage } from "../utils/TypeCoverage.js";
+import { buildImportTree } from "../utils/ImportTreeContext.js";
+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 { runTestAutofix } from "../utils/TestAutofixInterceptor.js";
+import { findPattern, storePattern, getPatternStats } from "../utils/PromptPatternCache.js";
+import { runAnalysis, parseDiff } from "../pr-review/PRReviewEngine.js";
+import { ReviewStore } from "../pr-review/ReviewStore.js";
+import { runPRReview } from "../pr-review/reviewRunner.js";
+import { getBrain, deriveProjectId } from "../subconscious/TheBrainV2.js";
+import { collapseContext } from "../utils/ContextCollapser.js";
+import { getSymbolSurgicalContext } from "../utils/SymbolSurgicalContext.js";
+import { compressWormhole } from "../utils/WormholeCompressor.js";
+import { generateExecutiveReport } from "../utils/ExecutiveReport.js";
+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 { distillCommandOutput, buildDistillFooter, readRegion } from "../utils/CommandOutputDistiller.js";
+import { findMatch, reindentReplacement } from "../utils/PatchMatcher.js";
+import { searchWorkspace, groupSearchResults, parseExtensionFilter } from "../utils/WorkspaceSearch.js";
+import { checkAlreadySent, recordSent } from "../utils/ReadWorkspaceCache.js";
+import { getCachedSearch, setCachedSearch } from "../utils/SearchCache.js";
 // ── Pro License Gate ──────────────────────────────────────────────────────────
 const LICENSE_FILE = path.join(os.homedir(), '.lemma-cache', 'license.json');
 let _proStatusCache = null;
@@ -62,6 +63,8 @@ const FREE_TOOLS = new Set([
     "token_budget", "squeeze_prompt", "turbosqueeze",
     // Utility — just enough to function
     "read_workspace_file", "scrub_privacy", "summarize_long_text",
+    // Discovery of withheld schemas — gating this would hide tools with no way back
+    "lemma_toolbox",
     // Phase 1 zero-cost analysis tools
     "file_fingerprint", "git_blame_heat", "type_coverage_report", "import_tree_context",
     // Phase 2 smart reading & dedup tools
@@ -990,8 +993,32 @@ const toolDefinitions = [
 ];
 // ── Infrastructure Tool Definitions ──────────────────────────────────────────
 const _infraToolDefs = getInfraToolDefinitions();
-const allToolDefinitions = [...toolDefinitions, ..._infraToolDefs];
-const toolDefinitionsArray = _infraToolDefs.length > 0 ? allToolDefinitions : toolDefinitions;
+// `lemma_toolbox` keeps every non-advertised tool reachable. It is defined here rather
+// than in the main array because it must never itself be hidden.
+const TOOLBOX_TOOL_DEFINITION = {
+    name: "lemma_toolbox",
+    description: "Discover and invoke Lemma tools whose schemas are not loaded this session. Use action='list' (optionally with a query) to see what exists, 'schema' to read one tool's inputs, and 'call' to run it. Every Lemma capability is reachable here.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            action: { type: "string", enum: ["list", "schema", "call"], description: "list | schema | call", default: "list" },
+            query: { type: "string", description: "Filter terms for action='list' (e.g. 'terraform drift')" },
+            tool: { type: "string", description: "Tool name, for action='schema' or 'call'" },
+            args: { type: "object", description: "Arguments passed through to the tool, for action='call'" },
+        },
+        required: ["action"],
+    },
+};
+const allToolDefinitions = [
+    ...toolDefinitions,
+    ..._infraToolDefs,
+    TOOLBOX_TOOL_DEFINITION,
+];
+// Narrow what gets advertised to what this project can actually use. Hidden tools stay
+// registered in `toolHandlers` and callable — both directly and through `lemma_toolbox`.
+const _toolSurface = resolveToolSurface(allToolDefinitions, process.cwd());
+const toolDefinitionsArray = _toolSurface.advertised;
+const hiddenToolDefinitions = _toolSurface.hidden;
 /** Serialized size of every tool schema sent to the client, for cost accounting. */
 export function getToolSchemaChars() {
     try {
@@ -1001,6 +1028,24 @@ export function getToolSchemaChars() {
         return 0;
     }
 }
+/** Every tool name with a registered handler, advertised or not. */
+export function getRegisteredToolNames() {
+    return Object.keys(toolHandlers);
+}
+/** Tool names whose schemas this session sends to the client. */
+export function getAdvertisedToolNames() {
+    return toolDefinitionsArray.map((d) => d.name);
+}
+/** Which tools this session advertises, and why — surfaced by `token_budget`. */
+export function getToolSurfaceSummary() {
+    return {
+        profile: _toolSurface.profile,
+        advertised: toolDefinitionsArray.length,
+        hidden: hiddenToolDefinitions.length,
+        total: allToolDefinitions.length,
+        activeGroups: _toolSurface.activeGroups,
+    };
+}
 const toolHandlers = {
     scrub_privacy: handleScrubPrivacy,
     search_memory: handleSearchMemory,
@@ -1073,8 +1118,44 @@ const toolHandlers = {
     conversation_checkpoint: handleConversationCheckpoint,
     test_autofix_interceptor: handleTestAutofixInterceptor,
     prompt_pattern_cache: handlePromptPatternCache,
+    lemma_toolbox: handleToolbox,
     ...getInfraToolHandlers(),
 };
+/**
+ * Reaches the tools whose schemas were withheld from the session listing.
+ *
+ * `call` proxies through this server rather than relying on the client to emit a name it
+ * never saw advertised — some clients validate outgoing tool names against tools/list, so
+ * the proxy is what makes hiding a schema safe rather than a silent capability loss.
+ */
+async function handleToolbox(args) {
+    const action = args?.action || "list";
+    if (action === "list") {
+        return {
+            content: [{ type: "text", text: buildToolboxCatalog(hiddenToolDefinitions, args?.query) }],
+        };
+    }
+    const toolName = args?.tool;
+    if (!toolName)
+        throw new Error("`tool` is required for action '" + action + "'");
+    if (action === "schema") {
+        const def = allToolDefinitions.find((d) => d.name === toolName);
+        if (!def)
+            throw new Error(`Unknown tool: ${toolName}`);
+        return { content: [{ type: "text", text: JSON.stringify(def, null, 2) }] };
+    }
+    if (action === "call") {
+        const handler = toolHandlers[toolName];
+        if (!handler)
+            throw new Error(`Unknown tool: ${toolName}`);
+        // The proxy must not become a way around the license gate the direct path enforces.
+        if (!isProUser() && !FREE_TOOLS.has(toolName)) {
+            return { content: [{ type: "text", text: PRO_GATE_MESSAGE }] };
+        }
+        return handler((args?.args || {}));
+    }
+    throw new Error(`Unknown action: ${action}. Use 'list', 'schema', or 'call'.`);
+}
 export function setupToolsHandlers(server, onToolCall) {
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: toolDefinitionsArray,
@@ -1151,7 +1232,7 @@ async function handleSearchMemory(args) {
         throw new Error("Query is required");
     try {
         const brain = getBrain();
-        const results = brain.search(query, limit);
+        const results = brain.search(query, limit, 0, { projectId: deriveProjectId() });
         if (results.length === 0) {
             return { content: [{ type: "text", text: "No relevant memories found in Lemma's Brain." }] };
         }
@@ -1233,7 +1314,7 @@ async function handleGetRoutingAdvice(args) {
 async function handleAutoHeal(args) {
     const apply = !!args?.apply;
     try {
-        const { performAutoHeal: heal } = await import("../cli/lemma-proxy");
+        const { performAutoHeal: heal } = await import("../cli/lemma-proxy.js");
         const res = await heal(apply);
         return { content: [{ type: "text", text: JSON.stringify(res, null, 2) }] };
     }
@@ -1636,30 +1717,88 @@ async function handleSqueezePrompt(args) {
         return { content: [{ type: "text", text: `Error squeezing prompt: ${err.message}` }] };
     }
 }
+/**
+ * Onboarding built from the filesystem alone.
+ *
+ * The proxy produces a richer map, but this tool is in the core surface and CLAUDE.md tells
+ * the model to call it first — so when the proxy is down, the first call of every session
+ * used to return an error and the session started with no context at all. A local answer is
+ * strictly better than that, and it never fails.
+ */
+function buildLocalOnboarding(cwd) {
+    const lines = [];
+    const projectName = path.basename(cwd);
+    lines.push(`# ${projectName}`, "");
+    let pkg = null;
+    try {
+        pkg = JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf8"));
+    }
+    catch { /* not a node project */ }
+    if (pkg) {
+        if (pkg.description)
+            lines.push(pkg.description, "");
+        lines.push(`**Version:** ${pkg.version || "unknown"}`);
+        const deps = Object.keys(pkg.dependencies || {});
+        if (deps.length)
+            lines.push(`**Dependencies:** ${deps.slice(0, 12).join(", ")}${deps.length > 12 ? ` (+${deps.length - 12})` : ""}`);
+        const scripts = Object.keys(pkg.scripts || {});
+        if (scripts.length)
+            lines.push(`**Scripts:** ${scripts.slice(0, 12).join(", ")}`);
+    }
+    // Current branch straight from .git/HEAD — no subprocess, works on a detached HEAD too.
+    try {
+        const head = fs.readFileSync(path.join(cwd, ".git", "HEAD"), "utf8").trim();
+        const branch = head.startsWith("ref: ") ? head.replace("ref: refs/heads/", "") : `detached @ ${head.slice(0, 8)}`;
+        lines.push(`**Branch:** ${branch}`);
+    }
+    catch { /* not a git repo */ }
+    try {
+        const entries = fs
+            .readdirSync(cwd, { withFileTypes: true })
+            .filter((e) => e.isDirectory() && !e.name.startsWith(".") && e.name !== "node_modules")
+            .map((e) => e.name);
+        if (entries.length)
+            lines.push(`**Top-level directories:** ${entries.slice(0, 15).join(", ")}`);
+    }
+    catch { /* unreadable cwd */ }
+    try {
+        const memories = getBrain().getEntriesForProject(deriveProjectId(cwd));
+        lines.push("", `**Brain memories for this project:** ${memories.length}`);
+        if (memories.length) {
+            const recent = memories
+                .slice()
+                .sort((a, b) => (a.timestamp < b.timestamp ? 1 : -1))
+                .slice(0, 5);
+            lines.push("", "Most recent:");
+            for (const m of recent)
+                lines.push(`- ${m.query.slice(0, 100)}`);
+            lines.push("", "Use `search_memory` to retrieve any of these in full.");
+        }
+    }
+    catch { /* brain unavailable */ }
+    return lines.join("\n");
+}
 async function handleGetProjectOnboarding(_args) {
+    const cwd = process.cwd();
     try {
         const port = getProxyPort();
-        const response = await axios.get(`http://localhost:${port}/api/project/onboarding`);
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: response.data.markdown || "# Onboarding mental model could not be generated.",
-                },
-            ],
-        };
+        const response = await axios.get(`http://localhost:${port}/api/project/onboarding`, { timeout: 2000 });
+        if (response.data?.markdown) {
+            return { content: [{ type: "text", text: response.data.markdown }] };
+        }
     }
     catch (error) {
-        logError("get_project_onboarding", error);
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Failed to fetch codebase onboarding mental model: ${error.message}. Is Lemma proxy running?`,
-                },
-            ],
-        };
+        // Proxy down or slow — fall through. Not worth surfacing as an error to the model.
+        logError("get_project_onboarding (falling back to local)", error);
     }
+    return {
+        content: [
+            {
+                type: "text",
+                text: `${buildLocalOnboarding(cwd)}\n\n---\n*Generated locally. Start the Lemma proxy (\`lemma start\`) for the full indexed architecture map.*`,
+            },
+        ],
+    };
 }
 function extractSymbolsWithTsCompiler(filePath, relPath) {
     try {
@@ -1887,7 +2026,7 @@ async function handleQueryHybridConsensus(args) {
     const fullQuery = context ? `${query}\n\nContext: ${context}` : query;
     try {
         const brain = getBrain();
-        const results = brain.search(fullQuery, 3);
+        const results = brain.search(fullQuery, 3, 0, { projectId: deriveProjectId() });
         const topHit = results[0];
         if (topHit && topHit.similarity >= threshold) {
             const savedTokens = Math.floor((topHit.response?.length || 500) / 4);
@@ -1945,7 +2084,7 @@ async function handleGetTelepathicHints(args) {
     const telepathicQuery = `${basename} ${dirContext} ${ext} patterns solutions architecture`;
     try {
         const brain = getBrain();
-        const results = brain.search(telepathicQuery, limit);
+        const results = brain.search(telepathicQuery, limit, 0, { projectId: deriveProjectId() });
         if (results.length === 0) {
             return {
                 content: [
@@ -2125,7 +2264,7 @@ async function handleTurboSqueeze(args) {
     const ratio = text.length > 0 ? ((1 - squeezed.length / text.length) * 100).toFixed(1) : "0";
     const saved = Math.max(0, text.length - squeezed.length);
     try {
-        const { reportSavings } = await import("../utils/reportSavings");
+        const { reportSavings } = await import("../utils/reportSavings.js");
         reportSavings({ source: "contextSqueeze", charsBefore: text.length, charsAfter: squeezed.length, toolName: "turbosqueeze" });
     }
     catch { }
@@ -2170,7 +2309,7 @@ async function handleCompressContext(args) {
         ...recent,
     ];
     try {
-        const { reportSavings } = await import("../utils/reportSavings");
+        const { reportSavings } = await import("../utils/reportSavings.js");
         reportSavings({ source: "historyPrune", tokens: tokensSaved, toolName: "compress_context" });
     }
     catch { }
@@ -2191,13 +2330,13 @@ async function handleSmarterCache(args) {
     const fullQuery = context ? `${query}\n\nContext: ${context}` : query;
     try {
         const brain = getBrain();
-        const results = brain.search(fullQuery, 5);
+        const results = brain.search(fullQuery, 5, 0, { projectId: deriveProjectId() });
         const topHit = results[0];
         if (topHit && topHit.similarity >= threshold) {
             const responseText = topHit.response;
             const tokensSaved = Math.floor(responseText.length / 4);
             try {
-                const { reportSavings } = await import("../utils/reportSavings");
+                const { reportSavings } = await import("../utils/reportSavings.js");
                 reportSavings({ source: "cache", tokens: tokensSaved, toolName: "smarter_cache", query: query.substring(0, 100) });
             }
             catch { }
@@ -2344,6 +2483,12 @@ async function handleTokenBudget(_args) {
                         astNavigation: true,
                         privacyScrubbing: true,
                     },
+                    // The fixed cost of being connected, re-sent on every request of the session.
+                    perTurnOverhead: {
+                        ...getToolSurfaceSummary(),
+                        schemaTokens: Math.round(getToolSchemaChars() / 4),
+                        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."]
                         : ["Sigue usando turbosqueeze antes de cada code block grande.", "Usa smarter_cache antes de razonar."],
@@ -2957,7 +3102,8 @@ async function handleSemanticDedupGuard(args) {
         throw new Error("query and response are required");
     try {
         const brain = getBrain();
-        const results = brain.search(query, 3);
+        // A dedup check is not a question the user asked — it must not register as a cache hit.
+        const results = brain.search(query, 3, 0, { countStats: false, projectId: deriveProjectId() });
         const topHit = results[0];
         if (!topHit) {
             return {
@@ -4063,7 +4209,7 @@ async function handleLocalSemanticAutofix(args) {
         throw new Error("errorMessage is required");
     try {
         const brain = getBrain();
-        const results = brain.search(errorMessage, 3, 0.70);
+        const results = brain.search(errorMessage, 3, 0.70, { projectId: deriveProjectId() });
         const topHit = results[0];
         if (topHit) {
             const responseText = topHit.response;