@jsonstudio/llms 0.6.467 → 0.6.567

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

@@ -0,0 +1,210 @@
+const SERIES_COOLDOWN_DETAIL_KEY = 'virtualRouterSeriesCooldown';
+export function handleProviderFailureImpl(event, healthManager, healthConfig, markProviderCooldown) {
+    if (!event || !event.providerKey) {
+        return;
+    }
+    if (event.affectsHealth === false) {
+        return;
+    }
+    if (event.fatal) {
+        healthManager.tripProvider(event.providerKey, event.reason, event.cooldownOverrideMs);
+    }
+    else if (event.reason === 'rate_limit' && event.statusCode === 429) {
+        healthManager.cooldownProvider(event.providerKey, event.reason, event.cooldownOverrideMs);
+        const ttl = event.cooldownOverrideMs ?? healthConfig.cooldownMs;
+        markProviderCooldown(event.providerKey, ttl);
+    }
+    else {
+        healthManager.recordFailure(event.providerKey, event.reason);
+    }
+}
+export function mapProviderErrorImpl(event, healthConfig) {
+    if (!event || !event.runtime) {
+        return null;
+    }
+    const runtime = event.runtime;
+    const providerKey = runtime.providerKey ||
+        (runtime.target && typeof runtime.target === 'object'
+            ? runtime.target.providerKey
+            : undefined);
+    if (!providerKey) {
+        return null;
+    }
+    const routeName = runtime.routeName;
+    const statusCode = event.status;
+    const code = event.code?.toUpperCase() ?? 'ERR_UNKNOWN';
+    const stage = event.stage?.toLowerCase() ?? 'unknown';
+    const recoverable = event.recoverable === true;
+    let fatal = !recoverable;
+    let reason = deriveReason(code, stage, statusCode);
+    let cooldownOverrideMs;
+    if (statusCode === 401 || statusCode === 402 || statusCode === 403 || code.includes('AUTH')) {
+        fatal = true;
+        cooldownOverrideMs = Math.max(10 * 60_000, healthConfig.fatalCooldownMs ?? 10 * 60_000);
+        reason = 'auth';
+    }
+    else if (statusCode === 429 && !recoverable) {
+        fatal = true;
+        cooldownOverrideMs = Math.max(10 * 60_000, healthConfig.fatalCooldownMs ?? 10 * 60_000);
+        reason = 'rate_limit';
+    }
+    else if (statusCode && statusCode >= 500) {
+        fatal = true;
+        cooldownOverrideMs = Math.max(5 * 60_000, healthConfig.fatalCooldownMs ?? 5 * 60_000);
+        reason = 'upstream_error';
+    }
+    else if (stage.includes('compat')) {
+        fatal = true;
+        cooldownOverrideMs = Math.max(10 * 60_000, healthConfig.fatalCooldownMs ?? 10 * 60_000);
+        reason = 'compatibility';
+    }
+    return {
+        providerKey,
+        routeName,
+        reason,
+        fatal,
+        statusCode,
+        errorCode: code,
+        retryable: recoverable,
+        affectsHealth: event.affectsHealth !== false,
+        cooldownOverrideMs,
+        metadata: {
+            ...event.runtime,
+            stage,
+            eventCode: code,
+            originalMessage: event.message,
+            statusCode
+        }
+    };
+}
+export function applySeriesCooldownImpl(event, providerRegistry, healthManager, markProviderCooldown, debug) {
+    const seriesDetail = extractSeriesCooldownDetail(event);
+    if (!seriesDetail) {
+        return;
+    }
+    const targetKeys = resolveSeriesCooldownTargets(seriesDetail, event, providerRegistry);
+    if (targetKeys.length === 0) {
+        debug?.log?.('[virtual-router] series cooldown skipped: no targets', {
+            providerId: seriesDetail.providerId,
+            providerKey: seriesDetail.providerKey,
+            series: seriesDetail.series
+        });
+        return;
+    }
+    const affected = [];
+    for (const providerKey of targetKeys) {
+        try {
+            const profile = providerRegistry.get(providerKey);
+            const modelSeries = resolveModelSeries(profile.modelId);
+            if (modelSeries !== seriesDetail.series) {
+                continue;
+            }
+            healthManager.tripProvider(providerKey, 'rate_limit', seriesDetail.cooldownMs);
+            markProviderCooldown(providerKey, seriesDetail.cooldownMs);
+            affected.push(providerKey);
+        }
+        catch {
+            // ignore lookup failures; invalid keys may show up if config drifted
+        }
+    }
+    if (affected.length) {
+        debug?.log?.('[virtual-router] series cooldown', {
+            providerId: seriesDetail.providerId,
+            providerKey: seriesDetail.providerKey,
+            series: seriesDetail.series,
+            cooldownMs: seriesDetail.cooldownMs,
+            affected
+        });
+    }
+}
+function resolveSeriesCooldownTargets(detail, event, providerRegistry) {
+    const candidates = new Set();
+    const push = (key) => {
+        if (typeof key !== 'string') {
+            return;
+        }
+        const trimmed = key.trim();
+        if (!trimmed) {
+            return;
+        }
+        if (providerRegistry.has(trimmed)) {
+            candidates.add(trimmed);
+        }
+    };
+    push(detail.providerKey);
+    const runtimeKey = (event.runtime?.target && typeof event.runtime.target === 'object'
+        ? event.runtime.target.providerKey
+        : undefined) || event.runtime?.providerKey;
+    push(runtimeKey);
+    return Array.from(candidates);
+}
+function extractSeriesCooldownDetail(event) {
+    if (!event || !event.details || typeof event.details !== 'object') {
+        return null;
+    }
+    const raw = event.details[SERIES_COOLDOWN_DETAIL_KEY];
+    if (!raw || typeof raw !== 'object') {
+        return null;
+    }
+    const record = raw;
+    const providerIdRaw = record.providerId;
+    const seriesRaw = record.series;
+    const providerKeyRaw = record.providerKey;
+    const cooldownRaw = record.cooldownMs;
+    if (typeof providerIdRaw !== 'string' || !providerIdRaw.trim()) {
+        return null;
+    }
+    const normalizedSeries = typeof seriesRaw === 'string' ? seriesRaw.trim().toLowerCase() : '';
+    if (normalizedSeries !== 'gemini-pro' && normalizedSeries !== 'gemini-flash' && normalizedSeries !== 'claude') {
+        return null;
+    }
+    const cooldownMs = typeof cooldownRaw === 'number'
+        ? cooldownRaw
+        : typeof cooldownRaw === 'string'
+            ? Number.parseFloat(cooldownRaw)
+            : Number.NaN;
+    if (!Number.isFinite(cooldownMs) || cooldownMs <= 0) {
+        return null;
+    }
+    return {
+        providerId: providerIdRaw.trim(),
+        ...(typeof providerKeyRaw === 'string' && providerKeyRaw.trim().length
+            ? { providerKey: providerKeyRaw.trim() }
+            : {}),
+        series: normalizedSeries,
+        cooldownMs: Math.round(cooldownMs)
+    };
+}
+export function deriveReason(code, stage, statusCode) {
+    if (code.includes('RATE') || code.includes('429'))
+        return 'rate_limit';
+    if (code.includes('AUTH') || statusCode === 401 || statusCode === 403)
+        return 'auth';
+    if (stage.includes('compat'))
+        return 'compatibility';
+    if (code.includes('SSE'))
+        return 'sse';
+    if (code.includes('TIMEOUT') || statusCode === 408 || statusCode === 504)
+        return 'timeout';
+    if (statusCode && statusCode >= 500)
+        return 'upstream_error';
+    if (statusCode && statusCode >= 400)
+        return 'client_error';
+    return 'unknown';
+}
+function resolveModelSeries(modelId) {
+    if (!modelId) {
+        return 'default';
+    }
+    const lower = modelId.toLowerCase();
+    if (lower.includes('claude') || lower.includes('opus')) {
+        return 'claude';
+    }
+    if (lower.includes('flash')) {
+        return 'gemini-flash';
+    }
+    if (lower.includes('gemini') || lower.includes('pro')) {
+        return 'gemini-pro';
+    }
+    return 'default';
+}

