capman 0.4.2 → 0.4.4

package/bin/lib/cmd-validate.js

@@ -0,0 +1,32 @@
+'use strict'
+
+const { header, log, c, getFlag, requireSrc } = require('./shared')
+
+module.exports = function cmdValidate() {
+  header()
+  const { readManifest, validate } = requireSrc()
+
+  const manifestPath = getFlag('--manifest') ?? 'manifest.json'
+  let manifest
+  try {
+    manifest = readManifest(manifestPath)
+  } catch (e) {
+    log.error(e.message)
+    process.exit(1)
+  }
+
+  log.info(`Validating ${c.bold}${manifestPath}${c.reset}...`)
+  const result = validate(manifest)
+  log.blank()
+
+  for (const w of result.warnings) log.warn(w)
+  for (const e of result.errors)   log.error(e)
+
+  if (result.valid) {
+    log.success(`${manifest.capabilities.length} capabilities — all valid`)
+  } else {
+    log.error(`${result.errors.length} error(s) found.`)
+    process.exit(1)
+  }
+  console.log()
+}

package/bin/lib/shared.js

@@ -0,0 +1,77 @@
+'use strict'
+
+const path = require('path')
+const fs   = require('fs')
+
+// ─── Args ─────────────────────────────────────────────────────────────────────
+
+const args    = process.argv.slice(2)
+const command = args[0]
+const flags   = args.slice(1)
+
+const getFlag = (name) => {
+  const i = flags.indexOf(name)
+  if (i === -1) return undefined
+  const value = flags[i + 1]
+  // If next token is another flag or doesn't exist, the flag has no value
+  if (value === undefined || value.startsWith('--')) {
+    console.error(`${'\x1b[31m'}✗${'\x1b[0m'} Flag "${name}" requires a value. Example: ${name} <value>`)
+    process.exit(1)
+  }
+  return value
+}
+
+// ─── Colors ───────────────────────────────────────────────────────────────────
+
+const c = {
+  reset:  '\x1b[0m',
+  bold:   '\x1b[1m',
+  teal:   '\x1b[36m',
+  yellow: '\x1b[33m',
+  red:    '\x1b[31m',
+  green:  '\x1b[32m',
+  gray:   '\x1b[90m',
+}
+
+// ─── Logger ───────────────────────────────────────────────────────────────────
+
+const log = {
+  info:    (...a) => console.log(`${c.teal}i${c.reset}`, ...a),
+  success: (...a) => console.log(`${c.green}✓${c.reset}`, ...a),
+  warn:    (...a) => console.log(`${c.yellow}⚠${c.reset}`, ...a),
+  error:   (...a) => console.error(`${c.red}✗${c.reset}`, ...a),
+  blank:   ()     => console.log(),
+}
+
+// ─── Header ───────────────────────────────────────────────────────────────────
+
+function header() {
+  const pkg = require(path.join(__dirname, '..', '..', 'package.json'))
+  console.log()
+  console.log(`${c.bold}${c.teal}  capman${c.reset} ${c.gray}v${pkg.version} — Capability Manifest Engine${c.reset}`)
+  console.log(`${c.gray}  ─────────────────────────────────────────${c.reset}`)
+  console.log()
+}
+
+// ─── requireSrc ───────────────────────────────────────────────────────────────
+
+function requireSrc() {
+  const distPath = path.join(__dirname, '..', '..', 'dist', 'cjs', 'index.js')
+  if (fs.existsSync(distPath)) return require(distPath)
+
+  log.info('dist/cjs not found — running build...')
+  try {
+    require('child_process').execSync('npm run build', {
+      cwd: path.join(__dirname, '..', '..'),
+      stdio: 'inherit',
+    })
+    if (fs.existsSync(distPath)) return require(distPath)
+  } catch {
+    // build failed
+  }
+
+  log.error('Cannot find dist/cjs/. Run: pnpm run build')
+  process.exit(1)
+}
+
+module.exports = { args, command, flags, getFlag, c, log, header, requireSrc }

