@jsonstudio/llms 0.6.1172 → 0.6.1354

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

@@ -1,6 +1,12 @@
-import { computeContextMultiplier, computeEffectiveSafeWindowTokens, resolveContextWeightedConfig } from './context-weighted.js';
-import { computeHealthWeight, resolveHealthWeightedConfig } from './health-weighted.js';
-import { DEFAULT_ROUTE, ROUTE_PRIORITY, VirtualRouterError, VirtualRouterErrorCode } from './types.js';
+import { DEFAULT_ROUTE, VirtualRouterError, VirtualRouterErrorCode } from './types.js';
+import { extractExcludedProviderKeySet, extractProviderId } from './engine-selection/key-parsing.js';
+import { trySelectFromTier } from './engine-selection/tier-selection.js';
+import { resolveInstructionTarget } from './engine-selection/instruction-target.js';
+import { filterCandidatesByRoutingState } from './engine-selection/routing-state-filter.js';
+import { selectFromStickyPool as selectFromStickyPoolImpl } from './engine-selection/sticky-pool.js';
+export { selectDirectProviderModel } from './engine-selection/direct-provider-model.js';
+export { selectFromStickyPool } from './engine-selection/sticky-pool.js';
+import { buildRouteCandidates, extendRouteCandidatesForState, initializeRouteQueue, normalizeRouteAlias, routeHasTargets, sortRoutePools } from './engine-selection/route-utils.js';
 export function selectProviderImpl(requestedRoute, metadata, classification, features, activeState, deps, options = {}) {
     const state = options.routingState ?? activeState;
     const quotaView = deps.quotaView;
@@ -122,7 +128,7 @@ export function selectProviderImpl(requestedRoute, metadata, classification, fea
         }
     }
     if (stickyKeySet && stickyKeySet.size > 0) {
-        const stickySelection = selectFromStickyPool(stickyKeySet, metadata, features, state, deps, { allowAliasRotation });
+        const stickySelection = selectFromStickyPoolImpl(stickyKeySet, metadata, features, state, deps, { allowAliasRotation });
         if (stickySelection) {
             return stickySelection;
         }
@@ -169,72 +175,6 @@ export function selectProviderImpl(requestedRoute, metadata, classification, fea
         allowAliasRotation
     });
 }
-function extendRouteCandidatesForState(candidates, state, routing) {
-    // When provider allowlists are active (e.g. "<**!glm**>"), routing should not be bounded by
-    // classifier candidates only. Otherwise, a perfectly valid provider that exists in config
-    // (e.g. in a backup/default pool) can become unreachable and cause PROVIDER_NOT_AVAILABLE.
-    //
-    // We keep original ordering, then append all known routes (by priority) as a fallback search space.
-    if (!state.allowedProviders || state.allowedProviders.size === 0) {
-        return candidates;
-    }
-    const allRoutes = sortByPriority(Object.keys(routing).filter((routeName) => routeName && routeHasTargets(routing[routeName])));
-    const expanded = Array.isArray(candidates) ? [...candidates] : [];
-    for (const routeName of allRoutes) {
-        if (!expanded.includes(routeName)) {
-            expanded.push(routeName);
-        }
-    }
-    return expanded;
-}
-export function selectDirectProviderModel(providerId, modelId, metadata, features, activeState, deps) {
-    const normalizedProvider = typeof providerId === 'string' ? providerId.trim() : '';
-    const normalizedModel = typeof modelId === 'string' ? modelId.trim() : '';
-    if (!normalizedProvider || !normalizedModel) {
-        return null;
-    }
-    const providerKeys = deps.providerRegistry.listProviderKeys(normalizedProvider);
-    if (providerKeys.length === 0) {
-        return null;
-    }
-    const matchingKeys = providerKeys.filter((key) => {
-        try {
-            const profile = deps.providerRegistry.get(key);
-            return profile?.modelId === normalizedModel;
-        }
-        catch {
-            return false;
-        }
-    });
-    if (matchingKeys.length === 0) {
-        return null;
-    }
-    const attempted = [];
-    const estimatedTokens = typeof features.estimatedTokens === 'number' && Number.isFinite(features.estimatedTokens)
-        ? Math.max(0, features.estimatedTokens)
-        : 0;
-    const tier = {
-        id: `direct:${normalizedProvider}.${normalizedModel}`,
-        targets: matchingKeys,
-        priority: 100,
-        mode: 'round-robin',
-        backup: false
-    };
-    const { providerKey, poolTargets, tierId, failureHint } = trySelectFromTier('direct', tier, undefined, estimatedTokens, features, deps, {
-        disabledProviders: new Set(activeState.disabledProviders),
-        disabledKeysMap: new Map(activeState.disabledKeys),
-        allowedProviders: new Set(activeState.allowedProviders),
-        disabledModels: new Map(activeState.disabledModels),
-        allowAliasRotation: true
-    });
-    if (providerKey) {
-        return { providerKey, routeUsed: 'direct', pool: poolTargets, poolId: tierId };
-    }
-    if (failureHint) {
-        attempted.push(failureHint);
-    }
-    return null;
-}
 function selectFromCandidates(routes, metadata, classification, features, state, deps, options) {
     const allowedProviders = new Set(state.allowedProviders);
     const disabledProviders = new Set(state.disabledProviders);
@@ -283,895 +223,3 @@ function selectFromCandidates(routes, metadata, classification, features, state,
     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));
