@jsonstudio/llms 0.6.1172 → 0.6.1397

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

@@ -0,0 +1,423 @@
+import { computeContextMultiplier } from '../context-weighted.js';
+import { computeHealthWeight } from '../health-weighted.js';
+import { pinCandidatesByAliasQueue, pinCandidatesByBestQuota, resolveAliasSelectionStrategy } from './alias-selection.js';
+import { computeContextWeightMultipliers } from './context-weight-multipliers.js';
+import { extractKeyAlias, extractProviderId, getProviderModelId } from './key-parsing.js';
+import { pickPriorityGroup } from './tier-priority.js';
+const ANTIGRAVITY_COOLDOWN_ALIAS_THRESHOLD_MS = 30_000;
+function applyAliasStickyQueuePinning(opts) {
+    const { candidates, orderedTargets, deps, excludedKeys, now } = opts;
+    if (!Array.isArray(candidates) || candidates.length < 2) {
+        return candidates;
+    }
+    const store = deps.aliasQueueStore;
+    if (!store) {
+        return candidates;
+    }
+    // Candidates may include multiple providers. Apply sticky-queue pinning per (providerId, modelId) group
+    // while preserving cross-provider competition.
+    const groups = new Map();
+    const keyToGroup = new Map();
+    for (const key of candidates) {
+        if (!key || typeof key !== 'string') {
+            continue;
+        }
+        const providerId = extractProviderId(key) ?? '';
+        if (!providerId) {
+            continue;
+        }
+        const strategy = resolveAliasSelectionStrategy(providerId, deps.loadBalancer.getPolicy().aliasSelection);
+        if (strategy !== 'sticky-queue' && strategy !== 'best-quota') {
+            continue;
+        }
+        const modelId = getProviderModelId(key, deps.providerRegistry) ?? '';
+        if (!modelId) {
+            continue;
+        }
+        const groupId = `${providerId}::${modelId}`;
+        const entry = groups.get(groupId) ?? { providerId, modelId, keys: [] };
+        entry.keys.push(key);
+        groups.set(groupId, entry);
+        keyToGroup.set(key, groupId);
+    }
+    if (groups.size === 0) {
+        return candidates;
+    }
+    const pinnedByGroup = new Map();
+    for (const [groupId, group] of groups.entries()) {
+        if (group.keys.length < 2) {
+            continue;
+        }
+        // Only pin when we have multiple aliases for the same provider+model.
+        const aliases = new Set();
+        for (const key of group.keys) {
+            const alias = extractKeyAlias(key);
+            if (alias) {
+                aliases.add(alias);
+            }
+        }
+        if (aliases.size < 2) {
+            continue;
+        }
+        const strategy = resolveAliasSelectionStrategy(group.providerId, deps.loadBalancer.getPolicy().aliasSelection);
+        let pinned = null;
+        if (strategy === 'best-quota') {
+            pinned = pinCandidatesByBestQuota({
+                providerId: group.providerId,
+                modelId: group.modelId,
+                candidates: group.keys,
+                orderedTargets,
+                aliasOfKey: extractKeyAlias,
+                modelIdOfKey: (key) => getProviderModelId(key, deps.providerRegistry),
+                quotaView: deps.quotaView,
+                now
+            });
+        }
+        if (!pinned) {
+            pinned = pinCandidatesByAliasQueue({
+                queueStore: store,
+                providerId: group.providerId,
+                modelId: group.modelId,
+                candidates: group.keys,
+                orderedTargets,
+                excludedProviderKeys: excludedKeys,
+                aliasOfKey: extractKeyAlias,
+                modelIdOfKey: (key) => getProviderModelId(key, deps.providerRegistry),
+                availabilityCheck: (key) => deps.healthManager.isAvailable(key)
+            });
+        }
+        if (pinned && pinned.length) {
+            pinnedByGroup.set(groupId, new Set(pinned));
+        }
+    }
+    if (pinnedByGroup.size === 0) {
+        return candidates;
+    }
+    return candidates.filter((key) => {
+        const groupId = keyToGroup.get(key);
+        if (!groupId) {
+            return true;
+        }
+        const pinned = pinnedByGroup.get(groupId);
+        return pinned ? pinned.has(key) : true;
+    });
+}
+function preferAntigravityAliasesOnRetry(opts) {
+    const { candidates, excludedKeys, deps } = opts;
+    if (!Array.isArray(candidates) || candidates.length < 2) {
+        return candidates;
+    }
+    if (!excludedKeys || excludedKeys.size === 0) {
+        return candidates;
+    }
+    // Only apply this stronger retry preference for Antigravity.
+    const strategy = resolveAliasSelectionStrategy('antigravity', deps.loadBalancer.getPolicy().aliasSelection);
+    if (strategy !== 'sticky-queue') {
+        return candidates;
+    }
+    const excludedModels = new Set();
+    for (const ex of excludedKeys) {
+        if (!ex || typeof ex !== 'string')
+            continue;
+        if ((extractProviderId(ex) ?? '') !== 'antigravity')
+            continue;
+        try {
+            const modelId = getProviderModelId(ex, deps.providerRegistry) ?? '';
+            if (modelId) {
+                excludedModels.add(modelId);
+            }
+        }
+        catch {
+            // ignore unknown model ids
+        }
+    }
+    if (excludedModels.size === 0) {
+        return candidates;
+    }
+    const preferred = candidates.filter((key) => {
+        if (!key || typeof key !== 'string')
+            return false;
+        if ((extractProviderId(key) ?? '') !== 'antigravity')
+            return false;
+        try {
+            const modelId = getProviderModelId(key, deps.providerRegistry) ?? '';
+            return modelId && excludedModels.has(modelId);
+        }
+        catch {
+            return false;
+        }
+    });
+    // If we still have any Antigravity candidates for the failing model, keep retrying within Antigravity
+    // (rotate aliases) before falling back to other pool targets.
+    return preferred.length > 0 ? preferred : candidates;
+}
+export function selectProviderKeyFromCandidatePool(opts) {
+    const { routeName, tier, stickyKey, candidates, isSafePool, deps, options, contextResult, warnRatio, excludedKeys, isRecoveryAttempt, now, nowForWeights, healthWeightedCfg, contextWeightedCfg } = opts;
+    const quotaView = deps.quotaView;
+    const selectFirstAvailable = (keys) => {
+        for (const key of keys) {
+            if (deps.healthManager.isAvailable(key)) {
+                return key;
+            }
+        }
+        return null;
+    };
+    if (!quotaView) {
+        // Single-provider pool should never be "emptied" by health/cooldown.
+        // If there's only one possible target, we must return it even if it's currently unhealthy,
+        // otherwise context routing can incorrectly fall back to a smaller-context route.
+        if (candidates.length === 1) {
+            return candidates[0] ?? null;
+        }
+        const retryPreferredCandidates = isRecoveryAttempt
+            ? preferAntigravityAliasesOnRetry({ candidates, excludedKeys, deps })
+            : candidates;
+        // Alias-level selection strategy (config-driven).
+        // Apply sticky-queue pinning per provider/model group (candidates can be mixed providers).
+        const pinnedCandidates = applyAliasStickyQueuePinning({
+            candidates: retryPreferredCandidates,
+            orderedTargets: tier.targets,
+            deps,
+            excludedKeys,
+            now
+        });
+        if (tier.mode === 'priority') {
+            if (isRecoveryAttempt) {
+                return selectFirstAvailable(pinnedCandidates);
+            }
+            const group = pickPriorityGroup({
+                candidates: pinnedCandidates,
+                orderedTargets: tier.targets,
+                providerRegistry: deps.providerRegistry,
+                healthManager: deps.healthManager
+            });
+            if (!group) {
+                return null;
+            }
+            const weights = (() => {
+                if (!isSafePool)
+                    return undefined;
+                const ctx = computeContextWeightMultipliers({ candidates: group.groupCandidates, usage: contextResult.usage, warnRatio, cfg: contextWeightedCfg });
+                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: pinnedCandidates, usage: contextResult.usage, warnRatio, cfg: contextWeightedCfg });
+            if (!ctx)
+                return undefined;
+            const out = {};
+            for (const key of pinnedCandidates) {
+                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}`,
+            candidates: pinnedCandidates,
+            stickyKey: options.allowAliasRotation ? undefined : stickyKey,
+            weights,
+            availabilityCheck: (key) => deps.healthManager.isAvailable(key)
+        }, tier.mode === 'round-robin' ? 'round-robin' : undefined);
+    }
+    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) {
+            const providerId = extractProviderId(key) ?? '';
+            const cooldownMs = entry.cooldownUntil - now;
+            if (providerId !== 'antigravity' || cooldownMs >= ANTIGRAVITY_COOLDOWN_ALIAS_THRESHOLD_MS) {
+                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));
+        let bucketCandidates = bucket.map((item) => item.key);
+        // Single-provider pool should never be "emptied" by health/cooldown.
+        if (bucketCandidates.length === 1) {
+            return bucketCandidates[0] ?? null;
+        }
+        if (isRecoveryAttempt) {
+            bucketCandidates = preferAntigravityAliasesOnRetry({ candidates: bucketCandidates, excludedKeys, deps });
+        }
+        // Alias-level selection strategy (config-driven).
+        // For configured providers, we stick to one alias globally and rotate only on error/unavailability.
+        bucketCandidates = applyAliasStickyQueuePinning({
+            candidates: bucketCandidates,
+            orderedTargets: tier.targets,
+            deps,
+            excludedKeys,
+            now
+        });
+        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({ candidates: bucketCandidates, usage: contextResult.usage, warnRatio, cfg: contextWeightedCfg });
+            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({
+                    candidates: bucketCandidates,
+                    orderedTargets: tier.targets,
+                    providerRegistry: deps.providerRegistry,
+                    healthManager: deps.healthManager,
+                    penalties: 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;
+}

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

@@ -0,0 +1,3 @@
+import type { RoutePoolTier, RoutingFeatures } from '../types.js';
+import type { SelectionDeps, TrySelectFromTierOptions, SelectionResult } from './selection-deps.js';
+export declare function trySelectFromTier(routeName: string, tier: RoutePoolTier, stickyKey: string | undefined, estimatedTokens: number, features: RoutingFeatures, deps: SelectionDeps, options: TrySelectFromTierOptions): SelectionResult;

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

@@ -0,0 +1,228 @@
+import { DEFAULT_ROUTE } from '../types.js';
+import { resolveContextWeightedConfig } from '../context-weighted.js';
+import { resolveHealthWeightedConfig } from '../health-weighted.js';
+import { pinCandidatesByAliasQueue, resolveAliasSelectionStrategy } from './alias-selection.js';
+import { extractKeyAlias, extractKeyIndex, extractProviderId, getProviderModelId } from './key-parsing.js';
+import { selectProviderKeyFromCandidatePool } from './tier-selection-select.js';
+export 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 = Array.isArray(features.metadata?.excludedProviderKeys)
+        ? features.metadata.excludedProviderKeys
+            .filter((val) => typeof val === 'string')
+            .map((val) => val.trim())
+            .filter((val) => val.length > 0)
+        : [];
+    const excludedKeys = new Set(excludedRaw);
+    if (excludedKeys.size > 0) {
+        recordAliasQueueFailuresFromExcludedKeys(excludedKeys, tier.targets, deps);
+    }
+    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, routeName);
+    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();
+    for (const candidatePool of prioritizedPools) {
+        const providerKey = selectProviderKeyFromCandidatePool({
+            routeName,
+            tier,
+            stickyKey,
+            candidates: candidatePool,
+            isSafePool: candidatePool === contextResult.safe,
+            deps,
+            options,
+            contextResult,
+            warnRatio,
+            excludedKeys,
+            isRecoveryAttempt,
+            now,
+            nowForWeights,
+            healthWeightedCfg,
+            contextWeightedCfg
+        });
+        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)
+    };
+}
+function recordAliasQueueFailuresFromExcludedKeys(excludedKeys, orderedTargets, deps) {
+    const store = deps.aliasQueueStore;
+    if (!store || !excludedKeys || excludedKeys.size === 0) {
+        return;
+    }
+    if (!Array.isArray(orderedTargets) || orderedTargets.length === 0) {
+        return;
+    }
+    for (const ex of excludedKeys) {
+        if (!ex || typeof ex !== 'string')
+            continue;
+        const providerId = extractProviderId(ex) ?? '';
+        if (!providerId)
+            continue;
+        const strategy = resolveAliasSelectionStrategy(providerId, deps.loadBalancer.getPolicy().aliasSelection);
+        if (strategy !== 'sticky-queue')
+            continue;
+        const modelId = getProviderModelId(ex, deps.providerRegistry) ?? '';
+        if (!modelId)
+            continue;
+        const groupCandidates = orderedTargets.filter((key) => (extractProviderId(key) ?? '') === providerId && (getProviderModelId(key, deps.providerRegistry) ?? '') === modelId);
+        if (groupCandidates.length < 2)
+            continue;
+        try {
+            pinCandidatesByAliasQueue({
+                queueStore: store,
+                providerId,
+                modelId,
+                candidates: groupCandidates,
+                orderedTargets,
+                excludedProviderKeys: new Set([ex]),
+                aliasOfKey: extractKeyAlias,
+                modelIdOfKey: (key) => getProviderModelId(key, deps.providerRegistry),
+                availabilityCheck: () => true
+            });
+        }
+        catch {
+            // best-effort: alias queue rotation must not block selection
+        }
+    }
+}
+function buildContextCandidatePools(result, routeName) {
+    const ordered = [];
+    if (result.safe.length) {
+        ordered.push(result.safe);
+    }
+    if (result.risky.length) {
+        ordered.push(result.risky);
+    }
+    if (routeName === 'longcontext' && result.overflow.length) {
+        ordered.push(result.overflow);
+    }
+    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;
+}