capman 0.6.0 → 0.6.2

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,46 @@ export function extractBigrams(tokens) {
     }
     return bigrams;
 }
+/**
+ * Reciprocal Rank Fusion — fuses multiple ranked lists into a single score map.
+ * k=60 is the standard literature default.
+ */
+export function rrf(rankings, k = 60) {
+    const scores = new Map();
+    for (const ranking of rankings) {
+        const sorted = [...ranking].sort((a, b) => b.score - a.score);
+        sorted.forEach((item, rank) => {
+            scores.set(item.id, (scores.get(item.id) ?? 0) + 1 / (k + rank + 1));
+        });
+    }
+    return scores;
+}
+/**
+ * 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 +305,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 +348,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 +377,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 +437,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,28 +541,58 @@ 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 allScores = [];
+    const ceiling = options.bm25Ceiling ?? calibrateCeiling(manifest.capabilities, bm25Index, k1, b);
+    // Build per-source ranked lists for RRF fusion
+    const keywordRanking = [];
+    const fuzzyRanking = [];
+    const embeddingRanking = [];
+    const keywordScoreMap = new Map();
     for (const cap of manifest.capabilities) {
         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)));
-        logger.debug(`  scored "${cap.id}": ${score}% (keyword: ${keywordScore}%, fuzzy: ${Math.round(fuzzyScore)}%)`);
+        const embScore = options.embeddingScores?.get(cap.id) ?? 0;
+        if (keywordScore > 0)
+            keywordRanking.push({ id: cap.id, score: keywordScore });
+        keywordScoreMap.set(cap.id, keywordScore);
+        if (fuzzyScore > 0)
+            fuzzyRanking.push({ id: cap.id, score: fuzzyScore });
+        if (embScore > 0)
+            embeddingRanking.push({ id: cap.id, score: embScore });
+    }
+    // RRF fusion. Anchor to theoretical max — a rank-1 entry in all lists scores
+    // rankings.length/(k+1). Using observed max instead inflates zero-overlap queries
+    // (all capabilities rank equally) to 100%, breaking out-of-scope rejection.
+    const rrfK = 60;
+    const rankings = [
+        keywordRanking,
+        ...(fuzzyRanking.length > 0 ? [fuzzyRanking] : []),
+        ...(embeddingRanking.length > 0 ? [embeddingRanking] : []),
+    ];
+    const rrfScores = rrf(rankings, rrfK);
+    const theoreticalMax = rankings.length / (rrfK + 1);
+    // Pre-compute rank maps — rank 0 = best. Used for accurate via attribution.
+    const rankIn = (list, id) => {
+        const idx = list.findIndex(e => e.id === id);
+        return idx === -1 ? Infinity : idx;
+    };
+    const allScores = [];
+    for (const cap of manifest.capabilities) {
+        const rrfScore = rrfScores.get(cap.id) ?? 0;
+        const score = Math.min(100, Math.round((rrfScore / theoreticalMax) * 100));
+        const keywordScore = keywordScoreMap.get(cap.id) ?? 0;
+        const fuzzyScore = fuzzyScoreMap.get(cap.id) ?? 0;
+        const embScore = options.embeddingScores?.get(cap.id) ?? 0;
+        // via = whichever signal ranked this capability highest (lowest rank index).
+        // Uses rank position rather than raw score — RRF is rank-based, not score-based.
+        const kRank = rankIn(keywordRanking, cap.id);
+        const fRank = rankIn(fuzzyRanking, cap.id);
+        const eRank = rankIn(embeddingRanking, cap.id);
+        const via = eRank < fRank && eRank < kRank ? 'embedding' :
+            fRank < kRank ? 'fuzzy' : 'keyword';
+        logger.debug(`  scored "${cap.id}": ${score}% (keyword: ${keywordScore}%, fuzzy: ${Math.round(fuzzyScore)}%, emb: ${Math.round(embScore)}%, rrf: ${rrfScore.toFixed(4)})`);
         allScores.push({ cap, score, via });
         if (score > bestScore) {
             bestScore = score;
@@ -492,7 +622,8 @@ export function match(query, manifest, options = {}) {
     logger.debug(`Extracted params: ${JSON.stringify(Object.fromEntries(Object.entries(params).map(([k, v]) => [k, v != null ? '[REDACTED]' : 'null'])))}`);
     // Use the via tag tracked during scoring — avoids redundant scoreCapability call.
     const bestEntry = allScores.find(s => s.cap.id === best.id);
-    const winner = bestEntry?.via === 'fuzzy' ? 'fuzzy match' : 'keyword scoring';
+    const winner = bestEntry?.via === 'embedding' ? 'embedding match' :
+        bestEntry?.via === 'fuzzy' ? 'fuzzy match' : 'keyword scoring';
     // Matched return:
     return {
         capability: best,
@@ -514,17 +645,17 @@ export function match(query, manifest, options = {}) {
  * 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) {
+export async function matchWithLLM(query, topCandidates, 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}): ${sanitizeForPrompt(c.description, MAX_DESC_LEN)}${c.examples?.length
+    const manifestSummary = topCandidates.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 safeApp = sanitizeForPrompt(options.app ?? 'the application', 100);
     const prompt = `You are an intent matcher for an AI agent system.
 
   App: ${safeApp}
@@ -566,7 +697,7 @@ ${JSON.stringify({ user_query: query })}
     const isOOS = parsed.matched_capability === 'OUT_OF_SCOPE';
     const capability = isOOS
         ? null
-        : manifest.capabilities.find(c => c.id === parsed.matched_capability) ?? null;
+        : topCandidates.find(c => c.id === parsed.matched_capability) ?? null;
     // If LLM returned an unknown capability ID, treat as out of scope
     const effectivelyOOS = isOOS || capability === null;
     if (!isOOS && capability === null) {
@@ -575,8 +706,14 @@ ${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;
-    const allCandidates = manifest.capabilities.map(c => ({
+    // 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 = topCandidates.map(c => ({
         capabilityId: c.id,
         score: c.id === capability?.id ? llmConfidence : 0,
         matched: c.id === capability?.id,

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),
         };