package/dist/cjs/cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/cache.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAK1C,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,WAAW,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;CACb;AAID,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAA;IAC5C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;CACxB;AAID,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;GAKG;AAEH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,GAAG,IAAI,EAC3B,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,GAC7C,MAAM,CAQR;AAMD,qBAAa,WAAY,YAAW,UAAU;IAC5C,OAAO,CAAC,KAAK,CAAgC;IAEvC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAU5C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAepD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IACtB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;CAC9B;AAID,qBAAa,SAAU,YAAW,UAAU;IAC1C,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,KAAK,CAAqC;IAClD,OAAO,CAAC,MAAM,CAAQ;gBAEV,QAAQ,SAAuB;YAK7B,IAAI;YAYJ,IAAI;IAaZ,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAW5C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAYpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;CAI9B;AAID,qBAAa,UAAW,YAAW,UAAU;IAC3C,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,IAAI,CAAW;gBAEX,QAAQ,SAAuB;IAKrC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAY5C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAOpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAOtB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;CAG9B"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/cache.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAK1C,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,WAAW,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;CACb;AAID,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAA;IAC5C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;CACxB;AAID,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;GAKG;AAEH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,GAAG,IAAI,EAC3B,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,GAC7C,MAAM,CAQR;AAMD,qBAAa,WAAY,YAAW,UAAU;IAC5C,OAAO,CAAC,KAAK,CAAgC;IAEvC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAU5C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAepD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IACtB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;CAC9B;AAID,qBAAa,SAAU,YAAW,UAAU;IAC1C,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,KAAK,CAAqC;IAClD,OAAO,CAAC,MAAM,CAAQ;gBAEV,QAAQ,SAAuB;YAK7B,IAAI;YAiBJ,IAAI;IAaZ,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAW5C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAYpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;CAI9B;AAID,qBAAa,UAAW,YAAW,UAAU;IAC3C,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,IAAI,CAAW;gBAEX,QAAQ,SAAuB;IAKrC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAY5C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAOpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAOtB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;CAG9B"}

package/dist/cjs/cache.js

