@jsonstudio/llms 0.6.2172 → 0.6.3214

package/dist/router/virtual-router/engine-legacy/route-utils.d.ts

@@ -0,0 +1,19 @@
+import type { RoutePoolTier } from '../types.js';
+import type { VirtualRouterEngine } from '../engine-legacy.js';
+export declare function normalizeRouteAlias(routeName: string | undefined): string;
+export declare function buildRouteCandidates(engine: VirtualRouterEngine, requestedRoute: string, classificationCandidates: string[] | undefined, features: {
+    hasImageAttachment?: boolean;
+    hasVideoAttachment?: boolean;
+    hasLocalVideoAttachment?: boolean;
+}): string[];
+export declare function reorderForInlineVision(engine: VirtualRouterEngine, routeNames: string[]): string[];
+export declare function reorderForPreferredModel(engine: VirtualRouterEngine, routeNames: string[], modelId: string): string[];
+export declare function routeSupportsModel(engine: VirtualRouterEngine, routeName: string, modelId: string): boolean;
+export declare function routeSupportsInlineVision(engine: VirtualRouterEngine, routeName: string): boolean;
+export declare function sortByPriority(routeNames: string[]): string[];
+export declare function routeWeight(routeName: string): number;
+export declare function routeHasForceFlag(engine: VirtualRouterEngine, routeName: string): boolean;
+export declare function routeHasTargets(engine: VirtualRouterEngine, pools?: RoutePoolTier[]): boolean;
+export declare function hasPrimaryPool(engine: VirtualRouterEngine, pools?: RoutePoolTier[]): boolean;
+export declare function sortRoutePools(_engine: VirtualRouterEngine, pools?: RoutePoolTier[]): RoutePoolTier[];
+export declare function flattenPoolTargets(_engine: VirtualRouterEngine, pools?: RoutePoolTier[]): string[];

package/dist/router/virtual-router/engine-legacy/route-utils.js

