capman 0.3.0 → 0.4.0

package/dist/esm/cache.js

@@ -43,36 +43,33 @@ export class FileCache {
         this.store = new Map();
         this.loaded = false;
         this.filePath = path.resolve(process.cwd(), filePath);
+        logger.info(`FileCache initialized — writing to: ${this.filePath}`);
     }
-    load() {
+    async load() {
         if (this.loaded)
             return;
         try {
-            if (fs.existsSync(this.filePath)) {
-                const raw = JSON.parse(fs.readFileSync(this.filePath, 'utf-8'));
-                this.store = new Map(Object.entries(raw));
-                logger.debug(`File cache loaded: ${this.store.size} entries`);
-            }
+            const raw = await fs.promises.readFile(this.filePath, 'utf-8');
+            this.store = new Map(Object.entries(JSON.parse(raw)));
+            logger.debug(`File cache loaded: ${this.store.size} entries`);
         }
         catch {
-            logger.warn(`Failed to load file cache at ${this.filePath}`);
+            // File doesn't exist yet — start fresh
         }
         this.loaded = true;
     }
-    save() {
+    async save() {
         try {
             const dir = path.dirname(this.filePath);
-            if (!fs.existsSync(dir))
-                fs.mkdirSync(dir, { recursive: true });
-            const obj = Object.fromEntries(this.store);
-            fs.writeFileSync(this.filePath, JSON.stringify(obj, null, 2));
+            await fs.promises.mkdir(dir, { recursive: true });
+            await fs.promises.writeFile(this.filePath, JSON.stringify(Object.fromEntries(this.store), null, 2));
         }
         catch {
             logger.warn(`Failed to save file cache to ${this.filePath}`);
         }
     }
     async get(query) {
-        this.load();
+        await this.load();
         const key = normalizeQuery(query);
         const entry = this.store.get(key);
         if (entry) {
@@ -83,7 +80,7 @@ export class FileCache {
         return null;
     }
     async set(query, result) {
-        this.load();
+        await this.load();
         const key = normalizeQuery(query);
         this.store.set(key, {
             query,
@@ -91,15 +88,15 @@ export class FileCache {
             cachedAt: new Date().toISOString(),
             hits: 0,
         });
-        this.save();
+        await this.save();
         logger.debug(`Cache set (file): "${query}"`);
     }
     async clear() {
         this.store.clear();
-        this.save();
+        await this.save();
     }
     async size() {
-        this.load();
+        await this.load();
         return this.store.size;
     }
 }
@@ -119,6 +116,7 @@ export class ComboCache {
         if (fileHit) {
             // Promote to memory for next time
             await this.memory.set(query, fileHit.result);
+            logger.debug(`Cache promoted to memory: "${query}"`);
             return fileHit;
         }
         return null;

package/dist/esm/engine.js

@@ -1,7 +1,7 @@
 import { match as _match, matchWithLLM as _matchWithLLM } from './matcher';
 import { resolve as _resolve } from './resolver';
-import { ComboCache } from './cache';
-import { FileLearningStore } from './learning';
+import { MemoryCache } from './cache';
+import { MemoryLearningStore } from './learning';
 import { logger } from './logger';
 // ─── CapmanEngine ─────────────────────────────────────────────────────────────
 export class CapmanEngine {
@@ -13,14 +13,16 @@ export class CapmanEngine {
         this.auth = options.auth;
         this.headers = options.headers;
         this.threshold = options.threshold ?? 50;
-        // Cache — default ComboCache, or disabled with false
+        // Cache — default MemoryCache (no filesystem writes), or disabled with false
+        // Use FileCache or ComboCache explicitly for persistence across restarts
         this.cache = options.cache === false
             ? null
-            : (options.cache ?? new ComboCache());
-        // Learning — default FileLearningStore, or disabled with false
+            : (options.cache ?? new MemoryCache());
+        // Learning — default MemoryLearningStore (no filesystem writes), or disabled with false
+        // Use FileLearningStore explicitly for persistence across restarts
         this.learning = options.learning === false
             ? null
-            : (options.learning ?? new FileLearningStore());
+            : (options.learning ?? new MemoryLearningStore());
         logger.info(`CapmanEngine initialized — mode: ${this.mode}, cache: ${this.cache ? 'enabled' : 'disabled'}, learning: ${this.learning ? 'enabled' : 'disabled'}`);
     }
     /**
@@ -36,68 +38,145 @@ export class CapmanEngine {
      */
     async ask(query, overrides = {}) {
         const start = Date.now();
+        const steps = [];
+        let resolvedVia = 'keyword';
         // ── Step 1: Check cache ──────────────────────────────────────────────────
+        const cacheStart = Date.now();
         if (this.cache) {
             const cached = await this.cache.get(query);
             if (cached) {
+                steps.push({ type: 'cache_check', status: 'hit', durationMs: Date.now() - cacheStart, detail: 'Served from cache' });
                 logger.info(`Cache hit for: "${query}"`);
                 const resolution = await _resolve(cached.result, cached.result.extractedParams, this.resolveOptions(overrides));
+                const trace = {
+                    query,
+                    candidates: cached.result.candidates ?? [],
+                    reasoning: [`Served from cache (original: ${cached.result.reasoning})`],
+                    steps,
+                    resolvedVia: 'cache',
+                    totalMs: Date.now() - start,
+                };
                 const result = {
                     match: cached.result,
                     resolution,
                     resolvedVia: 'cache',
                     durationMs: Date.now() - start,
+                    trace,
                 };
                 await this.recordLearning(query, cached.result, 'cache');
                 return result;
             }
+            steps.push({ type: 'cache_check', status: 'miss', durationMs: Date.now() - cacheStart });
+        }
+        else {
+            steps.push({ type: 'cache_check', status: 'skip', durationMs: 0, detail: 'Cache disabled' });
         }
         // ── Step 2: Match ────────────────────────────────────────────────────────
         let matchResult;
-        let resolvedVia = 'keyword';
         switch (this.mode) {
             case 'cheap': {
+                const t = Date.now();
                 matchResult = _match(query, this.manifest);
+                steps.push({ type: 'keyword_match', status: 'pass', durationMs: Date.now() - t, detail: `confidence: ${matchResult.confidence}%` });
                 break;
             }
             case 'accurate': {
                 if (this.llm) {
+                    const t = Date.now();
                     matchResult = await _matchWithLLM(query, this.manifest, { llm: this.llm });
                     resolvedVia = 'llm';
+                    steps.push({ type: 'llm_match', status: 'pass', durationMs: Date.now() - t, detail: `confidence: ${matchResult.confidence}%` });
                 }
                 else {
                     logger.warn('accurate mode requires llm — falling back to keyword');
+                    const t = Date.now();
                     matchResult = _match(query, this.manifest);
+                    steps.push({ type: 'keyword_match', status: 'pass', durationMs: Date.now() - t, detail: 'llm not provided, used keyword' });
                 }
                 break;
             }
             case 'balanced':
             default: {
+                const t1 = Date.now();
                 const keywordResult = _match(query, this.manifest);
+                steps.push({ type: 'keyword_match', status: 'pass', durationMs: Date.now() - t1, detail: `confidence: ${keywordResult.confidence}%` });
                 if (keywordResult.confidence >= this.threshold || !this.llm) {
                     matchResult = keywordResult;
                 }
                 else {
                     logger.info(`Low confidence (${keywordResult.confidence}%) — escalating to LLM`);
+                    const t2 = Date.now();
                     matchResult = await _matchWithLLM(query, this.manifest, { llm: this.llm });
                     resolvedVia = 'llm';
+                    steps.push({ type: 'llm_match', status: 'pass', durationMs: Date.now() - t2, detail: `confidence: ${matchResult.confidence}%` });
                 }
                 break;
             }
         }
-        // ── Step 3: Cache the match result ───────────────────────────────────────
+        // ── Step 3: Privacy check ────────────────────────────────────────────────
+        if (matchResult.capability) {
+            const privacyLevel = matchResult.capability.privacy.level;
+            steps.push({
+                type: 'privacy_check',
+                status: 'pass',
+                durationMs: 0,
+                detail: `level: ${privacyLevel}`,
+            });
+        }
+        // ── Step 4: Cache the match result ───────────────────────────────────────
         if (this.cache && matchResult.capability) {
             await this.cache.set(query, matchResult);
         }
-        // ── Step 4: Resolve ──────────────────────────────────────────────────────
+        // ── Step 5: Resolve ──────────────────────────────────────────────────────
+        const resolveStart = Date.now();
         const resolution = await _resolve(matchResult, matchResult.extractedParams, this.resolveOptions(overrides));
-        // ── Step 5: Record learning ──────────────────────────────────────────────
+        steps.push({
+            type: 'resolve',
+            status: resolution.success ? 'pass' : 'fail',
+            durationMs: Date.now() - resolveStart,
+            detail: resolution.error ?? `via ${resolution.resolverType}`,
+        });
+        // ── Step 6: Build reasoning array ────────────────────────────────────────
+        const reasoning = [];
+        if (matchResult.candidates?.length) {
+            const winner = matchResult.candidates.find(c => c.matched);
+            const rejected = matchResult.candidates
+                .filter(c => !c.matched && c.score > 0)
+                .sort((a, b) => b.score - a.score)
+                .slice(0, 3);
+            if (winner) {
+                reasoning.push(`Matched "${winner.capabilityId}" with ${winner.score}% confidence`);
+            }
+            if (rejected.length) {
+                reasoning.push(`Rejected: ${rejected.map(r => `${r.capabilityId} (${r.score}%)`).join(', ')}`);
+            }
+            reasoning.push(`Resolved via: ${resolvedVia}`);
+            if (matchResult.extractedParams && Object.keys(matchResult.extractedParams).length) {
+                const params = Object.entries(matchResult.extractedParams)
+                    .map(([k, v]) => `${k}=${v}`)
+                    .join(', ');
+                reasoning.push(`Extracted params: ${params}`);
+            }
+        }
+        else {
+            reasoning.push(matchResult.reasoning);
+        }
+        // ── Step 7: Record learning ──────────────────────────────────────────────
         await this.recordLearning(query, matchResult, resolvedVia);
+        const trace = {
+            query,
+            candidates: matchResult.candidates ?? [],
+            reasoning,
+            steps,
+            resolvedVia,
+            totalMs: Date.now() - start,
+        };
         return {
             match: matchResult,
             resolution,
             resolvedVia,
             durationMs: Date.now() - start,
+            trace,
         };
     }
     /**

package/dist/esm/learning.js

@@ -1,34 +1,74 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { logger } from './logger';
+// ─── Shared computation helpers ───────────────────────────────────────────────
+function computeStats(entries) {
+    const index = {};
+    let totalQueries = 0;
+    let llmQueries = 0;
+    let cacheHits = 0;
+    let outOfScope = 0;
+    for (const entry of entries) {
+        totalQueries++;
+        if (entry.resolvedVia === 'llm')
+            llmQueries++;
+        if (entry.resolvedVia === 'cache')
+            cacheHits++;
+        if (!entry.capabilityId)
+            outOfScope++;
+        if (entry.capabilityId) {
+            const words = entry.query.toLowerCase()
+                .split(/\W+/)
+                .filter(w => w.length > 2);
+            for (const word of words) {
+                if (!index[word])
+                    index[word] = {};
+                index[word][entry.capabilityId] =
+                    (index[word][entry.capabilityId] ?? 0) + 1;
+            }
+        }
+    }
+    return { index, totalQueries, llmQueries, cacheHits, outOfScope };
+}
+function computeTopCapabilities(entries, limit) {
+    const counts = {};
+    for (const entry of entries) {
+        if (entry.capabilityId) {
+            counts[entry.capabilityId] = (counts[entry.capabilityId] ?? 0) + 1;
+        }
+    }
+    return Object.entries(counts)
+        .sort(([, a], [, b]) => b - a)
+        .slice(0, limit)
+        .map(([id, hits]) => ({ id, hits }));
+}
 // ─── File Learning Store ──────────────────────────────────────────────────────
 export class FileLearningStore {
     constructor(filePath = '.capman/learning.json') {
         this.entries = [];
         this.loaded = false;
         this.filePath = path.resolve(process.cwd(), filePath);
+        logger.info(`FileLearningStore initialized — writing to: ${this.filePath}`);
     }
-    load() {
+    async load() {
         if (this.loaded)
             return;
         try {
-            if (fs.existsSync(this.filePath)) {
-                const raw = JSON.parse(fs.readFileSync(this.filePath, 'utf-8'));
-                this.entries = raw.entries ?? [];
-                logger.debug(`Learning store loaded: ${this.entries.length} entries`);
-            }
+            const raw = await fs.promises.readFile(this.filePath, 'utf-8');
+            const parsed = JSON.parse(raw);
+            this.entries = parsed.entries ?? [];
+            logger.debug(`Learning store loaded: ${this.entries.length} entries`);
         }
         catch {
-            logger.warn(`Failed to load learning store at ${this.filePath}`);
+            // File doesn't exist yet — start fresh
         }
         this.loaded = true;
     }
-    save() {
+    async save() {
         try {
             const dir = path.dirname(this.filePath);
-            if (!fs.existsSync(dir))
-                fs.mkdirSync(dir, { recursive: true });
-            fs.writeFileSync(this.filePath, JSON.stringify({
+            await fs.promises.mkdir(dir, { recursive: true });
+            await fs.promises.writeFile(this.filePath, JSON.stringify({
                 entries: this.entries,
                 updatedAt: new Date().toISOString(),
             }, null, 2));
@@ -38,57 +78,22 @@ export class FileLearningStore {
         }
     }
     async record(entry) {
-        this.load();
+        await this.load();
         this.entries.push(entry);
-        this.save();
+        await this.save();
         logger.debug(`Learning recorded: "${entry.query}" → ${entry.capabilityId ?? 'OUT_OF_SCOPE'} via ${entry.resolvedVia}`);
     }
     async getStats() {
-        this.load();
-        const index = {};
-        let totalQueries = 0;
-        let llmQueries = 0;
-        let cacheHits = 0;
-        let outOfScope = 0;
-        for (const entry of this.entries) {
-            totalQueries++;
-            if (entry.resolvedVia === 'llm')
-                llmQueries++;
-            if (entry.resolvedVia === 'cache')
-                cacheHits++;
-            if (!entry.capabilityId)
-                outOfScope++;
-            if (entry.capabilityId) {
-                // Index each word of the query against the matched capability
-                const words = entry.query.toLowerCase()
-                    .split(/\W+/)
-                    .filter(w => w.length > 2);
-                for (const word of words) {
-                    if (!index[word])
-                        index[word] = {};
-                    index[word][entry.capabilityId] =
-                        (index[word][entry.capabilityId] ?? 0) + 1;
-                }
-            }
-        }
-        return { index, totalQueries, llmQueries, cacheHits, outOfScope };
+        await this.load();
+        return computeStats(this.entries);
     }
     async getTopCapabilities(limit = 5) {
-        this.load();
-        const counts = {};
-        for (const entry of this.entries) {
-            if (entry.capabilityId) {
-                counts[entry.capabilityId] = (counts[entry.capabilityId] ?? 0) + 1;
-            }
-        }
-        return Object.entries(counts)
-            .sort(([, a], [, b]) => b - a)
-            .slice(0, limit)
-            .map(([id, hits]) => ({ id, hits }));
+        await this.load();
+        return computeTopCapabilities(this.entries, limit);
     }
     async clear() {
         this.entries = [];
-        this.save();
+        await this.save();
     }
 }
 // ─── Memory Learning Store (for testing) ─────────────────────────────────────
@@ -100,44 +105,10 @@ export class MemoryLearningStore {
         this.entries.push(entry);
     }
     async getStats() {
-        const index = {};
-        let totalQueries = 0;
-        let llmQueries = 0;
-        let cacheHits = 0;
-        let outOfScope = 0;
-        for (const entry of this.entries) {
-            totalQueries++;
-            if (entry.resolvedVia === 'llm')
-                llmQueries++;
-            if (entry.resolvedVia === 'cache')
-                cacheHits++;
-            if (!entry.capabilityId)
-                outOfScope++;
-            if (entry.capabilityId) {
-                const words = entry.query.toLowerCase()
-                    .split(/\W+/)
-                    .filter(w => w.length > 2);
-                for (const word of words) {
-                    if (!index[word])
-                        index[word] = {};
-                    index[word][entry.capabilityId] =
-                        (index[word][entry.capabilityId] ?? 0) + 1;
-                }
-            }
-        }
-        return { index, totalQueries, llmQueries, cacheHits, outOfScope };
+        return computeStats(this.entries);
     }
     async getTopCapabilities(limit = 5) {
-        const counts = {};
-        for (const entry of this.entries) {
-            if (entry.capabilityId) {
-                counts[entry.capabilityId] = (counts[entry.capabilityId] ?? 0) + 1;
-            }
-        }
-        return Object.entries(counts)
-            .sort(([, a], [, b]) => b - a)
-            .slice(0, limit)
-            .map(([id, hits]) => ({ id, hits }));
+        return computeTopCapabilities(this.entries, limit);
     }
     async clear() {
         this.entries = [];

package/dist/esm/matcher.js

@@ -140,33 +140,44 @@ export function match(query, manifest) {
     logger.debug(`Manifest has ${manifest.capabilities.length} capabilities`);
     let best = null;
     let bestScore = 0;
+    const allScores = [];
     for (const cap of manifest.capabilities) {
         const score = scoreCapability(query, cap);
         logger.debug(`  scored "${cap.id}": ${score}%`);
+        allScores.push({ cap, score });
         if (score > bestScore) {
             bestScore = score;
             best = cap;
         }
     }
+    const candidates = allScores.map(({ cap, score }) => ({
+        capabilityId: cap.id,
+        score,
+        matched: cap.id === best?.id,
+    }));
     if (!best || bestScore < 50) {
         logger.info(`No match above threshold (best: ${bestScore}% for "${best?.id ?? 'none'}")`);
+        // Out of scope return:
         return {
             capability: null,
             confidence: bestScore,
             intent: 'out_of_scope',
             extractedParams: {},
             reasoning: `No capability matched with sufficient confidence (best score: ${bestScore})`,
+            candidates,
         };
     }
     const params = extractParams(query, best);
     logger.info(`Matched "${best.id}" at ${bestScore}% confidence`);
     logger.debug(`Extracted params: ${JSON.stringify(params)}`);
+    // Matched return:
     return {
         capability: best,
         confidence: bestScore,
         intent: resolverToIntent(best),
         extractedParams: params,
         reasoning: `Matched "${best.id}" via keyword scoring (score: ${bestScore})`,
+        candidates,
     };
 }
 export async function matchWithLLM(query, manifest, options) {

package/dist/esm/resolver.js

@@ -88,78 +88,76 @@ export async function resolve(matchResult, params = {}, options = {}) {
 }
 async function resolveApi(resolver, params, options) {
     const startTime = Date.now();
+    const retries = options.retries ?? 0;
+    const timeoutMs = options.timeoutMs ?? 5000;
     const apiCalls = resolver.endpoints.map(endpoint => ({
         method: endpoint.method,
         url: buildUrl(options.baseUrl ?? '', endpoint.path, params),
         params,
     }));
     if (options.dryRun) {
-        return {
-            success: true,
-            resolverType: 'api',
-            apiCalls,
-            durationMs: Date.now() - startTime,
-        };
+        return { success: true, resolverType: 'api', apiCalls, durationMs: Date.now() - startTime };
     }
     const fetchFn = options.fetch ?? globalThis.fetch;
     if (!fetchFn) {
         return {
-            success: true,
-            resolverType: 'api',
-            apiCalls,
+            success: true, resolverType: 'api', apiCalls,
             durationMs: Date.now() - startTime,
             error: 'No fetch available — returning call plan only',
         };
     }
+    // ── Fetch with retry + timeout ────────────────────────────────────────────
+    async function fetchWithRetry(call, attempt) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const res = await fetchFn(call.url, {
+                method: call.method,
+                headers: options.headers ?? {},
+                signal: controller.signal,
+                body: ['POST', 'PUT', 'PATCH'].includes(call.method)
+                    ? JSON.stringify(call.params)
+                    : undefined,
+            });
+            clearTimeout(timer);
+            return res;
+        }
+        catch (err) {
+            clearTimeout(timer);
+            const isTimeout = err instanceof Error && err.name === 'AbortError';
+            if (attempt < retries) {
+                logger.warn(`Request failed (attempt ${attempt + 1}/${retries + 1}) — retrying: ${isTimeout ? 'timeout' : err}`);
+                return fetchWithRetry(call, attempt + 1);
+            }
+            throw isTimeout ? new Error(`Request timed out after ${timeoutMs}ms`) : err;
+        }
+    }
     try {
-        const responses = await Promise.all(apiCalls.map(c => fetchFn(c.url, {
-            method: c.method,
-            headers: options.headers ?? {},
-            body: ['POST', 'PUT', 'PATCH'].includes(c.method)
-                ? JSON.stringify(c.params)
-                : undefined,
-        })));
-        // Check for HTTP errors
+        const responses = await Promise.all(apiCalls.map(c => fetchWithRetry(c, 0)));
         const failedIdx = responses.findIndex(r => !r.ok);
         if (failedIdx !== -1) {
             const failed = responses[failedIdx];
             return {
-                success: false,
-                resolverType: 'api',
-                apiCalls,
+                success: false, resolverType: 'api', apiCalls,
                 durationMs: Date.now() - startTime,
                 error: `API request failed: ${failed.status} ${failed.statusText}`,
             };
         }
-        // Parse response bodies
         const enrichedCalls = await Promise.all(responses.map(async (res, i) => {
             let data = undefined;
             try {
                 const text = await res.text();
                 data = text ? JSON.parse(text) : undefined;
             }
-            catch {
-                // Non-JSON response — leave data undefined
-            }
-            return {
-                ...apiCalls[i],
-                status: res.status,
-                data,
-            };
+            catch { /* non-JSON response */ }
+            return { ...apiCalls[i], status: res.status, data };
         }));
         logger.debug(`API calls completed in ${Date.now() - startTime}ms`);
-        return {
-            success: true,
-            resolverType: 'api',
-            apiCalls: enrichedCalls,
-            durationMs: Date.now() - startTime,
-        };
+        return { success: true, resolverType: 'api', apiCalls: enrichedCalls, durationMs: Date.now() - startTime };
     }
     catch (err) {
         return {
-            success: false,
-            resolverType: 'api',
-            apiCalls,
+            success: false, resolverType: 'api', apiCalls,
             durationMs: Date.now() - startTime,
             error: err instanceof Error ? err.message : String(err),
         };

package/dist/esm/version.js

@@ -1,2 +1,2 @@
 // Auto-generated by scripts/version.js — do not edit manually
-export const VERSION = '0.3.0';
+export const VERSION = '0.4.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "capman",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Capability Manifest Engine — let AI agents interact with your app without navigating the UI",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",