@nxuss/lemma 0.5.1 → 0.5.3

package/dist/esm/utils/SavingsLedger.d.ts

@@ -0,0 +1,52 @@
+/**
+ * SavingsLedger — Singleton accumulator for token savings across all Lemma modules.
+ *
+ * Every module (ClipboardWatcher, ContextSqueezer, ComplexityRouter, SemanticCache)
+ * calls `ledger.record(source, charsBefore, charsAfter)` — no one knows about the dashboard.
+ *
+ * The proxy exposes the ledger via GET /api/savings-breakdown for the dashboard to consume.
+ */
+export type SavingsSource = 'clipboard' | 'contextSqueeze' | 'historyPrune' | 'complexityRouting' | 'cache';
+export interface SourceStats {
+    /** How many individual savings events were recorded */
+    events: number;
+    /** Estimated tokens saved (chars / 4) */
+    tokensSaved: number;
+    /** Estimated USD saved (tokensSaved * avg price per token) */
+    costSaved: number;
+}
+export interface SavingsSnapshot {
+    clipboard: SourceStats;
+    contextSqueeze: SourceStats;
+    historyPrune: SourceStats;
+    complexityRouting: SourceStats;
+    cache: SourceStats;
+    total: SourceStats;
+    sessionStartedAt: string;
+}
+declare class SavingsLedger {
+    private sources;
+    private readonly sessionStartedAt;
+    constructor();
+    /**
+     * Record a savings event by char counts (automatically converts to token estimate).
+     * @param source  Which module recorded the savings
+     * @param charsBefore  Original char count before compression/routing
+     * @param charsAfter   Resulting char count after compression/routing
+     */
+    record(source: SavingsSource, charsBefore: number, charsAfter: number): void;
+    /**
+     * Record a savings event directly in tokens (for sources that already know their token count).
+     */
+    recordTokens(source: SavingsSource, tokensSaved: number): void;
+    /** Returns a full snapshot including computed totals */
+    getSnapshot(): SavingsSnapshot;
+    /** Returns a pretty terminal summary block */
+    getTerminalSummary(): string;
+    /** Reset all counters (e.g., on cache clear) */
+    reset(): void;
+}
+/** Global singleton — import this everywhere */
+export declare const savingsLedger: SavingsLedger;
+export default savingsLedger;
+//# sourceMappingURL=SavingsLedger.d.ts.map

package/dist/esm/utils/SavingsLedger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SavingsLedger.d.ts","sourceRoot":"","sources":["../../../src/utils/SavingsLedger.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,gBAAgB,GAAG,cAAc,GAAG,mBAAmB,GAAG,OAAO,CAAC;AAE5G,MAAM,WAAW,WAAW;IAC1B,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,WAAW,CAAC;IACvB,cAAc,EAAE,WAAW,CAAC;IAC5B,YAAY,EAAE,WAAW,CAAC;IAC1B,iBAAiB,EAAE,WAAW,CAAC;IAC/B,KAAK,EAAE,WAAW,CAAC;IACnB,KAAK,EAAE,WAAW,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAKD,cAAM,aAAa;IACjB,OAAO,CAAC,OAAO,CAAqC;IACpD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;;IAa1C;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAY5E;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAQ9D,wDAAwD;IACxD,WAAW,IAAI,eAAe;IAgB9B,8CAA8C;IAC9C,kBAAkB,IAAI,MAAM;IA+B5B,gDAAgD;IAChD,KAAK,IAAI,IAAI;CAKd;AAED,gDAAgD;AAChD,eAAO,MAAM,aAAa,eAAsB,CAAC;AACjD,eAAe,aAAa,CAAC"}

package/dist/esm/utils/SavingsLedger.js