@@ -0,0 +1,212 @@
+import { DEFAULT_ROUTE, ROUTE_PRIORITY } from '../types.js';
+export function normalizeRouteAlias(routeName) {
+    const base = routeName && routeName.trim() ? routeName.trim() : DEFAULT_ROUTE;
+    return base;
+}
+export function buildRouteCandidates(engine, requestedRoute, classificationCandidates, features) {
+    const forceVision = routeHasForceFlag(engine, 'vision');
+    const hasMultimodalTargets = routeHasTargets(engine, engine.routing.multimodal);
+    const hasVisionTargets = routeHasTargets(engine, engine.routing.vision);
+    const hasLocalVideoAttachment = features.hasVideoAttachment === true && features.hasLocalVideoAttachment === true;
+    if (features.hasImageAttachment && hasLocalVideoAttachment && hasVisionTargets) {
+        return ['vision'];
+    }
+    const normalized = normalizeRouteAlias(requestedRoute || DEFAULT_ROUTE);
+    const baseList = [];
+    if (classificationCandidates && classificationCandidates.length) {
+        for (const candidate of classificationCandidates) {
+            baseList.push(normalizeRouteAlias(candidate));
+        }
+    }
+    else if (normalized) {
+        baseList.push(normalized);
+    }
+    if (features.hasImageAttachment) {
+        if (hasMultimodalTargets) {
+            if (!baseList.includes('multimodal')) {
+                baseList.unshift('multimodal');
+            }
+        }
+        if (hasVisionTargets && (!hasMultimodalTargets || forceVision)) {
+            if (!baseList.includes('vision')) {
+                baseList.push('vision');
+            }
+        }
+        if (!forceVision && hasMultimodalTargets) {
+            const visionAwareRoutes = [DEFAULT_ROUTE, 'thinking'];
+            for (const routeName of visionAwareRoutes) {
+                if (routeHasTargets(engine, engine.routing[routeName]) && !baseList.includes(routeName)) {
+                    baseList.push(routeName);
+                }
+            }
+        }
+    }
+    let ordered = sortByPriority(baseList);
+    if (features.hasImageAttachment && !forceVision && hasMultimodalTargets) {
+        ordered = reorderForInlineVision(engine, ordered);
+    }
+    if (features.hasImageAttachment && hasMultimodalTargets) {
+        ordered = reorderForPreferredModel(engine, ordered, 'kimi-k2.5');
+    }
+    const deduped = [];
+    for (const routeName of ordered) {
+        if (routeName && !deduped.includes(routeName)) {
+            deduped.push(routeName);
+        }
+    }
+    if (!deduped.includes(DEFAULT_ROUTE)) {
+        deduped.push(DEFAULT_ROUTE);
+    }
+    const filtered = deduped.filter((routeName) => routeHasTargets(engine, engine.routing[routeName]));
+    if (!filtered.includes(DEFAULT_ROUTE) && routeHasTargets(engine, engine.routing[DEFAULT_ROUTE])) {
+        filtered.push(DEFAULT_ROUTE);
+    }
+    return filtered.length ? filtered : [DEFAULT_ROUTE];
+}
+export function reorderForInlineVision(engine, routeNames) {
+    const unique = Array.from(new Set(routeNames.filter(Boolean)));
+    if (!unique.length) {
+        return unique;
+    }
+    // 仅当 default/thinking 中存在 Responses/Gemini 提供方时，才将其提前作为「一次完成」优先级。
+    const inlinePreferred = [];
+    const inlineRoutes = [DEFAULT_ROUTE, 'thinking'];
+    for (const routeName of inlineRoutes) {
+        if (routeSupportsInlineVision(engine, routeName) && !inlinePreferred.includes(routeName)) {
+            inlinePreferred.push(routeName);
+        }
+    }
+    if (!inlinePreferred.length) {
+        return unique;
+    }
+    const remaining = [];
+    for (const routeName of unique) {
+        if (!inlinePreferred.includes(routeName)) {
+            remaining.push(routeName);
+        }
+    }
+    return [...inlinePreferred, ...remaining];
+}
+export function reorderForPreferredModel(engine, routeNames, modelId) {
+    const unique = Array.from(new Set(routeNames.filter(Boolean)));
+    if (!unique.length) {
+        return unique;
+    }
+    const preferred = unique.filter((routeName) => routeSupportsModel(engine, routeName, modelId));
+    if (!preferred.length) {
+        return unique;
+    }
+    const remaining = unique.filter((routeName) => !preferred.includes(routeName));
+    return [...preferred, ...remaining];
+}
+export function routeSupportsModel(engine, routeName, modelId) {
+    const normalizedModel = modelId.trim().toLowerCase();
+    if (!normalizedModel) {
+        return false;
+    }
+    const pools = engine.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 = engine.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;
+}
+export function routeSupportsInlineVision(engine, routeName) {
+    const pools = engine.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 = engine.providerRegistry.get(providerKey);
+                if (profile.providerType === 'responses' || profile.providerType === 'gemini') {
+                    return true;
+                }
+            }
+            catch {
+                // ignore unknown provider keys during capability probing
+            }
+        }
+    }
+    return false;
+}
+export function sortByPriority(routeNames) {
+    return [...routeNames].sort((a, b) => routeWeight(a) - routeWeight(b));
+}
+export function routeWeight(routeName) {
+    const idx = ROUTE_PRIORITY.indexOf(routeName);
+    return idx >= 0 ? idx : ROUTE_PRIORITY.length;
+}
+export function routeHasForceFlag(engine, routeName) {
+    const pools = engine.routing[routeName];
+    if (!Array.isArray(pools)) {
+        return false;
+    }
+    return pools.some((pool) => pool.force);
+}
+export function routeHasTargets(engine, pools) {
+    if (!Array.isArray(pools)) {
+        return false;
+    }
+    return pools.some((pool) => Array.isArray(pool.targets) && pool.targets.length > 0);
+}
+export function hasPrimaryPool(engine, pools) {
+    if (!Array.isArray(pools)) {
+        return false;
+    }
+    return pools.some((pool) => !pool.backup && Array.isArray(pool.targets) && pool.targets.length > 0);
+}
+export function sortRoutePools(_engine, pools) {
+    if (!Array.isArray(pools)) {
+        return [];
+    }
+    return pools
+        .filter((pool) => Array.isArray(pool.targets) && pool.targets.length > 0)
+        .sort((a, b) => {
+        if (a.backup && !b.backup)
+            return 1;
+        if (!a.backup && b.backup)
+            return -1;
+        if (a.priority !== b.priority) {
+            return b.priority - a.priority;
+        }
+        return a.id.localeCompare(b.id);
+    });
+}
+export function flattenPoolTargets(_engine, pools) {
+    const flattened = [];
+    if (!Array.isArray(pools)) {
+        return flattened;
+    }
+    for (const pool of pools) {
+        if (!Array.isArray(pool.targets)) {
+            continue;
+        }
+        for (const target of pool.targets) {
+            if (typeof target === 'string' && target && !flattened.includes(target)) {
+                flattened.push(target);
+            }
+        }
+    }
+    return flattened;
+}

