@jsonstudio/llms 0.6.467 → 0.6.567

package/dist/router/virtual-router/engine-selection.js

@@ -0,0 +1,649 @@
+import { DEFAULT_ROUTE, ROUTE_PRIORITY, VirtualRouterError, VirtualRouterErrorCode } from './types.js';
+export function selectProviderImpl(requestedRoute, metadata, classification, features, activeState, deps, options = {}) {
+    const state = options.routingState ?? activeState;
+    const excludedProviderKeys = extractExcludedProviderKeySet(features.metadata);
+    const forcedResolution = state.forcedTarget ? resolveInstructionTarget(state.forcedTarget, deps.providerRegistry) : null;
+    if (forcedResolution && forcedResolution.mode === 'exact') {
+        const forcedKey = forcedResolution.keys[0];
+        if (!excludedProviderKeys.has(forcedKey) && !deps.isProviderCoolingDown(forcedKey)) {
+            return {
+                providerKey: forcedKey,
+                routeUsed: requestedRoute,
+                pool: [forcedKey],
+                poolId: 'forced'
+            };
+        }
+    }
+    let stickyResolution = null;
+    let stickyKeySet;
+    if (!forcedResolution && state.stickyTarget) {
+        stickyResolution = resolveInstructionTarget(state.stickyTarget, deps.providerRegistry);
+        if (stickyResolution && stickyResolution.mode === 'exact') {
+            const stickyKey = stickyResolution.keys[0];
+            if (deps.healthManager.isAvailable(stickyKey) &&
+                !excludedProviderKeys.has(stickyKey) &&
+                !deps.isProviderCoolingDown(stickyKey)) {
+                return {
+                    providerKey: stickyKey,
+                    routeUsed: requestedRoute,
+                    pool: [stickyKey],
+                    poolId: 'sticky'
+                };
+            }
+        }
+        if (stickyResolution && stickyResolution.mode === 'filter' && stickyResolution.keys.length > 0) {
+            const liveKeys = stickyResolution.keys.filter((key) => deps.healthManager.isAvailable(key) &&
+                !excludedProviderKeys.has(key) &&
+                !deps.isProviderCoolingDown(key));
+            if (liveKeys.length > 0) {
+                stickyKeySet = new Set(liveKeys);
+            }
+        }
+    }
+    const allowAliasRotation = Boolean(state.stickyTarget) &&
+        !state.stickyTarget?.keyAlias &&
+        state.stickyTarget?.keyIndex === undefined;
+    if (forcedResolution && forcedResolution.mode === 'filter') {
+        const forcedKeySet = new Set(forcedResolution.keys);
+        if (forcedKeySet.size > 0) {
+            for (const key of Array.from(forcedKeySet)) {
+                if (excludedProviderKeys.has(key) || deps.isProviderCoolingDown(key)) {
+                    forcedKeySet.delete(key);
+                }
+            }
+        }
+        if (forcedKeySet.size > 0) {
+            const candidates = buildRouteCandidates(requestedRoute, classification.candidates, features, deps.routing, deps.providerRegistry);
+            const filteredCandidates = filterCandidatesByRoutingState(candidates, state, deps.routing, deps.providerRegistry);
+            if (filteredCandidates.length === 0) {
+                throw new VirtualRouterError('No available providers after applying routing instructions', VirtualRouterErrorCode.PROVIDER_NOT_AVAILABLE, {
+                    requestedRoute,
+                    allowedProviders: Array.from(state.allowedProviders),
+                    disabledProviders: Array.from(state.disabledProviders)
+                });
+            }
+            return selectFromCandidates(filteredCandidates, metadata, classification, features, state, deps, {
+                requiredProviderKeys: forcedKeySet,
+                allowAliasRotation
+            });
+        }
+    }
+    if (stickyKeySet && stickyKeySet.size > 0) {
+        const stickySelection = selectFromStickyPool(stickyKeySet, metadata, features, state, deps, { allowAliasRotation });
+        if (stickySelection) {
+            return stickySelection;
+        }
+    }
+    const candidates = buildRouteCandidates(requestedRoute, classification.candidates, features, deps.routing, deps.providerRegistry);
+    const filteredCandidates = filterCandidatesByRoutingState(candidates, state, deps.routing, deps.providerRegistry);
+    if (filteredCandidates.length === 0) {
+        throw new VirtualRouterError('No available providers after applying routing instructions', VirtualRouterErrorCode.PROVIDER_NOT_AVAILABLE, {
+            requestedRoute,
+            allowedProviders: Array.from(state.allowedProviders),
+            disabledProviders: Array.from(state.disabledProviders)
+        });
+    }
+    return selectFromCandidates(filteredCandidates, metadata, classification, features, state, deps, {
+        allowAliasRotation
+    });
+}
+function selectFromCandidates(routes, metadata, classification, features, state, deps, options) {
+    const allowedProviders = new Set(state.allowedProviders);
+    const disabledProviders = new Set(state.disabledProviders);
+    const disabledKeysMap = new Map(Array.from(state.disabledKeys.entries()).map(([provider, keys]) => [
+        provider,
+        new Set(Array.from(keys).map((k) => (typeof k === 'string' ? k : k + 1)))
+    ]));
+    const disabledModels = new Map(Array.from(state.disabledModels.entries()).map(([provider, models]) => [provider, new Set(models)]));
+    const stickyKey = options.allowAliasRotation ? undefined : deps.resolveStickyKey(metadata);
+    const attempted = [];
+    const visitedRoutes = new Set();
+    const routeQueue = initializeRouteQueue(routes);
+    const estimatedTokens = typeof features.estimatedTokens === 'number' && Number.isFinite(features.estimatedTokens)
+        ? Math.max(0, features.estimatedTokens)
+        : 0;
+    while (routeQueue.length) {
+        const routeName = routeQueue.shift();
+        if (visitedRoutes.has(routeName)) {
+            continue;
+        }
+        const routePools = deps.routing[routeName];
+        if (!routeHasTargets(routePools)) {
+            visitedRoutes.add(routeName);
+            attempted.push(`${routeName}:empty`);
+            continue;
+        }
+        visitedRoutes.add(routeName);
+        const orderedPools = sortRoutePools(routePools);
+        for (const poolTier of orderedPools) {
+            const { providerKey, poolTargets, tierId, failureHint } = trySelectFromTier(routeName, poolTier, stickyKey, estimatedTokens, features, deps, {
+                disabledProviders,
+                disabledKeysMap,
+                allowedProviders,
+                disabledModels,
+                requiredProviderKeys: options.requiredProviderKeys,
+                allowAliasRotation: options.allowAliasRotation
+            });
+            if (providerKey) {
+                return { providerKey, routeUsed: routeName, pool: poolTargets, poolId: tierId };
+            }
+            if (failureHint) {
+                attempted.push(failureHint);
+            }
+        }
+    }
+    const requestedRoute = normalizeRouteAlias(classification.routeName || DEFAULT_ROUTE);
+    throw new VirtualRouterError(`All providers unavailable for route ${requestedRoute}`, VirtualRouterErrorCode.PROVIDER_NOT_AVAILABLE, { routeName: requestedRoute, attempted });
+}
+function trySelectFromTier(routeName, tier, stickyKey, estimatedTokens, features, deps, options) {
+    const { disabledProviders, disabledKeysMap, allowedProviders, disabledModels, requiredProviderKeys } = options;
+    let targets = Array.isArray(tier.targets) ? tier.targets : [];
+    const excludedRaw = features.metadata?.excludedProviderKeys &&
+        Array.isArray(features.metadata.excludedProviderKeys)
+        ? features.metadata.excludedProviderKeys
+        : [];
+    const excludedKeys = new Set(excludedRaw
+        .map((val) => (typeof val === 'string' ? val.trim() : ''))
+        .filter((val) => Boolean(val)));
+    if (excludedKeys.size > 0) {
+        targets = targets.filter((key) => !excludedKeys.has(key));
+    }
+    if (targets.length > 0) {
+        targets = targets.filter((key) => !deps.isProviderCoolingDown(key));
+    }
+    if (allowedProviders && allowedProviders.size > 0) {
+        targets = targets.filter((key) => {
+            const providerId = extractProviderId(key);
+            return providerId && allowedProviders.has(providerId);
+        });
+    }
+    if (disabledProviders && disabledProviders.size > 0) {
+        targets = targets.filter((key) => {
+            const providerId = extractProviderId(key);
+            return providerId && !disabledProviders.has(providerId);
+        });
+    }
+    if (disabledKeysMap && disabledKeysMap.size > 0) {
+        targets = targets.filter((key) => {
+            const providerId = extractProviderId(key);
+            if (!providerId)
+                return true;
+            const disabledKeys = disabledKeysMap.get(providerId);
+            if (!disabledKeys || disabledKeys.size === 0)
+                return true;
+            const keyAlias = extractKeyAlias(key);
+            const keyIndex = extractKeyIndex(key);
+            if (keyAlias && disabledKeys.has(keyAlias)) {
+                return false;
+            }
+            if (keyIndex !== undefined && disabledKeys.has(keyIndex + 1)) {
+                return false;
+            }
+            return true;
+        });
+    }
+    if (disabledModels && disabledModels.size > 0) {
+        targets = targets.filter((key) => {
+            const providerId = extractProviderId(key);
+            if (!providerId) {
+                return true;
+            }
+            const disabled = disabledModels.get(providerId);
+            if (!disabled || disabled.size === 0) {
+                return true;
+            }
+            const modelId = getProviderModelId(key, deps.providerRegistry);
+            if (!modelId) {
+                return true;
+            }
+            return !disabled.has(modelId);
+        });
+    }
+    if (requiredProviderKeys && requiredProviderKeys.size > 0) {
+        targets = targets.filter((key) => requiredProviderKeys.has(key));
+    }
+    const serverToolRequired = features.metadata?.serverToolRequired === true;
+    if (serverToolRequired) {
+        const filtered = [];
+        for (const key of targets) {
+            try {
+                const profile = deps.providerRegistry.get(key);
+                if (!profile.serverToolsDisabled) {
+                    filtered.push(key);
+                }
+            }
+            catch {
+                // ignore unknown providers when filtering for servertools
+            }
+        }
+        targets = filtered;
+    }
+    if (features.hasImageAttachment && (routeName === DEFAULT_ROUTE || routeName === 'thinking')) {
+        const prioritized = [];
+        const fallthrough = [];
+        for (const key of targets) {
+            try {
+                const profile = deps.providerRegistry.get(key);
+                if (profile.providerType === 'responses') {
+                    prioritized.push(key);
+                }
+                else if (profile.providerType === 'gemini') {
+                    prioritized.push(key);
+                }
+                else {
+                    fallthrough.push(key);
+                }
+            }
+            catch {
+                fallthrough.push(key);
+            }
+        }
+        if (prioritized.length) {
+            targets = prioritized;
+        }
+    }
+    if (!targets.length) {
+        return { providerKey: null, poolTargets: [], tierId: tier.id, failureHint: `${routeName}:${tier.id}:empty` };
+    }
+    const contextResult = deps.contextAdvisor.classify(targets, estimatedTokens, (key) => deps.providerRegistry.get(key));
+    const prioritizedPools = buildContextCandidatePools(contextResult);
+    for (const candidatePool of prioritizedPools) {
+        const providerKey = deps.loadBalancer.select({
+            routeName: `${routeName}:${tier.id}`,
+            candidates: candidatePool,
+            stickyKey: options.allowAliasRotation ? undefined : stickyKey,
+            availabilityCheck: (key) => deps.healthManager.isAvailable(key)
+        });
+        if (providerKey) {
+            return { providerKey, poolTargets: tier.targets, tierId: tier.id };
+        }
+    }
+    return {
+        providerKey: null,
+        poolTargets: tier.targets,
+        tierId: tier.id,
+        failureHint: describeAttempt(routeName, tier.id, contextResult)
+    };
+}
+export function selectFromStickyPool(stickyKeySet, metadata, features, state, deps, options) {
+    if (!stickyKeySet || stickyKeySet.size === 0) {
+        return null;
+    }
+    const allowedProviders = new Set(state.allowedProviders);
+    const disabledProviders = new Set(state.disabledProviders);
+    const disabledKeysMap = new Map(Array.from(state.disabledKeys.entries()).map(([provider, keys]) => [
+        provider,
+        new Set(Array.from(keys).map((k) => (typeof k === 'string' ? k : k + 1)))
+    ]));
+    const disabledModels = new Map(Array.from(state.disabledModels.entries()).map(([provider, models]) => [provider, new Set(models)]));
+    let candidates = Array.from(stickyKeySet).filter((key) => !deps.isProviderCoolingDown(key));
+    if (allowedProviders.size > 0) {
+        candidates = candidates.filter((key) => {
+            const providerId = extractProviderId(key);
+            return providerId && allowedProviders.has(providerId);
+        });
+    }
+    if (disabledProviders.size > 0) {
+        candidates = candidates.filter((key) => {
+            const providerId = extractProviderId(key);
+            return providerId && !disabledProviders.has(providerId);
+        });
+    }
+    if (disabledKeysMap.size > 0 || disabledModels.size > 0) {
+        candidates = candidates.filter((key) => {
+            const providerId = extractProviderId(key);
+            if (!providerId) {
+                return true;
+            }
+            const disabledKeys = disabledKeysMap.get(providerId);
+            if (disabledKeys && disabledKeys.size > 0) {
+                const keyAlias = extractKeyAlias(key);
+                const keyIndex = extractKeyIndex(key);
+                if (keyAlias && disabledKeys.has(keyAlias)) {
+                    return false;
+                }
+                if (keyIndex !== undefined && disabledKeys.has(keyIndex + 1)) {
+                    return false;
+                }
+            }
+            const disabledModelSet = disabledModels.get(providerId);
+            if (disabledModelSet && disabledModelSet.size > 0) {
+                const modelId = getProviderModelId(key, deps.providerRegistry);
+                if (modelId && disabledModelSet.has(modelId)) {
+                    return false;
+                }
+            }
+            return true;
+        });
+    }
+    if (!candidates.length) {
+        return null;
+    }
+    const stickyKey = options.allowAliasRotation ? undefined : deps.resolveStickyKey(metadata);
+    const estimatedTokens = typeof features.estimatedTokens === 'number' && Number.isFinite(features.estimatedTokens)
+        ? Math.max(0, features.estimatedTokens)
+        : 0;
+    const tier = {
+        id: 'sticky-primary',
+        targets: candidates,
+        priority: 0
+    };
+    const { providerKey, poolTargets, tierId } = trySelectFromTier('sticky', tier, stickyKey, estimatedTokens, features, deps, {
+        disabledProviders,
+        disabledKeysMap,
+        allowedProviders,
+        disabledModels,
+        requiredProviderKeys: stickyKeySet,
+        allowAliasRotation: options.allowAliasRotation
+    });
+    if (!providerKey) {
+        return null;
+    }
+    return {
+        providerKey,
+        routeUsed: 'sticky',
+        pool: poolTargets,
+        poolId: tierId
+    };
+}
+function filterCandidatesByRoutingState(routes, state, routing, providerRegistry) {
+    if (state.allowedProviders.size === 0 &&
+        state.disabledProviders.size === 0 &&
+        state.disabledKeys.size === 0 &&
+        state.disabledModels.size === 0) {
+        return routes;
+    }
+    return routes.filter((routeName) => {
+        const pools = routing[routeName];
+        if (!pools)
+            return false;
+        for (const pool of pools) {
+            if (!Array.isArray(pool.targets) || pool.targets.length === 0) {
+                continue;
+            }
+            for (const providerKey of pool.targets) {
+                const providerId = extractProviderId(providerKey);
+                if (!providerId)
+                    continue;
+                if (state.allowedProviders.size > 0 && !state.allowedProviders.has(providerId)) {
+                    continue;
+                }
+                if (state.disabledProviders.has(providerId)) {
+                    continue;
+                }
+                const disabledKeys = state.disabledKeys.get(providerId);
+                if (disabledKeys && disabledKeys.size > 0) {
+                    const keyAlias = extractKeyAlias(providerKey);
+                    const keyIndex = extractKeyIndex(providerKey);
+                    if (keyAlias && disabledKeys.has(keyAlias)) {
+                        continue;
+                    }
+                    if (keyIndex !== undefined && disabledKeys.has(keyIndex + 1)) {
+                        continue;
+                    }
+                }
+                const disabledModels = state.disabledModels.get(providerId);
+                if (disabledModels && disabledModels.size > 0) {
+                    const modelId = getProviderModelId(providerKey, providerRegistry);
+                    if (modelId && disabledModels.has(modelId)) {
+                        continue;
+                    }
+                }
+                return true;
+            }
+        }
+        return false;
+    });
+}
+function buildRouteCandidates(requestedRoute, classificationCandidates, features, routing, providerRegistry) {
+    const forceVision = routeHasForceFlag('vision', routing);
+    const normalized = normalizeRouteAlias(requestedRoute || DEFAULT_ROUTE);
+    const baseList = [];
+    if (classificationCandidates && classificationCandidates.length) {
+        for (const candidate of classificationCandidates) {
+            baseList.push(normalizeRouteAlias(candidate));
+        }
+    }
+    else if (normalized) {
+        baseList.push(normalized);
+    }
+    if (features.hasImageAttachment && !forceVision) {
+        const visionAwareRoutes = [DEFAULT_ROUTE, 'thinking'];
+        for (const routeName of visionAwareRoutes) {
+            if (routeHasTargets(routing[routeName])) {
+                if (!baseList.includes(routeName)) {
+                    baseList.push(routeName);
+                }
+            }
+        }
+    }
+    let ordered = sortByPriority(baseList);
+    if (features.hasImageAttachment && !forceVision) {
+        ordered = reorderForInlineVision(ordered, routing, providerRegistry);
+    }
+    const deduped = [];
+    for (const routeName of ordered) {
+        if (routeName && !deduped.includes(routeName)) {
+            deduped.push(routeName);
+        }
+    }
+    if (!deduped.includes(DEFAULT_ROUTE)) {
+        deduped.push(DEFAULT_ROUTE);
+    }
+    const filtered = deduped.filter((routeName) => routeHasTargets(routing[routeName]));
+    if (!filtered.includes(DEFAULT_ROUTE) && routeHasTargets(routing[DEFAULT_ROUTE])) {
+        filtered.push(DEFAULT_ROUTE);
+    }
+    return filtered.length ? filtered : [DEFAULT_ROUTE];
+}
+function reorderForInlineVision(routeNames, routing, providerRegistry) {
+    const unique = Array.from(new Set(routeNames.filter(Boolean)));
+    if (!unique.length) {
+        return unique;
+    }
+    const inlinePreferred = [];
+    const inlineRoutes = [DEFAULT_ROUTE, 'thinking'];
+    for (const routeName of inlineRoutes) {
+        if (routeSupportsInlineVision(routeName, routing, providerRegistry) && !inlinePreferred.includes(routeName)) {
+            inlinePreferred.push(routeName);
+        }
+    }
+    if (!inlinePreferred.length) {
+        return unique;
+    }
+    const remaining = [];
+    for (const routeName of unique) {
+        if (!inlinePreferred.includes(routeName)) {
+            remaining.push(routeName);
+        }
+    }
+    return [...inlinePreferred, ...remaining];
+}
+function routeSupportsInlineVision(routeName, routing, providerRegistry) {
+    const pools = routing[routeName];
+    if (!Array.isArray(pools)) {
+        return false;
+    }
+    for (const pool of pools) {
+        if (!Array.isArray(pool.targets)) {
+            continue;
+        }
+        for (const providerKey of pool.targets) {
+            try {
+                const profile = providerRegistry.get(providerKey);
+                if (profile.providerType === 'responses' || profile.providerType === 'gemini') {
+                    return true;
+                }
+            }
+            catch {
+                // ignore unknown providers when probing capabilities
+            }
+        }
+    }
+    return false;
+}
+function normalizeRouteAlias(routeName) {
+    const base = routeName && routeName.trim() ? routeName.trim() : DEFAULT_ROUTE;
+    return base;
+}
+function routeHasForceFlag(routeName, routing) {
+    const pools = routing[routeName];
+    if (!Array.isArray(pools)) {
+        return false;
+    }
+    return pools.some((pool) => pool.force);
+}
+function routeHasTargets(pools) {
+    if (!Array.isArray(pools)) {
+        return false;
+    }
+    return pools.some((pool) => Array.isArray(pool.targets) && pool.targets.length > 0);
+}
+function sortRoutePools(pools) {
+    if (!Array.isArray(pools)) {
+        return [];
+    }
+    return pools
+        .filter((pool) => Array.isArray(pool.targets) && pool.targets.length > 0)
+        .sort((a, b) => {
+        if (a.backup && !b.backup)
+            return 1;
+        if (!a.backup && b.backup)
+            return -1;
+        if (a.priority !== b.priority) {
+            return b.priority - a.priority;
+        }
+        return a.id.localeCompare(b.id);
+    });
+}
+function initializeRouteQueue(candidates) {
+    return Array.from(new Set(candidates));
+}
+function buildContextCandidatePools(result) {
+    const ordered = [];
+    if (result.safe.length) {
+        ordered.push(result.safe);
+        return ordered;
+    }
+    if (result.risky.length) {
+        ordered.push(result.risky);
+    }
+    return ordered;
+}
+function describeAttempt(routeName, poolId, result) {
+    const prefix = poolId ? `${routeName}:${poolId}` : routeName;
+    if (result.safe.length > 0) {
+        return `${prefix}:health`;
+    }
+    if (result.risky.length > 0) {
+        return `${prefix}:context_risky`;
+    }
+    if (result.overflow.length > 0) {
+        return `${prefix}:max_context_window`;
+    }
+    return prefix;
+}
+function extractProviderId(providerKey) {
+    const firstDot = providerKey.indexOf('.');
+    if (firstDot <= 0)
+        return null;
+    return providerKey.substring(0, firstDot);
+}
+function extractKeyAlias(providerKey) {
+    const parts = providerKey.split('.');
+    if (parts.length === 3) {
+        return normalizeAliasDescriptor(parts[1]);
+    }
+    return null;
+}
+function normalizeAliasDescriptor(alias) {
+    if (/^\d+-/.test(alias)) {
+        return alias.replace(/^\d+-/, '');
+    }
+    return alias;
+}
+function extractKeyIndex(providerKey) {
+    const parts = providerKey.split('.');
+    if (parts.length === 2) {
+        const index = parseInt(parts[1], 10);
+        if (!isNaN(index) && index > 0) {
+            return index;
+        }
+    }
+    return undefined;
+}
+function getProviderModelId(providerKey, providerRegistry) {
+    const profile = providerRegistry.get(providerKey);
+    if (profile.modelId) {
+        return profile.modelId;
+    }
+    const parts = providerKey.split('.');
+    if (parts.length === 2) {
+        return parts[1] || null;
+    }
+    if (parts.length === 3) {
+        return parts[2] || null;
+    }
+    return null;
+}
+function extractExcludedProviderKeySet(metadata) {
+    if (!metadata) {
+        return new Set();
+    }
+    const raw = metadata.excludedProviderKeys;
+    if (!Array.isArray(raw) || raw.length === 0) {
+        return new Set();
+    }
+    const normalized = raw
+        .map((value) => (typeof value === 'string' ? value.trim() : ''))
+        .filter((value) => Boolean(value));
+    return new Set(normalized);
+}
+function sortByPriority(routeNames) {
+    return [...routeNames].sort((a, b) => routeWeight(a) - routeWeight(b));
+}
+function routeWeight(routeName) {
+    const idx = ROUTE_PRIORITY.indexOf(routeName);
+    return idx >= 0 ? idx : ROUTE_PRIORITY.length;
+}
+function resolveInstructionTarget(target, providerRegistry) {
+    if (!target || !target.provider) {
+        return null;
+    }
+    const providerId = target.provider;
+    const providerKeys = providerRegistry.listProviderKeys(providerId);
+    if (providerKeys.length === 0) {
+        return null;
+    }
+    const alias = typeof target.keyAlias === 'string' ? target.keyAlias.trim() : '';
+    const aliasExplicit = alias.length > 0 && target.pathLength === 3;
+    if (aliasExplicit) {
+        const runtimeKey = providerRegistry.resolveRuntimeKeyByAlias(providerId, alias);
+        if (runtimeKey) {
+            return { mode: 'exact', keys: [runtimeKey] };
+        }
+    }
+    if (typeof target.keyIndex === 'number' && target.keyIndex > 0) {
+        const runtimeKey = providerRegistry.resolveRuntimeKeyByIndex(providerId, target.keyIndex);
+        if (runtimeKey) {
+            return { mode: 'exact', keys: [runtimeKey] };
+        }
+    }
+    if (target.model && target.model.trim()) {
+        const normalizedModel = target.model.trim();
+        const matchingKeys = providerKeys.filter((key) => {
+            const modelId = getProviderModelId(key, providerRegistry);
+            return modelId === normalizedModel;
+        });
+        if (matchingKeys.length > 0) {
+            return { mode: 'filter', keys: matchingKeys };
+        }
+    }
+    if (alias && !aliasExplicit) {
+        const legacyKey = providerRegistry.resolveRuntimeKeyByAlias(providerId, alias);
+        if (legacyKey) {
+            return { mode: 'exact', keys: [legacyKey] };
+        }
+    }
+    return { mode: 'filter', keys: providerKeys };
+}

