capman 0.5.0 → 0.5.1

package/dist/esm/engine.js

@@ -20,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;
@@ -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,88 +94,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);
@@ -295,67 +214,9 @@ 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) {
-                        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);
-            }
-        }
-        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);
-        }
+        // ── 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 ─────────────────────────────────────────
@@ -541,6 +402,97 @@ 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.

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,6 +60,7 @@ export declare class MemoryLearningStore implements LearningStore {
     getStats(): Promise<KeywordStats>;
     getIndex(): Promise<Record<string, Record<string, number>>>;
     private updateIndex;
+    private subtractFromIndex;
     private rebuildIndex;
     getTopCapabilities(limit?: number): Promise<Array<{
         id: string;

package/dist/esm/learning.js

@@ -78,6 +78,37 @@ export class FileLearningStore {
             }
         }
     }
+    subtractFromIndex(entry) {
+        if (!entry.capabilityId) {
+            this.statsCounter.outOfScope = Math.max(0, this.statsCounter.outOfScope - 1);
+            this.statsCounter.totalQueries = Math.max(0, this.statsCounter.totalQueries - 1);
+            if (entry.resolvedVia === 'llm')
+                this.statsCounter.llmQueries = Math.max(0, this.statsCounter.llmQueries - 1);
+            if (entry.resolvedVia === 'cache')
+                this.statsCounter.cacheHits = Math.max(0, this.statsCounter.cacheHits - 1);
+            return;
+        }
+        this.statsCounter.totalQueries = Math.max(0, this.statsCounter.totalQueries - 1);
+        if (entry.resolvedVia === 'llm')
+            this.statsCounter.llmQueries = Math.max(0, this.statsCounter.llmQueries - 1);
+        if (entry.resolvedVia === 'cache')
+            this.statsCounter.cacheHits = Math.max(0, this.statsCounter.cacheHits - 1);
+        const words = entry.query.toLowerCase()
+            .split(/\W+/)
+            .filter(w => w.length > 2 && !STOPWORDS.has(w));
+        for (const word of words) {
+            if (!this.index[word])
+                continue;
+            this.index[word][entry.capabilityId] =
+                (this.index[word][entry.capabilityId] ?? 1) - 1;
+            if (this.index[word][entry.capabilityId] <= 0) {
+                delete this.index[word][entry.capabilityId];
+            }
+            if (Object.keys(this.index[word]).length === 0) {
+                delete this.index[word];
+            }
+        }
+    }
     rebuildIndex() {
         this.index = {};
         this.statsCounter = { totalQueries: 0, llmQueries: 0, cacheHits: 0, outOfScope: 0 };
@@ -128,9 +159,11 @@ export class FileLearningStore {
         this.updateIndex(entry);
         if (this.entries.length > MAX_LEARNING_ENTRIES) {
             const excess = this.entries.length - MAX_LEARNING_ENTRIES;
-            this.entries.splice(0, excess);
-            // Rebuild index after pruning — pruned entries may have affected counts
-            this.rebuildIndex();
+            const pruned = this.entries.splice(0, excess);
+            // Subtract pruned entries from index — O(pruned × w) instead of O(n × w) full rebuild
+            for (const entry of pruned) {
+                this.subtractFromIndex(entry);
+            }
             logger.debug(`Learning store pruned ${excess} oldest entries (cap: ${MAX_LEARNING_ENTRIES})`);
         }
         await this.save();
@@ -167,8 +200,11 @@ export class MemoryLearningStore {
         this.entries.push(entry);
         this.updateIndex(entry);
         if (this.entries.length > MAX_LEARNING_ENTRIES) {
-            this.entries.splice(0, this.entries.length - MAX_LEARNING_ENTRIES);
-            this.rebuildIndex();
+            const excess = this.entries.length - MAX_LEARNING_ENTRIES;
+            const pruned = this.entries.splice(0, excess);
+            for (const entry of pruned) {
+                this.subtractFromIndex(entry);
+            }
         }
     }
     async getStats() {
@@ -197,6 +233,37 @@ export class MemoryLearningStore {
             }
         }
     }
+    subtractFromIndex(entry) {
+        if (!entry.capabilityId) {
+            this.statsCounter.outOfScope = Math.max(0, this.statsCounter.outOfScope - 1);
+            this.statsCounter.totalQueries = Math.max(0, this.statsCounter.totalQueries - 1);
+            if (entry.resolvedVia === 'llm')
+                this.statsCounter.llmQueries = Math.max(0, this.statsCounter.llmQueries - 1);
+            if (entry.resolvedVia === 'cache')
+                this.statsCounter.cacheHits = Math.max(0, this.statsCounter.cacheHits - 1);
+            return;
+        }
+        this.statsCounter.totalQueries = Math.max(0, this.statsCounter.totalQueries - 1);
+        if (entry.resolvedVia === 'llm')
+            this.statsCounter.llmQueries = Math.max(0, this.statsCounter.llmQueries - 1);
+        if (entry.resolvedVia === 'cache')
+            this.statsCounter.cacheHits = Math.max(0, this.statsCounter.cacheHits - 1);
+        const words = entry.query.toLowerCase()
+            .split(/\W+/)
+            .filter(w => w.length > 2 && !STOPWORDS.has(w));
+        for (const word of words) {
+            if (!this.index[word])
+                continue;
+            this.index[word][entry.capabilityId] =
+                (this.index[word][entry.capabilityId] ?? 1) - 1;
+            if (this.index[word][entry.capabilityId] <= 0) {
+                delete this.index[word][entry.capabilityId];
+            }
+            if (Object.keys(this.index[word]).length === 0) {
+                delete this.index[word];
+            }
+        }
+    }
     rebuildIndex() {
         this.index = {};
         this.statsCounter = { totalQueries: 0, llmQueries: 0, cacheHits: 0, outOfScope: 0 };

package/dist/esm/matcher.d.ts

@@ -16,4 +16,15 @@ export declare function match(query: string, manifest: Manifest): MatchResult;
 export interface LLMMatcherOptions {
     llm: (prompt: string) => Promise<string>;
 }
+/**
+ * Matches a query to a capability using an LLM.
+ *
+ * ⚠️  SECURITY NOTE: Capability `description` and `examples` fields from the
+ * manifest are injected verbatim into the LLM prompt (system portion).
+ * In a solo deployment with a developer-controlled manifest this is safe.
+ * If your manifest is generated from third-party OpenAPI specs, user-controlled
+ * sources, or any external input, sanitize `description` and `examples` fields
+ * before passing the manifest to this function — adversarial content in those
+ * fields can influence LLM routing decisions.
+ */
 export declare function matchWithLLM(query: string, manifest: Manifest, options: LLMMatcherOptions): Promise<MatchResult>;

package/dist/esm/matcher.js

@@ -117,10 +117,11 @@ export function extractParams(query, cap) {
             const words = query.trim().split(/\s+/);
             const meaningful = words.filter(w => !STOPWORDS.has(w.toLowerCase()));
             const candidate = meaningful[meaningful.length - 1] ?? null;
-            // Only use fallback if candidate looks like an identifier — not a generic noun or verb
+            // Only use fallback if candidate looks like an identifier — not a generic noun, verb,
+            // or category word that would produce junk URLs like /orders/orders or /users/data
             if (candidate &&
                 /^[a-zA-Z0-9_-]{2,}$/.test(candidate) &&
-                !/^(all|new|latest|recent|current|list|get|show|find|fetch|give|open|my|their|your)$/i.test(candidate)) {
+                !/^(all|new|latest|recent|current|list|get|show|find|fetch|give|open|my|their|your|orders|order|items|item|data|results|result|records|record|entries|entry|users|user|products|product|details|info|summary|history|status|feed|content|files|file|documents|document)$/i.test(candidate)) {
                 extracted = candidate;
             }
         }
@@ -184,6 +185,17 @@ export function match(query, manifest) {
         candidates,
     };
 }
+/**
+ * Matches a query to a capability using an LLM.
+ *
+ * ⚠️  SECURITY NOTE: Capability `description` and `examples` fields from the
+ * manifest are injected verbatim into the LLM prompt (system portion).
+ * In a solo deployment with a developer-controlled manifest this is safe.
+ * If your manifest is generated from third-party OpenAPI specs, user-controlled
+ * sources, or any external input, sanitize `description` and `examples` fields
+ * before passing the manifest to this function — adversarial content in those
+ * fields can influence LLM routing decisions.
+ */
 export async function matchWithLLM(query, manifest, options) {
     const manifestSummary = manifest.capabilities.map(c => `- ${c.id} (${c.resolver.type}): ${c.description}${c.examples?.length ? `\n  examples: ${c.examples.slice(0, 2).join(', ')}` : ''}`).join('\n');
     const prompt = `You are an intent matcher for an AI agent system.

package/dist/esm/parser.js

@@ -10,7 +10,21 @@ async function loadSpec(source) {
     // URL
     if (source.startsWith('http://') || source.startsWith('https://')) {
         logger.info(`Fetching OpenAPI spec from: ${source}`);
-        const res = await fetch(source);
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 10000);
+        // eslint-disable-next-line prefer-const
+        let res;
+        try {
+            res = await fetch(source, { signal: controller.signal });
+            clearTimeout(timer);
+        }
+        catch (err) {
+            clearTimeout(timer);
+            if (err instanceof Error && err.name === 'AbortError') {
+                throw new Error(`Timed out fetching spec from ${source} (10s limit)`);
+            }
+            throw err;
+        }
         if (!res.ok)
             throw new Error(`Failed to fetch spec: ${res.status} ${res.statusText}`);
         const text = await res.text();

package/dist/esm/resolver.js

@@ -44,11 +44,17 @@ export async function resolve(matchResult, params = {}, options = {}) {
         };
     }
     // ── Session param injection ───────────────────────────────────────────────
-    // Inject auth.userId into any params marked as source: 'session'
+    // Inject auth.userId into params marked as source: 'session'
+    // Session params are only injected if they appear as {template} in the path —
+    // they must never leak into the query string as ?user_id=xyz
     const enrichedParams = { ...params };
     if (options.auth?.userId !== undefined && options.auth.userId !== '') {
+        const resolver = capability.resolver;
+        const pathTemplate = resolver.type === 'api' ? resolver.endpoints.map(e => e.path).join('') :
+            resolver.type === 'hybrid' ? resolver.api.endpoints.map(e => e.path).join('') :
+                resolver.type === 'nav' ? resolver.destination : '';
         for (const param of capability.params) {
-            if (param.source === 'session') {
+            if (param.source === 'session' && pathTemplate.includes(`{${param.name}}`)) {
                 enrichedParams[param.name] = options.auth.userId;
                 logger.debug(`Injected session param "${param.name}" (value redacted)`);
             }

package/dist/esm/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.5.0";
+export declare const VERSION = "0.5.1";

package/dist/esm/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "capman",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "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",