@jsonstudio/llms 0.6.1172 → 0.6.1397

package/dist/router/virtual-router/bootstrap.js

@@ -1094,7 +1094,7 @@ function normalizeScopeList(value) {
     }
     if (typeof value === 'string' && value.trim()) {
         const normalized = value
-            .split(/[\,\s]+/)
+            .split(/[,\s]+/)
             .map((item) => item.trim())
             .filter(Boolean);
         return normalized.length ? normalized : undefined;
@@ -1146,9 +1146,6 @@ function normalizeLoadBalancing(input) {
         return undefined;
     const record = input;
     const strategyRaw = typeof record.strategy === 'string' ? record.strategy.trim().toLowerCase() : '';
-    if (!strategyRaw)
-        return undefined;
-    const strategy = strategyRaw === 'weighted' || strategyRaw === 'sticky' ? strategyRaw : 'round-robin';
     const weightsRaw = asRecord(record.weights);
     const weightsEntries = {};
     for (const [key, value] of Object.entries(weightsRaw)) {
@@ -1192,13 +1189,66 @@ function normalizeLoadBalancing(input) {
                 : {})
         }
         : undefined;
+    const aliasSelection = normalizeAliasSelection(record.aliasSelection);
+    const hasNonStrategyConfig = Object.keys(weightsEntries).length > 0 ||
+        Boolean(healthWeighted) ||
+        Boolean(contextWeighted) ||
+        Boolean(aliasSelection);
+    if (!strategyRaw && !hasNonStrategyConfig) {
+        return undefined;
+    }
+    const strategy = strategyRaw === 'weighted' || strategyRaw === 'sticky' ? strategyRaw : 'round-robin';
     return {
         strategy,
         ...(Object.keys(weightsEntries).length ? { weights: weightsEntries } : {}),
+        ...(aliasSelection ? { aliasSelection } : {}),
         ...(healthWeighted ? { healthWeighted } : {}),
         ...(contextWeighted ? { contextWeighted } : {})
     };
 }
+function normalizeAliasSelection(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return undefined;
+    }
+    const record = raw;
+    const enabled = typeof record.enabled === 'boolean' ? record.enabled : undefined;
+    const defaultStrategy = coerceAliasSelectionStrategy(record.defaultStrategy);
+    const providersRaw = asRecord(record.providers);
+    const providers = {};
+    for (const [providerId, value] of Object.entries(providersRaw)) {
+        const strategy = coerceAliasSelectionStrategy(value);
+        if (strategy) {
+            providers[providerId] = strategy;
+        }
+    }
+    const out = {
+        ...(enabled !== undefined ? { enabled } : {}),
+        ...(defaultStrategy ? { defaultStrategy } : {}),
+        ...(Object.keys(providers).length ? { providers } : {})
+    };
+    return Object.keys(out).length ? out : undefined;
+}
+function coerceAliasSelectionStrategy(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (!normalized) {
+        return undefined;
+    }
+    if (normalized === 'none')
+        return 'none';
+    if (normalized === 'sticky-queue' || normalized === 'sticky_queue' || normalized === 'stickyqueue') {
+        return 'sticky-queue';
+    }
+    if (normalized === 'best-quota' ||
+        normalized === 'best_quota' ||
+        normalized === 'quota-best' ||
+        normalized === 'quota_best') {
+        return 'best-quota';
+    }
+    return undefined;
+}
 function coerceRatio(value) {
     if (typeof value === 'number' && Number.isFinite(value)) {
         return value;

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

@@ -7,7 +7,6 @@ type DebugLike = {
 export declare function resetRateLimitBackoffForProvider(providerKey: string): void;
 export declare function handleProviderFailureImpl(event: ProviderFailureEvent, healthManager: ProviderHealthManager, healthConfig: Required<ProviderHealthConfig>, markProviderCooldown: (providerKey: string, cooldownMs: number | undefined) => void): void;
 export declare function mapProviderErrorImpl(event: ProviderErrorEvent, healthConfig: Required<ProviderHealthConfig>): ProviderFailureEvent | null;
-export declare function applySeriesCooldownImpl(event: ProviderErrorEvent, providerRegistry: ProviderRegistry, healthManager: ProviderHealthManager, markProviderCooldown: (providerKey: string, cooldownMs: number | undefined) => void, debug?: DebugLike): void;
 /**
  * 处理来自 Host 侧的配额恢复事件：
  * - 清除指定 providerKey 在健康管理器中的熔断/冷却状态；
@@ -18,5 +17,6 @@ export declare function applySeriesCooldownImpl(event: ProviderErrorEvent, provi
  */
 export declare function applyQuotaRecoveryImpl(event: ProviderErrorEvent, healthManager: ProviderHealthManager, clearProviderCooldown: (providerKey: string) => void, debug?: DebugLike): boolean;
 export declare function applyQuotaDepletedImpl(event: ProviderErrorEvent, healthManager: ProviderHealthManager, markProviderCooldown: (providerKey: string, cooldownMs: number | undefined) => void, debug?: DebugLike): boolean;
+export declare function applySeriesCooldownImpl(event: ProviderErrorEvent, _providerRegistry: ProviderRegistry, _healthManager: ProviderHealthManager, _markProviderCooldown: (providerKey: string, cooldownMs: number | undefined) => void, debug?: DebugLike): boolean;
 export declare function deriveReason(code: string, stage: string, statusCode?: number): string;
 export {};

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

@@ -1,4 +1,3 @@
-const SERIES_COOLDOWN_DETAIL_KEY = 'virtualRouterSeriesCooldown';
 const QUOTA_RECOVERY_DETAIL_KEY = 'virtualRouterQuotaRecovery';
 const QUOTA_DEPLETED_DETAIL_KEY = 'virtualRouterQuotaDepleted';
 function parseDurationToMs(value) {
@@ -196,46 +195,6 @@ export function mapProviderErrorImpl(event, healthConfig) {
         }
     };
 }
-export function applySeriesCooldownImpl(event, providerRegistry, healthManager, markProviderCooldown, debug) {
-    const seriesDetail = extractSeriesCooldownDetail(event);
-    if (!seriesDetail) {
-        return;
-    }
-    const targetKeys = resolveSeriesCooldownTargets(seriesDetail, event, providerRegistry);
-    if (targetKeys.length === 0) {
-        debug?.log?.('[virtual-router] series cooldown skipped: no targets', {
-            providerId: seriesDetail.providerId,
-            providerKey: seriesDetail.providerKey,
-            series: seriesDetail.series
-        });
-        return;
-    }
-    const affected = [];
-    for (const providerKey of targetKeys) {
-        try {
-            const profile = providerRegistry.get(providerKey);
-            const modelSeries = resolveModelSeries(profile.modelId);
-            if (modelSeries !== seriesDetail.series) {
-                continue;
-            }
-            healthManager.tripProvider(providerKey, 'rate_limit', seriesDetail.cooldownMs);
-            markProviderCooldown(providerKey, seriesDetail.cooldownMs);
-            affected.push(providerKey);
-        }
-        catch {
-            // ignore lookup failures; invalid keys may show up if config drifted
-        }
-    }
-    if (affected.length) {
-        debug?.log?.('[virtual-router] series cooldown', {
-            providerId: seriesDetail.providerId,
-            providerKey: seriesDetail.providerKey,
-            series: seriesDetail.series,
-            cooldownMs: seriesDetail.cooldownMs,
-            affected
-        });
-    }
-}
 function extractQuotaRecoveryDetail(event) {
     if (!event || !event.details || typeof event.details !== 'object') {
         return null;
@@ -326,63 +285,21 @@ export function applyQuotaDepletedImpl(event, healthManager, markProviderCooldow
     }
     return true;
 }
-function resolveSeriesCooldownTargets(detail, event, providerRegistry) {
-    const candidates = new Set();
-    const push = (key) => {
-        if (typeof key !== 'string') {
-            return;
-        }
-        const trimmed = key.trim();
-        if (!trimmed) {
-            return;
-        }
-        if (providerRegistry.has(trimmed)) {
-            candidates.add(trimmed);
-        }
-    };
-    push(detail.providerKey);
-    const runtimeKey = (event.runtime?.target && typeof event.runtime.target === 'object'
-        ? event.runtime.target.providerKey
-        : undefined) || event.runtime?.providerKey;
-    push(runtimeKey);
-    return Array.from(candidates);
-}
-function extractSeriesCooldownDetail(event) {
+export function applySeriesCooldownImpl(event, _providerRegistry, _healthManager, _markProviderCooldown, debug) {
     if (!event || !event.details || typeof event.details !== 'object') {
-        return null;
+        return false;
     }
-    const raw = event.details[SERIES_COOLDOWN_DETAIL_KEY];
+    const raw = event.details.virtualRouterSeriesCooldown;
     if (!raw || typeof raw !== 'object') {
-        return null;
-    }
-    const record = raw;
-    const providerIdRaw = record.providerId;
-    const seriesRaw = record.series;
-    const providerKeyRaw = record.providerKey;
-    const cooldownRaw = record.cooldownMs;
-    if (typeof providerIdRaw !== 'string' || !providerIdRaw.trim()) {
-        return null;
-    }
-    const normalizedSeries = typeof seriesRaw === 'string' ? seriesRaw.trim().toLowerCase() : '';
-    if (normalizedSeries !== 'gemini-pro' && normalizedSeries !== 'gemini-flash' && normalizedSeries !== 'claude') {
-        return null;
-    }
-    const cooldownMs = typeof cooldownRaw === 'number'
-        ? cooldownRaw
-        : typeof cooldownRaw === 'string'
-            ? Number.parseFloat(cooldownRaw)
-            : Number.NaN;
-    if (!Number.isFinite(cooldownMs) || cooldownMs <= 0) {
-        return null;
+        return false;
     }
-    return {
-        providerId: providerIdRaw.trim(),
-        ...(typeof providerKeyRaw === 'string' && providerKeyRaw.trim().length
-            ? { providerKey: providerKeyRaw.trim() }
-            : {}),
-        series: normalizedSeries,
-        cooldownMs: Math.round(cooldownMs)
-    };
+    const detail = raw;
+    debug?.log?.('[virtual-router] series cooldown ignored', {
+        providerId: detail.providerId,
+        series: detail.series,
+        cooldownMs: detail.cooldownMs
+    });
+    return true;
 }
 export function deriveReason(code, stage, statusCode) {
     if (code.includes('RATE') || code.includes('429'))
@@ -401,19 +318,3 @@ export function deriveReason(code, stage, statusCode) {
         return 'client_error';
     return 'unknown';
 }
-function resolveModelSeries(modelId) {
-    if (!modelId) {
-        return 'default';
-    }
-    const lower = modelId.toLowerCase();
-    if (lower.includes('claude') || lower.includes('opus')) {
-        return 'claude';
-    }
-    if (lower.includes('flash')) {
-        return 'gemini-flash';
-    }
-    if (lower.includes('gemini') || lower.includes('pro')) {
-        return 'gemini-pro';
-    }
-    return 'default';
-}

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

@@ -0,0 +1,30 @@
+import type { AliasSelectionConfig, AliasSelectionStrategy } from '../types.js';
+export type AliasQueueStore = Map<string, string[]>;
+export declare const DEFAULT_PROVIDER_ALIAS_SELECTION: Record<string, AliasSelectionStrategy>;
+export declare function resolveAliasSelectionStrategy(providerId: string, cfg: AliasSelectionConfig | undefined): AliasSelectionStrategy;
+export declare function pinCandidatesByAliasQueue(opts: {
+    queueStore: AliasQueueStore | undefined;
+    providerId: string;
+    modelId: string;
+    candidates: string[];
+    orderedTargets: string[];
+    excludedProviderKeys: Set<string>;
+    aliasOfKey: (providerKey: string) => string | null;
+    modelIdOfKey: (providerKey: string) => string | null;
+    availabilityCheck: (providerKey: string) => boolean;
+}): string[] | null;
+export declare function pinCandidatesByBestQuota(opts: {
+    providerId: string;
+    modelId: string;
+    candidates: string[];
+    orderedTargets: string[];
+    aliasOfKey: (providerKey: string) => string | null;
+    modelIdOfKey: (providerKey: string) => string | null;
+    quotaView: ((providerKey: string) => {
+        remainingFraction?: number | null;
+        inPool: boolean;
+        cooldownUntil?: number | null;
+        blacklistUntil?: number | null;
+    } | null) | undefined;
+    now: number;
+}): string[] | null;

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

@@ -0,0 +1,237 @@
+const COOLDOWN_EMPTY_THRESHOLD_MS = 30_000;
+// Default provider-level strategy table.
+// This is a data-only default; callers can override via `loadBalancing.aliasSelection.providers`.
+export const DEFAULT_PROVIDER_ALIAS_SELECTION = {
+    // Antigravity: prefer the alias with highest remaining quota; fall back to sticky-queue when quota is unknown.
+    antigravity: 'best-quota'
+};
+export function resolveAliasSelectionStrategy(providerId, cfg) {
+    if (!providerId)
+        return 'none';
+    if (cfg?.enabled === false)
+        return 'none';
+    const overrides = cfg?.providers ?? {};
+    const override = overrides[providerId];
+    if (override === 'none' || override === 'sticky-queue' || override === 'best-quota') {
+        return override;
+    }
+    const def = cfg?.defaultStrategy;
+    if (def === 'none' || def === 'sticky-queue' || def === 'best-quota') {
+        return def;
+    }
+    const table = DEFAULT_PROVIDER_ALIAS_SELECTION[providerId];
+    return table ?? 'none';
+}
+export function pinCandidatesByAliasQueue(opts) {
+    const { queueStore, providerId, modelId, candidates, orderedTargets, excludedProviderKeys, aliasOfKey, modelIdOfKey, availabilityCheck } = opts;
+    if (!queueStore)
+        return null;
+    if (!providerId || !modelId)
+        return null;
+    if (!Array.isArray(candidates) || candidates.length < 2)
+        return null;
+    const aliasBuckets = new Map();
+    for (const key of candidates) {
+        if (!key || typeof key !== 'string')
+            continue;
+        if (!key.startsWith(`${providerId}.`))
+            return null;
+        const m = modelIdOfKey(key);
+        if (!m || m !== modelId)
+            return null;
+        const alias = aliasOfKey(key);
+        if (!alias)
+            return null;
+        const list = aliasBuckets.get(alias) ?? [];
+        list.push(key);
+        aliasBuckets.set(alias, list);
+    }
+    if (aliasBuckets.size <= 1)
+        return null;
+    const queueKey = `${providerId}::${modelId}`;
+    const desiredOrder = resolveAliasOrderFromTargets({
+        orderedTargets,
+        providerId,
+        modelId,
+        aliasOfKey,
+        modelIdOfKey,
+        allowedAliases: new Set(aliasBuckets.keys())
+    });
+    let queue = mergeAliasQueue(queueStore.get(queueKey) ?? [], desiredOrder);
+    // If this is a retry attempt and the previous alias was excluded, rotate it to the tail.
+    if (excludedProviderKeys && excludedProviderKeys.size) {
+        const excludedAliases = [];
+        for (const ex of excludedProviderKeys) {
+            if (!ex || typeof ex !== 'string')
+                continue;
+            if (!ex.startsWith(`${providerId}.`))
+                continue;
+            const exModel = modelIdOfKey(ex);
+            if (!exModel || exModel !== modelId)
+                continue;
+            const exAlias = aliasOfKey(ex);
+            if (exAlias)
+                excludedAliases.push(exAlias);
+        }
+        if (excludedAliases.length) {
+            queue = rotateQueueToTail(queue, excludedAliases);
+        }
+    }
+    // Ensure the head alias points to an available candidate; otherwise rotate until we find one.
+    if (queue.length) {
+        for (let i = 0; i < queue.length; i += 1) {
+            const head = queue[0];
+            const keys = aliasBuckets.get(head) ?? [];
+            const hasAvailable = keys.some((key) => availabilityCheck(key));
+            if (hasAvailable) {
+                break;
+            }
+            queue = rotateQueueToTail(queue, [head]);
+        }
+    }
+    // Persist queue updates (even if unchanged, ensure first-time init is stored).
+    queueStore.set(queueKey, queue);
+    const selectedAlias = queue[0];
+    if (!selectedAlias)
+        return null;
+    const selectedKeys = aliasBuckets.get(selectedAlias) ?? [];
+    if (!selectedKeys.length)
+        return null;
+    // Preserve original candidate order.
+    const selectedSet = new Set(selectedKeys);
+    return candidates.filter((key) => selectedSet.has(key));
+}
+export function pinCandidatesByBestQuota(opts) {
+    const { providerId, modelId, candidates, orderedTargets, aliasOfKey, modelIdOfKey, quotaView, now } = opts;
+    if (!quotaView)
+        return null;
+    if (!providerId || !modelId)
+        return null;
+    if (!Array.isArray(candidates) || candidates.length < 2)
+        return null;
+    const aliasBuckets = new Map();
+    const aliasOrder = new Map();
+    let order = 0;
+    for (const key of candidates) {
+        if (!key || typeof key !== 'string')
+            continue;
+        if (!key.startsWith(`${providerId}.`))
+            return null;
+        const m = modelIdOfKey(key);
+        if (!m || m !== modelId)
+            return null;
+        const alias = aliasOfKey(key);
+        if (!alias)
+            return null;
+        const list = aliasBuckets.get(alias) ?? [];
+        list.push(key);
+        aliasBuckets.set(alias, list);
+        if (!aliasOrder.has(alias)) {
+            aliasOrder.set(alias, order++);
+        }
+    }
+    if (aliasBuckets.size <= 1)
+        return null;
+    const preferredOrder = resolveAliasOrderFromTargets({
+        orderedTargets,
+        providerId,
+        modelId,
+        aliasOfKey,
+        modelIdOfKey,
+        allowedAliases: new Set(aliasBuckets.keys())
+    });
+    for (const alias of preferredOrder) {
+        if (!aliasOrder.has(alias)) {
+            aliasOrder.set(alias, order++);
+        }
+    }
+    const eligible = [];
+    for (const [alias, keys] of aliasBuckets.entries()) {
+        const entry = quotaView(keys[0] ?? '');
+        if (!entry || entry.inPool === false) {
+            continue;
+        }
+        if (entry.blacklistUntil && entry.blacklistUntil > now) {
+            continue;
+        }
+        if (entry.cooldownUntil && entry.cooldownUntil - now >= COOLDOWN_EMPTY_THRESHOLD_MS) {
+            continue;
+        }
+        const remainingRaw = entry.remainingFraction;
+        const remaining = typeof remainingRaw === 'number' && Number.isFinite(remainingRaw) ? remainingRaw : 0;
+        if (remaining <= 0) {
+            continue;
+        }
+        eligible.push({
+            alias,
+            score: remaining,
+            order: aliasOrder.get(alias) ?? Number.MAX_SAFE_INTEGER
+        });
+    }
+    if (!eligible.length) {
+        return null;
+    }
+    eligible.sort((a, b) => (b.score - a.score) || (a.order - b.order));
+    const selectedAlias = eligible[0]?.alias;
+    if (!selectedAlias)
+        return null;
+    const selectedKeys = aliasBuckets.get(selectedAlias) ?? [];
+    if (!selectedKeys.length)
+        return null;
+    const selectedSet = new Set(selectedKeys);
+    return candidates.filter((key) => selectedSet.has(key));
+}
+function resolveAliasOrderFromTargets(opts) {
+    const { orderedTargets, providerId, modelId, aliasOfKey, modelIdOfKey, allowedAliases } = opts;
+    if (!Array.isArray(orderedTargets) || orderedTargets.length === 0) {
+        return Array.from(allowedAliases);
+    }
+    const out = [];
+    const seen = new Set();
+    for (const key of orderedTargets) {
+        if (!key || typeof key !== 'string')
+            continue;
+        if (!key.startsWith(`${providerId}.`))
+            continue;
+        const m = modelIdOfKey(key);
+        if (!m || m !== modelId)
+            continue;
+        const alias = aliasOfKey(key);
+        if (!alias || !allowedAliases.has(alias) || seen.has(alias))
+            continue;
+        seen.add(alias);
+        out.push(alias);
+    }
+    for (const alias of Array.from(allowedAliases)) {
+        if (!seen.has(alias))
+            out.push(alias);
+    }
+    return out;
+}
+function mergeAliasQueue(existing, desired) {
+    if (!Array.isArray(existing) || existing.length === 0) {
+        return [...desired];
+    }
+    const desiredSet = new Set(desired);
+    const merged = existing.filter((a) => desiredSet.has(a));
+    const mergedSet = new Set(merged);
+    for (const a of desired) {
+        if (!mergedSet.has(a))
+            merged.push(a);
+    }
+    return merged;
+}
+function rotateQueueToTail(queue, aliases) {
+    if (!Array.isArray(queue) || queue.length < 2)
+        return queue;
+    if (!Array.isArray(aliases) || aliases.length === 0)
+        return queue;
+    const toMove = new Set(aliases);
+    const kept = queue.filter((a) => !toMove.has(a));
+    const moved = [];
+    for (const a of queue) {
+        if (toMove.has(a) && !moved.includes(a))
+            moved.push(a);
+    }
+    return [...kept, ...moved];
+}

package/dist/router/virtual-router/engine-selection/context-weight-multipliers.d.ts

@@ -0,0 +1,11 @@
+import { type ResolvedContextWeightedConfig } from '../context-weighted.js';
+import type { ContextAdvisorResult } from '../context-advisor.js';
+export declare function computeContextWeightMultipliers(opts: {
+    candidates: string[];
+    usage: ContextAdvisorResult['usage'] | undefined;
+    warnRatio: number;
+    cfg: ResolvedContextWeightedConfig;
+}): {
+    ref: number;
+    eff: Record<string, number>;
+} | null;

package/dist/router/virtual-router/engine-selection/context-weight-multipliers.js

@@ -0,0 +1,23 @@
+import { computeEffectiveSafeWindowTokens } from '../context-weighted.js';
+export function computeContextWeightMultipliers(opts) {
+    const { candidates, usage, warnRatio, cfg } = opts;
+    if (!cfg.enabled) {
+        return null;
+    }
+    const eff = {};
+    let ref = 1;
+    for (const key of candidates) {
+        const entry = usage?.[key];
+        const limit = entry && typeof entry.limit === 'number' && Number.isFinite(entry.limit) ? Math.floor(entry.limit) : 0;
+        const safeEff = computeEffectiveSafeWindowTokens({
+            modelMaxTokens: Math.max(1, limit),
+            warnRatio,
+            clientCapTokens: cfg.clientCapTokens
+        });
+        eff[key] = safeEff;
+        if (safeEff > ref) {
+            ref = safeEff;
+        }
+    }
+    return { ref, eff };
+}

package/dist/router/virtual-router/engine-selection/direct-provider-model.d.ts

@@ -0,0 +1,9 @@
+import type { RouterMetadataInput, RoutingFeatures } from '../types.js';
+import type { RoutingInstructionState } from '../routing-instructions.js';
+import type { SelectionDeps } from './selection-deps.js';
+export declare function selectDirectProviderModel(providerId: string, modelId: string, metadata: RouterMetadataInput, features: RoutingFeatures, activeState: RoutingInstructionState, deps: SelectionDeps): {
+    providerKey: string;
+    routeUsed: string;
+    pool: string[];
+    poolId?: string;
+} | null;

package/dist/router/virtual-router/engine-selection/direct-provider-model.js

@@ -0,0 +1,49 @@
+import { trySelectFromTier } from './tier-selection.js';
+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;
+}

package/dist/router/virtual-router/engine-selection/instruction-target.d.ts

@@ -0,0 +1,6 @@
+import type { RoutingInstructionState } from '../routing-instructions.js';
+import type { ProviderRegistry } from '../provider-registry.js';
+export declare function resolveInstructionTarget(target: NonNullable<RoutingInstructionState['forcedTarget']>, providerRegistry: ProviderRegistry): {
+    mode: 'exact' | 'filter';
+    keys: string[];
+} | null;

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

@@ -0,0 +1,54 @@
+import { getProviderModelId } from './key-parsing.js';
+export 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 };
+}