@nxuss/lemma 1.6.0 → 1.7.1

package/dist/cjs/mcp/tool-profiles.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Tool surface control.
+ *
+ * Every tool schema Lemma advertises is injected into the model's system prompt and
+ * re-sent on every single request of the session. At 76 tools that is ~11.4k tokens
+ * per turn, charged before Lemma has saved anything — and it is charged even for tools
+ * the project can never use (Terraform schemas in a repo with no `.tf` files).
+ *
+ * So the advertised list is narrowed to what this project can actually use. Nothing is
+ * removed: every handler stays registered, and `lemma_toolbox` exposes the rest by name
+ * on demand — a one-time ~1.2k token catalog instead of ~8k every turn.
+ *
+ * The list is resolved once at startup and never mutated mid-session. It lives in the
+ * cached prefix of every request; changing it (e.g. lazily "unlocking" tools via
+ * notifications/tools/list_changed) invalidates that cache and re-charges the whole
+ * context at full price, which costs far more than the schemas it would defer.
+ */
+export type ToolProfile = "auto" | "core" | "full";
+/**
+ * Tools that pay for their schema in an ordinary coding session: reading, searching,
+ * patching, AST context, exact-hash caching, and the ledger. Everything else is
+ * situational and reachable through `lemma_toolbox`.
+ */
+export declare const CORE_TOOL_NAMES: string[];
+/**
+ * Code review is a mode the user enters, not a property of the repo — and it cannot be
+ * detected at startup. Gating these on `.git` advertised them in every git repo, which is
+ * every repo: ~670 tokens per turn for tools most sessions never touch. They stay
+ * registered and `lemma_toolbox` finds them by query the moment a review actually starts.
+ */
+export declare const REVIEW_TOOL_NAMES: string[];
+export interface ResolvedToolSurface<T extends {
+    name: string;
+}> {
+    profile: ToolProfile;
+    /** Schemas advertised in tools/list. */
+    advertised: T[];
+    /** Registered and callable, but not advertised — reachable through `lemma_toolbox`. */
+    hidden: T[];
+    /** Situational groups that matched this project. */
+    activeGroups: string[];
+}
+export declare function resolveToolSurface<T extends {
+    name: string;
+    description?: string;
+}>(allDefinitions: T[], cwd?: string): ResolvedToolSurface<T>;
+/**
+ * One-line-per-tool catalog of everything not advertised, so the model can find and
+ * invoke a hidden tool without its schema having been resident all session.
+ */
+export declare function buildToolboxCatalog(hidden: Array<{
+    name: string;
+    description?: string;
+}>, query?: string): string;
+//# sourceMappingURL=tool-profiles.d.ts.map

package/dist/cjs/mcp/tool-profiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-profiles.d.ts","sourceRoot":"","sources":["../../../src/mcp/tool-profiles.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAEnD;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,EA0BnC,CAAC;AA4DF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,UAAoE,CAAC;AAkBnG,MAAM,WAAW,mBAAmB,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE;IAC7D,OAAO,EAAE,WAAW,CAAC;IACrB,wCAAwC;IACxC,UAAU,EAAE,CAAC,EAAE,CAAC;IAChB,uFAAuF;IACvF,MAAM,EAAE,CAAC,EAAE,CAAC;IACZ,oDAAoD;IACpD,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,wBAAgB,kBAAkB,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,EACjF,cAAc,EAAE,CAAC,EAAE,EACnB,GAAG,GAAE,MAAsB,GAC1B,mBAAmB,CAAC,CAAC,CAAC,CAmCxB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,EACrD,KAAK,CAAC,EAAE,MAAM,GACb,MAAM,CAuDR"}

package/dist/cjs/mcp/tool-profiles.js

