@jsonstudio/llms 0.6.147 → 0.6.187

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

@@ -3,24 +3,19 @@ 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';
-const VIRTUAL_ROUTER_HIT_COLOR = '\x1b[38;5;208m';
-const ANSI_RESET = '\x1b[0m';
-const STICKY_PLAN_TTL_MS = 30 * 60 * 1000;
-const ERROR_STREAK_TTL_MS = 10 * 60 * 1000;
-const ERROR_STREAK_THRESHOLD = 4;
+import { ContextAdvisor } from './context-advisor.js';
+import { DEFAULT_MODEL_CONTEXT_TOKENS, DEFAULT_ROUTE, ROUTE_PRIORITY, VirtualRouterError, VirtualRouterErrorCode } from './types.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;
-    stickyPlans = new Map();
-    selectionHistory = new Map();
-    providerErrorStreaks = new Map();
     initialize(config) {
         this.validateConfig(config);
         this.routing = config.routing;
@@ -30,6 +25,8 @@ 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.routeStats = new Map();
         for (const routeName of Object.keys(this.routing)) {
             this.routeStats.set(routeName, { hits: 0 });
@@ -37,42 +34,21 @@ export class VirtualRouterEngine {
     }
     route(request, metadata) {
         const features = buildRoutingFeatures(request, metadata);
-        let stickyActivation = this.consumeSticky(metadata, features);
-        let classification = null;
-        let selection = null;
-        if (stickyActivation) {
-            selection = this.selectStickyTarget(stickyActivation, metadata);
-            if (selection) {
-                classification = this.buildStickyClassification(stickyActivation);
-            }
-            else {
-                stickyActivation = null;
-            }
-        }
-        if (!selection || !classification) {
-            classification = this.classifier.classify(features);
-            classification = this.ensureConfiguredClassification(classification);
-            const routeName = classification.routeName || DEFAULT_ROUTE;
-            selection = this.selectProvider(routeName, metadata, classification);
-        }
-        if (!selection || !classification) {
-            throw new VirtualRouterError('Virtual router failed to select provider', VirtualRouterErrorCode.ROUTE_NOT_FOUND);
-        }
+        const classification = this.classifier.classify(features);
+        const routeName = classification.routeName || DEFAULT_ROUTE;
+        const selection = this.selectProvider(routeName, metadata, classification, features);
         const target = this.providerRegistry.buildTarget(selection.providerKey);
         this.healthManager.recordSuccess(selection.providerKey);
-        this.resetProviderErrorStreak(selection.providerKey);
         this.incrementRouteStat(selection.routeUsed, selection.providerKey);
-        const targetModel = typeof target.modelId === 'string' ? target.modelId : '';
-        this.recordSelectionSnapshot(metadata.requestId, selection.routeUsed, selection.providerKey, targetModel);
-        if (!stickyActivation || stickyActivation.mode === 'forced') {
-            const nextPlan = this.buildStickyPlan(features, selection, target);
-            this.storeStickyPlan(metadata.requestId, nextPlan);
-        }
-        const phase = stickyActivation ? 'execution' : 'hit';
-        const hitReason = this.buildHitReason(selection.routeUsed, classification, features, stickyActivation || undefined, phase);
-        const hitLog = this.buildVirtualRouterHitLog(selection.routeUsed, selection.providerKey, targetModel, hitReason, stickyActivation || undefined, phase);
-        this.debug?.log?.(hitLog);
-        const didFallback = selection.routeUsed !== (classification.routeName || DEFAULT_ROUTE) || classification.fallback;
+        const hitReason = this.buildHitReason(selection.routeUsed, selection.providerKey, classification, features);
+        const formatted = this.formatVirtualRouterHit(selection.routeUsed, 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 !== routeName || classification.fallback;
         return {
             target,
             decision: {
@@ -108,9 +84,6 @@ export class VirtualRouterEngine {
         }
     }
     handleProviderError(event) {
-        if (event?.runtime?.requestId) {
-            this.dropStickyForRequest(event.runtime.requestId);
-        }
         const derived = this.mapProviderError(event);
         if (!derived) {
             return;
@@ -132,206 +105,6 @@ export class VirtualRouterEngine {
             health: this.healthManager.getSnapshot()
         };
     }
-    consumeSticky(metadata, features) {
-        const prevId = this.extractPreviousRequestId(metadata);
-        if (!prevId) {
-            return null;
-        }
-        this.pruneStickyPlans();
-        const planned = this.stickyPlans.get(prevId);
-        if (planned) {
-            this.stickyPlans.delete(prevId);
-            const activation = {
-                ...planned,
-                sourceRequestId: prevId,
-                mode: 'planned'
-            };
-            if (planned.remainingRounds > 1 && metadata.requestId) {
-                this.stickyPlans.set(metadata.requestId, {
-                    ...planned,
-                    remainingRounds: planned.remainingRounds - 1,
-                    createdAt: Date.now()
-                });
-            }
-            return activation;
-        }
-        return this.maybeForceStickyFromHistory(prevId, features);
-    }
-    selectStickyTarget(sticky, metadata) {
-        if (sticky.strategy === 'target' && sticky.providerKey) {
-            if (!this.healthManager.isAvailable(sticky.providerKey)) {
-                return null;
-            }
-            const pool = this.routing[sticky.routeName] ?? [];
-            return { providerKey: sticky.providerKey, routeUsed: sticky.routeName, pool };
-        }
-        const pool = this.routing[sticky.routeName];
-        if (!Array.isArray(pool) || pool.length === 0) {
-            return null;
-        }
-        const stub = {
-            routeName: sticky.routeName,
-            confidence: 1,
-            reasoning: `sticky:${sticky.reason}`,
-            fallback: false,
-            candidates: [sticky.routeName]
-        };
-        return this.selectProvider(sticky.routeName, metadata, stub);
-    }
-    buildStickyClassification(sticky) {
-        return {
-            routeName: sticky.routeName,
-            confidence: 1,
-            reasoning: `sticky:${sticky.reason}`,
-            fallback: false,
-            candidates: [sticky.routeName]
-        };
-    }
-    recordSelectionSnapshot(requestId, routeName, providerKey, modelId) {
-        if (!requestId || !providerKey) {
-            return;
-        }
-        this.selectionHistory.set(requestId, {
-            routeName,
-            providerKey,
-            modelId,
-            createdAt: Date.now()
-        });
-        this.pruneStickyPlans();
-    }
-    buildStickyPlan(features, selection, target) {
-        const descriptor = this.resolveStickyDescriptor(selection.routeUsed, features);
-        if (!descriptor || descriptor.rounds <= 0) {
-            return null;
-        }
-        const plan = {
-            routeName: selection.routeUsed,
-            strategy: descriptor.strategy,
-            providerKey: descriptor.strategy === 'target' ? selection.providerKey : undefined,
-            modelId: descriptor.strategy === 'target' ? target.modelId : undefined,
-            remainingRounds: descriptor.rounds,
-            totalRounds: descriptor.rounds,
-            reason: descriptor.reason,
-            createdAt: Date.now()
-        };
-        return plan;
-    }
-    storeStickyPlan(requestId, plan) {
-        if (!requestId) {
-            return;
-        }
-        this.pruneStickyPlans();
-        if (plan && plan.remainingRounds > 0) {
-            this.stickyPlans.set(requestId, plan);
-        }
-        else {
-            this.stickyPlans.delete(requestId);
-        }
-    }
-    dropStickyForRequest(requestId) {
-        if (!requestId) {
-            return;
-        }
-        this.stickyPlans.delete(requestId);
-        this.selectionHistory.delete(requestId);
-    }
-    resolveStickyDescriptor(routeName, features) {
-        if (this.shouldForceApplyPatchSticky(features)) {
-            return { strategy: 'target', rounds: 1, reason: 'apply_patch' };
-        }
-        if (routeName === 'coding' || routeName === 'thinking') {
-            return { strategy: 'pool', rounds: 3, reason: routeName };
-        }
-        if (routeName === 'tools') {
-            return { strategy: 'pool', rounds: 0, reason: routeName };
-        }
-        if (routeName === DEFAULT_ROUTE || !routeName) {
-            return null;
-        }
-        return { strategy: 'pool', rounds: 1, reason: routeName };
-    }
-    maybeForceStickyFromHistory(prevId, features) {
-        if (!this.shouldForceApplyPatchSticky(features)) {
-            return null;
-        }
-        const snapshot = this.selectionHistory.get(prevId);
-        if (!snapshot) {
-            return null;
-        }
-        if (!this.healthManager.isAvailable(snapshot.providerKey)) {
-            return null;
-        }
-        return {
-            routeName: snapshot.routeName,
-            providerKey: snapshot.providerKey,
-            modelId: snapshot.modelId,
-            strategy: 'target',
-            remainingRounds: 0,
-            totalRounds: 1,
-            reason: 'apply_patch',
-            createdAt: Date.now(),
-            sourceRequestId: prevId,
-            mode: 'forced'
-        };
-    }
-    shouldForceApplyPatchSticky(features) {
-        const name = (features.lastAssistantToolName || '').toLowerCase();
-        if (name === 'apply_patch') {
-            return true;
-        }
-        const detail = (features.lastAssistantToolDetail || '').toLowerCase();
-        if (detail.includes('apply_patch')) {
-            return true;
-        }
-        return false;
-    }
-    extractPreviousRequestId(metadata) {
-        const resume = metadata.responsesResume;
-        if (resume && typeof resume.previousRequestId === 'string' && resume.previousRequestId.trim()) {
-            return resume.previousRequestId.trim();
-        }
-        return undefined;
-    }
-    pruneStickyPlans() {
-        const cutoff = Date.now() - STICKY_PLAN_TTL_MS;
-        for (const [key, plan] of this.stickyPlans.entries()) {
-            if (!plan || plan.createdAt < cutoff) {
-                this.stickyPlans.delete(key);
-            }
-        }
-        for (const [key, snapshot] of this.selectionHistory.entries()) {
-            if (!snapshot || snapshot.createdAt < cutoff) {
-                this.selectionHistory.delete(key);
-            }
-        }
-    }
-    buildErrorSignature(code, statusCode, message) {
-        const normalizedMessage = typeof message === 'string'
-            ? message.trim().toLowerCase().replace(/\s+/g, ' ').slice(0, 120)
-            : '';
-        const codeToken = code?.toUpperCase() || 'ERR_UNKNOWN';
-        const statusToken = typeof statusCode === 'number' ? String(statusCode) : 'NA';
-        return `${statusToken}|${codeToken}|${normalizedMessage}`;
-    }
-    bumpProviderErrorStreak(providerKey, signature) {
-        if (!providerKey || !signature) {
-            return 0;
-        }
-        const now = Date.now();
-        const entry = this.providerErrorStreaks.get(providerKey);
-        if (!entry || entry.signature !== signature || now - entry.lastAt > ERROR_STREAK_TTL_MS) {
-            this.providerErrorStreaks.set(providerKey, { signature, count: 1, lastAt: now });
-            return 1;
-        }
-        const next = { signature, count: entry.count + 1, lastAt: now };
-        this.providerErrorStreaks.set(providerKey, next);
-        return next.count;
-    }
-    resetProviderErrorStreak(providerKey) {
-        if (providerKey) {
-            this.providerErrorStreaks.delete(providerKey);
-        }
-    }
     validateConfig(config) {
         if (!config.routing || typeof config.routing !== 'object') {
             throw new VirtualRouterError('routing configuration is required', VirtualRouterErrorCode.CONFIG_ERROR);
@@ -358,30 +131,47 @@ export class VirtualRouterEngine {
             }
         }
     }
-    selectProvider(requestedRoute, metadata, classification) {
-        const normalizedRoute = this.normalizeRouteName(requestedRoute);
-        const candidates = this.buildRouteCandidates(normalizedRoute, classification.candidates);
+    selectProvider(requestedRoute, metadata, classification, features) {
+        const candidates = this.buildRouteCandidates(requestedRoute, classification.candidates);
         const stickyKey = this.resolveStickyKey(metadata);
         const attempted = [];
-        for (const routeName of candidates) {
+        const visitedRoutes = new Set();
+        const fallbackRoute = this.resolveFallbackRoute();
+        const routeQueue = this.initializeRouteQueue(candidates, fallbackRoute);
+        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 pool = this.routing[routeName];
             if (!Array.isArray(pool) || pool.length === 0) {
+                visitedRoutes.add(routeName);
                 attempted.push(routeName);
                 continue;
             }
-            const providerKey = this.loadBalancer.select({
-                routeName,
-                candidates: pool,
-                stickyKey,
-                availabilityCheck: (key) => this.healthManager.isAvailable(key)
-            });
-            if (providerKey) {
-                return { providerKey, routeUsed: routeName, pool };
+            const contextResult = this.contextAdvisor.classify(pool, estimatedTokens, (key) => this.providerRegistry.get(key));
+            if (this.maybeDeferToFallback(routeName, contextResult, routeQueue, visitedRoutes, fallbackRoute)) {
+                continue;
+            }
+            visitedRoutes.add(routeName);
+            const prioritizedPools = this.buildContextCandidatePools(contextResult);
+            for (const candidatePool of prioritizedPools) {
+                const providerKey = this.loadBalancer.select({
+                    routeName,
+                    candidates: candidatePool,
+                    stickyKey,
+                    availabilityCheck: (key) => this.healthManager.isAvailable(key)
+                });
+                if (providerKey) {
+                    return { providerKey, routeUsed: routeName, pool };
+                }
             }
-            attempted.push(routeName);
+            attempted.push(this.describeAttempt(routeName, contextResult));
         }
-        const failureRoute = attempted.length ? attempted[attempted.length - 1] : requestedRoute;
-        throw new VirtualRouterError(`All providers unavailable for route ${failureRoute}`, VirtualRouterErrorCode.PROVIDER_NOT_AVAILABLE, { routeName: failureRoute, attempted });
+        throw new VirtualRouterError(`All providers unavailable for route ${requestedRoute}`, VirtualRouterErrorCode.PROVIDER_NOT_AVAILABLE, { routeName: requestedRoute, attempted });
     }
     incrementRouteStat(routeName, providerKey) {
         if (!this.routeStats.has(routeName)) {
@@ -395,6 +185,64 @@ export class VirtualRouterEngine {
     providerHealthConfig() {
         return this.healthManager.getConfig();
     }
+    initializeRouteQueue(candidates, fallbackRoute) {
+        const queue = Array.from(new Set(candidates));
+        if (fallbackRoute && !queue.includes(fallbackRoute)) {
+            queue.push(fallbackRoute);
+        }
+        return queue;
+    }
+    resolveFallbackRoute() {
+        const candidate = this.contextRouting?.fallbackRoute;
+        if (!candidate) {
+            return undefined;
+        }
+        const pool = this.routing[candidate];
+        if (!Array.isArray(pool) || pool.length === 0) {
+            return undefined;
+        }
+        return candidate;
+    }
+    maybeDeferToFallback(routeName, contextResult, queue, visited, fallbackRoute) {
+        if (!fallbackRoute || fallbackRoute === routeName || visited.has(fallbackRoute)) {
+            return false;
+        }
+        if (!this.contextAdvisor.prefersFallback(contextResult)) {
+            return false;
+        }
+        const fallbackPool = this.routing[fallbackRoute];
+        if (!Array.isArray(fallbackPool) || fallbackPool.length === 0) {
+            return false;
+        }
+        queue.unshift(routeName);
+        queue.unshift(fallbackRoute);
+        return true;
+    }
+    buildContextCandidatePools(result) {
+        const ordered = [];
+        if (result.safe.length) {
+            ordered.push(result.safe);
+        }
+        if (result.risky.length) {
+            ordered.push(result.risky);
+        }
+        if (result.overflow.length && this.contextAdvisor.allowsOverflow()) {
+            ordered.push(result.overflow);
+        }
+        return ordered;
+    }
+    describeAttempt(routeName, result) {
+        if (result.safe.length > 0) {
+            return `${routeName}:health`;
+        }
+        if (result.risky.length > 0) {
+            return `${routeName}:context_risky`;
+        }
+        if (result.overflow.length > 0) {
+            return `${routeName}:context_overflow`;
+        }
+        return routeName;
+    }
     resolveStickyKey(metadata) {
         const resume = metadata.responsesResume;
         if (resume && typeof resume.previousRequestId === 'string' && resume.previousRequestId.trim()) {
@@ -447,13 +295,6 @@ export class VirtualRouterEngine {
             cooldownOverrideMs = Math.max(10 * 60_000, this.providerHealthConfig().fatalCooldownMs ?? 10 * 60_000);
             reason = 'compatibility';
         }
-        const signature = this.buildErrorSignature(code, statusCode, event.message);
-        const streak = this.bumpProviderErrorStreak(providerKey, signature);
-        if (streak >= ERROR_STREAK_THRESHOLD) {
-            fatal = true;
-            reason = reason === 'unknown' ? 'repeated_error' : `${reason}|repeated`;
-            cooldownOverrideMs = Math.max(this.providerHealthConfig().fatalCooldownMs ?? 5 * 60_000, 5 * 60_000);
-        }
         return {
             providerKey,
             routeName,
@@ -517,59 +358,6 @@ export class VirtualRouterEngine {
         }
         return filtered.length ? filtered : [DEFAULT_ROUTE];
     }
-    ensureConfiguredClassification(classification) {
-        const normalizedRoute = this.normalizeRouteName(classification.routeName);
-        const normalizedCandidates = this.normalizeCandidateList(normalizedRoute, classification.candidates);
-        const fallback = normalizedRoute === DEFAULT_ROUTE ? true : classification.fallback;
-        return {
-            ...classification,
-            routeName: normalizedRoute,
-            fallback,
-            candidates: normalizedCandidates
-        };
-    }
-    normalizeCandidateList(primaryRoute, rawCandidates) {
-        const base = rawCandidates && rawCandidates.length ? rawCandidates : [primaryRoute];
-        const deduped = [];
-        for (const routeName of base) {
-            if (!routeName) {
-                continue;
-            }
-            if (!this.isRouteConfigured(routeName)) {
-                continue;
-            }
-            if (!deduped.includes(routeName)) {
-                deduped.push(routeName);
-            }
-        }
-        if (!deduped.includes(primaryRoute) && this.isRouteConfigured(primaryRoute)) {
-            deduped.push(primaryRoute);
-        }
-        if (!deduped.includes(DEFAULT_ROUTE) && this.isRouteConfigured(DEFAULT_ROUTE)) {
-            deduped.push(DEFAULT_ROUTE);
-        }
-        if (!deduped.length && this.isRouteConfigured(DEFAULT_ROUTE)) {
-            deduped.push(DEFAULT_ROUTE);
-        }
-        return this.sortByPriority(deduped);
-    }
-    normalizeRouteName(routeName) {
-        if (routeName && this.isRouteConfigured(routeName)) {
-            return routeName;
-        }
-        if (this.isRouteConfigured(DEFAULT_ROUTE)) {
-            return DEFAULT_ROUTE;
-        }
-        const firstConfigured = Object.keys(this.routing).find((key) => this.isRouteConfigured(key));
-        return firstConfigured || DEFAULT_ROUTE;
-    }
-    isRouteConfigured(routeName) {
-        if (!routeName) {
-            return false;
-        }
-        const pool = this.routing[routeName];
-        return Array.isArray(pool) && pool.length > 0;
-    }
     sortByPriority(routeNames) {
         return [...routeNames].sort((a, b) => this.routeWeight(a) - this.routeWeight(b));
     }
@@ -577,89 +365,96 @@ export class VirtualRouterEngine {
         const idx = ROUTE_PRIORITY.indexOf(routeName);
         return idx >= 0 ? idx : ROUTE_PRIORITY.length;
     }
-    buildHitReason(routeUsed, classification, features, sticky, phase) {
+    buildHitReason(routeUsed, providerKey, classification, features) {
         const reasoning = classification.reasoning || '';
         const primary = reasoning.split('|')[0] || '';
-        const lastToolName = features.lastAssistantToolName;
-        const lastToolDetail = features.lastAssistantToolDetail;
-        if (routeUsed === 'tools') {
-            const decoratedTools = lastToolName ? this.formatToolIdentifier(lastToolName, lastToolDetail) : null;
-            const base = primary
-                ? decoratedTools
-                    ? `${primary}(${decoratedTools})`
-                    : primary
-                : decoratedTools
-                    ? `tools(${decoratedTools})`
-                    : 'tools';
-            return this.decorateReason(base, sticky, phase);
-        }
-        if (routeUsed === 'thinking') {
-            return this.decorateReason(primary || 'thinking', sticky, phase);
-        }
-        if (routeUsed === DEFAULT_ROUTE && classification.fallback) {
-            return this.decorateReason(primary || 'fallback:default', sticky, phase);
-        }
-        if (primary) {
-            return this.decorateReason(primary, sticky, phase);
-        }
-        return this.decorateReason(routeUsed ? `route:${routeUsed}` : 'route:unknown', sticky, phase);
-    }
-    formatToolIdentifier(name, detail) {
-        if (!detail) {
-            return name;
-        }
-        return `${name}:${detail}`;
-    }
-    decorateReason(base, sticky, phase) {
-        let result = base;
-        if (sticky) {
-            result = `${result}|sticky:${sticky.reason}`;
-        }
-        if (phase === 'execution') {
-            result = `${result}|phase=execution`;
-        }
-        return result;
-    }
-    buildVirtualRouterHitLog(route, providerKey, modelId, reason, sticky, phase) {
-        const parts = ['[virtual-router-hit]', route, providerKey];
-        if (modelId) {
-            parts.push(modelId);
-        }
-        if (reason) {
-            parts.push(`reason=${reason}`);
-        }
-        parts.push(`phase=${phase}`);
-        if (sticky) {
-            const total = Math.max(1, sticky.totalRounds || sticky.remainingRounds || 1);
-            const consumed = Math.max(1, Math.min(total, total - sticky.remainingRounds));
-            const descriptor = `${sticky.strategy}:${sticky.reason}[${consumed}/${total};${sticky.mode}]`;
-            parts.push(`sticky=${descriptor}`);
-        }
-        const message = parts.filter((segment) => typeof segment === 'string' && segment.length > 0).join(' ');
-        return this.colorizeVirtualRouterLog(message);
+        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 === 'websearch') {
+                return this.decorateWithDetail(primary || 'websearch', primary, commandDetail);
+            }
+            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 (primaryReason) {
+            return `${primaryReason}(${normalizedDetail})`;
+        }
+        return `${baseLabel}(${normalizedDetail})`;
+    }
+    formatVirtualRouterHit(routeName, providerKey, modelId, hitReason) {
+        try {
+            const prefixColor = '\x1b[38;5;208m';
+            const reset = '\x1b[0m';
+            const routeColor = this.resolveRouteColor(routeName);
+            const prefix = `${prefixColor}[virtual-router-hit]${reset}`;
+            const targetLabel = `${routeName} -> ${providerKey}${modelId ? '.' + modelId : ''}`;
+            const reasonLabel = hitReason ? ` reason=${hitReason}` : '';
+            return `${prefix} ${routeColor}${targetLabel}${reasonLabel}${reset}`;
+        }
+        catch {
+            return `[virtual-router-hit] ${routeName} -> ${providerKey}${modelId ? '.' + modelId : ''}${hitReason ? ` reason=${hitReason}` : ''}`;
+        }
+    }
+    resolveRouteColor(routeName) {
+        const reset = '\x1b[0m';
+        const map = {
+            tools: '\x1b[38;5;214m',
+            thinking: '\x1b[34m',
+            coding: '\x1b[35m',
+            longcontext: '\x1b[38;5;141m',
+            websearch: '\x1b[32m',
+            vision: '\x1b[38;5;207m',
+            background: '\x1b[90m'
+        };
+        return map[routeName] ?? '\x1b[36m';
     }
-    colorizeVirtualRouterLog(message) {
-        if (!this.shouldColorVirtualRouterLogs()) {
-            return message;
+    describeContextUsage(providerKey, estimatedTokens) {
+        if (typeof estimatedTokens !== 'number' || !Number.isFinite(estimatedTokens) || estimatedTokens <= 0) {
+            return undefined;
         }
-        return `${VIRTUAL_ROUTER_HIT_COLOR}${message}${ANSI_RESET}`;
-    }
-    shouldColorVirtualRouterLogs() {
-        if (typeof process === 'undefined') {
-            return false;
+        let limit = DEFAULT_MODEL_CONTEXT_TOKENS;
+        try {
+            const profile = this.providerRegistry.get(providerKey);
+            if (profile?.maxContextTokens && Number.isFinite(profile.maxContextTokens)) {
+                limit = profile.maxContextTokens;
+            }
         }
-        const noColor = String(process.env.NO_COLOR ?? process.env.RCC_NO_COLOR ?? '').toLowerCase();
-        if (noColor === '1' || noColor === 'true') {
-            return false;
+        catch {
+            limit = DEFAULT_MODEL_CONTEXT_TOKENS;
         }
-        const forceColor = String(process.env.FORCE_COLOR ?? '').trim();
-        if (forceColor === '0') {
-            return false;
+        if (!limit || limit <= 0) {
+            return undefined;
         }
-        const stdout = process.stdout;
-        if (stdout && stdout.isTTY === false) {
-            return false;
+        const ratio = estimatedTokens / limit;
+        const threshold = this.contextRouting?.warnRatio ?? 0.9;
+        if (ratio < threshold) {
+            return undefined;
         }
-        return true;
+        return `${ratio.toFixed(2)}/${Math.round(limit)}`;
     }
 }