capman 0.5.1 → 0.5.2

package/dist/esm/learning.d.ts

@@ -61,7 +61,6 @@ export declare class MemoryLearningStore implements LearningStore {
     getIndex(): Promise<Record<string, Record<string, number>>>;
     private updateIndex;
     private subtractFromIndex;
-    private rebuildIndex;
     getTopCapabilities(limit?: number): Promise<Array<{
         id: string;
         hits: number;

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,7 +78,7 @@ 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;
             }
@@ -155,8 +161,19 @@ 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;
             const pruned = this.entries.splice(0, excess);
@@ -197,8 +214,16 @@ 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) {
             const excess = this.entries.length - MAX_LEARNING_ENTRIES;
             const pruned = this.entries.splice(0, excess);
@@ -214,7 +239,6 @@ export class MemoryLearningStore {
         return structuredClone(this.index);
     }
     updateIndex(entry) {
-        var _a;
         this.statsCounter.totalQueries++;
         if (entry.resolvedVia === 'llm')
             this.statsCounter.llmQueries++;
@@ -227,7 +251,7 @@ 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;
             }
@@ -264,13 +288,6 @@ export class MemoryLearningStore {
             }
         }
     }
-    rebuildIndex() {
-        this.index = {};
-        this.statsCounter = { totalQueries: 0, llmQueries: 0, cacheHits: 0, outOfScope: 0 };
-        for (const entry of this.entries) {
-            this.updateIndex(entry);
-        }
-    }
     async getTopCapabilities(limit = 5) {
         return computeTopCapabilities(this.entries, limit);
     }

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'];
 /**

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') {
@@ -197,7 +204,13 @@ export function match(query, manifest) {
  * 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}
@@ -228,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
@@ -245,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

@@ -11,7 +11,7 @@ async function loadSpec(source) {
     if (source.startsWith('http://') || source.startsWith('https://')) {
         logger.info(`Fetching OpenAPI spec from: ${source}`);
         const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), 10000);
+        const timer = setTimeout(() => controller.abort(), 10_000);
         // eslint-disable-next-line prefer-const
         let res;
         try {
@@ -36,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

@@ -95,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;
@@ -102,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 };
@@ -127,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);
@@ -191,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 = {};
@@ -202,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.1";
+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.1';
+export const VERSION = '0.5.2';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "capman",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Capability Manifest Engine — let AI agents interact with your app without navigating the UI",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",