-    }
-    const isRecoveryAttempt = excludedKeys.size > 0;
-    const singleCandidateFallback = targets.length === 1 ? targets[0] : undefined;
-    if (targets.length > 0) {
-        // Always respect cooldown signals. If a route/tier is depleted due to cooldown,
-        // routing is expected to fall back to other tiers/routes (e.g. longcontext → default),
-        // rather than repeatedly selecting the cooled-down provider.
-        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);
-    const quotaView = deps.quotaView;
-    const now = quotaView ? Date.now() : 0;
-    const healthWeightedCfg = resolveHealthWeightedConfig(deps.loadBalancer.getPolicy().healthWeighted);
-    const contextWeightedCfg = resolveContextWeightedConfig(deps.loadBalancer.getPolicy().contextWeighted);
-    const warnRatio = deps.contextAdvisor.getConfig().warnRatio;
-    const nowForWeights = Date.now();
-    const selectFirstAvailable = (candidates) => {
-        for (const key of candidates) {
-            if (deps.healthManager.isAvailable(key)) {
-                return key;
-            }
-        }
-        return null;
-    };
-    const resolvePriorityMeta = (orderedTargets) => {
-        // Priority mode semantics (strict group priority + alias-level balancing):
-        // - Targets are interpreted as ordered (providerId, modelId) groups.
-        // - Group base priorities: 100, 90, 80, ... (step=10) by appearance order.
-        // - Within a group (different auth aliases), base scores: 100, 99, 98, ... (step=1).
-        //
-        // Group selection is strict: always use the best group until it is unavailable.
-        // Alias selection is balanced within the chosen group (RR / health-weighted / context-weighted).
-        const meta = new Map();
-        if (!Array.isArray(orderedTargets) || orderedTargets.length === 0) {
-            return meta;
-        }
-        let groupIndex = -1;
-        let aliasOffset = 0;
-        let lastGroupKey = '';
-        for (const key of orderedTargets) {
-            const providerId = extractProviderId(key) ?? '';
-            const modelId = getProviderModelId(key, deps.providerRegistry) ?? '';
-            const groupKey = `${providerId}::${modelId}`;
-            if (groupKey !== lastGroupKey) {
-                groupIndex += 1;
-                aliasOffset = 0;
-                lastGroupKey = groupKey;
-            }
-            const groupBase = 100 - groupIndex * 10;
-            const base = groupBase - aliasOffset;
-            meta.set(key, { groupId: `${providerId}.${modelId}`, groupBase, base });
-            aliasOffset += 1;
-        }
-        return meta;
-    };
-    const pickPriorityGroup = (candidates, orderedTargets, penalties) => {
-        const meta = resolvePriorityMeta(orderedTargets);
-        let bestGroupId = null;
-        let bestScore = Number.NEGATIVE_INFINITY;
-        for (const key of candidates) {
-            if (!deps.healthManager.isAvailable(key))
-                continue;
-            const m = meta.get(key);
-            if (!m)
-                continue;
-            const penalty = penalties ? Math.max(0, Math.floor(penalties[key] ?? 0)) : 0;
-            const score = m.base - penalty;
-            if (score > bestScore) {
-                bestScore = score;
-                bestGroupId = m.groupId;
-            }
-        }
-        if (!bestGroupId)
-            return null;
-        const groupCandidates = candidates.filter((key) => meta.get(key)?.groupId === bestGroupId);
-        return groupCandidates.length ? { groupId: bestGroupId, groupCandidates } : null;
-    };
-    const computeContextWeightMultipliers = (candidates) => {
-        if (!contextWeightedCfg.enabled) {
-            return null;
-        }
-        const eff = {};
-        let ref = 1;
-        for (const key of candidates) {
-            const usage = contextResult.usage?.[key];
-            const limit = usage && typeof usage.limit === 'number' && Number.isFinite(usage.limit) ? Math.floor(usage.limit) : 0;
-            const safeEff = computeEffectiveSafeWindowTokens({
-                modelMaxTokens: Math.max(1, limit),
-                warnRatio,
-                clientCapTokens: contextWeightedCfg.clientCapTokens
-            });
-            eff[key] = safeEff;
-            if (safeEff > ref) {
-                ref = safeEff;
-            }
-        }
-        return { ref, eff };
-    };
-    const selectWithQuota = (candidates, isSafePool) => {
-        if (!quotaView) {
-            if (tier.mode === 'priority') {
-                if (isRecoveryAttempt) {
-                    return selectFirstAvailable(candidates);
-                }
-                const group = pickPriorityGroup(candidates, tier.targets);
-                if (!group) {
-                    return null;
-                }
-                const weights = (() => {
-                    if (!isSafePool)
-                        return undefined;
-                    const ctx = computeContextWeightMultipliers(group.groupCandidates);
-                    if (!ctx)
-                        return undefined;
-                    const out = {};
-                    for (const key of group.groupCandidates) {
-                        const m = computeContextMultiplier({
-                            effectiveSafeRefTokens: ctx.ref,
-                            effectiveSafeTokens: ctx.eff[key] ?? 1,
-                            cfg: contextWeightedCfg
-                        });
-                        out[key] = Math.max(1, Math.round(100 * m));
-                    }
-                    return out;
-                })();
-                return deps.loadBalancer.select({
-                    routeName: `${routeName}:${tier.id}:priority:group:${group.groupId}`,
-                    candidates: group.groupCandidates,
-                    stickyKey: options.allowAliasRotation ? undefined : stickyKey,
-                    weights,
-                    availabilityCheck: (key) => deps.healthManager.isAvailable(key)
-                }, 'round-robin');
-            }
-            const weights = (() => {
-                if (!isSafePool || !contextWeightedCfg.enabled)
-                    return undefined;
-                const ctx = computeContextWeightMultipliers(candidates);
-                if (!ctx)
-                    return undefined;
-                const out = {};
-                for (const key of candidates) {
-                    const m = computeContextMultiplier({
-                        effectiveSafeRefTokens: ctx.ref,
-                        effectiveSafeTokens: ctx.eff[key] ?? 1,
-                        cfg: contextWeightedCfg
-                    });
-                    out[key] = Math.max(1, Math.round(100 * m));
-                }
-                return out;
-            })();
-            const selected = deps.loadBalancer.select({
-                routeName: `${routeName}:${tier.id}`,
-                candidates,
-                stickyKey: options.allowAliasRotation ? undefined : stickyKey,
-                weights,
-                availabilityCheck: (key) => deps.healthManager.isAvailable(key)
-            }, tier.mode === 'round-robin' ? 'round-robin' : undefined);
-            return selected;
-        }
-        const buckets = new Map();
-        let order = 0;
-        for (const key of candidates) {
-            const entry = quotaView(key);
-            if (!entry) {
-                const list = buckets.get(100) ?? [];
-                list.push({ key, penalty: 0, order: order++ });
-                buckets.set(100, list);
-                continue;
-            }
-            if (!entry.inPool) {
-                continue;
-            }
-            if (entry.cooldownUntil && entry.cooldownUntil > now) {
-                continue;
-            }
-            if (entry.blacklistUntil && entry.blacklistUntil > now) {
-                continue;
-            }
-            const tierPriority = typeof entry.priorityTier === 'number' && Number.isFinite(entry.priorityTier)
-                ? entry.priorityTier
-                : 100;
-            const penaltyRaw = entry.selectionPenalty;
-            const penalty = typeof penaltyRaw === 'number' && Number.isFinite(penaltyRaw) && penaltyRaw > 0 ? Math.floor(penaltyRaw) : 0;
-            const list = buckets.get(tierPriority) ?? [];
-            list.push({ key, penalty, order: order++ });
-            buckets.set(tierPriority, list);
-        }
-        const sortedPriorities = Array.from(buckets.keys()).sort((a, b) => a - b);
-        for (const priority of sortedPriorities) {
-            const bucket = buckets.get(priority) ?? [];
-            if (!bucket.length) {
-                continue;
-            }
-            bucket.sort((a, b) => (a.penalty - b.penalty) || (a.order - b.order));
-            const bucketCandidates = bucket.map((item) => item.key);
-            // antigravity special: avoid rotating across keys while the current key is healthy.
-            // Rationale: some upstream gateways reject rapid cross-key switching even when quota exists,
-            // causing repeated 429s. We therefore pin a single key per (providerId, modelId) until it is
-            // excluded by quota/cooldown, then fail over to the next available key.
-            //
-            // This is only applied when the request has no session-level sticky key, to avoid breaking
-            // explicit session stickiness.
-            const shouldPinAntigravityModel = (() => {
-                // Only respect explicit session/conversation stickiness. requestId-scoped sticky keys
-                // (used for request-chain pinning) should not prevent global antigravity key pinning.
-                if (typeof stickyKey === 'string' && (stickyKey.startsWith('session:') || stickyKey.startsWith('conversation:'))) {
-                    return false;
-                }
-                if (bucketCandidates.length < 2) {
-                    return false;
-                }
-                let modelId = null;
-                for (const key of bucketCandidates) {
-                    const providerId = extractProviderId(key);
-                    if (providerId !== 'antigravity') {
-                        return false;
-                    }
-                    const candidateModel = getProviderModelId(key, deps.providerRegistry);
-                    if (!candidateModel) {
-                        return false;
-                    }
-                    if (modelId === null) {
-                        modelId = candidateModel;
-                    }
-                    else if (modelId !== candidateModel) {
-                        return false;
-                    }
-                }
-                return Boolean(modelId);
-            })();
-            if (shouldPinAntigravityModel && !isRecoveryAttempt) {
-                const pinned = selectFirstAvailable(bucketCandidates);
-                if (pinned) {
-                    return pinned;
-                }
-            }
-            const bucketPenaltyMap = {};
-            for (const item of bucket) {
-                bucketPenaltyMap[item.key] = item.penalty;
-            }
-            const bucketWeights = {};
-            const bucketMultipliers = {};
-            for (const item of bucket) {
-                if (healthWeightedCfg.enabled) {
-                    const entry = quotaView(item.key);
-                    const { weight, multiplier } = computeHealthWeight(entry, nowForWeights, healthWeightedCfg);
-                    bucketWeights[item.key] = weight;
-                    bucketMultipliers[item.key] = multiplier;
-                }
-                else {
-                    // Legacy: penalty => lower weight, but never zero (unhealthy should still get a chance).
-                    bucketWeights[item.key] = Math.max(1, Math.floor(100 / (1 + Math.max(0, item.penalty))));
-                    bucketMultipliers[item.key] = 1;
-                }
-            }
-            if (isSafePool && contextWeightedCfg.enabled) {
-                const ctx = computeContextWeightMultipliers(bucketCandidates);
-                if (ctx) {
-                    for (const key of bucketCandidates) {
-                        const m = computeContextMultiplier({
-                            effectiveSafeRefTokens: ctx.ref,
-                            effectiveSafeTokens: ctx.eff[key] ?? 1,
-                            cfg: contextWeightedCfg
-                        });
-                        bucketWeights[key] = Math.max(1, Math.round((bucketWeights[key] ?? 1) * m));
-                    }
-                }
-            }
-            if (tier.mode === 'priority') {
-                if (!isRecoveryAttempt) {
-                    const group = pickPriorityGroup(bucketCandidates, tier.targets, bucketPenaltyMap);
-                    if (!group) {
-                        continue;
-                    }
-                    const groupWeights = {};
-                    for (const key of group.groupCandidates) {
-                        groupWeights[key] = bucketWeights[key] ?? 1;
-                    }
-                    const selected = deps.loadBalancer.select({
-                        routeName: `${routeName}:${tier.id}:priority:${priority}:group:${group.groupId}`,
-                        candidates: group.groupCandidates,
-                        stickyKey: options.allowAliasRotation ? undefined : stickyKey,
-                        weights: groupWeights,
-                        availabilityCheck: (key) => deps.healthManager.isAvailable(key)
-                    }, 'round-robin');
-                    if (selected) {
-                        return selected;
-                    }
-                    continue;
-                }
-                if (isRecoveryAttempt && healthWeightedCfg.enabled && healthWeightedCfg.recoverToBestOnRetry) {
-                    let best = null;
-                    let bestM = Number.NEGATIVE_INFINITY;
-                    for (const key of bucketCandidates) {
-                        if (!deps.healthManager.isAvailable(key))
-                            continue;
-                        const m = bucketMultipliers[key] ?? 1;
-                        if (m > bestM) {
-                            bestM = m;
-                            best = key;
-                        }
-                    }
-                    if (best) {
-                        return best;
-                    }
-                    continue;
-                }
-                else if (isRecoveryAttempt) {
-                    const recovered = selectFirstAvailable(bucketCandidates);
-                    if (recovered)
-                        return recovered;
-                    continue;
-                }
-                // (unreachable) recovery handled above
-            }
-            else {
-                if (isRecoveryAttempt && healthWeightedCfg.enabled && healthWeightedCfg.recoverToBestOnRetry) {
-                    let best = null;
-                    let bestM = Number.NEGATIVE_INFINITY;
-                    for (const key of bucketCandidates) {
-                        if (!deps.healthManager.isAvailable(key))
-                            continue;
-                        const m = bucketMultipliers[key] ?? 1;
-                        if (m > bestM) {
-                            bestM = m;
-                            best = key;
-                        }
-                    }
-                    if (best) {
-                        return best;
-                    }
-                    continue;
-                }
-                else if (isRecoveryAttempt) {
-                    const recovered = selectFirstAvailable(bucketCandidates);
-                    if (recovered)
-                        return recovered;
-                    continue;
-                }
-                const selected = deps.loadBalancer.select({
-                    routeName: `${routeName}:${tier.id}`,
-                    candidates: bucketCandidates,
-                    stickyKey: options.allowAliasRotation ? undefined : stickyKey,
-                    weights: bucketWeights,
-                    availabilityCheck: (key) => deps.healthManager.isAvailable(key)
-                }, tier.mode === 'round-robin' ? 'round-robin' : undefined);
-                if (selected) {
-                    return selected;
-                }
-            }
-        }
-        return null;
-    };
-    for (const candidatePool of prioritizedPools) {
-        const providerKey = selectWithQuota(candidatePool, candidatePool === contextResult.safe);
-        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 (!candidates.length && stickyKeySet.size === 1) {
-        candidates = Array.from(stickyKeySet);
-    }
-    const quotaView = deps.quotaView;
-    const now = quotaView ? Date.now() : 0;
-    if (quotaView) {
-        const filtered = candidates.filter((key) => {
-            const entry = quotaView(key);
-            if (!entry) {
-                return true;
-            }
-            if (!entry.inPool) {
-                return false;
-            }
-            if (entry.cooldownUntil && entry.cooldownUntil > now) {
-                return false;
-            }
-            if (entry.blacklistUntil && entry.blacklistUntil > now) {
-                return false;
-            }
-            return true;
-        });
-        if (filtered.length > 0 || candidates.length !== 1) {
-            candidates = filtered;
-        }
-    }
-    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);
-    }
-    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 prefix = `${providerId}.${alias}.`;
-        const aliasKeys = providerKeys.filter((key) => key.startsWith(prefix));
-        if (aliasKeys.length > 0) {
-            if (target.model && target.model.trim()) {
-                const normalizedModel = target.model.trim();
-                const matching = aliasKeys.filter((key) => getProviderModelId(key, providerRegistry) === normalizedModel);
-                if (matching.length > 0) {
-                    // Prefer exact to keep sticky pool deterministic when only one key matches.
-                    if (matching.length === 1) {
-                        return { mode: 'exact', keys: [matching[0]] };
-                    }
-                    return { mode: 'filter', keys: matching };
-                }
-            }
-            return { mode: 'filter', keys: aliasKeys };
-        }
-    }
-    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 };
-}