@ekkos/cli 1.3.1 → 1.3.2

package/dist/local/local-embeddings.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Local Embeddings using ONNX Runtime
+ *
+ * Uses bge-small-en-v1.5 (384 dimensions) for offline similarity search.
+ * Same model OMEGA uses — lightweight, good quality.
+ *
+ * Note: Local embeddings are 384-dim (bge-small-en-v1.5)
+ *       Cloud embeddings are 1536-dim (OpenAI text-embedding-3-small)
+ *       On sync: re-embed with cloud model for consistency
+ *
+ * Optional dependency: @xenova/transformers
+ * If not installed, falls back to TF-IDF keyword similarity.
+ */
+export interface SimilarityResult {
+    id: string;
+    score: number;
+}
+/**
+ * Generate a 384-dimensional embedding vector using bge-small-en-v1.5.
+ * Falls back to an empty array if @xenova/transformers is not installed.
+ * Callers should check array length before using for similarity.
+ */
+export declare function generateLocalEmbedding(text: string): Promise<number[]>;
+/**
+ * Cosine similarity between two dense numeric vectors.
+ * Returns a value in [-1, 1] (1 = identical direction).
+ */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+/**
+ * Rank candidates by semantic similarity to the query.
+ *
+ * Tries ONNX embedding first; falls back to TF-IDF keyword similarity if
+ * @xenova/transformers is not installed or if embedding fails.
+ *
+ * @param query      - Search query string
+ * @param candidates - Items to rank (each has an `id` and `text` for embedding)
+ * @param topK       - How many results to return (default 5)
+ *
+ * @returns Ranked array of { id, score } sorted by descending similarity
+ */
+export declare function searchByEmbedding(query: string, candidates: {
+    id: string;
+    text: string;
+}[], topK?: number): Promise<SimilarityResult[]>;
+/**
+ * Check whether the ONNX embedding pipeline is available.
+ * Returns false if @xenova/transformers is not installed.
+ */
+export declare function isEmbeddingAvailable(): Promise<boolean>;

package/dist/local/local-embeddings.js

