capman 0.5.4 → 0.5.5

package/dist/esm/matcher.js

@@ -21,10 +21,8 @@ export const STOPWORDS = new Set([
 function filterStopwords(words) {
     return words.filter(w => !STOPWORDS.has(w.toLowerCase()) && w.length > 1);
 }
-function scoreCapability(query, cap) {
-    const q = query.toLowerCase();
+function scoreCapability(qWordSet, cap) {
     let score = 0;
-    const qWords = filterStopwords(q.split(/\W+/).filter(Boolean));
     // Check examples — take the best single example match, not the sum.
     // Accumulating across examples rewards bloated example lists over precise ones:
     // 10 examples at 50% overlap = 300 points (clamped to 60) beats 1 perfect example at 60.
@@ -34,21 +32,23 @@ function scoreCapability(query, cap) {
         const exWords = filterStopwords(example.toLowerCase().split(/\s+/));
         if (exWords.length === 0)
             continue;
-        const overlap = exWords.filter(w => qWords.includes(w)).length;
+        const overlap = exWords.filter(w => qWordSet.has(w)).length;
         const contribution = (overlap / exWords.length) * 60;
         bestExampleScore = Math.max(bestExampleScore, contribution);
     }
     score += bestExampleScore;
-    // Check description words
+    // Check description words — normalize against min(length, 10) to avoid
+    // penalizing rich documentation (many words = lower ratio) while also
+    // preventing single-word descriptions from maxing out on any match.
     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;
+        const descOverlap = descWords.filter(w => qWordSet.has(w)).length;
+        score += Math.min((descOverlap / Math.min(descWords.length, 10)) * 30, 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;
+        const nameOverlap = nameWords.filter(w => qWordSet.has(w)).length;
         score += (nameOverlap / nameWords.length) * 10;
     }
     return Math.min(Math.round(score), 100);
@@ -63,14 +63,33 @@ export function resolverToIntent(cap) {
         return 'hybrid';
     return 'out_of_scope';
 }
+/**
+ * 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.
+ */
+function sanitizeForPrompt(value, maxLen) {
+    return value
+        .replace(/[\r\n\t]/g, ' ') // newlines → space
+        .replace(/---+/g, '—') // horizontal rules → em dash
+        .replace(/^\s*[{}\[\]]/gm, ' ') // leading braces/brackets → space
+        .replace(/\s+/g, ' ') // collapse whitespace
+        .trim()
+        .slice(0, maxLen);
+}
 /**
  * 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
+ * - Required param fallback grabs the last meaningful word — "list all
+ *   recent orders" may extract "orders" even with the denylist extended.
+ *   For precise extraction of complex queries, use matchWithLLM() which
+ *   handles param extraction via structured LLM prompt.
+ * - To support richer extraction patterns, add a `pattern` field to
+ *   CapabilityParam in a future version.
  */
 export function extractParams(query, cap) {
     const result = {};
@@ -205,9 +224,11 @@ export function match(query, manifest, options = {}) {
         }
     }
     // ── Score all capabilities ────────────────────────────────────────────────
+    // Build qWordSet once — O(1) lookups instead of O(n) Array.includes per word
+    const qWordSet = new Set(filterStopwords(query.toLowerCase().split(/\W+/).filter(Boolean)));
     const allScores = [];
     for (const cap of manifest.capabilities) {
-        const keywordScore = scoreCapability(query, cap);
+        const keywordScore = scoreCapability(qWordSet, cap);
         const fuzzyScore = fuzzyScoreMap.get(cap.id) ?? 0;
         const via = fuzzyScore > keywordScore ? 'fuzzy' : 'keyword';
         const score = Math.min(100, Math.round(Math.max(keywordScore, fuzzyScore)));
@@ -255,25 +276,28 @@ export function match(query, manifest, options = {}) {
 /**
  * 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.
+ * ⚠️  SECURITY NOTE: Capability fields are sanitized before injection into
+ * the LLM prompt (newlines stripped, delimiters neutralized, length capped).
+ * However, the current interface passes a single prompt string — it cannot
+ * provide true system/user message separation that some LLM APIs support.
+ * For maximum injection resistance in high-security deployments, use an LLM
+ * wrapper that maps the prompt to a proper system message, keeping user query
+ * data in the user turn only.
  */
 export async function matchWithLLM(query, manifest, options) {
     // 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(', ')}`
+    const manifestSummary = manifest.capabilities.map(c => `- ${c.id} (${c.resolver.type}): ${sanitizeForPrompt(c.description, MAX_DESC_LEN)}${c.examples?.length
+        ? `\n  examples: ${c.examples.slice(0, 2).map(e => sanitizeForPrompt(e, MAX_EXAMPLE_LEN)).join(', ')}`
         : ''}`).join('\n');
+    // Sanitize app name — strip newlines and control characters that could
+    // break the prompt structure or inject additional instructions.
+    const safeApp = sanitizeForPrompt(manifest.app, 100);
     const prompt = `You are an intent matcher for an AI agent system.
 
-App: ${manifest.app}
+  App: ${safeApp}
 
 Available capabilities:
 ${manifestSummary}
@@ -331,7 +355,32 @@ ${JSON.stringify({ user_query: query })}
         capability,
         confidence: llmConfidence,
         intent: effectivelyOOS ? 'out_of_scope' : parsed.intent,
-        extractedParams: (parsed.extracted_params ?? {}),
+        extractedParams: (() => {
+            // Validate extracted params against declared capability params.
+            // Rejects nested objects ("[object Object]" in URLs), unknown keys,
+            // and non-scalar values. For OOS results (capability === null),
+            // drops all params — correct since there's no capability to match against.
+            const rawParams = (parsed.extracted_params ?? {});
+            const validParams = {};
+            for (const param of capability?.params ?? []) {
+                const val = rawParams[param.name];
+                if (val === null || val === undefined) {
+                    validParams[param.name] = null;
+                }
+                else if (typeof val === 'string') {
+                    validParams[param.name] = val;
+                }
+                else if (typeof val === 'number' || typeof val === 'boolean') {
+                    validParams[param.name] = String(val);
+                }
+                else {
+                    // Reject complex types (objects, arrays) — would produce "[object Object]" in URLs
+                    logger.warn(`LLM returned non-scalar value for param "${param.name}" — dropping`);
+                    validParams[param.name] = null;
+                }
+            }
+            return validParams;
+        })(),
         reasoning: parsed.reasoning ?? 'No reasoning provided',
         candidates: allCandidates,
     };

package/dist/esm/parser.js

@@ -166,7 +166,7 @@ function extractParams(op) {
             continue;
         const source = p.in === 'path' ? 'user_query' :
             p.in === 'query' ? 'user_query' :
-                'context';
+                'user_query'; // body/formData (Swagger 2.x) — treat as user_query
         params.push({
             name: toSnakeCase(p.name),
             description: p.description ?? toHumanName(p.name),
@@ -201,13 +201,17 @@ function inferPrivacy(op, hasGlobalAuth, securitySchemes) {
     // Explicitly no security on this operation
     if (op.security !== undefined && op.security.length === 0)
         return 'public';
-    // Check operation tags for admin hints
-    const tags = (op.tags ?? []).map(t => t.toLowerCase());
-    if (tags.some(t => t.includes('admin') || t.includes('internal')))
+    // Check operation tags for admin hints — word-boundary match only.
+    // Avoids false positives like 'manageWishlist', 'fileManager', 'managedService'
+    // being classified as admin when they are user-facing operations.
+    const ADMIN_PATTERN = /\b(admin|administrator|backoffice|back-office|internal|superuser)\b/i;
+    const tags = op.tags ?? [];
+    if (tags.some(t => ADMIN_PATTERN.test(t)))
         return 'admin';
-    // Check operation ID / summary for admin hints
+    // Check operation ID / summary — same word-boundary pattern.
+    // 'manage' alone is NOT an admin signal — too many user-facing ops use it.
     const hint = `${op.operationId ?? ''} ${op.summary ?? ''}`.toLowerCase();
-    if (hint.includes('admin') || hint.includes('manage') || hint.includes('internal')) {
+    if (ADMIN_PATTERN.test(hint)) {
         return 'admin';
     }
     // If global auth exists or operation has security, it's user_owned
@@ -248,12 +252,15 @@ function extractBaseUrl(spec) {
     if (spec.servers?.length) {
         return spec.servers[0].url.replace(/\/$/, '');
     }
-    // Swagger 2.x
+    // Swagger 2.x — respect declared schemes, prefer https over http
     if (spec.host) {
-        const scheme = 'https';
+        const schemes = spec.schemes ?? ['https'];
+        const scheme = schemes.includes('https') ? 'https' : schemes[0] ?? 'https';
         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';
 }
 function sanitizeAppName(title) {

package/dist/esm/resolver.d.ts

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

package/dist/esm/resolver.js

@@ -4,7 +4,7 @@ const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
 function redactParams(params) {
     return Object.fromEntries(Object.entries(params).map(([k, v]) => [k, v != null ? '[REDACTED]' : 'null']));
 }
-function checkPrivacy(capability, auth) {
+export function checkPrivacy(capability, auth) {
     const level = capability.privacy.level;
     if (level === 'public')
         return null;
@@ -109,6 +109,12 @@ export async function resolve(matchResult, params = {}, options = {}) {
  *
  * For capabilities where ordering or rollback matters, define separate capabilities
  * with single endpoints and orchestrate them at the application layer.
+ *
+ * Note: the current ResolveResult does not expose which endpoints succeeded and
+ * which failed in a partial failure scenario. If your use case requires this
+ * granularity, use separate single-endpoint capabilities and inspect each result.
+ * Full partial success reporting (partialSuccess, completedCalls, failedCalls)
+ * is planned for a future version.
  */
 async function resolveApi(resolver, params, options, sessionParamNames = new Set()) {
     const startTime = Date.now();
@@ -126,7 +132,7 @@ async function resolveApi(resolver, params, options, sessionParamNames = new Set
         }
         return {
             method: endpoint.method,
-            url: buildUrl(options.baseUrl ?? '', endpoint.path, endpointParams),
+            url: buildUrl(options.baseUrl ?? '', endpoint.path, endpointParams, sessionParamNames),
             params: Object.fromEntries(Object.entries(endpointParams).filter(([, v]) => v !== null && v !== undefined)),
         };
     });
@@ -210,9 +216,12 @@ async function resolveApi(resolver, params, options, sessionParamNames = new Set
     }
 }
 function validateNavParam(key, value) {
-    if (!/^[a-zA-Z0-9_\-]+$/.test(value)) {
+    // Allowlist aligned with validateApiPathParam — permits dots, colons, @ for
+    // deep links (myapp://path), domain-qualified values (auth.tokens), and
+    // versioned routes (v1:resource). Rejects path separators and shell metacharacters.
+    if (!/^[a-zA-Z0-9_\-.:@]+$/.test(value)) {
         throw new Error(`Nav param "${key}" contains invalid characters: "${value}". ` +
-            `Only alphanumeric, hyphens, and underscores are allowed.`);
+            `Only alphanumeric, hyphens, underscores, dots, colons, and @ are allowed.`);
     }
 }
 function resolveNav(resolver, params) {
@@ -237,7 +246,7 @@ function validateApiPathParam(key, value) {
 }
 // Both buildUrl (API) and resolveNav (nav) validate path param values against
 // an allowlist before substitution — prevents path traversal via unencoded slashes.
-function buildUrl(baseUrl, urlPath, params) {
+function buildUrl(baseUrl, urlPath, params, blockedQsParams) {
     let resolved = urlPath;
     const unused = {};
     for (const [key, value] of Object.entries(params)) {
@@ -254,7 +263,8 @@ function buildUrl(baseUrl, urlPath, params) {
     }
     const base = `${baseUrl.replace(/\/$/, '')}${resolved}`;
     const qs = Object.entries(unused)
-        .filter(([, v]) => v !== null && v !== undefined)
+        .filter(([k, v]) => v !== null && v !== undefined
+        && (!blockedQsParams || !blockedQsParams.has(k)))
         .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`)
         .join('&');
     return qs ? `${base}?${qs}` : base;

package/dist/esm/schema.d.ts

@@ -11,19 +11,19 @@ export declare const CapmanConfigSchema: z.ZodEffects<z.ZodObject<{
             name: z.ZodString;
             description: z.ZodString;
             required: z.ZodBoolean;
-            source: z.ZodEnum<["user_query", "session", "context", "static"]>;
+            source: z.ZodEnum<["user_query", "session"]>;
             default: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
         }, "strip", z.ZodTypeAny, {
             name: string;
             required: boolean;
             description: string;
-            source: "user_query" | "session" | "context" | "static";
+            source: "user_query" | "session";
             default?: string | number | boolean | undefined;
         }, {
             name: string;
             required: boolean;
             description: string;
-            source: "user_query" | "session" | "context" | "static";
+            source: "user_query" | "session";
             default?: string | number | boolean | undefined;
         }>, "many">;
         returns: z.ZodArray<z.ZodString, "many">;
@@ -151,7 +151,7 @@ export declare const CapmanConfigSchema: z.ZodEffects<z.ZodObject<{
             name: string;
             required: boolean;
             description: string;
-            source: "user_query" | "session" | "context" | "static";
+            source: "user_query" | "session";
             default?: string | number | boolean | undefined;
         }[];
         description: string;
@@ -193,7 +193,7 @@ export declare const CapmanConfigSchema: z.ZodEffects<z.ZodObject<{
             name: string;
             required: boolean;
             description: string;
-            source: "user_query" | "session" | "context" | "static";
+            source: "user_query" | "session";
             default?: string | number | boolean | undefined;
         }[];
         description: string;
@@ -235,7 +235,7 @@ export declare const CapmanConfigSchema: z.ZodEffects<z.ZodObject<{
             name: string;
             required: boolean;
             description: string;
-            source: "user_query" | "session" | "context" | "static";
+            source: "user_query" | "session";
             default?: string | number | boolean | undefined;
         }[];
         description: string;
@@ -277,7 +277,7 @@ export declare const CapmanConfigSchema: z.ZodEffects<z.ZodObject<{
             name: string;
             required: boolean;
             description: string;
-            source: "user_query" | "session" | "context" | "static";
+            source: "user_query" | "session";
             default?: string | number | boolean | undefined;
         }[];
         description: string;
@@ -322,7 +322,7 @@ export declare const CapmanConfigSchema: z.ZodEffects<z.ZodObject<{
             name: string;
             required: boolean;
             description: string;
-            source: "user_query" | "session" | "context" | "static";
+            source: "user_query" | "session";
             default?: string | number | boolean | undefined;
         }[];
         description: string;
@@ -368,7 +368,7 @@ export declare const CapmanConfigSchema: z.ZodEffects<z.ZodObject<{
             name: string;
             required: boolean;
             description: string;
-            source: "user_query" | "session" | "context" | "static";
+            source: "user_query" | "session";
             default?: string | number | boolean | undefined;
         }[];
         description: string;
@@ -414,7 +414,7 @@ export declare const CapmanConfigSchema: z.ZodEffects<z.ZodObject<{
             name: string;
             required: boolean;
             description: string;
-            source: "user_query" | "session" | "context" | "static";
+            source: "user_query" | "session";
             default?: string | number | boolean | undefined;
         }[];
         description: string;
@@ -460,7 +460,7 @@ export declare const CapmanConfigSchema: z.ZodEffects<z.ZodObject<{
             name: string;
             required: boolean;
             description: string;
-            source: "user_query" | "session" | "context" | "static";
+            source: "user_query" | "session";
             default?: string | number | boolean | undefined;
         }[];
         description: string;
@@ -511,19 +511,19 @@ export declare const ManifestSchema: z.ZodObject<{
             name: z.ZodString;
             description: z.ZodString;
             required: z.ZodBoolean;
-            source: z.ZodEnum<["user_query", "session", "context", "static"]>;
+            source: z.ZodEnum<["user_query", "session"]>;
             default: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
         }, "strip", z.ZodTypeAny, {
             name: string;
             required: boolean;
             description: string;
-            source: "user_query" | "session" | "context" | "static";
+            source: "user_query" | "session";
             default?: string | number | boolean | undefined;
         }, {
             name: string;
             required: boolean;
             description: string;
-            source: "user_query" | "session" | "context" | "static";
+            source: "user_query" | "session";
             default?: string | number | boolean | undefined;
         }>, "many">;
         returns: z.ZodArray<z.ZodString, "many">;
@@ -651,7 +651,7 @@ export declare const ManifestSchema: z.ZodObject<{
             name: string;
             required: boolean;
             description: string;
-            source: "user_query" | "session" | "context" | "static";
+            source: "user_query" | "session";
             default?: string | number | boolean | undefined;
         }[];
         description: string;
@@ -693,7 +693,7 @@ export declare const ManifestSchema: z.ZodObject<{
             name: string;
             required: boolean;
             description: string;
-            source: "user_query" | "session" | "context" | "static";
+            source: "user_query" | "session";
             default?: string | number | boolean | undefined;
         }[];
         description: string;
@@ -739,7 +739,7 @@ export declare const ManifestSchema: z.ZodObject<{
             name: string;
             required: boolean;
             description: string;
-            source: "user_query" | "session" | "context" | "static";
+            source: "user_query" | "session";
             default?: string | number | boolean | undefined;
         }[];
         description: string;
@@ -786,7 +786,7 @@ export declare const ManifestSchema: z.ZodObject<{
             name: string;
             required: boolean;
             description: string;
-            source: "user_query" | "session" | "context" | "static";
+            source: "user_query" | "session";
             default?: string | number | boolean | undefined;
         }[];
         description: string;

package/dist/esm/schema.js

@@ -4,7 +4,7 @@ const CapabilityParamSchema = z.object({
     name: z.string().min(1, 'param name is required'),
     description: z.string().min(1, 'param description is required'),
     required: z.boolean(),
-    source: z.enum(['user_query', 'session', 'context', 'static']),
+    source: z.enum(['user_query', 'session']),
     default: z.union([z.string(), z.number(), z.boolean()]).optional(),
 });
 // ─── Resolver Schemas ─────────────────────────────────────────────────────────

package/dist/esm/types.d.ts

@@ -4,7 +4,7 @@ export interface CapabilityParam {
     name: string;
     description: string;
     required: boolean;
-    source: 'user_query' | 'session' | 'context' | 'static';
+    source: 'user_query' | 'session';
     default?: string | number | boolean;
 }
 export interface ApiResolver {

package/dist/esm/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.5.3";
+export declare const VERSION = "0.5.5";

package/dist/esm/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "capman",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "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",