@@ -0,0 +1,204 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REVIEW_TOOL_NAMES = exports.CORE_TOOL_NAMES = void 0;
+exports.resolveToolSurface = resolveToolSurface;
+exports.buildToolboxCatalog = buildToolboxCatalog;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+/**
+ * Tools that pay for their schema in an ordinary coding session: reading, searching,
+ * patching, AST context, exact-hash caching, and the ledger. Everything else is
+ * situational and reachable through `lemma_toolbox`.
+ */
+exports.CORE_TOOL_NAMES = [
+    // Workspace read & navigation
+    "read_workspace_file",
+    "list_workspace_dir",
+    "search_workspace",
+    "smart_file_slice",
+    "run_workspace_command",
+    "output_region",
+    // Write path — patch, then validate before it lands
+    "apply_workspace_patch",
+    "write_workspace_file",
+    "create_workspace_file",
+    "surgical_ast_insert",
+    "validate_patch_sandbox",
+    // Structure without reading whole files
+    "get_ast_hologram",
+    "get_symbol_surgical_context",
+    "get_project_onboarding",
+    // Avoid re-deriving what was already derived
+    "state_hash_cache",
+    "smarter_cache",
+    "search_memory",
+    "store_memory",
+    // Accounting & routing
+    "token_receipt",
+    "get_routing_advice",
+];
+const exists = (cwd, ...rel) => rel.some((r) => {
+    try {
+        return fs_1.default.existsSync(path_1.default.join(cwd, r));
+    }
+    catch {
+        return false;
+    }
+});
+/** Shallow scan for an extension — deep walks at startup would cost more than they save. */
+function hasExtension(cwd, ext, depth = 2) {
+    const walk = (dir, left) => {
+        let entries;
+        try {
+            entries = fs_1.default.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return false;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith(".") || entry.name === "node_modules")
+                continue;
+            if (entry.isFile() && entry.name.endsWith(ext))
+                return true;
+            if (entry.isDirectory() && left > 0 && walk(path_1.default.join(dir, entry.name), left - 1))
+                return true;
+        }
+        return false;
+    };
+    return walk(cwd, depth);
+}
+const TOOL_GROUPS = [
+    {
+        name: "infra",
+        tools: [
+            "infra_discover", "infra_connect", "infra_status", "infra_health_check",
+            "infra_diagnose", "infra_analyze_monolith", "infra_suggest_split",
+            "jenkins_generate_pipeline", "jenkins_trigger_build", "jenkins_build_status", "jenkins_logs",
+            "okd_generate_manifests", "okd_apply", "okd_status", "okd_logs", "okd_events",
+            "okd_describe", "okd_route_url",
+            "terraform_plan", "terraform_apply", "terraform_state_list", "terraform_drift",
+        ],
+        applies: (cwd) => 
+        // A provider already connected, or the repo actually contains infra to act on.
+        exists(process.env.HOME || "", ".lemma-cache/infra/config.json") ||
+            exists(cwd, "Jenkinsfile", "kustomization.yaml", ".openshift", "openshift") ||
+            hasExtension(cwd, ".tf", 2),
+    },
+];
+/**
+ * Code review is a mode the user enters, not a property of the repo — and it cannot be
+ * detected at startup. Gating these on `.git` advertised them in every git repo, which is
+ * every repo: ~670 tokens per turn for tools most sessions never touch. They stay
+ * registered and `lemma_toolbox` finds them by query the moment a review actually starts.
+ */
+exports.REVIEW_TOOL_NAMES = ["review_diff", "review_pr", "pr_status", "generate_pr_workflow"];
+function readConfiguredProfile(cwd) {
+    try {
+        const configPath = path_1.default.join(cwd, "lemma.config.json");
+        if (fs_1.default.existsSync(configPath)) {
+            const config = JSON.parse(fs_1.default.readFileSync(configPath, "utf8"));
+            const profile = config?.mcp?.toolProfile;
+            if (profile === "core" || profile === "full" || profile === "auto")
+                return profile;
+        }
+    }
+    catch {
+        // Unreadable config must never change which tools work — fall through to the default.
+    }
+    const env = process.env.LEMMA_TOOL_PROFILE;
+    if (env === "core" || env === "full" || env === "auto")
+        return env;
+    return "auto";
+}
+function resolveToolSurface(allDefinitions, cwd = process.cwd()) {
+    const profile = readConfiguredProfile(cwd);
+    if (profile === "full") {
+        return { profile, advertised: allDefinitions, hidden: [], activeGroups: ["*"] };
+    }
+    // Always advertised: it is the only route back to a withheld schema, so hiding it
+    // would turn a deferred tool into a lost one.
+    const allowed = new Set([...exports.CORE_TOOL_NAMES, "lemma_toolbox"]);
+    const activeGroups = [];
+    if (profile === "auto") {
+        for (const group of TOOL_GROUPS) {
+            let matched = false;
+            try {
+                matched = group.applies(cwd);
+            }
+            catch {
+                // Detection must never be the reason a tool disappears; on error, include it.
+                matched = true;
+            }
+            if (matched) {
+                activeGroups.push(group.name);
+                group.tools.forEach((t) => allowed.add(t));
+            }
+        }
+    }
+    const advertised = [];
+    const hidden = [];
+    for (const def of allDefinitions) {
+        (allowed.has(def.name) ? advertised : hidden).push(def);
+    }
+    return { profile, advertised, hidden, activeGroups };
+}
+/**
+ * One-line-per-tool catalog of everything not advertised, so the model can find and
+ * invoke a hidden tool without its schema having been resident all session.
+ */
+function buildToolboxCatalog(hidden, query) {
+    const q = (query || "").trim().toLowerCase();
+    const terms = q ? q.split(/\s+/).filter(Boolean) : [];
+    let matches = hidden;
+    if (terms.length) {
+        // Plain substring matching floods the result: "pr" hits scrub_privacy, precrime_static
+        // and compress_context, so a 3-word query returns the whole catalog and costs more
+        // than the schemas it was meant to replace. Match on word boundaries and rank by how
+        // many distinct terms a tool hits, so the tools the user meant come first.
+        const scored = hidden
+            .map((t) => {
+            const haystack = `${t.name} ${t.description || ""}`.toLowerCase();
+            const words = new Set(haystack.split(/[^a-z0-9]+/).filter(Boolean));
+            let score = 0;
+            for (const term of terms) {
+                if (words.has(term))
+                    score += 2; // whole word — the strong signal
+                else if (term.length >= 4 && haystack.includes(term))
+                    score += 1; // prefix/partial
+            }
+            return { tool: t, score };
+        })
+            .filter((s) => s.score > 0)
+            .sort((a, b) => b.score - a.score);
+        // A whole-word hit is a real match; partials only get shown when nothing matched a
+        // whole word, so a weak substring never crowds out the tool the user asked for.
+        const hasWordHit = scored.some((s) => s.score >= 2);
+        matches = scored.filter((s) => (hasWordHit ? s.score >= 2 : true)).map((s) => s.tool);
+    }
+    const CATALOG_LIMIT = 15;
+    const truncated = Math.max(0, matches.length - CATALOG_LIMIT);
+    const shown = matches.slice(0, CATALOG_LIMIT);
+    if (matches.length === 0) {
+        return terms.length
+            ? `No hidden Lemma tool matches "${query}". ${hidden.length} tools available; call lemma_toolbox with no query to list all.`
+            : "No hidden tools — every Lemma tool is already advertised in this session.";
+    }
+    const lines = shown.map((t) => {
+        // One line per tool: enough to choose, not enough to be a second schema listing.
+        const desc = (t.description || "").split(/\.\s|\n/)[0].slice(0, 100);
+        return `- ${t.name}: ${desc}`;
+    });
+    return [
+        `${matches.length} Lemma tool(s) available but not advertised (schemas withheld to keep per-turn context small).`,
+        `Invoke one with: lemma_toolbox { action: "call", tool: "<name>", args: { ... } }`,
+        "",
+        ...lines,
+        ...(truncated > 0 ? [`… and ${truncated} more — narrow the query to see them.`] : []),
+        "",
+        `Call lemma_toolbox { action: "schema", tool: "<name>" } for a tool's full input schema before calling it.`,
+    ].join("\n");
+}
+//# sourceMappingURL=tool-profiles.js.map