package/dist/router/virtual-router/engine-legacy/routing.d.ts

@@ -0,0 +1,8 @@
+import type { ProcessedRequest, StandardizedRequest } from '../../../conversion/hub/types/standardized.js';
+import type { RouterMetadataInput, RoutingDecision, RoutingDiagnostics, TargetMetadata } from '../types.js';
+import type { VirtualRouterEngine } from '../engine-legacy.js';
+export declare function routeRequest(engine: VirtualRouterEngine, request: StandardizedRequest | ProcessedRequest, metadata: RouterMetadataInput): {
+    target: TargetMetadata;
+    decision: RoutingDecision;
+    diagnostics: RoutingDiagnostics;
+};

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

@@ -0,0 +1,8 @@
+import { buildRoutingState } from './route-state.js';
+import { selectRoutingTarget } from './route-selection.js';
+import { finalizeRoutingDecision } from './route-finalize.js';
+export function routeRequest(engine, request, metadata) {
+    const routingStateResult = buildRoutingState(engine, request, metadata);
+    const selectionResult = selectRoutingTarget(engine, request, metadata, routingStateResult.routingState, routingStateResult.stateKey);
+    return finalizeRoutingDecision(engine, metadata, selectionResult.routingState, routingStateResult.metadataInstructions, routingStateResult.instructions, selectionResult);
+}

package/dist/router/virtual-router/engine-legacy/selection-core.d.ts

@@ -0,0 +1,28 @@
+import type { ClassificationResult, RouterMetadataInput, RoutingFeatures } from '../types.js';
+import type { RoutingInstructionState } from '../routing-instructions.js';
+import type { VirtualRouterEngine } from '../engine-legacy.js';
+export declare function selectProvider(engine: VirtualRouterEngine, requestedRoute: string, metadata: RouterMetadataInput, classification: ClassificationResult, features: RoutingFeatures, routingState?: RoutingInstructionState): {
+    providerKey: string;
+    routeUsed: string;
+    pool: string[];
+    poolId?: string;
+};
+export declare function selectFromCandidates(engine: VirtualRouterEngine, routes: string[], metadata: RouterMetadataInput, classification: ClassificationResult, features: RoutingFeatures, state: RoutingInstructionState, requiredProviderKeys?: Set<string>, allowAliasRotation?: boolean): {
+    providerKey: string;
+    routeUsed: string;
+    pool: string[];
+    poolId?: string;
+};
+/**
+ * 在 sticky 模式下，仅在 sticky 池内选择 Provider：
+ * - stickyKeySet 表示已经解析并通过健康检查的 providerKey 集合；
+ * - 不再依赖 routing[*].targets 中是否挂载这些 key，避免「未初始化路由池」导致 sticky 池为空；
+ * - 仍然尊重 allowed/disabledProviders、disabledKeys、disabledModels 以及上下文长度。
+ */
+export declare function selectFromStickyPool(engine: VirtualRouterEngine, stickyKeySet: Set<string>, metadata: RouterMetadataInput, features: RoutingFeatures, state: RoutingInstructionState, allowAliasRotation?: boolean): {
+    providerKey: string;
+    routeUsed: string;
+    pool: string[];
+    poolId?: string;
+} | null;
+export declare function extractExcludedProviderKeySet(engine: VirtualRouterEngine, metadata: RouterMetadataInput | undefined): Set<string>;

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

