@jsonstudio/rcc 0.89.164 → 0.89.333

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

@@ -3,13 +3,16 @@ 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';
 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;
@@ -22,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 });
@@ -31,12 +36,18 @@ export class VirtualRouterEngine {
         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 selection = this.selectProvider(routeName, metadata, classification, features);
         const target = this.providerRegistry.buildTarget(selection.providerKey);
         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 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,
@@ -120,26 +131,45 @@ export class VirtualRouterEngine {
             }
         }
     }
-    selectProvider(requestedRoute, metadata, classification) {
+    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;
             }
-            attempted.push(routeName);
+            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(this.describeAttempt(routeName, contextResult));
         }
         throw new VirtualRouterError(`All providers unavailable for route ${requestedRoute}`, VirtualRouterErrorCode.PROVIDER_NOT_AVAILABLE, { routeName: requestedRoute, attempted });
     }
@@ -155,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()) {
@@ -277,25 +365,96 @@ export class VirtualRouterEngine {
         const idx = ROUTE_PRIORITY.indexOf(routeName);
         return idx >= 0 ? idx : ROUTE_PRIORITY.length;
     }
-    buildHitReason(routeUsed, classification, features) {
+    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 === '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';
+    }
+    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;
             }
-            return primary || 'tools';
         }
-        if (routeUsed === 'thinking') {
-            return primary || 'thinking';
+        catch {
+            limit = DEFAULT_MODEL_CONTEXT_TOKENS;
         }
-        if (routeUsed === DEFAULT_ROUTE && classification.fallback) {
-            return primary || 'fallback:default';
+        if (!limit || limit <= 0) {
+            return undefined;
         }
-        if (primary) {
-            return primary;
+        const ratio = estimatedTokens / limit;
+        const threshold = this.contextRouting?.warnRatio ?? 0.9;
+        if (ratio < threshold) {
+            return undefined;
         }
-        return routeUsed ? `route:${routeUsed}` : 'route:unknown';
+        return `${ratio.toFixed(2)}/${Math.round(limit)}`;
     }
 }