capman 0.6.0 → 0.6.2

package/dist/esm/generator.js

@@ -5,10 +5,14 @@ import { validateConfig, validateManifest } from './schema';
 import { logger } from './logger';
 export function generate(config) {
     return {
+        schemaVersion: '1',
         version: VERSION,
         app: config.app,
         generatedAt: new Date().toISOString(),
-        capabilities: config.capabilities.map(cap => ({ ...cap, params: [...cap.params] })),
+        capabilities: config.capabilities.map(cap => ({ ...cap })),
+        ...(config.info ? { info: config.info } : {}),
+        ...(config.tagRegistry ? { tagRegistry: config.tagRegistry } : {}),
+        ...(config.servers ? { servers: config.servers } : {}),
     };
 }
 export function loadConfig(configPath) {
@@ -33,6 +37,10 @@ export function loadConfig(configPath) {
             // Use a CJS config file or convert with: module.exports = { ... }
             // Full ESM config support is planned for v0.5.
             try {
+                // Bust the module cache before loading — require() caches by resolved path,
+                // so a second call without this returns the stale version from the first call.
+                // This matters in watch mode and test suites that change config between calls.
+                delete require.cache[require.resolve(resolved)];
                 const mod = require(resolved);
                 raw = mod.default ?? mod;
             }
@@ -80,7 +88,12 @@ export function writeManifest(manifest, outputPath = 'manifest.json') {
         throw new Error(`writeManifest: output path "${outputPath}" resolves outside the working directory.\n` +
             `Resolved: ${resolved}\nAllowed:  ${cwd}`);
     }
-    fs.writeFileSync(resolved, JSON.stringify(manifest, null, 2));
+    // Write atomically via tmp → rename — same pattern used by FileCache and
+    // FileLearningStore. A crash or SIGKILL mid-write leaves the .tmp file, not
+    // a truncated manifest.json, so the next readManifest() can still parse it.
+    const tmp = `${resolved}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(manifest, null, 2));
+    fs.renameSync(tmp, resolved);
     return resolved;
 }
 export function readManifest(manifestPath = 'manifest.json') {
@@ -122,14 +135,23 @@ export function validate(manifest) {
     return { valid: errors.length === 0, errors, warnings };
 }
 export function generateStarterConfig() {
-    return `// capman.config.js 
-// Define what your app can do for AI agents.
-// Replace the examples below with your own app's capabilities.
+    return `// capman.config.js
+// Auto-generated starter config — edit before use
 
 module.exports = {
-  app: 'your-app-name',
+  app: 'my-app',
   baseUrl: 'https://api.your-app.com',
 
+  // Optional metadata block — used for documentation and provenance
+  info: {
+    title:       'My App',
+    description: 'Brief description of what this app does',
+    version:     '1.0.0',
+    homepage:    'https://your-app.com',
+    contact:     { name: 'Your Name', email: 'you@your-app.com' },
+    license:     { name: 'MIT' },
+  },
+
   capabilities: [
     {
       id: 'get_resource',

package/dist/esm/index.d.ts

@@ -1,14 +1,16 @@
 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 type { Capability, CapabilityParam, CapmanConfig, Manifest, MatchResult, ExecutionTrace, TraceStep, MatchCandidate, ResolveResult, ApiCallResult, ValidationResult, Resolver, ApiResolver, NavResolver, HybridResolver, PrivacyScope, ResolverType, HttpMethod, ExplainResult, ExplainCandidate, ManifestInfo, Server, LifecycleInfo, LifecycleStatus, CapabilityError, Endpoint, ParamType, MatchHint, EmbeddingProvider, } 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 { TYPE_PATTERNS } from './matcher';
+export { filterByTags } from './matcher';
 export { resolve } from './resolver';
 export type { ResolveOptions, AuthContext } from './resolver';
 export { CapmanEngine } from './engine';
+export { ConcurrentCapmanEngine } from './concurrent';
 export type { EngineOptions, EngineResult } from './engine';
 export { MemoryCache, FileCache, ComboCache, buildCacheKey, normalizeQuery } from './cache';
 export type { CacheStore, CacheEntry } from './cache';

package/dist/esm/index.js

@@ -3,9 +3,11 @@ export { generate, loadConfig, writeManifest, readManifest, validate, generateSt
 export { match, matchWithLLM, extractParams, } from './matcher';
 export { LLMParseError } from './matcher';
 export { TYPE_PATTERNS } from './matcher';
+export { filterByTags } from './matcher';
 export { resolve } from './resolver';
 // ─── Engine (recommended API) ─────────────────────────────────────────────────
 export { CapmanEngine } from './engine';
+export { ConcurrentCapmanEngine } from './concurrent';
 // ─── Cache ────────────────────────────────────────────────────────────────────
 export { MemoryCache, FileCache, ComboCache, buildCacheKey, normalizeQuery } from './cache';
 // ─── Learning ─────────────────────────────────────────────────────────────────

package/dist/esm/learning.d.ts

@@ -6,6 +6,20 @@ export interface LearningEntry {
     extractedParams: Record<string, string | null>;
     resolvedVia: 'keyword' | 'llm' | 'cache';
     timestamp: string;
+    /**
+       * Confidence-derived weight stored at record time (confidence / 100, floor 0.1).
+       * Used by subtract() to reverse the exact contribution made by update(),
+       * preventing index drift when high-confidence entries are pruned.
+       * Optional for backwards-compatibility with persisted entries written before v0.5.5.
+       */
+    weight?: number;
+    /**
+     * Unix timestamp (ms) when this entry was last updated.
+     * Used for time-decay — older entries contribute less learning signal.
+     * Optional for backwards-compatibility with persisted entries written before v0.7.0.
+     * Migration: FileLearningStore falls back to file mtime for entries missing this field.
+     */
+    lastUpdated?: number;
 }
 export interface KeywordStats {
     /** keyword → Map of capabilityId → hit count */
@@ -43,7 +57,7 @@ export declare class FileLearningStore implements LearningStore {
     private learningIndex;
     private dirty;
     private saveTimer;
-    constructor(filePath?: string);
+    constructor(filePath?: string, halfLifeDays?: number);
     flushSync(): void;
     /**
      * Removes this store from the exit flush registry and cancels any pending save timer.
@@ -67,6 +81,7 @@ export declare class FileLearningStore implements LearningStore {
 export declare class MemoryLearningStore implements LearningStore {
     private entries;
     private learningIndex;
+    constructor(halfLifeDays?: number);
     record(entry: LearningEntry): Promise<void>;
     getStats(): Promise<KeywordStats>;
     getIndex(): Promise<Record<string, Record<string, number>>>;

package/dist/esm/learning.js

@@ -3,6 +3,15 @@ import * as path from 'path';
 import { logger } from './logger';
 const MAX_LEARNING_ENTRIES = 10_000;
 import { tokenize } from './matcher';
+/**
+ * Exponential decay — older entries contribute less signal.
+ * At exactly halfLifeDays old, a weight of 1.0 decays to 0.5.
+ * At 2× halfLifeDays, it decays to 0.25. And so on.
+ */
+function decayedWeight(weight, lastUpdated, halfLifeDays) {
+    const ageDays = (Date.now() - lastUpdated) / (1000 * 60 * 60 * 24);
+    return weight * Math.pow(0.5, ageDays / halfLifeDays);
+}
 // Module-level registry — tracks all active FileLearningStore instances
 // for process exit flushing. Handlers registered once to avoid accumulation.
 const activeStores = new Set();
@@ -56,11 +65,18 @@ function computeTopCapabilities(entries, limit) {
 // Both FileLearningStore and MemoryLearningStore compose this instead of
 // duplicating the same ~80 lines of index management logic.
 class LearningIndex {
-    constructor() {
+    constructor(halfLifeDays = 30) {
         this.index = {};
+        /** Tracks when each (word, capabilityId) cell was last reinforced — used for decay */
+        this.lastUpdatedIndex = {};
         this.statsCounter = {
             totalQueries: 0, llmQueries: 0, cacheHits: 0, outOfScope: 0,
         };
+        if (halfLifeDays <= 0) {
+            throw new RangeError(`halfLifeDays must be a positive number — got ${halfLifeDays}. ` +
+                `Use a value in days e.g. 30 (1 month), 7 (1 week).`);
+        }
+        this.halfLifeDays = halfLifeDays;
     }
     update(entry) {
         this.statsCounter.totalQueries++;
@@ -75,11 +91,21 @@ class LearningIndex {
             // more signal than a 51% borderline match. Floor of 0.1 ensures
             // borderline matches still contribute, just proportionally less.
             const weight = Math.max(0.1, entry.confidence / 100);
+            // Respect a caller-supplied timestamp (historical replay, rebuild()).
+            // For brand-new real-time entries lastUpdated is undefined — default to now.
+            const now = entry.lastUpdated ?? Date.now();
+            // Store weight and timestamp on the entry so subtract() can reverse the
+            // exact amount and migration has an accurate record time.
+            entry.weight = weight;
+            entry.lastUpdated = now;
             const words = tokenize(entry.query);
             for (const word of words) {
                 this.index[word] ??= {};
                 this.index[word][entry.capabilityId] =
                     (this.index[word][entry.capabilityId] ?? 0) + weight;
+                // Track when this (word, cap) cell was last reinforced for decay
+                this.lastUpdatedIndex[word] ??= {};
+                this.lastUpdatedIndex[word][entry.capabilityId] = now;
             }
         }
     }
@@ -99,15 +125,19 @@ class LearningIndex {
         for (const word of words) {
             if (!this.index[word])
                 continue;
-            // Subtract estimated weight (0.5 average) — exact weight not stored.
-            // Minor drift on prune is acceptable; index is rebuilt when drift matters.
+            // Use the weight stored at record time for exact symmetric subtraction.
+            // Fallback recalculates from confidence for entries persisted before the
+            // weight field was added (backwards-compatible with older learning.json files).
+            const weight = entry.weight ?? Math.max(0.1, entry.confidence / 100);
             this.index[word][entry.capabilityId] =
-                (this.index[word][entry.capabilityId] ?? 0.5) - 0.5;
+                (this.index[word][entry.capabilityId] ?? weight) - weight;
             if (this.index[word][entry.capabilityId] <= 0) {
                 delete this.index[word][entry.capabilityId];
+                delete this.lastUpdatedIndex[word]?.[entry.capabilityId];
             }
             if (Object.keys(this.index[word]).length === 0) {
                 delete this.index[word];
+                delete this.lastUpdatedIndex[word];
             }
         }
     }
@@ -120,10 +150,25 @@ class LearningIndex {
     }
     reset() {
         this.index = {};
+        this.lastUpdatedIndex = {};
         this.statsCounter = { totalQueries: 0, llmQueries: 0, cacheHits: 0, outOfScope: 0 };
     }
     getStats() {
-        return { ...this.statsCounter, index: structuredClone(this.index) };
+        // Apply time-decay lazily on read. The index stores accumulated weights;
+        // each (word, capId) cell is decayed by how long ago it was last reinforced.
+        // This means recently-used capabilities retain full signal while stale ones fade.
+        const decayed = {};
+        for (const [word, capMap] of Object.entries(this.index)) {
+            for (const [capId, weight] of Object.entries(capMap)) {
+                const lastUpdated = this.lastUpdatedIndex[word]?.[capId] ?? Date.now();
+                const dw = decayedWeight(weight, lastUpdated, this.halfLifeDays);
+                if (dw > 0.001) { // drop negligible signal — avoids ghost entries
+                    decayed[word] ??= {};
+                    decayed[word][capId] = dw;
+                }
+            }
+        }
+        return { ...this.statsCounter, index: decayed };
     }
     getIndex() {
         return structuredClone(this.index);
@@ -131,13 +176,13 @@ class LearningIndex {
 }
 // ─── File Learning Store ──────────────────────────────────────────────────────
 export class FileLearningStore {
-    constructor(filePath = '.capman/learning.json') {
+    constructor(filePath = '.capman/learning.json', halfLifeDays = 30) {
         this.entries = [];
         this.loadPromise = null;
         this.saveQueue = Promise.resolve();
-        this.learningIndex = new LearningIndex();
         this.dirty = false;
         this.saveTimer = null;
+        this.learningIndex = new LearningIndex(halfLifeDays);
         const cwd = process.cwd();
         const resolved = path.resolve(cwd, filePath);
         const allowedPrefix = cwd === '/' ? '/' : cwd + path.sep;
@@ -168,8 +213,10 @@ export class FileLearningStore {
             fs.writeFileSync(tmp, payload);
             fs.renameSync(tmp, this.filePath);
         }
-        catch {
-            // Best-effort in exit handler
+        catch (err) {
+            // Use process.stderr.write — never console.error in an exit handler,
+            // as stdout may already be flushed or closed at this point.
+            process.stderr.write(`[capman] Failed to flush learning store to ${this.filePath}: ${err}\n`);
         }
     }
     /**
@@ -199,10 +246,44 @@ export class FileLearningStore {
     }
     async _doLoad() {
         try {
+            // Fetch mtime once — used as lastUpdated fallback for pre-v0.7.0 entries.
+            // Conservative: treats all old entries as "last updated when file was written"
+            // rather than "infinitely old", preventing a cliff-edge decay on first upgrade.
+            let fileMtimeMs = Date.now();
+            try {
+                const stat = await fs.promises.stat(this.filePath);
+                fileMtimeMs = stat.mtimeMs;
+            }
+            catch {
+                // File doesn't exist yet or stat failed — Date.now() fallback is safe
+            }
             const raw = await fs.promises.readFile(this.filePath, 'utf-8');
             const parsed = JSON.parse(raw);
             if (parsed && typeof parsed === 'object' && !Array.isArray(parsed) && Array.isArray(parsed.entries)) {
-                this.entries = parsed.entries;
+                // Validate each entry — corrupted entries (null capability, wrong types) must
+                // not propagate into the engine where they cause runtime errors deep in matching.
+                const validEntries = [];
+                let skipped = 0;
+                for (const entry of parsed.entries) {
+                    if (entry !== null && typeof entry === 'object' &&
+                        typeof entry.query === 'string' &&
+                        (entry.capabilityId === null || typeof entry.capabilityId === 'string') &&
+                        typeof entry.confidence === 'number' &&
+                        typeof entry.resolvedVia === 'string') {
+                        // Migration guard: backfill lastUpdated for pre-v0.7.0 entries
+                        validEntries.push({
+                            ...entry,
+                            lastUpdated: entry.lastUpdated ?? fileMtimeMs,
+                        });
+                    }
+                    else {
+                        skipped++;
+                    }
+                }
+                if (skipped > 0) {
+                    logger.warn(`Learning store: skipped ${skipped} invalid entries during load`);
+                }
+                this.entries = validEntries;
                 this.learningIndex.rebuild(this.entries);
                 logger.debug(`Learning store loaded: ${this.entries.length} entries`);
             }
@@ -299,9 +380,9 @@ export class FileLearningStore {
 }
 // ─── Memory Learning Store (for testing) ─────────────────────────────────────
 export class MemoryLearningStore {
-    constructor() {
+    constructor(halfLifeDays = 30) {
         this.entries = [];
-        this.learningIndex = new LearningIndex();
+        this.learningIndex = new LearningIndex(halfLifeDays);
     }
     async record(entry) {
         const sanitized = {
@@ -313,8 +394,8 @@ export class MemoryLearningStore {
         if (this.entries.length > MAX_LEARNING_ENTRIES) {
             const excess = this.entries.length - MAX_LEARNING_ENTRIES;
             const pruned = this.entries.splice(0, excess);
-            for (const entry of pruned) {
-                this.learningIndex.subtract(entry);
+            for (const staleEntry of pruned) {
+                this.learningIndex.subtract(staleEntry);
             }
         }
     }

package/dist/esm/matcher.d.ts

@@ -34,6 +34,17 @@ export interface BM25Index {
     N: number;
     /** Bigram sets per capability — post-stopword, post-stem, examples only */
     bigrams: Record<string, Set<string>>;
+    /**
+     * Pre-computed token arrays per capability, per field.
+     * Avoids re-tokenizing capability text on every scoreCapability() call.
+     * At 50 capabilities × 100 req/s, that is 5,000 redundant tokenization
+     * calls per second — each involving stem() and split/filter chains.
+     */
+    capTokens: Record<string, {
+        examples: string[];
+        description: string[];
+        name: string[];
+    }>;
 }
 /** Build a BM25 index over all capabilities. Call once at manifest load. */
 export declare function buildBM25Index(capabilities: Capability[]): BM25Index;
@@ -48,11 +59,39 @@ export declare function scoreCapability(qWordSet: Set<string>, cap: Capability,
  * Input must already be post-stopword and post-stem (use tokenize() first).
  */
 export declare function extractBigrams(tokens: string[]): Set<string>;
+/**
+ * Reciprocal Rank Fusion — fuses multiple ranked lists into a single score map.
+ * k=60 is the standard literature default.
+ */
+export declare function rrf(rankings: Array<Array<{
+    id: string;
+    score: number;
+}>>, k?: number): Map<string, number>;
+/**
+ * Returns a sub-manifest containing only capabilities that match ALL provided tags.
+ * Capabilities without tags are excluded when tags filter is active.
+ * Enables token-efficient LLM prompts for large manifests:
+ *
+ * @example
+ * // Only send order-related capabilities to LLM
+ * const orderManifest = filterByTags(manifest, ['orders'])
+ * const result = await matchWithLLM(query, orderManifest, { llm })
+ *
+ * @example
+ * // Match by any of multiple tags (union) — call filterByTags per tag and merge
+ * const ordersOrPayments = [
+ *   ...filterByTags(manifest, ['orders']).capabilities,
+ *   ...filterByTags(manifest, ['payments']).capabilities,
+ * ]
+ */
+export declare function filterByTags(manifest: Manifest, tags: string[]): Manifest;
 export declare function resolverToIntent(cap: Capability): MatchResult['intent'];
 /**
  * Strips characters that could break LLM prompt structure from
  * capability field values before injection into the system prompt.
- * Removes control characters, newlines, and delimiter-like sequences.
+ * Removes control characters, newlines, delimiter sequences, and braces
+ * anywhere in the string (not just at line starts) to resist prompt injection
+ * from third-party OpenAPI spec content ingested via parseOpenAPI().
  */
 export declare function sanitizeForPrompt(value: string, maxLen: number): string;
 /**
@@ -77,9 +116,19 @@ export interface MatchOptions {
     bm25K1?: number;
     bm25B?: number;
     bm25Ceiling?: number;
+    /** Pre-computed cosine similarity scores keyed by capability ID (0–100). Engine passes these when an EmbeddingProvider is configured. */
+    embeddingScores?: Map<string, number>;
 }
+/**
+ * Calibrates a BM25 normalization ceiling from the manifest.
+ * Scores each capability against all of its own examples and returns the maximum.
+ * Call once at manifest load time — O(capabilities × examples).
+ */
+export declare function calibrateCeiling(capabilities: Capability[], bm25Index: BM25Index, k1: number, b: number): number;
 export declare function match(query: string, manifest: Manifest, options?: MatchOptions): MatchResult;
 export interface LLMMatcherOptions {
+    /** App name for prompt context — passed from engine, optional for direct callers */
+    app?: string;
     llm: (prompt: string) => Promise<string>;
 }
 /**
@@ -93,4 +142,4 @@ export interface LLMMatcherOptions {
  * wrapper that maps the prompt to a proper system message, keeping user query
  * data in the user turn only.
  */
-export declare function matchWithLLM(query: string, manifest: Manifest, options: LLMMatcherOptions): Promise<MatchResult>;
+export declare function matchWithLLM(query: string, topCandidates: Capability[], options: LLMMatcherOptions): Promise<MatchResult>;