@@ -0,0 +1,112 @@
+import { DEFAULT_ROUTE } from '../types.js';
+import { getRoutingInstructionState } from '../engine/routing-state/store.js';
+import { selectProviderImpl } from '../engine/routing-pools/index.js';
+import { extractKeyAlias, extractKeyIndex, extractProviderId, getProviderModelId } from '../engine/provider-key/parse.js';
+export function selectProvider(engine, requestedRoute, metadata, classification, features, routingState) {
+    const activeState = routingState ||
+        getRoutingInstructionState(engine.resolveStickyKey(metadata), engine.routingInstructionState, engine.routingStateStore);
+    return selectProviderImpl(requestedRoute, metadata, classification, features, activeState, {
+        routing: engine.routing,
+        providerRegistry: engine.providerRegistry,
+        healthManager: engine.healthManager,
+        contextAdvisor: engine.contextAdvisor,
+        loadBalancer: engine.loadBalancer,
+        isProviderCoolingDown: (key) => engine.isProviderCoolingDown(key),
+        getProviderCooldownRemainingMs: (key) => engine.getProviderCooldownRemainingMs(key),
+        resolveStickyKey: (m) => engine.resolveStickyKey(m),
+        quotaView: engine.quotaView,
+        aliasQueueStore: engine.stickySessionManager.getAllStores().aliasQueueStore,
+        antigravityAliasLeaseStore: engine.stickySessionManager.getAllStores().aliasLeaseStore,
+        antigravitySessionAliasStore: engine.stickySessionManager.getAllStores().sessionAliasStore,
+        antigravityAliasReuseCooldownMs: engine.stickySessionManager.getAliasReuseCooldownMs()
+    }, { routingState });
+}
+export function selectFromCandidates(engine, routes, metadata, classification, features, state, requiredProviderKeys, allowAliasRotation) {
+    // legacy helper kept for backward compatibility; selection logic moved to engine-selection.ts
+    return selectProviderImpl(engine.normalizeRouteAlias(classification.routeName || DEFAULT_ROUTE), metadata, classification, features, state, {
+        routing: engine.routing,
+        providerRegistry: engine.providerRegistry,
+        healthManager: engine.healthManager,
+        contextAdvisor: engine.contextAdvisor,
+        loadBalancer: engine.loadBalancer,
+        isProviderCoolingDown: (key) => engine.isProviderCoolingDown(key),
+        getProviderCooldownRemainingMs: (key) => engine.getProviderCooldownRemainingMs(key),
+        resolveStickyKey: (m) => engine.resolveStickyKey(m),
+        quotaView: engine.quotaView,
+        aliasQueueStore: engine.stickySessionManager.getAllStores().aliasQueueStore
+    }, { routingState: state });
+}
+/**
+ * 在 sticky 模式下，仅在 sticky 池内选择 Provider：
+ * - stickyKeySet 表示已经解析并通过健康检查的 providerKey 集合；
+ * - 不再依赖 routing[*].targets 中是否挂载这些 key，避免「未初始化路由池」导致 sticky 池为空；
+ * - 仍然尊重 allowed/disabledProviders、disabledKeys、disabledModels 以及上下文长度。
+ */
+export function selectFromStickyPool(engine, stickyKeySet, metadata, features, state, allowAliasRotation) {
+    if (!stickyKeySet || stickyKeySet.size === 0) {
+        return null;
+    }
+    const allowedProviders = new Set(state.allowedProviders);
+    const disabledProviders = new Set(state.disabledProviders);
+    const disabledKeysMap = new Map(Array.from(state.disabledKeys.entries()).map(([provider, keys]) => [
+        provider,
+        new Set(Array.from(keys).map((k) => (typeof k === 'string' ? k : k + 1)))
+    ]));
+    const disabledModels = new Map(Array.from(state.disabledModels.entries()).map(([provider, models]) => [provider, new Set(models)]));
+    // 初始候选集合：sticky 池中的所有 key
+    // In quota routing mode, cooldown is controlled by quotaView only.
+    let candidates = Array.from(stickyKeySet).filter((key) => (engine.quotaView ? true : !engine.isProviderCoolingDown(key)));
+    // 应用 provider 白名单 / 黑名单
+    if (allowedProviders.size > 0) {
+        candidates = candidates.filter((key) => {
+            const providerId = extractProviderId(key);
+            return providerId && allowedProviders.has(providerId);
+        });
+    }
+    if (disabledProviders.size > 0) {
+        candidates = candidates.filter((key) => {
+            const providerId = extractProviderId(key);
+            return providerId && !disabledProviders.has(providerId);
+        });
+    }
+    // 应用 key / model 级别黑名单
+    if (disabledKeysMap.size > 0 || disabledModels.size > 0) {
+        candidates = candidates.filter((key) => {
+            const providerId = extractProviderId(key);
+            if (!providerId) {
+                return true;
+            }
+            const disabledKeys = disabledKeysMap.get(providerId);
+            if (disabledKeys && disabledKeys.size > 0) {
+                const keyAlias = extractKeyAlias(key);
+                const keyIndex = extractKeyIndex(key);
+                if (keyAlias && disabledKeys.has(keyAlias)) {
+                    return false;
+                }
+                if (keyIndex !== undefined && disabledKeys.has(keyIndex + 1)) {
+                    return false;
+                }
+            }
+            const disabledModelSet = disabledModels.get(providerId);
+            if (disabledModelSet && disabledModelSet.size > 0) {
+                const modelId = getProviderModelId(key, engine.providerRegistry);
+                if (modelId && disabledModelSet.has(modelId)) {
+                    return false;
+                }
+            }
+            return true;
+        });
+    }
+    if (!candidates.length) {
+        return null;
+    }
+    const stickyKey = allowAliasRotation ? undefined : engine.resolveStickyKey(metadata);
+    const estimatedTokens = typeof features.estimatedTokens === 'number' && Number.isFinite(features.estimatedTokens)
+        ? Math.max(0, features.estimatedTokens)
+        : 0;
+    // delegate to selection module
+    return null;
+}
+export function extractExcludedProviderKeySet(engine, metadata) {
+    return engine.routeAnalytics.extractExcludedProviderKeySet(metadata);
+}

