capman 0.5.4 → 0.6.0

package/dist/esm/matcher.d.ts

@@ -3,20 +3,80 @@ export declare class LLMParseError extends Error {
     constructor(message: string);
 }
 export declare const STOPWORDS: Set<string>;
+/**
+ * Regex patterns for common param types.
+ * Used when a CapabilityParam has `pattern` set to a named type.
+ */
+export declare const TYPE_PATTERNS: Record<string, RegExp>;
+/**
+ * Simplified suffix-stripping stemmer — 10 most common English morphological
+ * patterns covering ~80% of benefit at ~25% the complexity of Porter stemmer.
+ * Applied symmetrically to both query words and capability index words.
+ */
+export declare function stem(word: string): string;
+/**
+ * Shared tokenizer — used by scorer, learning index, and boost system.
+ * Applies stopword filtering AND stemming symmetrically.
+ * Any site that tokenizes text for matching MUST use this function
+ * to avoid silent mismatches between query and index tokens.
+ */
+export declare function tokenize(text: string): string[];
+export interface BM25Index {
+    /** Document frequency — how many capabilities contain each term */
+    df: Record<string, number>;
+    /** Average field length per field type */
+    avgdl: {
+        examples: number;
+        description: number;
+        name: number;
+    };
+    /** Total number of capabilities */
+    N: number;
+    /** Bigram sets per capability — post-stopword, post-stem, examples only */
+    bigrams: Record<string, Set<string>>;
+}
+/** Build a BM25 index over all capabilities. Call once at manifest load. */
+export declare function buildBM25Index(capabilities: Capability[]): BM25Index;
+/**
+ * BM25 scoring with field weights.
+ * k1 = 1.5 (TF saturation), b = 0.75 (length normalization)
+ * Field weights: examples 0.6, description 0.3, name 0.1
+ */
+export declare function scoreCapability(qWordSet: Set<string>, cap: Capability, index: BM25Index, k1?: number, b?: number): number;
+/**
+ * Extracts bigrams from a token array as "token1__token2" strings.
+ * Input must already be post-stopword and post-stem (use tokenize() first).
+ */
+export declare function extractBigrams(tokens: string[]): Set<string>;
 export declare function resolverToIntent(cap: Capability): MatchResult['intent'];