@@ -0,0 +1,232 @@
+"use strict";
+/**
+ * Local Embeddings using ONNX Runtime
+ *
+ * Uses bge-small-en-v1.5 (384 dimensions) for offline similarity search.
+ * Same model OMEGA uses — lightweight, good quality.
+ *
+ * Note: Local embeddings are 384-dim (bge-small-en-v1.5)
+ *       Cloud embeddings are 1536-dim (OpenAI text-embedding-3-small)
+ *       On sync: re-embed with cloud model for consistency
+ *
+ * Optional dependency: @xenova/transformers
+ * If not installed, falls back to TF-IDF keyword similarity.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateLocalEmbedding = generateLocalEmbedding;
+exports.cosineSimilarity = cosineSimilarity;
+exports.searchByEmbedding = searchByEmbedding;
+exports.isEmbeddingAvailable = isEmbeddingAvailable;
+let _pipeline = null;
+let _pipelineLoading = null;
+let _transformersAvailable = null; // null = not yet checked
+async function getTransformerPipeline() {
+    if (_transformersAvailable === false)
+        return null;
+    if (_pipeline)
+        return _pipeline;
+    if (_pipelineLoading)
+        return _pipelineLoading;
+    _pipelineLoading = (async () => {
+        try {
+            // Dynamic import — fails gracefully if package not installed
+            const mod = await Promise.resolve(`${'@xenova/transformers'}`).then(s => __importStar(require(s)));
+            const { pipeline } = mod;
+            // Load the bge-small-en-v1.5 model (384 dims, ~33MB)
+            const featureExtractor = await pipeline('feature-extraction', 'Xenova/bge-small-en-v1.5', {
+                quantized: true, // use int8 quantised version for speed
+            });
+            // Wrap in a normalised shape so callers get consistent output
+            const wrapped = async (text) => {
+                const output = await featureExtractor(text, { pooling: 'mean', normalize: true });
+                return output;
+            };
+            _pipeline = wrapped;
+            _transformersAvailable = true;
+            return wrapped;
+        }
+        catch {
+            _transformersAvailable = false;
+            return null;
+        }
+    })();
+    return _pipelineLoading;
+}
+// ---------------------------------------------------------------------------
+// TF-IDF fallback
+// ---------------------------------------------------------------------------
+/**
+ * Build a simple term-frequency vector from a piece of text.
+ * Returns a sparse Map<term, tf> (normalised by document length).
+ */
+function buildTfVector(text) {
+    const tokens = tokenise(text);
+    const tf = new Map();
+    for (const token of tokens) {
+        tf.set(token, (tf.get(token) ?? 0) + 1);
+    }
+    // Normalise by document length
+    for (const [term, count] of tf) {
+        tf.set(term, count / tokens.length);
+    }
+    return tf;
+}
+function tokenise(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, ' ')
+        .split(/\s+/)
+        .filter(t => t.length > 1 && !STOP_WORDS.has(t));
+}
+/** Minimal English stop-word list */
+const STOP_WORDS = new Set([
+    'a', 'an', 'the', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for',
+    'of', 'is', 'it', 'its', 'be', 'by', 'as', 'are', 'was', 'were', 'with',
+    'this', 'that', 'from', 'not', 'we', 'i', 'you', 'he', 'she', 'they',
+    'do', 'does', 'did', 'have', 'has', 'had', 'can', 'will', 'would', 'should',
+    'so', 'if', 'up', 'out', 'no', 'my', 'your', 'our', 'all', 'more', 'also',
+]);
+/**
+ * Cosine similarity between two TF sparse vectors.
+ */
+function sparseCosine(a, b) {
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (const [term, va] of a) {
+        normA += va * va;
+        const vb = b.get(term) ?? 0;
+        dot += va * vb;
+    }
+    for (const [, vb] of b) {
+        normB += vb * vb;
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    return denom === 0 ? 0 : dot / denom;
+}
+// ---------------------------------------------------------------------------
+// Exported functions
+// ---------------------------------------------------------------------------
+/**
+ * Generate a 384-dimensional embedding vector using bge-small-en-v1.5.
+ * Falls back to an empty array if @xenova/transformers is not installed.
+ * Callers should check array length before using for similarity.
+ */
+async function generateLocalEmbedding(text) {
+    const pipe = await getTransformerPipeline();
+    if (!pipe)
+        return [];
+    try {
+        const result = await pipe(text);
+        return Array.from(result.data);
+    }
+    catch (err) {
+        console.warn('[LocalEmbeddings] generateLocalEmbedding failed:', err.message);
+        return [];
+    }
+}
+/**
+ * Cosine similarity between two dense numeric vectors.
+ * Returns a value in [-1, 1] (1 = identical direction).
+ */
+function cosineSimilarity(a, b) {
+    if (a.length === 0 || b.length === 0 || a.length !== b.length)
+        return 0;
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    return denom === 0 ? 0 : dot / denom;
+}
+/**
+ * Rank candidates by semantic similarity to the query.
+ *
+ * Tries ONNX embedding first; falls back to TF-IDF keyword similarity if
+ * @xenova/transformers is not installed or if embedding fails.
+ *
+ * @param query      - Search query string
+ * @param candidates - Items to rank (each has an `id` and `text` for embedding)
+ * @param topK       - How many results to return (default 5)
+ *
+ * @returns Ranked array of { id, score } sorted by descending similarity
+ */
+async function searchByEmbedding(query, candidates, topK = 5) {
+    if (candidates.length === 0)
+        return [];
+    const pipe = await getTransformerPipeline();
+    if (pipe) {
+        // --- ONNX path ---
+        try {
+            const queryVec = await generateLocalEmbedding(query);
+            if (queryVec.length === 0)
+                throw new Error('Empty query embedding');
+            const scored = await Promise.all(candidates.map(async (c) => {
+                const vec = await generateLocalEmbedding(c.text);
+                return { id: c.id, score: cosineSimilarity(queryVec, vec) };
+            }));
+            return scored
+                .sort((a, b) => b.score - a.score)
+                .slice(0, topK);
+        }
+        catch (err) {
+            console.warn('[LocalEmbeddings] ONNX search failed, falling back to TF-IDF:', err.message);
+        }
+    }
+    // --- TF-IDF keyword fallback ---
+    const queryTf = buildTfVector(query);
+    const scored = candidates.map((c) => ({
+        id: c.id,
+        score: sparseCosine(queryTf, buildTfVector(c.text)),
+    }));
+    return scored
+        .sort((a, b) => b.score - a.score)
+        .slice(0, topK);
+}
+/**
+ * Check whether the ONNX embedding pipeline is available.
+ * Returns false if @xenova/transformers is not installed.
+ */
+async function isEmbeddingAvailable() {
+    if (_transformersAvailable !== null)
+        return _transformersAvailable;
+    const pipe = await getTransformerPipeline();
+    return pipe !== null;
+}

package/dist/local/offline-fallback.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Offline MCP Fallback
+ *
+ * When the remote API is unreachable, falls back to local SQLite.
+ * Transparent to callers — same interface, different backend.
+ *
+ * Tool coverage:
+ *   ekkOS_Search   → localStore.searchPatterns
+ *   ekkOS_Forge    → localStore.forgePattern
+ *   ekkOS_Track    → localStore.trackApplication
+ *   ekkOS_Outcome  → localStore.recordOutcome
+ *   ekkOS_Directive→ localStore.createDirective
+ *   ekkOS_Stats    → localStore.getStats
+ */
+declare const OFFLINE_CAPABLE_TOOLS: readonly ["ekkOS_Search", "ekkOS_Forge", "ekkOS_Track", "ekkOS_Outcome", "ekkOS_Directive", "ekkOS_Stats"];
+export interface ToolCallResult {
+    success: boolean;
+    data?: any;
+    error?: string;
+    /** Present when the call was served from local store rather than the cloud */
+    _degraded?: boolean;
+    /** Present when the call was served from local store */
+    _local?: boolean;
+}
+export type RemoteCallFn = () => Promise<any>;
+/**
+ * Attempt the remote MCP call. If it times out or throws, transparently fall
+ * back to the local SQLite store for supported tools.
+ *
+ * @param tool       - ekkOS tool name (e.g. 'ekkOS_Search')
+ * @param args       - Arguments to pass to the tool / local equivalent
+ * @param remoteCall - Zero-arg async function that performs the actual remote call
+ *
+ * @returns ToolCallResult with optional `_local: true` flag when served locally
+ */
+export declare function callWithFallback(tool: string, args: Record<string, any>, remoteCall: RemoteCallFn): Promise<ToolCallResult>;
+/**
+ * Convenience check: is the offline fallback layer ready to serve requests?
+ */
+export declare function isOfflineFallbackReady(): boolean;
+/**
+ * Exported constant for consumers that need to know which tools work offline.
+ */
+export { OFFLINE_CAPABLE_TOOLS };

package/dist/local/offline-fallback.js

@@ -0,0 +1,159 @@
+"use strict";
+/**
+ * Offline MCP Fallback
+ *
+ * When the remote API is unreachable, falls back to local SQLite.
+ * Transparent to callers — same interface, different backend.
+ *
+ * Tool coverage:
+ *   ekkOS_Search   → localStore.searchPatterns
+ *   ekkOS_Forge    → localStore.forgePattern
+ *   ekkOS_Track    → localStore.trackApplication
+ *   ekkOS_Outcome  → localStore.recordOutcome
+ *   ekkOS_Directive→ localStore.createDirective
+ *   ekkOS_Stats    → localStore.getStats
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OFFLINE_CAPABLE_TOOLS = void 0;
+exports.callWithFallback = callWithFallback;
+exports.isOfflineFallbackReady = isOfflineFallbackReady;
+const sqlite_store_1 = require("./sqlite-store");
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const MCP_TIMEOUT = 3000; // 3 seconds
+const OFFLINE_CAPABLE_TOOLS = [
+    'ekkOS_Search',
+    'ekkOS_Forge',
+    'ekkOS_Track',
+    'ekkOS_Outcome',
+    'ekkOS_Directive',
+    'ekkOS_Stats',
+];
+exports.OFFLINE_CAPABLE_TOOLS = OFFLINE_CAPABLE_TOOLS;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function isOfflineCapable(tool) {
+    return OFFLINE_CAPABLE_TOOLS.includes(tool);
+}
+function withTimeout(promise, ms) {
+    return Promise.race([
+        promise,
+        new Promise((_, reject) => setTimeout(() => reject(new Error(`Timeout after ${ms}ms`)), ms)),
+    ]);
+}
+// ---------------------------------------------------------------------------
+// Local tool dispatch
+// ---------------------------------------------------------------------------
+function dispatchLocal(tool, args) {
+    if (!sqlite_store_1.localStore.isAvailable()) {
+        return {
+            success: false,
+            error: 'Local store not available (better-sqlite3 not installed)',
+            _degraded: true,
+        };
+    }
+    try {
+        switch (tool) {
+            case 'ekkOS_Search': {
+                const { user_id, query, limit } = args;
+                const patterns = sqlite_store_1.localStore.searchPatterns(user_id, query, limit);
+                return {
+                    success: true,
+                    data: { patterns, source: 'local', total: patterns.length },
+                    _local: true,
+                };
+            }
+            case 'ekkOS_Forge': {
+                const { user_id, title, problem, solution, tags } = args;
+                const patternId = sqlite_store_1.localStore.forgePattern(user_id, { title, problem, solution, tags });
+                return {
+                    success: true,
+                    data: { pattern_id: patternId, source: 'local' },
+                    _local: true,
+                };
+            }
+            case 'ekkOS_Track': {
+                const { pattern_id } = args;
+                sqlite_store_1.localStore.trackApplication(pattern_id);
+                return { success: true, data: { tracked: true, source: 'local' }, _local: true };
+            }
+            case 'ekkOS_Outcome': {
+                const { pattern_id, success } = args;
+                sqlite_store_1.localStore.recordOutcome(pattern_id, success);
+                return { success: true, data: { recorded: true, source: 'local' }, _local: true };
+            }
+            case 'ekkOS_Directive': {
+                const { user_id, type, rule, reason, priority, scope } = args;
+                const id = sqlite_store_1.localStore.createDirective(user_id, { type, rule, reason, priority, scope });
+                return {
+                    success: true,
+                    data: { id, source: 'local' },
+                    _local: true,
+                };
+            }
+            case 'ekkOS_Stats': {
+                const { user_id } = args;
+                const stats = sqlite_store_1.localStore.getStats(user_id);
+                return { success: true, data: { ...stats, source: 'local' }, _local: true };
+            }
+            default: {
+                // TypeScript exhaustiveness guard — should never reach here
+                const _never = tool;
+                return {
+                    success: false,
+                    error: `Unknown offline-capable tool: ${_never}`,
+                    _degraded: true,
+                };
+            }
+        }
+    }
+    catch (err) {
+        return {
+            success: false,
+            error: `Local store error: ${err.message}`,
+            _degraded: true,
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Main export: callWithFallback
+// ---------------------------------------------------------------------------
+/**
+ * Attempt the remote MCP call. If it times out or throws, transparently fall
+ * back to the local SQLite store for supported tools.
+ *
+ * @param tool       - ekkOS tool name (e.g. 'ekkOS_Search')
+ * @param args       - Arguments to pass to the tool / local equivalent
+ * @param remoteCall - Zero-arg async function that performs the actual remote call
+ *
+ * @returns ToolCallResult with optional `_local: true` flag when served locally
+ */
+async function callWithFallback(tool, args, remoteCall) {
+    // Attempt remote call with timeout
+    try {
+        const data = await withTimeout(remoteCall(), MCP_TIMEOUT);
+        return { success: true, data };
+    }
+    catch (err) {
+        const reason = err.message;
+        // Check whether we can serve this tool locally
+        if (!isOfflineCapable(tool)) {
+            return {
+                success: false,
+                error: `Offline — tool not available locally (${reason})`,
+                _degraded: true,
+            };
+        }
+        // Log the fallback so callers / users are aware
+        console.warn(`[OfflineFallback] Remote call failed for ${tool} (${reason}) — using local store`);
+        return dispatchLocal(tool, args);
+    }
+}
+/**
+ * Convenience check: is the offline fallback layer ready to serve requests?
+ */
+function isOfflineFallbackReady() {
+    return sqlite_store_1.localStore.isAvailable();
+}

package/dist/local/sqlite-store.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Local SQLite Memory Store
+ *
+ * Provides offline-capable memory storage using SQLite with WAL mode.
+ * Mirrors the Supabase schema for seamless sync.
+ * Location: ~/.ekkos/memory.db
+ *
+ * Dependency: better-sqlite3
+ * Add to package.json: "better-sqlite3": "^9.4.0"
+ * Dev dep:             "@types/better-sqlite3": "^7.6.8"
+ */
+export interface Pattern {
+    pattern_id: string;
+    user_id: string;
+    title: string;
+    problem: string;
+    solution: string;
+    status: string;
+    applied_count: number;
+    success_rate: number;
+    tags: string[];
+    quarantined: boolean;
+    created_at: string;
+    updated_at: string;
+    synced_at: string | null;
+}
+export interface Directive {
+    id: string;
+    user_id: string;
+    type: 'MUST' | 'NEVER' | 'PREFER' | 'AVOID';
+    rule: string;
+    reason: string;
+    priority: number;
+    scope: string | null;
+    is_active: boolean;
+    created_at: string;
+    synced_at: string | null;
+}
+export interface EpisodicMemory {
+    id: string;
+    user_id: string;
+    problem: string;
+    solution: string;
+    session_name: string | null;
+    quality_score: number;
+    created_at: string;
+    synced_at: string | null;
+}
+export interface SyncQueueItem {
+    id: number;
+    table_name: string;
+    record_id: string;
+    operation: 'insert' | 'update' | 'delete';
+    payload: any;
+    created_at: string;
+    synced_at: string | null;
+}
+export interface StoreStats {
+    pattern_count: number;
+    active_pattern_count: number;
+    directive_count: number;
+    episodic_count: number;
+    pending_sync_count: number;
+    db_path: string;
+}
+export declare class LocalMemoryStore {
+    private db;
+    constructor();
+    private init;
+    private get database();
+    private migrate;
+    private rowToPattern;
+    private parseTags;
+    /**
+     * Full-text search across title, problem, solution, and tags using LIKE.
+     * Falls back gracefully when FTS5 is unavailable.
+     */
+    searchPatterns(userId: string, query: string, limit?: number): Pattern[];
+    /**
+     * Insert a new pattern and enqueue it for sync.
+     * Returns the generated pattern_id.
+     */
+    forgePattern(userId: string, input: {
+        title: string;
+        problem: string;
+        solution: string;
+        tags?: string[];
+    }): string;
+    /**
+     * Increment applied_count and mark as needing sync.
+     */
+    trackApplication(patternId: string): void;
+    /**
+     * Update success_rate using a weighted moving average and enqueue sync.
+     * Weight: 0.1 for new observation (exponential moving average).
+     */
+    recordOutcome(patternId: string, success: boolean): void;
+    /**
+     * Get active directives for a user, optionally filtered by type.
+     */
+    getDirectives(userId: string, types?: string[]): Directive[];
+    /**
+     * Insert a new directive and enqueue for sync.
+     * Returns the generated id.
+     */
+    createDirective(userId: string, input: {
+        type: string;
+        rule: string;
+        reason: string;
+        priority?: number;
+        scope?: string;
+    }): string;
+    /**
+     * Soft-delete a directive by setting is_active = 0.
+     */
+    deleteDirective(id: string): void;
+    private rowToDirective;
+    getStats(userId: string): StoreStats;
+    getPendingSync(): SyncQueueItem[];
+    markSynced(id: number): void;
+    getMeta(key: string): string | null;
+    setMeta(key: string, value: string): void;
+    private queueSync;
+    isAvailable(): boolean;
+}
+export declare const localStore: LocalMemoryStore;