@nxuss/lemma 1.5.0 → 1.6.0

package/README.md

@@ -1,11 +1,11 @@
-# 🧠 Lemma v1.4.0
+# 🧠 Lemma v1.6.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-92-ff69b4?style=flat-square)](https://github.com/Nxusbets/lemma)
+[![MCP Tools](https://img.shields.io/badge/MCP%20tools-93-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-199%20passing-00c853?style=flat-square)](https://github.com/Nxusbets/lemma)
+[![Tests](https://img.shields.io/badge/tests-236%20passing-00c853?style=flat-square)](https://github.com/Nxusbets/lemma)
 
 ```text
     __                                
@@ -17,13 +17,80 @@
 
 > **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 **92 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 **93 MCP tools** — including zero-token static code intelligence that runs entirely on your machine with no LLM calls required.
 
 ---
 
 ## 📋 Changelog
 
-### v1.4.0 — Correctness-first patching, search, and memory freshness *(NEW)*
+### v1.6.0 — The savings ledger can now report a loss *(NEW)*
+
+Every release up to this one measured only what Lemma **saved**. That is single-entry bookkeeping:
+a number that can only go up is not evidence of anything, because the ledger had no way to express
+the outcome *"this session cost more than it returned."* Meanwhile Lemma's own overhead — the
+TURBOMODE prompt and 93 tool schemas injected into the model's system prompt, plus every tool
+result that lands in context — was real spend that appeared nowhere.
+
+| Change | What it does | Why it matters |
+| :--- | :--- | :--- |
+| **Cost side of the ledger** | Records `mcpInstructions` (prompt + all tool schemas, charged **once at MCP connect** — ~13,700 tokens on this repo), `toolResult` (charged on **every** call, including ones that also report a saving), and `cacheMiss`. | A session now starts visibly underwater and has to earn its way out, instead of starting at zero and only ever climbing. |
+| **Net position** | `getSnapshot()` returns `net.netTokens`, `net.netCost`, and `net.ratio` (saved ÷ spent). The terminal summary prints **`NET COST`** instead of `NET SAVED` when the ratio drops below 1.0. | The report is falsifiable. If Lemma isn't paying for itself, it says so. |
+| **`POST /api/cost-record`** *(new)* | Counterpart to `/api/savings-record`, so out-of-process callers (MCP server, CLI) can charge the ledger. Unknown sources are rejected with a 400. | Costs incurred outside the proxy were previously unrecordable. |
+| **Versioned ledger file** | `_version: 2`. Savings stay top-level so pre-v2 readers keep working; costs are additive under `_costs`. A v1 ledger loads with zeroed costs rather than failing. | No migration step, no data loss on upgrade. |
+
+**Three ways the old numbers were wrong**, now fixed:
+
+- **Cache hits were credited a hardcoded 2,000 tokens** — every semantic, synthesized, and cloud
+  hit reported the same invented figure regardless of what was actually served. Savings are now
+  measured from the cached payload that replaced the LLM call. The 2,000 placeholder survives only
+  in `stats.json` for dashboard continuity and is explicitly **barred from the ledger**: a guess
+  must not become part of a net-position claim.
+- **`pruneHistoryMessages` counted chars as tokens**, inflating history-prune savings ~4x. It now
+  converts with the same `chars / 4` heuristic used everywhere else.
+- **A cache *miss* is not charged.** The lookup is local, so a miss costs latency, not tokens.
+  Charging it an invented figure would repeat the exact error this release exists to correct.
+
+**Also fixed**: `reportSessionOverhead()` ran *after* `await trySamplingContext()`, which blocks on
+a `sampling/createMessage` round-trip that clients without sampling support never answer — so the
+overhead charge was stalled until the SDK timeout, or dropped entirely. It now runs first.
+
+**TURBOMODE prompt rewritten** at the top: it no longer promises to "multiply your LLM membership
+50x" or tell the model to poll `token_budget` every 5 turns (a scheduled call that produces a
+report instead of work, and costs tokens each time). It now states the real goal — reduce what
+enters context without costing a correct answer — and warns that a tool call which saves less than
+its own round-trip is a net loss.
+
+---
+
+### v1.5.0 — Command output stops being the biggest unoptimized token sink
+
+`run_workspace_command` returned raw stdout/stderr in full — a failing `npm test` put thousands of
+lines into context to communicate three broken assertions. Long output is now distilled by
+deterministic per-format parsers (no LLM summarization: a summarizer that invents a test name is
+worse than the dump it replaced).
+
+| Format | What survives distillation |
+| :--- | :--- |
+| jest / vitest | Failing test titles, assertion reason and diff, project-local source location. Code frames and `node_modules` stack frames dropped. |
+| tsc | Grouped by file; a repeated diagnostic printed once with its positions (`TS2322 ×40 … at 1:7, 2:7, …`) instead of forty identical lines. |
+| eslint (stylish) | Grouped by file with a rule-frequency header, capped per file. |
+| anything else | Head, tail, and the error/failure lines from the middle, each with its line number, plus an explicit count of what was withheld. |
+
+Measured on this repo: a 30-failure jest run went from 32,324 → 7,183 chars (78% withheld); a
+65-error `tsc --noEmit` from 5,597 → 527 (91%).
+
+**Lossless, not lossy.** The complete output is written to disk *before* anything is trimmed and
+the reply carries a handle; the footer always states how much was withheld. `output_region` *(new
+tool)* retrieves stored output verbatim — the whole run, one named section (a failing test title or
+file path), or a line range. Small outputs pass through untouched with no handle.
+
+**Also fixed**: stderr was discarded on success. `execSync` leaves stderr attached to the parent
+unless `stdio` is overridden, so a *passing* jest or tsc run — both report on stderr — returned an
+empty "Output:". Switched to `spawnSync`, which also raises the output limit to 20MB.
+
+---
+
+### v1.4.0 — Correctness-first patching, search, and memory freshness
 
 An audit of the everyday MCP path — read a file, search the workspace, patch it, remember the
 answer — found the same failure mode repeating: a tool that looked done but silently degraded
@@ -441,7 +508,7 @@ lemma start
 | `lemma start` | Launches proxy, cache engine, and dashboard at `http://localhost:8081`. |
 | `lemma stop` | Gracefully shuts down the background proxy. |
 | `lemma status` | Health of all modules and active connections. |
-| `lemma stats` | Real-time token and cost savings metrics. |
+| `lemma stats` | Real-time token and cost metrics — savings, Lemma's own overhead, and the net position between them. Reports `NET COST` when the session is underwater. |
 | `lemma mcp` | Starts the stdin/stdout MCP server for IDE integration. |
 | `lemma heal` | Auto-diagnose and repair the latest server crash from live context logs. |
 | `lemma autopilot` | Toggle autonomous background watcher mode (auto-applies fixes). |

package/dist/cjs/cli/lemma-proxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lemma-proxy.d.ts","sourceRoot":"","sources":["../../../src/cli/lemma-proxy.ts"],"names":[],"mappings":";AA4cA,wBAAgB,+BAA+B,CAAC,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CA4DvF;AAijED,wBAAsB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA6KhL"}
+{"version":3,"file":"lemma-proxy.d.ts","sourceRoot":"","sources":["../../../src/cli/lemma-proxy.ts"],"names":[],"mappings":";AA4cA,wBAAgB,+BAA+B,CAAC,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CA4DvF;AA8lED,wBAAsB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA6KhL"}

package/dist/cjs/cli/lemma-proxy.js

@@ -587,6 +587,31 @@ async function loadUsage() {
 async function loadStats() {
     return readJson(ProjectStore_1.STATS_FILE, {});
 }
+/**
+ * Tokens a cache hit actually avoided regenerating, measured from the cached payload
+ * that was served instead of an LLM call. Replaces the old hardcoded 2000 guess.
+ */
+function measureCachedTokens(data) {
+    try {
+        const chars = JSON.stringify(data)?.length;
+        if (!chars)
+            return undefined;
+        return Math.floor(chars / 4);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * @param tokensSaved  Measured tokens saved. When omitted for a cache hit, stats.json
+ *   still falls back to a 2000-token placeholder for dashboard continuity, but that
+ *   guess is deliberately NOT written to the savings ledger — the ledger only accepts
+ *   measured values, otherwise its net position is built on invented numbers.
+ *
+ * Note: a cache *miss* is not charged to the cost ledger. The lookup is local (no LLM
+ * round-trip), so a miss costs latency, not tokens. Charging it a fabricated token
+ * figure would repeat exactly the error the cost ledger exists to correct.
+ */
 async function recordStat(stats, project, fromCache, latencyMs, provider, tokensSaved) {
     if (!stats[project]) {
         stats[project] = { total: 0, hits: 0, misses: 0, totalLatency: 0, totalTokensSaved: 0, providers: {} };
@@ -600,9 +625,11 @@ async function recordStat(stats, project, fromCache, latencyMs, provider, tokens
     if (!s.providers[provider])
         s.providers[provider] = { hits: 0, misses: 0 };
     fromCache ? s.providers[provider].hits++ : s.providers[provider].misses++;
-    if (fromCache && tkSaved > 0) {
-        // Automatically report cache hits directly to the server session ledger for absolute sync consistency
-        SavingsLedger_1.savingsLedger.recordTokens('cache', tkSaved);
+    // Only measured savings reach the ledger. `tokensSaved === undefined` means the
+    // caller never counted, so tkSaved is the 2000 placeholder — usable for the
+    // dashboard, not for a net-position claim.
+    if (fromCache && typeof tokensSaved === 'number' && tokensSaved > 0) {
+        SavingsLedger_1.savingsLedger.recordTokens('cache', tokensSaved);
     }
     logEvent({
         type: fromCache ? 'cache:hit' : 'cache:miss',
@@ -1508,6 +1535,23 @@ class LemmaServer {
                 }
                 res.json({ ok: true, snapshot: SavingsLedger_1.savingsLedger.getSnapshot().total });
             });
+            // Cost Record Endpoint — the counterpart to /api/savings-record. Without it the
+            // ledger only ever counts wins, which makes its totals unfalsifiable.
+            this.app.post('/api/cost-record', (req, res) => {
+                const { source, tokens, chars } = req.body || {};
+                const validSources = ['mcpInstructions', 'toolResult', 'cacheMiss'];
+                if (!source || !validSources.includes(source)) {
+                    return res.status(400).json({ error: 'Invalid cost source' });
+                }
+                if (typeof tokens === 'number' && tokens > 0) {
+                    SavingsLedger_1.savingsLedger.recordCost(source, tokens);
+                }
+                else if (typeof chars === 'number' && chars > 0) {
+                    SavingsLedger_1.savingsLedger.recordCostChars(source, chars);
+                }
+                const snap = SavingsLedger_1.savingsLedger.getSnapshot();
+                res.json({ ok: true, totalCost: snap.totalCost, net: snap.net });
+            });
             // MCP Tool Event Endpoint — called by MCP server when tools execute
             this.app.post('/api/mcp-event', (req, res) => {
                 try {
@@ -1733,7 +1777,7 @@ class LemmaServer {
             const semHit = await semanticGet(provider, prompt, this.projectName);
             if (semHit) {
                 if (semHit.similarity >= 0.90) {
-                    await recordStat(this.stats, this.projectName, true, Date.now() - t0, provider, 2000);
+                    await recordStat(this.stats, this.projectName, true, Date.now() - t0, provider, measureCachedTokens(semHit.data));
                     const unmaskedData = semanticScrubber.unmask(semHit.data, tokenMap);
                     const cacheHeader = semHit.hiveMind ? 'HIT-HIVE-MIND' : 'HIT';
                     if (isStream)
@@ -1784,7 +1828,7 @@ Adjusted Answer:`;
                                 else if (provider === 'anthropic') {
                                     synthesizedData.content[0].text = adjustedText;
                                 }
-                                await recordStat(this.stats, this.projectName, true, Date.now() - t0, provider, 2000);
+                                await recordStat(this.stats, this.projectName, true, Date.now() - t0, provider, measureCachedTokens(synthesizedData));
                                 const unmaskedData = semanticScrubber.unmask(synthesizedData, tokenMap);
                                 if (isStream) {
                                     return SseRelay_1.SseRelay.simulateHit(res, unmaskedData, { provider: provider, tier, similarity: semHit.similarity });
@@ -1804,7 +1848,7 @@ Adjusted Answer:`;
             const cloudHit = await cloudSync.get(prompt);
             if (cloudHit) {
                 cacheSet(provider, prompt, cloudHit.data);
-                await recordStat(this.stats, this.projectName, true, Date.now() - t0, provider, 2000);
+                await recordStat(this.stats, this.projectName, true, Date.now() - t0, provider, measureCachedTokens(cloudHit.data));
                 const unmaskedData = semanticScrubber.unmask(cloudHit.data, tokenMap);
                 if (isStream)
                     return SseRelay_1.SseRelay.simulateHit(res, unmaskedData, { provider: provider, tier, similarity: cloudHit.similarity || 0.95 });