package/dist/router/virtual-router/engine-logging.d.ts

@@ -0,0 +1,19 @@
+import { type ClassificationResult, type RoutingFeatures, type RoutingInstructionMode, type VirtualRouterContextRoutingConfig } from './types.js';
+import { ProviderRegistry } from './provider-registry.js';
+type LoggingDeps = {
+    providerRegistry: ProviderRegistry;
+    contextRouting: VirtualRouterContextRoutingConfig | undefined;
+};
+export declare function formatStickyScope(scope?: string): string | undefined;
+export declare function parseProviderKey(providerKey: string): {
+    providerId: string;
+    keyAlias?: string;
+    modelId?: string;
+} | null;
+export declare function describeTargetProvider(providerKey: string, fallbackModelId?: string): {
+    providerLabel: string;
+    resolvedModel?: string;
+};
+export declare function buildHitReason(routeUsed: string, providerKey: string, classification: ClassificationResult, features: RoutingFeatures, mode: RoutingInstructionMode | undefined, deps: LoggingDeps): string;
+export declare function formatVirtualRouterHit(routeName: string, poolId: string | undefined, providerKey: string, modelId?: string, hitReason?: string, stickyScope?: string): string;
+export {};

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

@@ -0,0 +1,165 @@
+import { DEFAULT_MODEL_CONTEXT_TOKENS, DEFAULT_ROUTE } from './types.js';
+export function formatStickyScope(scope) {
+    if (!scope || scope.trim().length === 0) {
+        return undefined;
+    }
+    const normalized = scope.trim();
+    const maxLength = 20;
+    if (normalized.length <= maxLength) {
+        return normalized;
+    }
+    const delimiterIndex = normalized.indexOf(':');
+    const prefix = delimiterIndex > 0 ? normalized.slice(0, delimiterIndex + 1) : '';
+    const body = delimiterIndex > 0 ? normalized.slice(delimiterIndex + 1) : normalized;
+    if (body.length <= 8) {
+        return `${prefix}${body}`;
+    }
+    return `${prefix}${body.slice(0, 4)}…${body.slice(-4)}`;
+}
+export function 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('.')
+    };
+}
+export function describeTargetProvider(providerKey, fallbackModelId) {
+    const parsed = 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 };
+}
+function resolveRouteColor(routeName) {
+    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';
+}
+function describeContextUsage(providerKey, estimatedTokens, deps) {
+    if (typeof estimatedTokens !== 'number' || !Number.isFinite(estimatedTokens) || estimatedTokens <= 0) {
+        return undefined;
+    }
+    let limit = DEFAULT_MODEL_CONTEXT_TOKENS;
+    try {
+        const profile = deps.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 = deps.contextRouting?.warnRatio ?? 0.9;
+    if (ratio < threshold) {
+        return undefined;
+    }
+    return `${ratio.toFixed(2)}/${Math.round(limit)}`;
+}
+function decorateWithDetail(baseLabel, primaryReason, detail) {
+    const normalizedDetail = detail && detail.trim();
+    if (!normalizedDetail) {
+        return primaryReason || baseLabel;
+    }
+    if (primaryReason) {
+        return `${primaryReason}(${normalizedDetail})`;
+    }
+    return `${baseLabel}(${normalizedDetail})`;
+}
+export function buildHitReason(routeUsed, providerKey, classification, features, mode, deps) {
+    const reasoning = classification.reasoning || '';
+    let primary = reasoning.split('|')[0] || '';
+    const commandDetail = features.lastAssistantToolLabel;
+    const isStickyMode = mode === 'sticky';
+    if (isStickyMode &&
+        (routeUsed === 'tools' || routeUsed === 'thinking' || routeUsed === 'coding')) {
+        primary = '';
+    }
+    const base = (() => {
+        if (routeUsed === 'tools') {
+            const label = isStickyMode ? 'sticky' : 'tools';
+            return decorateWithDetail(primary || label, primary, commandDetail);
+        }
+        if (routeUsed === 'thinking') {
+            const label = isStickyMode ? 'sticky' : 'thinking';
+            return decorateWithDetail(primary || label, primary, commandDetail);
+        }
+        if (routeUsed === 'coding') {
+            const label = isStickyMode ? 'sticky' : 'coding';
+            return decorateWithDetail(primary || label, primary, commandDetail);
+        }
+        if (routeUsed === 'web_search' || routeUsed === 'search') {
+            return decorateWithDetail(primary || routeUsed, primary, commandDetail);
+        }
+        if (routeUsed === DEFAULT_ROUTE && classification.fallback) {
+            if (isStickyMode) {
+                return primary || 'sticky:default';
+            }
+            return primary || 'fallback:default';
+        }
+        if (primary) {
+            return primary;
+        }
+        return routeUsed ? `route:${routeUsed}` : 'route:unknown';
+    })();
+    const contextDetail = describeContextUsage(providerKey, features.estimatedTokens, deps);
+    if (contextDetail) {
+        return `${base}|context:${contextDetail}`;
+    }
+    return base;
+}
+export function formatVirtualRouterHit(routeName, poolId, providerKey, modelId, hitReason, stickyScope) {
+    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 stickyColor = '\x1b[33m';
+        const routeColor = resolveRouteColor(routeName);
+        const prefix = `${prefixColor}[virtual-router-hit]${reset}`;
+        const timeLabel = `${timeColor}${timestamp}${reset}`;
+        const { providerLabel, resolvedModel } = describeTargetProvider(providerKey, modelId);
+        const routeLabel = poolId ? `${routeName}/${poolId}` : routeName;
+        const targetLabel = `${routeLabel} -> ${providerLabel}${resolvedModel ? '.' + resolvedModel : ''}`;
+        const stickyText = formatStickyScope(stickyScope);
+        const stickyLabel = stickyText ? ` ${stickyColor}[sticky:${stickyText}]${reset}` : '';
+        const reasonLabel = hitReason ? ` reason=${hitReason}` : '';
+        return `${prefix} ${timeLabel} ${routeColor}${targetLabel}${stickyLabel}${reasonLabel}${reset}`;
+    }
+    catch {
+        const now = new Date();
+        const timestamp = now.toLocaleTimeString('zh-CN', { hour12: false });
+        const routeLabel = poolId ? `${routeName}/${poolId}` : routeName;
+        const stickyText = formatStickyScope(stickyScope);
+        const stickyLabel = stickyText ? ` [sticky:${stickyText}]` : '';
+        return `[virtual-router-hit] ${timestamp} ${routeLabel} -> ${providerKey}${modelId ? '.' + modelId : ''}${stickyLabel}${hitReason ? ` reason=${hitReason}` : ''}`;
+    }
+}

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

