capman 0.5.0 → 0.5.2

package/dist/esm/engine.js

@@ -1,4 +1,4 @@
-import { match as _match, matchWithLLM as _matchWithLLM, resolverToIntent, extractParams, STOPWORDS } from './matcher';
+import { match as _match, matchWithLLM as _matchWithLLM, resolverToIntent, extractParams, STOPWORDS, LLMParseError } from './matcher';
 import { resolve as _resolve } from './resolver';
 import { MemoryLearningStore } from './learning';
 import { logger } from './logger';
@@ -20,10 +20,11 @@ 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;
-        this.llmCircuitBreakerResetMs = options.llmCircuitBreakerResetMs ?? 60000;
+        this.llmCircuitBreakerResetMs = options.llmCircuitBreakerResetMs ?? 60_000;
         // Cache — default MemoryCache (no filesystem writes), or disabled with false
         // Use FileCache or ComboCache explicitly for persistence across restarts
         this.cache = options.cache === false
@@ -36,14 +37,14 @@ export class CapmanEngine {
             : (options.learning ?? new MemoryLearningStore());
         logger.info(`CapmanEngine initialized — mode: ${this.mode}, cache: ${this.cache ? 'enabled' : 'disabled'}, learning: ${this.learning ? 'enabled' : 'disabled'}`);
         // ── Manifest version compatibility check ─────────────────────────────────
-        const manifestMajorMinor = options.manifest.version?.split('.').slice(0, 2).join('.');
-        const engineMajorMinor = VERSION.split('.').slice(0, 2).join('.');
-        if (manifestMajorMinor && manifestMajorMinor !== engineMajorMinor) {
-            // 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`);
+        if (options.manifest.version) {
+            const [mMaj, mMin] = options.manifest.version.split('.').map(Number);
+            const [eMaj, eMin] = VERSION.split('.').map(Number);
+            if (mMaj !== eMaj || mMin !== eMin) {
+                console.warn(`[capman] Manifest version "${options.manifest.version}" was generated with a ` +
+                    `different engine version than "${VERSION}". This is usually fine across patch versions. ` +
+                    `If you experience unexpected matching issues, regenerate with: npx capman generate`);
+            }
         }
     }
     /**
@@ -58,18 +59,34 @@ export class CapmanEngine {
      * console.log(result.resolvedVia)           // 'keyword' | 'llm' | 'cache'
      */
     async ask(query, overrides = {}) {
+        if (!query || typeof query !== 'string') {
+            throw new TypeError('query must be a non-empty string');
+        }
+        if (query.length > CapmanEngine.MAX_QUERY_LENGTH) {
+            throw new RangeError(`query exceeds maximum length of ${CapmanEngine.MAX_QUERY_LENGTH} characters`);
+        }
         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}"`);
-                const resolution = await _resolve(cached.result, cached.result.extractedParams, this.resolveOptions(overrides));
+                // Re-extract params from the current query — never re-use cached params.
+                // Cached params belong to the original query (potentially from a different user).
+                // e.g. User A: "show orders for john" → cached with { customer: 'john' }
+                //      User B: "show orders for jane" → must get { customer: 'jane' }, not john's
+                const freshParams = cached.result.capability
+                    ? extractParams(query, cached.result.capability)
+                    : {};
+                const matchWithFreshParams = {
+                    ...cached.result,
+                    extractedParams: freshParams,
+                };
+                const resolution = await _resolve(matchWithFreshParams, freshParams, this.resolveOptions(overrides));
                 const trace = {
                     query,
                     candidates: cached.result.candidates,
@@ -79,13 +96,13 @@ export class CapmanEngine {
                     totalMs: Date.now() - start,
                 };
                 const result = {
-                    match: cached.result,
+                    match: matchWithFreshParams,
                     resolution,
                     resolvedVia: 'cache',
                     durationMs: Date.now() - start,
                     trace,
                 };
-                await this.recordLearning(query, cached.result, 'cache');
+                await this.recordLearning(query, matchWithFreshParams, 'cache');
                 return result;
             }
             steps.push({ type: 'cache_check', status: 'miss', durationMs: Date.now() - cacheStart });
@@ -94,88 +111,7 @@ 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) {
-                            const isParseError = String(err).startsWith('LLM_PARSE_ERROR');
-                            if (!isParseError)
-                                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) {
-                            const isParseError = String(err).startsWith('LLM_PARSE_ERROR');
-                            if (!isParseError)
-                                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;
-            }
-        }
+        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 ───────────────────────────────────────
         matchResult = await this.applyBoostToMatchResult(query, matchResult);