package/dist/router/virtual-router/engine-legacy/selection-state.d.ts

@@ -0,0 +1,16 @@
+import type { RoutingInstructionState } from '../routing-instructions.js';
+import type { VirtualRouterEngine } from '../engine-legacy.js';
+export declare function resolveSelectionPenalty(engine: VirtualRouterEngine, providerKey: string): number | undefined;
+export declare function resolveInstructionProcessModeForSelection(engine: VirtualRouterEngine, providerKey: string, routingState: RoutingInstructionState): 'chat' | 'passthrough' | undefined;
+export declare function resolveInstructionTarget(engine: VirtualRouterEngine, target: NonNullable<RoutingInstructionState['forcedTarget']>): {
+    mode: 'exact' | 'filter';
+    keys: string[];
+} | null;
+export declare function filterCandidatesByRoutingState(engine: VirtualRouterEngine, routes: string[], state: RoutingInstructionState): string[];
+/**
+ * 在已有候选路由集合上，筛选出真正挂载了 sticky 池内 providerKey 的路由，
+ * 并按 ROUTE_PRIORITY 进行排序；同时显式排除 tools 路由，保证一旦进入
+ * sticky 模式，就不会再命中独立的 tools 池（例如 glm/qwen 工具模型）。
+ * 若候选集合中完全没有挂载 sticky key 的路由，则尝试在 default 路由上兜底。
+ */
+export declare function buildStickyRouteCandidatesFromFiltered(engine: VirtualRouterEngine, filteredCandidates: string[], stickyKeySet: Set<string>): string[];

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

