capman 0.5.0 → 0.5.2

package/dist/esm/learning.js

@@ -1,7 +1,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { logger } from './logger';
-const MAX_LEARNING_ENTRIES = 10000;
+const MAX_LEARNING_ENTRIES = 10_000;
 import { STOPWORDS } from './matcher';
 // ─── Shared computation helpers ───────────────────────────────────────────────
 function computeStats(entries) {
@@ -55,11 +55,17 @@ export class FileLearningStore {
         this.statsCounter = {
             totalQueries: 0, llmQueries: 0, cacheHits: 0, outOfScope: 0,
         };
-        this.filePath = path.resolve(process.cwd(), filePath);
+        const cwd = process.cwd();
+        const resolved = path.resolve(cwd, filePath);
+        const allowedPrefix = cwd === '/' ? '/' : cwd + path.sep;
+        if (!resolved.startsWith(allowedPrefix)) {
+            throw new Error(`FileCache path "${filePath}" resolves outside the working directory.\n` +
+                `Resolved: ${resolved}\nAllowed:  ${cwd}`);
+        }
+        this.filePath = resolved;
         logger.info(`FileLearningStore initialized — writing to: ${this.filePath}`);
     }
     updateIndex(entry) {
-        var _a;
         this.statsCounter.totalQueries++;
         if (entry.resolvedVia === 'llm')
             this.statsCounter.llmQueries++;
@@ -72,12 +78,43 @@ export class FileLearningStore {
                 .split(/\W+/)
                 .filter(w => w.length > 2 && !STOPWORDS.has(w));
             for (const word of words) {
-                (_a = this.index)[word] ?? (_a[word] = {});
+                this.index[word] ??= {};
                 this.index[word][entry.capabilityId] =
                     (this.index[word][entry.capabilityId] ?? 0) + 1;
             }
         }
     }
+    subtractFromIndex(entry) {
+        if (!entry.capabilityId) {
+            this.statsCounter.outOfScope = Math.max(0, this.statsCounter.outOfScope - 1);
+            this.statsCounter.totalQueries = Math.max(0, this.statsCounter.totalQueries - 1);
+            if (entry.resolvedVia === 'llm')
+                this.statsCounter.llmQueries = Math.max(0, this.statsCounter.llmQueries - 1);
+            if (entry.resolvedVia === 'cache')
+                this.statsCounter.cacheHits = Math.max(0, this.statsCounter.cacheHits - 1);
+            return;
+        }
+        this.statsCounter.totalQueries = Math.max(0, this.statsCounter.totalQueries - 1);
+        if (entry.resolvedVia === 'llm')
+            this.statsCounter.llmQueries = Math.max(0, this.statsCounter.llmQueries - 1);
+        if (entry.resolvedVia === 'cache')
+            this.statsCounter.cacheHits = Math.max(0, this.statsCounter.cacheHits - 1);
+        const words = entry.query.toLowerCase()
+            .split(/\W+/)
+            .filter(w => w.length > 2 && !STOPWORDS.has(w));
+        for (const word of words) {
+            if (!this.index[word])
+                continue;
+            this.index[word][entry.capabilityId] =
+                (this.index[word][entry.capabilityId] ?? 1) - 1;
+            if (this.index[word][entry.capabilityId] <= 0) {
+                delete this.index[word][entry.capabilityId];
+            }
+            if (Object.keys(this.index[word]).length === 0) {
+                delete this.index[word];
+            }
+        }
+    }
     rebuildIndex() {
         this.index = {};
         this.statsCounter = { totalQueries: 0, llmQueries: 0, cacheHits: 0, outOfScope: 0 };
@@ -124,13 +161,26 @@ export class FileLearningStore {
     }
     async record(entry) {
         await this.load();
-        this.entries.push(entry);
-        this.updateIndex(entry);
+        // Store only tokenized keywords — never raw query text.
+        // Raw queries may contain PII (emails, names, order IDs) that should
+        // not be persisted to disk under GDPR/CCPA data retention requirements.
+        const sanitized = {
+            ...entry,
+            query: entry.query
+                .toLowerCase()
+                .split(/\W+/)
+                .filter(w => w.length > 2 && !STOPWORDS.has(w))
+                .join(' '),
+        };
+        this.entries.push(sanitized);
+        this.updateIndex(sanitized);
         if (this.entries.length > MAX_LEARNING_ENTRIES) {
             const excess = this.entries.length - MAX_LEARNING_ENTRIES;
-            this.entries.splice(0, excess);
-            // Rebuild index after pruning — pruned entries may have affected counts
-            this.rebuildIndex();
+            const pruned = this.entries.splice(0, excess);
+            // Subtract pruned entries from index — O(pruned × w) instead of O(n × w) full rebuild
+            for (const entry of pruned) {
+                this.subtractFromIndex(entry);
+            }
             logger.debug(`Learning store pruned ${excess} oldest entries (cap: ${MAX_LEARNING_ENTRIES})`);
         }
         await this.save();
@@ -164,11 +214,22 @@ export class MemoryLearningStore {
         };
     }
     async record(entry) {
-        this.entries.push(entry);
-        this.updateIndex(entry);
+        const sanitized = {
+            ...entry,
+            query: entry.query
+                .toLowerCase()
+                .split(/\W+/)
+                .filter(w => w.length > 2 && !STOPWORDS.has(w))
+                .join(' '),
+        };
+        this.entries.push(sanitized);
+        this.updateIndex(sanitized);
         if (this.entries.length > MAX_LEARNING_ENTRIES) {
-            this.entries.splice(0, this.entries.length - MAX_LEARNING_ENTRIES);
-            this.rebuildIndex();
+            const excess = this.entries.length - MAX_LEARNING_ENTRIES;
+            const pruned = this.entries.splice(0, excess);
+            for (const entry of pruned) {
+                this.subtractFromIndex(entry);
+            }
         }
     }
     async getStats() {
@@ -178,7 +239,6 @@ export class MemoryLearningStore {
         return structuredClone(this.index);
     }
     updateIndex(entry) {
-        var _a;
         this.statsCounter.totalQueries++;
         if (entry.resolvedVia === 'llm')
             this.statsCounter.llmQueries++;
@@ -191,17 +251,41 @@ export class MemoryLearningStore {
                 .split(/\W+/)
                 .filter(w => w.length > 2 && !STOPWORDS.has(w));
             for (const word of words) {
-                (_a = this.index)[word] ?? (_a[word] = {});
+                this.index[word] ??= {};
                 this.index[word][entry.capabilityId] =
                     (this.index[word][entry.capabilityId] ?? 0) + 1;
             }
         }
     }
-    rebuildIndex() {
-        this.index = {};
-        this.statsCounter = { totalQueries: 0, llmQueries: 0, cacheHits: 0, outOfScope: 0 };
-        for (const entry of this.entries) {
-            this.updateIndex(entry);
+    subtractFromIndex(entry) {
+        if (!entry.capabilityId) {
+            this.statsCounter.outOfScope = Math.max(0, this.statsCounter.outOfScope - 1);
+            this.statsCounter.totalQueries = Math.max(0, this.statsCounter.totalQueries - 1);
+            if (entry.resolvedVia === 'llm')
+                this.statsCounter.llmQueries = Math.max(0, this.statsCounter.llmQueries - 1);
+            if (entry.resolvedVia === 'cache')
+                this.statsCounter.cacheHits = Math.max(0, this.statsCounter.cacheHits - 1);
+            return;
+        }
+        this.statsCounter.totalQueries = Math.max(0, this.statsCounter.totalQueries - 1);
+        if (entry.resolvedVia === 'llm')
+            this.statsCounter.llmQueries = Math.max(0, this.statsCounter.llmQueries - 1);
+        if (entry.resolvedVia === 'cache')
+            this.statsCounter.cacheHits = Math.max(0, this.statsCounter.cacheHits - 1);
+        const words = entry.query.toLowerCase()
+            .split(/\W+/)
+            .filter(w => w.length > 2 && !STOPWORDS.has(w));
+        for (const word of words) {
+            if (!this.index[word])
+                continue;
+            this.index[word][entry.capabilityId] =
+                (this.index[word][entry.capabilityId] ?? 1) - 1;
+            if (this.index[word][entry.capabilityId] <= 0) {
+                delete this.index[word][entry.capabilityId];
+            }
+            if (Object.keys(this.index[word]).length === 0) {
+                delete this.index[word];
+            }
         }
     }
     async getTopCapabilities(limit = 5) {

package/dist/esm/matcher.d.ts

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

package/dist/esm/matcher.js

@@ -1,4 +1,11 @@
 import { logger } from './logger';
+// ─── Typed error for LLM parse failures ──────────────────────────────────────
+export class LLMParseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'LLMParseError';
+    }
+}
 export const STOPWORDS = new Set([
     'show', 'me', 'the', 'get', 'find', 'fetch', 'give', 'please',
     'can', 'you', 'i', 'want', 'to', 'a', 'an', 'my', 'our', 'your',
@@ -65,7 +72,7 @@ export function extractParams(query, cap) {
     for (const param of cap.params) {
         // Session params come from auth context, not query
         if (param.source === 'session') {
-            result[param.name] = '[from_session]';
+            result[param.name] = null; // injected by resolver from auth context — not extracted from query
             continue;
         }
         if (param.source !== 'user_query') {
@@ -117,10 +124,11 @@ export function extractParams(query, cap) {
             const words = query.trim().split(/\s+/);
             const meaningful = words.filter(w => !STOPWORDS.has(w.toLowerCase()));
             const candidate = meaningful[meaningful.length - 1] ?? null;
-            // Only use fallback if candidate looks like an identifier — not a generic noun or verb
+            // Only use fallback if candidate looks like an identifier — not a generic noun, verb,
+            // or category word that would produce junk URLs like /orders/orders or /users/data
             if (candidate &&
                 /^[a-zA-Z0-9_-]{2,}$/.test(candidate) &&
-                !/^(all|new|latest|recent|current|list|get|show|find|fetch|give|open|my|their|your)$/i.test(candidate)) {
+                !/^(all|new|latest|recent|current|list|get|show|find|fetch|give|open|my|their|your|orders|order|items|item|data|results|result|records|record|entries|entry|users|user|products|product|details|info|summary|history|status|feed|content|files|file|documents|document)$/i.test(candidate)) {
                 extracted = candidate;
             }
         }
@@ -184,8 +192,25 @@ export function match(query, manifest) {
         candidates,
     };
 }
+/**
+ * Matches a query to a capability using an LLM.
+ *
+ * ⚠️  SECURITY NOTE: Capability `description` and `examples` fields from the
+ * manifest are injected verbatim into the LLM prompt (system portion).
+ * In a solo deployment with a developer-controlled manifest this is safe.
+ * If your manifest is generated from third-party OpenAPI specs, user-controlled
+ * sources, or any external input, sanitize `description` and `examples` fields
+ * before passing the manifest to this function — adversarial content in those
+ * fields can influence LLM routing decisions.
+ */
 export async function matchWithLLM(query, manifest, options) {
-    const manifestSummary = manifest.capabilities.map(c => `- ${c.id} (${c.resolver.type}): ${c.description}${c.examples?.length ? `\n  examples: ${c.examples.slice(0, 2).join(', ')}` : ''}`).join('\n');
+    // Truncate description and examples — prevents context window overflow and
+    // reduces prompt injection surface from third-party OpenAPI spec content.
+    const MAX_DESC_LEN = 200;
+    const MAX_EXAMPLE_LEN = 100;
+    const manifestSummary = manifest.capabilities.map(c => `- ${c.id} (${c.resolver.type}): ${c.description.slice(0, MAX_DESC_LEN)}${c.description.length > MAX_DESC_LEN ? '…' : ''}${c.examples?.length
+        ? `\n  examples: ${c.examples.slice(0, 2).map(e => e.slice(0, MAX_EXAMPLE_LEN)).join(', ')}`
+        : ''}`).join('\n');
     const prompt = `You are an intent matcher for an AI agent system.
 
 App: ${manifest.app}
@@ -216,13 +241,13 @@ ${JSON.stringify({ user_query: query })}
         parsed = JSON.parse(clean);
     }
     catch {
-        throw new Error(`LLM_PARSE_ERROR: LLM returned invalid JSON. First 300 chars: ${clean.slice(0, 300)}`);
+        throw new LLMParseError(`LLM returned invalid JSON. First 300 chars: ${clean.slice(0, 300)}`);
     }
     if (typeof parsed.matched_capability !== 'string') {
-        throw new Error(`LLM_PARSE_ERROR: missing "matched_capability" field in response`);
+        throw new LLMParseError(`missing "matched_capability" field in response`);
     }
     if (typeof parsed.confidence !== 'number') {
-        throw new Error(`LLM_PARSE_ERROR: missing numeric "confidence" field in response`);
+        throw new LLMParseError(`missing numeric "confidence" field in response`);
     }
     const isOOS = parsed.matched_capability === 'OUT_OF_SCOPE';
     const capability = isOOS
@@ -233,16 +258,21 @@ ${JSON.stringify({ user_query: query })}
     if (!isOOS && capability === null) {
         logger.warn(`LLM returned unknown capability ID: "${parsed.matched_capability}" — treating as out_of_scope`);
     }
+    // Build full candidate list — all capabilities scored, LLM winner marked as matched.
+    // This aligns the shape with keyword match results and allows the learning boost
+    // to surface alternatives if the LLM made a wrong call.
+    const llmConfidence = effectivelyOOS ? 0 : parsed.confidence;
+    const allCandidates = manifest.capabilities.map(c => ({
+        capabilityId: c.id,
+        score: c.id === capability?.id ? llmConfidence : 0,
+        matched: c.id === capability?.id,
+    }));
     return {
         capability,
-        confidence: effectivelyOOS ? 0 : parsed.confidence,
+        confidence: llmConfidence,
         intent: effectivelyOOS ? 'out_of_scope' : parsed.intent,
         extractedParams: (parsed.extracted_params ?? {}),
         reasoning: parsed.reasoning ?? 'No reasoning provided',
-        candidates: capability ? [{
-                capabilityId: capability.id,
-                score: parsed.confidence,
-                matched: true,
-            }] : [],
+        candidates: allCandidates,
     };
 }

package/dist/esm/parser.js

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

package/dist/esm/resolver.js

@@ -44,11 +44,17 @@ export async function resolve(matchResult, params = {}, options = {}) {
         };
     }
     // ── Session param injection ───────────────────────────────────────────────
-    // Inject auth.userId into any params marked as source: 'session'
+    // Inject auth.userId into params marked as source: 'session'
+    // Session params are only injected if they appear as {template} in the path —
+    // they must never leak into the query string as ?user_id=xyz
     const enrichedParams = { ...params };
     if (options.auth?.userId !== undefined && options.auth.userId !== '') {
+        const resolver = capability.resolver;
+        const pathTemplate = resolver.type === 'api' ? resolver.endpoints.map(e => e.path).join('') :
+            resolver.type === 'hybrid' ? resolver.api.endpoints.map(e => e.path).join('') :
+                resolver.type === 'nav' ? resolver.destination : '';
         for (const param of capability.params) {
-            if (param.source === 'session') {
+            if (param.source === 'session' && pathTemplate.includes(`{${param.name}}`)) {
                 enrichedParams[param.name] = options.auth.userId;
                 logger.debug(`Injected session param "${param.name}" (value redacted)`);
             }
@@ -89,6 +95,20 @@ export async function resolve(matchResult, params = {}, options = {}) {
         };
     }
 }
+/**
+ * Resolves an API capability by executing all configured endpoints.
+ *
+ * ⚠️  PARALLEL EXECUTION: All endpoints are fired simultaneously via Promise.all().
+ * If any endpoint fails, the entire result is marked as failed and partial results
+ * are discarded — but side effects from successful endpoints cannot be rolled back.
+ *
+ * Example: a capability with two endpoints [POST /reserve, POST /confirm] will
+ * fire both in parallel. If /confirm fails after /reserve succeeded, the reservation
+ * exists but the caller receives success: false with no indication that /reserve ran.
+ *
+ * For capabilities where ordering or rollback matters, define separate capabilities
+ * with single endpoints and orchestrate them at the application layer.
+ */
 async function resolveApi(resolver, params, options) {
     const startTime = Date.now();
     const retries = options.retries ?? 0;
@@ -96,7 +116,7 @@ async function resolveApi(resolver, params, options) {
     const apiCalls = resolver.endpoints.map(endpoint => ({
         method: endpoint.method,
         url: buildUrl(options.baseUrl ?? '', endpoint.path, params),
-        params,
+        params: Object.fromEntries(Object.entries(params).filter(([, v]) => v !== null && v !== undefined)),
     }));
     if (options.dryRun) {
         return { success: true, resolverType: 'api', apiCalls, durationMs: Date.now() - startTime };
@@ -121,7 +141,7 @@ async function resolveApi(resolver, params, options) {
                     headers: options.headers ?? {},
                     signal: controller.signal,
                     body: ['POST', 'PUT', 'PATCH'].includes(call.method)
-                        ? JSON.stringify(call.params)
+                        ? JSON.stringify(Object.fromEntries(Object.entries(call.params).filter(([, v]) => v !== null && v !== undefined)))
                         : undefined,
                 });
                 clearTimeout(timer);
@@ -185,10 +205,16 @@ function resolveNav(resolver, params) {
             continue;
         const str = String(value);
         validateNavParam(key, str);
-        destination = destination.replace(`{${key}}`, encodeURIComponent(str));
+        destination = destination.replaceAll(`{${key}}`, encodeURIComponent(str));
     }
     return { success: true, resolverType: 'nav', navTarget: destination };
 }
+// Note: buildUrl does not validate param values against an allowlist.
+// resolveNav() does validate via validateNavParam() because nav destinations
+// are used as deep links where path traversal is a real risk.
+// For API URLs, extractParams() strips most dangerous characters upstream,
+// so the practical risk is low — but any future caller bypassing extractParams
+// should add validation here too.
 function buildUrl(baseUrl, urlPath, params) {
     let resolved = urlPath;
     const unused = {};
@@ -196,7 +222,7 @@ function buildUrl(baseUrl, urlPath, params) {
         if (value === null || value === undefined)
             continue; // never write null into URLs
         if (resolved.includes(`{${key}}`)) {
-            resolved = resolved.replace(`{${key}}`, encodeURIComponent(String(value)));
+            resolved = resolved.replaceAll(`{${key}}`, encodeURIComponent(String(value)));
         }
         else {
             unused[key] = value;

package/dist/esm/schema.d.ts

@@ -108,6 +108,7 @@ export declare const CapmanConfigSchema: z.ZodObject<{
                 hint?: string | undefined;
             }>;
         }, "strip", z.ZodTypeAny, {
+            type: "hybrid";
             api: {
                 endpoints: {
                     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -119,8 +120,8 @@ export declare const CapmanConfigSchema: z.ZodObject<{
                 destination: string;
                 hint?: string | undefined;
             };
-            type: "hybrid";
         }, {
+            type: "hybrid";
             api: {
                 endpoints: {
                     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -132,7 +133,6 @@ export declare const CapmanConfigSchema: z.ZodObject<{
                 destination: string;
                 hint?: string | undefined;
             };
-            type: "hybrid";
         }>]>;
         privacy: z.ZodObject<{
             level: z.ZodEnum<["public", "user_owned", "admin"]>;
@@ -168,6 +168,7 @@ export declare const CapmanConfigSchema: z.ZodObject<{
             destination: string;
             hint?: string | undefined;
         } | {
+            type: "hybrid";
             api: {
                 endpoints: {
                     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -179,7 +180,6 @@ export declare const CapmanConfigSchema: z.ZodObject<{
                 destination: string;
                 hint?: string | undefined;
             };
-            type: "hybrid";
         };
         privacy: {
             level: "public" | "user_owned" | "admin";
@@ -210,6 +210,7 @@ export declare const CapmanConfigSchema: z.ZodObject<{
             destination: string;
             hint?: string | undefined;
         } | {
+            type: "hybrid";
             api: {
                 endpoints: {
                     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -221,7 +222,6 @@ export declare const CapmanConfigSchema: z.ZodObject<{
                 destination: string;
                 hint?: string | undefined;
             };
-            type: "hybrid";
         };
         privacy: {
             level: "public" | "user_owned" | "admin";
@@ -252,6 +252,7 @@ export declare const CapmanConfigSchema: z.ZodObject<{
             destination: string;
             hint?: string | undefined;
         } | {
+            type: "hybrid";
             api: {
                 endpoints: {
                     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -263,7 +264,6 @@ export declare const CapmanConfigSchema: z.ZodObject<{
                 destination: string;
                 hint?: string | undefined;
             };
-            type: "hybrid";
         };
         privacy: {
             level: "public" | "user_owned" | "admin";
@@ -294,6 +294,7 @@ export declare const CapmanConfigSchema: z.ZodObject<{
             destination: string;
             hint?: string | undefined;
         } | {
+            type: "hybrid";
             api: {
                 endpoints: {
                     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -305,7 +306,6 @@ export declare const CapmanConfigSchema: z.ZodObject<{
                 destination: string;
                 hint?: string | undefined;
             };
-            type: "hybrid";
         };
         privacy: {
             level: "public" | "user_owned" | "admin";
@@ -339,6 +339,7 @@ export declare const CapmanConfigSchema: z.ZodObject<{
             destination: string;
             hint?: string | undefined;
         } | {
+            type: "hybrid";
             api: {
                 endpoints: {
                     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -350,7 +351,6 @@ export declare const CapmanConfigSchema: z.ZodObject<{
                 destination: string;
                 hint?: string | undefined;
             };
-            type: "hybrid";
         };
         privacy: {
             level: "public" | "user_owned" | "admin";
@@ -385,6 +385,7 @@ export declare const CapmanConfigSchema: z.ZodObject<{
             destination: string;
             hint?: string | undefined;
         } | {
+            type: "hybrid";
             api: {
                 endpoints: {
                     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -396,7 +397,6 @@ export declare const CapmanConfigSchema: z.ZodObject<{
                 destination: string;
                 hint?: string | undefined;
             };
-            type: "hybrid";
         };
         privacy: {
             level: "public" | "user_owned" | "admin";
@@ -516,6 +516,7 @@ export declare const ManifestSchema: z.ZodObject<{
                 hint?: string | undefined;
             }>;
         }, "strip", z.ZodTypeAny, {
+            type: "hybrid";
             api: {
                 endpoints: {
                     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -527,8 +528,8 @@ export declare const ManifestSchema: z.ZodObject<{
                 destination: string;
                 hint?: string | undefined;
             };
-            type: "hybrid";
         }, {
+            type: "hybrid";
             api: {
                 endpoints: {
                     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -540,7 +541,6 @@ export declare const ManifestSchema: z.ZodObject<{
                 destination: string;
                 hint?: string | undefined;
             };
-            type: "hybrid";
         }>]>;
         privacy: z.ZodObject<{
             level: z.ZodEnum<["public", "user_owned", "admin"]>;
@@ -576,6 +576,7 @@ export declare const ManifestSchema: z.ZodObject<{
             destination: string;
             hint?: string | undefined;
         } | {
+            type: "hybrid";
             api: {
                 endpoints: {
                     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -587,7 +588,6 @@ export declare const ManifestSchema: z.ZodObject<{
                 destination: string;
                 hint?: string | undefined;
             };
-            type: "hybrid";
         };
         privacy: {
             level: "public" | "user_owned" | "admin";
@@ -618,6 +618,7 @@ export declare const ManifestSchema: z.ZodObject<{
             destination: string;
             hint?: string | undefined;
         } | {
+            type: "hybrid";
             api: {
                 endpoints: {
                     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -629,7 +630,6 @@ export declare const ManifestSchema: z.ZodObject<{
                 destination: string;
                 hint?: string | undefined;
             };
-            type: "hybrid";
         };
         privacy: {
             level: "public" | "user_owned" | "admin";
@@ -664,6 +664,7 @@ export declare const ManifestSchema: z.ZodObject<{
             destination: string;
             hint?: string | undefined;
         } | {
+            type: "hybrid";
             api: {
                 endpoints: {
                     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -675,7 +676,6 @@ export declare const ManifestSchema: z.ZodObject<{
                 destination: string;
                 hint?: string | undefined;
             };
-            type: "hybrid";
         };
         privacy: {
             level: "public" | "user_owned" | "admin";
@@ -711,6 +711,7 @@ export declare const ManifestSchema: z.ZodObject<{
             destination: string;
             hint?: string | undefined;
         } | {
+            type: "hybrid";
             api: {
                 endpoints: {
                     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -722,7 +723,6 @@ export declare const ManifestSchema: z.ZodObject<{
                 destination: string;
                 hint?: string | undefined;
             };
-            type: "hybrid";
         };
         privacy: {
             level: "public" | "user_owned" | "admin";

package/dist/esm/schema.js

@@ -50,8 +50,10 @@ const CapabilitySchema = z.object({
     id: z.string().min(1, 'capability id is required')
         .regex(/^[a-z0-9_]+$/, 'id must be snake_case (lowercase, numbers, underscores only)'),
     name: z.string().min(1, 'capability name is required'),
-    description: z.string().min(10, 'description must be at least 10 characters for accurate matching'),
-    examples: z.array(z.string()).optional(),
+    description: z.string()
+        .min(10, 'description must be at least 10 characters for accurate matching')
+        .max(500, 'description must be 500 characters or fewer'),
+    examples: z.array(z.string().max(200, 'each example must be 200 characters or fewer')).optional(),
     params: z.array(CapabilityParamSchema),
     returns: z.array(z.string()),
     resolver: ResolverSchema,

package/dist/esm/types.d.ts

@@ -134,3 +134,4 @@ export interface ExplainResult {
     resolvedVia: 'keyword' | 'llm';
     durationMs: number;
 }
+export type MatchMode = 'cheap' | 'balanced' | 'accurate';

package/dist/esm/version.d.ts

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

package/dist/esm/version.js

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