@jsonstudio/llms 0.6.1892 → 0.6.2172

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

@@ -9,15 +9,20 @@ import { getStatsCenter } from '../../telemetry/stats-center.js';
 import { parseRoutingInstructions, applyRoutingInstructions, cleanMessagesFromRoutingInstructions } from './routing-instructions.js';
 import { extractMessageText } from './message-utils.js';
 import { loadRoutingInstructionStateSync, saveRoutingInstructionStateAsync, saveRoutingInstructionStateSync } from './sticky-session-store.js';
-import { buildHitReason, formatVirtualRouterHit } from './engine-logging.js';
+import { buildHitReason, createVirtualRouterHitRecord, formatVirtualRouterHit, toVirtualRouterHitEvent } from './engine-logging.js';
 import { selectDirectProviderModel, selectFromStickyPool, selectProviderImpl } from './engine/routing-pools/index.js';
 import { applyQuotaDepletedImpl, applyQuotaRecoveryImpl, applySeriesCooldownImpl, applyAntigravityRiskPolicyImpl, handleProviderFailureImpl, mapProviderErrorImpl } from './engine/health/index.js';
 import { hydrateAntigravityAliasLeaseStoreIfNeeded, recordAntigravitySessionLease, resolveAntigravityAliasReuseCooldownMs } from './engine/antigravity/alias-lease.js';
 import { buildMetadataInstructions, resolveRoutingMode } from './engine/routing-state/metadata.js';
 import { getRoutingInstructionState, persistRoutingInstructionState, resolveStopMessageScope } from './engine/routing-state/store.js';
+import { ensureStopMessageModeMaxRepeats } from './routing-stop-message-state-codec.js';
 import { validateStopMessageStageTemplatesCompleteness } from './stop-message-stage-template-files.js';
 import { extractKeyAlias, extractKeyIndex, extractProviderId, getProviderModelId } from './engine/provider-key/parse.js';
 import { resolveSessionScope as resolveSessionScopeImpl, resolveStickyKey as resolveStickyKeyImpl } from './engine/routing-state/keys.js';