@@ -0,0 +1,98 @@
+/**
+ * SavingsLedger — Singleton accumulator for token savings across all Lemma modules.
+ *
+ * Every module (ClipboardWatcher, ContextSqueezer, ComplexityRouter, SemanticCache)
+ * calls `ledger.record(source, charsBefore, charsAfter)` — no one knows about the dashboard.
+ *
+ * The proxy exposes the ledger via GET /api/savings-breakdown for the dashboard to consume.
+ */
+/** Average blended cost per input token across GPT-4o / Claude Sonnet / Gemini Pro */
+const AVG_COST_PER_TOKEN = 0.000008; // $0.008 per 1K tokens
+class SavingsLedger {
+    constructor() {
+        this.sessionStartedAt = new Date().toISOString();
+        this.sources = {
+            clipboard: { events: 0, tokensSaved: 0, costSaved: 0 },
+            contextSqueeze: { events: 0, tokensSaved: 0, costSaved: 0 },
+            historyPrune: { events: 0, tokensSaved: 0, costSaved: 0 },
+            complexityRouting: { events: 0, tokensSaved: 0, costSaved: 0 },
+            cache: { events: 0, tokensSaved: 0, costSaved: 0 },
+        };
+    }
+    /**
+     * Record a savings event by char counts (automatically converts to token estimate).
+     * @param source  Which module recorded the savings
+     * @param charsBefore  Original char count before compression/routing
+     * @param charsAfter   Resulting char count after compression/routing
+     */
+    record(source, charsBefore, charsAfter) {
+        const charsSaved = Math.max(0, charsBefore - charsAfter);
+        if (charsSaved === 0)
+            return;
+        const tokensSaved = Math.floor(charsSaved / 4);
+        const costSaved = tokensSaved * AVG_COST_PER_TOKEN;
+        this.sources[source].events++;
+        this.sources[source].tokensSaved += tokensSaved;
+        this.sources[source].costSaved += costSaved;
+    }
+    /**
+     * Record a savings event directly in tokens (for sources that already know their token count).
+     */
+    recordTokens(source, tokensSaved) {
+        if (tokensSaved <= 0)
+            return;
+        const costSaved = tokensSaved * AVG_COST_PER_TOKEN;
+        this.sources[source].events++;
+        this.sources[source].tokensSaved += tokensSaved;
+        this.sources[source].costSaved += costSaved;
+    }
+    /** Returns a full snapshot including computed totals */
+    getSnapshot() {
+        const total = { events: 0, tokensSaved: 0, costSaved: 0 };
+        for (const src of Object.values(this.sources)) {
+            total.events += src.events;
+            total.tokensSaved += src.tokensSaved;
+            total.costSaved += src.costSaved;
+        }
+        return {
+            ...this.sources,
+            total,
+            sessionStartedAt: this.sessionStartedAt,
+        };
+    }
+    /** Returns a pretty terminal summary block */
+    getTerminalSummary() {
+        const snap = this.getSnapshot();
+        const fmt = (n) => n.toLocaleString('en-US');
+        const fmtUSD = (n) => new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD', minimumFractionDigits: 4 }).format(n);
+        const rows = [
+            ['📋 Clipboard Squeeze', snap.clipboard.tokensSaved, snap.clipboard.costSaved],
+            ['🗜️  Context Squeeze  ', snap.contextSqueeze.tokensSaved, snap.contextSqueeze.costSaved],
+            ['📜 History Prune    ', snap.historyPrune.tokensSaved, snap.historyPrune.costSaved],
+            ['🔀 Model Routing    ', snap.complexityRouting.tokensSaved, snap.complexityRouting.costSaved],
+            ['⚡ Semantic Cache   ', snap.cache.tokensSaved, snap.cache.costSaved],
+        ];
+        const lines = [
+            '┌──────────────────────────────────────────────────────┐',
+            '│          💰 Lemma Savings Report (this session)      │',
+            '├──────────────────────────────────────────────────────┤',
+            ...rows
+                .filter(([, tokens]) => tokens > 0)
+                .map(([label, tokens, cost]) => `│  ${label}   ${fmt(tokens).padStart(7)} tokens   ${fmtUSD(cost).padStart(10)}  │`),
+            '│  ──────────────────────────────────────────────────  │',
+            `│  TOTAL                       ${fmt(snap.total.tokensSaved).padStart(7)} tokens   ${fmtUSD(snap.total.costSaved).padStart(10)}  │`,
+            '└──────────────────────────────────────────────────────┘',
+        ];
+        return lines.join('\n');
+    }
+    /** Reset all counters (e.g., on cache clear) */
+    reset() {
+        for (const key of Object.keys(this.sources)) {
+            this.sources[key] = { events: 0, tokensSaved: 0, costSaved: 0 };
+        }
+    }
+}
+/** Global singleton — import this everywhere */
+export const savingsLedger = new SavingsLedger();
+export default savingsLedger;
+//# sourceMappingURL=SavingsLedger.js.map

