capman 0.6.0 → 0.6.1

package/dist/esm/engine.js

@@ -1,4 +1,4 @@
-import { match as _match, matchWithLLM as _matchWithLLM, resolverToIntent, extractParams, LLMParseError, tokenize, buildBM25Index, scoreCapability as _scoreCapability, sanitizeForPrompt } from './matcher';
+import { match as _match, matchWithLLM as _matchWithLLM, resolverToIntent, extractParams, LLMParseError, tokenize, buildBM25Index, sanitizeForPrompt, calibrateCeiling as _calibrateCeiling } from './matcher';
 import { resolve as _resolve, checkPrivacy } from './resolver';
 import { MemoryLearningStore } from './learning';
 import { logger } from './logger';
@@ -17,6 +17,7 @@ export class CapmanEngine {
         this.mode = options.mode ?? 'balanced';
         this.llm = options.llm;
         this.baseUrl = options.baseUrl;
+        this.environment = options.environment;
         this.auth = options.auth;
         this.headers = options.headers;
         this.threshold = options.threshold ?? 50;
@@ -124,6 +125,7 @@ export class CapmanEngine {
         // ── Step 2.5: Apply learning boost ───────────────────────────────────────
         matchResult = await this.applyBoostToMatchResult(query, matchResult, resolvedVia);
         // ── Step 3: Privacy check ────────────────────────────────────────────────
+        let privacyFailed = false;
         if (matchResult.capability) {
             const privacyError = checkPrivacy(matchResult.capability, this.auth);
             steps.push({
@@ -132,13 +134,23 @@ export class CapmanEngine {
                 durationMs: 0,
                 detail: privacyError ?? `level: ${matchResult.capability.privacy.level}`,
             });
+            // Warn on deprecated or sunset capabilities — never silently fail
+            this.checkCapabilityLifecycle(matchResult.capability);
+            // Log when engine mode differs from capability's preferred mode
+            this.checkMatchHint(matchResult.capability);
+            // Short-circuit: if privacy fails, skip disambiguation to avoid burning an LLM
+            // call on a request that _resolve() will block anyway. privacyFailed propagates
+            // to Step 4a so the mode guard check is clean and explicit.
+            if (privacyError)
+                privacyFailed = true;
         }
         // ── Step 4a: Compute verdict + optional margin-aware LLM disambiguation ──
         let { verdict, margin } = this.computeVerdict(matchResult);
         if (verdict === 'marginal' &&
             this.marginAwareLLM &&
             this.llm &&
-            this.mode === 'balanced') {
+            !privacyFailed &&
+            (this.mode === 'balanced' || this.mode === 'accurate')) {
             matchResult = await this.disambiguateLLM(query, matchResult, steps);
             // Recompute verdict after disambiguation
             const recomputed = this.computeVerdict(matchResult);
@@ -205,8 +217,19 @@ export class CapmanEngine {
                             }
                         }
                     }
-                    catch {
-                        // LLM param extraction failed — fall through to missingParams below
+                    catch (err) {
+                        const isParseError = err instanceof SyntaxError;
+                        if (isParseError) {
+                            // JSON parse failure: refund the rate-limit slot but don't open circuit breaker
+                            // The llm is reachable - the response format was just bad
+                            this.llmCallsThisMinute = Math.max(0, this.llmCallsThisMinute - 1);
+                        }
+                        else {
+                            // Hard failure (timeout, network): refund slot and increment fail counter
+                            this.recordLLMFailure();
+                        }
+                        logger.warn(`LLM param extraction failed: ${err instanceof Error ? err.message : String(err)}`);
+                        // fall through to missingParams below
                     }
                 }
             }
@@ -292,6 +315,20 @@ export class CapmanEngine {
             await this.cache.clear();
     }
     checkManifestVersion(manifest) {
+        // ── Schema version check ─────────────────────────────────────────────────
+        // schemaVersion tracks manifest format — "1" for v0.6+.
+        // Manifests without schemaVersion are pre-v0.6 — warn but allow.
+        const CURRENT_SCHEMA_VERSION = '1';
+        if (!manifest.schemaVersion) {
+            console.warn(`[capman] Manifest is missing schemaVersion — it was generated with capman < 0.6. ` +
+                `Regenerate with: npx capman generate`);
+        }
+        else if (manifest.schemaVersion !== CURRENT_SCHEMA_VERSION) {
+            console.warn(`[capman] Manifest schemaVersion "${manifest.schemaVersion}" differs from ` +
+                `engine's expected "${CURRENT_SCHEMA_VERSION}". ` +
+                `Regenerate with: npx capman generate`);
+        }
+        // ── Package version check ────────────────────────────────────────────────
         if (!manifest.version)
             return;
         const SEMVER_RE = /^\d+\.\d+\.\d+$/;
@@ -299,8 +336,8 @@ export class CapmanEngine {
             const [mMaj, mMin] = manifest.version.split('.').map(Number);
             const [eMaj, eMin] = VERSION.split('.').map(Number);
             if (mMaj !== eMaj || mMin !== eMin) {
-                console.warn(`[capman] Manifest version "${manifest.version}" was generated with a ` +
-                    `different engine version than "${VERSION}". This is usually fine across patch versions. ` +
+                console.warn(`[capman] Manifest was generated with capman "${manifest.version}" ` +
+                    `but engine is "${VERSION}". This is usually fine across patch versions. ` +
                     `If you experience unexpected matching issues, regenerate with: npx capman generate`);
             }
         }
@@ -309,6 +346,42 @@ export class CapmanEngine {
                 `to engine version "${VERSION}" — version strings are not valid semver.`);
         }
     }
+    checkCapabilityLifecycle(capability) {
+        const lc = capability.lifecycle;
+        if (!lc || lc.status === 'stable' || lc.status === 'beta' || lc.status === 'experimental') {
+            if (lc?.status === 'beta') {
+                logger.warn(`Capability "${capability.id}" is in beta — behavior may change`);
+            }
+            if (lc?.status === 'experimental') {
+                logger.warn(`Capability "${capability.id}" is experimental — use with caution`);
+            }
+            return;
+        }
+        if (lc.status === 'deprecated') {
+            const sunsetPassed = lc.sunsetAt && new Date(lc.sunsetAt) < new Date();
+            if (sunsetPassed) {
+                // Sunset date has passed — strongest warning
+                console.warn(`[capman] ⚠️  Capability "${capability.id}" passed its sunset date (${lc.sunsetAt}). ` +
+                    `It may be removed in a future version.` +
+                    (lc.successor ? ` Use "${lc.successor}" instead.` : '') +
+                    (lc.note ? ` Note: ${lc.note}` : ''));
+            }
+            else {
+                logger.warn(`Capability "${capability.id}" is deprecated.` +
+                    (lc.sunsetAt ? ` Sunset: ${lc.sunsetAt}.` : '') +
+                    (lc.successor ? ` Use "${lc.successor}" instead.` : '') +
+                    (lc.note ? ` Note: ${lc.note}` : ''));
+            }
+        }
+    }
+    checkMatchHint(capability) {
+        const hint = capability.matchHint?.preferredMode;
+        if (!hint || hint === this.mode)
+            return;
+        // Advisory only — log but never enforce
+        logger.warn(`Capability "${capability.id}" prefers mode "${hint}" but engine is in "${this.mode}" mode. ` +
+            `Set mode: '${hint}' in EngineOptions to honor this hint.`);
+    }
     /**
      * Replaces the active manifest without creating a new engine instance.
      * Useful for hot-reloading manifests in long-running servers without
@@ -327,6 +400,8 @@ export class CapmanEngine {
         this.bm25Index = buildBM25Index(manifest.capabilities);
         this.bm25Ceiling = this.calibrateBM25Ceiling();
         this.adaptiveMargin = this.calibrateAdaptiveMargin();
+        // resolveBaseUrl() reads from this.manifest.servers on each call —
+        // server selection updates automatically after loadManifest()
         await this.clearCache();
     }
     /**
@@ -684,7 +759,11 @@ export class CapmanEngine {
                 break;
             }
         }
-        return { matchResult: matchResult, resolvedVia };
+        if (matchResult === undefined) {
+            const exhaustive = this.mode;
+            throw new Error(`_runMatch: unhandled MatchMode "${exhaustive}"`);
+        }
+        return { matchResult, resolvedVia };
     }
     /**
      * Applies learning boost to a MatchResult and returns the updated result.
@@ -769,10 +848,26 @@ export class CapmanEngine {
             };
         });
     }
+    /**
+     * Resolves the effective baseUrl from manifest.servers[] or EngineOptions.baseUrl.
+     * Priority: environment-matched server > first server > explicit baseUrl > undefined
+     */
+    resolveBaseUrl() {
+        const servers = this.manifest.servers;
+        if (!servers?.length)
+            return this.baseUrl;
+        if (this.environment) {
+            const match = servers.find(s => s.environment === this.environment);
+            if (match)
+                return match.url.replace(/\/$/, '');
+        }
+        // Fallback to first server
+        return servers[0].url.replace(/\/$/, '');
+    }
     // ── Private helpers ────────────────────────────────────────────────────────
     resolveOptions(overrides = {}) {
         return {
-            baseUrl: this.baseUrl,
+            baseUrl: this.resolveBaseUrl(),
             auth: this.auth,
             headers: this.headers,
             ...overrides,
@@ -792,16 +887,7 @@ export class CapmanEngine {
         });
     }
     calibrateBM25Ceiling() {
-        let max = 0;
-        for (const cap of this.manifest.capabilities) {
-            if (!cap.examples?.length)
-                continue;
-            const selfWords = new Set(tokenize(cap.examples[0]));
-            const raw = _scoreCapability(selfWords, cap, this.bm25Index, this.bm25K1, this.bm25B);
-            if (raw > max)
-                max = raw;
-        }
-        return max > 0 ? max : 100;
+        return _calibrateCeiling(this.manifest.capabilities, this.bm25Index, this.bm25K1, this.bm25B);
     }
     /**
      * Calibrates the adaptive margin threshold from the manifest's own score
@@ -829,10 +915,14 @@ export class CapmanEngine {
         for (const cap of this.manifest.capabilities) {
             if (!cap.examples?.length)
                 continue;
-            const result = _match(cap.examples[0], this.manifest, fuzzyOpts);
-            const sorted = [...result.candidates].sort((a, b) => b.score - a.score);
-            if (sorted.length >= 2) {
-                margins.push(sorted[0].score - sorted[1].score);
+            // Use all examples and take the maximum margin — same rationale as
+            // calibrateBM25Ceiling(): a weak first example skews the calibration.
+            for (const example of cap.examples) {
+                const result = _match(example, this.manifest, fuzzyOpts);
+                const sorted = [...result.candidates].sort((a, b) => b.score - a.score);
+                if (sorted.length >= 2) {
+                    margins.push(sorted[0].score - sorted[1].score);
+                }
             }
         }
         if (margins.length === 0)

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,11 +1,12 @@
 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, } 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';

package/dist/esm/index.js

@@ -3,6 +3,7 @@ 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';

package/dist/esm/learning.d.ts

@@ -6,6 +6,13 @@ 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;
 }
 export interface KeywordStats {
     /** keyword → Map of capabilityId → hit count */

package/dist/esm/learning.js

@@ -75,6 +75,10 @@ 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);
+            // Store weight on the entry so subtract() can reverse the exact amount.
+            // Without this, subtract() would have to use a hardcoded estimate (0.5)
+            // that causes index drift after pruning high-confidence entries.
+            entry.weight = weight;
             const words = tokenize(entry.query);
             for (const word of words) {
                 this.index[word] ??= {};
@@ -99,10 +103,12 @@ 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];
             }
@@ -168,8 +174,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`);
         }
     }
     /**
@@ -202,7 +210,26 @@ export class FileLearningStore {
             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') {
+                        validEntries.push(entry);
+                    }
+                    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`);
             }
@@ -313,8 +340,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,31 @@ 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>;
+/**
+ * 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;
 /**
@@ -78,6 +109,12 @@ export interface MatchOptions {
     bm25B?: number;
     bm25Ceiling?: 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 {
     llm: (prompt: string) => Promise<string>;