@@ -294,68 +230,16 @@ export class CapmanEngine {
      * console.log(explanation.candidates)
      */
     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) {
-                        const isParseError = String(err).startsWith('LLM_PARSE_ERROR');
-                        if (!isParseError)
-                            this.recordLLMFailure();
-                        logger.warn(`LLM call failed — falling back to keyword: ${err}`);
-                        matchResult = _match(query, this.manifest);
-                    }
-                }
-            }
-            else {
-                matchResult = _match(query, this.manifest);
-            }
+        if (!query || typeof query !== 'string') {
+            throw new TypeError('query must be a non-empty string');
         }
-        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) {
-                        const isParseError = String(err).startsWith('LLM_PARSE_ERROR');
-                        if (!isParseError)
-                            this.recordLLMFailure();
-                        logger.warn(`LLM call failed — falling back to keyword: ${err}`);
-                        matchResult = keywordResult;
-                    }
-                }
-            }
-        }
-        else {
-            // cheap mode or no llm — keyword only
-            matchResult = _match(query, this.manifest);
+        if (query.length > CapmanEngine.MAX_QUERY_LENGTH) {
+            throw new RangeError(`query exceeds maximum length of ${CapmanEngine.MAX_QUERY_LENGTH} characters`);
         }
+        const start = Date.now();
+        // ── Match — shared with ask() via _runMatch() ─────────────────────────────
+        let { matchResult, resolvedVia: _resolvedVia } = await this._runMatch(query);
+        let resolvedVia = _resolvedVia;
         // ── Apply learning boost (same as ask()) ─────────────────────────────────
         matchResult = await this.applyBoostToMatchResult(query, matchResult);
         // ── Build candidate explanations ─────────────────────────────────────────
@@ -400,12 +284,17 @@ export class CapmanEngine {
         }
         reasoning.push(`Resolved via: ${resolvedVia}`);
         if (matchResult.extractedParams && Object.keys(matchResult.extractedParams).length) {
-            const params = Object.entries(matchResult.extractedParams)
+            const extracted = Object.entries(matchResult.extractedParams)
                 .filter(([, v]) => v !== null)
                 .map(([k, v]) => `${k}=${v}`)
                 .join(', ');
-            if (params)
-                reasoning.push(`Would extract params: ${params}`);
+            const session = matchResult.capability?.params
+                .filter(p => p.source === 'session')
+                .map(p => `${p.name}=[from auth]`)
+                .join(', ');
+            const parts = [extracted, session].filter(Boolean).join(', ');
+            if (parts)
+                reasoning.push(`Would extract params: ${parts}`);
         }
         // ── Build wouldExecute ───────────────────────────────────────────────────
         const cap = matchResult.capability;
@@ -438,7 +327,7 @@ export class CapmanEngine {
                     let path = endpoint.path;
                     for (const [k, v] of Object.entries(params)) {
                         if (v)
-                            path = path.replace(`{${k}}`, v);
+                            path = path.replaceAll(`{${k}}`, v);
                     }
                     const base = this.baseUrl ?? '';
                     action = `${endpoint.method} ${base}${path}`;
@@ -447,7 +336,7 @@ export class CapmanEngine {
                     let dest = cap.resolver.destination;
                     for (const [k, v] of Object.entries(params)) {
                         if (v)
-                            dest = dest.replace(`{${k}}`, v);
+                            dest = dest.replaceAll(`{${k}}`, v);
                     }
                     action = `navigate → ${dest}`;
                 }
@@ -457,12 +346,12 @@ export class CapmanEngine {
                     let path = endpoint.path;
                     for (const [k, v] of Object.entries(params)) {
                         if (v)
-                            path = path.replace(`{${k}}`, v);
+                            path = path.replaceAll(`{${k}}`, v);
                     }
                     let dest = hybrid.nav.destination;
                     for (const [k, v] of Object.entries(params)) {
                         if (v)
-                            dest = dest.replace(`{${k}}`, v);
+                            dest = dest.replaceAll(`{${k}}`, v);
                     }
                     const base = this.baseUrl ?? '';
                     action = `${endpoint.method} ${base}${path} + navigate → ${dest}`;
@@ -511,13 +400,13 @@ export class CapmanEngine {
         }
         // ── Per-minute rate limit ────────────────────────────────────────────────
         const windowElapsed = now - this.llmWindowStart;
-        if (windowElapsed >= 60000) {
+        if (windowElapsed >= 60_000) {
             this.llmCallsThisMinute = 0;
             this.llmWindowStart = now;
         }
         if (this.llmCallsThisMinute >= this.maxLLMCallsPerMinute) {
             // Recalculate elapsed after possible window reset above
-            const resetIn = Math.ceil((60000 - (now - this.llmWindowStart)) / 1000);
+            const resetIn = Math.ceil((60_000 - (now - this.llmWindowStart)) / 1000);
             return `rate limit reached (${this.maxLLMCallsPerMinute}/min) — resets in ${Math.max(0, resetIn)}s`;
         }
         // Reserve the slot atomically before the call happens
@@ -541,6 +430,118 @@ 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';
+                            // Merge keyword scores into LLM candidates so boost has real signal for alternatives
+                            const kwResult = _match(query, this.manifest);
+                            matchResult = {
+                                ...matchResult,
+                                candidates: matchResult.candidates.map(c => ({
+                                    ...c,
+                                    score: c.matched
+                                        ? c.score // keep LLM confidence for winner
+                                        : (kwResult.candidates.find(kc => kc.capabilityId === c.capabilityId)?.score ?? 0),
+                                })),
+                            };
+                            steps?.push({ type: 'llm_match', status: 'pass', durationMs: Date.now() - t, detail: `confidence: ${matchResult.confidence}%` });
+                        }
+                        catch (err) {
+                            const isParseError = err instanceof LLMParseError;
+                            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';
+                            // keywordResult already computed above in balanced mode — merge scores
+                            matchResult = {
+                                ...matchResult,
+                                candidates: matchResult.candidates.map(c => ({
+                                    ...c,
+                                    score: c.matched
+                                        ? c.score
+                                        : (keywordResult.candidates.find(kc => kc.capabilityId === c.capabilityId)?.score ?? 0),
+                                })),
+                            };
+                            steps?.push({ type: 'llm_match', status: 'pass', durationMs: Date.now() - t2, detail: `confidence: ${matchResult.confidence}%` });
+                        }
+                        catch (err) {
+                            const isParseError = err instanceof LLMParseError;
+                            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.
@@ -642,3 +643,5 @@ export class CapmanEngine {
         });
     }
 }
+/** Maximum allowed query length in characters. Queries exceeding this throw RangeError. */
+CapmanEngine.MAX_QUERY_LENGTH = 1000;

package/dist/esm/index.d.ts

@@ -3,6 +3,7 @@ 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, extractParams, } from './matcher';
+export { LLMParseError } from './matcher';
 export type { LLMMatcherOptions } from './matcher';
 export { resolve } from './resolver';
 export type { ResolveOptions, AuthContext } from './resolver';