package/dist/router/virtual-router/engine.d.ts

@@ -4,6 +4,7 @@ export declare class VirtualRouterEngine {
     private routing;
     private readonly providerRegistry;
     private readonly healthManager;
+    private readonly providerCooldowns;
     private loadBalancer;
     private classifier;
     private readonly contextAdvisor;
@@ -37,12 +38,8 @@ export declare class VirtualRouterEngine {
     private normalizeRouteAlias;
     private validateConfig;
     private selectProvider;
-    private trySelectFromTier;
     private incrementRouteStat;
     private providerHealthConfig;
-    private initializeRouteQueue;
-    private buildContextCandidatePools;
-    private describeAttempt;
     private resolveStickyKey;
     private resolveSessionScope;
     private getRoutingInstructionState;
@@ -71,8 +68,7 @@ export declare class VirtualRouterEngine {
     private normalizeAliasDescriptor;
     private extractKeyIndex;
     private getProviderModelId;
-    private mapProviderError;
-    private deriveReason;
+    private extractExcludedProviderKeySet;
     private buildRouteCandidates;
     private reorderForInlineVision;
     private routeSupportsInlineVision;
@@ -83,13 +79,8 @@ export declare class VirtualRouterEngine {
     private hasPrimaryPool;
     private sortRoutePools;
     private flattenPoolTargets;
-    private buildHitReason;
     private isRoutingStateEmpty;
     private persistRoutingInstructionState;
-    private decorateWithDetail;
-    private formatVirtualRouterHit;
-    private resolveRouteColor;
-    private describeContextUsage;
-    private describeTargetProvider;
-    private parseProviderKey;
+    private markProviderCooldown;
+    private isProviderCoolingDown;
 }