package/dist/esm/utils/SavingsLedger.js.map

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

package/dist/esm/utils/logger.d.ts

@@ -8,24 +8,45 @@ export declare enum LogLevel {
     DEBUG = 3
 }
 /**
- * Simple structured logger with color support
+ * Structured Logger Entry Schema
+ */
+export interface LogEntry {
+    timestamp: string;
+    level: string;
+    context: string;
+    message: string;
+    meta?: any;
+    error?: {
+        message: string;
+        stack?: string;
+    };
+}
+/**
+ * Enterprise Structured Logger supporting standard console and file output streams.
  */
 declare class Logger {
     private level;
     private context;
+    private format;
+    private logFilePath;
+    private disableConsole;
     constructor(context?: string);
     /**
      * Parse log level from string
      */
     private parseLogLevel;
     /**
-     * Format timestamp
+     * Format text log line with color
      */
-    private getTimestamp;
+    private formatText;
     /**
-     * Format log message
+     * Safe file appending utility
      */
-    private format;
+    private appendToFile;
+    /**
+     * Unified writer for standard and file streams
+     */
+    private log;
     /**
      * Log error message
      */
@@ -47,7 +68,7 @@ declare class Logger {
      */
     metric(name: string, value: number, unit?: string): void;
     /**
-     * Create child logger with different context
+     * Create child logger with parent context chaining
      */
     child(context: string): Logger;
 }

package/dist/esm/utils/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../src/utils/logger.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,oBAAY,QAAQ;IAClB,KAAK,IAAI;IACT,IAAI,IAAI;IACR,IAAI,IAAI;IACR,KAAK,IAAI;CACV;AAcD;;GAEG;AACH,cAAM,MAAM;IACV,OAAO,CAAC,KAAK,CAAW;IACxB,OAAO,CAAC,OAAO,CAAS;gBAEZ,OAAO,GAAE,MAAc;IAKnC;;OAEG;IACH,OAAO,CAAC,aAAa;IAerB;;OAEG;IACH,OAAO,CAAC,YAAY;IAIpB;;OAEG;IACH,OAAO,CAAC,MAAM;IAMd;;OAEG;IACI,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,GAAG,GAAG,GAAG,IAAI;IAYxD;;OAEG;IACI,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI;IAO9C;;OAEG;IACI,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI;IAO9C;;OAEG;IACI,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI;IAO/C;;OAEG;IACI,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,MAAa,GAAG,IAAI;IAOrE;;OAEG;IACI,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;CAGtC;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,MAAc,GAAG,MAAM,CAE5D;AAED;;GAEG;AACH,eAAO,MAAM,MAAM,QAAqC,CAAC"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../src/utils/logger.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,oBAAY,QAAQ;IAClB,KAAK,IAAI;IACT,IAAI,IAAI;IACR,IAAI,IAAI;IACR,KAAK,IAAI;CACV;AAcD;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,GAAG,CAAC;IACX,KAAK,CAAC,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAED;;GAEG;AACH,cAAM,MAAM;IACV,OAAO,CAAC,KAAK,CAAW;IACxB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,cAAc,CAAkB;gBAE5B,OAAO,GAAE,MAAc;IAsBnC;;OAEG;IACH,OAAO,CAAC,aAAa;IAerB;;OAEG;IACH,OAAO,CAAC,UAAU;IAKlB;;OAEG;IACH,OAAO,CAAC,YAAY;IAWpB;;OAEG;IACH,OAAO,CAAC,GAAG;IAkDX;;OAEG;IACI,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,GAAG,GAAG,GAAG,IAAI;IAIxD;;OAEG;IACI,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI;IAI9C;;OAEG;IACI,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI;IAI9C;;OAEG;IACI,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI;IAI/C;;OAEG;IACI,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,MAAa,GAAG,IAAI;IAKrE;;OAEG;IACI,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;CAGtC;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,MAAc,GAAG,MAAM,CAE5D;AAED;;GAEG;AACH,eAAO,MAAM,MAAM,QAAqC,CAAC"}