@@ -106,8 +106,14 @@ class FileCache {
             return;
         try {
             const raw = await fs.promises.readFile(this.filePath, 'utf-8');
-            this.store = new Map(Object.entries(JSON.parse(raw)));
-            logger_1.logger.debug(`File cache loaded: ${this.store.size} entries`);
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                this.store = new Map(Object.entries(parsed));
+                logger_1.logger.debug(`File cache loaded: ${this.store.size} entries`);
+            }
+            else {
+                logger_1.logger.warn(`File cache at ${this.filePath} contained unexpected format — starting fresh`);
+            }
         }
         catch {
             // File doesn't exist yet — start fresh

package/dist/cjs/cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/cache.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/cache.ts"],"names":[],"mappings":"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"}

package/dist/cjs/engine.d.ts

@@ -1,4 +1,4 @@
-import type { Manifest, MatchResult, ResolveResult, ExecutionTrace } from './types';
+import type { Manifest, MatchResult, ResolveResult, ExecutionTrace, ExplainResult } from './types';
 import type { LLMMatcherOptions } from './matcher';
 import type { ResolveOptions, AuthContext } from './resolver';
 import type { CacheStore } from './cache';
@@ -28,6 +28,29 @@ export interface EngineOptions {
     headers?: Record<string, string>;
     /** Confidence threshold for keyword matcher (default: 50) */
     threshold?: number;
+    /**
+     * Maximum LLM calls per minute in balanced/accurate mode.
+     * After limit is hit, falls back to keyword result.
+     * @default 60
+     */
+    maxLLMCallsPerMinute?: number;
+    /**
+     * Minimum milliseconds between consecutive LLM calls.
+     * Useful for free-tier models with burst limits.
+     * @default 0
+     */
+    llmCooldownMs?: number;
+    /**
+     * Maximum consecutive LLM failures before circuit breaker opens.
+     * When open, LLM calls are skipped for llmCircuitBreakerResetMs.
+     * @default 3
+     */
+    llmCircuitBreakerThreshold?: number;
+    /**
+     * Milliseconds to wait before retrying LLM after circuit breaker opens.
+     * @default 60000
+     */
+    llmCircuitBreakerResetMs?: number;
 }
 export interface EngineResult {
     match: MatchResult;
@@ -47,6 +70,15 @@ export declare class CapmanEngine {
     private auth?;
     private headers?;
     private threshold;
+    private maxLLMCallsPerMinute;
+    private llmCooldownMs;
+    private llmCircuitBreakerThreshold;
+    private llmCircuitBreakerResetMs;
+    private llmCallsThisMinute;
+    private llmWindowStart;
+    private llmLastCallAt;
+    private llmConsecutiveFails;
+    private llmCircuitOpenAt;
     constructor(options: EngineOptions);
     /**
      * Ask the engine a natural language query.
@@ -76,6 +108,31 @@ export declare class CapmanEngine {
      * Clear the cache.
      */
     clearCache(): Promise<void>;
+    /**
+     * Explain what would happen for a query — without executing it.
+     * Shows matched capability, all candidate scores with reasoning,
+     * and what action would be taken.
+     *
+     * @example
+     * const explanation = await engine.explain('track order 1234')
+     * console.log(explanation.matched.reasoning)
+     * console.log(explanation.wouldExecute.action)
+     * console.log(explanation.candidates)
+     */
+    explain(query: string): Promise<ExplainResult>;
+    /**
+     * Checks all rate limiting and circuit breaker conditions.
+     * Returns null if LLM call is allowed, or a skip reason string if it should be skipped.
+     */
+    private checkLLMAllowed;
+    /**
+     * Records a successful LLM call — updates rate limit counters.
+     */
+    private recordLLMSuccess;
+    /**
+     * Records a failed LLM call — may open the circuit breaker.
+     */
+    private recordLLMFailure;
     private resolveOptions;
     private recordLearning;
 }

package/dist/cjs/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,aAAa,EAAE,cAAc,EAAa,MAAM,SAAS,CAAA;AAC9F,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAC7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACzC,OAAO,KAAK,EAAE,aAAa,EAAiB,MAAM,YAAY,CAAA;AAK9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAKxC,MAAM,WAAW,aAAa;IAC5B,qCAAqC;IACrC,QAAQ,EAAE,QAAQ,CAAA;IAClB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,kDAAkD;IAClD,GAAG,CAAC,EAAE,iBAAiB,CAAC,KAAK,CAAC,CAAA;IAC9B,0FAA0F;IAC1F,KAAK,CAAC,EAAE,UAAU,GAAG,KAAK,CAAA;IAC1B,+FAA+F;IAC/F,QAAQ,CAAC,EAAE,aAAa,GAAG,KAAK,CAAA;IAChC,iCAAiC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,mDAAmD;IACnD,IAAI,CAAC,EAAE,WAAW,CAAA;IAClB,mCAAmC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAID,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,WAAW,CAAA;IAClB,UAAU,EAAE,aAAa,CAAA;IACzB,WAAW,EAAE,OAAO,GAAG,SAAS,GAAG,KAAK,CAAA;IACxC,UAAU,EAAE,MAAM,CAAA;IAClB,4CAA4C;IAC5C,KAAK,EAAE,cAAc,CAAA;CACtB;AAID,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,IAAI,CAAgB;IAC5B,OAAO,CAAC,GAAG,CAAC,CAA+B;IAC3C,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,OAAO,CAAC,IAAI,CAAC,CAAiB;IAC9B,OAAO,CAAC,OAAO,CAAC,CAAyB;IACzC,OAAO,CAAC,SAAS,CAAQ;gBAEb,OAAO,EAAE,aAAa;IAwBlC;;;;;;;;;;OAUG;IACG,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,GAAE,OAAO,CAAC,cAAc,CAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAoKxF;;;OAGG;IACG,QAAQ;IAKd;;OAEG;IACG,kBAAkB,CAAC,KAAK,SAAI;;;;IAKlC;;OAEG;IACG,UAAU;IAMhB,OAAO,CAAC,cAAc;YASR,cAAc;CAgB7B"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/engine.ts"],"names":[],"mappings":"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"}