@@ -0,0 +1,187 @@
+import { DEFAULT_ROUTE } from '../types.js';
+import { extractKeyAlias, extractKeyIndex, extractProviderId, getProviderModelId } from '../engine/provider-key/parse.js';
+import { routeHasTargets, sortByPriority, flattenPoolTargets } from './route-utils.js';
+export function resolveSelectionPenalty(engine, providerKey) {
+    if (!engine.quotaView) {
+        return undefined;
+    }
+    try {
+        const entry = engine.quotaView(providerKey);
+        const raw = entry?.selectionPenalty;
+        if (typeof raw !== 'number' || !Number.isFinite(raw) || raw <= 0) {
+            return undefined;
+        }
+        return Math.floor(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function resolveInstructionProcessModeForSelection(engine, providerKey, routingState) {
+    const candidates = [
+        routingState.forcedTarget,
+        routingState.stickyTarget,
+        routingState.preferTarget
+    ];
+    for (const candidate of candidates) {
+        const processMode = candidate?.processMode;
+        if (!processMode) {
+            continue;
+        }
+        const resolved = resolveInstructionTarget(engine, candidate);
+        if (!resolved) {
+            continue;
+        }
+        if (resolved.keys.includes(providerKey)) {
+            return processMode;
+        }
+    }
+    return undefined;
+}
+export function resolveInstructionTarget(engine, target) {
+    if (!target || !target.provider) {
+        return null;
+    }
+    const providerId = target.provider;
+    const providerKeys = engine.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 runtimeKey = engine.providerRegistry.resolveRuntimeKeyByAlias(providerId, alias);
+        if (runtimeKey) {
+            return { mode: 'exact', keys: [runtimeKey] };
+        }
+    }
+    if (typeof target.keyIndex === 'number' && target.keyIndex > 0) {
+        const runtimeKey = engine.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, engine.providerRegistry);
+            return modelId === normalizedModel;
+        });
+        if (matchingKeys.length > 0) {
+            return { mode: 'filter', keys: matchingKeys };
+        }
+    }
+    if (alias && !aliasExplicit) {
+        const legacyKey = engine.providerRegistry.resolveRuntimeKeyByAlias(providerId, alias);
+        if (legacyKey) {
+            return { mode: 'exact', keys: [legacyKey] };
+        }
+    }
+    return { mode: 'filter', keys: providerKeys };
+}
+export function filterCandidatesByRoutingState(engine, routes, state) {
+    // console.log('[filter] routes:', routes, 'state:', {
+    //   allowed: Array.from(state.allowedProviders),
+    //   disabled: Array.from(state.disabledProviders)
+    // });
+    if (state.allowedProviders.size === 0 &&
+        state.disabledProviders.size === 0 &&
+        state.disabledKeys.size === 0 &&
+        state.disabledModels.size === 0) {
+        return routes;
+    }
+    return routes.filter((routeName) => {
+        const pools = engine.routing[routeName];
+        if (!pools)
+            return false;
+        for (const pool of pools) {
+            if (!Array.isArray(pool.targets) || pool.targets.length === 0) {
+                continue;
+            }
+            for (const providerKey of pool.targets) {
+                const providerId = extractProviderId(providerKey);
+                // console.log('[filter] checking', providerKey, 'id=', providerId);
+                if (!providerId)
+                    continue;
+                if (state.allowedProviders.size > 0 && !state.allowedProviders.has(providerId)) {
+                    // console.log('[filter] dropped by allowed list');
+                    continue;
+                }
+                if (state.disabledProviders.has(providerId)) {
+                    continue;
+                }
+                const disabledKeys = state.disabledKeys.get(providerId);
+                if (disabledKeys && disabledKeys.size > 0) {
+                    const keyAlias = extractKeyAlias(providerKey);
+                    const keyIndex = extractKeyIndex(providerKey);
+                    if (keyAlias && disabledKeys.has(keyAlias)) {
+                        continue;
+                    }
+                    if (keyIndex !== undefined && disabledKeys.has(keyIndex + 1)) {
+                        continue;
+                    }
+                }
+                const disabledModels = state.disabledModels.get(providerId);
+                if (disabledModels && disabledModels.size > 0) {
+                    const modelId = getProviderModelId(providerKey, engine.providerRegistry);
+                    if (modelId && disabledModels.has(modelId)) {
+                        continue;
+                    }
+                }
+                return true;
+            }
+        }
+        return false;
+    });
+}
+/**
+ * 在已有候选路由集合上，筛选出真正挂载了 sticky 池内 providerKey 的路由，
+ * 并按 ROUTE_PRIORITY 进行排序；同时显式排除 tools 路由，保证一旦进入
+ * sticky 模式，就不会再命中独立的 tools 池（例如 glm/qwen 工具模型）。
+ * 若候选集合中完全没有挂载 sticky key 的路由，则尝试在 default 路由上兜底。
+ */
+export function buildStickyRouteCandidatesFromFiltered(engine, filteredCandidates, stickyKeySet) {
+    const routesWithSticky = [];
+    const candidateSet = new Set(filteredCandidates.filter((name) => name && name !== 'tools'));
+    for (const routeName of candidateSet) {
+        const pools = engine.routing[routeName];
+        if (!routeHasTargets(engine, pools)) {
+            continue;
+        }
+        const targets = flattenPoolTargets(engine, pools);
+        if (!targets.some((key) => stickyKeySet.has(key))) {
+            continue;
+        }
+        routesWithSticky.push(routeName);
+    }
+    // 若当前候选路由中没有任何挂载 sticky key 的路由，尝试直接在 default 路由上兜底；
+    // 若 default 也不包含 sticky key，则视为 sticky 配置失效，由调用方回落到非 sticky 逻辑。
+    if (routesWithSticky.length === 0) {
+        const defaultPools = engine.routing[DEFAULT_ROUTE];
+        if (routeHasTargets(engine, defaultPools)) {
+            const targets = flattenPoolTargets(engine, defaultPools);
+            if (targets.some((key) => stickyKeySet.has(key))) {
+                return [DEFAULT_ROUTE];
+            }
+        }
+        return [];
+    }
+    const ordered = sortByPriority(routesWithSticky);
+    const result = [];
+    let hasDefault = false;
+    for (const routeName of ordered) {
+        if (routeName === DEFAULT_ROUTE) {
+            hasDefault = true;
+            continue;
+        }
+        if (!result.includes(routeName)) {
+            result.push(routeName);
+        }
+    }
+    // default 路由若包含 sticky key，则始终放在候选列表最后，用于 sticky 模式兜底。
+    if (hasDefault && !result.includes(DEFAULT_ROUTE)) {
+        result.push(DEFAULT_ROUTE);
+    }
+    return result;
+}
+// Intentionally no extra exports here; keep this module focused on state filtering.

package/dist/router/virtual-router/engine-legacy/state-accessors.d.ts

@@ -0,0 +1,21 @@
+import type { PreCommandStateSnapshot, RouterMetadataInput, StopMessageStateSnapshot } from '../types.js';
+import type { VirtualRouterEngine } from '../engine-legacy.js';
+export declare function getStopMessageState(engine: VirtualRouterEngine, metadata: RouterMetadataInput): StopMessageStateSnapshot | null;
+export declare function getPreCommandState(engine: VirtualRouterEngine, metadata: RouterMetadataInput): PreCommandStateSnapshot | null;
+export declare function getStatus(engine: VirtualRouterEngine): {
+    routes: Record<string, {
+        providers: string[];
+        hits: number;
+        lastUsedProvider?: string;
+        lastHit?: {
+            timestampMs: number;
+            reason?: string;
+            requestTokens?: number;
+            selectionPenalty?: number;
+            stopMessageActive: boolean;
+            stopMessageMode?: "on" | "off" | "auto";
+            stopMessageRemaining?: number;
+        };
+    }>;
+    health: import("../types.js").ProviderHealthState[];
+};