@jsonstudio/llms 0.6.203 → 0.6.215

package/dist/conversion/codecs/gemini-openai-codec.js

@@ -4,6 +4,7 @@ import { normalizeChatMessageContent } from '../shared/chat-output-normalizer.js
 import { mapBridgeToolsToChat } from '../shared/tool-mapping.js';
 import { prepareGeminiToolsForBridge } from '../shared/gemini-tool-utils.js';
 import { registerResponsesReasoning, consumeResponsesReasoning, registerResponsesOutputTextMeta, consumeResponsesOutputTextMeta, consumeResponsesPayloadSnapshot, registerResponsesPayloadSnapshot, consumeResponsesPassthrough, registerResponsesPassthrough } from '../shared/responses-reasoning-registry.js';
+const DUMMY_THOUGHT_SIGNATURE = 'skip_thought_signature_validator';
 function isObject(v) {
     return !!v && typeof v === 'object' && !Array.isArray(v);
 }
@@ -54,6 +55,32 @@ function mapChatRoleToGemini(role) {
         return 'tool';
     return 'user';
 }
+function coerceThoughtSignature(value) {
+    if (typeof value === 'string' && value.trim().length) {
+        return value.trim();
+    }
+    return undefined;
+}
+function extractThoughtSignatureFromToolCall(tc) {
+    if (!tc || typeof tc !== 'object') {
+        return undefined;
+    }
+    const direct = coerceThoughtSignature(tc.thought_signature ?? tc.thoughtSignature);
+    if (direct) {
+        return direct;
+    }
+    const extraContent = tc.extra_content ?? tc.extraContent;
+    if (extraContent && typeof extraContent === 'object') {
+        const googleNode = extraContent.google ?? extraContent.Google;
+        if (googleNode && typeof googleNode === 'object') {
+            const googleSig = coerceThoughtSignature(googleNode.thought_signature ?? googleNode.thoughtSignature);
+            if (googleSig) {
+                return googleSig;
+            }
+        }
+    }
+    return undefined;
+}
 export function buildOpenAIChatFromGeminiRequest(payload) {
     const messages = [];
     // systemInstruction → Chat system 消息
@@ -195,11 +222,21 @@ export function buildOpenAIChatFromGeminiResponse(payload) {
             else {
                 argsStr = safeJson(argsRaw);
             }
-            toolCalls.push({
+            const thoughtSignature = coerceThoughtSignature(pObj.thoughtSignature);
+            const toolCall = {
                 id,
                 type: 'function',
                 function: { name, arguments: argsStr }
-            });
+            };
+            if (thoughtSignature) {
+                toolCall.thought_signature = thoughtSignature;
+                toolCall.extra_content = {
+                    google: {
+                        thought_signature: thoughtSignature
+                    }
+                };
+            }
+            toolCalls.push(toolCall);
             continue;
         }
     }