+/**
+ * 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.
+ */
+export declare function sanitizeForPrompt(value: string, maxLen: number): string;
 /**
  * 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 declare function extractParams(query: string, cap: Capability): Record<string, string | null>;
 export interface MatchOptions {
     fuzzyMatch?: boolean;
     fuzzyThreshold?: number;
+    bm25Index?: BM25Index;
+    bm25K1?: number;
+    bm25B?: number;
+    bm25Ceiling?: number;
 }
 export declare function match(query: string, manifest: Manifest, options?: MatchOptions): MatchResult;
 export interface LLMMatcherOptions {
@@ -25,12 +85,12 @@ export interface LLMMatcherOptions {
 /**
  * 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 declare function matchWithLLM(query: string, manifest: Manifest, options: LLMMatcherOptions): Promise<MatchResult>;

package/dist/esm/matcher.js

@@ -18,40 +18,226 @@ export const STOPWORDS = new Set([
     'it', 'its', 'how', 'when', 'where', 'who', 'which', 'all',
     'just', 'some', 'any', 'there', 'their', 'them', 'they',
 ]);
-function filterStopwords(words) {
-    return words.filter(w => !STOPWORDS.has(w.toLowerCase()) && w.length > 1);
-}
-function scoreCapability(query, cap) {
+// ─── Type Patterns ────────────────────────────────────────────────────────────
+/**
+ * Regex patterns for common param types.
+ * Used when a CapabilityParam has `pattern` set to a named type.
+ */
+export const TYPE_PATTERNS = {
+    email: /\b[\w.+-]+@[\w-]+\.[a-zA-Z]{2,}\b/,
+    date: /\b\d{4}-\d{2}-\d{2}\b|\b(?:jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\w*\s+\d{1,2}\b/i,
+    orderId: /\b[A-Z]{2,}-?\d{4,}\b|\b\d{6,}\b/,
+    url: /https?:\/\/[^\s]+/,
+};
+/**
+ * Extracts a value from a query using an example template pattern.
+ * e.g. template "order {orderId}", query "track order 12345" → "12345"
+ * e.g. template "booking {ref}", query "cancel booking ABC-001" → "ABC-001"
+ */
+function extractFromTemplate(query, template, paramName) {
+    // Split template on {paramName} to get prefix and suffix
+    const placeholder = `{${paramName}}`;
+    const idx = template.indexOf(placeholder);
+    if (idx === -1)
+        return null;
+    const prefix = template.slice(0, idx).trim().toLowerCase();
+    const suffix = template.slice(idx + placeholder.length).trim().toLowerCase();
     const q = query.toLowerCase();
+    if (prefix) {
+        const prefixIdx = q.indexOf(prefix);
+        if (prefixIdx === -1)
+            return null;
+        const after = query.slice(prefixIdx + prefix.length).trim();
+        const tokens = after.split(/\s+/).filter(t => t.length > 0);
+        if (!tokens.length)
+            return null;
+        // If there's a suffix, find it and take what's between
+        if (suffix) {
+            const suffixIdx = after.toLowerCase().indexOf(suffix);
+            if (suffixIdx > 0) {
+                return after.slice(0, suffixIdx).trim().split(/\s+/)[0] ?? null;
+            }
+        }
+        return tokens[0].replace(/[^a-zA-Z0-9\-_.@]/g, '') || null;
+    }
+    // Prefix is empty — placeholder is at start of template e.g. "{email} unsubscribe"
+    if (!prefix) {
+        if (suffix) {
+            // Find suffix in query — take what comes before it
+            const suffixIdx = query.toLowerCase().indexOf(suffix);
+            if (suffixIdx > 0) {
+                return query.slice(0, suffixIdx).trim().split(/\s+/).pop()
+                    ?.replace(/[^a-zA-Z0-9\-_.@]/g, '') || null;
+            }
+        }
+        // No prefix, no suffix — template is just "{paramName}"; take last meaningful word
+        const words = query.trim().split(/\s+/);
+        return words[words.length - 1]?.replace(/[^a-zA-Z0-9\-_.@]/g, '') || null;
+    }
+    return null;
+}
+// ─── Stem cache ───────────────────────────────────────────────────────────────
+// Each word stemmed exactly once per process — O(1) on repeat lookups.
+// Module-level — persists for the process lifetime. Vocabulary in production
+// is finite (capability names + user query vocabulary) so growth is bounded
+// in practice. In test environments with synthetic random strings, this may
+// grow larger but remains functionally harmless.
+const stemCache = new Map();
+/**
+ * Simplified suffix-stripping stemmer — 10 most common English morphological
+ * patterns covering ~80% of benefit at ~25% the complexity of Porter stemmer.
+ * Applied symmetrically to both query words and capability index words.
+ */
+export function stem(word) {
+    const cached = stemCache.get(word);
+    if (cached !== undefined)
+        return cached;
+    let s = word;
+    if (s.length > 7 && s.endsWith('ation'))
+        s = s.slice(0, -5); // cancellation → cancell
+    else if (s.length > 6 && s.endsWith('tion'))
+        s = s.slice(0, -4); // completion → comple
+    else if (s.length > 6 && s.endsWith('ing'))
+        s = s.slice(0, -3); // tracking → track
+    else if (s.length > 6 && s.endsWith('ity'))
+        s = s.slice(0, -3); // availability → availabil
+    else if (s.length > 5 && s.endsWith('ion'))
+        s = s.slice(0, -3); // version → vers
+    else if (s.length > 6 && s.endsWith('est'))
+        s = s.slice(0, -3); // fastest → fast
+    else if (s.length > 4 && s.endsWith('er'))
+        s = s.slice(0, -2); // tracker → track
+    else if (s.length > 4 && s.endsWith('ed'))
+        s = s.slice(0, -2); // ordered → order
+    else if (s.length > 4 && s.endsWith('ly'))
+        s = s.slice(0, -2); // quickly → quick
+    else if (s.length > 4 && s.endsWith('es'))
+        s = s.slice(0, -2); // fetches → fetch
+    else if (s.length > 3 && s.endsWith('s') &&
+        !s.endsWith('ss'))
+        s = s.slice(0, -1); // orders → order
+    stemCache.set(word, s);
+    return s;
+}
+/**
+ * Shared tokenizer — used by scorer, learning index, and boost system.
+ * Applies stopword filtering AND stemming symmetrically.
+ * Any site that tokenizes text for matching MUST use this function
+ * to avoid silent mismatches between query and index tokens.
+ */
+export function tokenize(text) {
+    return text
+        .toLowerCase()
+        .split(/\W+/)
+        .filter(w => w.length > 2 && !STOPWORDS.has(w))
+        .map(stem);
+}
+/** Build a BM25 index over all capabilities. Call once at manifest load. */
+export function buildBM25Index(capabilities) {
+    const N = capabilities.length;
+    if (N === 0)
+        return { df: {}, avgdl: { examples: 0, description: 0, name: 0 }, N: 0, bigrams: {}, };
+    const df = {};
+    let totalExLen = 0;
+    let totalDescLen = 0;
+    let totalNameLen = 0;
+    for (const cap of capabilities) {
+        const exTokens = tokenize((cap.examples ?? []).join(' '));
+        const descTokens = tokenize(cap.description);
+        const nameTokens = tokenize(cap.name);
+        totalExLen += exTokens.length;
+        totalDescLen += descTokens.length;
+        totalNameLen += nameTokens.length;
+        // Count document frequency — each term counted once per capability
+        const seen = new Set();
+        for (const t of [...exTokens, ...descTokens, ...nameTokens]) {
+            if (!seen.has(t)) {
+                df[t] = (df[t] ?? 0) + 1;
+                seen.add(t);
+            }
+        }
+    }
+    // Build bigram sets per capability — examples field only
+    // Clean bigrams only: post-stopword, post-stem tokens
+    const bigrams = {};
+    for (const cap of capabilities) {
+        const set = new Set();
+        for (const example of cap.examples ?? []) {
+            for (const bg of extractBigrams(tokenize(example)))
+                set.add(bg);
+        }
+        bigrams[cap.id] = set;
+    }
+    return {
+        df,
+        avgdl: {
+            examples: totalExLen / N,
+            description: totalDescLen / N,
+            name: totalNameLen / N,
+        },
+        N,
+        bigrams,
+    };
+}
+/**
+ * BM25 scoring with field weights.
+ * k1 = 1.5 (TF saturation), b = 0.75 (length normalization)
+ * Field weights: examples 0.6, description 0.3, name 0.1
+ */
+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;
+    return score;
+}
+function bm25Field(queryTerms, fieldTokens, index, field, k1, b) {
+    if (fieldTokens.length === 0)
+        return 0;
+    const avgdl = index.avgdl[field] || 1;
+    const dl = fieldTokens.length;
+    const tf = new Map();
+    for (const t of fieldTokens) {
+        tf.set(t, (tf.get(t) ?? 0) + 1);
+    }
     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.
-    // Taking Math.max means quality of examples matters, not quantity.
-    let bestExampleScore = 0;
-    for (const example of cap.examples ?? []) {
-        const exWords = filterStopwords(example.toLowerCase().split(/\s+/));
-        if (exWords.length === 0)
+    for (const term of queryTerms) {
+        const termTf = tf.get(term) ?? 0;
+        if (termTf === 0)
             continue;
-        const overlap = exWords.filter(w => qWords.includes(w)).length;
-        const contribution = (overlap / exWords.length) * 60;
-        bestExampleScore = Math.max(bestExampleScore, contribution);
+        const df = index.df[term] ?? 0;
+        const idf = Math.log((index.N - df + 0.5) / (df + 0.5) + 1);
+        const tfNorm = (termTf * (k1 + 1)) / (termTf + k1 * (1 - b + b * (dl / avgdl)));
+        score += idf * tfNorm;
     }
-    score += bestExampleScore;
-    // Check description words
-    const descWords = filterStopwords(cap.description.toLowerCase().split(/\W+/).filter(Boolean));
-    if (descWords.length > 0) {
-        const descOverlap = descWords.filter(w => qWords.includes(w)).length;
-        score += (descOverlap / descWords.length) * 30;
+    return score;
+}
+/**
+ * Extracts bigrams from a token array as "token1__token2" strings.
+ * Input must already be post-stopword and post-stem (use tokenize() first).
+ */
+export function extractBigrams(tokens) {
+    const bigrams = new Set();
+    for (let i = 0; i < tokens.length - 1; i++) {
+        bigrams.add(`${tokens[i]}__${tokens[i + 1]}`);
     }
-    // Check name words
-    const nameWords = filterStopwords(cap.name.toLowerCase().split(/\W+/).filter(Boolean));
-    if (nameWords.length > 0) {
-        const nameOverlap = nameWords.filter(w => qWords.includes(w)).length;
-        score += (nameOverlap / nameWords.length) * 10;
+    return bigrams;
+}
+/**
+ * Returns a fixed bonus in normalized points (0–15), applied after BM25 normalization.
+ * 5 points per matching bigram, saturates at 3 bigrams (15 points).
+ * Fixed point value regardless of manifest size — ceiling-independent.
+ */
+function bigramBonus(queryBigrams, capBigrams) {
+    if (queryBigrams.size === 0 || capBigrams.size === 0)
+        return 0;
+    let overlap = 0;
+    for (const bigram of queryBigrams) {
+        if (capBigrams.has(bigram))
+            overlap++;
     }
-    return Math.min(Math.round(score), 100);
+    return Math.min(overlap * 5, 15); // normalized points — 3 bigrams saturate at 15
 }
 export function resolverToIntent(cap) {
     const t = cap.resolver.type;
@@ -63,14 +249,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.
+ */
+export 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 = {};
@@ -85,6 +290,26 @@ export function extractParams(query, cap) {
             result[param.name] = null;
             continue;
         }
+        // ── Pattern extraction (highest priority) ─────────────────────────────
+        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];
+                    continue;
+                }
+            }
+            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;
+                    continue;
+                }
+            }
+        }
         // Try to extract value after known keywords
         // e.g. "profile for johndoe" → johndoe
         //      "articles by jane"   → jane
@@ -205,9 +430,35 @@ export function match(query, manifest, options = {}) {
         }
     }
     // ── Score all capabilities ────────────────────────────────────────────────
+    // Build qWordSet once — O(1) lookups instead of O(n) Array.includes per word
+    const qTokens = tokenize(query);
+    const qWordSet = new Set(qTokens);
+    // Build query bigrams for phrase bonus
+    const qBigrams = extractBigrams(qTokens);
+    // Build BM25 index for this manifest — O(capabilities × tokens)
+    // In CapmanEngine this is pre-built; for direct match() calls it's built per-call
+    const bm25Index = options.bm25Index ?? buildBM25Index(manifest.capabilities);
+    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 allScores = [];
     for (const cap of manifest.capabilities) {
-        const keywordScore = scoreCapability(query, cap);
+        const rawBM25 = scoreCapability(qWordSet, cap, bm25Index, k1, b);
+        const bm25Score = Math.min(100, Math.round((rawBM25 / ceiling) * 100));
+        const bonusPoints = bigramBonus(qBigrams, bm25Index.bigrams[cap.id] ?? new Set());
+        const keywordScore = Math.min(100, bm25Score + bonusPoints);
         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 +506,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 +585,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;