@x12i/ai-providers-router 4.7.0 → 4.7.6

package/README.md

@@ -308,6 +308,21 @@ Router uses its own request/response types:
 * `AIStreamEvent` (streaming output) - includes reasoning streaming events
 * `AIBatchResponse` (batch output)
 
+### Authoritative trace diagnostics (stable contract)
+
+For downstream orchestration, `AIResponse` includes stable, provider-agnostic diagnostics:
+
+- `response.usage?: { promptTokens; completionTokens; totalTokens }`
+- `response.metadata` (keys when known):
+  - `metadata.provider`: final provider used for the successful call (or last attempt)
+  - `metadata.modelUsed`: the actual model that served the response
+  - `metadata.maxTokensRequested`: final effective generation cap applied (if determinable)
+  - `metadata.costUsd`: normalized USD cost (if computable)
+  - `metadata.requestIds`: `{ routerRequestId, providerRequestId?, openrouterRequestId? }`
+  - `metadata.timing`: `{ startedAt, endedAt, durationMs }` (provider-call timing)
+  - `metadata.latencyMs`: alias for `metadata.timing.durationMs`
+  - `metadata.attempts[]`: ordered attempts across retries + fallbacks (authoritative execution trace)
+
 ```ts
 import type { AIRouterRequest, AIResponse } from '@x12i/ai-providers-router';
 

package/dist/router/Router.js

@@ -90,28 +90,182 @@ export class AIRouter {
      */
     async runSync(input) {
         const requestId = input.requestId ?? newId();
-        const providerName = this.resolveProviderName(input);
-        const provider = this.providers.get(providerName);
-        const adapter = this.adapters.get(providerName);
-        // Check capabilities
-        if (!provider.capabilities.modes.sync) {
-            throw new Error(`Provider '${providerName}' does not support sync mode`);
+        const primaryProviderName = this.resolveProviderName(input);
+        const fallbackProvidersRaw = input.request?.config?.fallbackProviders;
+        const fallbackProviders = Array.isArray(fallbackProvidersRaw)
+            ? fallbackProvidersRaw.filter((p) => typeof p === 'string' && p.trim().length > 0).map((p) => p.trim())
+            : [];
+        // Candidates are ordered: primary, then fallbacks.
+        const providerCandidates = [primaryProviderName, ...fallbackProviders.filter((p) => p !== primaryProviderName)];
+        const maxRetries = Math.max(0, Math.min(10, Number(input.exec?.retries ?? 0) || 0));
+        const attempts = [];
+        const normalizeUsage = (usage) => {
+            if (!usage || typeof usage !== 'object')
+                return undefined;
+            const promptTokens = (typeof usage.promptTokens === 'number' ? usage.promptTokens : undefined) ??
+                (typeof usage.inputTokens === 'number' ? usage.inputTokens : undefined) ??
+                (typeof usage.prompt_tokens === 'number' ? usage.prompt_tokens : undefined) ??
+                (typeof usage.input_tokens === 'number' ? usage.input_tokens : undefined);
+            const completionTokens = (typeof usage.completionTokens === 'number' ? usage.completionTokens : undefined) ??
+                (typeof usage.outputTokens === 'number' ? usage.outputTokens : undefined) ??
+                (typeof usage.completion_tokens === 'number' ? usage.completion_tokens : undefined) ??
+                (typeof usage.output_tokens === 'number' ? usage.output_tokens : undefined);
+            const totalTokens = (typeof usage.totalTokens === 'number' ? usage.totalTokens : undefined) ??
+                (typeof usage.total_tokens === 'number' ? usage.total_tokens : undefined);
+            if (promptTokens === undefined && completionTokens === undefined && totalTokens === undefined)
+                return undefined;
+            const p = promptTokens ?? 0;
+            const c = completionTokens ?? 0;
+            return { promptTokens: p, completionTokens: c, totalTokens: totalTokens ?? p + c };
+        };
+        const extractMaxTokensRequested = (spec) => {
+            const args = spec?.args;
+            if (!args || typeof args !== 'object')
+                return undefined;
+            const v = (typeof args.max_output_tokens === 'number' ? args.max_output_tokens : undefined) ??
+                (typeof args.max_tokens === 'number' ? args.max_tokens : undefined) ??
+                (typeof args.maxTokens === 'number' ? args.maxTokens : undefined);
+            return typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+        };
+        const summarizeError = (err) => {
+            const e = err instanceof Error ? err : new Error(String(err));
+            const name = typeof e.name === 'string' ? e.name : 'Error';
+            const message = typeof e.message === 'string' ? e.message : String(err);
+            // Size cap to avoid shipping huge provider payloads.
+            const capped = message.length > 500 ? message.slice(0, 500) : message;
+            return { name, message: capped };
+        };
+        const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+        const isRetryableError = (err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            const name = err instanceof Error ? err.name : '';
+            const combined = `${name} ${msg}`.toLowerCase();
+            return (combined.includes('timeout') ||
+                combined.includes('timed out') ||
+                combined.includes('rate limit') ||
+                combined.includes('429') ||
+                combined.includes('econnreset') ||
+                combined.includes('etimedout') ||
+                combined.includes('503') ||
+                combined.includes('502') ||
+                combined.includes('504') ||
+                combined.includes('temporarily unavailable'));
+        };
+        const backoffMs = (retryIndex) => {
+            const base = 250 * Math.pow(2, Math.max(0, retryIndex));
+            const jitter = Math.floor(Math.random() * 100);
+            return Math.min(5000, base + jitter);
+        };
+        let lastError = undefined;
+        for (let fallbackIndex = 0; fallbackIndex < providerCandidates.length; fallbackIndex++) {
+            const providerName = providerCandidates[fallbackIndex];
+            const provider = this.providers.get(providerName);
+            const adapter = this.adapters.get(providerName);
+            // Check capabilities
+            if (!provider.capabilities.modes.sync) {
+                throw new Error(`Provider '${providerName}' does not support sync mode`);
+            }
+            // Build call spec (once per provider candidate; retries reuse the same spec)
+            const spec = await adapter.buildCallSpec({
+                requestId,
+                mode: 'sync',
+                request: input.request,
+                exec: input.exec,
+            });
+            const maxTokensRequested = extractMaxTokensRequested(spec);
+            const requestedModel = spec?.args?.model ?? input.request?.config?.model ?? input.request?.model;
+            for (let retryIndex = 0; retryIndex <= maxRetries; retryIndex++) {
+                const startedAt = Date.now();
+                try {
+                    const execResult = await provider.execute(spec);
+                    const endedAt = Date.now();
+                    const parsed = adapter.parseResponse({
+                        requestId,
+                        request: { ...input.request, _callSpec: spec }, // Include call spec for adapter access
+                        execResult,
+                    });
+                    const usage = normalizeUsage(parsed.usage);
+                    const modelUsed = parsed.metadata?.modelUsed ||
+                        parsed.metadata?.model ||
+                        parsed.rawResponse?.model ||
+                        (typeof requestedModel === 'string' ? requestedModel : undefined);
+                    const providerRequestId = parsed.metadata?.providerRequestId ||
+                        parsed.metadata?.id ||
+                        parsed.rawResponse?.id;
+                    const openrouterRequestId = providerName === 'openrouter' ? providerRequestId : undefined;
+                    const timing = { startedAt, endedAt, durationMs: endedAt - startedAt };
+                    const attempt = {
+                        ok: true,
+                        routing: {
+                            provider: providerName,
+                            retryIndex,
+                            fallbackIndex,
+                            requestIds: {
+                                routerRequestId: requestId,
+                                providerRequestId: providerRequestId ? String(providerRequestId) : undefined,
+                                openrouterRequestId: openrouterRequestId ? String(openrouterRequestId) : undefined,
+                            },
+                        },
+                        timing,
+                        usage,
+                        maxTokensRequested,
+                        modelUsed,
+                        costUsd: typeof parsed.metadata?.costUsd === 'number' ? parsed.metadata.costUsd : undefined,
+                    };
+                    attempts.push(attempt);
+                    const mergedMetadata = {
+                        ...(parsed.metadata || {}),
+                        provider: providerName,
+                        modelUsed,
+                        maxTokensRequested,
+                        costUsd: attempt.costUsd,
+                        requestIds: {
+                            ...parsed.metadata?.requestIds,
+                            routerRequestId: requestId,
+                            providerRequestId: providerRequestId ? String(providerRequestId) : undefined,
+                            openrouterRequestId: openrouterRequestId ? String(openrouterRequestId) : undefined,
+                        },
+                        timing,
+                        latencyMs: timing.durationMs,
+                        attempts,
+                    };
+                    return {
+                        ...parsed,
+                        requestId,
+                        provider: parsed.provider || providerName,
+                        usage,
+                        metadata: mergedMetadata,
+                    };
+                }
+                catch (err) {
+                    const endedAt = Date.now();
+                    lastError = err;
+                    attempts.push({
+                        ok: false,
+                        routing: {
+                            provider: providerName,
+                            retryIndex,
+                            fallbackIndex,
+                            requestIds: { routerRequestId: requestId },
+                        },
+                        timing: { startedAt, endedAt, durationMs: endedAt - startedAt },
+                        maxTokensRequested,
+                        modelUsed: typeof requestedModel === 'string' ? requestedModel : undefined,
+                        error: summarizeError(err),
+                    });
+                    const shouldRetry = retryIndex < maxRetries && isRetryableError(err);
+                    if (shouldRetry) {
+                        await sleep(backoffMs(retryIndex));
+                        continue;
+                    }
+                    break;
+                }
+            }
         }
-        // Build call spec
-        const spec = await adapter.buildCallSpec({
-            requestId,
-            mode: 'sync',
-            request: input.request,
-            exec: input.exec,
-        });
-        // Execute
-        const execResult = await provider.execute(spec);
-        // Parse response
-        return adapter.parseResponse({
-            requestId,
-            request: { ...input.request, _callSpec: spec }, // Include call spec for adapter access
-            execResult,
-        });
+        // Fallback chain exhausted
+        const error = lastError instanceof Error ? lastError : new Error(String(lastError ?? 'Unknown error'));
+        error.attempts = attempts;
+        throw error;
     }
     /**
      * Execute a streaming request

package/dist/router/RouterTypes.d.ts

@@ -3,6 +3,61 @@
  * These are the public API of the router
  */
 export type RouterMode = 'sync' | 'stream' | 'batch';
+export type NormalizedUsage = {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+};
+export type AttemptTiming = {
+    startedAt: number;
+    endedAt: number;
+    durationMs: number;
+};
+export type AttemptErrorSummary = {
+    name: string;
+    message: string;
+};
+export type AttemptRouting = {
+    provider: string;
+    region?: string;
+    requestIds?: Record<string, string | undefined>;
+    retryIndex: number;
+    fallbackIndex: number;
+};
+export type AttemptTrace = {
+    timing?: AttemptTiming;
+    routing: AttemptRouting;
+    usage?: NormalizedUsage;
+    maxTokensRequested?: number;
+    modelUsed?: string;
+    costUsd?: number;
+    ok: boolean;
+    error?: AttemptErrorSummary;
+};
+export type DiagnosticsMetadata = {
+    /** Final provider used for the successful call (or last attempt). */
+    provider?: string;
+    region?: string;
+    /** The actual model that served the response (may differ after normalization/routing). */
+    modelUsed?: string;
+    costUsd?: number;
+    maxTokensRequested?: number;
+    /** Stable correlation ids across router/provider proxies. */
+    requestIds?: Record<string, string | undefined>;
+    /** Provider-call timing for the successful call (or last attempt). */
+    timing?: AttemptTiming;
+    /** Provider-call latency in ms (alias for timing.durationMs). */
+    latencyMs?: number;
+    /** Ordered attempt trace across retries + fallbacks. */
+    attempts?: AttemptTrace[];
+    /** Optional normalization details (size-capped by caller). */
+    normalization?: {
+        normalizedConfig?: Record<string, unknown>;
+        warnings?: string[];
+    };
+    /** Allow additional vendor/provider specific keys. */
+    [key: string]: unknown;
+};
 /**
  * Router configuration
  */
@@ -56,7 +111,7 @@ export interface AIResponse {
     provider: string;
     rawResponse: unknown;
     outputText?: string;
-    usage?: any;
+    usage?: NormalizedUsage;
     reasoning: {
         requested: {
             effort: string;
@@ -85,7 +140,7 @@ export interface AIResponse {
         };
         warnings?: any[];
     };
-    metadata?: any;
+    metadata?: DiagnosticsMetadata;
 }
 /**
  * Router stream events

package/dist/router/RouterWrapper.js

@@ -224,43 +224,11 @@ export class LLMProviderRouter {
             duration: invokeDuration,
             usage: result.usage,
         });
-        // #region agent log
-        const logDataC = { location: 'RouterWrapper.ts:224', message: 'Before response interceptors', data: { hasMetadata: !!result.metadata, metadataKeys: result.metadata ? Object.keys(result.metadata) : [], hasAiActivitiesResponse: !!result.metadata?.['ai-activities-response'], hasAiActivitiesRequest: !!result.metadata?.['ai-activities-request'], interceptorsCount: this.responseInterceptors.length }, timestamp: Date.now(), sessionId: 'debug-session', runId: 'run1', hypothesisId: 'C' };
-        console.log('[DEBUG]', logDataC);
-        fetch('http://127.0.0.1:7243/ingest/0d4596d8-b8fa-4ca1-a4f4-2e6f23baa429', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(logDataC) }).catch(() => { });
-        // #endregion
         // Apply response interceptors
         let processedResponse = result;
-        for (let i = 0; i < this.responseInterceptors.length; i++) {
-            const interceptor = this.responseInterceptors[i];
-            const beforeInterceptor = {
-                hasMetadata: !!processedResponse.metadata,
-                metadataKeys: processedResponse.metadata ? Object.keys(processedResponse.metadata) : [],
-                hasAiActivitiesResponse: !!processedResponse.metadata?.['ai-activities-response'],
-                hasAiActivitiesRequest: !!processedResponse.metadata?.['ai-activities-request'],
-            };
+        for (const interceptor of this.responseInterceptors) {
             processedResponse = await interceptor(processedResponse, result.provider);
-            const afterInterceptor = {
-                hasMetadata: !!processedResponse.metadata,
-                metadataKeys: processedResponse.metadata ? Object.keys(processedResponse.metadata) : [],
-                hasAiActivitiesResponse: !!processedResponse.metadata?.['ai-activities-response'],
-                hasAiActivitiesRequest: !!processedResponse.metadata?.['ai-activities-request'],
-            };
-            // #region agent log
-            const interceptorLog = { location: `RouterWrapper.ts:231:interceptor_${i}`, message: `Interceptor ${i} execution`, data: { before: beforeInterceptor, after: afterInterceptor, changed: JSON.stringify(beforeInterceptor) !== JSON.stringify(afterInterceptor) }, timestamp: Date.now(), sessionId: 'debug-session', runId: 'run1', hypothesisId: `INTERCEPTOR_${i}` };
-            console.log(`[DEBUG RouterWrapper] Interceptor ${i} - Before:`, JSON.stringify(beforeInterceptor, null, 2));
-            console.log(`[DEBUG RouterWrapper] Interceptor ${i} - After:`, JSON.stringify(afterInterceptor, null, 2));
-            if (JSON.stringify(beforeInterceptor) !== JSON.stringify(afterInterceptor)) {
-                console.warn(`[WARNING RouterWrapper] Interceptor ${i} modified ai-activities metadata!`);
-            }
-            fetch('http://127.0.0.1:7243/ingest/0d4596d8-b8fa-4ca1-a4f4-2e6f23baa429', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(interceptorLog) }).catch(() => { });
-            // #endregion
         }
-        // #region agent log
-        const logDataD = { location: 'RouterWrapper.ts:230', message: 'After response interceptors', data: { hasMetadata: !!processedResponse.metadata, metadataKeys: processedResponse.metadata ? Object.keys(processedResponse.metadata) : [], hasAiActivitiesResponse: !!processedResponse.metadata?.['ai-activities-response'], hasAiActivitiesRequest: !!processedResponse.metadata?.['ai-activities-request'], responseChanged: processedResponse !== result }, timestamp: Date.now(), sessionId: 'debug-session', runId: 'run1', hypothesisId: 'D' };
-        console.log('[DEBUG]', logDataD);
-        fetch('http://127.0.0.1:7243/ingest/0d4596d8-b8fa-4ca1-a4f4-2e6f23baa429', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(logDataD) }).catch(() => { });
-        // #endregion
         // Record usage
         if (this.config.usageTracker) {
             const duration = Date.now() - startTime;
@@ -269,192 +237,14 @@ export class LLMProviderRouter {
                 timestamp: Date.now(),
                 duration,
                 tokens: {
-                    input: result.usage?.inputTokens || 0,
-                    output: result.usage?.outputTokens || 0,
+                    input: result.usage?.promptTokens || 0,
+                    output: result.usage?.completionTokens || 0,
                     total: result.usage?.totalTokens || 0,
                 },
-                cost: result.usage?.cost,
+                cost: result.metadata?.costUsd,
                 success: true,
             });
         }
-        // #region agent log
-        const logDataE = { location: 'RouterWrapper.ts:246', message: 'Returning final response from invoke', data: { hasMetadata: !!processedResponse.metadata, metadataKeys: processedResponse.metadata ? Object.keys(processedResponse.metadata) : [], hasAiActivitiesResponse: !!processedResponse.metadata?.['ai-activities-response'], hasAiActivitiesRequest: !!processedResponse.metadata?.['ai-activities-request'], finalResponseKeys: Object.keys(processedResponse) }, timestamp: Date.now(), sessionId: 'debug-session', runId: 'run1', hypothesisId: 'E' };
-        console.log('[DEBUG RouterWrapper] Final response metadata keys:', processedResponse.metadata ? Object.keys(processedResponse.metadata) : 'NO METADATA');
-        console.log('[DEBUG RouterWrapper] ai-activities keys in final response:', processedResponse.metadata ? Object.keys(processedResponse.metadata).filter(k => k.startsWith('ai-activities')) : []);
-        console.log('[DEBUG RouterWrapper] Full log data:', JSON.stringify(logDataE, null, 2));
-        fetch('http://127.0.0.1:7243/ingest/0d4596d8-b8fa-4ca1-a4f4-2e6f23baa429', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(logDataE) }).catch(() => { });
-        // Test serialization to verify metadata survives JSON.stringify/parse
-        let serializationTest = null;
-        let serializationError = null;
-        try {
-            const serialized = JSON.stringify(processedResponse);
-            const deserialized = JSON.parse(serialized);
-            serializationTest = {
-                success: true,
-                hasMetadataAfterSerialize: !!deserialized.metadata,
-                metadataKeysAfterSerialize: deserialized.metadata ? Object.keys(deserialized.metadata) : [],
-                hasAiActivitiesResponseAfterSerialize: !!deserialized.metadata?.['ai-activities-response'],
-                hasAiActivitiesRequestAfterSerialize: !!deserialized.metadata?.['ai-activities-request'],
-                aiActivitiesKeysAfterSerialize: deserialized.metadata ? Object.keys(deserialized.metadata).filter((k) => k.startsWith('ai-activities')) : [],
-            };
-        }
-        catch (err) {
-            serializationError = err.message || String(err);
-            serializationTest = { success: false, error: serializationError };
-        }
-        const logDataF = { location: 'RouterWrapper.ts:280', message: 'Serialization test of final response', data: serializationTest, timestamp: Date.now(), sessionId: 'debug-session', runId: 'run1', hypothesisId: 'F' };
-        console.log('[DEBUG RouterWrapper] Serialization test:', JSON.stringify(serializationTest, null, 2));
-        fetch('http://127.0.0.1:7243/ingest/0d4596d8-b8fa-4ca1-a4f4-2e6f23baa429', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(logDataF) }).catch(() => { });
-        // Detailed inspection of ai-activities data structure
-        const aiActivitiesInspection = {
-            hasAiActivitiesResponse: !!processedResponse.metadata?.['ai-activities-response'],
-            hasAiActivitiesRequest: !!processedResponse.metadata?.['ai-activities-request'],
-            aiActivitiesResponseType: typeof processedResponse.metadata?.['ai-activities-response'],
-            aiActivitiesRequestType: typeof processedResponse.metadata?.['ai-activities-request'],
-        };
-        if (processedResponse.metadata?.['ai-activities-response']) {
-            const resp = processedResponse.metadata['ai-activities-response'];
-            aiActivitiesInspection.aiActivitiesResponseKeys = Object.keys(resp);
-            aiActivitiesInspection.hasRequestId = !!resp.requestId;
-            aiActivitiesInspection.hasProvider = !!resp.provider;
-            aiActivitiesInspection.hasRawResponse = !!resp.rawResponse;
-            aiActivitiesInspection.hasOutputText = !!resp.outputText;
-            aiActivitiesInspection.hasUsage = !!resp.usage;
-            aiActivitiesInspection.hasReasoning = !!resp.reasoning;
-            aiActivitiesInspection.outputTextLength = resp.outputText?.length || 0;
-            aiActivitiesInspection.outputTextPreview = resp.outputText?.substring(0, 100) || null;
-        }
-        if (processedResponse.metadata?.['ai-activities-request']) {
-            const req = processedResponse.metadata['ai-activities-request'];
-            aiActivitiesInspection.aiActivitiesRequestKeys = Object.keys(req);
-            aiActivitiesInspection.requestHasInstructions = !!req.instructions;
-            aiActivitiesInspection.requestHasInputData = !!req.inputData;
-            aiActivitiesInspection.requestHasConfig = !!req.config;
-            aiActivitiesInspection.requestHasCallSpec = !!req._callSpec;
-        }
-        // Test if we can serialize just the ai-activities data
-        let aiActivitiesSerializationTest = null;
-        try {
-            const aiActivitiesOnly = {
-                'ai-activities-response': processedResponse.metadata?.['ai-activities-response'],
-                'ai-activities-request': processedResponse.metadata?.['ai-activities-request'],
-                'ai-activities-raw-response': processedResponse.metadata?.['ai-activities-raw-response'],
-                'ai-activities-original-response': processedResponse.metadata?.['ai-activities-original-response'],
-                'ai-activities-exec-meta': processedResponse.metadata?.['ai-activities-exec-meta'],
-            };
-            const serialized = JSON.stringify(aiActivitiesOnly);
-            const deserialized = JSON.parse(serialized);
-            aiActivitiesSerializationTest = {
-                success: true,
-                serializedSize: serialized.length,
-                hasResponseAfterSerialize: !!deserialized['ai-activities-response'],
-                hasRequestAfterSerialize: !!deserialized['ai-activities-request'],
-                responseKeysAfterSerialize: deserialized['ai-activities-response'] ? Object.keys(deserialized['ai-activities-response']) : [],
-            };
-        }
-        catch (err) {
-            aiActivitiesSerializationTest = { success: false, error: err.message || String(err) };
-        }
-        const logDataG = { location: 'RouterWrapper.ts:320', message: 'Detailed ai-activities inspection', data: { inspection: aiActivitiesInspection, serializationTest: aiActivitiesSerializationTest }, timestamp: Date.now(), sessionId: 'debug-session', runId: 'run1', hypothesisId: 'G' };
-        console.log('[DEBUG RouterWrapper] ai-activities inspection:', JSON.stringify(aiActivitiesInspection, null, 2));
-        console.log('[DEBUG RouterWrapper] ai-activities serialization test:', JSON.stringify(aiActivitiesSerializationTest, null, 2));
-        fetch('http://127.0.0.1:7243/ingest/0d4596d8-b8fa-4ca1-a4f4-2e6f23baa429', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(logDataG) }).catch(() => { });
-        // Summary: Print complete response structure for downstream system debugging
-        console.log('\n=== ROUTER RESPONSE SUMMARY (for downstream system) ===');
-        console.log('Response has metadata:', !!processedResponse.metadata);
-        console.log('Metadata keys:', processedResponse.metadata ? Object.keys(processedResponse.metadata) : 'NONE');
-        console.log('ai-activities keys:', processedResponse.metadata ? Object.keys(processedResponse.metadata).filter(k => k.startsWith('ai-activities')) : []);
-        console.log('Access path: response.metadata["ai-activities-response"]');
-        console.log('Access path: response.metadata["ai-activities-request"]');
-        if (processedResponse.metadata?.['ai-activities-response']) {
-            const resp = processedResponse.metadata['ai-activities-response'];
-            console.log('ai-activities-response structure:', {
-                hasRequestId: !!resp.requestId,
-                hasProvider: !!resp.provider,
-                hasRawResponse: !!resp.rawResponse,
-                hasOutputText: !!resp.outputText,
-                hasUsage: !!resp.usage,
-                hasReasoning: !!resp.reasoning,
-                outputTextPreview: resp.outputText?.substring(0, 50) || 'NONE',
-            });
-        }
-        console.log('=== END ROUTER RESPONSE SUMMARY ===\n');
-        // Final verification: Test accessing ai-activities data as downstream system would
-        try {
-            const testAccess = {
-                'ai-activities-response': processedResponse.metadata?.['ai-activities-response'],
-                'ai-activities-request': processedResponse.metadata?.['ai-activities-request'],
-                'ai-activities-raw-response': processedResponse.metadata?.['ai-activities-raw-response'],
-                'ai-activities-original-response': processedResponse.metadata?.['ai-activities-original-response'],
-                'ai-activities-exec-meta': processedResponse.metadata?.['ai-activities-exec-meta'],
-            };
-            const canAccess = {
-                responseExists: !!testAccess['ai-activities-response'],
-                requestExists: !!testAccess['ai-activities-request'],
-                responseHasData: testAccess['ai-activities-response'] ? Object.keys(testAccess['ai-activities-response']).length > 0 : false,
-                requestHasData: testAccess['ai-activities-request'] ? Object.keys(testAccess['ai-activities-request']).length > 0 : false,
-            };
-            console.log('[VERIFICATION] Downstream access test:', JSON.stringify(canAccess, null, 2));
-            console.log('[VERIFICATION] Example access code:');
-            console.log('  const response = await router.invoke(request);');
-            console.log('  const activitiesResponse = response.metadata["ai-activities-response"];');
-            console.log('  const activitiesRequest = response.metadata["ai-activities-request"];');
-            console.log('  // Save to database: activitiesResponse, activitiesRequest');
-            if (!canAccess.responseExists || !canAccess.requestExists) {
-                console.error('[ERROR] ai-activities data is missing! This will cause database saves to fail.');
-            }
-        }
-        catch (err) {
-            console.error('[ERROR] Failed to verify ai-activities access:', err.message);
-        }
-        // Final safeguard: Ensure metadata is never lost
-        if (!processedResponse.metadata) {
-            console.error('[CRITICAL ERROR] Response has no metadata! Creating empty metadata object.');
-            processedResponse.metadata = {};
-        }
-        // Final safeguard: Ensure ai-activities data exists, log warning if missing
-        if (!processedResponse.metadata['ai-activities-response'] || !processedResponse.metadata['ai-activities-request']) {
-            console.warn('[WARNING] ai-activities data is missing from final response!');
-            console.warn('[WARNING] This will cause database saves to fail.');
-            console.warn('[WARNING] Metadata keys present:', Object.keys(processedResponse.metadata));
-        }
-        else {
-            console.log('[SUCCESS] ai-activities data confirmed present in final response');
-        }
-        // Final log: Complete response structure snapshot
-        const finalSnapshot = {
-            timestamp: new Date().toISOString(),
-            hasMetadata: !!processedResponse.metadata,
-            metadataKeys: processedResponse.metadata ? Object.keys(processedResponse.metadata) : [],
-            aiActivitiesKeys: processedResponse.metadata ? Object.keys(processedResponse.metadata).filter(k => k.startsWith('ai-activities')) : [],
-            hasAiActivitiesResponse: !!processedResponse.metadata?.['ai-activities-response'],
-            hasAiActivitiesRequest: !!processedResponse.metadata?.['ai-activities-request'],
-            responseKeys: Object.keys(processedResponse),
-        };
-        console.log('[FINAL SNAPSHOT] Response structure before return:', JSON.stringify(finalSnapshot, null, 2));
-        // Add helper property for easier access (non-enumerable to avoid breaking serialization)
-        // This makes it easier for downstream systems to find the data
-        if (processedResponse.metadata?.['ai-activities-response'] && processedResponse.metadata?.['ai-activities-request']) {
-            try {
-                Object.defineProperty(processedResponse, '_aiActivities', {
-                    value: {
-                        response: processedResponse.metadata['ai-activities-response'],
-                        request: processedResponse.metadata['ai-activities-request'],
-                        rawResponse: processedResponse.metadata['ai-activities-raw-response'],
-                        originalResponse: processedResponse.metadata['ai-activities-original-response'],
-                        execMeta: processedResponse.metadata['ai-activities-exec-meta'],
-                    },
-                    enumerable: false, // Don't include in JSON.stringify
-                    writable: false,
-                    configurable: true,
-                });
-                console.log('[HELPER] Added _aiActivities helper property (access via response._aiActivities)');
-            }
-            catch (err) {
-                console.warn('[WARNING] Could not add _aiActivities helper property:', err.message);
-            }
-        }
-        // #endregion
         return processedResponse;
     }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/ai-providers-router",
-  "version": "4.7.0",
+  "version": "4.7.6",
   "description": "Unified router for all LLM provider implementations",
   "type": "module",
   "main": "dist/index.js",
@@ -45,7 +45,7 @@
     "@x12i/ai-provider-grok": "^3.2.0",
     "@x12i/ai-provider-interface": "^3.2.1",
     "@x12i/ai-provider-openai": "^3.2.1",
-    "@x12i/logxer": "^4.3.5",
+    "@x12i/logxer": "^4.3.6",
     "ai-io-normalizer": "^6.0.3"
   },
   "devDependencies": {