@@ -14,10 +15,10 @@ export { FileLearningStore, MemoryLearningStore } from './learning';
 export type { LearningStore, LearningEntry, KeywordStats } from './learning';
 export { parseOpenAPI } from './parser';
 export type { ParseResult } from './parser';
-import type { Manifest, MatchResult, ResolveResult } from './types';
+import type { Manifest, MatchResult, ResolveResult, MatchMode } from './types';
 import type { LLMMatcherOptions } from './matcher';
 import type { ResolveOptions } from './resolver';
-export type MatchMode = 'cheap' | 'balanced' | 'accurate';
+export type { MatchMode } from './types';
 export interface AskOptions extends ResolveOptions {
     llm?: LLMMatcherOptions['llm'];
     /**

package/dist/esm/index.js

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

package/dist/esm/learning.d.ts

@@ -38,6 +38,7 @@ export declare class FileLearningStore implements LearningStore {
     private statsCounter;
     constructor(filePath?: string);
     private updateIndex;
+    private subtractFromIndex;
     private rebuildIndex;
     private load;
     private save;
@@ -59,7 +60,7 @@ export declare class MemoryLearningStore implements LearningStore {
     getStats(): Promise<KeywordStats>;
     getIndex(): Promise<Record<string, Record<string, number>>>;
     private updateIndex;
-    private rebuildIndex;
+    private subtractFromIndex;
     getTopCapabilities(limit?: number): Promise<Array<{
         id: string;
         hits: number;