package/dist/cjs/mcp/tool-profiles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-profiles.js","sourceRoot":"","sources":["../../../src/mcp/tool-profiles.ts"],"names":[],"mappings":"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"}

package/dist/cjs/mcp/tools.d.ts

@@ -1,6 +1,18 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 /** Serialized size of every tool schema sent to the client, for cost accounting. */
 export declare function getToolSchemaChars(): number;
+/** Every tool name with a registered handler, advertised or not. */
+export declare function getRegisteredToolNames(): string[];
+/** Tool names whose schemas this session sends to the client. */
+export declare function getAdvertisedToolNames(): string[];
+/** Which tools this session advertises, and why — surfaced by `token_budget`. */
+export declare function getToolSurfaceSummary(): {
+    profile: string;
+    advertised: number;
+    hidden: number;
+    total: number;
+    activeGroups: string[];
+};
 export interface ToolCallEvent {
     tool: string;
     args: Record<string, any>;

package/dist/cjs/mcp/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AA4/BnE,oFAAoF;AACpF,wBAAgB,kBAAkB,IAAI,MAAM,CAM3C;AA6ED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC1B,MAAM,EAAE,IAAI,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAC1C,IAAI,CA+DN"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AA2hCnE,oFAAoF;AACpF,wBAAgB,kBAAkB,IAAI,MAAM,CAM3C;AAED,oEAAoE;AACpE,wBAAgB,sBAAsB,IAAI,MAAM,EAAE,CAEjD;AAED,iEAAiE;AACjE,wBAAgB,sBAAsB,IAAI,MAAM,EAAE,CAEjD;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,IAAI;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB,CAQA;AAoHD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC1B,MAAM,EAAE,IAAI,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAC1C,IAAI,CA+DN"}