@@ -0,0 +1,32 @@
+import type { ClassificationResult, RoutePoolTier, RouterMetadataInput, RoutingFeatures } from './types.js';
+import type { RoutingInstructionState } from './routing-instructions.js';
+import type { ContextAdvisor } from './context-advisor.js';
+import type { RouteLoadBalancer } from './load-balancer.js';
+import type { ProviderHealthManager } from './health-manager.js';
+import type { ProviderRegistry } from './provider-registry.js';
+type SelectionDeps = {
+    routing: Record<string, RoutePoolTier[]>;
+    providerRegistry: ProviderRegistry;
+    healthManager: ProviderHealthManager;
+    contextAdvisor: ContextAdvisor;
+    loadBalancer: RouteLoadBalancer;
+    isProviderCoolingDown: (providerKey: string) => boolean;
+    resolveStickyKey: (metadata: RouterMetadataInput) => string | undefined;
+};
+export declare function selectProviderImpl(requestedRoute: string, metadata: RouterMetadataInput, classification: ClassificationResult, features: RoutingFeatures, activeState: RoutingInstructionState, deps: SelectionDeps, options?: {
+    routingState?: RoutingInstructionState;
+}): {
+    providerKey: string;
+    routeUsed: string;
+    pool: string[];
+    poolId?: string;
+};
+export declare function selectFromStickyPool(stickyKeySet: Set<string>, metadata: RouterMetadataInput, features: RoutingFeatures, state: RoutingInstructionState, deps: SelectionDeps, options: {
+    allowAliasRotation?: boolean;
+}): {
+    providerKey: string;
+    routeUsed: string;
+    pool: string[];
+    poolId?: string;
+} | null;
+export {};