@@ -398,7 +435,12 @@ export function buildGeminiFromOpenAIChat(chatResp) {
         const id = typeof tc.id === 'string' ? String(tc.id) : undefined;
         if (id)
             functionCall.id = id;
-        parts.push({ functionCall });
+        const thoughtSignature = extractThoughtSignatureFromToolCall(tc) ?? DUMMY_THOUGHT_SIGNATURE;
+        const partEntry = { functionCall };
+        if (thoughtSignature) {
+            partEntry.thoughtSignature = thoughtSignature;
+        }
+        parts.push(partEntry);
     }
     const candidate = {
         content: {

package/dist/conversion/hub/pipeline/hub-pipeline.js

@@ -11,6 +11,7 @@ import { GeminiSemanticMapper } from '../semantic-mappers/gemini-mapper.js';
 import { ChatFormatAdapter } from '../format-adapters/chat-format-adapter.js';
 import { ChatSemanticMapper } from '../semantic-mappers/chat-mapper.js';
 import { createSnapshotRecorder } from '../snapshot-recorder.js';
+import { shouldRecordSnapshots } from '../../shared/snapshot-utils.js';
 import { runReqInboundStage1FormatParse } from './stages/req_inbound/req_inbound_stage1_format_parse/index.js';
 import { runReqInboundStage2SemanticMap } from './stages/req_inbound/req_inbound_stage2_semantic_map/index.js';
 import { runChatContextCapture, captureResponsesContextSnapshot } from './stages/req_inbound/req_inbound_stage3_context_capture/index.js';
@@ -348,8 +349,7 @@ export class HubPipeline {
         return adapterContext;
     }
     maybeCreateStageRecorder(context, endpoint) {
-        const flag = (process.env.ROUTECODEX_HUB_SNAPSHOTS || '').trim();
-        if (flag === '0') {
+        if (!shouldRecordSnapshots()) {
             return undefined;
         }
         const effectiveEndpoint = endpoint || context.entryEndpoint || '/v1/chat/completions';

package/dist/conversion/hub/semantic-mappers/gemini-mapper.js

@@ -17,6 +17,31 @@ const GENERATION_CONFIG_KEYS = [
 ];
 const PASSTHROUGH_METADATA_PREFIX = 'rcc_passthrough_';
 const PASSTHROUGH_PARAMETERS = ['tool_choice'];
+const DUMMY_THOUGHT_SIGNATURE = 'skip_thought_signature_validator';
+function coerceThoughtSignature(value) {
+    if (typeof value === 'string' && value.trim().length) {
+        return value.trim();
+    }
+    return undefined;
+}
+function extractThoughtSignatureFromToolCall(tc) {
+    if (!tc || typeof tc !== 'object') {
+        return undefined;
+    }
+    const node = tc;
+    const direct = coerceThoughtSignature(node.thought_signature ?? node.thoughtSignature);
+    if (direct) {
+        return direct;
+    }
+    const extra = node.extra_content ?? node.extraContent;
+    if (extra && typeof extra === 'object') {
+        const googleNode = extra.google ?? extra.Google;
+        if (googleNode && typeof googleNode === 'object') {
+            return coerceThoughtSignature(googleNode.thought_signature ?? googleNode.thoughtSignature);
+        }
+    }
+    return undefined;
+}
 function normalizeToolOutputs(messages, missing) {
     const outputs = [];
     messages.forEach((msg, index) => {
@@ -35,6 +60,37 @@ function normalizeToolOutputs(messages, missing) {
     });
     return outputs.length ? outputs : undefined;
 }
+function synthesizeToolOutputsFromMessages(messages) {
+    if (!Array.isArray(messages)) {
+        return [];
+    }
+    const outputs = [];
+    for (const message of messages) {
+        if (!message || typeof message !== 'object')
+            continue;
+        if (message.role !== 'assistant')
+            continue;
+        const toolCalls = Array.isArray(message.tool_calls)
+            ? message.tool_calls
+            : [];
+        for (const call of toolCalls) {
+            const callId = typeof call.id === 'string' ? call.id : undefined;
+            if (!callId) {
+                continue;
+            }
+            const existing = outputs.find((entry) => entry.tool_call_id === callId);
+            if (existing) {
+                continue;
+            }
+            outputs.push({
+                tool_call_id: callId,
+                content: '',
+                name: (call.function && call.function.name) || undefined
+            });
+        }
+    }
+    return outputs;
+}
 function normalizeToolContent(value) {
     if (typeof value === 'string')
         return value;
@@ -47,6 +103,30 @@ function normalizeToolContent(value) {
         return String(value ?? '');
     }
 }
+function convertToolMessageToOutput(message) {
+    const rawId = (message.tool_call_id ?? message.id);
+    const callId = typeof rawId === 'string' && rawId.trim().length ? rawId.trim() : undefined;
+    if (!callId) {
+        return null;
+    }
+    return {
+        tool_call_id: callId,
+        content: normalizeToolContent(message.content),
+        name: typeof message.name === 'string' ? message.name : undefined
+    };
+}
+function buildFunctionResponseEntry(output) {
+    const parsedPayload = safeParseJson(output.content);
+    const normalizedPayload = ensureFunctionResponsePayload(cloneAsJsonValue(parsedPayload));
+    const part = {
+        functionResponse: {
+            name: output.name || 'tool',
+            id: output.tool_call_id,
+            response: normalizedPayload
+        }
+    };
+    return { role: 'user', parts: [part] };
+}
 function collectSystemSegments(systemInstruction) {
     if (!systemInstruction)
         return [];
@@ -93,13 +173,20 @@ function collectParameters(payload) {
 }
 function buildGeminiRequestFromChat(chat, metadata) {
     const contents = [];
+    const emittedToolOutputs = new Set();
     for (const message of chat.messages) {
         if (!message || typeof message !== 'object')
             continue;
         if (message.role === 'system')
             continue;
-        if (message.role === 'tool')
+        if (message.role === 'tool') {
+            const toolOutput = convertToolMessageToOutput(message);
+            if (toolOutput) {
+                contents.push(buildFunctionResponseEntry(toolOutput));
+                emittedToolOutputs.add(toolOutput.tool_call_id);
+            }
             continue;
+        }
         const entry = {
             role: mapChatRoleToGemini(message.role),
             parts: []
@@ -131,24 +218,36 @@ function buildGeminiRequestFromChat(chat, metadata) {
             if (typeof tc.id === 'string') {
                 part.functionCall.id = tc.id;
             }
+            const thoughtSignature = extractThoughtSignatureFromToolCall(tc) ?? DUMMY_THOUGHT_SIGNATURE;
+            if (thoughtSignature) {
+                part.thoughtSignature = thoughtSignature;
+            }
             entry.parts.push(part);
         }
         if (entry.parts.length) {
             contents.push(entry);
         }
     }
+    const toolOutputMap = new Map();
     if (Array.isArray(chat.toolOutputs)) {
-        for (const output of chat.toolOutputs) {
-            const response = cloneAsJsonValue(safeParseJson(output.content));
-            const part = {
-                functionResponse: {
-                    name: output.name || 'tool',
-                    id: output.tool_call_id,
-                    response
-                }
-            };
-            contents.push({ role: 'user', parts: [part] });
+        for (const entry of chat.toolOutputs) {
+            if (entry && typeof entry.tool_call_id === 'string' && entry.tool_call_id.trim().length) {
+                toolOutputMap.set(entry.tool_call_id.trim(), entry);
+            }
+        }
+    }
+    if (toolOutputMap.size === 0) {
+        const syntheticOutputs = synthesizeToolOutputsFromMessages(chat.messages);
+        for (const output of syntheticOutputs) {
+            toolOutputMap.set(output.tool_call_id, output);
+        }
+    }
+    for (const output of toolOutputMap.values()) {
+        if (emittedToolOutputs.has(output.tool_call_id)) {
+            continue;
         }
+        contents.push(buildFunctionResponseEntry(output));
+        emittedToolOutputs.add(output.tool_call_id);
     }
     const request = {
         model: chat.parameters?.model || 'models/gemini-pro',
@@ -235,6 +334,14 @@ function safeParseJson(value) {
         return value;
     }
 }
+function ensureFunctionResponsePayload(value) {
+    if (value && typeof value === 'object') {
+        return value;
+    }
+    return {
+        result: value === undefined ? null : value
+    };
+}
 function cloneAsJsonValue(value) {
     try {
         return JSON.parse(JSON.stringify(value ?? null));

package/dist/conversion/shared/snapshot-utils.js

@@ -1,35 +1,25 @@
-import os from 'node:os';
-import path from 'node:path';
-import fs from 'node:fs/promises';
 import { writeSnapshotViaHooks } from './snapshot-hooks.js';
-const SNAPSHOT_BASE = path.join(os.homedir(), '.routecodex', 'golden_samples');
-function mapEndpointToFolder(endpoint, hint) {
-    if (hint)
-        return hint;
-    const ep = String(endpoint || '').toLowerCase();
-    if (ep.includes('/responses'))
-        return 'openai-responses';
-    if (ep.includes('/messages'))
-        return 'anthropic-messages';
-    if (ep.includes('/gemini'))
-        return 'gemini-chat';
-    return 'openai-chat';
-}
-async function ensureDir(dir) {
-    try {
-        await fs.mkdir(dir, { recursive: true });
+function resolveBoolFromEnv(value, fallback) {
+    if (!value) {
+        return fallback;
     }
-    catch {
-        // ignore fs errors
+    const normalized = value.trim().toLowerCase();
+    if (['1', 'true', 'yes', 'on'].includes(normalized)) {
+        return true;
     }
-}
-function sanitize(value) {
-    return value.replace(/[^\w.-]/g, '_');
+    if (['0', 'false', 'no', 'off'].includes(normalized)) {
+        return false;
+    }
+    return fallback;
 }
 export function shouldRecordSnapshots() {
-    const flag = process.env.ROUTECODEX_HUB_SNAPSHOTS;
-    if (flag && flag.trim() === '0') {
-        return false;
+    const hubFlag = process.env.ROUTECODEX_HUB_SNAPSHOTS;
+    if (hubFlag && hubFlag.trim().length) {
+        return resolveBoolFromEnv(hubFlag, true);
+    }
+    const sharedFlag = process.env.ROUTECODEX_SNAPSHOT ?? process.env.ROUTECODEX_SNAPSHOTS;
+    if (sharedFlag && sharedFlag.trim().length) {
+        return resolveBoolFromEnv(sharedFlag, true);
     }
     return true;
 }
@@ -37,26 +27,6 @@ export async function recordSnapshot(options) {
     if (!shouldRecordSnapshots())
         return;
     const endpoint = options.endpoint || '/v1/chat/completions';
-    const folder = mapEndpointToFolder(endpoint, options.folderHint);
-    const dir = path.join(SNAPSHOT_BASE, folder);
-    try {
-        await ensureDir(dir);
-        const safeStage = sanitize(options.stage);
-        const safeRequestId = sanitize(options.requestId);
-        const file = path.join(dir, `${safeRequestId}_${safeStage}.json`);
-        const payload = {
-            meta: {
-                stage: options.stage,
-                timestamp: Date.now(),
-                endpoint
-            },
-            body: options.data
-        };
-        await fs.writeFile(file, JSON.stringify(payload, null, 2), 'utf-8');
-    }
-    catch (error) {
-        console.warn('[snapshot-utils] failed to write snapshot', error);
-    }
     void writeSnapshotViaHooks({
         endpoint,
         stage: options.stage,

package/dist/index.d.ts

@@ -7,4 +7,5 @@
 export * from './conversion/index.js';
 export * from './router/virtual-router/bootstrap.js';
 export * from './router/virtual-router/types.js';
+export * from './telemetry/stats-center.js';
 export declare const VERSION = "0.4.0";

package/dist/index.js

@@ -7,4 +7,5 @@
 export * from './conversion/index.js';
 export * from './router/virtual-router/bootstrap.js';
 export * from './router/virtual-router/types.js';
+export * from './telemetry/stats-center.js';
 export const VERSION = '0.4.0';

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

@@ -11,6 +11,7 @@ export declare class VirtualRouterEngine {
     private routeStats;
     private readonly debug;
     private healthConfig;
+    private readonly statsCenter;
     initialize(config: VirtualRouterConfig): void;
     route(request: StandardizedRequest | ProcessedRequest, metadata: RouterMetadataInput): {
         target: TargetMetadata;

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

@@ -5,6 +5,7 @@ import { RoutingClassifier } from './classifier.js';
 import { buildRoutingFeatures } from './features.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();
@@ -16,6 +17,7 @@ export class VirtualRouterEngine {
     routeStats = new Map();
     debug = console; // thin hook; host may monkey-patch for colored logging
     healthConfig = null;
+    statsCenter = getStatsCenter();
     initialize(config) {
         this.validateConfig(config);
         this.routing = config.routing;
@@ -40,6 +42,20 @@ export class VirtualRouterEngine {
         const target = this.providerRegistry.buildTarget(selection.providerKey);
         this.healthManager.recordSuccess(selection.providerKey);
         this.incrementRouteStat(selection.routeUsed, selection.providerKey);
+        try {
+            this.statsCenter.recordVirtualRouterHit({
+                requestId: metadata.requestId,
+                timestamp: Date.now(),
+                entryEndpoint: metadata.entryEndpoint || '/v1/chat/completions',
+                routeName: selection.routeUsed,
+                pool: 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.providerKey, target.modelId || '', hitReason);
         if (formatted) {

package/dist/telemetry/stats-center.d.ts

@@ -0,0 +1,73 @@
+export interface VirtualRouterHitEvent {
+    requestId: string;
+    timestamp: number;
+    entryEndpoint: string;
+    routeName: string;
+    pool: string;
+    providerKey: string;
+    runtimeKey?: string;
+    providerType?: string;
+    modelId?: string;
+}
+export interface ProviderUsageEvent {
+    requestId: string;
+    timestamp: number;
+    providerKey: string;
+    runtimeKey?: string;
+    providerType: string;
+    modelId?: string;
+    routeName?: string;
+    entryEndpoint?: string;
+    success: boolean;
+    latencyMs: number;
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+}
+export interface RouterStatsBucket {
+    requestCount: number;
+    poolHitCount: Record<string, number>;
+    routeHitCount: Record<string, number>;
+    providerHitCount: Record<string, number>;
+}
+export interface RouterStatsSnapshot {
+    global: RouterStatsBucket;
+    byEntryEndpoint: Record<string, RouterStatsBucket>;
+}
+export interface ProviderStatsBucket {
+    requestCount: number;
+    successCount: number;
+    errorCount: number;
+    latencySumMs: number;
+    minLatencyMs: number;
+    maxLatencyMs: number;
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+export interface ProviderStatsSnapshot {
+    global: ProviderStatsBucket;
+    byProviderKey: Record<string, ProviderStatsBucket>;
+    byRoute: Record<string, ProviderStatsBucket>;
+    byEntryEndpoint: Record<string, ProviderStatsBucket>;
+}
+export interface StatsSnapshot {
+    router: RouterStatsSnapshot;
+    providers: ProviderStatsSnapshot;
+}
+export interface StatsCenterOptions {
+    enable?: boolean;
+    autoPrintOnExit?: boolean;
+    persistPath?: string | null;
+}
+export interface StatsCenter {
+    recordVirtualRouterHit(ev: VirtualRouterHitEvent): void;
+    recordProviderUsage(ev: ProviderUsageEvent): void;
+    getSnapshot(): StatsSnapshot;
+    flushToDisk(): Promise<void>;
+    reset(): void;
+}
+export declare function initStatsCenter(options?: StatsCenterOptions): StatsCenter;
+export declare function getStatsCenter(): StatsCenter;

package/dist/telemetry/stats-center.js

@@ -0,0 +1,280 @@
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+function createEmptyRouterBucket() {
+    return {
+        requestCount: 0,
+        poolHitCount: {},
+        routeHitCount: {},
+        providerHitCount: {}
+    };
+}
+function createEmptyProviderBucket() {
+    return {
+        requestCount: 0,
+        successCount: 0,
+        errorCount: 0,
+        latencySumMs: 0,
+        minLatencyMs: Number.POSITIVE_INFINITY,
+        maxLatencyMs: 0,
+        usage: {
+            promptTokens: 0,
+            completionTokens: 0,
+            totalTokens: 0
+        }
+    };
+}
+function createEmptySnapshot() {
+    return {
+        router: {
+            global: createEmptyRouterBucket(),
+            byEntryEndpoint: {}
+        },
+        providers: {
+            global: createEmptyProviderBucket(),
+            byProviderKey: {},
+            byRoute: {},
+            byEntryEndpoint: {}
+        }
+    };
+}
+class NoopStatsCenter {
+    recordVirtualRouterHit() { }
+    recordProviderUsage() { }
+    getSnapshot() { return createEmptySnapshot(); }
+    async flushToDisk() { }
+    reset() { }
+}
+class DefaultStatsCenter {
+    snapshot = createEmptySnapshot();
+    dirty = false;
+    flushInFlight = false;
+    persistPath;
+    constructor(persistPath) {
+        if (persistPath === null) {
+            this.persistPath = null;
+        }
+        else if (typeof persistPath === 'string' && persistPath.trim().length) {
+            this.persistPath = persistPath.trim();
+        }
+        else {
+            const base = path.join(os.homedir(), '.routecodex', 'stats');
+            this.persistPath = path.join(base, 'stats.json');
+        }
+    }
+    recordVirtualRouterHit(ev) {
+        if (!ev || !ev.routeName || !ev.providerKey) {
+            return;
+        }
+        const snap = this.snapshot;
+        this.applyRouterHitToBucket(snap.router.global, ev);
+        const entryKey = ev.entryEndpoint || 'unknown';
+        if (!snap.router.byEntryEndpoint[entryKey]) {
+            snap.router.byEntryEndpoint[entryKey] = createEmptyRouterBucket();
+        }
+        this.applyRouterHitToBucket(snap.router.byEntryEndpoint[entryKey], ev);
+        this.dirty = true;
+    }
+    recordProviderUsage(ev) {
+        if (!ev || !ev.providerKey || !ev.providerType) {
+            return;
+        }
+        const snap = this.snapshot;
+        this.applyProviderUsageToBucket(snap.providers.global, ev);
+        const providerKey = ev.providerKey;
+        if (!snap.providers.byProviderKey[providerKey]) {
+            snap.providers.byProviderKey[providerKey] = createEmptyProviderBucket();
+        }
+        this.applyProviderUsageToBucket(snap.providers.byProviderKey[providerKey], ev);
+        const routeKey = ev.routeName || 'unknown';
+        if (!snap.providers.byRoute[routeKey]) {
+            snap.providers.byRoute[routeKey] = createEmptyProviderBucket();
+        }
+        this.applyProviderUsageToBucket(snap.providers.byRoute[routeKey], ev);
+        const entryKey = ev.entryEndpoint || 'unknown';
+        if (!snap.providers.byEntryEndpoint[entryKey]) {
+            snap.providers.byEntryEndpoint[entryKey] = createEmptyProviderBucket();
+        }
+        this.applyProviderUsageToBucket(snap.providers.byEntryEndpoint[entryKey], ev);
+        this.dirty = true;
+    }
+    getSnapshot() {
+        return this.snapshot;
+    }
+    reset() {
+        this.snapshot = createEmptySnapshot();
+        this.dirty = false;
+    }
+    async flushToDisk() {
+        if (!this.persistPath || !this.dirty || this.flushInFlight) {
+            return;
+        }
+        this.flushInFlight = true;
+        try {
+            const dir = path.dirname(this.persistPath);
+            await fs.mkdir(dir, { recursive: true });
+            const payload = JSON.stringify(this.snapshot, null, 2);
+            await fs.writeFile(this.persistPath, payload, 'utf-8');
+            this.dirty = false;
+        }
+        catch {
+            // ignore persistence errors
+        }
+        finally {
+            this.flushInFlight = false;
+        }
+    }
+    applyRouterHitToBucket(bucket, ev) {
+        bucket.requestCount += 1;
+        if (ev.pool) {
+            bucket.poolHitCount[ev.pool] = (bucket.poolHitCount[ev.pool] || 0) + 1;
+        }
+        if (ev.routeName) {
+            bucket.routeHitCount[ev.routeName] = (bucket.routeHitCount[ev.routeName] || 0) + 1;
+        }
+        if (ev.providerKey) {
+            bucket.providerHitCount[ev.providerKey] = (bucket.providerHitCount[ev.providerKey] || 0) + 1;
+        }
+    }
+    applyProviderUsageToBucket(bucket, ev) {
+        bucket.requestCount += 1;
+        if (ev.success) {
+            bucket.successCount += 1;
+        }
+        else {
+            bucket.errorCount += 1;
+        }
+        if (Number.isFinite(ev.latencyMs) && ev.latencyMs >= 0) {
+            bucket.latencySumMs += ev.latencyMs;
+            if (ev.latencyMs < bucket.minLatencyMs) {
+                bucket.minLatencyMs = ev.latencyMs;
+            }
+            if (ev.latencyMs > bucket.maxLatencyMs) {
+                bucket.maxLatencyMs = ev.latencyMs;
+            }
+        }
+        if (typeof ev.promptTokens === 'number' && Number.isFinite(ev.promptTokens)) {
+            bucket.usage.promptTokens += Math.max(0, ev.promptTokens);
+        }
+        if (typeof ev.completionTokens === 'number' && Number.isFinite(ev.completionTokens)) {
+            bucket.usage.completionTokens += Math.max(0, ev.completionTokens);
+        }
+        if (typeof ev.totalTokens === 'number' && Number.isFinite(ev.totalTokens)) {
+            bucket.usage.totalTokens += Math.max(0, ev.totalTokens);
+        }
+        else {
+            const derivedTotal = (typeof ev.promptTokens === 'number' ? Math.max(0, ev.promptTokens) : 0) +
+                (typeof ev.completionTokens === 'number' ? Math.max(0, ev.completionTokens) : 0);
+            bucket.usage.totalTokens += derivedTotal;
+        }
+    }
+}
+let instance = null;
+function resolveEnableFlag(defaultValue) {
+    const raw = process.env.ROUTECODEX_STATS;
+    if (!raw)
+        return defaultValue;
+    const normalized = raw.trim().toLowerCase();
+    if (['1', 'true', 'yes', 'on'].includes(normalized))
+        return true;
+    if (['0', 'false', 'no', 'off'].includes(normalized))
+        return false;
+    return defaultValue;
+}
+function printStatsToConsole(snapshot) {
+    const router = snapshot.router;
+    const providers = snapshot.providers;
+    const totalRequests = router.global.requestCount;
+    const poolEntries = Object.entries(router.global.poolHitCount);
+    const providerEntries = Object.entries(router.global.providerHitCount);
+    // Router summary
+    // eslint-disable-next-line no-console
+    console.log('[stats] Virtual Router:');
+    // eslint-disable-next-line no-console
+    console.log(`  total requests: ${totalRequests}`);
+    if (poolEntries.length) {
+        // eslint-disable-next-line no-console
+        console.log('  pools:');
+        for (const [pool, count] of poolEntries) {
+            const ratio = totalRequests > 0 ? (count / totalRequests) * 100 : 0;
+            // eslint-disable-next-line no-console
+            console.log(`    ${pool}: ${count} (${ratio.toFixed(2)}%)`);
+        }
+    }
+    if (providerEntries.length) {
+        // eslint-disable-next-line no-console
+        console.log('  top providers:');
+        const sorted = providerEntries.sort((a, b) => b[1] - a[1]).slice(0, 5);
+        for (const [providerKey, count] of sorted) {
+            // eslint-disable-next-line no-console
+            console.log(`    ${providerKey}: ${count}`);
+        }
+    }
+    const globalProvider = providers.global;
+    const totalProviderRequests = globalProvider.requestCount;
+    const avgLatency = globalProvider.successCount > 0 ? globalProvider.latencySumMs / globalProvider.successCount : 0;
+    // Provider summary
+    // eslint-disable-next-line no-console
+    console.log('\n[stats] Providers:');
+    // eslint-disable-next-line no-console
+    console.log(`  total requests : ${totalProviderRequests} (success=${globalProvider.successCount}, error=${globalProvider.errorCount})`);
+    // eslint-disable-next-line no-console
+    console.log(`  avg latency    : ${avgLatency.toFixed(1)} ms`);
+    // eslint-disable-next-line no-console
+    console.log(`  total tokens   : prompt=${globalProvider.usage.promptTokens} completion=${globalProvider.usage.completionTokens} total=${globalProvider.usage.totalTokens}`);
+}
+export function initStatsCenter(options) {
+    if (instance) {
+        return instance;
+    }
+    const enabled = resolveEnableFlag(options?.enable ?? true);
+    if (!enabled) {
+        instance = new NoopStatsCenter();
+        return instance;
+    }
+    const center = new DefaultStatsCenter(options?.persistPath);
+    instance = center;
+    const autoPrint = options?.autoPrintOnExit !== false;
+    if (autoPrint && typeof process !== 'undefined' && typeof process.on === 'function') {
+        const handler = async () => {
+            try {
+                await center.flushToDisk();
+            }
+            catch {
+                // ignore
+            }
+            try {
+                const snapshot = center.getSnapshot();
+                printStatsToConsole(snapshot);
+            }
+            catch {
+                // ignore
+            }
+        };
+        try {
+            process.once('beforeExit', handler);
+        }
+        catch {
+            // ignore
+        }
+        try {
+            process.once('SIGINT', handler);
+        }
+        catch {
+            // ignore
+        }
+        try {
+            process.once('SIGTERM', handler);
+        }
+        catch {
+            // ignore
+        }
+    }
+    return instance;
+}
+export function getStatsCenter() {
+    if (!instance) {
+        return initStatsCenter();
+    }
+    return instance;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsonstudio/llms",
-  "version": "0.6.203",
+  "version": "0.6.215",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",