@jsonstudio/llms 0.6.1643 → 0.6.1739

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

@@ -4,17 +4,18 @@ import { RouteLoadBalancer } from './load-balancer.js';
 import { RoutingClassifier } from './classifier.js';
 import { buildRoutingFeatures } from './features.js';
 import { ContextAdvisor } from './context-advisor.js';
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
 import { DEFAULT_ROUTE, ROUTE_PRIORITY, VirtualRouterError, VirtualRouterErrorCode } from './types.js';
 import { getStatsCenter } from '../../telemetry/stats-center.js';
 import { parseRoutingInstructions, applyRoutingInstructions, cleanMessagesFromRoutingInstructions } from './routing-instructions.js';
 import { loadRoutingInstructionStateSync, saveRoutingInstructionStateAsync, saveRoutingInstructionStateSync } from './sticky-session-store.js';
 import { buildHitReason, formatVirtualRouterHit } from './engine-logging.js';
-import { selectDirectProviderModel, selectFromStickyPool, selectProviderImpl } from './engine-selection.js';
-import { applyQuotaDepletedImpl, applyQuotaRecoveryImpl, applySeriesCooldownImpl, applyAntigravityRiskPolicyImpl, handleProviderFailureImpl, mapProviderErrorImpl } from './engine-health.js';
-import { mergeStopMessageFromPersisted } from './stop-message-state-sync.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 { extractKeyAlias, extractKeyIndex, extractProviderId, getProviderModelId } from './engine/provider-key/parse.js';
+import { resolveSessionScope as resolveSessionScopeImpl, resolveStickyKey as resolveStickyKeyImpl } from './engine/routing-state/keys.js';
 export class VirtualRouterEngine {
     routing = {};
     providerRegistry = new ProviderRegistry();
@@ -122,8 +123,13 @@ export class VirtualRouterEngine {
         this.providerCooldowns.clear();
         this.restoreHealthFromStore();
         this.loadBalancer = new RouteLoadBalancer(config.loadBalancing);
-        this.antigravityAliasReuseCooldownMs = this.resolveAntigravityAliasReuseCooldownMs(config);
-        this.hydrateAntigravityAliasLeaseStoreIfNeeded(true);
+        this.antigravityAliasReuseCooldownMs = resolveAntigravityAliasReuseCooldownMs(config);
+        hydrateAntigravityAliasLeaseStoreIfNeeded({
+            force: true,
+            leaseStore: this.antigravityAliasLeaseStore,
+            persistence: this.antigravityLeasePersistence,
+            aliasReuseCooldownMs: this.antigravityAliasReuseCooldownMs
+        });
         this.classifier = new RoutingClassifier(config.classifier);
         this.contextRouting = config.contextRouting ?? { warnRatio: 0.9, hardLimit: false };
         this.contextAdvisor.configure(this.contextRouting);
@@ -136,13 +142,13 @@ export class VirtualRouterEngine {
     route(request, metadata) {
         const stickyKey = this.resolveStickyKey(metadata);
         const sessionScope = this.resolveSessionScope(metadata);
-        const stopMessageScope = this.resolveStopMessageScope(metadata);
+        const stopMessageScope = resolveStopMessageScope(metadata);
         // Routing instructions should be session/conversation-scoped when available (including /v1/responses),
         // while auto-sticky for Responses remains request-chain scoped via resolveStickyKey().
         const stateKey = sessionScope || stickyKey || 'default';
-        const baseState = this.getRoutingInstructionState(stateKey);
+        const baseState = getRoutingInstructionState(stateKey, this.routingInstructionState, this.routingStateStore);
         let routingState = baseState;
-        const metadataInstructions = this.buildMetadataInstructions(metadata);
+        const metadataInstructions = buildMetadataInstructions(metadata);
         if (metadataInstructions.length > 0) {
             routingState = applyRoutingInstructions(metadataInstructions, routingState);
         }
@@ -157,7 +163,7 @@ export class VirtualRouterEngine {
             };
         }
         if (stopMessageScope) {
-            const sessionState = this.getRoutingInstructionState(stopMessageScope);
+            const sessionState = getRoutingInstructionState(stopMessageScope, this.routingInstructionState, this.routingStateStore);
             if (typeof sessionState.stopMessageText === 'string' ||
                 typeof sessionState.stopMessageMaxRepeats === 'number') {
                 routingState = {
@@ -173,7 +179,7 @@ export class VirtualRouterEngine {
         const parsedInstructions = parseRoutingInstructions(request.messages);
         let instructions = parsedInstructions;
         if (stopMessageScope && parsedInstructions.length > 0) {
-            const sessionState = this.getRoutingInstructionState(stopMessageScope);
+            const sessionState = getRoutingInstructionState(stopMessageScope, this.routingInstructionState, this.routingStateStore);
             const hasStopMessageClear = parsedInstructions.some((entry) => entry.type === 'stopMessageClear');
             const stopMessageSets = parsedInstructions.filter((entry) => entry.type === 'stopMessageSet');
             if (!hasStopMessageClear && stopMessageSets.length > 0) {
@@ -213,7 +219,7 @@ export class VirtualRouterEngine {
         if (instructions.length > 0) {
             routingState = applyRoutingInstructions(instructions, routingState);
             this.routingInstructionState.set(stateKey, routingState);
-            this.persistRoutingInstructionState(stateKey, routingState);
+            persistRoutingInstructionState(stateKey, routingState, this.routingStateStore);
             // 对 stopMessage 指令补充一份基于 session/conversation 的持久化状态，
             // 便于 server-side 工具通过 session:*/conversation:* scope 读取到相同配置。
             // stopMessage is strictly session-scoped (sessionId only). Persist it under the session scope
@@ -222,7 +228,7 @@ export class VirtualRouterEngine {
                 const hasStopMessageSet = instructions.some((entry) => entry.type === 'stopMessageSet');
                 const hasStopMessageClear = instructions.some((entry) => entry.type === 'stopMessageClear');
                 if (hasStopMessageSet || hasStopMessageClear) {
-                    const sessionState = this.getRoutingInstructionState(stopMessageScope);
+                    const sessionState = getRoutingInstructionState(stopMessageScope, this.routingInstructionState, this.routingStateStore);
                     let nextSessionState = {
                         ...sessionState
                     };
@@ -267,7 +273,7 @@ export class VirtualRouterEngine {
                     }
                     if (shouldPersistSessionState) {
                         this.routingInstructionState.set(stopMessageScope, nextSessionState);
-                        this.persistRoutingInstructionState(stopMessageScope, nextSessionState);
+                        persistRoutingInstructionState(stopMessageScope, nextSessionState, this.routingStateStore);
                     }
                     else {
                         nextSessionState = sessionState;
@@ -285,7 +291,7 @@ export class VirtualRouterEngine {
             }
         }
         if (instructions.length === 0 && stopMessageScope) {
-            const sessionState = this.getRoutingInstructionState(stopMessageScope);
+            const sessionState = getRoutingInstructionState(stopMessageScope, this.routingInstructionState, this.routingStateStore);
             if (typeof sessionState.stopMessageText === 'string' ||
                 typeof sessionState.stopMessageMaxRepeats === 'number') {
                 routingState.stopMessageText = sessionState.stopMessageText;
@@ -308,14 +314,14 @@ export class VirtualRouterEngine {
                     for (const key of pool.targets) {
                         if (typeof key !== 'string' || !key)
                             continue;
-                        const providerId = this.extractProviderId(key);
+                        const providerId = extractProviderId(key);
                         if (providerId) {
                             providersInRouting.add(providerId);
                         }
                     }
                 }
             }
-            const allowed = Array.from(routingState.allowedProviders);
+            const allowed = Array.from(routingState.allowedProviders).filter((provider) => typeof provider === 'string');
             const hasIntersection = allowed.some((provider) => providersInRouting.has(provider));
             if (!hasIntersection) {
                 routingState = {
@@ -323,7 +329,7 @@ export class VirtualRouterEngine {
                     allowedProviders: new Set()
                 };
                 this.routingInstructionState.set(stateKey, routingState);
-                this.persistRoutingInstructionState(stateKey, routingState);
+                persistRoutingInstructionState(stateKey, routingState, this.routingStateStore);
             }
         }
         const features = buildRoutingFeatures(request, metadata);
@@ -492,7 +498,7 @@ export class VirtualRouterEngine {
                             preferTarget: undefined
                         };
                         this.routingInstructionState.set(stateKey, routingState);
-                        this.persistRoutingInstructionState(stateKey, routingState);
+                        persistRoutingInstructionState(stateKey, routingState, this.routingStateStore);
                     }
                 }
             }
@@ -517,9 +523,20 @@ export class VirtualRouterEngine {
             ...(this.webSearchForce ? { forceWebSearch: true } : {}),
             ...(forceVision ? { forceVision: true } : {})
         };
-        this.recordAntigravitySessionLease(features.metadata, selection.providerKey, { commitSessionBinding: false });
+        recordAntigravitySessionLease({
+            metadata: features.metadata,
+            providerKey: selection.providerKey,
+            sessionKey: this.resolveSessionScope(features.metadata),
+            providerRegistry: this.providerRegistry,
+            leaseStore: this.antigravityAliasLeaseStore,
+            sessionAliasStore: this.antigravitySessionAliasStore,
+            persistence: this.antigravityLeasePersistence,
+            aliasReuseCooldownMs: this.antigravityAliasReuseCooldownMs,
+            commitSessionBinding: false,
+            debug: this.debug
+        });
         this.incrementRouteStat(selection.routeUsed, selection.providerKey);
-        const routingMode = this.resolveRoutingMode([...metadataInstructions, ...instructions], routingState);
+        const routingMode = resolveRoutingMode([...metadataInstructions, ...instructions], routingState);
         try {
             this.statsCenter.recordVirtualRouterHit({
                 requestId: metadata.requestId,
@@ -569,9 +586,13 @@ export class VirtualRouterEngine {
     }
     getStopMessageState(metadata) {
         const sessionScope = this.resolveSessionScope(metadata);
-        const sessionState = sessionScope ? this.getRoutingInstructionState(sessionScope) : null;
+        const sessionState = sessionScope
+            ? getRoutingInstructionState(sessionScope, this.routingInstructionState, this.routingStateStore)
+            : null;
         const stickyKey = this.resolveStickyKey(metadata);
-        const stickyState = stickyKey ? this.getRoutingInstructionState(stickyKey) : null;
+        const stickyState = stickyKey
+            ? getRoutingInstructionState(stickyKey, this.routingInstructionState, this.routingStateStore)
+            : null;
         const effectiveState = sessionState && typeof sessionState.stopMessageText === 'string' && sessionState.stopMessageText.trim()
             ? sessionState
             : stickyState;
@@ -659,7 +680,18 @@ export class VirtualRouterEngine {
             return;
         }
         if (providerKey.toLowerCase().startsWith('antigravity.')) {
-            this.recordAntigravitySessionLease(metadata, providerKey, { commitSessionBinding: true });
+            recordAntigravitySessionLease({
+                metadata: metadata,
+                providerKey,
+                sessionKey: this.resolveSessionScope(metadata),
+                providerRegistry: this.providerRegistry,
+                leaseStore: this.antigravityAliasLeaseStore,
+                sessionAliasStore: this.antigravitySessionAliasStore,
+                persistence: this.antigravityLeasePersistence,
+                aliasReuseCooldownMs: this.antigravityAliasReuseCooldownMs,
+                commitSessionBinding: true,
+                debug: this.debug
+            });
         }
     }
     getStatus() {
@@ -720,7 +752,8 @@ export class VirtualRouterEngine {
         }
     }
     selectProvider(requestedRoute, metadata, classification, features, routingState) {
-        const activeState = routingState || this.getRoutingInstructionState(this.resolveStickyKey(metadata));
+        const activeState = routingState ||
+            getRoutingInstructionState(this.resolveStickyKey(metadata), this.routingInstructionState, this.routingStateStore);
         return selectProviderImpl(requestedRoute, metadata, classification, features, activeState, {
             routing: this.routing,
             providerRegistry: this.providerRegistry,
@@ -749,477 +782,10 @@ export class VirtualRouterEngine {
         return this.healthManager.getConfig();
     }
     resolveStickyKey(metadata) {
-        const providerProtocol = metadata.providerProtocol;
-        // 对 Responses 协议的自动粘滞，仅在“单次会话链路”内生效：
-        // - Resume/submit 调用：stickyKey = previousRequestId（指向首轮请求）；
-        // - 普通 /v1/responses 调用：stickyKey = 本次 requestId；
-        // 这样不会把 Responses 的自动粘滞扩散到整个 session，仅在需要 save/restore
-        // 的请求链路中复用 provider.key.model。
-        if (providerProtocol === 'openai-responses') {
-            const resume = metadata.responsesResume;
-            if (resume && typeof resume.previousRequestId === 'string' && resume.previousRequestId.trim()) {
-                return resume.previousRequestId.trim();
-            }
-            return metadata.requestId;
-        }
-        // 其它协议沿用会话级 sticky 语义：sessionId / conversationId → requestId。
-        const sessionScope = this.resolveSessionScope(metadata);
-        if (sessionScope) {
-            return sessionScope;
-        }
-        return metadata.requestId;
+        return resolveStickyKeyImpl(metadata);
     }
     resolveSessionScope(metadata) {
-        const sessionId = typeof metadata.sessionId === 'string' ? metadata.sessionId.trim() : '';
-        if (sessionId) {
-            return `session:${sessionId}`;
-        }
-        const conversationId = typeof metadata.conversationId === 'string' ? metadata.conversationId.trim() : '';
-        if (conversationId) {
-            return `conversation:${conversationId}`;
-        }
-        return undefined;
-    }
-    resolveAntigravityAliasReuseCooldownMs(config) {
-        const cfg = config.loadBalancing?.aliasSelection?.sessionLeaseCooldownMs;
-        if (typeof cfg === 'number' && Number.isFinite(cfg)) {
-            return Math.max(0, Math.floor(cfg));
-        }
-        return 5 * 60_000;
-    }
-    resolveAntigravityLeaseScope(providerKey) {
-        try {
-            const profile = this.providerRegistry.get(providerKey);
-            const modelId = typeof profile?.modelId === 'string' ? profile.modelId.trim().toLowerCase() : '';
-            if (modelId.startsWith('gemini-')) {
-                return 'gemini';
-            }
-            return null;
-        }
-        catch {
-            return null;
-        }
-    }
-    buildScopedSessionKey(sessionKey) {
-        return `${sessionKey}::gemini`;
-    }
-    buildAntigravityLeaseRuntimeKey(runtimeKey) {
-        return `${runtimeKey}::gemini`;
-    }
-    extractRuntimeKey(providerKey) {
-        const value = typeof providerKey === 'string' ? providerKey.trim() : '';
-        if (!value)
-            return null;
-        const firstDot = value.indexOf('.');
-        if (firstDot <= 0 || firstDot === value.length - 1)
-            return null;
-        const secondDot = value.indexOf('.', firstDot + 1);
-        if (secondDot <= firstDot + 1)
-            return null;
-        const providerId = value.slice(0, firstDot);
-        const alias = value.slice(firstDot + 1, secondDot);
-        if (!providerId || !alias)
-            return null;
-        return `${providerId}.${alias}`;
-    }
-    recordAntigravitySessionLease(metadata, providerKey, opts) {
-        // Per-request runtime override: allow callers (e.g. servertool followups) to disable
-        // Antigravity gemini session binding/lease without changing global config.
-        try {
-            const rt = metadata?.__rt;
-            if (rt && typeof rt === 'object' && !Array.isArray(rt)) {
-                const disable = rt.disableAntigravitySessionBinding;
-                const mode = rt.antigravitySessionBinding;
-                if (disable === true || mode === false) {
-                    return;
-                }
-                if (typeof mode === 'string' && ['0', 'false', 'off', 'disabled', 'none'].includes(mode.trim().toLowerCase())) {
-                    return;
-                }
-            }
-        }
-        catch {
-            // ignore metadata parse errors
-        }
-        const sessionKey = this.resolveSessionScope(metadata);
-        if (!sessionKey) {
-            return;
-        }
-        const runtimeKeyBase = this.extractRuntimeKey(providerKey);
-        if (!runtimeKeyBase || !runtimeKeyBase.startsWith('antigravity.')) {
-            return;
-        }
-        const commitSessionBinding = opts?.commitSessionBinding === true;
-        const scope = this.resolveAntigravityLeaseScope(providerKey);
-        // Policy: antigravity alias leasing/binding applies only to Gemini models.
-        if (scope !== 'gemini') {
-            return;
-        }
-        const scopedSessionKey = this.buildScopedSessionKey(sessionKey);
-        const runtimeKey = this.buildAntigravityLeaseRuntimeKey(runtimeKeyBase);
-        const now = Date.now();
-        const cooldownMs = this.antigravityAliasReuseCooldownMs;
-        const existing = this.antigravityAliasLeaseStore.get(runtimeKey);
-        // Do not steal a lease from another active session. This prevents a "forced fallback" route
-        // (e.g. default route bypass) from evicting the original session and causing churn.
-        if (existing && existing.sessionKey !== scopedSessionKey && cooldownMs > 0 && now - existing.lastSeenAt < cooldownMs) {
-            return;
-        }
-        this.antigravityAliasLeaseStore.set(runtimeKey, { sessionKey: scopedSessionKey, lastSeenAt: now });
-        if (commitSessionBinding) {
-            const previous = this.antigravitySessionAliasStore.get(scopedSessionKey);
-            this.antigravitySessionAliasStore.set(scopedSessionKey, runtimeKey);
-            try {
-                const raw = String(process.env.ROUTECODEX_STAGE_LOG || process.env.RCC_STAGE_LOG || '').trim().toLowerCase();
-                const enabled = raw !== '' && raw !== '0' && raw !== 'false' && raw !== 'no';
-                if (enabled && previous !== runtimeKey) {
-                    this.debug?.log?.('[virtual-router][antigravity-session-binding] commit', JSON.stringify({ sessionKey: scopedSessionKey, runtimeKey, prev: previous ?? null }));
-                }
-            }
-            catch {
-                // ignore logging errors
-            }
-        }
-        this.scheduleAntigravityAliasLeaseStoreFlush();
-        // Opportunistic cleanup: keep only active leases within cooldown window.
-        if (cooldownMs <= 0) {
-            return;
-        }
-        for (const [key, entry] of this.antigravityAliasLeaseStore.entries()) {
-            if (now - entry.lastSeenAt >= cooldownMs) {
-                this.antigravityAliasLeaseStore.delete(key);
-                // Clear session mapping if it still points at the expired runtimeKey.
-                if (this.antigravitySessionAliasStore.get(entry.sessionKey) === key) {
-                    this.antigravitySessionAliasStore.delete(entry.sessionKey);
-                }
-            }
-        }
-    }
-    resolveAntigravityAliasLeasePersistPath() {
-        try {
-            const enabledRaw = process.env.ROUTECODEX_ANTIGRAVITY_ALIAS_LEASE_PERSIST;
-            const enabled = typeof enabledRaw === 'string' &&
-                ['1', 'true', 'yes', 'on'].includes(enabledRaw.trim().toLowerCase());
-            if (!enabled) {
-                return null;
-            }
-            const home = os.homedir();
-            if (!home)
-                return null;
-            return path.join(home, '.routecodex', 'state', 'antigravity-alias-leases.json');
-        }
-        catch {
-            return null;
-        }
-    }
-    hydrateAntigravityAliasLeaseStoreIfNeeded(force = false) {
-        const filePath = this.resolveAntigravityAliasLeasePersistPath();
-        if (!filePath) {
-            return;
-        }
-        let stat = null;
-        try {
-            stat = fs.statSync(filePath);
-        }
-        catch {
-            this.antigravityLeasePersistence.loadedOnce = true;
-            this.antigravityLeasePersistence.loadedMtimeMs = null;
-            return;
-        }
-        const mtimeMs = typeof stat.mtimeMs === 'number' && Number.isFinite(stat.mtimeMs) ? stat.mtimeMs : stat.mtime.getTime();
-        if (!force && this.antigravityLeasePersistence.loadedOnce && this.antigravityLeasePersistence.loadedMtimeMs === mtimeMs) {
-            return;
-        }
-        let parsed;
-        try {
-            parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
-        }
-        catch {
-            this.antigravityLeasePersistence.loadedOnce = true;
-            this.antigravityLeasePersistence.loadedMtimeMs = mtimeMs;
-            return;
-        }
-        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-            this.antigravityLeasePersistence.loadedOnce = true;
-            this.antigravityLeasePersistence.loadedMtimeMs = mtimeMs;
-            return;
-        }
-        const leasesRaw = parsed.leases;
-        if (!leasesRaw || typeof leasesRaw !== 'object' || Array.isArray(leasesRaw)) {
-            this.antigravityLeasePersistence.loadedOnce = true;
-            this.antigravityLeasePersistence.loadedMtimeMs = mtimeMs;
-            return;
-        }
-        const now = Date.now();
-        const cooldownMs = this.antigravityAliasReuseCooldownMs;
-        const nextLeaseStore = new Map();
-        for (const [runtimeKeyRaw, entryRaw] of Object.entries(leasesRaw)) {
-            const runtimeKeyBase = typeof runtimeKeyRaw === 'string' ? runtimeKeyRaw.trim() : '';
-            if (!runtimeKeyBase || !runtimeKeyBase.startsWith('antigravity.'))
-                continue;
-            if (!entryRaw || typeof entryRaw !== 'object' || Array.isArray(entryRaw))
-                continue;
-            const rawSessionKey = typeof entryRaw.sessionKey === 'string' ? String(entryRaw.sessionKey).trim() : '';
-            const lastSeenAt = typeof entryRaw.lastSeenAt === 'number' && Number.isFinite(entryRaw.lastSeenAt)
-                ? Math.floor(entryRaw.lastSeenAt)
-                : 0;
-            if (!rawSessionKey || !lastSeenAt)
-                continue;
-            if (cooldownMs > 0 && now - lastSeenAt >= cooldownMs)
-                continue;
-            // Backwards compatible: legacy lease keys were unscoped ("antigravity.<alias>").
-            // Policy: only keep Gemini-scoped leases. Drop any non-gemini scoped entries.
-            const hasExplicitScope = runtimeKeyBase.includes('::');
-            if (hasExplicitScope && !runtimeKeyBase.endsWith('::gemini'))
-                continue;
-            const runtimeKey = hasExplicitScope ? runtimeKeyBase : this.buildAntigravityLeaseRuntimeKey(runtimeKeyBase);
-            if (rawSessionKey.includes('::') && !rawSessionKey.endsWith('::gemini'))
-                continue;
-            const sessionKey = rawSessionKey.includes('::') ? rawSessionKey : this.buildScopedSessionKey(rawSessionKey);
-            nextLeaseStore.set(runtimeKey, { sessionKey, lastSeenAt });
-        }
-        this.antigravityAliasLeaseStore.clear();
-        for (const [key, val] of nextLeaseStore.entries()) {
-            this.antigravityAliasLeaseStore.set(key, val);
-        }
-        this.antigravityLeasePersistence.loadedOnce = true;
-        this.antigravityLeasePersistence.loadedMtimeMs = mtimeMs;
-    }
-    scheduleAntigravityAliasLeaseStoreFlush() {
-        if (this.antigravityLeasePersistence.flushTimer) {
-            return;
-        }
-        this.antigravityLeasePersistence.flushTimer = setTimeout(() => {
-            this.antigravityLeasePersistence.flushTimer = null;
-            this.flushAntigravityAliasLeaseStoreSync();
-        }, 250);
-        this.antigravityLeasePersistence.flushTimer.unref?.();
-    }
-    flushAntigravityAliasLeaseStoreSync() {
-        const filePath = this.resolveAntigravityAliasLeasePersistPath();
-        if (!filePath) {
-            return;
-        }
-        try {
-            fs.mkdirSync(path.dirname(filePath), { recursive: true });
-        }
-        catch {
-            // ignore
-        }
-        const now = Date.now();
-        const cooldownMs = this.antigravityAliasReuseCooldownMs;
-        const leases = {};
-        for (const [runtimeKey, entry] of this.antigravityAliasLeaseStore.entries()) {
-            if (!runtimeKey || !entry)
-                continue;
-            if (cooldownMs > 0 && now - entry.lastSeenAt >= cooldownMs)
-                continue;
-            if (!entry.sessionKey || !entry.lastSeenAt)
-                continue;
-            leases[runtimeKey] = { sessionKey: entry.sessionKey, lastSeenAt: entry.lastSeenAt };
-        }
-        try {
-            const tmpPath = `${filePath}.tmp.${process.pid}.${now}`;
-            fs.writeFileSync(tmpPath, JSON.stringify({ version: 1, updatedAt: now, leases }, null, 2), 'utf8');
-            fs.renameSync(tmpPath, filePath);
-            try {
-                const stat = fs.statSync(filePath);
-                const mtimeMs = typeof stat.mtimeMs === 'number' && Number.isFinite(stat.mtimeMs) ? stat.mtimeMs : stat.mtime.getTime();
-                this.antigravityLeasePersistence.loadedOnce = true;
-                this.antigravityLeasePersistence.loadedMtimeMs = mtimeMs;
-            }
-            catch {
-                // ignore
-            }
-        }
-        catch {
-            // best-effort persistence: must not affect routing
-        }
-    }
-    resolveStopMessageScope(metadata) {
-        const sessionId = typeof metadata.sessionId === 'string' ? metadata.sessionId.trim() : '';
-        if (sessionId) {
-            return `session:${sessionId}`;
-        }
-        return undefined;
-    }
-    getRoutingInstructionState(stickyKey) {
-        const key = stickyKey || 'default';
-        const existing = this.routingInstructionState.get(key);
-        // 对 session:/conversation: 作用域，在每次读取时尝试从磁盘刷新 stopMessage 相关字段，
-        // 确保 servertool（如 stop_message_auto）通过 sticky-session-store 更新的使用次数
-        // 能在 VirtualRouter 日志中实时反映出来。
-        if (existing && (key.startsWith('session:') || key.startsWith('conversation:'))) {
-            try {
-                const persisted = this.routingStateStore.loadSync(key);
-                const merged = mergeStopMessageFromPersisted(existing, persisted);
-                existing.stopMessageSource = merged.stopMessageSource;
-                existing.stopMessageText = merged.stopMessageText;
-                existing.stopMessageMaxRepeats = merged.stopMessageMaxRepeats;
-                existing.stopMessageUsed = merged.stopMessageUsed;
-                existing.stopMessageUpdatedAt = merged.stopMessageUpdatedAt;
-                existing.stopMessageLastUsedAt = merged.stopMessageLastUsedAt;
-            }
-            catch {
-                // 刷新失败不影响原有内存状态
-            }
-            return existing;
-        }
-        let initial = null;
-        // 仅对 session:/conversation: 作用域的 key 尝试从磁盘恢复持久化状态
-        if (key.startsWith('session:') || key.startsWith('conversation:')) {
-            initial = this.routingStateStore.loadSync(key);
-        }
-        if (!initial) {
-            initial = {
-                forcedTarget: undefined,
-                stickyTarget: undefined,
-                allowedProviders: new Set(),
-                disabledProviders: new Set(),
-                disabledKeys: new Map(),
-                disabledModels: new Map(),
-                stopMessageSource: undefined,
-                stopMessageText: undefined,
-                stopMessageMaxRepeats: undefined,
-                stopMessageUsed: undefined,
-                stopMessageUpdatedAt: undefined,
-                stopMessageLastUsedAt: undefined
-            };
-        }
-        this.routingInstructionState.set(key, initial);
-        return initial;
-    }
-    buildMetadataInstructions(metadata) {
-        const instructions = [];
-        const forcedProviderKeyRaw = metadata
-            .__shadowCompareForcedProviderKey;
-        const forcedProviderKey = this.parseMetadataForceProviderKey(forcedProviderKeyRaw);
-        if (forcedProviderKey) {
-            instructions.push({ type: 'force', ...forcedProviderKey });
-        }
-        if (Array.isArray(metadata.disabledProviderKeyAliases)) {
-            for (const entry of metadata.disabledProviderKeyAliases) {
-                const parsed = this.parseMetadataDisableDescriptor(entry);
-                if (parsed) {
-                    instructions.push({ type: 'disable', ...parsed });
-                }
-            }
-        }
-        return instructions;
-    }
-    parseMetadataDisableDescriptor(entry) {
-        if (typeof entry !== 'string') {
-            return null;
-        }
-        const trimmed = entry.trim();
-        if (!trimmed) {
-            return null;
-        }
-        const parts = trimmed.split('.');
-        if (parts.length < 2) {
-            return null;
-        }
-        const provider = parts[0];
-        const alias = parts[1];
-        if (!provider || !alias) {
-            return null;
-        }
-        if (/^\d+$/.test(alias)) {
-            return { provider, keyIndex: Number.parseInt(alias, 10) };
-        }
-        return { provider, keyAlias: alias };
-    }
-    parseMetadataForceProviderKey(entry) {
-        if (typeof entry !== 'string') {
-            return null;
-        }
-        const trimmed = entry.trim();
-        if (!trimmed) {
-            return null;
-        }
-        // Accept the bracket notation used in virtual-router-hit logs: provider[alias].model
-        // - provider[].model means provider.model across all aliases
-        const bracketMatch = trimmed.match(/^([a-zA-Z0-9_-]+)\[([a-zA-Z0-9_-]*)\](?:\.(.+))?$/);
-        if (bracketMatch) {
-            const provider = bracketMatch[1]?.trim() || '';
-            const keyAlias = bracketMatch[2]?.trim() || '';
-            const model = typeof bracketMatch[3] === 'string' ? bracketMatch[3].trim() : '';
-            if (!provider) {
-                return null;
-            }
-            if (keyAlias) {
-                return {
-                    provider,
-                    keyAlias,
-                    ...(model ? { model } : {}),
-                    pathLength: 3
-                };
-            }
-            if (model) {
-                return {
-                    provider,
-                    model,
-                    pathLength: 2
-                };
-            }
-            return { provider, pathLength: 1 };
-        }
-        // Accept provider.keyAlias.model and provider.model (model may contain dots when keyAlias is explicit).
-        const parts = trimmed.split('.').map((part) => part.trim()).filter(Boolean);
-        if (parts.length === 0) {
-            return null;
-        }
-        const provider = parts[0] || '';
-        if (!provider) {
-            return null;
-        }
-        if (parts.length === 1) {
-            return { provider, pathLength: 1 };
-        }
-        if (parts.length === 2) {
-            const second = parts[1] || '';
-            if (!second) {
-                return null;
-            }
-            if (/^\d+$/.test(second)) {
-                const keyIndex = Number.parseInt(second, 10);
-                return Number.isFinite(keyIndex) && keyIndex > 0 ? { provider, keyIndex, pathLength: 2 } : null;
-            }
-            return { provider, model: second, pathLength: 2 };
-        }
-        const keyAlias = parts[1] || '';
-        const model = parts.slice(2).join('.').trim();
-        if (!keyAlias) {
-            return null;
-        }
-        return {
-            provider,
-            keyAlias,
-            ...(model ? { model } : {}),
-            pathLength: 3
-        };
-    }
-    resolveRoutingMode(instructions, state) {
-        const hasForce = instructions.some((inst) => inst.type === 'force');
-        const hasAllow = instructions.some((inst) => inst.type === 'allow');
-        const hasClear = instructions.some((inst) => inst.type === 'clear');
-        const hasPrefer = instructions.some((inst) => inst.type === 'prefer');
-        if (hasClear) {
-            return 'none';
-        }
-        if (hasAllow || state.allowedProviders.size > 0) {
-            return 'sticky';
-        }
-        if (hasForce || state.forcedTarget) {
-            return 'force';
-        }
-        if (hasPrefer || state.preferTarget) {
-            return 'sticky';
-        }
-        if (state.stickyTarget) {
-            return 'sticky';
-        }
-        return 'none';
+        return resolveSessionScopeImpl(metadata);
     }
     resolveInstructionTarget(target) {
         if (!target || !target.provider) {
@@ -1247,7 +813,7 @@ export class VirtualRouterEngine {
         if (target.model && target.model.trim()) {
             const normalizedModel = target.model.trim();
             const matchingKeys = providerKeys.filter((key) => {
-                const modelId = this.getProviderModelId(key);
+                const modelId = getProviderModelId(key, this.providerRegistry);
                 return modelId === normalizedModel;
             });
             if (matchingKeys.length > 0) {
@@ -1282,7 +848,7 @@ export class VirtualRouterEngine {
                     continue;
                 }
                 for (const providerKey of pool.targets) {
-                    const providerId = this.extractProviderId(providerKey);
+                    const providerId = extractProviderId(providerKey);
                     // console.log('[filter] checking', providerKey, 'id=', providerId);
                     if (!providerId)
                         continue;
@@ -1295,8 +861,8 @@ export class VirtualRouterEngine {
                     }
                     const disabledKeys = state.disabledKeys.get(providerId);
                     if (disabledKeys && disabledKeys.size > 0) {
-                        const keyAlias = this.extractKeyAlias(providerKey);
-                        const keyIndex = this.extractKeyIndex(providerKey);
+                        const keyAlias = extractKeyAlias(providerKey);
+                        const keyIndex = extractKeyIndex(providerKey);
                         if (keyAlias && disabledKeys.has(keyAlias)) {
                             continue;
                         }
@@ -1306,7 +872,7 @@ export class VirtualRouterEngine {
                     }
                     const disabledModels = state.disabledModels.get(providerId);
                     if (disabledModels && disabledModels.size > 0) {
-                        const modelId = this.getProviderModelId(providerKey);
+                        const modelId = getProviderModelId(providerKey, this.providerRegistry);
                         if (modelId && disabledModels.has(modelId)) {
                             continue;
                         }
@@ -1331,12 +897,6 @@ export class VirtualRouterEngine {
             aliasQueueStore: this.aliasQueueStore
         }, { routingState: state });
     }
-    extractProviderId(providerKey) {
-        const firstDot = providerKey.indexOf('.');
-        if (firstDot <= 0)
-            return null;
-        return providerKey.substring(0, firstDot);
-    }
     /**
      * 在已有候选路由集合上，筛选出真正挂载了 sticky 池内 providerKey 的路由，
      * 并按 ROUTE_PRIORITY 进行排序；同时显式排除 tools 路由，保证一旦进入
@@ -1410,27 +970,27 @@ export class VirtualRouterEngine {
         // 应用 provider 白名单 / 黑名单
         if (allowedProviders.size > 0) {
             candidates = candidates.filter((key) => {
-                const providerId = this.extractProviderId(key);
+                const providerId = extractProviderId(key);
                 return providerId && allowedProviders.has(providerId);
             });
         }
         if (disabledProviders.size > 0) {
             candidates = candidates.filter((key) => {
-                const providerId = this.extractProviderId(key);
+                const providerId = extractProviderId(key);
                 return providerId && !disabledProviders.has(providerId);
             });
         }
         // 应用 key / model 级别黑名单
         if (disabledKeysMap.size > 0 || disabledModels.size > 0) {
             candidates = candidates.filter((key) => {
-                const providerId = this.extractProviderId(key);
+                const providerId = extractProviderId(key);
                 if (!providerId) {
                     return true;
                 }
                 const disabledKeys = disabledKeysMap.get(providerId);
                 if (disabledKeys && disabledKeys.size > 0) {
-                    const keyAlias = this.extractKeyAlias(key);
-                    const keyIndex = this.extractKeyIndex(key);
+                    const keyAlias = extractKeyAlias(key);
+                    const keyIndex = extractKeyIndex(key);
                     if (keyAlias && disabledKeys.has(keyAlias)) {
                         return false;
                     }
@@ -1440,7 +1000,7 @@ export class VirtualRouterEngine {
                 }
                 const disabledModelSet = disabledModels.get(providerId);
                 if (disabledModelSet && disabledModelSet.size > 0) {
-                    const modelId = this.getProviderModelId(key);
+                    const modelId = getProviderModelId(key, this.providerRegistry);
                     if (modelId && disabledModelSet.has(modelId)) {
                         return false;
                     }
@@ -1458,43 +1018,6 @@ export class VirtualRouterEngine {
         // delegate to selection module
         return null;
     }
-    extractKeyAlias(providerKey) {
-        const parts = providerKey.split('.');
-        if (parts.length === 3) {
-            return this.normalizeAliasDescriptor(parts[1]);
-        }
-        return null;
-    }
-    normalizeAliasDescriptor(alias) {
-        if (/^\d+-/.test(alias)) {
-            return alias.replace(/^\d+-/, '');
-        }
-        return alias;
-    }
-    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;
-    }
-    getProviderModelId(providerKey) {
-        const profile = this.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;
-    }
     // mapProviderError/applySeriesCooldown moved to engine-health.ts
     extractExcludedProviderKeySet(metadata) {
         if (!metadata) {
@@ -1531,10 +1054,27 @@ export class VirtualRouterEngine {
                 }
             }
         }
+        if (features.hasImageAttachment) {
+            const allRouteNames = Object.keys(this.routing);
+            for (const routeName of allRouteNames) {
+                if (!this.routeHasTargets(this.routing[routeName])) {
+                    continue;
+                }
+                if (!this.routeSupportsModel(routeName, 'kimi-k2.5')) {
+                    continue;
+                }
+                if (!baseList.includes(routeName)) {
+                    baseList.push(routeName);
+                }
+            }
+        }
         let ordered = this.sortByPriority(baseList);
         if (features.hasImageAttachment && !forceVision) {
             ordered = this.reorderForInlineVision(ordered);
         }
+        if (features.hasImageAttachment) {
+            ordered = this.reorderForPreferredModel(ordered, 'kimi-k2.5');
+        }
         const deduped = [];
         for (const routeName of ordered) {
             if (routeName && !deduped.includes(routeName)) {
@@ -1574,6 +1114,46 @@ export class VirtualRouterEngine {
         }
         return [...inlinePreferred, ...remaining];
     }
+    reorderForPreferredModel(routeNames, modelId) {
+        const unique = Array.from(new Set(routeNames.filter(Boolean)));
+        if (!unique.length) {
+            return unique;
+        }
+        const preferred = unique.filter((routeName) => this.routeSupportsModel(routeName, modelId));
+        if (!preferred.length) {
+            return unique;
+        }
+        const remaining = unique.filter((routeName) => !preferred.includes(routeName));
+        return [...preferred, ...remaining];
+    }
+    routeSupportsModel(routeName, modelId) {
+        const normalizedModel = modelId.trim().toLowerCase();
+        if (!normalizedModel) {
+            return false;
+        }
+        const pools = this.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 = this.providerRegistry.get(providerKey);
+                    const candidate = typeof profile.modelId === 'string' ? profile.modelId.trim().toLowerCase() : '';
+                    if (candidate === normalizedModel) {
+                        return true;
+                    }
+                }
+                catch {
+                    // ignore unknown provider keys during capability probing
+                }
+            }
+        }
+        return false;
+    }
     routeSupportsInlineVision(routeName) {
         const pools = this.routing[routeName];
         if (!Array.isArray(pools)) {
@@ -1657,59 +1237,6 @@ export class VirtualRouterEngine {
         }
         return flattened;
     }
-    isRoutingStateEmpty(state) {
-        if (!state) {
-            return true;
-        }
-        const noForced = !state.forcedTarget;
-        const noSticky = !state.stickyTarget;
-        const noPrefer = !state.preferTarget;
-        const noAllowed = state.allowedProviders.size === 0;
-        const noDisabledProviders = state.disabledProviders.size === 0;
-        const noDisabledKeys = state.disabledKeys.size === 0;
-        const noDisabledModels = state.disabledModels.size === 0;
-        const noStopMessage = (!state.stopMessageText || !state.stopMessageText.trim()) &&
-            (typeof state.stopMessageMaxRepeats !== 'number' || !Number.isFinite(state.stopMessageMaxRepeats)) &&
-            (typeof state.stopMessageUsed !== 'number' || !Number.isFinite(state.stopMessageUsed)) &&
-            (typeof state.stopMessageUpdatedAt !== 'number' || !Number.isFinite(state.stopMessageUpdatedAt)) &&
-            (typeof state.stopMessageLastUsedAt !== 'number' || !Number.isFinite(state.stopMessageLastUsedAt));
-        return (noForced &&
-            noSticky &&
-            noPrefer &&
-            noAllowed &&
-            noDisabledProviders &&
-            noDisabledKeys &&
-            noDisabledModels &&
-            noStopMessage);
-    }
-    persistRoutingInstructionState(key, state) {
-        if (!key || (!key.startsWith('session:') && !key.startsWith('conversation:'))) {
-            return;
-        }
-        const supportsSync = typeof this.routingStateStore.saveSync === 'function';
-        const prefersSync = supportsSync &&
-            key.startsWith('session:') &&
-            (Boolean(state.stopMessageText && state.stopMessageText.trim()) ||
-                (typeof state.stopMessageMaxRepeats === 'number' && Number.isFinite(state.stopMessageMaxRepeats)) ||
-                (typeof state.stopMessageUsed === 'number' && Number.isFinite(state.stopMessageUsed)) ||
-                (typeof state.stopMessageUpdatedAt === 'number' && Number.isFinite(state.stopMessageUpdatedAt)) ||
-                (typeof state.stopMessageLastUsedAt === 'number' && Number.isFinite(state.stopMessageLastUsedAt)));
-        if (this.isRoutingStateEmpty(state)) {
-            if (prefersSync) {
-                this.routingStateStore.saveSync(key, null);
-            }
-            else {
-                this.routingStateStore.saveAsync(key, null);
-            }
-            return;
-        }
-        if (prefersSync) {
-            this.routingStateStore.saveSync(key, state);
-        }
-        else {
-            this.routingStateStore.saveAsync(key, state);
-        }
-    }
     markProviderCooldown(providerKey, cooldownMs) {
         if (!providerKey) {
             return;