+import { RouteAnalytics } from './engine/route-analytics.js';
+import { StickySessionManager } from './engine/sticky-session-manager.js';
+import { CooldownManager } from './engine/cooldown-manager.js';
+const DEFAULT_STOP_MESSAGE_MAX_REPEATS = 10;
 function normalizeStopMessageStageMode(value) {
     if (typeof value !== 'string') {
         return undefined;
@@ -72,9 +77,12 @@ function hasRoutingInstructionMarker(messages) {
 function hasLatestUserRoutingInstructionMarker(messages) {
     for (let idx = messages.length - 1; idx >= 0; idx -= 1) {
         const message = messages[idx];
-        if (!message || message.role !== 'user') {
+        if (!message) {
             continue;
         }
+        if (message.role !== 'user') {
+            return false;
+        }
         const content = extractMessageText(message);
         if (!content) {
             return false;
@@ -83,25 +91,30 @@ function hasLatestUserRoutingInstructionMarker(messages) {
     }
     return false;
 }
+function isServerToolFollowupRequest(metadata) {
+    if (!metadata || typeof metadata !== 'object') {
+        return false;
+    }
+    const rt = metadata.__rt;
+    if (!rt || typeof rt !== 'object' || Array.isArray(rt)) {
+        return false;
+    }
+    const flag = rt.serverToolFollowup;
+    return (flag === true ||
+        (typeof flag === 'string' && flag.trim().toLowerCase() === 'true'));
+}
 export class VirtualRouterEngine {
     routing = {};
     providerRegistry = new ProviderRegistry();
     healthManager = new ProviderHealthManager();
-    providerCooldowns = new Map();
+    get providerCooldowns() { return this.cooldownManager.getCooldownMap(); }
     loadBalancer = new RouteLoadBalancer();
     classifier = new RoutingClassifier({});
     contextAdvisor = new ContextAdvisor();
     contextRouting;
-    routeStats = new Map();
-    // Alias selection state (global within this VirtualRouterEngine instance).
-    // Used by alias-selection strategies to avoid rapid cross-alias switching.
-    aliasQueueStore = new Map();
-    // Antigravity alias session lease store:
-    // - Enforces that one auth alias is not shared across different sessions within a cooldown window.
-    // - Tracks lastSeenAt per alias runtimeKey (providerId.keyAlias).
-    antigravityAliasLeaseStore = new Map();
-    antigravitySessionAliasStore = new Map();
-    antigravityAliasReuseCooldownMs = 5 * 60_000;
+    routeAnalytics = new RouteAnalytics();
+    stickySessionManager = new StickySessionManager();
+    cooldownManager;
     antigravityLeasePersistence = { loadedOnce: false, loadedMtimeMs: null, flushTimer: null };
     debug = console; // thin hook; host may monkey-patch for colored logging
     healthConfig = null;
@@ -116,7 +129,19 @@ export class VirtualRouterEngine {
     };
     routingInstructionState = new Map();
     quotaView;
+    /**
+     * Backward-compatible test/debug surface used by existing regression scripts.
+     * Keep this as a read-only view over StickySessionManager storage.
+     */
+    get antigravitySessionAliasStore() {
+        return this.stickySessionManager.getAllStores().sessionAliasStore;
+    }
     constructor(deps) {
+        this.cooldownManager = new CooldownManager({
+            healthStore: deps?.healthStore,
+            healthConfig: this.healthConfig,
+            quotaView: deps?.quotaView
+        });
         if (deps?.healthStore) {
             this.healthStore = deps.healthStore;
         }
@@ -133,6 +158,7 @@ export class VirtualRouterEngine {
         }
         if ('healthStore' in deps) {
             this.healthStore = deps.healthStore ?? undefined;
+            this.cooldownManager.updateDeps({ healthStore: this.healthStore });
         }
         if ('routingStateStore' in deps) {
             this.routingStateStore =
@@ -148,15 +174,16 @@ export class VirtualRouterEngine {
         if ('quotaView' in deps) {
             const prevQuotaEnabled = Boolean(this.quotaView);
             this.quotaView = deps.quotaView ?? undefined;
+            this.cooldownManager.updateDeps({ quotaView: this.quotaView });
             const nextQuotaEnabled = Boolean(this.quotaView);
             // When quotaView is enabled, health/cooldown decisions must be driven by quotaView only.
             // - Enabling quotaView: clear any legacy router-local cooldown TTLs immediately.
             // - Disabling quotaView: reload legacy cooldown state from health snapshots.
             if (!prevQuotaEnabled && nextQuotaEnabled) {
-                this.providerCooldowns.clear();
+                this.cooldownManager.clearAllCooldowns();
             }
             else if (prevQuotaEnabled && !nextQuotaEnabled) {
-                this.providerCooldowns.clear();
+                this.cooldownManager.clearAllCooldowns();
                 this.restoreHealthFromStore();
             }
         }
@@ -180,6 +207,24 @@ export class VirtualRouterEngine {
         }
         return { providerId, modelId };
     }
+    shouldFallbackDirectModelForMedia(direct, features) {
+        if (!features.hasImageAttachment) {
+            return false;
+        }
+        const providerId = direct.providerId.trim().toLowerCase();
+        const modelId = direct.modelId.trim().toLowerCase();
+        if (providerId !== 'qwen') {
+            return false;
+        }
+        const isQwen35Plus = modelId === 'qwen3.5-plus' || modelId === 'qwen3-5-plus' || modelId === 'qwen3_5-plus';
+        if (!isQwen35Plus) {
+            return false;
+        }
+        if (!(features.hasVideoAttachment === true && features.hasLocalVideoAttachment === true)) {
+            return false;
+        }
+        return this.routeHasTargets(this.routing.vision);
+    }
     initialize(config) {
         this.validateConfig(config);
         this.routing = config.routing;
@@ -187,23 +232,24 @@ export class VirtualRouterEngine {
         this.healthManager.configure(config.health);
         this.healthConfig = config.health ?? null;
         this.healthManager.registerProviders(Object.keys(config.providers));
-        this.providerCooldowns.clear();
+        this.cooldownManager.clearAllCooldowns();
         this.restoreHealthFromStore();
         this.loadBalancer = new RouteLoadBalancer(config.loadBalancing);
-        this.antigravityAliasReuseCooldownMs = resolveAntigravityAliasReuseCooldownMs(config);
+        const aliasReuseCooldownMs = resolveAntigravityAliasReuseCooldownMs(config);
+        this.stickySessionManager = new StickySessionManager(aliasReuseCooldownMs);
         hydrateAntigravityAliasLeaseStoreIfNeeded({
             force: true,
-            leaseStore: this.antigravityAliasLeaseStore,
+            leaseStore: this.stickySessionManager.getAllStores().aliasLeaseStore,
             persistence: this.antigravityLeasePersistence,
-            aliasReuseCooldownMs: this.antigravityAliasReuseCooldownMs
+            aliasReuseCooldownMs: this.stickySessionManager.getAliasReuseCooldownMs()
         });
         this.classifier = new RoutingClassifier(config.classifier);
         this.contextRouting = config.contextRouting ?? { warnRatio: 0.9, hardLimit: false };
         this.contextAdvisor.configure(this.contextRouting);
         this.webSearchForce = config.webSearch?.force === true;
-        this.routeStats = new Map();
+        this.routeAnalytics.getAllRouteStats().clear();
         for (const routeName of Object.keys(this.routing)) {
-            this.routeStats.set(routeName, { hits: 0 });
+            this.routeAnalytics.getRouteStats(routeName) || this.routeAnalytics.incrementRouteStat(routeName, '', { timestampMs: Date.now(), stopMessage: { active: false } });
         }
     }
     route(request, metadata) {
@@ -231,6 +277,10 @@ export class VirtualRouterEngine {
         }
         if (stopMessageScope) {
             const sessionState = getRoutingInstructionState(stopMessageScope, this.routingInstructionState, this.routingStateStore);
+            if (ensureStopMessageModeMaxRepeats(sessionState)) {
+                this.routingInstructionState.set(stopMessageScope, sessionState);
+                persistRoutingInstructionState(stopMessageScope, sessionState, this.routingStateStore);
+            }
             if (typeof sessionState.stopMessageText === 'string' ||
                 typeof sessionState.stopMessageMaxRepeats === 'number' ||
                 typeof sessionState.stopMessageStageMode === 'string') {
@@ -258,8 +308,16 @@ export class VirtualRouterEngine {
             }
         }
         const parsedInstructions = parseRoutingInstructions(request.messages);
+        const serverToolFollowup = isServerToolFollowupRequest(metadata);
         const latestUserHasMarker = hasLatestUserRoutingInstructionMarker(request.messages);
         let instructions = parsedInstructions;
+        if (serverToolFollowup && instructions.length > 0) {
+            instructions = instructions.filter((entry) => entry.type !== 'stopMessageSet' &&
+                entry.type !== 'stopMessageMode' &&
+                entry.type !== 'stopMessageClear' &&
+                entry.type !== 'preCommandSet' &&
+                entry.type !== 'preCommandClear');
+        }
         if (stopMessageScope && parsedInstructions.length > 0) {
             const sessionState = getRoutingInstructionState(stopMessageScope, this.routingInstructionState, this.routingStateStore);
             const hasStaleStopMessageInstruction = !latestUserHasMarker &&
@@ -278,7 +336,8 @@ export class VirtualRouterEngine {
                         entry.type !== 'stopMessageClear');
                 }
             }
-            const hasStopMessageClear = instructions.some((entry) => entry.type === 'stopMessageClear');
+            const hasGlobalClear = instructions.some((entry) => entry.type === 'clear');
+            const hasStopMessageClear = hasGlobalClear || instructions.some((entry) => entry.type === 'stopMessageClear');
             const stopMessageSets = instructions.filter((entry) => entry.type === 'stopMessageSet');
             if (!hasStopMessageClear && stopMessageSets.length > 0) {
                 const sessionText = typeof sessionState.stopMessageText === 'string' ? sessionState.stopMessageText.trim() : '';
@@ -308,8 +367,8 @@ export class VirtualRouterEngine {
         }
         // stopMessage must be session-scoped: require explicit sessionId in metadata.
         // This prevents global/default persistence and ensures the trigger matches the setting sessionId.
-        if (parsedInstructions.length > 0) {
-            const hasSessionScopedInstruction = parsedInstructions.some((entry) => entry.type === 'stopMessageSet' ||
+        if (instructions.length > 0) {
+            const hasSessionScopedInstruction = instructions.some((entry) => entry.type === 'stopMessageSet' ||
                 entry.type === 'stopMessageMode' ||
                 entry.type === 'stopMessageClear' ||
                 entry.type === 'preCommandSet' ||
@@ -318,7 +377,7 @@ export class VirtualRouterEngine {
                 throw new VirtualRouterError('[stopMessage/precommand] requires sessionId (e.g. set x-session-id header or metadata.sessionId).', VirtualRouterErrorCode.CONFIG_ERROR, { requestId: metadata.requestId, entryEndpoint: metadata.entryEndpoint });
             }
         }
-        if (stopMessageScope && parsedInstructions.length > 0) {
+        if (stopMessageScope && instructions.length > 0) {
             const sessionState = getRoutingInstructionState(stopMessageScope, this.routingInstructionState, this.routingStateStore);
             const nextStopMessageMode = resolveStopMessageStageModeAfterInstructions(instructions, sessionState.stopMessageStageMode);
             if (nextStopMessageMode === 'on') {
@@ -345,7 +404,8 @@ export class VirtualRouterEngine {
             if (stopMessageScope) {
                 const hasStopMessageSet = instructions.some((entry) => entry.type === 'stopMessageSet');
                 const hasStopMessageMode = instructions.some((entry) => entry.type === 'stopMessageMode');
-                const hasStopMessageClear = instructions.some((entry) => entry.type === 'stopMessageClear');
+                const hasGlobalClear = instructions.some((entry) => entry.type === 'clear');
+                const hasStopMessageClear = hasGlobalClear || instructions.some((entry) => entry.type === 'stopMessageClear');
                 if (hasStopMessageSet || hasStopMessageMode || hasStopMessageClear) {
                     const sessionState = getRoutingInstructionState(stopMessageScope, this.routingInstructionState, this.routingStateStore);
                     let nextSessionState = {
@@ -436,10 +496,27 @@ export class VirtualRouterEngine {
                                 nextSessionState.stopMessageStageMode = mode;
                                 shouldPersistSessionState = true;
                             }
-                            if (modeMaxRepeats > 0 &&
+                            const fallbackMaxRepeats = mode === 'on' || mode === 'auto'
+                                ? DEFAULT_STOP_MESSAGE_MAX_REPEATS
+                                : 0;
+                            const normalizedMaxRepeats = modeMaxRepeats > 0 ? modeMaxRepeats : fallbackMaxRepeats;
+                            if (normalizedMaxRepeats > 0 &&
                                 (typeof nextSessionState.stopMessageMaxRepeats !== 'number' ||
-                                    Math.floor(nextSessionState.stopMessageMaxRepeats) !== modeMaxRepeats)) {
-                                nextSessionState.stopMessageMaxRepeats = modeMaxRepeats;
+                                    Math.floor(nextSessionState.stopMessageMaxRepeats) !== normalizedMaxRepeats)) {
+                                nextSessionState.stopMessageMaxRepeats = normalizedMaxRepeats;
+                                shouldPersistSessionState = true;
+                            }
+                            // Explicit mode marker from latest user turn should re-arm lifecycle counters,
+                            // even when mode/max are unchanged (e.g. <**stopMessage:on,10**>).
+                            if (mode === 'on' || mode === 'auto') {
+                                nextSessionState.stopMessageUsed = 0;
+                                nextSessionState.stopMessageUpdatedAt = Date.now();
+                                nextSessionState.stopMessageLastUsedAt = undefined;
+                                nextSessionState.stopMessageStage = undefined;
+                                nextSessionState.stopMessageSource = 'explicit';
+                                nextSessionState.stopMessageObservationHash = undefined;
+                                nextSessionState.stopMessageObservationStableCount = 0;
+                                nextSessionState.stopMessageBdWorkState = undefined;
                                 shouldPersistSessionState = true;
                             }
                         }
@@ -579,6 +656,7 @@ export class VirtualRouterEngine {
             quotaView: this.quotaView
         };
         if (directProviderModel) {
+            const forceMediaFallback = this.shouldFallbackDirectModelForMedia(directProviderModel, features);
             const providerKeys = this.providerRegistry.listProviderKeys(directProviderModel.providerId);
             let hasModel = false;
             for (const key of providerKeys) {
@@ -596,19 +674,26 @@ export class VirtualRouterEngine {
             if (!hasModel) {
                 throw new VirtualRouterError(`Unknown model ${directProviderModel.modelId} for provider ${directProviderModel.providerId}`, VirtualRouterErrorCode.CONFIG_ERROR, { providerId: directProviderModel.providerId, modelId: directProviderModel.modelId });
             }
-            classification = {
-                routeName: 'direct',
-                confidence: 1,
-                reasoning: `direct_model:${directProviderModel.providerId}.${directProviderModel.modelId}`,
-                fallback: false,
-                candidates: ['direct']
-            };
-            requestedRoute = 'direct';
-            const directSelection = selectDirectProviderModel(directProviderModel.providerId, directProviderModel.modelId, metadata, features, routingState, selectionDeps);
-            if (!directSelection) {
-                throw new VirtualRouterError(`All providers unavailable for model ${directProviderModel.providerId}.${directProviderModel.modelId}`, VirtualRouterErrorCode.PROVIDER_NOT_AVAILABLE, { providerId: directProviderModel.providerId, modelId: directProviderModel.modelId });
+            if (!forceMediaFallback) {
+                const directSelection = selectDirectProviderModel(directProviderModel.providerId, directProviderModel.modelId, metadata, features, routingState, selectionDeps);
+                if (!directSelection) {
+                    throw new VirtualRouterError(`All providers unavailable for model ${directProviderModel.providerId}.${directProviderModel.modelId}`, VirtualRouterErrorCode.PROVIDER_NOT_AVAILABLE, { providerId: directProviderModel.providerId, modelId: directProviderModel.modelId });
+                }
+                classification = {
+                    routeName: 'direct',
+                    confidence: 1,
+                    reasoning: `direct_model:${directProviderModel.providerId}.${directProviderModel.modelId}`,
+                    fallback: false,
+                    candidates: ['direct']
+                };
+                requestedRoute = 'direct';
+                selection = directSelection;
+            }
+            else {
+                classification = this.classifier.classify(features);
+                requestedRoute = this.normalizeRouteAlias(classification.routeName || DEFAULT_ROUTE);
+                selection = this.selectProvider(requestedRoute, metadata, classification, features, routingState);
             }
-            selection = directSelection;
         }
         else {
             // Prefer target (from "<**!provider.model**>") is evaluated before routing classification.
@@ -763,38 +848,44 @@ export class VirtualRouterEngine {
             providerKey: selection.providerKey,
             sessionKey: this.resolveSessionScope(features.metadata),
             providerRegistry: this.providerRegistry,
-            leaseStore: this.antigravityAliasLeaseStore,
-            sessionAliasStore: this.antigravitySessionAliasStore,
+            leaseStore: this.stickySessionManager.getAllStores().aliasLeaseStore,
+            sessionAliasStore: this.stickySessionManager.getAllStores().sessionAliasStore,
             persistence: this.antigravityLeasePersistence,
-            aliasReuseCooldownMs: this.antigravityAliasReuseCooldownMs,
+            aliasReuseCooldownMs: this.stickySessionManager.getAliasReuseCooldownMs(),
             commitSessionBinding: false,
             debug: this.debug
         });
-        this.incrementRouteStat(selection.routeUsed, selection.providerKey);
         const routingMode = resolveRoutingMode([...metadataInstructions, ...instructions], routingState);
+        const hitReason = buildHitReason(selection.routeUsed, selection.providerKey, classification, features, routingMode, { providerRegistry: this.providerRegistry, contextRouting: this.contextRouting });
+        const stickyScope = routingMode !== 'none' ? this.resolveSessionScope(metadata) : undefined;
+        const routeForLog = routingMode === 'sticky' ? 'sticky' : selection.routeUsed;
+        const hitRecord = createVirtualRouterHitRecord({
+            routeName: routeForLog,
+            poolId: selection.poolId,
+            providerKey: selection.providerKey,
+            modelId: target.modelId || undefined,
+            hitReason,
+            stickyScope,
+            routingState,
+            requestTokens: features.estimatedTokens,
+            selectionPenalty: this.resolveSelectionPenalty(selection.providerKey)
+        });
+        this.routeAnalytics.incrementRouteStat(selection.routeUsed, selection.providerKey, hitRecord);
         try {
-            this.statsCenter.recordVirtualRouterHit({
+            this.statsCenter.recordVirtualRouterHit(toVirtualRouterHitEvent(hitRecord, {
                 requestId: metadata.requestId,
-                timestamp: Date.now(),
-                entryEndpoint: metadata.entryEndpoint || '/v1/chat/completions',
-                routeName: selection.routeUsed,
-                pool: selection.poolId || selection.routeUsed,
-                providerKey: selection.providerKey,
-                modelId: target.modelId || undefined
-            });
+                entryEndpoint: metadata.entryEndpoint || '/v1/chat/completions'
+            }));
         }
         catch {
             // stats must never break routing
         }
-        const hitReason = buildHitReason(selection.routeUsed, selection.providerKey, classification, features, routingMode, { providerRegistry: this.providerRegistry, contextRouting: this.contextRouting });
-        const stickyScope = routingMode !== 'none' ? this.resolveSessionScope(metadata) : undefined;
-        const routeForLog = routingMode === 'sticky' ? 'sticky' : selection.routeUsed;
-        const formatted = formatVirtualRouterHit(routeForLog, selection.poolId, selection.providerKey, target.modelId || '', hitReason, stickyScope, routingState);
+        const formatted = formatVirtualRouterHit(hitRecord);
         if (formatted) {
             this.debug?.log?.(formatted);
         }
         else {
-            this.debug?.log?.('[virtual-router-hit]', selection.routeUsed, selection.providerKey, target.modelId || '', hitReason ? `reason=${hitReason}` : '');
+            this.debug?.log?.(formatVirtualRouterHit(hitRecord));
         }
         const didFallback = selection.routeUsed !== requestedRoute;
         return {
@@ -986,10 +1077,10 @@ export class VirtualRouterEngine {
                 providerKey,
                 sessionKey: this.resolveSessionScope(metadata),
                 providerRegistry: this.providerRegistry,
-                leaseStore: this.antigravityAliasLeaseStore,
-                sessionAliasStore: this.antigravitySessionAliasStore,
+                leaseStore: this.stickySessionManager.getAllStores().aliasLeaseStore,
+                sessionAliasStore: this.stickySessionManager.getAllStores().sessionAliasStore,
                 persistence: this.antigravityLeasePersistence,
-                aliasReuseCooldownMs: this.antigravityAliasReuseCooldownMs,
+                aliasReuseCooldownMs: this.stickySessionManager.getAliasReuseCooldownMs(),
                 commitSessionBinding: true,
                 debug: this.debug
             });
@@ -998,11 +1089,12 @@ export class VirtualRouterEngine {
     getStatus() {
         const routes = {};
         for (const [route, pools] of Object.entries(this.routing)) {
-            const stats = this.routeStats.get(route) ?? { hits: 0 };
+            const stats = this.routeAnalytics.getRouteStats(route);
             routes[route] = {
                 providers: this.flattenPoolTargets(pools),
-                hits: stats.hits,
-                lastUsedProvider: stats.lastProvider
+                hits: stats?.hits ?? 0,
+                lastUsedProvider: stats?.lastProvider,
+                ...(stats?.lastHit ? { lastHit: { ...stats.lastHit } } : {})
             };
         }
         return {
@@ -1062,22 +1154,30 @@ export class VirtualRouterEngine {
             contextAdvisor: this.contextAdvisor,
             loadBalancer: this.loadBalancer,
             isProviderCoolingDown: (key) => this.isProviderCoolingDown(key),
+            getProviderCooldownRemainingMs: (key) => this.getProviderCooldownRemainingMs(key),
             resolveStickyKey: (m) => this.resolveStickyKey(m),
             quotaView: this.quotaView,
-            aliasQueueStore: this.aliasQueueStore,
-            antigravityAliasLeaseStore: this.antigravityAliasLeaseStore,
-            antigravitySessionAliasStore: this.antigravitySessionAliasStore,
-            antigravityAliasReuseCooldownMs: this.antigravityAliasReuseCooldownMs
+            aliasQueueStore: this.stickySessionManager.getAllStores().aliasQueueStore,
+            antigravityAliasLeaseStore: this.stickySessionManager.getAllStores().aliasLeaseStore,
+            antigravitySessionAliasStore: this.stickySessionManager.getAllStores().sessionAliasStore,
+            antigravityAliasReuseCooldownMs: this.stickySessionManager.getAliasReuseCooldownMs()
         }, { routingState });
     }
-    incrementRouteStat(routeName, providerKey) {
-        if (!this.routeStats.has(routeName)) {
-            this.routeStats.set(routeName, { hits: 0, lastProvider: providerKey });
-            return;
+    resolveSelectionPenalty(providerKey) {
+        if (!this.quotaView) {
+            return undefined;
+        }
+        try {
+            const entry = this.quotaView(providerKey);
+            const raw = entry?.selectionPenalty;
+            if (typeof raw !== 'number' || !Number.isFinite(raw) || raw <= 0) {
+                return undefined;
+            }
+            return Math.floor(raw);
+        }
+        catch {
+            return undefined;
         }
-        const stats = this.routeStats.get(routeName);
-        stats.hits += 1;
-        stats.lastProvider = providerKey;
     }
     providerHealthConfig() {
         return this.healthManager.getConfig();
@@ -1214,9 +1314,10 @@ export class VirtualRouterEngine {
             contextAdvisor: this.contextAdvisor,
             loadBalancer: this.loadBalancer,
             isProviderCoolingDown: (key) => this.isProviderCoolingDown(key),
+            getProviderCooldownRemainingMs: (key) => this.getProviderCooldownRemainingMs(key),
             resolveStickyKey: (m) => this.resolveStickyKey(m),
             quotaView: this.quotaView,
-            aliasQueueStore: this.aliasQueueStore
+            aliasQueueStore: this.stickySessionManager.getAllStores().aliasQueueStore
         }, { routingState: state });
     }
     /**
@@ -1342,22 +1443,16 @@ export class VirtualRouterEngine {
     }
     // mapProviderError/applySeriesCooldown moved to engine-health.ts
     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);
+        return this.routeAnalytics.extractExcludedProviderKeySet(metadata);
     }
     buildRouteCandidates(requestedRoute, classificationCandidates, features) {
         const forceVision = this.routeHasForceFlag('vision');
         const hasMultimodalTargets = this.routeHasTargets(this.routing.multimodal);
         const hasVisionTargets = this.routeHasTargets(this.routing.vision);
+        const hasLocalVideoAttachment = features.hasVideoAttachment === true && features.hasLocalVideoAttachment === true;
+        if (features.hasImageAttachment && hasLocalVideoAttachment && hasVisionTargets) {
+            return ['vision'];
+        }
         const normalized = this.normalizeRouteAlias(requestedRoute || DEFAULT_ROUTE);
         const baseList = [];
         if (classificationCandidates && classificationCandidates.length) {
@@ -1374,9 +1469,9 @@ export class VirtualRouterEngine {
                     baseList.unshift('multimodal');
                 }
             }
-            else if (hasVisionTargets) {
+            if (hasVisionTargets) {
                 if (!baseList.includes('vision')) {
-                    baseList.unshift('vision');
+                    baseList.push('vision');
                 }
             }
             if (!forceVision && hasMultimodalTargets) {
@@ -1558,125 +1653,34 @@ export class VirtualRouterEngine {
         return flattened;
     }
     markProviderCooldown(providerKey, cooldownMs) {
-        if (!providerKey) {
-            return;
-        }
-        const ttl = typeof cooldownMs === 'number' ? Math.round(cooldownMs) : Number.NaN;
-        if (!Number.isFinite(ttl) || ttl <= 0) {
-            return;
-        }
-        this.providerCooldowns.set(providerKey, Date.now() + ttl);
-        this.persistHealthSnapshot();
+        this.cooldownManager.markProviderCooldown(providerKey, cooldownMs);
     }
     clearProviderCooldown(providerKey) {
-        if (!providerKey) {
-            return;
-        }
-        if (this.providerCooldowns.delete(providerKey)) {
-            this.persistHealthSnapshot();
-        }
+        this.cooldownManager.clearProviderCooldown(providerKey);
     }
     isProviderCoolingDown(providerKey) {
+        return this.cooldownManager.isProviderCoolingDown(providerKey);
+    }
+    getProviderCooldownRemainingMs(providerKey) {
         if (!providerKey) {
-            return false;
+            return 0;
         }
         const expiry = this.providerCooldowns.get(providerKey);
-        if (!expiry) {
-            return false;
+        if (!expiry || !Number.isFinite(expiry)) {
+            return 0;
         }
-        if (Date.now() >= expiry) {
-            this.providerCooldowns.delete(providerKey);
-            return false;
-        }
-        return true;
+        const remaining = Math.floor(expiry - Date.now());
+        return remaining > 0 ? remaining : 0;
     }
     restoreHealthFromStore() {
-        if (!this.healthStore || typeof this.healthStore.loadInitialSnapshot !== 'function') {
-            return;
-        }
-        // When quotaView is enabled, health/cooldown must be driven by quotaView only.
-        // Do not restore legacy router-local cooldown TTLs from health snapshots.
-        if (this.quotaView) {
-            return;
-        }
-        let snapshot = null;
-        try {
-            snapshot = this.healthStore.loadInitialSnapshot();
-        }
-        catch {
-            snapshot = null;
-        }
-        if (!snapshot) {
-            return;
-        }
-        const now = Date.now();
-        const providerKeys = new Set();
-        for (const pools of Object.values(this.routing)) {
-            for (const pool of pools) {
-                for (const key of pool.targets) {
-                    if (typeof key === 'string' && key) {
-                        providerKeys.add(key);
-                    }
-                }
-            }
-        }
-        const byKey = new Map();
-        for (const entry of snapshot.cooldowns || []) {
-            if (!entry || !entry.providerKey) {
-                continue;
-            }
-            if (!providerKeys.has(entry.providerKey)) {
-                continue;
-            }
-            if (!Number.isFinite(entry.cooldownExpiresAt) || entry.cooldownExpiresAt <= now) {
-                continue;
-            }
-            byKey.set(entry.providerKey, entry);
-            this.providerCooldowns.set(entry.providerKey, entry.cooldownExpiresAt);
-        }
-        for (const state of snapshot.providers || []) {
-            if (!state || !state.providerKey) {
-                continue;
-            }
-            if (!providerKeys.has(state.providerKey)) {
-                continue;
-            }
-            if (state.cooldownExpiresAt && state.cooldownExpiresAt > now) {
-                const ttl = state.cooldownExpiresAt - now;
-                if (ttl > 0) {
-                    this.healthManager.tripProvider(state.providerKey, state.reason, ttl);
-                    if (!byKey.has(state.providerKey)) {
-                        this.providerCooldowns.set(state.providerKey, state.cooldownExpiresAt);
-                    }
-                }
-            }
-        }
+        this.cooldownManager.restoreHealthFromStore();
     }
     buildHealthSnapshot() {
         const providers = this.healthManager.getSnapshot();
-        const cooldowns = [];
-        const now = Date.now();
-        for (const [providerKey, expiry] of this.providerCooldowns.entries()) {
-            if (!expiry || expiry <= now) {
-                continue;
-            }
-            cooldowns.push({
-                providerKey,
-                cooldownExpiresAt: expiry
-            });
-        }
-        return { providers, cooldowns };
+        const cooldownSnapshot = this.cooldownManager.buildHealthSnapshot();
+        return { providers, cooldowns: cooldownSnapshot.cooldowns };
     }
     persistHealthSnapshot() {
-        if (!this.healthStore || typeof this.healthStore.persistSnapshot !== 'function') {
-            return;
-        }
-        try {
-            const snapshot = this.buildHealthSnapshot();
-            this.healthStore.persistSnapshot(snapshot);
-        }
-        catch {
-            // 持久化失败不影响路由主流程
-        }
+        this.cooldownManager.persistHealthSnapshot();
     }
 }