capman 0.6.0 → 0.6.1

package/dist/esm/matcher.js

@@ -136,15 +136,19 @@ export function tokenize(text) {
 export function buildBM25Index(capabilities) {
     const N = capabilities.length;
     if (N === 0)
-        return { df: {}, avgdl: { examples: 0, description: 0, name: 0 }, N: 0, bigrams: {}, };
+        return { df: {}, avgdl: { examples: 0, description: 0, name: 0 }, N: 0, bigrams: {}, capTokens: {}, };
     const df = {};
     let totalExLen = 0;
     let totalDescLen = 0;
     let totalNameLen = 0;
+    // Pre-compute token arrays for every capability in a single pass.
+    // scoreCapability() reads from capTokens instead of re-tokenizing on every call.
+    const capTokens = {};
     for (const cap of capabilities) {
         const exTokens = tokenize((cap.examples ?? []).join(' '));
         const descTokens = tokenize(cap.description);
         const nameTokens = tokenize(cap.name);
+        capTokens[cap.id] = { examples: exTokens, description: descTokens, name: nameTokens };
         totalExLen += exTokens.length;
         totalDescLen += descTokens.length;
         totalNameLen += nameTokens.length;
@@ -177,6 +181,7 @@ export function buildBM25Index(capabilities) {
         },
         N,
         bigrams,
+        capTokens,
     };
 }
 /**
@@ -187,9 +192,17 @@ export function buildBM25Index(capabilities) {
 export function scoreCapability(qWordSet, cap, index, k1 = 1.5, b = 0.75) {
     if (index.N === 0)
         return 0;
-    const score = bm25Field(qWordSet, tokenize((cap.examples ?? []).join(' ')), index, 'examples', k1, b) * 0.6
-        + bm25Field(qWordSet, tokenize(cap.description), index, 'description', k1, b) * 0.3
-        + bm25Field(qWordSet, tokenize(cap.name), index, 'name', k1, b) * 0.1;
+    // Use pre-computed token arrays from the index — avoids re-tokenizing
+    // capability text on every call. Falls back to live tokenization only when
+    // scoreCapability() is called outside CapmanEngine (e.g. unit tests that
+    // build a BM25Index manually without capTokens populated).
+    const tokens = index.capTokens[cap.id];
+    const exTokens = tokens?.examples ?? tokenize((cap.examples ?? []).join(' '));
+    const descTokens = tokens?.description ?? tokenize(cap.description);
+    const nameTokens = tokens?.name ?? tokenize(cap.name);
+    const score = bm25Field(qWordSet, exTokens, index, 'examples', k1, b) * 0.6
+        + bm25Field(qWordSet, descTokens, index, 'description', k1, b) * 0.3
+        + bm25Field(qWordSet, nameTokens, index, 'name', k1, b) * 0.1;
     return score;
 }
 function bm25Field(queryTerms, fieldTokens, index, field, k1, b) {
@@ -224,6 +237,32 @@ export function extractBigrams(tokens) {
     }
     return bigrams;
 }
+/**
+ * Returns a sub-manifest containing only capabilities that match ALL provided tags.
+ * Capabilities without tags are excluded when tags filter is active.
+ * Enables token-efficient LLM prompts for large manifests:
+ *
+ * @example
+ * // Only send order-related capabilities to LLM
+ * const orderManifest = filterByTags(manifest, ['orders'])
+ * const result = await matchWithLLM(query, orderManifest, { llm })
+ *
+ * @example
+ * // Match by any of multiple tags (union) — call filterByTags per tag and merge
+ * const ordersOrPayments = [
+ *   ...filterByTags(manifest, ['orders']).capabilities,
+ *   ...filterByTags(manifest, ['payments']).capabilities,
+ * ]
+ */
+export function filterByTags(manifest, tags) {
+    if (tags.length === 0)
+        return manifest;
+    const tagSet = new Set(tags);
+    return {
+        ...manifest,
+        capabilities: manifest.capabilities.filter(cap => cap.tags?.length && tags.every(t => cap.tags.includes(t))),
+    };
+}
 /**
  * Returns a fixed bonus in normalized points (0–15), applied after BM25 normalization.
  * 5 points per matching bigram, saturates at 3 bigrams (15 points).
@@ -252,13 +291,18 @@ export function resolverToIntent(cap) {
 /**
  * Strips characters that could break LLM prompt structure from
  * capability field values before injection into the system prompt.
- * Removes control characters, newlines, and delimiter-like sequences.
+ * Removes control characters, newlines, delimiter sequences, and braces
+ * anywhere in the string (not just at line starts) to resist prompt injection
+ * from third-party OpenAPI spec content ingested via parseOpenAPI().
  */
 export function sanitizeForPrompt(value, maxLen) {
     return value
-        .replace(/[\r\n\t]/g, ' ') // newlines → space
+        .replace(/[\r\n\t]/g, ' ') // newlines/tabs → space
         .replace(/---+/g, '—') // horizontal rules → em dash
-        .replace(/^\s*[{}\[\]]/gm, ' ') // leading braces/brackets → space
+        .replace(/[{}\[\]]/g, ' ') // all braces/brackets anywhere → space (was: leading only)
+        .split(' ') // per-word cap — limits injection payload per token
+        .map(w => w.slice(0, 200)) // no single token longer than 200 chars
+        .join(' ')
         .replace(/\s+/g, ' ') // collapse whitespace
         .trim()
         .slice(0, maxLen);
@@ -290,11 +334,28 @@ export function extractParams(query, cap) {
             result[param.name] = null;
             continue;
         }
-        // ── Pattern extraction (highest priority) ─────────────────────────────
+        // ── Type-implied pattern extraction ───────────────────────────────────
+        // param.type implies a TYPE_PATTERNS match — no need to set pattern explicitly
+        if (param.type && !param.pattern) {
+            // Map param types that have direct regex equivalents
+            const typeToPattern = {
+                email: TYPE_PATTERNS.email,
+                date: TYPE_PATTERNS.date,
+                url: TYPE_PATTERNS.url,
+            };
+            const impliedPattern = typeToPattern[param.type];
+            if (impliedPattern) {
+                const match = query.match(impliedPattern);
+                if (match) {
+                    result[param.name] = match[0];
+                    continue;
+                }
+            }
+        }
+        // ── Explicit pattern extraction (highest priority when set) ───────────
         if (param.pattern) {
             const namedPattern = TYPE_PATTERNS[param.pattern];
             if (namedPattern) {
-                // Named type pattern — match regex directly against full query
                 const match = query.match(namedPattern);
                 if (match) {
                     result[param.name] = match[0];
@@ -302,7 +363,6 @@ export function extractParams(query, cap) {
                 }
             }
             else if (param.pattern.includes(`{${param.name}}`)) {
-                // Example template — positional extraction
                 const extracted = extractFromTemplate(query, param.pattern, param.name);
                 if (extracted) {
                     result[param.name] = extracted;
@@ -363,10 +423,36 @@ export function extractParams(query, cap) {
                 extracted = candidate;
             }
         }
+        // ── Enum validation ───────────────────────────────────────────────────
+        if (extracted !== null && param.type === 'enum' && param.enum?.length) {
+            if (!param.enum.includes(extracted)) {
+                // Extracted value not in allowed list — treat as not found
+                extracted = null;
+            }
+        }
         result[param.name] = extracted;
     }
     return result;
 }
+/**
+ * Calibrates a BM25 normalization ceiling from the manifest.
+ * Scores each capability against all of its own examples and returns the maximum.
+ * Call once at manifest load time — O(capabilities × examples).
+ */
+export function calibrateCeiling(capabilities, bm25Index, k1, b) {
+    let max = 0;
+    for (const cap of capabilities) {
+        if (!cap.examples?.length)
+            continue;
+        for (const example of cap.examples) {
+            const selfWords = new Set(tokenize(example));
+            const raw = scoreCapability(selfWords, cap, bm25Index, k1, b);
+            if (raw > max)
+                max = raw;
+        }
+    }
+    return max > 0 ? max : 100;
+}
 export function match(query, manifest, options = {}) {
     if (!query?.trim()) {
         logger.warn('Empty query received');
@@ -441,18 +527,7 @@ export function match(query, manifest, options = {}) {
     const k1 = options.bm25K1 ?? 1.5;
     const b = options.bm25B ?? 0.75;
     // Calibrate ceiling — max self-score for normalization
-    const ceiling = options.bm25Ceiling ?? (() => {
-        let max = 0;
-        for (const cap of manifest.capabilities) {
-            if (!cap.examples?.length)
-                continue;
-            const selfWords = new Set(tokenize(cap.examples[0]));
-            const raw = scoreCapability(selfWords, cap, bm25Index, k1, b);
-            if (raw > max)
-                max = raw;
-        }
-        return max > 0 ? max : 100;
-    })();
+    const ceiling = options.bm25Ceiling ?? calibrateCeiling(manifest.capabilities, bm25Index, k1, b);
     const allScores = [];
     for (const cap of manifest.capabilities) {
         const rawBM25 = scoreCapability(qWordSet, cap, bm25Index, k1, b);
@@ -575,7 +650,13 @@ ${JSON.stringify({ user_query: query })}
     // 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;
+    // Clamp and round confidence — LLM may return values outside 0–100 with
+    // misconfigured models or prompt drift. Unclamped values corrupt learning
+    // weights (weight = confidence/100 can exceed 1.0) and verdict margins.
+    // disambiguateLLM() already does this; apply the same treatment here.
+    const llmConfidence = effectivelyOOS
+        ? 0
+        : Math.min(100, Math.max(0, Math.round(parsed.confidence)));
     const allCandidates = manifest.capabilities.map(c => ({
         capabilityId: c.id,
         score: c.id === capability?.id ? llmConfidence : 0,

package/dist/esm/parser.js

@@ -31,7 +31,16 @@ async function loadSpec(source) {
         return parseSpecText(text, source);
     }
     // Local file
-    const resolved = path.resolve(process.cwd(), source);
+    const cwd = process.cwd();
+    const resolved = path.resolve(cwd, source);
+    // Guard against path traversal — same check used by FileCache and FileLearningStore.
+    // Prevents parseOpenAPI('../../etc/passwd') from reading arbitrary files when
+    // the source argument comes from user input (CLI args, UI, CI scripts).
+    const allowedPrefix = cwd === '/' ? '/' : cwd + path.sep;
+    if (!resolved.startsWith(allowedPrefix)) {
+        throw new Error(`Spec path "${source}" resolves outside the working directory.\n` +
+            `Resolved: ${resolved}\nAllowed:  ${cwd}`);
+    }
     if (!fs.existsSync(resolved)) {
         throw new Error(`Spec file not found: ${resolved}`);
     }
@@ -101,11 +110,20 @@ function convertSpec(spec) {
                 warnings.push(`Skipped ${method} ${urlPath} — no useful info to generate capability`);
                 continue;
             }
-            // Check for duplicate IDs
-            const existing = capabilities.find(c => c.id === result.id);
-            if (existing) {
-                result.id = `${result.id}_${method.toLowerCase()}`;
-                warnings.push(`Duplicate ID resolved: ${result.id}`);
+            // De-conflict duplicate IDs — loop until the candidate ID is unique.
+            // A single find() check is insufficient: if two operations both produce
+            // `get_user`, the second becomes `get_user_get`. A third `get_user` would
+            // then collide with `get_user_get` only when it also uses GET — the general
+            // multi-collision case is only caught by looping.
+            let candidateId = result.id;
+            let dedupeCount = 0;
+            while (capabilities.find(c => c.id === candidateId)) {
+                dedupeCount++;
+                candidateId = `${result.id}_${method.toLowerCase()}${dedupeCount > 1 ? `_${dedupeCount}` : ''}`;
+            }
+            if (candidateId !== result.id) {
+                warnings.push(`Duplicate ID resolved: ${result.id} → ${candidateId}`);
+                result.id = candidateId;
             }
             capabilities.push(result);
         }
@@ -259,9 +277,9 @@ function extractBaseUrl(spec) {
         const base = spec.basePath ?? '';
         return `${scheme}://${spec.host}${base}`.replace(/\/$/, '');
     }
-    logger.warn(`No server URL found in spec — using placeholder "https://api.your-app.com". ` +
-        `Set baseUrl manually in the generated config before use.`);
-    return 'https://api.your-app.com';
+    throw new Error(`No server URL found in OpenAPI spec — cannot determine base URL.\n` +
+        `Add a "servers" entry (OpenAPI 3.x) or "host" + "basePath" (Swagger 2.x), ` +
+        `or set baseUrl manually in capman.config.js after generating.`);
 }
 function sanitizeAppName(title) {
     return title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');

package/dist/esm/resolver.d.ts

@@ -1,4 +1,4 @@
-import type { MatchResult, ResolveResult } from './types';
+import type { MatchResult, ResolveResult, Capability } from './types';
 export interface AuthContext {
     /** Whether the current request is authenticated */
     isAuthenticated: boolean;
@@ -25,5 +25,5 @@ export interface ResolveOptions {
      */
     retryAllMethods?: boolean;
 }
-export declare function checkPrivacy(capability: import('./types').Capability, auth?: AuthContext): string | null;
+export declare function checkPrivacy(capability: Capability, auth?: AuthContext): string | null;
 export declare function resolve(matchResult: MatchResult, params?: Record<string, unknown>, options?: ResolveOptions): Promise<ResolveResult>;

package/dist/esm/resolver.js

@@ -68,13 +68,13 @@ export async function resolve(matchResult, params = {}, options = {}) {
             .map(p => p.name));
         switch (resolver.type) {
             case 'api':
-                return await resolveApi(resolver, enrichedParams, options, sessionParamNames);
+                return await resolveApi(resolver, enrichedParams, options, sessionParamNames, capability.errors ?? []);
             case 'nav':
                 return resolveNav(resolver, enrichedParams);
             case 'hybrid': {
                 logger.debug('Hybrid resolver — running API and nav in parallel');
                 const [apiResult, navResult] = await Promise.all([
-                    resolveApi(resolver.api, enrichedParams, options, sessionParamNames),
+                    resolveApi(resolver.api, enrichedParams, options, sessionParamNames, capability.errors ?? []),
                     Promise.resolve(resolveNav(resolver.nav, enrichedParams)),
                 ]);
                 return {
@@ -116,23 +116,27 @@ export async function resolve(matchResult, params = {}, options = {}) {
  * Full partial success reporting (partialSuccess, completedCalls, failedCalls)
  * is planned for a future version.
  */
-async function resolveApi(resolver, params, options, sessionParamNames = new Set()) {
+async function resolveApi(resolver, params, options, sessionParamNames = new Set(), capabilityErrors = []) {
     const startTime = Date.now();
     const retries = options.retries ?? 0;
     const timeoutMs = options.timeoutMs ?? 5000;
+    // Map url → endpoint metadata for idempotency and Idempotency-Key injection
+    const endpointMeta = new Map();
     const apiCalls = resolver.endpoints.map(endpoint => {
-        // Build per-endpoint params — only inject session params if this
-        // specific endpoint has the placeholder. Prevents userId leaking
-        // as ?user_id=xyz on endpoints that don't use it in their path.
         const endpointParams = { ...params };
         for (const name of sessionParamNames) {
             if (!endpoint.path.includes(`{${name}}`)) {
-                delete endpointParams[name]; // strip session param — not in this endpoint's path
+                delete endpointParams[name];
             }
         }
+        const url = buildUrl(options.baseUrl ?? '', endpoint.path, endpointParams, sessionParamNames);
+        endpointMeta.set(url, {
+            idempotent: endpoint.idempotent,
+            idempotencyKey: endpoint.idempotencyKey,
+        });
         return {
             method: endpoint.method,
-            url: buildUrl(options.baseUrl ?? '', endpoint.path, endpointParams, sessionParamNames),
+            url,
             params: Object.fromEntries(Object.entries(endpointParams).filter(([, v]) => v !== null && v !== undefined)),
         };
     });
@@ -151,23 +155,42 @@ async function resolveApi(resolver, params, options, sessionParamNames = new Set
     // Only retry safe/idempotent methods — retrying POST/PUT/PATCH/DELETE
     // can cause duplicate side effects (e.g. duplicate orders, double charges).
     async function fetchWithRetry(call) {
-        const effectiveRetries = (options.retryAllMethods || SAFE_METHODS.has(call.method))
-            ? retries
-            : 0;
-        let lastErr;
+        const meta = endpointMeta.get(call.url);
+        // Explicit idempotent flag overrides method-based default
+        const isIdempotent = meta?.idempotent !== undefined
+            ? meta.idempotent
+            : SAFE_METHODS.has(call.method);
+        const effectiveRetries = (options.retryAllMethods || isIdempotent) ? retries : 0;
+        let lastErr = new Error('fetchWithRetry: exhausted all attempts without result');
         for (let attempt = 0; attempt <= effectiveRetries; attempt++) {
             const controller = new AbortController();
             const timer = setTimeout(() => controller.abort(), timeoutMs);
             try {
+                // Inject Idempotency-Key header when configured
+                const idempotencyHeaders = {};
+                if (meta?.idempotencyKey) {
+                    const keyValue = call.params[meta.idempotencyKey];
+                    if (keyValue !== null && keyValue !== undefined) {
+                        idempotencyHeaders['Idempotency-Key'] = String(keyValue);
+                    }
+                }
                 const res = await fetchFn(call.url, {
                     method: call.method,
-                    headers: options.headers ?? {},
+                    headers: { ...options.headers ?? {}, ...idempotencyHeaders },
                     signal: controller.signal,
                     body: ['POST', 'PUT', 'PATCH'].includes(call.method)
                         ? JSON.stringify(Object.fromEntries(Object.entries(call.params).filter(([, v]) => v !== null && v !== undefined)))
                         : undefined,
                 });
                 clearTimeout(timer);
+                // Throw on retryable 5xx — fetch() resolves (doesn't throw) on HTTP errors,
+                // so without this check a 503 is returned immediately with no retry.
+                // 4xx errors are not retried — they are client errors that won't change.
+                if (res.status >= 500 && attempt < effectiveRetries) {
+                    lastErr = new Error(`HTTP ${res.status}`);
+                    logger.warn(`Server error ${res.status} (attempt ${attempt + 1}/${effectiveRetries + 1}) — retrying`);
+                    continue;
+                }
                 return res;
             }
             catch (err) {
@@ -184,32 +207,49 @@ async function resolveApi(resolver, params, options, sessionParamNames = new Set
         }
         throw lastErr;
     }
+    let enrichedCalls = apiCalls.map(c => ({ ...c }));
     try {
-        const responses = await Promise.all(apiCalls.map(c => fetchWithRetry(c)));
-        const failedIdx = responses.findIndex(r => !r.ok);
-        if (failedIdx !== -1) {
-            const failed = responses[failedIdx];
-            return {
-                success: false, resolverType: 'api', apiCalls,
-                durationMs: Date.now() - startTime,
-                error: `API request failed: ${failed.status} ${failed.statusText}`,
-            };
-        }
-        const enrichedCalls = await Promise.all(responses.map(async (res, i) => {
+        const settled = await Promise.allSettled(apiCalls.map(c => fetchWithRetry(c)));
+        enrichedCalls = await Promise.all(settled.map(async (result, i) => {
+            if (result.status === 'rejected') {
+                const reason = result.reason;
+                logger.warn(`Endpoint ${apiCalls[i].method} ${apiCalls[i].url} failed: ${reason}`);
+                return {
+                    ...apiCalls[i],
+                    status: 0,
+                    error: reason instanceof Error ? reason.message : String(reason),
+                };
+            }
+            const res = result.value;
             let data = undefined;
             try {
                 const text = await res.text();
                 data = text ? JSON.parse(text) : undefined;
             }
-            catch { /* non-JSON response */ }
+            catch { /* non-JSON response body */ }
             return { ...apiCalls[i], status: res.status, data };
         }));
+        const failedCall = enrichedCalls.find(c => typeof c.status === 'number' && (c.status === 0 || c.status >= 400));
+        if (failedCall) {
+            const matchedError = capabilityErrors.find(e => e.httpStatus === failedCall.status);
+            const statusLabel = failedCall.status === 0 ? 'network failure' : String(failedCall.status);
+            return {
+                success: false,
+                resolverType: 'api',
+                apiCalls: enrichedCalls,
+                durationMs: Date.now() - startTime,
+                error: matchedError
+                    ? `${matchedError.code}: ${matchedError.description}`
+                    : `API request failed: ${statusLabel} on ${failedCall.method} ${failedCall.url}`,
+                matchedError,
+            };
+        }
         logger.debug(`API calls completed in ${Date.now() - startTime}ms`);
         return { success: true, resolverType: 'api', apiCalls: enrichedCalls, durationMs: Date.now() - startTime };
     }
     catch (err) {
         return {
-            success: false, resolverType: 'api', apiCalls,
+            success: false, resolverType: 'api', apiCalls: enrichedCalls,
             durationMs: Date.now() - startTime,
             error: err instanceof Error ? err.message : String(err),
         };