capman 0.4.5 → 0.5.1

package/dist/esm/engine.js

@@ -1,4 +1,4 @@
-import { match as _match, matchWithLLM as _matchWithLLM, resolverToIntent } from './matcher';
+import { match as _match, matchWithLLM as _matchWithLLM, resolverToIntent, extractParams, STOPWORDS } from './matcher';
 import { resolve as _resolve } from './resolver';
 import { MemoryLearningStore } from './learning';
 import { logger } from './logger';
@@ -7,9 +7,6 @@ import { VERSION } from './version';
 // ─── CapmanEngine ─────────────────────────────────────────────────────────────
 export class CapmanEngine {
     constructor(options) {
-        // ── Learning index cache ──────────────────────────────────────────────────
-        this.cachedStats = null;
-        this.statsInvalidated = true;
         // ── LLM rate limiting state ────────────────────────────────────────────────
         this.llmCallsThisMinute = 0;
         this.llmWindowStart = Date.now();
@@ -23,6 +20,7 @@ export class CapmanEngine {
         this.auth = options.auth;
         this.headers = options.headers;
         this.threshold = options.threshold ?? 50;
+        this.cacheTtlMs = options.cacheTtlMs ?? null;
         this.maxLLMCallsPerMinute = options.maxLLMCallsPerMinute ?? 60;
         this.llmCooldownMs = options.llmCooldownMs ?? 0;
         this.llmCircuitBreakerThreshold = options.llmCircuitBreakerThreshold ?? 3;
@@ -42,8 +40,11 @@ export class CapmanEngine {
         const manifestMajorMinor = options.manifest.version?.split('.').slice(0, 2).join('.');
         const engineMajorMinor = VERSION.split('.').slice(0, 2).join('.');
         if (manifestMajorMinor && manifestMajorMinor !== engineMajorMinor) {
-            logger.warn(`Manifest version "${options.manifest.version}" differs from engine version "${VERSION}". ` +
-                `Run: npx capman generate  to regenerate your manifest.`);
+            // Use console.warn directly — must be visible regardless of logger level
+            // Default log level is 'silent' so logger.warn would never be seen
+            console.warn(`[capman] Manifest version "${options.manifest.version}" was generated with a ` +
+                `different engine version than "${VERSION}". If you experience matching issues, ` +
+                `regenerate with: npx capman generate`);
         }
     }
     /**
@@ -60,12 +61,11 @@ 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 queryKey = normalizeQuery(query);
-            const cached = await this.cache.get(queryKey);
+            const cached = await this.cache.get(queryKey, this.cacheTtlMs ?? undefined);
             if (cached) {
                 steps.push({ type: 'cache_check', status: 'hit', durationMs: Date.now() - cacheStart, detail: 'Served from cache' });
                 logger.info(`Cache hit for: "${query}"`);
@@ -94,116 +94,10 @@ export class CapmanEngine {
             steps.push({ type: 'cache_check', status: 'skip', durationMs: 0, detail: 'Cache disabled' });
         }
         // ── Step 2: Match ────────────────────────────────────────────────────────
-        let matchResult;
-        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 skipReason = this.checkLLMAllowed();
-                    if (skipReason) {
-                        logger.warn(`LLM skipped — ${skipReason} — 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 skipped: ${skipReason}` });
-                    }
-                    else {
-                        const t = Date.now();
-                        try {
-                            matchResult = await _matchWithLLM(query, this.manifest, { llm: this.llm });
-                            this.recordLLMSuccess();
-                            resolvedVia = 'llm';
-                            steps.push({ type: 'llm_match', status: 'pass', durationMs: Date.now() - t, detail: `confidence: ${matchResult.confidence}%` });
-                        }
-                        catch (err) {
-                            this.recordLLMFailure();
-                            logger.warn(`LLM call failed — falling back to keyword: ${err}`);
-                            const t2 = Date.now();
-                            matchResult = _match(query, this.manifest);
-                            steps.push({ type: 'llm_match', status: 'fail', durationMs: Date.now() - t, detail: String(err) });
-                            steps.push({ type: 'keyword_match', status: 'pass', durationMs: Date.now() - t2, detail: 'fallback after llm failure' });
-                        }
-                    }
-                }
-                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 {
-                    const skipReason = this.checkLLMAllowed();
-                    if (skipReason) {
-                        logger.warn(`LLM skipped — ${skipReason}`);
-                        steps.push({ type: 'llm_match', status: 'skip', durationMs: 0, detail: skipReason });
-                        matchResult = keywordResult;
-                    }
-                    else {
-                        logger.info(`Low confidence (${keywordResult.confidence}%) — escalating to LLM`);
-                        const t2 = Date.now();
-                        try {
-                            matchResult = await _matchWithLLM(query, this.manifest, { llm: this.llm });
-                            this.recordLLMSuccess();
-                            resolvedVia = 'llm';
-                            steps.push({ type: 'llm_match', status: 'pass', durationMs: Date.now() - t2, detail: `confidence: ${matchResult.confidence}%` });
-                        }
-                        catch (err) {
-                            this.recordLLMFailure();
-                            logger.warn(`LLM call failed — falling back to keyword: ${err}`);
-                            steps.push({ type: 'llm_match', status: 'fail', durationMs: Date.now() - t2, detail: String(err) });
-                            matchResult = keywordResult;
-                        }
-                    }
-                }
-                break;
-            }
-        }
-        const preBoostMatchResult = matchResult;
+        let { matchResult, resolvedVia } = await this._runMatch(query, steps);
+        const preBoostMatchResult = matchResult; // kept for learning recording only — prevents feedback loop
         // ── Step 2.5: Apply learning boost ───────────────────────────────────────
-        if (matchResult.candidates.length > 0 && this.learning && this.mode !== 'cheap') {
-            const boosted = await this.applyLearningBoost(query, matchResult.candidates);
-            if (boosted.length > 0) {
-                const newWinner = boosted.reduce((a, b) => a.score > b.score ? a : b);
-                const oldWinner = matchResult.candidates.find(c => c.matched);
-                if (newWinner.capabilityId !== oldWinner?.capabilityId && newWinner.score >= this.threshold) {
-                    // Boost changed the winner — re-extract params for the new capability
-                    const newCap = this.manifest.capabilities.find(c => c.id === newWinner.capabilityId) ?? null;
-                    const newParams = newCap ? _match(query, { ...this.manifest, capabilities: [newCap] }).extractedParams : {};
-                    matchResult = {
-                        ...matchResult,
-                        capability: newCap,
-                        confidence: newWinner.score,
-                        intent: newCap ? resolverToIntent(newCap) : 'out_of_scope',
-                        extractedParams: newParams,
-                        candidates: boosted.map(c => ({ ...c, matched: c.capabilityId === newWinner.capabilityId })),
-                        reasoning: `Matched "${newWinner.capabilityId}" via learning boost (score: ${newWinner.score})`,
-                    };
-                    logger.info(`Learning boost changed winner: "${oldWinner?.capabilityId ?? 'none'}" → "${newWinner.capabilityId}"`);
-                }
-                else {
-                    // Same winner — update scores only
-                    matchResult = {
-                        ...matchResult,
-                        confidence: newWinner.score,
-                        candidates: boosted.map(c => ({ ...c, matched: c.capabilityId === (oldWinner?.capabilityId ?? '') })),
-                    };
-                }
-            }
-        }
+        matchResult = await this.applyBoostToMatchResult(query, matchResult);
         // ── Step 3: Privacy check ────────────────────────────────────────────────
         if (matchResult.capability) {
             const privacyLevel = matchResult.capability.privacy.level;
@@ -214,10 +108,13 @@ export class CapmanEngine {
                 detail: `level: ${privacyLevel}`,
             });
         }
-        // ── Step 4: Cache the match result ───────────────────────────────────────
-        if (this.cache && preBoostMatchResult.capability) {
+        // ── Step 4: Cache the match result (public capabilities only) ─────────────
+        // Non-public capabilities are never cached — prevents auth bypass where
+        // User A's cached match is served to User B without privacy enforcement.
+        if (this.cache && matchResult.capability
+            && matchResult.capability.privacy.level === 'public') {
             const queryKey = normalizeQuery(query);
-            await this.cache.set(queryKey, preBoostMatchResult);
+            await this.cache.set(queryKey, matchResult);
         }
         // ── Step 5: Resolve ──────────────────────────────────────────────────────
         const resolveStart = Date.now();
@@ -254,7 +151,10 @@ export class CapmanEngine {
             reasoning.push(matchResult.reasoning);
         }
         // ── Step 7: Record learning ──────────────────────────────────────────────
-        await this.recordLearning(query, matchResult, resolvedVia);
+        // Record the pre-boost match result — not the boosted one.
+        // Recording the boosted winner would reinforce it further on every call,
+        // creating a feedback loop that permanently displaces keyword matches.
+        await this.recordLearning(query, preBoostMatchResult, resolvedVia);
         const trace = {
             query,
             candidates: matchResult.candidates,
@@ -314,91 +214,11 @@ export class CapmanEngine {
      */
     async explain(query) {
         const start = Date.now();
-        // ── Match — mirrors ask() logic including rate limiting ───────────────────
-        let matchResult;
-        let resolvedVia = 'keyword';
-        if (this.mode === 'accurate') {
-            if (this.llm) {
-                const skipReason = this.checkLLMAllowed();
-                if (skipReason) {
-                    logger.warn(`explain(): LLM skipped — ${skipReason} — falling back to keyword`);
-                    matchResult = _match(query, this.manifest);
-                }
-                else {
-                    try {
-                        matchResult = await _matchWithLLM(query, this.manifest, { llm: this.llm });
-                        this.recordLLMSuccess();
-                        resolvedVia = 'llm';
-                    }
-                    catch (err) {
-                        this.recordLLMFailure();
-                        logger.warn(`explain(): LLM call failed — falling back to keyword: ${err}`);
-                        matchResult = _match(query, this.manifest);
-                    }
-                }
-            }
-            else {
-                matchResult = _match(query, this.manifest);
-            }
-        }
-        else if (this.mode === 'balanced' && this.llm) {
-            // Keyword first — escalate to LLM if low confidence (same as ask())
-            const keywordResult = _match(query, this.manifest);
-            if (keywordResult.confidence >= this.threshold) {
-                matchResult = keywordResult;
-            }
-            else {
-                const skipReason = this.checkLLMAllowed();
-                if (skipReason) {
-                    logger.warn(`explain(): LLM skipped — ${skipReason}`);
-                    matchResult = keywordResult;
-                }
-                else {
-                    try {
-                        matchResult = await _matchWithLLM(query, this.manifest, { llm: this.llm });
-                        this.recordLLMSuccess();
-                        resolvedVia = 'llm';
-                    }
-                    catch (err) {
-                        this.recordLLMFailure();
-                        logger.warn(`explain(): LLM call failed — falling back to keyword: ${err}`);
-                        matchResult = keywordResult;
-                    }
-                }
-            }
-        }
-        else {
-            // cheap mode or no llm — keyword only
-            matchResult = _match(query, this.manifest);
-        }
+        // ── Match — shared with ask() via _runMatch() ─────────────────────────────
+        let { matchResult, resolvedVia: _resolvedVia } = await this._runMatch(query);
+        let resolvedVia = _resolvedVia;
         // ── Apply learning boost (same as ask()) ─────────────────────────────────
-        if (matchResult.candidates.length > 0 && this.learning && this.mode !== 'cheap') {
-            const boosted = await this.applyLearningBoost(query, matchResult.candidates);
-            if (boosted.length > 0) {
-                const newWinner = boosted.reduce((a, b) => a.score > b.score ? a : b);
-                const oldWinner = matchResult.candidates.find(c => c.matched);
-                if (newWinner.capabilityId !== oldWinner?.capabilityId && newWinner.score >= this.threshold) {
-                    const newCap = this.manifest.capabilities.find(c => c.id === newWinner.capabilityId) ?? null;
-                    const newParams = newCap ? _match(query, { ...this.manifest, capabilities: [newCap] }).extractedParams : {};
-                    matchResult = {
-                        ...matchResult,
-                        capability: newCap,
-                        confidence: newWinner.score,
-                        intent: newCap ? resolverToIntent(newCap) : 'out_of_scope',
-                        extractedParams: newParams,
-                        candidates: boosted.map(c => ({ ...c, matched: c.capabilityId === newWinner.capabilityId })),
-                        reasoning: `Matched "${newWinner.capabilityId}" via learning boost (score: ${newWinner.score})`,
-                    };
-                }
-                else {
-                    matchResult = {
-                        ...matchResult,
-                        confidence: newWinner.score,
-                        candidates: boosted.map(c => ({ ...c, matched: c.capabilityId === (oldWinner?.capabilityId ?? '') })),
-                    };
-                }
-            }
-        }
+        matchResult = await this.applyBoostToMatchResult(query, matchResult);
         // ── Build candidate explanations ─────────────────────────────────────────
         const candidates = matchResult.candidates
             .sort((a, b) => b.score - a.score)
@@ -582,6 +402,137 @@ export class CapmanEngine {
             logger.warn(`LLM circuit breaker opened after ${this.llmConsecutiveFails} consecutive failures — pausing for ${this.llmCircuitBreakerResetMs / 1000}s`);
         }
     }
+    /**
+     * Runs the matching pipeline for a query — shared by ask() and explain().
+     * Handles cheap / balanced / accurate mode dispatch and LLM rate limiting.
+     * Returns the match result and which resolver was used.
+     */
+    async _runMatch(query, steps) {
+        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 skipReason = this.checkLLMAllowed();
+                    if (skipReason) {
+                        logger.warn(`LLM skipped — ${skipReason} — 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 skipped: ${skipReason}` });
+                    }
+                    else {
+                        const t = Date.now();
+                        try {
+                            matchResult = await _matchWithLLM(query, this.manifest, { llm: this.llm });
+                            this.recordLLMSuccess();
+                            resolvedVia = 'llm';
+                            steps?.push({ type: 'llm_match', status: 'pass', durationMs: Date.now() - t, detail: `confidence: ${matchResult.confidence}%` });
+                        }
+                        catch (err) {
+                            const isParseError = String(err).startsWith('LLM_PARSE_ERROR');
+                            if (!isParseError)
+                                this.recordLLMFailure();
+                            logger.warn(`LLM call failed — falling back to keyword: ${err instanceof Error ? err.message : String(err)}`);
+                            const t2 = Date.now();
+                            matchResult = _match(query, this.manifest);
+                            steps?.push({ type: 'llm_match', status: 'fail', durationMs: Date.now() - t, detail: String(err) });
+                            steps?.push({ type: 'keyword_match', status: 'pass', durationMs: Date.now() - t2, detail: 'fallback after llm failure' });
+                        }
+                    }
+                }
+                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 {
+                    const skipReason = this.checkLLMAllowed();
+                    if (skipReason) {
+                        logger.warn(`LLM skipped — ${skipReason}`);
+                        steps?.push({ type: 'llm_match', status: 'skip', durationMs: 0, detail: skipReason });
+                        matchResult = keywordResult;
+                    }
+                    else {
+                        logger.info(`Low confidence (${keywordResult.confidence}%) — escalating to LLM`);
+                        const t2 = Date.now();
+                        try {
+                            matchResult = await _matchWithLLM(query, this.manifest, { llm: this.llm });
+                            this.recordLLMSuccess();
+                            resolvedVia = 'llm';
+                            steps?.push({ type: 'llm_match', status: 'pass', durationMs: Date.now() - t2, detail: `confidence: ${matchResult.confidence}%` });
+                        }
+                        catch (err) {
+                            const isParseError = String(err).startsWith('LLM_PARSE_ERROR');
+                            if (!isParseError)
+                                this.recordLLMFailure();
+                            logger.warn(`LLM call failed — falling back to keyword: ${err instanceof Error ? err.message : String(err)}`);
+                            steps?.push({ type: 'llm_match', status: 'fail', durationMs: Date.now() - t2, detail: String(err) });
+                            matchResult = keywordResult;
+                        }
+                    }
+                }
+                break;
+            }
+        }
+        return { matchResult: matchResult, resolvedVia };
+    }
+    /**
+     * Applies learning boost to a MatchResult and returns the updated result.
+     * Shared by ask() and explain() to avoid logic divergence.
+     */
+    async applyBoostToMatchResult(query, matchResult) {
+        const hasKeywordSignal = matchResult.candidates.some(c => c.score > 0);
+        if (!hasKeywordSignal || matchResult.candidates.length === 0 || !this.learning || this.mode === 'cheap') {
+            return matchResult;
+        }
+        const boosted = await this.applyLearningBoost(query, matchResult.candidates);
+        if (boosted.length === 0)
+            return matchResult;
+        const newWinner = boosted.reduce((a, b) => {
+            if (b.score > a.score)
+                return b;
+            if (b.score === a.score && b.matched)
+                return b; // original winner wins ties
+            return a;
+        });
+        const oldWinner = matchResult.candidates.find(c => c.matched);
+        if (newWinner.capabilityId !== oldWinner?.capabilityId && newWinner.score >= this.threshold) {
+            const newCap = this.manifest.capabilities.find(c => c.id === newWinner.capabilityId) ?? null;
+            const newParams = newCap ? extractParams(query, newCap) : {};
+            logger.info(`Learning boost changed winner: "${oldWinner?.capabilityId ?? 'none'}" → "${newWinner.capabilityId}"`);
+            return {
+                ...matchResult,
+                capability: newCap,
+                confidence: newWinner.score,
+                intent: newCap ? resolverToIntent(newCap) : 'out_of_scope',
+                extractedParams: newParams,
+                candidates: boosted.map(c => ({ ...c, matched: c.capabilityId === newWinner.capabilityId })),
+                reasoning: `Matched "${newWinner.capabilityId}" via learning boost (score: ${newWinner.score})`,
+            };
+        }
+        return {
+            ...matchResult,
+            confidence: newWinner.score,
+            candidates: boosted.map(c => ({ ...c, matched: c.capabilityId === (oldWinner?.capabilityId ?? '') })),
+        };
+    }
     /**
      * Applies learning boost to match candidates based on historical usage.
      * Capabilities that have previously matched similar keywords get a small
@@ -591,14 +542,10 @@ export class CapmanEngine {
         if (!this.learning)
             return candidates;
         // Use cached stats — rebuilt only when new entries recorded
-        if (this.statsInvalidated) {
-            this.cachedStats = await this.learning.getStats();
-            this.statsInvalidated = false;
-        }
-        const stats = this.cachedStats;
+        const stats = await this.learning.getStats();
         if (!stats || Object.keys(stats.index).length === 0)
             return candidates;
-        const qWords = query.toLowerCase().split(/\W+/).filter(w => w.length > 2);
+        const qWords = query.toLowerCase().split(/\W+/).filter(w => w.length > 2 && !STOPWORDS.has(w));
         if (qWords.length === 0)
             return candidates;
         return candidates.map(candidate => {
@@ -645,6 +592,5 @@ export class CapmanEngine {
             resolvedVia,
             timestamp: new Date().toISOString(),
         });
-        this.statsInvalidated = true;
     }
 }

package/dist/esm/index.d.ts

@@ -2,7 +2,7 @@ export { setLogLevel } from './logger';
 export type { LogLevel } from './logger';
 export type { Capability, CapabilityParam, CapmanConfig, Manifest, MatchResult, ExecutionTrace, TraceStep, MatchCandidate, ResolveResult, ApiCallResult, ValidationResult, Resolver, ApiResolver, NavResolver, HybridResolver, PrivacyScope, ResolverType, HttpMethod, ExplainResult, ExplainCandidate, } from './types';
 export { generate, loadConfig, writeManifest, readManifest, validate, generateStarterConfig, } from './generator';
-export { match, matchWithLLM, } from './matcher';
+export { match, matchWithLLM, extractParams, } from './matcher';
 export type { LLMMatcherOptions } from './matcher';
 export { resolve } from './resolver';
 export type { ResolveOptions, AuthContext } from './resolver';

package/dist/esm/index.js

@@ -1,6 +1,6 @@
 export { setLogLevel } from './logger';
 export { generate, loadConfig, writeManifest, readManifest, validate, generateStarterConfig, } from './generator';
-export { match, matchWithLLM, } from './matcher';
+export { match, matchWithLLM, extractParams, } from './matcher';
 export { resolve } from './resolver';
 // ─── Engine (recommended API) ─────────────────────────────────────────────────
 export { CapmanEngine } from './engine';

package/dist/esm/learning.d.ts

@@ -26,17 +26,26 @@ export interface LearningStore {
         id: string;
         hits: number;
     }>>;
-    clear(): Promise<void>;
+    /** Returns the live keyword index without rebuilding — O(1) */
+    getIndex(): Promise<Record<string, Record<string, number>>>;
 }
 export declare class FileLearningStore implements LearningStore {
     private filePath;
     private entries;
     private loaded;
+    private saveQueue;
+    private index;
+    private statsCounter;
     constructor(filePath?: string);
+    private updateIndex;
+    private subtractFromIndex;
+    private rebuildIndex;
     private load;
     private save;
+    private _doSave;
     record(entry: LearningEntry): Promise<void>;
     getStats(): Promise<KeywordStats>;
+    getIndex(): Promise<Record<string, Record<string, number>>>;
     getTopCapabilities(limit?: number): Promise<Array<{
         id: string;
         hits: number;
@@ -45,8 +54,14 @@ export declare class FileLearningStore implements LearningStore {
 }
 export declare class MemoryLearningStore implements LearningStore {
     private entries;
+    private index;
+    private statsCounter;
     record(entry: LearningEntry): Promise<void>;
     getStats(): Promise<KeywordStats>;
+    getIndex(): Promise<Record<string, Record<string, number>>>;
+    private updateIndex;
+    private subtractFromIndex;
+    private rebuildIndex;
     getTopCapabilities(limit?: number): Promise<Array<{
         id: string;
         hits: number;