package/dist/cjs/engine.js

@@ -9,6 +9,12 @@ const cache_1 = require("./cache");
 // ─── CapmanEngine ─────────────────────────────────────────────────────────────
 class CapmanEngine {
     constructor(options) {
+        // ── LLM rate limiting state ────────────────────────────────────────────────
+        this.llmCallsThisMinute = 0;
+        this.llmWindowStart = Date.now();
+        this.llmLastCallAt = 0;
+        this.llmConsecutiveFails = 0;
+        this.llmCircuitOpenAt = 0;
         this.manifest = options.manifest;
         this.mode = options.mode ?? 'balanced';
         this.llm = options.llm;
@@ -16,6 +22,10 @@ class CapmanEngine {
         this.auth = options.auth;
         this.headers = options.headers;
         this.threshold = options.threshold ?? 50;
+        this.maxLLMCallsPerMinute = options.maxLLMCallsPerMinute ?? 60;
+        this.llmCooldownMs = options.llmCooldownMs ?? 0;
+        this.llmCircuitBreakerThreshold = options.llmCircuitBreakerThreshold ?? 3;
+        this.llmCircuitBreakerResetMs = options.llmCircuitBreakerResetMs ?? 60000;
         // Cache — default MemoryCache (no filesystem writes), or disabled with false
         // Use FileCache or ComboCache explicitly for persistence across restarts
         this.cache = options.cache === false
@@ -54,7 +64,7 @@ class CapmanEngine {
                 const resolution = await (0, resolver_1.resolve)(cached.result, cached.result.extractedParams, this.resolveOptions(overrides));
                 const trace = {
                     query,
-                    candidates: cached.result.candidates ?? [],
+                    candidates: cached.result.candidates,
                     reasoning: [`Served from cache (original: ${cached.result.reasoning})`],
                     steps,
                     resolvedVia: 'cache',
@@ -86,10 +96,30 @@ class CapmanEngine {
             }
             case 'accurate': {
                 if (this.llm) {
-                    const t = Date.now();
-                    matchResult = await (0, matcher_1.matchWithLLM)(query, this.manifest, { llm: this.llm });
-                    resolvedVia = 'llm';
-                    steps.push({ type: 'llm_match', status: 'pass', durationMs: Date.now() - t, detail: `confidence: ${matchResult.confidence}%` });
+                    const skipReason = this.checkLLMAllowed();
+                    if (skipReason) {
+                        logger_1.logger.warn(`LLM skipped — ${skipReason} — falling back to keyword`);
+                        const t = Date.now();
+                        matchResult = (0, matcher_1.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 (0, matcher_1.matchWithLLM)(query, this.manifest, { llm: this.llm });
+                            this.recordLLMSuccess();
+                            resolvedVia = 'llm';
+                            steps.push({ type: 'llm_match', status: 'pass', durationMs: Date.now() - t, detail: `confidence: ${matchResult.confidence}%` });
+                        }
+                        catch (err) {
+                            this.recordLLMFailure();
+                            logger_1.logger.warn(`LLM call failed — falling back to keyword: ${err}`);
+                            const t2 = Date.now();
+                            matchResult = (0, matcher_1.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_1.logger.warn('accurate mode requires llm — falling back to keyword');
@@ -108,11 +138,28 @@ class CapmanEngine {
                     matchResult = keywordResult;
                 }
                 else {
-                    logger_1.logger.info(`Low confidence (${keywordResult.confidence}%) — escalating to LLM`);
-                    const t2 = Date.now();
-                    matchResult = await (0, matcher_1.matchWithLLM)(query, this.manifest, { llm: this.llm });
-                    resolvedVia = 'llm';
-                    steps.push({ type: 'llm_match', status: 'pass', durationMs: Date.now() - t2, detail: `confidence: ${matchResult.confidence}%` });
+                    const skipReason = this.checkLLMAllowed();
+                    if (skipReason) {
+                        logger_1.logger.warn(`LLM skipped — ${skipReason}`);
+                        steps.push({ type: 'llm_match', status: 'skip', durationMs: 0, detail: skipReason });
+                        matchResult = keywordResult;
+                    }
+                    else {
+                        logger_1.logger.info(`Low confidence (${keywordResult.confidence}%) — escalating to LLM`);
+                        const t2 = Date.now();
+                        try {
+                            matchResult = await (0, matcher_1.matchWithLLM)(query, this.manifest, { llm: this.llm });
+                            this.recordLLMSuccess();
+                            resolvedVia = 'llm';
+                            steps.push({ type: 'llm_match', status: 'pass', durationMs: Date.now() - t2, detail: `confidence: ${matchResult.confidence}%` });
+                        }
+                        catch (err) {
+                            this.recordLLMFailure();
+                            logger_1.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;
             }
@@ -143,7 +190,7 @@ class CapmanEngine {
         });
         // ── Step 6: Build reasoning array ────────────────────────────────────────
         const reasoning = [];
-        if (matchResult.candidates?.length) {
+        if (matchResult.candidates.length) {
             const winner = matchResult.candidates.find(c => c.matched);
             const rejected = matchResult.candidates
                 .filter(c => !c.matched && c.score > 0)
@@ -170,7 +217,7 @@ class CapmanEngine {
         await this.recordLearning(query, matchResult, resolvedVia);
         const trace = {
             query,
-            candidates: matchResult.candidates ?? [],
+            candidates: matchResult.candidates,
             reasoning,
             steps,
             resolvedVia,
@@ -208,6 +255,259 @@ class CapmanEngine {
         if (this.cache)
             await this.cache.clear();
     }
+    /**
+     * Explain what would happen for a query — without executing it.
+     * Shows matched capability, all candidate scores with reasoning,
+     * and what action would be taken.
+     *
+     * @example
+     * const explanation = await engine.explain('track order 1234')
+     * console.log(explanation.matched.reasoning)
+     * console.log(explanation.wouldExecute.action)
+     * 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_1.logger.warn(`explain(): LLM skipped — ${skipReason} — falling back to keyword`);
+                    matchResult = (0, matcher_1.match)(query, this.manifest);
+                }
+                else {
+                    try {
+                        matchResult = await (0, matcher_1.matchWithLLM)(query, this.manifest, { llm: this.llm });
+                        this.recordLLMSuccess();
+                        resolvedVia = 'llm';
+                    }
+                    catch (err) {
+                        this.recordLLMFailure();
+                        logger_1.logger.warn(`explain(): LLM call failed — falling back to keyword: ${err}`);
+                        matchResult = (0, matcher_1.match)(query, this.manifest);
+                    }
+                }
+            }
+            else {
+                matchResult = (0, matcher_1.match)(query, this.manifest);
+            }
+        }
+        else if (this.mode === 'balanced' && this.llm) {
+            // Keyword first — escalate to LLM if low confidence (same as ask())
+            const keywordResult = (0, matcher_1.match)(query, this.manifest);
+            if (keywordResult.confidence >= this.threshold) {
+                matchResult = keywordResult;
+            }
+            else {
+                const skipReason = this.checkLLMAllowed();
+                if (skipReason) {
+                    logger_1.logger.warn(`explain(): LLM skipped — ${skipReason}`);
+                    matchResult = keywordResult;
+                }
+                else {
+                    try {
+                        matchResult = await (0, matcher_1.matchWithLLM)(query, this.manifest, { llm: this.llm });
+                        this.recordLLMSuccess();
+                        resolvedVia = 'llm';
+                    }
+                    catch (err) {
+                        this.recordLLMFailure();
+                        logger_1.logger.warn(`explain(): LLM call failed — falling back to keyword: ${err}`);
+                        matchResult = keywordResult;
+                    }
+                }
+            }
+        }
+        else {
+            // cheap mode or no llm — keyword only
+            matchResult = (0, matcher_1.match)(query, this.manifest);
+        }
+        // ── Build candidate explanations ─────────────────────────────────────────
+        const candidates = matchResult.candidates
+            .sort((a, b) => b.score - a.score)
+            .map(c => {
+            const cap = this.manifest.capabilities.find(mc => mc.id === c.capabilityId);
+            let explanation = '';
+            if (c.score === 0) {
+                explanation = 'No keyword overlap with examples or description';
+            }
+            else if (c.score >= 90) {
+                explanation = `Strong match (${c.score}%) — query closely matches examples`;
+            }
+            else if (c.score >= 50) {
+                const qWords = query.toLowerCase().split(/\W+/).filter(Boolean);
+                const matchedWords = (cap?.examples ?? [])
+                    .flatMap(e => e.toLowerCase().split(/\s+/))
+                    .filter(w => qWords.includes(w) && w.length > 2);
+                const unique = [...new Set(matchedWords)].slice(0, 3);
+                explanation = unique.length
+                    ? `Matched keywords: ${unique.join(', ')} (${c.score}%)`
+                    : `Partial match (${c.score}%) — some keyword overlap`;
+            }
+            else {
+                explanation = `Weak match (${c.score}%) — below 50% confidence threshold, rejected`;
+            }
+            return { capabilityId: c.capabilityId, score: c.score, matched: c.matched, explanation };
+        });
+        // ── Build reasoning array ────────────────────────────────────────────────
+        const reasoning = [];
+        const winner = candidates.find(c => c.matched);
+        const rejected = candidates.filter(c => !c.matched && c.score > 0).slice(0, 3);
+        if (winner) {
+            reasoning.push(`Matched "${winner.capabilityId}" with ${winner.score}% confidence`);
+        }
+        else {
+            reasoning.push('No capability matched above the 50% confidence threshold');
+        }
+        if (rejected.length) {
+            reasoning.push(`Rejected: ${rejected.map(r => `${r.capabilityId} (${r.score}%)`).join(', ')}`);
+        }
+        reasoning.push(`Resolved via: ${resolvedVia}`);
+        if (matchResult.extractedParams && Object.keys(matchResult.extractedParams).length) {
+            const params = Object.entries(matchResult.extractedParams)
+                .filter(([, v]) => v !== null)
+                .map(([k, v]) => `${k}=${v}`)
+                .join(', ');
+            if (params)
+                reasoning.push(`Would extract params: ${params}`);
+        }
+        // ── Build wouldExecute ───────────────────────────────────────────────────
+        const cap = matchResult.capability;
+        let action = null;
+        let blocked = null;
+        let privacy = null;
+        let resolverType = null;
+        if (cap) {
+            privacy = cap.privacy.level;
+            resolverType = cap.resolver.type;
+            // Check if privacy would block — mirrors checkPrivacy() in resolver.ts
+            if (cap.privacy.level === 'user_owned') {
+                if (!this.auth?.isAuthenticated) {
+                    blocked = `Capability "${cap.id}" requires authentication (privacy: user_owned)`;
+                }
+            }
+            else if (cap.privacy.level === 'admin') {
+                if (!this.auth?.isAuthenticated) {
+                    blocked = `Capability "${cap.id}" requires authentication (privacy: admin)`;
+                }
+                else if (this.auth.role !== 'admin') {
+                    blocked = `Capability "${cap.id}" requires admin role (current role: ${this.auth.role ?? 'none'})`;
+                }
+            }
+            if (!blocked) {
+                // Build action string
+                const params = matchResult.extractedParams;
+                if (cap.resolver.type === 'api') {
+                    const endpoint = cap.resolver.endpoints[0];
+                    let path = endpoint.path;
+                    for (const [k, v] of Object.entries(params)) {
+                        if (v)
+                            path = path.replace(`{${k}}`, v);
+                    }
+                    const base = this.baseUrl ?? '';
+                    action = `${endpoint.method} ${base}${path}`;
+                }
+                else if (cap.resolver.type === 'nav') {
+                    let dest = cap.resolver.destination;
+                    for (const [k, v] of Object.entries(params)) {
+                        if (v)
+                            dest = dest.replace(`{${k}}`, v);
+                    }
+                    action = `navigate → ${dest}`;
+                }
+                else if (cap.resolver.type === 'hybrid') {
+                    const hybrid = cap.resolver;
+                    const endpoint = hybrid.api.endpoints[0];
+                    let path = endpoint.path;
+                    for (const [k, v] of Object.entries(params)) {
+                        if (v)
+                            path = path.replace(`{${k}}`, v);
+                    }
+                    let dest = hybrid.nav.destination;
+                    for (const [k, v] of Object.entries(params)) {
+                        if (v)
+                            dest = dest.replace(`{${k}}`, v);
+                    }
+                    const base = this.baseUrl ?? '';
+                    action = `${endpoint.method} ${base}${path} + navigate → ${dest}`;
+                }
+            }
+        }
+        return {
+            query,
+            matched: {
+                capability: matchResult.capability,
+                confidence: matchResult.confidence,
+                intent: matchResult.intent,
+                reasoning,
+            },
+            candidates,
+            wouldExecute: { resolverType, action, privacy, blocked },
+            resolvedVia,
+            durationMs: Date.now() - start,
+        };
+    }
+    /**
+     * Checks all rate limiting and circuit breaker conditions.
+     * Returns null if LLM call is allowed, or a skip reason string if it should be skipped.
+     */
+    checkLLMAllowed() {
+        const now = Date.now();
+        // ── Circuit breaker ──────────────────────────────────────────────────────
+        if (this.llmCircuitOpenAt > 0) {
+            const elapsed = now - this.llmCircuitOpenAt;
+            if (elapsed < this.llmCircuitBreakerResetMs) {
+                const remainingSec = Math.ceil((this.llmCircuitBreakerResetMs - elapsed) / 1000);
+                return `circuit breaker open — ${remainingSec}s remaining`;
+            }
+            // Reset circuit breaker — try again
+            logger_1.logger.info('LLM circuit breaker reset — trying again');
+            this.llmCircuitOpenAt = 0;
+            this.llmConsecutiveFails = 0;
+        }
+        // ── Cooldown between calls ───────────────────────────────────────────────
+        if (this.llmCooldownMs > 0 && this.llmLastCallAt > 0) {
+            const elapsed = now - this.llmLastCallAt;
+            if (elapsed < this.llmCooldownMs) {
+                const remainingMs = this.llmCooldownMs - elapsed;
+                return `cooldown active — ${remainingMs}ms remaining`;
+            }
+        }
+        // ── Per-minute rate limit ────────────────────────────────────────────────
+        const windowElapsed = now - this.llmWindowStart;
+        if (windowElapsed >= 60000) {
+            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);
+            return `rate limit reached (${this.maxLLMCallsPerMinute}/min) — resets in ${Math.max(0, resetIn)}s`;
+        }
+        // Reserve the slot atomically before the call happens
+        this.llmCallsThisMinute++;
+        this.llmLastCallAt = Date.now();
+        return null;
+    }
+    /**
+     * Records a successful LLM call — updates rate limit counters.
+     */
+    recordLLMSuccess() {
+        this.llmConsecutiveFails = 0;
+    }
+    /**
+     * Records a failed LLM call — may open the circuit breaker.
+     */
+    recordLLMFailure() {
+        this.llmConsecutiveFails++;
+        if (this.llmConsecutiveFails >= this.llmCircuitBreakerThreshold) {
+            this.llmCircuitOpenAt = Date.now();
+            logger_1.logger.warn(`LLM circuit breaker opened after ${this.llmConsecutiveFails} consecutive failures — pausing for ${this.llmCircuitBreakerResetMs / 1000}s`);
+        }
+    }
     // ── Private helpers ────────────────────────────────────────────────────────
     resolveOptions(overrides = {}) {
         return {