@jsonstudio/llms 0.6.567 → 0.6.586

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

@@ -10,7 +10,7 @@ import { parseRoutingInstructions, applyRoutingInstructions, cleanMessagesFromRo
 import { loadRoutingInstructionStateSync, saveRoutingInstructionStateAsync } from './sticky-session-store.js';
 import { buildHitReason, formatVirtualRouterHit } from './engine-logging.js';
 import { selectProviderImpl } from './engine-selection.js';
-import { applySeriesCooldownImpl, handleProviderFailureImpl, mapProviderErrorImpl } from './engine-health.js';
+import { applyQuotaDepletedImpl, applyQuotaRecoveryImpl, applySeriesCooldownImpl, handleProviderFailureImpl, mapProviderErrorImpl } from './engine-health.js';
 export class VirtualRouterEngine {
     routing = {};
     providerRegistry = new ProviderRegistry();
@@ -26,7 +26,20 @@ export class VirtualRouterEngine {
     statsCenter = getStatsCenter();
     // Derived flags from VirtualRouterConfig/routing used by process / response layers.
     webSearchForce = false;
+    healthStore;
+    routingStateStore = {
+        loadSync: loadRoutingInstructionStateSync,
+        saveAsync: saveRoutingInstructionStateAsync
+    };
     routingInstructionState = new Map();
+    constructor(deps) {
+        if (deps?.healthStore) {
+            this.healthStore = deps.healthStore;
+        }
+        if (deps?.routingStateStore) {
+            this.routingStateStore = deps.routingStateStore;
+        }
+    }
     initialize(config) {
         this.validateConfig(config);
         this.routing = config.routing;
@@ -34,6 +47,8 @@ export class VirtualRouterEngine {
         this.healthManager.configure(config.health);
         this.healthConfig = config.health ?? null;
         this.healthManager.registerProviders(Object.keys(config.providers));
+        this.providerCooldowns.clear();
+        this.restoreHealthFromStore();
         this.loadBalancer = new RouteLoadBalancer(config.loadBalancing);
         this.classifier = new RoutingClassifier(config.classifier);
         this.contextRouting = config.contextRouting ?? { warnRatio: 0.9, hardLimit: false };
@@ -52,6 +67,15 @@ export class VirtualRouterEngine {
         if (metadataInstructions.length > 0) {
             routingState = applyRoutingInstructions(metadataInstructions, routingState);
         }
+        const disableStickyRoutes = metadata &&
+            typeof metadata === 'object' &&
+            metadata.disableStickyRoutes === true;
+        if (disableStickyRoutes && routingState.stickyTarget) {
+            routingState = {
+                ...routingState,
+                stickyTarget: undefined
+            };
+        }
         const instructions = parseRoutingInstructions(request.messages);
         if (instructions.length > 0) {
             routingState = applyRoutingInstructions(instructions, routingState);
@@ -98,7 +122,7 @@ export class VirtualRouterEngine {
         const hitReason = buildHitReason(selection.routeUsed, selection.providerKey, classification, features, routingMode, { providerRegistry: this.providerRegistry, contextRouting: this.contextRouting });
         const stickyScope = routingMode !== 'none' ? this.resolveSessionScope(metadata) : undefined;
         const routeForLog = routingMode === 'sticky' ? 'sticky' : selection.routeUsed;
-        const formatted = formatVirtualRouterHit(routeForLog, selection.poolId, selection.providerKey, target.modelId || '', hitReason, stickyScope);
+        const formatted = formatVirtualRouterHit(routeForLog, selection.poolId, selection.providerKey, target.modelId || '', hitReason, stickyScope, routingState);
         if (formatted) {
             this.debug?.log?.(formatted);
         }
@@ -106,6 +130,36 @@ export class VirtualRouterEngine {
             this.debug?.log?.('[virtual-router-hit]', selection.routeUsed, selection.providerKey, target.modelId || '', hitReason ? `reason=${hitReason}` : '');
         }
         const didFallback = selection.routeUsed !== requestedRoute;
+        // 自动 sticky：对需要上下文 save/restore 的 Responses 会话，强制同一个 provider.key.model。
+        // 其它协议不启用粘滞，仅显式 routing 指令才会写入 stickyTarget。
+        const providerProtocol = metadata?.providerProtocol;
+        const disableSticky = metadata &&
+            typeof metadata === 'object' &&
+            metadata.disableStickyRoutes === true;
+        const shouldAutoStickyForResponses = providerProtocol === 'openai-responses' && !disableSticky;
+        if (shouldAutoStickyForResponses) {
+            const stickyKeyForState = this.resolveStickyKey(metadata);
+            if (stickyKeyForState) {
+                const stateKey = stickyKeyForState;
+                const state = this.getRoutingInstructionState(stateKey);
+                if (!state.stickyTarget) {
+                    const providerId = this.extractProviderId(selection.providerKey);
+                    if (providerId) {
+                        const parts = selection.providerKey.split('.');
+                        const keyAlias = parts.length >= 3 ? parts[1] : undefined;
+                        const modelId = target.modelId;
+                        state.stickyTarget = {
+                            provider: providerId,
+                            keyAlias,
+                            model: modelId,
+                            // pathLength=3 表示 provider.key.model 形式，对应 alias 显式 sticky；
+                            // 若缺少别名或模型，则退化为更短 pathLength。
+                            pathLength: keyAlias && modelId ? 3 : keyAlias ? 2 : 1
+                        };
+                    }
+                }
+            }
+        }
         return {
             target,
             decision: {
@@ -132,6 +186,24 @@ export class VirtualRouterEngine {
         handleProviderFailureImpl(event, this.healthManager, this.providerHealthConfig(), (key, ttl) => this.markProviderCooldown(key, ttl));
     }
     handleProviderError(event) {
+        if (this.healthStore && typeof this.healthStore.recordProviderError === 'function') {
+            try {
+                this.healthStore.recordProviderError(event);
+            }
+            catch {
+                // ignore persistence errors
+            }
+        }
+        // 配额恢复事件优先处理：一旦识别到 virtualRouterQuotaRecovery，
+        // 直接清理健康状态/冷却 TTL，避免继续走常规错误映射逻辑。
+        const handledByQuota = applyQuotaRecoveryImpl(event, this.healthManager, (key) => this.clearProviderCooldown(key), this.debug);
+        if (handledByQuota) {
+            return;
+        }
+        const handledByQuotaDepleted = applyQuotaDepletedImpl(event, this.healthManager, (key, ttl) => this.markProviderCooldown(key, ttl), this.debug);
+        if (handledByQuotaDepleted) {
+            return;
+        }
         applySeriesCooldownImpl(event, this.providerRegistry, this.healthManager, (key, ttl) => this.markProviderCooldown(key, ttl), this.debug);
         const derived = mapProviderErrorImpl(event, this.providerHealthConfig());
         if (!derived) {
@@ -262,7 +334,9 @@ export class VirtualRouterEngine {
                 disabledModels: new Map(),
                 stopMessageText: undefined,
                 stopMessageMaxRepeats: undefined,
-                stopMessageUsed: undefined
+                stopMessageUsed: undefined,
+                stopMessageUpdatedAt: undefined,
+                stopMessageLastUsedAt: undefined
             };
         }
         this.routingInstructionState.set(key, initial);
@@ -763,17 +837,28 @@ export class VirtualRouterEngine {
         const noDisabledProviders = state.disabledProviders.size === 0;
         const noDisabledKeys = state.disabledKeys.size === 0;
         const noDisabledModels = state.disabledModels.size === 0;
-        return noForced && noSticky && noAllowed && noDisabledProviders && noDisabledKeys && noDisabledModels;
+        const noStopMessage = (!state.stopMessageText || !state.stopMessageText.trim()) &&
+            (typeof state.stopMessageMaxRepeats !== 'number' || !Number.isFinite(state.stopMessageMaxRepeats)) &&
+            (typeof state.stopMessageUsed !== 'number' || !Number.isFinite(state.stopMessageUsed)) &&
+            (typeof state.stopMessageUpdatedAt !== 'number' || !Number.isFinite(state.stopMessageUpdatedAt)) &&
+            (typeof state.stopMessageLastUsedAt !== 'number' || !Number.isFinite(state.stopMessageLastUsedAt));
+        return (noForced &&
+            noSticky &&
+            noAllowed &&
+            noDisabledProviders &&
+            noDisabledKeys &&
+            noDisabledModels &&
+            noStopMessage);
     }
     persistRoutingInstructionState(key, state) {
         if (!key || (!key.startsWith('session:') && !key.startsWith('conversation:'))) {
             return;
         }
         if (this.isRoutingStateEmpty(state)) {
-            saveRoutingInstructionStateAsync(key, null);
+            this.routingStateStore.saveAsync(key, null);
             return;
         }
-        saveRoutingInstructionStateAsync(key, state);
+        this.routingStateStore.saveAsync(key, state);
     }
     markProviderCooldown(providerKey, cooldownMs) {
         if (!providerKey) {
@@ -784,6 +869,15 @@ export class VirtualRouterEngine {
             return;
         }
         this.providerCooldowns.set(providerKey, Date.now() + ttl);
+        this.persistHealthSnapshot();
+    }
+    clearProviderCooldown(providerKey) {
+        if (!providerKey) {
+            return;
+        }
+        if (this.providerCooldowns.delete(providerKey)) {
+            this.persistHealthSnapshot();
+        }
     }
     isProviderCoolingDown(providerKey) {
         if (!providerKey) {
@@ -799,4 +893,88 @@ export class VirtualRouterEngine {
         }
         return true;
     }
+    restoreHealthFromStore() {
+        if (!this.healthStore || typeof this.healthStore.loadInitialSnapshot !== 'function') {
+            return;
+        }
+        let snapshot = null;
+        try {
+            snapshot = this.healthStore.loadInitialSnapshot();
+        }
+        catch {
+            snapshot = null;
+        }
+        if (!snapshot) {
+            return;
+        }
+        const now = Date.now();
+        const providerKeys = new Set();
+        for (const pools of Object.values(this.routing)) {
+            for (const pool of pools) {
+                for (const key of pool.targets) {
+                    if (typeof key === 'string' && key) {
+                        providerKeys.add(key);
+                    }
+                }
+            }
+        }
+        const byKey = new Map();
+        for (const entry of snapshot.cooldowns || []) {
+            if (!entry || !entry.providerKey) {
+                continue;
+            }
+            if (!providerKeys.has(entry.providerKey)) {
+                continue;
+            }
+            if (!Number.isFinite(entry.cooldownExpiresAt) || entry.cooldownExpiresAt <= now) {
+                continue;
+            }
+            byKey.set(entry.providerKey, entry);
+            this.providerCooldowns.set(entry.providerKey, entry.cooldownExpiresAt);
+        }
+        for (const state of snapshot.providers || []) {
+            if (!state || !state.providerKey) {
+                continue;
+            }
+            if (!providerKeys.has(state.providerKey)) {
+                continue;
+            }
+            if (state.cooldownExpiresAt && state.cooldownExpiresAt > now) {
+                const ttl = state.cooldownExpiresAt - now;
+                if (ttl > 0) {
+                    this.healthManager.tripProvider(state.providerKey, state.reason, ttl);
+                    if (!byKey.has(state.providerKey)) {
+                        this.providerCooldowns.set(state.providerKey, state.cooldownExpiresAt);
+                    }
+                }
+            }
+        }
+    }
+    buildHealthSnapshot() {
+        const providers = this.healthManager.getSnapshot();
+        const cooldowns = [];
+        const now = Date.now();
+        for (const [providerKey, expiry] of this.providerCooldowns.entries()) {
+            if (!expiry || expiry <= now) {
+                continue;
+            }
+            cooldowns.push({
+                providerKey,
+                cooldownExpiresAt: expiry
+            });
+        }
+        return { providers, cooldowns };
+    }
+    persistHealthSnapshot() {
+        if (!this.healthStore || typeof this.healthStore.persistSnapshot !== 'function') {
+            return;
+        }
+        try {
+            const snapshot = this.buildHealthSnapshot();
+            this.healthStore.persistSnapshot(snapshot);
+        }
+        catch {
+            // 持久化失败不影响路由主流程
+        }
+    }
 }

package/dist/router/virtual-router/routing-instructions.d.ts

@@ -31,6 +31,8 @@ export interface RoutingInstructionState {
     stopMessageText?: string;
     stopMessageMaxRepeats?: number;
     stopMessageUsed?: number;
+    stopMessageUpdatedAt?: number;
+    stopMessageLastUsedAt?: number;
 }
 export declare function parseRoutingInstructions(messages: StandardizedMessage[]): RoutingInstruction[];
 export declare function applyRoutingInstructions(instructions: RoutingInstruction[], currentState: RoutingInstructionState): RoutingInstructionState;

package/dist/router/virtual-router/routing-instructions.js

@@ -275,7 +275,9 @@ export function applyRoutingInstructions(instructions, currentState) {
         disabledModels: new Map(Array.from(currentState.disabledModels.entries()).map(([k, v]) => [k, new Set(v)])),
         stopMessageText: currentState.stopMessageText,
         stopMessageMaxRepeats: currentState.stopMessageMaxRepeats,
-        stopMessageUsed: currentState.stopMessageUsed
+        stopMessageUsed: currentState.stopMessageUsed,
+        stopMessageUpdatedAt: currentState.stopMessageUpdatedAt,
+        stopMessageLastUsedAt: currentState.stopMessageLastUsedAt
     };
     let allowReset = false;
     let disableReset = false;
@@ -399,6 +401,8 @@ export function applyRoutingInstructions(instructions, currentState) {
                     newState.stopMessageText = text;
                     newState.stopMessageMaxRepeats = maxRepeats;
                     newState.stopMessageUsed = 0;
+                    newState.stopMessageUpdatedAt = Date.now();
+                    newState.stopMessageLastUsedAt = undefined;
                 }
                 break;
             }
@@ -406,6 +410,8 @@ export function applyRoutingInstructions(instructions, currentState) {
                 newState.stopMessageText = undefined;
                 newState.stopMessageMaxRepeats = undefined;
                 newState.stopMessageUsed = undefined;
+                newState.stopMessageUpdatedAt = undefined;
+                newState.stopMessageLastUsedAt = undefined;
                 break;
         }
     }
@@ -455,6 +461,12 @@ export function serializeRoutingInstructionState(state) {
             : {}),
         ...(typeof state.stopMessageUsed === 'number' && Number.isFinite(state.stopMessageUsed)
             ? { stopMessageUsed: state.stopMessageUsed }
+            : {}),
+        ...(typeof state.stopMessageUpdatedAt === 'number' && Number.isFinite(state.stopMessageUpdatedAt)
+            ? { stopMessageUpdatedAt: state.stopMessageUpdatedAt }
+            : {}),
+        ...(typeof state.stopMessageLastUsedAt === 'number' && Number.isFinite(state.stopMessageLastUsedAt)
+            ? { stopMessageLastUsedAt: state.stopMessageLastUsedAt }
             : {})
     };
 }
@@ -505,5 +517,11 @@ export function deserializeRoutingInstructionState(data) {
     if (typeof data.stopMessageUsed === 'number' && Number.isFinite(data.stopMessageUsed)) {
         state.stopMessageUsed = Math.max(0, Math.floor(data.stopMessageUsed));
     }
+    if (typeof data.stopMessageUpdatedAt === 'number' && Number.isFinite(data.stopMessageUpdatedAt)) {
+        state.stopMessageUpdatedAt = data.stopMessageUpdatedAt;
+    }
+    if (typeof data.stopMessageLastUsedAt === 'number' && Number.isFinite(data.stopMessageLastUsedAt)) {
+        state.stopMessageLastUsedAt = data.stopMessageLastUsedAt;
+    }
     return state;
 }

package/dist/router/virtual-router/tool-signals.d.ts

@@ -1,5 +1,5 @@
 import type { StandardizedMessage, StandardizedRequest } from '../../conversion/hub/types/standardized.js';
-export type ToolCategory = 'read' | 'write' | 'search' | 'other';
+export type ToolCategory = 'read' | 'write' | 'search' | 'websearch' | 'other';
 export type ToolClassification = {
     category: ToolCategory;
     name: string;
@@ -10,4 +10,5 @@ export declare function detectCodingTool(request: StandardizedRequest): boolean;
 export declare function detectWebTool(request: StandardizedRequest): boolean;
 export declare function extractMeaningfulDeclaredToolNames(tools: StandardizedRequest['tools'] | undefined): string[];
 export declare function detectLastAssistantToolCategory(messages: StandardizedMessage[]): ToolClassification | undefined;
+export declare function classifyToolCallForReport(call: StandardizedMessage['tool_calls'][number]): ToolClassification | undefined;
 export declare function canonicalizeToolName(rawName: string): string;