@jsonstudio/rcc 0.89.168 → 0.89.524

package/node_modules/@jsonstudio/llms/dist/router/virtual-router/engine.js

@@ -3,16 +3,23 @@ import { ProviderRegistry } from './provider-registry.js';
 import { RouteLoadBalancer } from './load-balancer.js';
 import { RoutingClassifier } from './classifier.js';
 import { buildRoutingFeatures } from './features.js';
-import { DEFAULT_ROUTE, ROUTE_PRIORITY, VirtualRouterError, VirtualRouterErrorCode } from './types.js';
+import { ContextAdvisor } from './context-advisor.js';
+import { DEFAULT_MODEL_CONTEXT_TOKENS, DEFAULT_ROUTE, ROUTE_PRIORITY, VirtualRouterError, VirtualRouterErrorCode } from './types.js';
+import { getStatsCenter } from '../../telemetry/stats-center.js';
 export class VirtualRouterEngine {
     routing = {};
     providerRegistry = new ProviderRegistry();
     healthManager = new ProviderHealthManager();
     loadBalancer = new RouteLoadBalancer();
     classifier = new RoutingClassifier({});
+    contextAdvisor = new ContextAdvisor();
+    contextRouting;
     routeStats = new Map();
     debug = console; // thin hook; host may monkey-patch for colored logging
     healthConfig = null;
+    statsCenter = getStatsCenter();
+    // Derived flags from VirtualRouterConfig/routing used by process / response layers.
+    webSearchForce = false;
     initialize(config) {
         this.validateConfig(config);
         this.routing = config.routing;
@@ -22,6 +29,9 @@ export class VirtualRouterEngine {
         this.healthManager.registerProviders(Object.keys(config.providers));
         this.loadBalancer = new RouteLoadBalancer(config.loadBalancing);
         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();
         for (const routeName of Object.keys(this.routing)) {
             this.routeStats.set(routeName, { hits: 0 });
@@ -29,21 +39,56 @@ export class VirtualRouterEngine {
     }
     route(request, metadata) {
         const features = buildRoutingFeatures(request, metadata);
-        const classification = this.classifier.classify(features);
-        const routeName = classification.routeName || DEFAULT_ROUTE;
-        const selection = this.selectProvider(routeName, metadata, classification);
-        const target = this.providerRegistry.buildTarget(selection.providerKey);
+        const classification = metadata.routeHint && metadata.routeHint.trim()
+            ? {
+                routeName: metadata.routeHint.trim(),
+                confidence: 1,
+                reasoning: `route_hint:${metadata.routeHint.trim()}`,
+                fallback: false,
+                candidates: [metadata.routeHint.trim()]
+            }
+            : this.classifier.classify(features);
+        const requestedRoute = this.normalizeRouteAlias(classification.routeName || DEFAULT_ROUTE);
+        const selection = this.selectProvider(requestedRoute, metadata, classification, features);
+        const baseTarget = this.providerRegistry.buildTarget(selection.providerKey);
+        const forceVision = this.routeHasForceFlag('vision');
+        const target = {
+            ...baseTarget,
+            ...(this.webSearchForce ? { forceWebSearch: true } : {}),
+            ...(forceVision ? { forceVision: true } : {})
+        };
         this.healthManager.recordSuccess(selection.providerKey);
         this.incrementRouteStat(selection.routeUsed, selection.providerKey);
-        const hitReason = this.buildHitReason(selection.routeUsed, classification, features);
-        this.debug?.log?.('[virtual-router-hit]', selection.routeUsed, selection.providerKey, target.modelId || '', hitReason ? `reason=${hitReason}` : '');
-        const didFallback = selection.routeUsed !== routeName || classification.fallback;
+        try {
+            this.statsCenter.recordVirtualRouterHit({
+                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
+            });
+        }
+        catch {
+            // stats must never break routing
+        }
+        const hitReason = this.buildHitReason(selection.routeUsed, selection.providerKey, classification, features);
+        const formatted = this.formatVirtualRouterHit(selection.routeUsed, selection.poolId, selection.providerKey, target.modelId || '', hitReason);
+        if (formatted) {
+            this.debug?.log?.(formatted);
+        }
+        else {
+            this.debug?.log?.('[virtual-router-hit]', selection.routeUsed, selection.providerKey, target.modelId || '', hitReason ? `reason=${hitReason}` : '');
+        }
+        const didFallback = selection.routeUsed !== requestedRoute;
         return {
             target,
             decision: {
                 routeName: selection.routeUsed,
                 providerKey: selection.providerKey,
                 pool: selection.pool,
+                poolId: selection.poolId,
                 confidence: classification.confidence,
                 reasoning: classification.reasoning,
                 fallback: didFallback
@@ -52,6 +97,7 @@ export class VirtualRouterEngine {
                 routeName: selection.routeUsed,
                 providerKey: selection.providerKey,
                 pool: selection.pool,
+                poolId: selection.poolId,
                 reasoning: classification.reasoning,
                 fallback: didFallback,
                 confidence: classification.confidence
@@ -81,10 +127,10 @@ export class VirtualRouterEngine {
     }
     getStatus() {
         const routes = {};
-        for (const [route, pool] of Object.entries(this.routing)) {
+        for (const [route, pools] of Object.entries(this.routing)) {
             const stats = this.routeStats.get(route) ?? { hits: 0 };
             routes[route] = {
-                providers: [...pool],
+                providers: this.flattenPoolTargets(pools),
                 hits: stats.hits,
                 lastUsedProvider: stats.lastProvider
             };
@@ -94,6 +140,14 @@ export class VirtualRouterEngine {
             health: this.healthManager.getSnapshot()
         };
     }
+    /**
+     * 将分类器产生的逻辑路由名直接归一化为配置中的路由键。
+     * 不再维护 "websearch" 之类的别名，调用方应显式使用 "web_search" 或 "search" 等实际路由名。
+     */
+    normalizeRouteAlias(routeName) {
+        const base = routeName && routeName.trim() ? routeName.trim() : DEFAULT_ROUTE;
+        return base;
+    }
     validateConfig(config) {
         if (!config.routing || typeof config.routing !== 'object') {
             throw new VirtualRouterError('routing configuration is required', VirtualRouterErrorCode.CONFIG_ERROR);
@@ -101,47 +155,133 @@ export class VirtualRouterEngine {
         if (!config.providers || Object.keys(config.providers).length === 0) {
             throw new VirtualRouterError('providers configuration is required', VirtualRouterErrorCode.CONFIG_ERROR);
         }
-        const defaultPool = config.routing[DEFAULT_ROUTE];
-        if (!Array.isArray(defaultPool) || defaultPool.length === 0) {
+        const defaultPools = config.routing[DEFAULT_ROUTE];
+        if (!this.routeHasTargets(defaultPools)) {
             throw new VirtualRouterError('default route must be configured with at least one provider', VirtualRouterErrorCode.CONFIG_ERROR);
         }
+        if (!this.hasPrimaryPool(defaultPools)) {
+            throw new VirtualRouterError('default route must define at least one non-backup pool', VirtualRouterErrorCode.CONFIG_ERROR);
+        }
         const providerKeys = new Set(Object.keys(config.providers));
-        for (const [routeName, pool] of Object.entries(config.routing)) {
-            if (!Array.isArray(pool) || !pool.length) {
+        for (const [routeName, pools] of Object.entries(config.routing)) {
+            if (!this.routeHasTargets(pools)) {
                 if (routeName === DEFAULT_ROUTE) {
                     throw new VirtualRouterError('default route cannot be empty', VirtualRouterErrorCode.CONFIG_ERROR);
                 }
                 continue;
             }
-            for (const providerKey of pool) {
-                if (!providerKeys.has(providerKey)) {
-                    throw new VirtualRouterError(`Route ${routeName} references unknown provider ${providerKey}`, VirtualRouterErrorCode.CONFIG_ERROR);
+            for (const pool of pools) {
+                if (!Array.isArray(pool.targets) || !pool.targets.length) {
+                    continue;
+                }
+                for (const providerKey of pool.targets) {
+                    if (!providerKeys.has(providerKey)) {
+                        throw new VirtualRouterError(`Route ${routeName} references unknown provider ${providerKey}`, VirtualRouterErrorCode.CONFIG_ERROR);
+                    }
                 }
             }
         }
     }
-    selectProvider(requestedRoute, metadata, classification) {
-        const candidates = this.buildRouteCandidates(requestedRoute, classification.candidates);
+    selectProvider(requestedRoute, metadata, classification, features) {
+        const candidates = this.buildRouteCandidates(requestedRoute, classification.candidates, features);
         const stickyKey = this.resolveStickyKey(metadata);
         const attempted = [];
-        for (const routeName of candidates) {
-            const pool = this.routing[routeName];
-            if (!Array.isArray(pool) || pool.length === 0) {
-                attempted.push(routeName);
+        const visitedRoutes = new Set();
+        const routeQueue = this.initializeRouteQueue(candidates);
+        const estimatedTokens = typeof features.estimatedTokens === 'number' && Number.isFinite(features.estimatedTokens)
+            ? Math.max(0, features.estimatedTokens)
+            : 0;
+        while (routeQueue.length) {
+            const routeName = routeQueue.shift();
+            if (visitedRoutes.has(routeName)) {
                 continue;
             }
+            const routePools = this.routing[routeName];
+            if (!this.routeHasTargets(routePools)) {
+                visitedRoutes.add(routeName);
+                attempted.push(`${routeName}:empty`);
+                continue;
+            }
+            visitedRoutes.add(routeName);
+            const orderedPools = this.sortRoutePools(routePools);
+            for (const poolTier of orderedPools) {
+                const { providerKey, poolTargets, tierId, failureHint } = this.trySelectFromTier(routeName, poolTier, stickyKey, estimatedTokens, features);
+                if (providerKey) {
+                    return { providerKey, routeUsed: routeName, pool: poolTargets, poolId: tierId };
+                }
+                if (failureHint) {
+                    attempted.push(failureHint);
+                }
+            }
+        }
+        throw new VirtualRouterError(`All providers unavailable for route ${requestedRoute}`, VirtualRouterErrorCode.PROVIDER_NOT_AVAILABLE, { routeName: requestedRoute, attempted });
+    }
+    trySelectFromTier(routeName, tier, stickyKey, estimatedTokens, features) {
+        let targets = Array.isArray(tier.targets) ? tier.targets : [];
+        const serverToolRequired = features.metadata?.serverToolRequired === true;
+        if (serverToolRequired) {
+            const filtered = [];
+            for (const key of targets) {
+                try {
+                    const profile = this.providerRegistry.get(key);
+                    if (!profile.serverToolsDisabled) {
+                        filtered.push(key);
+                    }
+                }
+                catch {
+                    // ignore unknown providers when filtering for servertools
+                }
+            }
+            targets = filtered;
+        }
+        // 当当前请求包含图片且路由为 default/thinking 时，优先在该路由池内选择
+        // Responses/Gemini 类型的 Provider，以便一次完成多模态推理；如果不存在则回退到原始列表。
+        if (features.hasImageAttachment && (routeName === DEFAULT_ROUTE || routeName === 'thinking')) {
+            const prioritized = [];
+            const fallthrough = [];
+            for (const key of targets) {
+                try {
+                    const profile = this.providerRegistry.get(key);
+                    if (profile.providerType === 'responses') {
+                        prioritized.push(key);
+                    }
+                    else if (profile.providerType === 'gemini') {
+                        prioritized.push(key);
+                    }
+                    else {
+                        fallthrough.push(key);
+                    }
+                }
+                catch {
+                    fallthrough.push(key);
+                }
+            }
+            if (prioritized.length) {
+                targets = prioritized;
+            }
+        }
+        if (!targets.length) {
+            return { providerKey: null, poolTargets: [], tierId: tier.id, failureHint: `${routeName}:${tier.id}:empty` };
+        }
+        const contextResult = this.contextAdvisor.classify(targets, estimatedTokens, (key) => this.providerRegistry.get(key));
+        const prioritizedPools = this.buildContextCandidatePools(contextResult);
+        for (const candidatePool of prioritizedPools) {
             const providerKey = this.loadBalancer.select({
-                routeName,
-                candidates: pool,
+                routeName: `${routeName}:${tier.id}`,
+                candidates: candidatePool,
                 stickyKey,
                 availabilityCheck: (key) => this.healthManager.isAvailable(key)
             });
             if (providerKey) {
-                return { providerKey, routeUsed: routeName, pool };
+                return { providerKey, poolTargets: tier.targets, tierId: tier.id };
             }
-            attempted.push(routeName);
         }
-        throw new VirtualRouterError(`All providers unavailable for route ${requestedRoute}`, VirtualRouterErrorCode.PROVIDER_NOT_AVAILABLE, { routeName: requestedRoute, attempted });
+        return {
+            providerKey: null,
+            poolTargets: tier.targets,
+            tierId: tier.id,
+            failureHint: this.describeAttempt(routeName, tier.id, contextResult)
+        };
     }
     incrementRouteStat(routeName, providerKey) {
         if (!this.routeStats.has(routeName)) {
@@ -155,6 +295,35 @@ export class VirtualRouterEngine {
     providerHealthConfig() {
         return this.healthManager.getConfig();
     }
+    initializeRouteQueue(candidates) {
+        return Array.from(new Set(candidates));
+    }
+    buildContextCandidatePools(result) {
+        const ordered = [];
+        if (result.safe.length) {
+            ordered.push(result.safe);
+            // 如果存在安全候选，直接放弃当前处于警戒阈值的模型
+            return ordered;
+        }
+        if (result.risky.length) {
+            ordered.push(result.risky);
+        }
+        // ratio >= 1 视为上下文溢出，直接标记为不可用
+        return ordered;
+    }
+    describeAttempt(routeName, poolId, result) {
+        const prefix = poolId ? `${routeName}:${poolId}` : routeName;
+        if (result.safe.length > 0) {
+            return `${prefix}:health`;
+        }
+        if (result.risky.length > 0) {
+            return `${prefix}:context_risky`;
+        }
+        if (result.overflow.length > 0) {
+            return `${prefix}:max_context_window`;
+        }
+        return prefix;
+    }
     resolveStickyKey(metadata) {
         const resume = metadata.responsesResume;
         if (resume && typeof resume.previousRequestId === 'string' && resume.previousRequestId.trim()) {
@@ -244,12 +413,32 @@ export class VirtualRouterEngine {
             return 'client_error';
         return 'unknown';
     }
-    buildRouteCandidates(requestedRoute, classificationCandidates) {
-        const normalized = requestedRoute || DEFAULT_ROUTE;
-        const baseList = classificationCandidates && classificationCandidates.length
-            ? classificationCandidates
-            : [normalized];
-        const ordered = this.sortByPriority(baseList);
+    buildRouteCandidates(requestedRoute, classificationCandidates, features) {
+        const forceVision = this.routeHasForceFlag('vision');
+        const normalized = this.normalizeRouteAlias(requestedRoute || DEFAULT_ROUTE);
+        const baseList = [];
+        if (classificationCandidates && classificationCandidates.length) {
+            for (const candidate of classificationCandidates) {
+                baseList.push(this.normalizeRouteAlias(candidate));
+            }
+        }
+        else if (normalized) {
+            baseList.push(normalized);
+        }
+        // 当检测到当前请求包含图片时，确保 default/thinking 也参与候选集，
+        // 以便优先尝试内建多模态模型（Responses/Gemini），再回落到 vision 路由池。
+        if (features.hasImageAttachment && !forceVision) {
+            const visionAwareRoutes = [DEFAULT_ROUTE, 'thinking'];
+            for (const routeName of visionAwareRoutes) {
+                if (this.routeHasTargets(this.routing[routeName]) && !baseList.includes(routeName)) {
+                    baseList.push(routeName);
+                }
+            }
+        }
+        let ordered = this.sortByPriority(baseList);
+        if (features.hasImageAttachment && !forceVision) {
+            ordered = this.reorderForInlineVision(ordered);
+        }
         const deduped = [];
         for (const routeName of ordered) {
             if (routeName && !deduped.includes(routeName)) {
@@ -259,17 +448,59 @@ export class VirtualRouterEngine {
         if (!deduped.includes(DEFAULT_ROUTE)) {
             deduped.push(DEFAULT_ROUTE);
         }
-        const filtered = deduped.filter((routeName) => {
-            const pool = this.routing[routeName];
-            return Array.isArray(pool) && pool.length > 0;
-        });
-        if (!filtered.includes(DEFAULT_ROUTE) &&
-            Array.isArray(this.routing[DEFAULT_ROUTE]) &&
-            this.routing[DEFAULT_ROUTE].length > 0) {
+        const filtered = deduped.filter((routeName) => this.routeHasTargets(this.routing[routeName]));
+        if (!filtered.includes(DEFAULT_ROUTE) && this.routeHasTargets(this.routing[DEFAULT_ROUTE])) {
             filtered.push(DEFAULT_ROUTE);
         }
         return filtered.length ? filtered : [DEFAULT_ROUTE];
     }
+    reorderForInlineVision(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 (this.routeSupportsInlineVision(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];
+    }
+    routeSupportsInlineVision(routeName) {
+        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);
+                    if (profile.providerType === 'responses' || profile.providerType === 'gemini') {
+                        return true;
+                    }
+                }
+                catch {
+                    // ignore unknown provider keys during capability probing
+                }
+            }
+        }
+        return false;
+    }
     sortByPriority(routeNames) {
         return [...routeNames].sort((a, b) => this.routeWeight(a) - this.routeWeight(b));
     }
@@ -277,25 +508,190 @@ export class VirtualRouterEngine {
         const idx = ROUTE_PRIORITY.indexOf(routeName);
         return idx >= 0 ? idx : ROUTE_PRIORITY.length;
     }
-    buildHitReason(routeUsed, classification, features) {
+    routeHasForceFlag(routeName) {
+        const pools = this.routing[routeName];
+        if (!Array.isArray(pools)) {
+            return false;
+        }
+        return pools.some((pool) => pool.force);
+    }
+    routeHasTargets(pools) {
+        if (!Array.isArray(pools)) {
+            return false;
+        }
+        return pools.some((pool) => Array.isArray(pool.targets) && pool.targets.length > 0);
+    }
+    hasPrimaryPool(pools) {
+        if (!Array.isArray(pools)) {
+            return false;
+        }
+        return pools.some((pool) => !pool.backup && Array.isArray(pool.targets) && pool.targets.length > 0);
+    }
+    sortRoutePools(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);
+        });
+    }
+    flattenPoolTargets(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;
+    }
+    buildHitReason(routeUsed, providerKey, classification, features) {
         const reasoning = classification.reasoning || '';
         const primary = reasoning.split('|')[0] || '';
-        const lastToolName = features.lastAssistantToolName;
-        if (routeUsed === 'tools') {
-            if (lastToolName) {
-                return primary ? `${primary}(${lastToolName})` : `tools(${lastToolName})`;
+        const commandDetail = features.lastAssistantToolLabel;
+        const base = (() => {
+            if (routeUsed === 'tools') {
+                return this.decorateWithDetail(primary || 'tools', primary, commandDetail);
+            }
+            if (routeUsed === 'thinking') {
+                return this.decorateWithDetail(primary || 'thinking', primary, commandDetail);
+            }
+            if (routeUsed === 'coding') {
+                return this.decorateWithDetail(primary || 'coding', primary, commandDetail);
+            }
+            if (routeUsed === 'web_search' || routeUsed === 'search') {
+                return this.decorateWithDetail(primary || routeUsed, primary, commandDetail);
             }
-            return primary || 'tools';
+            if (routeUsed === DEFAULT_ROUTE && classification.fallback) {
+                return primary || 'fallback:default';
+            }
+            if (primary) {
+                return primary;
+            }
+            return routeUsed ? `route:${routeUsed}` : 'route:unknown';
+        })();
+        const contextDetail = this.describeContextUsage(providerKey, features.estimatedTokens);
+        if (contextDetail) {
+            return `${base}|context:${contextDetail}`;
+        }
+        return base;
+    }
+    decorateWithDetail(baseLabel, primaryReason, detail) {
+        const normalizedDetail = detail && detail.trim();
+        if (!normalizedDetail) {
+            return primaryReason || baseLabel;
         }
-        if (routeUsed === 'thinking') {
-            return primary || 'thinking';
+        if (primaryReason) {
+            return `${primaryReason}(${normalizedDetail})`;
         }
-        if (routeUsed === DEFAULT_ROUTE && classification.fallback) {
-            return primary || 'fallback:default';
+        return `${baseLabel}(${normalizedDetail})`;
+    }
+    formatVirtualRouterHit(routeName, poolId, providerKey, modelId, hitReason) {
+        try {
+            // 生成本地时间戳
+            const now = new Date();
+            const hours = String(now.getHours()).padStart(2, '0');
+            const minutes = String(now.getMinutes()).padStart(2, '0');
+            const seconds = String(now.getSeconds()).padStart(2, '0');
+            const timestamp = `${hours}:${minutes}:${seconds}`;
+            const prefixColor = '\x1b[38;5;208m';
+            const reset = '\x1b[0m';
+            const timeColor = '\x1b[90m'; // 灰色
+            const routeColor = this.resolveRouteColor(routeName);
+            const prefix = `${prefixColor}[virtual-router-hit]${reset}`;
+            const timeLabel = `${timeColor}${timestamp}${reset}`;
+            const { providerLabel, resolvedModel } = this.describeTargetProvider(providerKey, modelId);
+            const routeLabel = poolId ? `${routeName}/${poolId}` : routeName;
+            const targetLabel = `${routeLabel} -> ${providerLabel}${resolvedModel ? '.' + resolvedModel : ''}`;
+            const reasonLabel = hitReason ? ` reason=${hitReason}` : '';
+            return `${prefix} ${timeLabel} ${routeColor}${targetLabel}${reasonLabel}${reset}`;
         }
-        if (primary) {
-            return primary;
+        catch {
+            const now = new Date();
+            const timestamp = now.toLocaleTimeString('zh-CN', { hour12: false });
+            const routeLabel = poolId ? `${routeName}/${poolId}` : routeName;
+            return `[virtual-router-hit] ${timestamp} ${routeLabel} -> ${providerKey}${modelId ? '.' + modelId : ''}${hitReason ? ` reason=${hitReason}` : ''}`;
         }
-        return routeUsed ? `route:${routeUsed}` : 'route:unknown';
+    }
+    resolveRouteColor(routeName) {
+        const reset = '\x1b[0m';
+        const map = {
+            tools: '\x1b[38;5;214m',
+            thinking: '\x1b[34m',
+            coding: '\x1b[35m',
+            longcontext: '\x1b[38;5;141m',
+            web_search: '\x1b[32m',
+            search: '\x1b[38;5;34m',
+            vision: '\x1b[38;5;207m',
+            background: '\x1b[90m'
+        };
+        return map[routeName] ?? '\x1b[36m';
+    }
+    describeContextUsage(providerKey, estimatedTokens) {
+        if (typeof estimatedTokens !== 'number' || !Number.isFinite(estimatedTokens) || estimatedTokens <= 0) {
+            return undefined;
+        }
+        let limit = DEFAULT_MODEL_CONTEXT_TOKENS;
+        try {
+            const profile = this.providerRegistry.get(providerKey);
+            if (profile?.maxContextTokens && Number.isFinite(profile.maxContextTokens)) {
+                limit = profile.maxContextTokens;
+            }
+        }
+        catch {
+            limit = DEFAULT_MODEL_CONTEXT_TOKENS;
+        }
+        if (!limit || limit <= 0) {
+            return undefined;
+        }
+        const ratio = estimatedTokens / limit;
+        const threshold = this.contextRouting?.warnRatio ?? 0.9;
+        if (ratio < threshold) {
+            return undefined;
+        }
+        return `${ratio.toFixed(2)}/${Math.round(limit)}`;
+    }
+    describeTargetProvider(providerKey, fallbackModelId) {
+        const parsed = this.parseProviderKey(providerKey);
+        if (!parsed) {
+            return { providerLabel: providerKey, resolvedModel: fallbackModelId };
+        }
+        const aliasLabel = parsed.keyAlias ? `${parsed.providerId}[${parsed.keyAlias}]` : parsed.providerId;
+        const resolvedModel = parsed.modelId || fallbackModelId;
+        return { providerLabel: aliasLabel, resolvedModel };
+    }
+    parseProviderKey(providerKey) {
+        const trimmed = typeof providerKey === 'string' ? providerKey.trim() : '';
+        if (!trimmed) {
+            return null;
+        }
+        const parts = trimmed.split('.');
+        if (parts.length < 2) {
+            return { providerId: trimmed };
+        }
+        if (parts.length === 2) {
+            return { providerId: parts[0], modelId: parts[1] };
+        }
+        return {
+            providerId: parts[0],
+            keyAlias: parts[1],
+            modelId: parts.slice(2).join('.')
+        };
     }
 }