package/dist/esm/utils/logger.js

@@ -1,3 +1,5 @@
+import fs from 'fs';
+import path from 'path';
 import { config } from '../config';
 /**
  * Log levels
@@ -21,12 +23,29 @@ const colors = {
     gray: '\x1b[90m',
 };
 /**
- * Simple structured logger with color support
+ * Enterprise Structured Logger supporting standard console and file output streams.
  */
 class Logger {
     constructor(context = 'App') {
+        this.logFilePath = null;
+        this.disableConsole = false;
         this.context = context;
-        this.level = this.parseLogLevel(config.logLevel || 'info');
+        // Resolve runtime settings dynamically
+        const rawLevel = process.env.LEMMA_LOG_LEVEL || process.env.LOG_LEVEL || config?.logLevel || 'info';
+        this.level = this.parseLogLevel(rawLevel);
+        this.format = (process.env.LEMMA_LOG_FORMAT || process.env.LOG_FORMAT || 'text').toLowerCase() === 'json' ? 'json' : 'text';
+        this.logFilePath = process.env.LEMMA_LOG_FILE || process.env.LOG_FILE || null;
+        this.disableConsole = (process.env.LEMMA_LOG_DISABLE_CONSOLE || 'false').toLowerCase() === 'true';
+        // Proactively construct base directory for log files if specified
+        if (this.logFilePath) {
+            try {
+                const dir = path.dirname(path.resolve(this.logFilePath));
+                if (!fs.existsSync(dir)) {
+                    fs.mkdirSync(dir, { recursive: true });
+                }
+            }
+            catch { }
+        }
     }
     /**
      * Parse log level from string
@@ -46,64 +65,110 @@ class Logger {
         }
     }
     /**
-     * Format timestamp
+     * Format text log line with color
      */
-    getTimestamp() {
-        return new Date().toISOString();
+    formatText(level, message, metaStr, colorCode) {
+        const timestamp = new Date().toISOString();
+        return `${colorCode}[${timestamp}] [${level}] [${this.context}] ${message}${metaStr}${colors.reset}`;
     }
     /**
-     * Format log message
+     * Safe file appending utility
      */
-    format(level, message, meta) {
-        const timestamp = this.getTimestamp();
-        const metaStr = meta ? ` ${JSON.stringify(meta)}` : '';
-        return `[${timestamp}] [${level}] [${this.context}] ${message}${metaStr}`;
+    appendToFile(entry) {
+        if (!this.logFilePath)
+            return;
+        try {
+            const line = this.format === 'json'
+                ? JSON.stringify(entry)
+                : `[${entry.timestamp}] [${entry.level}] [${entry.context}] ${entry.message}${entry.meta ? ' ' + JSON.stringify(entry.meta) : ''}${entry.error ? ' error: ' + entry.error.message + '\n' + (entry.error.stack || '') : ''}`;
+            fs.appendFileSync(this.logFilePath, line + '\n', 'utf8');
+        }
+        catch { }
+    }
+    /**
+     * Unified writer for standard and file streams
+     */
+    log(levelStr, levelVal, message, colorCode, meta, errObj) {
+        if (levelVal > this.level)
+            return;
+        const timestamp = new Date().toISOString();
+        const entry = {
+            timestamp,
+            level: levelStr,
+            context: this.context,
+            message,
+        };
+        if (meta !== undefined) {
+            entry.meta = meta;
+        }
+        if (errObj) {
+            entry.error = {
+                message: errObj instanceof Error ? errObj.message : String(errObj),
+                stack: errObj instanceof Error ? errObj.stack : undefined,
+            };
+        }
+        // Output to Console
+        if (!this.disableConsole) {
+            if (this.format === 'json') {
+                const jsonLine = JSON.stringify(entry);
+                if (levelVal === LogLevel.ERROR) {
+                    console.error(jsonLine);
+                }
+                else {
+                    console.log(jsonLine);
+                }
+            }
+            else {
+                const metaStr = meta ? ` ${JSON.stringify(meta)}` : '';
+                const colorLine = this.formatText(levelStr, message, metaStr, colorCode);
+                if (levelVal === LogLevel.ERROR) {
+                    console.error(colorLine);
+                    if (errObj && errObj.stack) {
+                        console.error(`${colors.red}${errObj.stack}${colors.reset}`);
+                    }
+                }
+                else {
+                    console.log(colorLine);
+                }
+            }
+        }
+        // Write to File Sink
+        this.appendToFile(entry);
     }
     /**
      * Log error message
      */
     error(message, error) {
-        if (this.level < LogLevel.ERROR)
-            return;
-        const meta = error instanceof Error
-            ? { error: error.message, stack: error.stack }
-            : error;
-        console.error(`${colors.red}${this.format('ERROR', message, meta)}${colors.reset}`);
+        this.log('ERROR', LogLevel.ERROR, message, colors.red, undefined, error);
     }
     /**
      * Log warning message
      */
     warn(message, meta) {
-        if (this.level < LogLevel.WARN)
-            return;
-        console.warn(`${colors.yellow}${this.format('WARN', message, meta)}${colors.reset}`);
+        this.log('WARN', LogLevel.WARN, message, colors.yellow, meta);
     }
     /**
      * Log info message
      */
     info(message, meta) {
-        if (this.level < LogLevel.INFO)
-            return;
-        console.log(`${colors.blue}${this.format('INFO', message, meta)}${colors.reset}`);
+        this.log('INFO', LogLevel.INFO, message, colors.blue, meta);
     }
     /**
      * Log debug message
      */
     debug(message, meta) {
-        if (this.level < LogLevel.DEBUG)
-            return;
-        console.log(`${colors.gray}${this.format('DEBUG', message, meta)}${colors.reset}`);
+        this.log('DEBUG', LogLevel.DEBUG, message, colors.gray, meta);
     }
     /**
      * Log performance metric
      */
     metric(name, value, unit = 'ms') {
-        if (this.level < LogLevel.INFO)
+        if (LogLevel.INFO > this.level)
             return;
-        console.log(`${colors.cyan}${this.format('METRIC', `${name}: ${value}${unit}`)}${colors.reset}`);
+        this.log('METRIC', LogLevel.INFO, `${name}: ${value}${unit}`, colors.cyan);
     }
     /**
-     * Create child logger with different context
+     * Create child logger with parent context chaining
      */
     child(context) {
         return new Logger(`${this.context}:${context}`);

package/dist/esm/utils/logger.js.map

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

package/dist/esm/utils/reportSavings.d.ts

@@ -0,0 +1,24 @@
+/**
+ * reportSavings — Fire-and-forget helper to report token savings to the proxy's SavingsLedger.
+ *
+ * Used by processes that run separately from the proxy (e.g., MCP server, CLI tools).
+ * The proxy accumulates all savings in its in-memory SavingsLedger and serves them to the dashboard.
+ */
+type SavingsSource = 'clipboard' | 'contextSqueeze' | 'historyPrune' | 'complexityRouting' | 'cache';
+interface ReportByChars {
+    source: SavingsSource;
+    charsBefore: number;
+    charsAfter: number;
+}
+interface ReportByTokens {
+    source: SavingsSource;
+    tokens: number;
+}
+type ReportPayload = ReportByChars | ReportByTokens;
+/**
+ * Report savings to the proxy's SavingsLedger via HTTP POST.
+ * Fire-and-forget — never throws, never blocks.
+ */
+export declare function reportSavings(payload: ReportPayload): void;
+export {};
+//# sourceMappingURL=reportSavings.d.ts.map

package/dist/esm/utils/reportSavings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reportSavings.d.ts","sourceRoot":"","sources":["../../../src/utils/reportSavings.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,KAAK,aAAa,GAAG,WAAW,GAAG,gBAAgB,GAAG,cAAc,GAAG,mBAAmB,GAAG,OAAO,CAAC;AAErG,UAAU,aAAa;IACrB,MAAM,EAAE,aAAa,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,UAAU,cAAc;IACtB,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,KAAK,aAAa,GAAG,aAAa,GAAG,cAAc,CAAC;AAapD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAsB1D"}

package/dist/esm/utils/reportSavings.js

@@ -0,0 +1,47 @@
+/**
+ * reportSavings — Fire-and-forget helper to report token savings to the proxy's SavingsLedger.
+ *
+ * Used by processes that run separately from the proxy (e.g., MCP server, CLI tools).
+ * The proxy accumulates all savings in its in-memory SavingsLedger and serves them to the dashboard.
+ */
+import fs from 'fs';
+import path from 'path';
+import http from 'http';
+function getProxyPort() {
+    try {
+        const HOME = process.env.HOME || process.env.USERPROFILE || '~';
+        const portFile = path.join(HOME, '.lemma-cache/proxy.port');
+        if (fs.existsSync(portFile)) {
+            return fs.readFileSync(portFile, 'utf8').trim();
+        }
+    }
+    catch { }
+    return '8081';
+}
+/**
+ * Report savings to the proxy's SavingsLedger via HTTP POST.
+ * Fire-and-forget — never throws, never blocks.
+ */
+export function reportSavings(payload) {
+    try {
+        const port = getProxyPort();
+        const body = JSON.stringify(payload);
+        const req = http.request({
+            hostname: '127.0.0.1',
+            port: parseInt(port),
+            path: '/api/savings-record',
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Content-Length': Buffer.byteLength(body),
+            },
+        });
+        req.on('error', () => { }); // Silently ignore if proxy isn't running
+        req.write(body);
+        req.end();
+    }
+    catch {
+        // Never throw — savings reporting is non-critical
+    }
+}
+//# sourceMappingURL=reportSavings.js.map

package/dist/esm/utils/reportSavings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reportSavings.js","sourceRoot":"","sources":["../../../src/utils/reportSavings.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,IAAI,MAAM,MAAM,CAAC;AAiBxB,SAAS,YAAY;IACnB,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,GAAG,CAAC;QAChE,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,yBAAyB,CAAC,CAAC;QAC5D,IAAI,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC5B,OAAO,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;QAClD,CAAC;IACH,CAAC;IAAC,MAAM,CAAC,CAAA,CAAC;IACV,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,OAAsB;IAClD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,YAAY,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAErC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC;YACvB,QAAQ,EAAE,WAAW;YACrB,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC;YACpB,IAAI,EAAE,qBAAqB;YAC3B,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,gBAAgB,EAAE,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC;aAC1C;SACF,CAAC,CAAC;QAEH,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC,CAAC,yCAAyC;QACpE,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAChB,GAAG,CAAC,GAAG,EAAE,CAAC;IACZ,CAAC;IAAC,MAAM,CAAC;QACP,kDAAkD;IACpD,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nxuss/lemma",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Intelligent AI Gateway for IDEs & Agents — Semantic cache, Privacy Firewall, and Autonomous Cost-Optimization.",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
@@ -102,37 +102,40 @@
     "dev": "npx tsx start-dev.ts",
     "start": "node dist/cjs/index.js",
     "test": "jest",
+    "type-check": "tsc --noEmit",
+    "format": "prettier --check 'src/**/*.ts' 'tests/**/*.ts' 'examples/**/*.ts' 'scripts/**/*.ts'",
+    "format:fix": "prettier --write 'src/**/*.ts' 'tests/**/*.ts' 'examples/**/*.ts' 'scripts/**/*.ts'",
     "lint": "eslint src/**/*.ts",
     "clean": "rm -rf dist sdks/langchain/dist sdks/crewai/dist",
     "prepublishOnly": "npm run clean && npm run build && npm test",
     "cloud:start": "node dist/cjs/cloud/server.js",
-    "cloud:dev": "ts-node src/cloud/server.ts",
-    "demo": "ts-node examples/demo-visual.ts",
-    "demo:comparison": "ts-node examples/demo-comparison.ts",
-    "example:simple": "ts-node examples/simple-agent.ts",
-    "example:swarm": "ts-node examples/agent-swarm.ts",
-    "example:secure": "ts-node examples/secure-agent.ts",
-    "example:langchain": "ts-node examples/langchain-example.ts",
-    "example:crewai": "ts-node examples/crewai-example.ts",
-    "example:speculative": "ts-node examples/phase3-speculative.ts",
-    "example:consensus": "ts-node examples/phase3-consensus.ts",
-    "example:semantic": "ts-node examples/semantic-cache-demo.ts",
-    "test:quick": "ts-node examples/quick-test.ts",
-    "test:real:ollama:1min": "ts-node examples/real-world-ollama-1min.ts",
-    "test:real:ollama": "ts-node examples/real-world-ollama.ts",
-    "test:real:1min": "ts-node examples/real-world-1min.ts",
-    "test:real:openai": "ts-node examples/real-world-openai.ts",
-    "test:real:anthropic": "ts-node examples/real-world-anthropic.ts",
-    "test:real:multi-agent": "ts-node examples/real-world-multi-agent.ts",
+    "cloud:dev": "npx tsx src/cloud/server.ts",
+    "demo": "npx tsx examples/demo-visual.ts",
+    "demo:comparison": "npx tsx examples/demo-comparison.ts",
+    "example:simple": "npx tsx examples/simple-agent.ts",
+    "example:swarm": "npx tsx examples/agent-swarm.ts",
+    "example:secure": "npx tsx examples/secure-agent.ts",
+    "example:langchain": "npx tsx examples/langchain-example.ts",
+    "example:crewai": "npx tsx examples/crewai-example.ts",
+    "example:speculative": "npx tsx examples/phase3-speculative.ts",
+    "example:consensus": "npx tsx examples/phase3-consensus.ts",
+    "example:semantic": "npx tsx examples/semantic-cache-demo.ts",
+    "test:quick": "npx tsx examples/quick-test.ts",
+    "test:real:ollama:1min": "npx tsx examples/real-world-ollama-1min.ts",
+    "test:real:ollama": "npx tsx examples/real-world-ollama.ts",
+    "test:real:1min": "npx tsx examples/real-world-1min.ts",
+    "test:real:openai": "npx tsx examples/real-world-openai.ts",
+    "test:real:anthropic": "npx tsx examples/real-world-anthropic.ts",
+    "test:real:multi-agent": "npx tsx examples/real-world-multi-agent.ts",
     "dashboard": "cd dashboard && npm run dev",
     "dashboard:build": "cd dashboard && npm run build",
     "stack:all": "bash scripts/launch-all.sh",
     "sdk:langchain:build": "cd sdks/langchain && npm run build",
     "sdk:crewai:build": "cd sdks/crewai && npm run build",
     "sdk:build": "npm run sdk:langchain:build && npm run sdk:crewai:build",
-    "keys:generate": "ts-node scripts/manage-keys.ts generate",
-    "keys:list": "ts-node scripts/manage-keys.ts list",
-    "keys:revoke": "ts-node scripts/manage-keys.ts revoke"
+    "keys:generate": "npx tsx scripts/manage-keys.ts generate",
+    "keys:list": "npx tsx scripts/manage-keys.ts list",
+    "keys:revoke": "npx tsx scripts/manage-keys.ts revoke"
   },
   "keywords": [
     "semantic-cache",
@@ -162,8 +165,6 @@
   "dependencies": {
     "@chroma-core/default-embed": "^0.1.9",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@nxuss/lemma": "^0.5.1",
-    "@types/cors": "^2.8.19",
     "axios": "^1.6.0",
     "commander": "^14.0.3",
     "cors": "^2.8.6",
@@ -180,6 +181,7 @@
     "ws": "^8.16.0"
   },
   "devDependencies": {
+    "@types/cors": "^2.8.19",
     "@types/express": "^4.17.21",
     "@types/jest": "^29.5.11",
     "@types/node": "^20.11.0",
@@ -187,6 +189,7 @@
     "@types/uuid": "^10.0.0",
     "@types/ws": "^8.5.10",
     "jest": "^29.7.0",
+    "prettier": "^3.0.0",
     "ts-jest": "^29.1.1",
     "ts-node": "^10.9.2",
     "typescript": "^5.3.3"