capman 0.1.0 → 0.3.0

package/dist/esm/generator.js

@@ -0,0 +1,183 @@
+import { VERSION } from './version';
+import * as fs from 'fs';
+import * as path from 'path';
+import { validateConfig, validateManifest } from './schema';
+import { logger } from './logger';
+export function generate(config) {
+    return {
+        version: VERSION,
+        app: config.app,
+        generatedAt: new Date().toISOString(),
+        capabilities: config.capabilities,
+    };
+}
+export function loadConfig(configPath) {
+    const candidates = configPath
+        ? [configPath]
+        : ['capman.config.js', 'capman.config.json'];
+    // If a specific path was given but doesn't exist — clear error
+    if (configPath) {
+        const resolved = path.resolve(process.cwd(), configPath);
+        if (!fs.existsSync(resolved)) {
+            throw new Error(`Config file not found at: ${resolved}\n` +
+                `Check the path and try again.`);
+        }
+    }
+    for (const candidate of candidates) {
+        const resolved = path.resolve(process.cwd(), candidate);
+        if (fs.existsSync(resolved)) {
+            let raw;
+            // Catch syntax errors in config file
+            try {
+                const mod = require(resolved);
+                raw = mod.default ?? mod;
+            }
+            catch (err) {
+                throw new Error(`Failed to load config at ${resolved}:\n` +
+                    `  ${err instanceof Error ? err.message : String(err)}\n\n` +
+                    `Check your config file for syntax errors.`);
+            }
+            // Catch invalid config structure
+            const check = validateConfig(raw);
+            if (!check.valid) {
+                throw new Error(`Invalid capman config at ${resolved}:\n` +
+                    check.errors.map(e => `  • ${e}`).join('\n') + '\n\n' +
+                    `Run: node bin/capman.js init  to see a valid example config.`);
+            }
+            return raw;
+        }
+    }
+    // No config found at all
+    throw new Error(`No capman config file found.\n\n` +
+        `Expected one of:\n` +
+        candidates.map(c => `  • ${c}`).join('\n') + '\n\n' +
+        `Run: node bin/capman.js init  to create one.`);
+}
+export function writeManifest(manifest, outputPath = 'manifest.json') {
+    const resolved = path.resolve(process.cwd(), outputPath);
+    fs.writeFileSync(resolved, JSON.stringify(manifest, null, 2));
+    return resolved;
+}
+export function readManifest(manifestPath = 'manifest.json') {
+    const resolved = path.resolve(process.cwd(), manifestPath);
+    if (!fs.existsSync(resolved)) {
+        throw new Error(`No manifest found at ${resolved}. Run: node bin/capman.js generate`);
+    }
+    const raw = JSON.parse(fs.readFileSync(resolved, 'utf-8'));
+    const check = validateManifest(raw);
+    if (!check.valid) {
+        throw new Error(`Invalid manifest at ${resolved}:\n` +
+            check.errors.map(e => `  • ${e}`).join('\n'));
+    }
+    return raw;
+}
+export function validate(manifest) {
+    const errors = [];
+    const warnings = [];
+    // Delegate error checking to Zod
+    const zodResult = validateManifest(manifest);
+    errors.push(...zodResult.errors);
+    // Warnings that Zod doesn't cover
+    for (const cap of manifest.capabilities ?? []) {
+        if (!cap.examples?.length) {
+            const msg = `Capability "${cap.id}" has no examples — adding examples improves matching`;
+            warnings.push(msg);
+            logger.warn(msg);
+        }
+        if (!cap.returns?.length) {
+            const msg = `Capability "${cap.id}" has no "returns" declaration`;
+            warnings.push(msg);
+            logger.warn(msg);
+        }
+    }
+    if (errors.length > 0) {
+        logger.error(`Manifest validation failed — ${errors.length} error(s)`);
+        errors.forEach(e => logger.error(e));
+    }
+    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.
+
+module.exports = {
+  app: 'your-app-name',
+  baseUrl: 'https://api.your-app.com',
+
+  capabilities: [
+    {
+      id: 'get_resource',
+      name: 'Get a resource',
+      description: 'Fetch a specific resource by name, ID, or filter from the app.',
+      examples: [
+        'Show me the resource details',
+        'Find resource by ID',
+        'Look up resource by name',
+      ],
+      params: [
+        {
+          name: 'resource_id',
+          description: 'The ID or name of the resource to fetch',
+          required: true,
+          source: 'user_query',
+        },
+      ],
+      returns: ['resource', 'metadata'],
+      resolver: {
+        type: 'api',
+        endpoints: [{ method: 'GET', path: '/resources/{resource_id}' }],
+      },
+      privacy: { level: 'public', note: 'No auth required' },
+    },
+
+    {
+      id: 'navigate_to_screen',
+      name: 'Navigate to a screen',
+      description: 'Route the user to a specific page or section in the app.',
+      examples: [
+        'Take me to the dashboard',
+        'Open settings',
+        'Go to my profile',
+      ],
+      params: [
+        {
+          name: 'destination',
+          description: 'The screen or page to navigate to',
+          required: true,
+          source: 'user_query',
+        },
+      ],
+      returns: ['deep_link'],
+      resolver: { type: 'nav', destination: '{destination}' },
+      privacy: { level: 'public' },
+    },
+
+    {
+      id: 'get_user_data',
+      name: 'Get user data',
+      description: 'Retrieve data belonging to the currently authenticated user.',
+      examples: [
+        'Show my account details',
+        'What is my current plan?',
+        'Show my recent activity',
+      ],
+      params: [
+        {
+          name: 'user_id',
+          description: 'Current user ID',
+          required: true,
+          source: 'session',
+        },
+      ],
+      returns: ['user_data'],
+      resolver: {
+        type: 'api',
+        endpoints: [{ method: 'GET', path: '/users/{user_id}' }],
+      },
+      privacy: { level: 'user_owned', note: 'Requires auth — scoped to current user only' },
+    },
+  ],
+}
+`;
+}

package/dist/esm/generator.js.map

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

package/dist/esm/index.js

@@ -0,0 +1,56 @@
+export { setLogLevel } from './logger';
+import { logger } from './logger';
+export { generate, loadConfig, writeManifest, readManifest, validate, generateStarterConfig, } from './generator';
+export { match, matchWithLLM, } from './matcher';
+export { resolve } from './resolver';
+// ─── Convenience: ask() — match + resolve in one call ────────────────────────
+import { match as _match, matchWithLLM as _matchWithLLM } from './matcher';
+import { resolve as _resolve } from './resolver';
+// ─── Engine (recommended API) ─────────────────────────────────────────────────
+export { CapmanEngine } from './engine';
+// ─── Cache ────────────────────────────────────────────────────────────────────
+export { MemoryCache, FileCache, ComboCache } from './cache';
+// ─── Learning ─────────────────────────────────────────────────────────────────
+export { FileLearningStore, MemoryLearningStore } from './learning';
+/**
+ * One-shot convenience: match + resolve in a single call.
+ *
+ * @example
+ * const result = await ask("show me the dashboard", manifest, {
+ *   baseUrl: 'https://api.your-app.com',
+ * })
+ */
+export async function ask(query, manifest, options = {}) {
+    const { llm, mode = 'balanced', ...resolveOptions } = options;
+    let matchResult;
+    switch (mode) {
+        case 'cheap': {
+            // Keyword only — never calls LLM
+            matchResult = _match(query, manifest);
+            break;
+        }
+        case 'accurate': {
+            // LLM first — falls back to keyword if LLM fails or no llm provided
+            if (llm) {
+                matchResult = await _matchWithLLM(query, manifest, { llm });
+            }
+            else {
+                logger.warn('ask() mode is "accurate" but no llm function was provided — falling back to keyword matching');
+                matchResult = _match(query, manifest);
+            }
+            break;
+        }
+        case 'balanced':
+        default: {
+            // Keyword first — LLM fallback if confidence below threshold
+            const keywordResult = _match(query, manifest);
+            const THRESHOLD = 50;
+            matchResult = (keywordResult.confidence >= THRESHOLD || !llm)
+                ? keywordResult
+                : await _matchWithLLM(query, manifest, { llm });
+            break;
+        }
+    }
+    const resolution = await _resolve(matchResult, matchResult.extractedParams, resolveOptions);
+    return { match: matchResult, resolution };
+}

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAEtC,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AAmBjC,OAAO,EACL,QAAQ,EACR,UAAU,EACV,aAAa,EACb,YAAY,EACZ,QAAQ,EACR,qBAAqB,GACtB,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,KAAK,EACL,YAAY,GACb,MAAM,WAAW,CAAA;AAGlB,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAGpC,gFAAgF;AAEhF,OAAO,EAAE,KAAK,IAAI,MAAM,EAAE,YAAY,IAAI,aAAa,EAAE,MAAM,WAAW,CAAA;AAC1E,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,YAAY,CAAA;AA0BhD;;;;;;;GAOG;AAEH,MAAM,CAAC,KAAK,UAAU,GAAG,CACvB,KAAa,EACb,QAAkB,EAClB,UAAsB,EAAE;IAExB,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,UAAU,EAAE,GAAG,cAAc,EAAE,GAAG,OAAO,CAAA;IAE7D,IAAI,WAAwB,CAAA;IAE5B,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,iCAAiC;YACjC,WAAW,GAAG,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;YACrC,MAAK;QACP,CAAC;QAED,KAAK,UAAU,CAAC,CAAC,CAAC;YAChB,oEAAoE;YACpE,IAAI,GAAG,EAAE,CAAC;gBACR,WAAW,GAAG,MAAM,aAAa,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,GAAG,EAAE,CAAC,CAAA;YAC7D,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,IAAI,CAAC,8FAA8F,CAAC,CAAA;gBAC3G,WAAW,GAAG,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;YACvC,CAAC;YACD,MAAK;QACP,CAAC;QAED,KAAK,UAAU,CAAC;QAChB,OAAO,CAAC,CAAC,CAAC;YACR,6DAA6D;YAC7D,MAAM,aAAa,GAAG,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;YAC7C,MAAM,SAAS,GAAG,EAAE,CAAA;YACpB,WAAW,GAAG,CAAC,aAAa,CAAC,UAAU,IAAI,SAAS,IAAI,CAAC,GAAG,CAAC;gBAC3D,CAAC,CAAC,aAAa;gBACf,CAAC,CAAC,MAAM,aAAa,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,GAAG,EAAE,CAAC,CAAA;YACjD,MAAK;QACP,CAAC;IACH,CAAC;IAED,MAAM,UAAU,GAAG,MAAM,QAAQ,CAC/B,WAAW,EACX,WAAW,CAAC,eAA0C,EACtD,cAAc,CACf,CAAA;IAED,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,CAAA;AAC3C,CAAC"}

package/dist/esm/learning.js

@@ -0,0 +1,145 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { logger } from './logger';
+// ─── File Learning Store ──────────────────────────────────────────────────────
+export class FileLearningStore {
+    constructor(filePath = '.capman/learning.json') {
+        this.entries = [];
+        this.loaded = false;
+        this.filePath = path.resolve(process.cwd(), filePath);
+    }
+    load() {
+        if (this.loaded)
+            return;
+        try {
+            if (fs.existsSync(this.filePath)) {
+                const raw = JSON.parse(fs.readFileSync(this.filePath, 'utf-8'));
+                this.entries = raw.entries ?? [];
+                logger.debug(`Learning store loaded: ${this.entries.length} entries`);
+            }
+        }
+        catch {
+            logger.warn(`Failed to load learning store at ${this.filePath}`);
+        }
+        this.loaded = true;
+    }
+    save() {
+        try {
+            const dir = path.dirname(this.filePath);
+            if (!fs.existsSync(dir))
+                fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(this.filePath, JSON.stringify({
+                entries: this.entries,
+                updatedAt: new Date().toISOString(),
+            }, null, 2));
+        }
+        catch {
+            logger.warn(`Failed to save learning store to ${this.filePath}`);
+        }
+    }
+    async record(entry) {
+        this.load();
+        this.entries.push(entry);
+        this.save();
+        logger.debug(`Learning recorded: "${entry.query}" → ${entry.capabilityId ?? 'OUT_OF_SCOPE'} via ${entry.resolvedVia}`);
+    }
+    async getStats() {
+        this.load();
+        const index = {};
+        let totalQueries = 0;
+        let llmQueries = 0;
+        let cacheHits = 0;
+        let outOfScope = 0;
+        for (const entry of this.entries) {
+            totalQueries++;
+            if (entry.resolvedVia === 'llm')
+                llmQueries++;
+            if (entry.resolvedVia === 'cache')
+                cacheHits++;
+            if (!entry.capabilityId)
+                outOfScope++;
+            if (entry.capabilityId) {
+                // Index each word of the query against the matched capability
+                const words = entry.query.toLowerCase()
+                    .split(/\W+/)
+                    .filter(w => w.length > 2);
+                for (const word of words) {
+                    if (!index[word])
+                        index[word] = {};
+                    index[word][entry.capabilityId] =
+                        (index[word][entry.capabilityId] ?? 0) + 1;
+                }
+            }
+        }
+        return { index, totalQueries, llmQueries, cacheHits, outOfScope };
+    }
+    async getTopCapabilities(limit = 5) {
+        this.load();
+        const counts = {};
+        for (const entry of this.entries) {
+            if (entry.capabilityId) {
+                counts[entry.capabilityId] = (counts[entry.capabilityId] ?? 0) + 1;
+            }
+        }
+        return Object.entries(counts)
+            .sort(([, a], [, b]) => b - a)
+            .slice(0, limit)
+            .map(([id, hits]) => ({ id, hits }));
+    }
+    async clear() {
+        this.entries = [];
+        this.save();
+    }
+}
+// ─── Memory Learning Store (for testing) ─────────────────────────────────────
+export class MemoryLearningStore {
+    constructor() {
+        this.entries = [];
+    }
+    async record(entry) {
+        this.entries.push(entry);
+    }
+    async getStats() {
+        const index = {};
+        let totalQueries = 0;
+        let llmQueries = 0;
+        let cacheHits = 0;
+        let outOfScope = 0;
+        for (const entry of this.entries) {
+            totalQueries++;
+            if (entry.resolvedVia === 'llm')
+                llmQueries++;
+            if (entry.resolvedVia === 'cache')
+                cacheHits++;
+            if (!entry.capabilityId)
+                outOfScope++;
+            if (entry.capabilityId) {
+                const words = entry.query.toLowerCase()
+                    .split(/\W+/)
+                    .filter(w => w.length > 2);
+                for (const word of words) {
+                    if (!index[word])
+                        index[word] = {};
+                    index[word][entry.capabilityId] =
+                        (index[word][entry.capabilityId] ?? 0) + 1;
+                }
+            }
+        }
+        return { index, totalQueries, llmQueries, cacheHits, outOfScope };
+    }
+    async getTopCapabilities(limit = 5) {
+        const counts = {};
+        for (const entry of this.entries) {
+            if (entry.capabilityId) {
+                counts[entry.capabilityId] = (counts[entry.capabilityId] ?? 0) + 1;
+            }
+        }
+        return Object.entries(counts)
+            .sort(([, a], [, b]) => b - a)
+            .slice(0, limit)
+            .map(([id, hits]) => ({ id, hits }));
+    }
+    async clear() {
+        this.entries = [];
+    }
+}

package/dist/esm/logger.js

@@ -0,0 +1,47 @@
+// ─── Log levels ───────────────────────────────────────────────────────────────
+const LEVELS = {
+    silent: 0,
+    error: 1,
+    warn: 2,
+    info: 3,
+    debug: 4,
+};
+// ─── Logger ───────────────────────────────────────────────────────────────────
+export class Logger {
+    constructor(level = 'silent') {
+        this.level = LEVELS[level];
+    }
+    setLevel(level) {
+        this.level = LEVELS[level];
+    }
+    error(msg, ...args) {
+        if (this.level >= LEVELS.error)
+            console.error(`[capman:error] ${msg}`, ...args);
+    }
+    warn(msg, ...args) {
+        if (this.level >= LEVELS.warn)
+            console.warn(`[capman:warn] ${msg}`, ...args);
+    }
+    info(msg, ...args) {
+        if (this.level >= LEVELS.info)
+            console.log(`[capman:info] ${msg}`, ...args);
+    }
+    debug(msg, ...args) {
+        if (this.level >= LEVELS.debug)
+            console.log(`[capman:debug] ${msg}`, ...args);
+    }
+}
+// ─── Global logger instance ───────────────────────────────────────────────────
+export const logger = new Logger('silent');
+/**
+ * Set the global log level for capman.
+ *
+ * @example
+ * import { setLogLevel } from 'capman'
+ * setLogLevel('debug') // see everything
+ * setLogLevel('info')  // see key steps
+ * setLogLevel('silent') // no output (default)
+ */
+export function setLogLevel(level) {
+    logger.setLevel(level);
+}

package/dist/esm/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/logger.ts"],"names":[],"mappings":"AAAA,iFAAiF;AAIjF,MAAM,MAAM,GAA6B;IACvC,MAAM,EAAE,CAAC;IACT,KAAK,EAAG,CAAC;IACT,IAAI,EAAI,CAAC;IACT,IAAI,EAAI,CAAC;IACT,KAAK,EAAG,CAAC;CACV,CAAA;AAED,iFAAiF;AAEjF,MAAM,OAAO,MAAM;IAGjB,YAAY,QAAkB,QAAQ;QACpC,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAA;IAC5B,CAAC;IAED,QAAQ,CAAC,KAAe;QACtB,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAA;IAC5B,CAAC;IAED,KAAK,CAAC,GAAW,EAAE,GAAG,IAAe;QACnC,IAAI,IAAI,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK;YAC5B,OAAO,CAAC,KAAK,CAAC,kBAAkB,GAAG,EAAE,EAAE,GAAG,IAAI,CAAC,CAAA;IACnD,CAAC;IAED,IAAI,CAAC,GAAW,EAAE,GAAG,IAAe;QAClC,IAAI,IAAI,CAAC,KAAK,IAAI,MAAM,CAAC,IAAI;YAC3B,OAAO,CAAC,IAAI,CAAC,iBAAiB,GAAG,EAAE,EAAE,GAAG,IAAI,CAAC,CAAA;IACjD,CAAC;IAED,IAAI,CAAC,GAAW,EAAE,GAAG,IAAe;QAClC,IAAI,IAAI,CAAC,KAAK,IAAI,MAAM,CAAC,IAAI;YAC3B,OAAO,CAAC,GAAG,CAAC,iBAAiB,GAAG,EAAE,EAAE,GAAG,IAAI,CAAC,CAAA;IAChD,CAAC;IAED,KAAK,CAAC,GAAW,EAAE,GAAG,IAAe;QACnC,IAAI,IAAI,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK;YAC5B,OAAO,CAAC,GAAG,CAAC,kBAAkB,GAAG,EAAE,EAAE,GAAG,IAAI,CAAC,CAAA;IACjD,CAAC;CACF;AAED,iFAAiF;AAEjF,MAAM,CAAC,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAA;AAE1C;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,KAAe;IACzC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;AACxB,CAAC"}

package/dist/esm/matcher.js

@@ -0,0 +1,211 @@
+import { logger } from './logger';
+const STOPWORDS = new Set([
+    'show', 'me', 'the', 'get', 'find', 'fetch', 'give', 'please',
+    'can', 'you', 'i', 'want', 'to', 'a', 'an', 'my', 'our', 'your',
+    'what', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
+    'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would',
+    'could', 'should', 'may', 'might', 'shall', 'and', 'or', 'but',
+    'in', 'on', 'at', 'by', 'for', 'with', 'about', 'into', 'through',
+    'of', 'from', 'up', 'out', 'that', 'this', 'these', 'those',
+    'it', 'its', 'how', 'when', 'where', 'who', 'which', 'all',
+    'just', 'some', 'any', 'there', 'their', 'them', 'they',
+]);
+function filterStopwords(words) {
+    return words.filter(w => !STOPWORDS.has(w.toLowerCase()) && w.length > 1);
+}
+function scoreCapability(query, cap) {
+    const q = query.toLowerCase();
+    let score = 0;
+    const qWords = filterStopwords(q.split(/\W+/).filter(Boolean));
+    // Check examples — exact substring match is a strong signal
+    for (const example of cap.examples ?? []) {
+        const exWords = filterStopwords(example.toLowerCase().split(/\s+/));
+        if (exWords.length === 0)
+            continue;
+        const overlap = exWords.filter(w => qWords.includes(w)).length;
+        score += (overlap / exWords.length) * 60;
+    }
+    // Check description words
+    const descWords = filterStopwords(cap.description.toLowerCase().split(/\W+/).filter(Boolean));
+    if (descWords.length > 0) {
+        const descOverlap = descWords.filter(w => qWords.includes(w)).length;
+        score += (descOverlap / descWords.length) * 30;
+    }
+    // Check name words
+    const nameWords = filterStopwords(cap.name.toLowerCase().split(/\W+/).filter(Boolean));
+    if (nameWords.length > 0) {
+        const nameOverlap = nameWords.filter(w => qWords.includes(w)).length;
+        score += (nameOverlap / nameWords.length) * 10;
+    }
+    return Math.min(Math.round(score), 100);
+}
+function resolverToIntent(cap) {
+    const t = cap.resolver.type;
+    if (t === 'api')
+        return 'retrieval';
+    if (t === 'nav')
+        return 'navigation';
+    if (t === 'hybrid')
+        return 'hybrid';
+    return 'out_of_scope';
+}
+/**
+ * Extracts parameter values from a user query using keyword heuristics.
+ *
+ * Known limits:
+ * - Extracts single tokens only — "jane smith" would extract "jane"
+ * - Keyword matching is positional — "articles from authors I follow"
+ *   may extract "authors" instead of nothing, since "from" is a keyword
+ * - For complex or ambiguous queries, use matchWithLLM() which handles
+ *   param extraction more accurately via the LLM prompt
+ */
+function extractParams(query, cap) {
+    const result = {};
+    const q = query.toLowerCase();
+    for (const param of cap.params) {
+        // Session params come from auth context, not query
+        if (param.source === 'session') {
+            result[param.name] = '[from_session]';
+            continue;
+        }
+        if (param.source !== 'user_query') {
+            result[param.name] = null;
+            continue;
+        }
+        // Try to extract value after known keywords
+        // e.g. "profile for johndoe" → johndoe
+        //      "articles by jane"   → jane
+        //      "tag javascript"     → javascript
+        // Use param name and description as hints for what to look for
+        const paramHints = [param.name, ...param.description.toLowerCase().split(/\s+/)]
+            .filter(w => w.length > 2);
+        // Try keyword-based extraction first
+        const keywords = [
+            `for `, `by `, `about `, `named `, `called `,
+            `tag `, `user `, `author `, `slug `, `id `,
+            `from `, `with `,
+        ];
+        // For nav params — look for destination after navigation verbs
+        const navKeywords = [`to `, `open `, `show `];
+        const isNavParam = param.name === 'destination' ||
+            param.description.toLowerCase().includes('screen') ||
+            param.description.toLowerCase().includes('page');
+        const activeKeywords = isNavParam
+            ? [...navKeywords, ...keywords]
+            : keywords;
+        let extracted = null;
+        for (const kw of activeKeywords) {
+            const idx = q.indexOf(kw);
+            if (idx !== -1) {
+                const after = query.slice(idx + kw.length).trim();
+                // Get remaining words, filter stopwords, take first meaningful one
+                const tokens = after.split(/\s+/)
+                    .map(t => t.replace(/[^a-zA-Z0-9-_@.]/g, ''))
+                    .filter(t => t.length > 1 && !STOPWORDS.has(t.toLowerCase()));
+                if (tokens.length > 0) {
+                    // For IDs and numbers — single token is correct
+                    const isIdParam = param.name === 'id' ||
+                        param.name.endsWith('_id') ||
+                        param.name.endsWith('Id') ||
+                        /^\s*\w+\s+id\b/i.test(param.description) ||
+                        /^id\b/i.test(param.description);
+                    // For names, products, destinations — grab multi-word phrase
+                    extracted = (isIdParam || isNavParam) ? tokens[0] : tokens.join('-').toLowerCase();
+                    break;
+                }
+            }
+        }
+        // Fallback — grab last meaningful word in the query
+        if (!extracted) {
+            const words = query.trim().split(/\s+/);
+            const meaningful = words.filter(w => !STOPWORDS.has(w.toLowerCase()));
+            extracted = meaningful[meaningful.length - 1] ?? null;
+        }
+        result[param.name] = extracted;
+    }
+    return result;
+}
+export function match(query, manifest) {
+    if (!query?.trim()) {
+        logger.warn('Empty query received');
+        return {
+            capability: null,
+            confidence: 0,
+            intent: 'out_of_scope',
+            extractedParams: {},
+            reasoning: 'Empty query',
+        };
+    }
+    logger.info(`Matching query: "${query}"`);
+    logger.debug(`Manifest has ${manifest.capabilities.length} capabilities`);
+    let best = null;
+    let bestScore = 0;
+    for (const cap of manifest.capabilities) {
+        const score = scoreCapability(query, cap);
+        logger.debug(`  scored "${cap.id}": ${score}%`);
+        if (score > bestScore) {
+            bestScore = score;
+            best = cap;
+        }
+    }
+    if (!best || bestScore < 50) {
+        logger.info(`No match above threshold (best: ${bestScore}% for "${best?.id ?? 'none'}")`);
+        return {
+            capability: null,
+            confidence: bestScore,
+            intent: 'out_of_scope',
+            extractedParams: {},
+            reasoning: `No capability matched with sufficient confidence (best score: ${bestScore})`,
+        };
+    }
+    const params = extractParams(query, best);
+    logger.info(`Matched "${best.id}" at ${bestScore}% confidence`);
+    logger.debug(`Extracted params: ${JSON.stringify(params)}`);
+    return {
+        capability: best,
+        confidence: bestScore,
+        intent: resolverToIntent(best),
+        extractedParams: params,
+        reasoning: `Matched "${best.id}" via keyword scoring (score: ${bestScore})`,
+    };
+}
+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.
+
+App: ${manifest.app}
+
+Available capabilities:
+${manifestSummary}
+
+User query: "${query}"
+
+Respond ONLY in valid JSON (no markdown):
+{
+  "matched_capability": "<capability_id or OUT_OF_SCOPE>",
+  "confidence": <0-100>,
+  "intent": "<navigation|retrieval|hybrid|out_of_scope>",
+  "reasoning": "<one sentence>",
+  "extracted_params": { "<param_name>": "<value or null>" }
+}`;
+    try {
+        const raw = await options.llm(prompt);
+        const clean = raw.replace(/```json|```/g, '').trim();
+        const parsed = JSON.parse(clean);
+        const isOOS = parsed.matched_capability === 'OUT_OF_SCOPE';
+        const capability = isOOS
+            ? null
+            : manifest.capabilities.find(c => c.id === parsed.matched_capability) ?? null;
+        return {
+            capability,
+            confidence: parsed.confidence,
+            intent: isOOS ? 'out_of_scope' : parsed.intent,
+            extractedParams: parsed.extracted_params ?? {},
+            reasoning: parsed.reasoning,
+        };
+    }
+    catch (err) {
+        logger.warn(`LLM match failed, falling back to keyword matcher: ${err}`);
+        return match(query, manifest);
+    }
+}