@nxuss/lemma 1.2.4 → 1.3.0

package/README.md

@@ -1,11 +1,11 @@
-# 🧠 Lemma v1.2.0
+# 🧠 Lemma v1.3.0
 
 [![npm version](https://img.shields.io/npm/v/@nxuss/lemma.svg?color=orange&style=flat-square)](https://www.npmjs.com/package/@nxuss/lemma)
 [![License](https://img.shields.io/npm/l/@nxuss/lemma.svg?color=blue&style=flat-square)](https://github.com/Nxusbets/lemma/blob/main/LICENSE)
-[![MCP Tools](https://img.shields.io/badge/MCP%20tools-84-ff69b4?style=flat-square)](https://github.com/Nxusbets/lemma)
+[![MCP Tools](https://img.shields.io/badge/MCP%20tools-92-ff69b4?style=flat-square)](https://github.com/Nxusbets/lemma)
 [![Security](https://img.shields.io/badge/privacy-firewall%20active-blueviolet?style=flat-square)](https://github.com/Nxusbets/lemma)
 [![Caching](https://img.shields.io/badge/semantic%20memory-enabled-success?style=flat-square)](https://github.com/Nxusbets/lemma)
-[![Tests](https://img.shields.io/badge/tests-206%20passing-00c853?style=flat-square)](https://github.com/Nxusbets/lemma)
+[![Tests](https://img.shields.io/badge/tests-199%20passing-00c853?style=flat-square)](https://github.com/Nxusbets/lemma)
 
 ```text
     __                                
@@ -17,13 +17,27 @@
 
 > **The Intelligent local-first AI Gateway — Privacy, Performance, Static Code Intelligence, and Infrastructure Command Center for the Agentic Era.**
 
-Lemma is a high-performance orchestration layer that sits between your development environment and LLM providers. It transforms the way you build with AI by providing **Shared Semantic Memory**, **Autonomous Cost Optimization**, **Privacy Guardrails**, **22 Infrastructure Management Tools**, and a suite of **84 MCP tools** — including zero-token static code intelligence that runs entirely on your machine with no LLM calls required.
+Lemma is a high-performance orchestration layer that sits between your development environment and LLM providers. It transforms the way you build with AI by providing **Shared Semantic Memory**, **Autonomous Cost Optimization**, **Privacy Guardrails**, **22 Infrastructure Management Tools**, and a suite of **92 MCP tools** — including zero-token static code intelligence that runs entirely on your machine with no LLM calls required.
 
 ---
 
 ## 📋 Changelog
 
-### v1.2.0 — Infrastructure Command Center *(NEW)*
+### v1.3.0 — Verifiable Caching *(NEW)*
+
+Two new tools built around a single rule: don't ask the model to trust a similarity score or a
+savings estimate — give it something it can actually verify.
+
+| Tool | Description |
+| :--- | :--- |
+| `state_hash_cache` | Reasoning cache keyed to the sha256 of the files an answer depends on. A hit only fires when those files are byte-identical to when the answer was cached — changing one line forces a guaranteed MISS, no similarity guessing. |
+| `token_receipt` | Per-session auditable ledger of how each answer was produced (exact cache hit, semantic cache hit, file read, fresh reasoning) — a real breakdown instead of a marketing "% saved" number. |
+
+Also in this release: `smarter_cache`'s match threshold moved from 0.75 → 0.8 to cut down false
+hits, `turbosqueeze` no longer touches code shown to the user (internal context only), and file
+insertions default to symbol-level `surgical_ast_insert` patches instead of full-file rewrites.
+
+### v1.2.0 — Infrastructure Command Center
 
 **22 new tools, all FREE**, for managing Jenkins, OKD/OpenShift, and Terraform deployments:
 

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

@@ -1,5 +1,5 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 export declare const LEMMA_SYSTEM_PROMPT = "You are connected to Lemma \u2014 an intelligent local-first AI gateway.\nLemma gives you a set of tools you MUST use proactively and automatically. NEVER ask the user\nto call a tool manually. YOU invoke the tools. The user should experience zero friction.\n\n## MANDATORY AUTOMATIC BEHAVIORS\n\n### 1. Before reading ANY file \u2192 call get_ast_hologram first\nWhen you need to understand the structure of a codebase or navigate files, ALWAYS call\n`get_ast_hologram` first (with the relevant dirPath, e.g. \"src\"). Use the returned symbol\nmap to pinpoint exactly which files to read. NEVER blindly read every file one by one.\n\n### 2. Before answering ANY technical question \u2192 call query_hybrid_consensus first\nBEFORE making any reasoning or cloud LLM call, ALWAYS call `query_hybrid_consensus` with\nthe user's question. If similarity \u2265 80%, return the cached answer immediately \u2014 no cloud\ncall needed. Only proceed with your own reasoning if the Brain returns a MISS.\n\n### 3. When you start working on ANY file \u2192 call get_telepathic_hints automatically\nWhenever the user mentions a file or you are about to read/edit a file, IMMEDIATELY call\n`get_telepathic_hints` with that file's path. Surface the results to the user as relevant\ncontext BEFORE doing any work. Do not ask permission \u2014 just do it.\n\n### 4. Before applying ANY code patch \u2192 call validate_patch_sandbox first\nNEVER call `write_workspace_file` or `apply_workspace_patch` without FIRST calling\n`validate_patch_sandbox` with the proposed content. Only proceed with the write if the\nverdict is \"\u2705 SAFE TO APPLY\". If it fails, fix the issues and re-validate.\n\n### 5. After solving any technical problem \u2192 call store_memory automatically\nAfter resolving a bug, implementing a feature, or answering a significant technical question,\nALWAYS call `store_memory` to persist the solution. Use a descriptive query key so it can\nbe retrieved in future sessions across ALL projects.\n\n### 6. Workspace navigation \u2192 always use Lemma tools, NEVER guess file contents\n- Use `list_workspace_dir` to navigate structure\n- Use `read_workspace_file` (auto-compresses + scrubs secrets) instead of asking the user\n- Use `search_workspace` for text search across files\n- Use `run_workspace_command` for builds, tests, linters\n\n### 7. Privacy is automatic\n`read_workspace_file` and `search_workspace` automatically scrub API keys and PII.\nYou never need to manually sanitize file content.\n\n## LEMMA RESOURCES (auto-subscribe when available)\n- `lemma://runtime/context` \u2014 live crash logs. Read this FIRST when the user reports a bug.\n- `lemma://multiverse/timeline` \u2014 AST history. Use when the user says \"it was working before\".\n- `lemma://project/onboarding` \u2014 architecture map. Read at session start in new repos.\n- `lemma://stats/usage` \u2014 token savings report.\n\nRemember: the user hired YOU to be autonomous. Act like it.";
-export declare const LEMMA_TURBOMODE_PROMPT = "You are operating in LEMMA TURBOMODE. Your goal: multiply the user's LLM membership 50x by spending 50x fewer tokens per task. Every token counts. Every cache hit is a membership extension.\n\n## MANDATORY TURBOMODE RULES \u2014 VIOLATE THESE AND YOU WASTE THE USER'S MONEY\n\n### 0. Before ANYTHING \u2192 check token_budget\nEvery 5 turns, call `token_budget` to check your consumption. If multiplier drops below 10x, optimize harder.\n\n### 1. Before sending ANY code \u2192 call turbosqueeze\nBEFORE including ANY code block in your response, run it through `turbosqueeze` first. Strip comments, collapse whitespace, remove imports. A 500-line file becomes 50 lines. This is your #1 token saver.\n\n### 2. Before reasoning \u2192 call smarter_cache (threshold 0.75)\nNEVER reason from scratch. Call `smarter_cache` with the user's exact question. If similarity >= 75%, return the cached answer INSTANTLY. Zero cloud tokens spent. Only reason if you get a MISS.\n\n### 3. Before every new turn \u2192 call compress_context\nAt the start of any extended interaction, call `compress_context` on the full message history. Keep only the last 3 turns intact. Summarize everything before that into 2 sentences. This keeps your context window lean.\n\n### 4. Before reading files \u2192 call get_ast_hologram\nNEVER read files blindly. Always call `get_ast_hologram` first to locate the exact symbols you need. Then read only those specific files. Each unnecessary file read wastes 1000+ tokens.\n\n### 4b. Before re-reading a file \u2192 call file_fingerprint\nBefore calling read_workspace_file, check if the file hash has changed since last read. If status is 'unchanged', skip the read entirely. Only read when hash differs.\n\n### 4c. Before deep file analysis \u2192 use import_tree_context + type_coverage_report\nInstead of reading full files to understand architecture, call import_tree_context (import graph) and type_coverage_report (type safety). Both are zero-token tools.\n\n### 4d. Before investigating code ownership \u2192 call git_blame_heat\nFor questions about who wrote code, why it's risky, or change history, call git_blame_heat instead of reasoning. Zero LLM cost.\n\n### 5. After every solution \u2192 call store_memory automatically\nEvery bug fix, feature, or answer MUST be stored via `store_memory`. This creates a permanent cache hit for future sessions. The first time costs tokens; every time after is FREE.\n\n### 6. Answer concisely \u2014 no fluff\n- No \"Sure, I can help you with that\" \u2014 just do it.\n- No explanation of what you did \u2014 unless asked.\n- No markdown formatting in internal responses.\n- No repeating the user's question back to them.\n\n### 7. Use batch_tool_calls aggressively\nAny set of independent operations (read 3 files, search 2 patterns, check cache for 2 questions) \u2014 use `batch_tool_calls` to run them in parallel. Single round-trip > multiple sequential calls.\n\n### 8. Before multi-file operations \u2192 use auto_context_bundle or bulk_file_digest\nInstead of reading files one by one, use `auto_context_bundle` (one file, everything included) or `bulk_file_digest` (multiple files, one call). Both save 75-80% round-trips.\n\n### 9. Before outputting long responses \u2192 check repeat_guard\nCall `repeat_guard` with your draft output to avoid repeating yourself. Saves 10-15% of output tokens.\n\n### 10. When resuming work \u2192 load conversation_checkpoint\nAt session start or when user says \"continuemos\", call `conversation_checkpoint` with action \"load\" to restore context without re-explaining.\n\n### 11. When tests fail \u2192 use test_autofix_interceptor\nInstead of manually reading errors and reasoning, call `test_autofix_interceptor` to get failures + Brain-suggested fixes in one call.\n\n### 12. For common prompt patterns \u2192 use prompt_pattern_cache\nBefore generating repetitive prompts (\"explain this\", \"review this\", \"write tests\"), check `prompt_pattern_cache` action \"find\" for cached templates.\n\n## TURBOMODE SCORING\n- Cache HIT = perfect score (0 tokens spent)\n- Cache MISS + compress = good score (< 100 tokens spent on overhead)\n- Reasoning from scratch = bad score (only when absolutely necessary)\n- Reading full files without hologram = FAIL (wasteful)\n\nRemember: this user has a deadline. Every token you save is time and money. Make every token count.";
+export declare const LEMMA_TURBOMODE_PROMPT = "You are operating in LEMMA TURBOMODE. Your goal: multiply the user's LLM membership 50x by spending 50x fewer tokens per task. Every token counts. Every cache hit is a membership extension.\n\n## MANDATORY TURBOMODE RULES \u2014 VIOLATE THESE AND YOU WASTE THE USER'S MONEY\n\n### 0. Before ANYTHING \u2192 check token_budget\nEvery 5 turns, call `token_budget` to check your consumption. If multiplier drops below 10x, optimize harder.\n\n### 1. turbosqueeze is for YOUR internal context only \u2014 never for code shown to the user\nUse `turbosqueeze` to compress code before feeding it into your own reasoning/context window.\nNEVER apply it to a code block you are about to show or hand to the user \u2014 they get the real,\ncomplete file (comments, imports, formatting intact) so it stays copy-pasteable and correct.\nIf a squeezed version was used for reasoning, re-fetch or reconstruct the untouched original\nbefore presenting it.\n\n### 2. smarter_cache (threshold 0.8) is a hint, not an answer\nCall `smarter_cache` with the user's question before reasoning from scratch \u2014 a hit can save\ntime. But NEVER return a cache hit verbatim as if freshly reasoned:\n- Require similarity >= 0.8 (raised from 0.75 \u2014 0.75 was matching questions that weren't\n  actually the same question).\n- Always tell the user the answer came from cache (e.g. \"from a cached earlier answer:\").\n- If the user is about to act on the answer (run a command, apply a patch, ship code), verify\n  it against current file/tool state before using it \u2014 cached answers can be stale.\n- On a MISS, or on any doubt, reason normally.\n\n### 3. Before every new turn \u2192 call compress_context\nAt the start of any extended interaction, call `compress_context` on the full message history. Keep only the last 3 turns intact. Summarize everything before that into 2 sentences. This keeps your context window lean.\n\n### 4. Before reading files \u2192 call get_ast_hologram\nNEVER read files blindly. Always call `get_ast_hologram` first to locate the exact symbols you need. Then read only those specific files. Each unnecessary file read wastes 1000+ tokens.\n\n### 4b. Before re-reading a file \u2192 call file_fingerprint\nBefore calling read_workspace_file, check if the file hash has changed since last read. If status is 'unchanged', skip the read entirely. Only read when hash differs.\n\n### 4c. Before deep file analysis \u2192 use import_tree_context + type_coverage_report\nInstead of reading full files to understand architecture, call import_tree_context (import graph) and type_coverage_report (type safety). Both are zero-token tools.\n\n### 4d. Before investigating code ownership \u2192 call git_blame_heat\nFor questions about who wrote code, why it's risky, or change history, call git_blame_heat instead of reasoning. Zero LLM cost.\n\n### 5. After every solution \u2192 call store_memory automatically\nEvery bug fix, feature, or answer MUST be stored via `store_memory`. This creates a permanent cache hit for future sessions. The first time costs tokens; every time after is FREE.\n\n### 6. Answer concisely \u2014 no fluff\n- No \"Sure, I can help you with that\" \u2014 just do it.\n- No explanation of what you did \u2014 unless asked.\n- No markdown formatting in internal responses.\n- No repeating the user's question back to them.\n\n### 7. Use batch_tool_calls aggressively\nAny set of independent operations (read 3 files, search 2 patterns, check cache for 2 questions) \u2014 use `batch_tool_calls` to run them in parallel. Single round-trip > multiple sequential calls.\n\n### 8. Before multi-file operations \u2192 use auto_context_bundle or bulk_file_digest\nInstead of reading files one by one, use `auto_context_bundle` (one file, everything included) or `bulk_file_digest` (multiple files, one call). Both save 75-80% round-trips.\n\n### 9. Before outputting long responses \u2192 check repeat_guard\nCall `repeat_guard` with your draft output to avoid repeating yourself. Saves 10-15% of output tokens.\n\n### 9b. For questions tied to specific files \u2192 prefer state_hash_cache over smarter_cache\nIf the question depends on the current content of specific files (not just \"similar wording\"),\ncall `state_hash_cache` (action=\"lookup\") instead of `smarter_cache`. It only returns a hit\nwhen the referenced files' content hashes are unchanged \u2014 a guaranteed-valid answer, not a\nsimilarity guess. After answering, call it again with action=\"store\" to cache it. Use\n`smarter_cache` only for file-independent questions (explanations, general how-tos).\n\n### 9c. Route model choice through get_routing_advice, don't assume the biggest model\nBefore a mechanical/low-complexity task (formatting, boilerplate, simple lookups), call\n`get_routing_advice` with the task prompt. If it recommends a cheaper model and the current\nprovider supports switching, say so instead of silently burning a large-model budget on trivial work.\n\n### 9d. Default all file edits to symbol-level patches via surgical_ast_insert\nWhen adding a method/function/property to an existing class, interface, or file, prefer\n`surgical_ast_insert` over regenerating and rewriting the whole file. Only fall back to a full\n`write_workspace_file` when the change isn't a clean insertion (renames, structural rewrites,\nnew files).\n\n### 9e. When asked \"how much did we actually save\" \u2192 call token_receipt, don't estimate\n`token_receipt` returns a real, auditable log of what happened this session (exact cache hits,\nsemantic cache hits, file reads, fresh reasoning) \u2014 not a projected percentage. Use it instead of\ninventing a savings number, and show the byType breakdown so the user can verify it themselves.\n\n### 10. When resuming work \u2192 load conversation_checkpoint\nAt session start or when user says \"continuemos\", call `conversation_checkpoint` with action \"load\" to restore context without re-explaining.\n\n### 11. When tests fail \u2192 use test_autofix_interceptor\nInstead of manually reading errors and reasoning, call `test_autofix_interceptor` to get failures + Brain-suggested fixes in one call.\n\n### 12. For common prompt patterns \u2192 use prompt_pattern_cache\nBefore generating repetitive prompts (\"explain this\", \"review this\", \"write tests\"), check `prompt_pattern_cache` action \"find\" for cached templates.\n\n## TURBOMODE SCORING\n- Cache HIT = perfect score (0 tokens spent)\n- Cache MISS + compress = good score (< 100 tokens spent on overhead)\n- Reasoning from scratch = bad score (only when absolutely necessary)\n- Reading full files without hologram = FAIL (wasteful)\n\nRemember: this user has a deadline. Every token you save is time and money. Make every token count.";
 export declare function setupPromptsHandlers(server: Server): void;
 //# sourceMappingURL=prompts.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/mcp/prompts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAGnE,eAAO,MAAM,mBAAmB,m6FA+C4B,CAAC;AAE7D,eAAO,MAAM,sBAAsB,yyIA6DiE,CAAC;AAErG,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAiDzD"}
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/mcp/prompts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAGnE,eAAO,MAAM,mBAAmB,m6FA+C4B,CAAC;AAE7D,eAAO,MAAM,sBAAsB,ymNA+FiE,CAAC;AAErG,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAiDzD"}

package/dist/cjs/mcp/prompts.js

@@ -58,11 +58,22 @@ exports.LEMMA_TURBOMODE_PROMPT = `You are operating in LEMMA TURBOMODE. Your goa
 ### 0. Before ANYTHING → check token_budget
 Every 5 turns, call \`token_budget\` to check your consumption. If multiplier drops below 10x, optimize harder.
 
-### 1. Before sending ANY code → call turbosqueeze
-BEFORE including ANY code block in your response, run it through \`turbosqueeze\` first. Strip comments, collapse whitespace, remove imports. A 500-line file becomes 50 lines. This is your #1 token saver.
-
-### 2. Before reasoning → call smarter_cache (threshold 0.75)
-NEVER reason from scratch. Call \`smarter_cache\` with the user's exact question. If similarity >= 75%, return the cached answer INSTANTLY. Zero cloud tokens spent. Only reason if you get a MISS.
+### 1. turbosqueeze is for YOUR internal context only — never for code shown to the user
+Use \`turbosqueeze\` to compress code before feeding it into your own reasoning/context window.
+NEVER apply it to a code block you are about to show or hand to the user — they get the real,
+complete file (comments, imports, formatting intact) so it stays copy-pasteable and correct.
+If a squeezed version was used for reasoning, re-fetch or reconstruct the untouched original
+before presenting it.
+
+### 2. smarter_cache (threshold 0.8) is a hint, not an answer
+Call \`smarter_cache\` with the user's question before reasoning from scratch — a hit can save
+time. But NEVER return a cache hit verbatim as if freshly reasoned:
+- Require similarity >= 0.8 (raised from 0.75 — 0.75 was matching questions that weren't
+  actually the same question).
+- Always tell the user the answer came from cache (e.g. "from a cached earlier answer:").
+- If the user is about to act on the answer (run a command, apply a patch, ship code), verify
+  it against current file/tool state before using it — cached answers can be stale.
+- On a MISS, or on any doubt, reason normally.
 
 ### 3. Before every new turn → call compress_context
 At the start of any extended interaction, call \`compress_context\` on the full message history. Keep only the last 3 turns intact. Summarize everything before that into 2 sentences. This keeps your context window lean.
@@ -97,6 +108,29 @@ Instead of reading files one by one, use \`auto_context_bundle\` (one file, ever
 ### 9. Before outputting long responses → check repeat_guard
 Call \`repeat_guard\` with your draft output to avoid repeating yourself. Saves 10-15% of output tokens.
 
+### 9b. For questions tied to specific files → prefer state_hash_cache over smarter_cache
+If the question depends on the current content of specific files (not just "similar wording"),
+call \`state_hash_cache\` (action="lookup") instead of \`smarter_cache\`. It only returns a hit
+when the referenced files' content hashes are unchanged — a guaranteed-valid answer, not a
+similarity guess. After answering, call it again with action="store" to cache it. Use
+\`smarter_cache\` only for file-independent questions (explanations, general how-tos).
+
+### 9c. Route model choice through get_routing_advice, don't assume the biggest model
+Before a mechanical/low-complexity task (formatting, boilerplate, simple lookups), call
+\`get_routing_advice\` with the task prompt. If it recommends a cheaper model and the current
+provider supports switching, say so instead of silently burning a large-model budget on trivial work.
+
+### 9d. Default all file edits to symbol-level patches via surgical_ast_insert
+When adding a method/function/property to an existing class, interface, or file, prefer
+\`surgical_ast_insert\` over regenerating and rewriting the whole file. Only fall back to a full
+\`write_workspace_file\` when the change isn't a clean insertion (renames, structural rewrites,
+new files).
+
+### 9e. When asked "how much did we actually save" → call token_receipt, don't estimate
+\`token_receipt\` returns a real, auditable log of what happened this session (exact cache hits,
+semantic cache hits, file reads, fresh reasoning) — not a projected percentage. Use it instead of
+inventing a savings number, and show the byType breakdown so the user can verify it themselves.
+
 ### 10. When resuming work → load conversation_checkpoint
 At session start or when user says "continuemos", call \`conversation_checkpoint\` with action "load" to restore context without re-explaining.
 

package/dist/cjs/mcp/prompts.js.map

@@ -1 +1 @@
-{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../../../src/mcp/prompts.ts"],"names":[],"mappings":";;;AAmHA,oDAiDC;AAnKD,iEAAsG;AAEzF,QAAA,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4DA+CyB,CAAC;AAEhD,QAAA,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oGA6D8D,CAAC;AAErG,SAAgB,oBAAoB,CAAC,MAAc;IACjD,MAAM,CAAC,iBAAiB,CAAC,mCAAwB,EAAE,KAAK,IAAI,EAAE;QAC5D,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,iBAAiB;oBACvB,WAAW,EAAE,+JAA+J;oBAC5K,SAAS,EAAE,EAAE;iBACd;gBACD;oBACE,IAAI,EAAE,iBAAiB;oBACvB,WAAW,EAAE,wOAAwO;oBACrP,SAAS,EAAE,EAAE;iBACd;aACF;SACF,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,iBAAiB,CAAC,iCAAsB,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QACjE,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,iBAAiB,EAAE,CAAC;YAC9C,OAAO;gBACL,WAAW,EAAE,qCAAqC;gBAClD,QAAQ,EAAE;oBACR;wBACE,IAAI,EAAE,MAAM;wBACZ,OAAO,EAAE;4BACP,IAAI,EAAE,MAAM;4BACZ,IAAI,EAAE,2BAAmB;yBAC1B;qBACF;iBACF;aACF,CAAC;QACJ,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,iBAAiB,EAAE,CAAC;YAC9C,OAAO;gBACL,WAAW,EAAE,8CAA8C;gBAC3D,QAAQ,EAAE;oBACR;wBACE,IAAI,EAAE,MAAM;wBACZ,OAAO,EAAE;4BACP,IAAI,EAAE,MAAM;4BACZ,IAAI,EAAE,8BAAsB;yBAC7B;qBACF;iBACF;aACF,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,mBAAmB,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IAC5D,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../../../src/mcp/prompts.ts"],"names":[],"mappings":";;;AAqJA,oDAiDC;AArMD,iEAAsG;AAEzF,QAAA,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4DA+CyB,CAAC;AAEhD,QAAA,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oGA+F8D,CAAC;AAErG,SAAgB,oBAAoB,CAAC,MAAc;IACjD,MAAM,CAAC,iBAAiB,CAAC,mCAAwB,EAAE,KAAK,IAAI,EAAE;QAC5D,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,iBAAiB;oBACvB,WAAW,EAAE,+JAA+J;oBAC5K,SAAS,EAAE,EAAE;iBACd;gBACD;oBACE,IAAI,EAAE,iBAAiB;oBACvB,WAAW,EAAE,wOAAwO;oBACrP,SAAS,EAAE,EAAE;iBACd;aACF;SACF,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,iBAAiB,CAAC,iCAAsB,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QACjE,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,iBAAiB,EAAE,CAAC;YAC9C,OAAO;gBACL,WAAW,EAAE,qCAAqC;gBAClD,QAAQ,EAAE;oBACR;wBACE,IAAI,EAAE,MAAM;wBACZ,OAAO,EAAE;4BACP,IAAI,EAAE,MAAM;4BACZ,IAAI,EAAE,2BAAmB;yBAC1B;qBACF;iBACF;aACF,CAAC;QACJ,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,iBAAiB,EAAE,CAAC;YAC9C,OAAO;gBACL,WAAW,EAAE,8CAA8C;gBAC3D,QAAQ,EAAE;oBACR;wBACE,IAAI,EAAE,MAAM;wBACZ,OAAO,EAAE;4BACP,IAAI,EAAE,MAAM;4BACZ,IAAI,EAAE,8BAAsB;yBAC7B;qBACF;iBACF;aACF,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,mBAAmB,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IAC5D,CAAC,CAAC,CAAC;AACL,CAAC"}

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;AA2gCnE,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,CA2DN"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAwiCnE,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,CA2DN"}

package/dist/cjs/mcp/tools.js

@@ -70,6 +70,8 @@ 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 StateHashCache_1 = require("../utils/StateHashCache");
+const TokenReceipt_1 = require("../utils/TokenReceipt");
 // ── Pro License Gate ──────────────────────────────────────────────────────────
 const LICENSE_FILE = path_1.default.join(os_1.default.homedir(), '.lemma-cache', 'license.json');
 let _proStatusCache = null;
@@ -89,7 +91,7 @@ function isProUser() {
 }
 const FREE_TOOLS = new Set([
     // Cache & Memory — the hook that shows instant value
-    "smarter_cache", "search_memory", "store_memory",
+    "smarter_cache", "state_hash_cache", "token_receipt", "search_memory", "store_memory",
     // Token optimization — shows what they're saving
     "token_budget", "squeeze_prompt", "turbosqueeze",
     // Utility — just enough to function
@@ -492,6 +494,31 @@ const toolDefinitions = [
             required: ["query"],
         },
     },
+    {
+        name: "state_hash_cache",
+        description: "Cache de razonamiento con invalidación EXACTA (no probabilística): la respuesta queda atada al sha256 del contenido de los archivos de los que depende. Si esos archivos no cambiaron, el hit es matemáticamente válido, no una adivinanza por similitud. Usa action='lookup' antes de razonar sobre una pregunta que dependa de archivos específicos, y action='store' después de responder para cachearla.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                action: { type: "string", enum: ["lookup", "store"], description: "lookup = buscar antes de razonar; store = guardar después de responder" },
+                query: { type: "string", description: "La pregunta o task, texto exacto" },
+                filePaths: { type: "array", items: { type: "string" }, description: "Archivos (relativos al workspace root) de los que depende la respuesta" },
+                answer: { type: "string", description: "Requerido solo para action='store': la respuesta a cachear" },
+            },
+            required: ["action", "query", "filePaths"],
+        },
+    },
+    {
+        name: "token_receipt",
+        description: "Recibo auditable de la sesión: de dónde vino cada respuesta (cache exacto, cache semántico, lectura de archivo, o razonamiento fresco). No es una estadística de 'ahorro' — es una bitácora verificable para que el usuario pueda comprobar que no se le está mintiendo con un cache hit inventado. Llamar con action='summary' para ver el reporte.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                action: { type: "string", enum: ["summary"], default: "summary" },
+                limit: { type: "number", description: "Cuántos eventos recientes incluir en el detalle", default: 20 },
+            },
+        },
+    },
     {
         name: "token_budget",
         description: "Muestra el dashboard de consumo: multiplicador actual de membresía, tokens ahorrados, tools usadas, y recomendaciones para optimizar más. Consultar periódicamente para auto-regular consumo.",
@@ -1007,6 +1034,8 @@ const toolHandlers = {
     local_semantic_autofix: handleLocalSemanticAutofix,
     compress_context: handleCompressContext,
     smarter_cache: handleSmarterCache,
+    state_hash_cache: handleStateHashCache,
+    token_receipt: handleTokenReceipt,
     token_budget: handleTokenBudget,
     entropy_score: handleEntropyScore,
     coupling_radar: handleCouplingRadar,
@@ -2109,6 +2138,69 @@ async function handleSmarterCache(args) {
         };
     }
 }
+// ── State Hash Cache (exact, non-probabilistic reasoning cache) ────
+async function handleStateHashCache(args) {
+    const action = args?.action;
+    const query = args?.query;
+    const filePaths = Array.isArray(args?.filePaths) ? args.filePaths : [];
+    if (!action || !query)
+        throw new Error("action and query are required");
+    const workspaceRoot = process.cwd();
+    if (action === "lookup") {
+        const result = (0, StateHashCache_1.lookupStateHash)(workspaceRoot, query, filePaths);
+        (0, TokenReceipt_1.recordReceiptEvent)(result.status === "hit" ? "exact_cache_hit" : "reasoning", query.substring(0, 100), { tool: "state_hash_cache", filePaths, reason: result.reason });
+        if (result.status === "hit" && result.entry) {
+            const tokensSaved = Math.floor(result.entry.answer.length / 4);
+            try {
+                (0, reportSavings_1.reportSavings)({ source: "cache", tokens: tokensSaved, toolName: "state_hash_cache", query: query.substring(0, 100) });
+            }
+            catch { }
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            status: "hit",
+                            answer: result.entry.answer,
+                            note: "Respuesta desde caché exacto (hash de archivos sin cambios) — no necesita re-razonar.",
+                            tokensSaved,
+                        }, null, 2),
+                    }],
+            };
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({ status: "miss", reason: result.reason, hint: "Razona normalmente y luego llama action='store' con la respuesta." }, null, 2),
+                }],
+        };
+    }
+    if (action === "store") {
+        const answer = args?.answer;
+        if (!answer)
+            throw new Error("answer is required for action='store'");
+        const entry = (0, StateHashCache_1.storeStateHash)(workspaceRoot, query, answer, filePaths);
+        return {
+            content: [{ type: "text", text: JSON.stringify({ status: "stored", id: entry.id, filesTracked: Object.keys(entry.fileHashes) }, null, 2) }],
+        };
+    }
+    throw new Error(`Unknown action: ${action}. Use 'lookup' or 'store'.`);
+}
+// ── Token Receipt (auditable ledger, not a marketing stat) ─────────
+async function handleTokenReceipt(args) {
+    const limit = typeof args?.limit === "number" ? args.limit : 20;
+    const summary = (0, TokenReceipt_1.getReceiptSummary)(limit);
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify({
+                    totalEvents: summary.totalEvents,
+                    byType: summary.byType,
+                    recentEvents: summary.recent,
+                    note: "Esto es una bitácora real de esta sesión, no una proyección de ahorro. Si byType.reasoning es alto, no hubo mucho cache — y está bien, es honesto.",
+                }, null, 2),
+            }],
+    };
+}
 // ── Token Budget ─────────────────────────────────────────────────
 async function handleTokenBudget(_args) {
     const statsFile = path_1.default.join(os_1.default.homedir(), '.lemma-cache/stats.json');