package/dist/cjs/mcp/tools.js

@@ -37,6 +37,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getToolSchemaChars = getToolSchemaChars;
+exports.getRegisteredToolNames = getRegisteredToolNames;
+exports.getAdvertisedToolNames = getAdvertisedToolNames;
+exports.getToolSurfaceSummary = getToolSurfaceSummary;
 exports.setupToolsHandlers = setupToolsHandlers;
 const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
 const fs_1 = __importDefault(require("fs"));
@@ -71,6 +74,7 @@ const WormholeCompressor_1 = require("../utils/WormholeCompressor");
 const ExecutiveReport_1 = require("../utils/ExecutiveReport");
 const SurgicalASTInsert_1 = require("../utils/SurgicalASTInsert");
 const mcp_tools_1 = require("../infra/mcp-tools");
+const tool_profiles_1 = require("./tool-profiles");
 const StateHashCache_1 = require("../utils/StateHashCache");
 const TokenReceipt_1 = require("../utils/TokenReceipt");
 const CommandOutputDistiller_1 = require("../utils/CommandOutputDistiller");
@@ -102,6 +106,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
@@ -1030,8 +1036,32 @@ const toolDefinitions = [
 ];
 // ── Infrastructure Tool Definitions ──────────────────────────────────────────
 const _infraToolDefs = (0, mcp_tools_1.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 = (0, tool_profiles_1.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. */
 function getToolSchemaChars() {
     try {
@@ -1041,6 +1071,24 @@ function getToolSchemaChars() {
         return 0;
     }
 }
+/** Every tool name with a registered handler, advertised or not. */
+function getRegisteredToolNames() {
+    return Object.keys(toolHandlers);
+}
+/** Tool names whose schemas this session sends to the client. */
+function getAdvertisedToolNames() {
+    return toolDefinitionsArray.map((d) => d.name);
+}
+/** Which tools this session advertises, and why — surfaced by `token_budget`. */
+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,
@@ -1113,8 +1161,44 @@ const toolHandlers = {
     conversation_checkpoint: handleConversationCheckpoint,
     test_autofix_interceptor: handleTestAutofixInterceptor,
     prompt_pattern_cache: handlePromptPatternCache,
+    lemma_toolbox: handleToolbox,
     ...(0, mcp_tools_1.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: (0, tool_profiles_1.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'.`);
+}
 function setupToolsHandlers(server, onToolCall) {
     server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
         tools: toolDefinitionsArray,
@@ -1191,7 +1275,7 @@ async function handleSearchMemory(args) {
         throw new Error("Query is required");
     try {
         const brain = (0, TheBrainV2_1.getBrain)();
-        const results = brain.search(query, limit);
+        const results = brain.search(query, limit, 0, { projectId: (0, TheBrainV2_1.deriveProjectId)() });
         if (results.length === 0) {
             return { content: [{ type: "text", text: "No relevant memories found in Lemma's Brain." }] };
         }
@@ -1676,30 +1760,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_1.default.basename(cwd);
+    lines.push(`# ${projectName}`, "");
+    let pkg = null;
+    try {
+        pkg = JSON.parse(fs_1.default.readFileSync(path_1.default.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_1.default.readFileSync(path_1.default.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_1.default
+            .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 = (0, TheBrainV2_1.getBrain)().getEntriesForProject((0, TheBrainV2_1.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 = (0, utils_1.getProxyPort)();
-        const response = await axios_1.default.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_1.default.get(`http://localhost:${port}/api/project/onboarding`, { timeout: 2000 });
+        if (response.data?.markdown) {
+            return { content: [{ type: "text", text: response.data.markdown }] };
+        }
     }
     catch (error) {
-        (0, utils_1.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.
+        (0, utils_1.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 {
@@ -1927,7 +2069,7 @@ async function handleQueryHybridConsensus(args) {
     const fullQuery = context ? `${query}\n\nContext: ${context}` : query;
     try {
         const brain = (0, TheBrainV2_1.getBrain)();
-        const results = brain.search(fullQuery, 3);
+        const results = brain.search(fullQuery, 3, 0, { projectId: (0, TheBrainV2_1.deriveProjectId)() });
         const topHit = results[0];
         if (topHit && topHit.similarity >= threshold) {
             const savedTokens = Math.floor((topHit.response?.length || 500) / 4);
@@ -1985,7 +2127,7 @@ async function handleGetTelepathicHints(args) {
     const telepathicQuery = `${basename} ${dirContext} ${ext} patterns solutions architecture`;
     try {
         const brain = (0, TheBrainV2_1.getBrain)();
-        const results = brain.search(telepathicQuery, limit);
+        const results = brain.search(telepathicQuery, limit, 0, { projectId: (0, TheBrainV2_1.deriveProjectId)() });
         if (results.length === 0) {
             return {
                 content: [
@@ -2231,7 +2373,7 @@ async function handleSmarterCache(args) {
     const fullQuery = context ? `${query}\n\nContext: ${context}` : query;
     try {
         const brain = (0, TheBrainV2_1.getBrain)();
-        const results = brain.search(fullQuery, 5);
+        const results = brain.search(fullQuery, 5, 0, { projectId: (0, TheBrainV2_1.deriveProjectId)() });
         const topHit = results[0];
         if (topHit && topHit.similarity >= threshold) {
             const responseText = topHit.response;
@@ -2384,6 +2526,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."],
@@ -2997,7 +3145,8 @@ async function handleSemanticDedupGuard(args) {
         throw new Error("query and response are required");
     try {
         const brain = (0, TheBrainV2_1.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: (0, TheBrainV2_1.deriveProjectId)() });
         const topHit = results[0];
         if (!topHit) {
             return {
@@ -4103,7 +4252,7 @@ async function handleLocalSemanticAutofix(args) {
         throw new Error("errorMessage is required");
     try {
         const brain = (0, TheBrainV2_1.getBrain)();
-        const results = brain.search(errorMessage, 3, 0.70);
+        const results = brain.search(errorMessage, 3, 0.70, { projectId: (0, TheBrainV2_1.deriveProjectId)() });
         const topHit = results[0];
         if (topHit) {
             const responseText = topHit.response;