@x12i/ai-providers-router 4.7.7 → 4.8.2

package/README.md

@@ -317,7 +317,9 @@ For downstream orchestration, `AIResponse` includes stable, provider-agnostic di
   - `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.costUsd` / `metadata.cost`: normalized USD cost when the provider reports it (e.g. OpenRouter `usage.cost`)
+  - `metadata.costStatus`: `'priced'` when `costUsd` is set; `'unpriced'` when usage exists but no cost was returned
+  - `response.output.parsed`: structured fields when `outputContract` is on the request (markdown sections → camelCase keys)
   - `metadata.requestIds`: `{ routerRequestId, providerRequestId?, openrouterRequestId? }`
   - `metadata.timing`: `{ startedAt, endedAt, durationMs }` (provider-call timing)
   - `metadata.latencyMs`: alias for `metadata.timing.durationMs`

package/dist/adapters/openrouter/OpenRouterAdapter.js

@@ -1,4 +1,5 @@
 import { openRouterCatalog } from '../../openrouter-catalog.js';
+import { extractCostUsdFromProviderUsage } from '../../normalization/cost.js';
 import { getReasoningCapabilitiesFromRegistry, hasReasoningParamInCatalog } from './reasoning-capabilities.js';
 /**
  * Router-side adapter for OpenRouter provider
@@ -1008,8 +1009,20 @@ export class OpenRouterAdapter {
             reasoning: fullResponse.reasoning,
             // Don't include metadata in the copy to avoid circular reference
         };
+        const usageSources = [
+            rawResponse?.usage,
+            originalResponse?.usage,
+            execResult.rawMeta?.originalResponse?.usage,
+        ];
+        let costUsd;
+        for (const src of usageSources) {
+            costUsd = extractCostUsdFromProviderUsage(src);
+            if (costUsd !== undefined)
+                break;
+        }
         const metadataWithActivities = {
             ...fullResponse.metadata,
+            ...(costUsd !== undefined ? { costUsd, cost: costUsd } : {}),
             // Include full response in metadata for ai-activities storage (without circular ref)
             'ai-activities-response': fullResponseForActivities,
             // Include request for complete audit trail

package/dist/errors.d.ts

@@ -5,18 +5,19 @@ import type { ProviderId } from './types.js';
 export declare class ProviderNotFoundError extends Error {
     constructor(providerName: ProviderId | string);
 }
+export type FallbackAttempt = {
+    provider: ProviderId | string;
+    model?: string;
+    httpStatus?: number;
+    error: Error;
+    responsePreview?: string;
+};
 /**
  * Error thrown when all providers in the fallback chain have failed
  */
 export declare class FallbackExhaustedError extends Error {
-    attempts: Array<{
-        provider: ProviderId;
-        error: Error;
-    }>;
-    constructor(attempts: Array<{
-        provider: ProviderId;
-        error: Error;
-    }>);
+    attempts: FallbackAttempt[];
+    constructor(attempts: FallbackAttempt[]);
 }
 /**
  * Error thrown when a provider package is not installed

package/dist/index.d.ts

@@ -1,9 +1,18 @@
 export { LLMProviderRouter } from './router.js';
-export type { RouterConfig, HealthCheckResult, ProviderId, AIRouterRequest, AIResponse, AIStreamEvent, AIBatchResponse, AIBatchRequestItem, } from './router.js';
+export type { RouterConfig, HealthCheckResult, ProviderId, AIRouterRequest, AIResponse, AIStreamEvent, AIBatchResponse, AIBatchRequestItem, NormalizedRouterOutput, ProviderModelRef, } from './router.js';
 export { createRouter, createRouterFromConfig } from './factory.js';
 export type { CreateRouterConfig } from './factory.js';
 export { ProviderNotFoundError, FallbackExhaustedError, ProviderNotInstalledError, ProviderTimeoutError } from './errors.js';
+export type { FallbackAttempt } from './errors.js';
+export type { PartialRouterPayload } from './router/partialErrorPayload.js';
 export type { RequestInterceptor, ResponseInterceptor } from './interceptors.js';
 export type { UsageTracker, AdapterLoader, ProviderInit } from './types.js';
 export { Logger, getLogger, createLogger } from './logger.js';
 export type { LogLevel, LoggerConfig } from './logger.js';
+export { AIGateway } from './gateway.js';
+export type { EnhancedLLMResponse } from './gateway.js';
+export { applyResponseNormalization } from './normalization/applyResponseNormalization.js';
+export { resolveCostReporting, extractCostUsdFromRouterResponse, extractCostUsdFromProviderUsage, hasNonZeroTokenUsage } from './normalization/cost.js';
+export type { ActivityCostStatus, ResolvedCostReporting } from './normalization/cost.js';
+export { resolveOutputContractFieldKeys, enrichParsedForOutputContract, contractSpecToFieldKeys } from './normalization/outputContract.js';
+export { parseMarkdownSectionsFromContent } from './normalization/markdownSections.js';

package/dist/index.js

@@ -40,3 +40,10 @@ export { createRouter, createRouterFromConfig } from './factory.js';
 export { ProviderNotFoundError, FallbackExhaustedError, ProviderNotInstalledError, ProviderTimeoutError } from './errors.js';
 // Logger
 export { Logger, getLogger, createLogger } from './logger.js';
+// Gateway (thin invoke wrapper)
+export { AIGateway } from './gateway.js';
+// Response normalization (Run Analysis G6/G8)
+export { applyResponseNormalization } from './normalization/applyResponseNormalization.js';
+export { resolveCostReporting, extractCostUsdFromRouterResponse, extractCostUsdFromProviderUsage, hasNonZeroTokenUsage } from './normalization/cost.js';
+export { resolveOutputContractFieldKeys, enrichParsedForOutputContract, contractSpecToFieldKeys } from './normalization/outputContract.js';
+export { parseMarkdownSectionsFromContent } from './normalization/markdownSections.js';

package/dist/normalization/applyResponseNormalization.d.ts

@@ -0,0 +1,5 @@
+import type { AIResponse, AIRouterRequest } from '../router/RouterTypes.js';
+/**
+ * Canonical post-parse normalization: cost reporting (G8) and output contract → parsed (G6/G9).
+ */
+export declare function applyResponseNormalization(response: AIResponse, requestContext?: AIRouterRequest['request']): AIResponse;

package/dist/normalization/applyResponseNormalization.js

@@ -0,0 +1,36 @@
+import { extractCostUsdFromRouterResponse, resolveCostReporting } from './cost.js';
+import { enrichParsedForOutputContract, resolveOutputContractFieldKeys } from './outputContract.js';
+/**
+ * Canonical post-parse normalization: cost reporting (G8) and output contract → parsed (G6/G9).
+ */
+export function applyResponseNormalization(response, requestContext) {
+    const costUsd = extractCostUsdFromRouterResponse({
+        metadata: response.metadata,
+        rawResponse: response.rawResponse,
+        costUsd: response.metadata?.costUsd,
+        cost: response.metadata?.cost
+    });
+    const costReporting = resolveCostReporting(response.usage, costUsd);
+    const contractKeys = resolveOutputContractFieldKeys(requestContext);
+    const rawText = response.outputText ?? '';
+    const existingParsed = response.output?.parsed ??
+        response.metadata?.parsedContent ??
+        (rawText.trim() ? { rawText } : {});
+    const parsed = enrichParsedForOutputContract(existingParsed, rawText, contractKeys);
+    const metadata = {
+        ...(response.metadata || {}),
+        ...(costReporting.costUsd !== undefined ? { costUsd: costReporting.costUsd, cost: costReporting.costUsd } : {}),
+        ...(costReporting.costStatus ? { costStatus: costReporting.costStatus } : {})
+    };
+    if (contractKeys?.length && Object.keys(parsed).length > 0) {
+        metadata.parsedContent = parsed;
+    }
+    const output = {
+        parsed: contractKeys?.length ? parsed : (response.output?.parsed ?? parsed)
+    };
+    return {
+        ...response,
+        metadata,
+        output
+    };
+}

package/dist/normalization/cost.d.ts

@@ -0,0 +1,23 @@
+import type { NormalizedUsage } from '../router/RouterTypes.js';
+/** Activity billing state when token usage is recorded (Run Analysis G8). */
+export type ActivityCostStatus = 'priced' | 'unpriced';
+export type ResolvedCostReporting = {
+    costUsd?: number;
+    costStatus?: ActivityCostStatus;
+};
+/** Extract USD cost from a provider usage object (e.g. OpenRouter `usage.cost`). */
+export declare function extractCostUsdFromProviderUsage(usage: unknown): number | undefined;
+/**
+ * Best-effort USD cost from router response: metadata, attempts, rawResponse.usage.
+ */
+export declare function extractCostUsdFromRouterResponse(routerResponse: {
+    metadata?: Record<string, unknown>;
+    rawResponse?: unknown;
+    costUsd?: unknown;
+    cost?: unknown;
+}): number | undefined;
+export declare function hasNonZeroTokenUsage(usage?: NormalizedUsage): boolean;
+/**
+ * When usage exists, never leave cost unexplained: numeric cost when priced, else `costStatus: "unpriced"`.
+ */
+export declare function resolveCostReporting(usage: NormalizedUsage | undefined, costUsd: number | undefined): ResolvedCostReporting;

package/dist/normalization/cost.js

@@ -0,0 +1,64 @@
+function firstFiniteNumber(...vals) {
+    for (const v of vals) {
+        if (typeof v === 'number' && Number.isFinite(v))
+            return v;
+    }
+    return undefined;
+}
+/** Extract USD cost from a provider usage object (e.g. OpenRouter `usage.cost`). */
+export function extractCostUsdFromProviderUsage(usage) {
+    if (usage == null || typeof usage !== 'object')
+        return undefined;
+    const u = usage;
+    return firstFiniteNumber(u.cost, u.costUsd, u.total_cost, u.totalCost);
+}
+/**
+ * Best-effort USD cost from router response: metadata, attempts, rawResponse.usage.
+ */
+export function extractCostUsdFromRouterResponse(routerResponse) {
+    const meta = routerResponse.metadata;
+    const fromMeta = firstFiniteNumber(meta?.costUsd, meta?.cost);
+    if (fromMeta !== undefined)
+        return fromMeta;
+    const fromRoot = firstFiniteNumber(routerResponse.costUsd, routerResponse.cost);
+    if (fromRoot !== undefined)
+        return fromRoot;
+    const attempts = meta?.attempts;
+    if (Array.isArray(attempts)) {
+        for (let i = attempts.length - 1; i >= 0; i--) {
+            const a = attempts[i];
+            if (a != null && typeof a === 'object') {
+                const o = a;
+                const c = firstFiniteNumber(o.costUsd, o.cost);
+                if (c !== undefined)
+                    return c;
+            }
+        }
+    }
+    const raw = routerResponse.rawResponse;
+    if (raw != null && typeof raw === 'object') {
+        const rawObj = raw;
+        const fromUsage = extractCostUsdFromProviderUsage(rawObj.usage);
+        if (fromUsage !== undefined)
+            return fromUsage;
+        return firstFiniteNumber(rawObj.cost, rawObj.costUsd);
+    }
+    return undefined;
+}
+export function hasNonZeroTokenUsage(usage) {
+    if (!usage)
+        return false;
+    return !!(usage.promptTokens || usage.completionTokens || usage.totalTokens);
+}
+/**
+ * When usage exists, never leave cost unexplained: numeric cost when priced, else `costStatus: "unpriced"`.
+ */
+export function resolveCostReporting(usage, costUsd) {
+    if (typeof costUsd === 'number' && Number.isFinite(costUsd)) {
+        return { costUsd, costStatus: 'priced' };
+    }
+    if (hasNonZeroTokenUsage(usage)) {
+        return { costStatus: 'unpriced' };
+    }
+    return {};
+}

package/dist/normalization/markdownSections.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Section-based markdown → camelCase fields (e.g. `### Short Answer` → `shortAnswer`).
+ */
+/** Parse markdown section headers into camelCase keys; returns {} when no sections found. */
+export declare function parseMarkdownSectionsFromContent(content: string): Record<string, unknown>;

package/dist/normalization/markdownSections.js

@@ -0,0 +1,78 @@
+/**
+ * Section-based markdown → camelCase fields (e.g. `### Short Answer` → `shortAnswer`).
+ */
+function parseMarkdownList(content) {
+    const listItems = [];
+    let currentItem = '';
+    let hasBulletPoints = false;
+    let hasNumberedItems = false;
+    for (const line of content) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith('- ')) {
+            hasBulletPoints = true;
+            if (currentItem)
+                listItems.push(currentItem.trim());
+            currentItem = trimmed.substring(2).trim();
+        }
+        else if (/^\d+\.\s/.test(trimmed)) {
+            hasNumberedItems = true;
+            if (currentItem)
+                listItems.push(currentItem.trim());
+            const match = trimmed.match(/^\d+\.\s(.+)$/);
+            currentItem = match ? match[1].trim() : trimmed;
+        }
+        else if (currentItem && trimmed) {
+            currentItem += ' ' + trimmed;
+        }
+        else if (!currentItem && trimmed) {
+            currentItem = trimmed;
+        }
+    }
+    if (currentItem)
+        listItems.push(currentItem.trim());
+    return listItems.length > 1 || hasBulletPoints || hasNumberedItems
+        ? listItems
+        : content.join('\n').trim();
+}
+function headerToCamelCase(header) {
+    return header
+        .toLowerCase()
+        .replace(/[^a-zA-Z0-9\s]/g, '')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .replace(/\s+(\w)/g, (_, letter) => letter.toUpperCase());
+}
+function parseMarkdownSections(content) {
+    const result = {};
+    const lines = content.split('\n');
+    let currentSection = '';
+    let currentContent = [];
+    const flush = () => {
+        if (currentSection && currentContent.length > 0) {
+            result[headerToCamelCase(currentSection)] = parseMarkdownList(currentContent);
+        }
+    };
+    for (const line of lines) {
+        const headerMatch = line.match(/^(#{1,6})\s*(.+?)\s*$/);
+        if (headerMatch) {
+            flush();
+            currentSection = headerMatch[2].trim();
+            currentContent = [];
+        }
+        else if (currentSection) {
+            currentContent.push(line);
+        }
+    }
+    flush();
+    return result;
+}
+/** Parse markdown section headers into camelCase keys; returns {} when no sections found. */
+export function parseMarkdownSectionsFromContent(content) {
+    if (!content || typeof content !== 'string' || !content.trim())
+        return {};
+    const sections = parseMarkdownSections(content);
+    const keys = Object.keys(sections);
+    if (keys.length === 1 && keys[0] === 'rawText')
+        return {};
+    return sections;
+}

package/dist/normalization/outputContract.d.ts

@@ -0,0 +1,12 @@
+export type OutputContractSpec = string[] | {
+    properties: Record<string, unknown>;
+};
+export declare function contractSpecToFieldKeys(contract: unknown): string[];
+/**
+ * Resolves field keys from explicit `outputContract` on the request or graph-forwarded inputs.
+ */
+export declare function resolveOutputContractFieldKeys(requestContext: unknown): string[] | undefined;
+/**
+ * Fills missing contract keys from markdown sections. Only runs when explicit contract keys were supplied.
+ */
+export declare function enrichParsedForOutputContract(parsed: unknown, rawContent: string, contractKeys: string[] | undefined): Record<string, unknown>;

package/dist/normalization/outputContract.js

@@ -0,0 +1,124 @@
+import { parseMarkdownSectionsFromContent } from './markdownSections.js';
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasMeaningfulContractValue(value) {
+    if (value === undefined || value === null)
+        return false;
+    if (typeof value === 'string')
+        return value.trim().length > 0;
+    if (Array.isArray(value))
+        return value.length > 0;
+    if (typeof value === 'object')
+        return Object.keys(value).length > 0;
+    return true;
+}
+export function contractSpecToFieldKeys(contract) {
+    if (contract == null)
+        return [];
+    if (Array.isArray(contract)) {
+        return contract.filter((k) => typeof k === 'string' && k.trim().length > 0);
+    }
+    if (!isPlainObject(contract))
+        return [];
+    const properties = contract.properties;
+    if (isPlainObject(properties)) {
+        return Object.keys(properties);
+    }
+    return [];
+}
+function readOutputContractFromWorkingMemory(workingMemory) {
+    if (!isPlainObject(workingMemory))
+        return undefined;
+    const inputs = workingMemory.inputs;
+    if (isPlainObject(inputs) && inputs.outputContract !== undefined) {
+        return inputs.outputContract;
+    }
+    const input = workingMemory.input;
+    if (typeof input === 'string') {
+        try {
+            const parsed = JSON.parse(input);
+            if (isPlainObject(parsed) && parsed.outputContract !== undefined) {
+                return parsed.outputContract;
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    else if (isPlainObject(input) && input.outputContract !== undefined) {
+        return input.outputContract;
+    }
+    if (workingMemory.outputContract !== undefined)
+        return workingMemory.outputContract;
+    return undefined;
+}
+/**
+ * Resolves field keys from explicit `outputContract` on the request or graph-forwarded inputs.
+ */
+export function resolveOutputContractFieldKeys(requestContext) {
+    if (requestContext == null || typeof requestContext !== 'object')
+        return undefined;
+    const r = requestContext;
+    const candidates = [
+        r.outputContract,
+        isPlainObject(r.config) ? r.config.outputContract : undefined,
+        readOutputContractFromWorkingMemory(r.workingMemory)
+    ];
+    for (const candidate of candidates) {
+        const keys = contractSpecToFieldKeys(candidate);
+        if (keys.length > 0)
+            return keys;
+    }
+    return undefined;
+}
+function asParsedRecord(parsed) {
+    if (!isPlainObject(parsed))
+        return {};
+    return { ...parsed };
+}
+function pickAliasValue(source, key) {
+    if (hasMeaningfulContractValue(source[key]))
+        return source[key];
+    const spaced = key.replace(/([A-Z])/g, ' $1').replace(/^./, (c) => c.toUpperCase());
+    const title = spaced.charAt(0).toUpperCase() + spaced.slice(1);
+    const aliases = [
+        key,
+        key.toLowerCase(),
+        title,
+        title.replace(/\s+/g, ' '),
+        key.replace(/([A-Z])/g, '_$1').toLowerCase()
+    ];
+    for (const alias of aliases) {
+        if (hasMeaningfulContractValue(source[alias]))
+            return source[alias];
+    }
+    return undefined;
+}
+/**
+ * Fills missing contract keys from markdown sections. Only runs when explicit contract keys were supplied.
+ */
+export function enrichParsedForOutputContract(parsed, rawContent, contractKeys) {
+    const base = asParsedRecord(parsed);
+    if (!contractKeys?.length)
+        return base;
+    const missing = contractKeys.filter((k) => !hasMeaningfulContractValue(base[k]));
+    if (missing.length === 0)
+        return base;
+    const content = typeof rawContent === 'string' && rawContent.trim().length > 0
+        ? rawContent
+        : typeof base.rawText === 'string'
+            ? base.rawText
+            : '';
+    if (!content.trim())
+        return base;
+    const fromMarkdown = parseMarkdownSectionsFromContent(content);
+    const merged = { ...base };
+    for (const key of missing) {
+        const value = pickAliasValue(fromMarkdown, key);
+        if (hasMeaningfulContractValue(value)) {
+            merged[key] = value;
+        }
+    }
+    return merged;
+}

package/dist/providers/OpenRouterProvider.js

@@ -4,6 +4,21 @@
  */
 import { OpenRouter } from '@openrouter/sdk';
 import { ProviderTimeoutError } from '../errors.js';
+function preservePartialResponseOnError(error) {
+    if (error == null || typeof error !== 'object')
+        return;
+    const e = error;
+    if (e.rawResponse !== undefined)
+        return;
+    const response = e.response;
+    if (response == null || typeof response !== 'object')
+        return;
+    const resp = response;
+    const body = resp.data ?? resp.body ?? resp;
+    if (body != null && typeof body === 'object') {
+        e.rawResponse = body;
+    }
+}
 /**
  * Create OpenRouter ProviderModule using @openrouter/sdk directly
  */
@@ -124,6 +139,7 @@ export function createOpenRouterProvider(config) {
                 if (timedOut && typeof timeoutMs === 'number') {
                     throw new ProviderTimeoutError('openrouter', timeoutMs, operation);
                 }
+                preservePartialResponseOnError(error);
                 throw error;
             }
             finally {
@@ -223,6 +239,7 @@ export function createOpenRouterProvider(config) {
                 if (timedOut && typeof timeoutMs === 'number') {
                     throw new ProviderTimeoutError('openrouter', timeoutMs, operation);
                 }
+                preservePartialResponseOnError(error);
                 throw error;
             }
             finally {

package/dist/router/Router.d.ts

@@ -1,6 +1,6 @@
 import type { ProviderRegistry } from '../registry/ProviderRegistry.js';
 import type { AdapterRegistry } from '../registry/AdapterRegistry.js';
-import type { AIRouterRequest, AIResponse, AIStreamEvent, AIBatchResponse, AIBatchRequestItem } from './RouterTypes.js';
+import type { AIRouterRequest, AIResponse, AIStreamEvent, AIBatchResponse, AIBatchRequestItem, RouterConfig } from './RouterTypes.js';
 /**
  * Main router class
  * Orchestrates provider execution using ProviderModules and router-side adapters
@@ -8,7 +8,12 @@ import type { AIRouterRequest, AIResponse, AIStreamEvent, AIBatchResponse, AIBat
 export declare class AIRouter {
     private providers;
     private adapters;
-    constructor(providers: ProviderRegistry, adapters: AdapterRegistry);
+    private routerConfig;
+    constructor(providers: ProviderRegistry, adapters: AdapterRegistry, routerConfig?: RouterConfig);
+    /**
+     * Resolve provider module name for a specific fallback candidate.
+     */
+    private resolveProviderNameForCandidate;
     /**
      * Resolve provider name from request, checking OpenRouter mode first
      */

package/dist/router/Router.js

@@ -1,12 +1,34 @@
 import { newId } from '../utils/ids.js';
+import { applyResponseNormalization } from '../normalization/applyResponseNormalization.js';
+import { extractCostUsdFromRouterResponse } from '../normalization/cost.js';
+import { FallbackExhaustedError } from '../errors.js';
+import { buildCandidateRequest, buildFallbackCandidates, isRetryableError, summarizeError, toError, } from './fallbackUtils.js';
+import { attachPartialRouterPayload, buildPartialRouterPayload } from './partialErrorPayload.js';
 /**
  * Main router class
  * Orchestrates provider execution using ProviderModules and router-side adapters
  */
 export class AIRouter {
-    constructor(providers, adapters) {
+    constructor(providers, adapters, routerConfig = {}) {
         this.providers = providers;
         this.adapters = adapters;
+        this.routerConfig = routerConfig;
+    }
+    /**
+     * Resolve provider module name for a specific fallback candidate.
+     */
+    resolveProviderNameForCandidate(input, candidateProvider) {
+        const candidateInput = {
+            ...input,
+            request: {
+                ...input.request,
+                config: {
+                    ...(input.request?.config ?? {}),
+                    provider: candidateProvider,
+                },
+            },
+        };
+        return this.resolveProviderName(candidateInput);
     }
     /**
      * Resolve provider name from request, checking OpenRouter mode first
@@ -91,12 +113,15 @@ export class AIRouter {
     async runSync(input) {
         const requestId = input.requestId ?? newId();
         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 requestConfig = input.request?.config;
+        const primaryModel = (typeof requestConfig?.model === 'string' ? requestConfig.model : undefined) ??
+            (typeof input.request?.model === 'string' ? input.request.model : undefined);
+        const fallbackCandidates = buildFallbackCandidates({
+            primaryProvider: primaryProviderName,
+            primaryModel,
+            requestConfig: requestConfig && typeof requestConfig === 'object' ? requestConfig : undefined,
+            routerFallbackChain: this.routerConfig.fallbackChain,
+        });
         const maxRetries = Math.max(0, Math.min(10, Number(input.exec?.retries ?? 0) || 0));
         const attempts = [];
         const normalizeUsage = (usage) => {
@@ -127,61 +152,73 @@ export class AIRouter {
                 (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 failedAttemptErrors = [];
+        let lastPartialPayload;
+        for (let fallbackIndex = 0; fallbackIndex < fallbackCandidates.length; fallbackIndex++) {
+            const candidate = fallbackCandidates[fallbackIndex];
+            const candidateInput = buildCandidateRequest(input, candidate);
+            const providerName = this.resolveProviderNameForCandidate(candidateInput, candidate.provider);
+            if (!this.providers.has(providerName)) {
+                const err = new Error(`Provider not registered: ${providerName}. Available: ${this.providers.list().join(', ')}`);
+                lastError = err;
+                failedAttemptErrors.push(err);
+                const partialPayload = buildPartialRouterPayload({
+                    requestId,
+                    engineProvider: candidate.provider,
+                    providerModule: providerName,
+                    modelUsed: candidate.model,
+                    attempts,
+                    providerError: err,
+                });
+                lastPartialPayload = partialPayload;
+                attachPartialRouterPayload(err, partialPayload);
+                attempts.push({
+                    ok: false,
+                    routing: {
+                        provider: candidate.provider,
+                        retryIndex: 0,
+                        fallbackIndex,
+                        requestIds: { routerRequestId: requestId },
+                    },
+                    modelUsed: candidate.model,
+                    error: summarizeError(err),
+                });
+                continue;
+            }
             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)
+            // Build call spec (once per fallback candidate; retries reuse the same spec)
             const spec = await adapter.buildCallSpec({
                 requestId,
                 mode: 'sync',
-                request: input.request,
+                request: candidateInput.request,
                 exec: input.exec,
             });
             const maxTokensRequested = extractMaxTokensRequested(spec);
-            const requestedModel = spec?.args?.model ?? input.request?.config?.model ?? input.request?.model;
+            const requestedModel = spec?.args?.model ??
+                candidate.model ??
+                candidateInput.request?.config?.model ??
+                candidateInput.request?.model;
             for (let retryIndex = 0; retryIndex <= maxRetries; retryIndex++) {
                 const startedAt = Date.now();
+                let execResult;
                 try {
-                    const execResult = await provider.execute(spec);
+                    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
+                        request: { ...candidateInput.request, _callSpec: spec },
                         execResult,
                     });
                     const usage = normalizeUsage(parsed.usage);
@@ -194,10 +231,14 @@ export class AIRouter {
                         parsed.rawResponse?.id;
                     const openrouterRequestId = providerName === 'openrouter' ? providerRequestId : undefined;
                     const timing = { startedAt, endedAt, durationMs: endedAt - startedAt };
+                    const resolvedCostUsd = extractCostUsdFromRouterResponse({
+                        metadata: parsed.metadata,
+                        rawResponse: parsed.rawResponse,
+                    });
                     const attempt = {
                         ok: true,
                         routing: {
-                            provider: providerName,
+                            provider: candidate.provider,
                             retryIndex,
                             fallbackIndex,
                             requestIds: {
@@ -210,7 +251,7 @@ export class AIRouter {
                         usage,
                         maxTokensRequested,
                         modelUsed,
-                        costUsd: typeof parsed.metadata?.costUsd === 'number' ? parsed.metadata.costUsd : undefined,
+                        costUsd: resolvedCostUsd,
                     };
                     attempts.push(attempt);
                     const mergedMetadata = {
@@ -218,7 +259,7 @@ export class AIRouter {
                         provider: providerName,
                         modelUsed,
                         maxTokensRequested,
-                        costUsd: attempt.costUsd,
+                        ...(resolvedCostUsd !== undefined ? { costUsd: resolvedCostUsd, cost: resolvedCostUsd } : {}),
                         requestIds: {
                             ...parsed.metadata?.requestIds,
                             routerRequestId: requestId,
@@ -229,30 +270,49 @@ export class AIRouter {
                         latencyMs: timing.durationMs,
                         attempts,
                     };
-                    return {
+                    const baseResponse = {
                         ...parsed,
                         requestId,
                         provider: parsed.provider || providerName,
                         usage,
                         metadata: mergedMetadata,
                     };
+                    return applyResponseNormalization(baseResponse, candidateInput.request);
                 }
                 catch (err) {
                     const endedAt = Date.now();
                     lastError = err;
+                    failedAttemptErrors.push(err);
+                    const modelUsed = typeof requestedModel === 'string'
+                        ? requestedModel
+                        : candidate.model;
+                    const timing = { startedAt, endedAt, durationMs: endedAt - startedAt };
                     attempts.push({
                         ok: false,
                         routing: {
-                            provider: providerName,
+                            provider: candidate.provider,
                             retryIndex,
                             fallbackIndex,
                             requestIds: { routerRequestId: requestId },
                         },
-                        timing: { startedAt, endedAt, durationMs: endedAt - startedAt },
+                        timing,
                         maxTokensRequested,
-                        modelUsed: typeof requestedModel === 'string' ? requestedModel : undefined,
+                        modelUsed,
                         error: summarizeError(err),
                     });
+                    const partialPayload = buildPartialRouterPayload({
+                        requestId,
+                        engineProvider: candidate.provider,
+                        providerModule: providerName,
+                        modelUsed,
+                        maxTokensRequested,
+                        timing,
+                        attempts,
+                        execResult,
+                        providerError: err,
+                    });
+                    lastPartialPayload = partialPayload;
+                    attachPartialRouterPayload(err, partialPayload);
                     const shouldRetry = retryIndex < maxRetries && isRetryableError(err);
                     if (shouldRetry) {
                         await sleep(backoffMs(retryIndex));
@@ -262,10 +322,19 @@ export class AIRouter {
                 }
             }
         }
-        // Fallback chain exhausted
-        const error = lastError instanceof Error ? lastError : new Error(String(lastError ?? 'Unknown error'));
-        error.attempts = attempts;
-        throw error;
+        const failedTraces = attempts.filter((a) => !a.ok);
+        const exhaustedAttempts = failedTraces.map((trace, i) => ({
+            provider: trace.routing.provider,
+            model: trace.modelUsed,
+            httpStatus: trace.error?.httpStatus,
+            error: toError(failedAttemptErrors[i] ?? lastError),
+            ...(trace.error?.responsePreview !== undefined ? { responsePreview: trace.error.responsePreview } : {}),
+        }));
+        const exhaustedError = new FallbackExhaustedError(exhaustedAttempts);
+        if (lastPartialPayload) {
+            attachPartialRouterPayload(exhaustedError, lastPartialPayload);
+        }
+        throw exhaustedError;
     }
     /**
      * Execute a streaming request

package/dist/router/RouterTypes.d.ts

@@ -8,6 +8,8 @@ export type NormalizedUsage = {
     completionTokens: number;
     totalTokens: number;
 };
+/** Activity billing state when token usage is recorded (Run Analysis G8). */
+export type ActivityCostStatus = 'priced' | 'unpriced';
 export type AttemptTiming = {
     startedAt: number;
     endedAt: number;
@@ -16,6 +18,14 @@ export type AttemptTiming = {
 export type AttemptErrorSummary = {
     name: string;
     message: string;
+    httpStatus?: number;
+    responsePreview?: string;
+};
+/** Provider + model reference used in fallback chains (`engine` is a gateway alias for `provider`). */
+export type ProviderModelRef = {
+    engine?: string;
+    provider?: string;
+    model?: string;
 };
 export type AttemptRouting = {
     provider: string;
@@ -41,6 +51,10 @@ export type DiagnosticsMetadata = {
     /** The actual model that served the response (may differ after normalization/routing). */
     modelUsed?: string;
     costUsd?: number;
+    /** Alias for activity consumers; mirrors `costUsd` when priced. */
+    cost?: number;
+    /** Set to `unpriced` when usage exists but no USD cost was returned by the provider. */
+    costStatus?: ActivityCostStatus;
     maxTokensRequested?: number;
     /** Stable correlation ids across router/provider proxies. */
     requestIds?: Record<string, string | undefined>;
@@ -87,6 +101,8 @@ export interface RouterConfig {
         httpReferer?: string;
         xTitle?: string;
     };
+    /** Default provider/model fallback chain when request config does not specify one. */
+    fallbackChain?: ProviderModelRef[];
 }
 /**
  * Router request - the input to the router
@@ -106,11 +122,17 @@ export interface AIRouterRequest {
 /**
  * Router response for sync mode
  */
+export type NormalizedRouterOutput = {
+    /** Structured fields when an output contract is present (Run Analysis G6/G9). */
+    parsed?: Record<string, unknown>;
+};
 export interface AIResponse {
     requestId: string;
     provider: string;
     rawResponse: unknown;
     outputText?: string;
+    /** Gateway-normalized structured output (`output.parsed` on persisted activities). */
+    output?: NormalizedRouterOutput;
     usage?: NormalizedUsage;
     reasoning: {
         requested: {

package/dist/router/RouterWrapper.js

@@ -60,7 +60,7 @@ export class LLMProviderRouter {
         this.adapterRegistry.register(new GrokAdapter());
         this.adapterRegistry.register(new OpenRouterAdapter());
         // Create router
-        this.router = new AIRouter(this.providerRegistry, this.adapterRegistry);
+        this.router = new AIRouter(this.providerRegistry, this.adapterRegistry, this.config);
         this.logger.info('Router initialized with ProviderModule architecture', {
             verbose: this.logger.verbose,
             logLevel: this.logger.level,
@@ -241,7 +241,7 @@ export class LLMProviderRouter {
                     output: result.usage?.completionTokens || 0,
                     total: result.usage?.totalTokens || 0,
                 },
-                cost: result.metadata?.costUsd,
+                cost: result.metadata?.costUsd ?? result.metadata?.cost,
                 success: true,
             });
         }

package/dist/router/fallbackUtils.d.ts

@@ -0,0 +1,38 @@
+import type { AttemptErrorSummary } from './RouterTypes.js';
+export type FallbackCandidate = {
+    provider: string;
+    model?: string;
+};
+export type ProviderModelRef = {
+    engine?: string;
+    provider?: string;
+    model?: string;
+};
+export declare function extractHttpStatus(err: unknown): number | undefined;
+export declare function extractResponsePreview(err: unknown): string | undefined;
+export declare function toError(err: unknown): Error;
+export declare function summarizeError(err: unknown): AttemptErrorSummary;
+export declare function isModelNotFoundError(err: unknown): boolean;
+/** Transient failures — retry the same provider/model candidate. */
+export declare function isRetryableError(err: unknown): boolean;
+/** Failures that should advance to the next fallback candidate (not retry same candidate). */
+export declare function isFallbackEligibleError(err: unknown): boolean;
+export declare function buildFallbackCandidates(input: {
+    primaryProvider: string;
+    primaryModel?: string;
+    requestConfig?: Record<string, unknown>;
+    routerFallbackChain?: ProviderModelRef[];
+}): FallbackCandidate[];
+export declare function buildCandidateRequest(input: AIRouterRequestLike, candidate: FallbackCandidate): AIRouterRequestLike;
+type AIRouterRequestLike = {
+    request?: {
+        config?: Record<string, unknown>;
+        model?: string;
+        [key: string]: unknown;
+    };
+    provider?: string;
+    mode?: string;
+    exec?: unknown;
+    requestId?: string;
+};
+export {};

package/dist/router/fallbackUtils.js

@@ -0,0 +1,176 @@
+const PREVIEW_CAP = 500;
+export function extractHttpStatus(err) {
+    const e = err;
+    if (!e)
+        return undefined;
+    for (const key of ['status', 'statusCode', 'httpStatus']) {
+        const v = e[key];
+        if (typeof v === 'number' && Number.isFinite(v))
+            return v;
+    }
+    const response = e.response;
+    if (response && typeof response.status === 'number')
+        return response.status;
+    const msg = err instanceof Error ? err.message : String(err);
+    const httpMatch = msg.match(/\bHTTP\s+(\d{3})\b/i);
+    if (httpMatch)
+        return Number(httpMatch[1]);
+    return undefined;
+}
+export function extractResponsePreview(err) {
+    const e = err;
+    if (!e)
+        return undefined;
+    const raw = e.body ??
+        e.responseBody ??
+        e.response?.data ??
+        e.data ??
+        e.error;
+    if (raw === undefined || raw === null)
+        return undefined;
+    let text;
+    if (typeof raw === 'string') {
+        text = raw;
+    }
+    else {
+        try {
+            text = JSON.stringify(raw);
+        }
+        catch {
+            text = String(raw);
+        }
+    }
+    return text.length > PREVIEW_CAP ? text.slice(0, PREVIEW_CAP) : text;
+}
+export function toError(err) {
+    return err instanceof Error ? err : new Error(String(err));
+}
+export function summarizeError(err) {
+    const e = toError(err);
+    const name = typeof e.name === 'string' ? e.name : 'Error';
+    const message = typeof e.message === 'string' ? e.message : String(err);
+    const capped = message.length > PREVIEW_CAP ? message.slice(0, PREVIEW_CAP) : message;
+    const httpStatus = extractHttpStatus(err);
+    const responsePreview = extractResponsePreview(err);
+    return {
+        name,
+        message: capped,
+        ...(httpStatus !== undefined ? { httpStatus } : {}),
+        ...(responsePreview !== undefined ? { responsePreview } : {}),
+    };
+}
+export function isModelNotFoundError(err) {
+    const status = extractHttpStatus(err);
+    if (status === 404)
+        return true;
+    const msg = err instanceof Error ? err.message : String(err);
+    const name = err instanceof Error ? err.name : '';
+    const combined = `${name} ${msg}`.toLowerCase();
+    return (combined.includes('model not found') ||
+        combined.includes('model_not_found') ||
+        combined.includes('model does not exist') ||
+        combined.includes('unknown model') ||
+        combined.includes('invalid model'));
+}
+/** Transient failures — retry the same provider/model candidate. */
+export function isRetryableError(err) {
+    if (isModelNotFoundError(err))
+        return false;
+    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'));
+}
+/** Failures that should advance to the next fallback candidate (not retry same candidate). */
+export function isFallbackEligibleError(err) {
+    if (isModelNotFoundError(err))
+        return true;
+    const status = extractHttpStatus(err);
+    if (status !== undefined) {
+        if (status === 404)
+            return true;
+        if (status >= 500)
+            return false;
+        if (status === 429)
+            return false;
+    }
+    return !isRetryableError(err);
+}
+function parseProviderModelRef(entry) {
+    if (!entry || typeof entry !== 'object')
+        return undefined;
+    const ref = entry;
+    const providerRaw = ref.engine ?? ref.provider;
+    if (typeof providerRaw !== 'string' || !providerRaw.trim())
+        return undefined;
+    const provider = providerRaw.trim();
+    const model = typeof ref.model === 'string' && ref.model.trim() ? ref.model.trim() : undefined;
+    return { provider, model };
+}
+function dedupeCandidates(candidates) {
+    const seen = new Set();
+    const out = [];
+    for (const c of candidates) {
+        const key = `${c.provider}\0${c.model ?? ''}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(c);
+    }
+    return out;
+}
+export function buildFallbackCandidates(input) {
+    const { primaryProvider, primaryModel, requestConfig, routerFallbackChain } = input;
+    const candidates = [{ provider: primaryProvider, model: primaryModel }];
+    const chainRaw = (Array.isArray(requestConfig?.fallbackChain) ? requestConfig.fallbackChain : undefined) ??
+        (Array.isArray(requestConfig?.fallbackEngines) ? requestConfig.fallbackEngines : undefined) ??
+        (Array.isArray(routerFallbackChain) ? routerFallbackChain : undefined);
+    if (Array.isArray(chainRaw) && chainRaw.length > 0) {
+        for (const entry of chainRaw) {
+            const parsed = parseProviderModelRef(entry);
+            if (parsed)
+                candidates.push(parsed);
+        }
+    }
+    else {
+        const fallbackProvidersRaw = requestConfig?.fallbackProviders;
+        const fallbackProviders = Array.isArray(fallbackProvidersRaw)
+            ? fallbackProvidersRaw
+                .filter((p) => typeof p === 'string' && p.trim().length > 0)
+                .map((p) => p.trim())
+            : [];
+        for (const provider of fallbackProviders) {
+            if (provider !== primaryProvider) {
+                candidates.push({ provider, model: primaryModel });
+            }
+        }
+    }
+    return dedupeCandidates(candidates);
+}
+export function buildCandidateRequest(input, candidate) {
+    const baseConfig = (input.request?.config && typeof input.request.config === 'object')
+        ? input.request.config
+        : {};
+    const model = candidate.model ?? (typeof baseConfig.model === 'string' ? baseConfig.model : undefined);
+    return {
+        ...input,
+        request: {
+            ...input.request,
+            ...(model !== undefined ? { model } : {}),
+            config: {
+                ...baseConfig,
+                provider: candidate.provider,
+                ...(model !== undefined ? { model } : {}),
+            },
+        },
+    };
+}

package/dist/router/partialErrorPayload.d.ts

@@ -0,0 +1,26 @@
+import type { ProviderSDKExecResult } from '@x12i/ai-provider-interface';
+import type { AttemptTrace, DiagnosticsMetadata, NormalizedUsage } from './RouterTypes.js';
+export type PartialRouterPayload = {
+    requestId: string;
+    provider: string;
+    usage?: NormalizedUsage;
+    metadata: DiagnosticsMetadata;
+    rawResponse?: unknown;
+};
+export declare function attachPartialRouterPayload(err: unknown, payload: PartialRouterPayload): void;
+export declare function normalizeUsageFromUnknown(usage: unknown): NormalizedUsage | undefined;
+export declare function buildPartialRouterPayload(args: {
+    requestId: string;
+    engineProvider: string;
+    providerModule?: string;
+    modelUsed?: string;
+    maxTokensRequested?: number;
+    timing?: {
+        startedAt: number;
+        endedAt: number;
+        durationMs: number;
+    };
+    attempts?: AttemptTrace[];
+    execResult?: ProviderSDKExecResult;
+    providerError?: unknown;
+}): PartialRouterPayload;

package/dist/router/partialErrorPayload.js

@@ -0,0 +1,133 @@
+export function attachPartialRouterPayload(err, payload) {
+    if (err == null || typeof err !== 'object')
+        return;
+    err.response = payload;
+}
+function firstString(...values) {
+    for (const v of values) {
+        if (typeof v === 'string' && v.trim())
+            return v.trim();
+    }
+    return undefined;
+}
+export function normalizeUsageFromUnknown(usage) {
+    if (!usage || typeof usage !== 'object')
+        return undefined;
+    const u = usage;
+    const promptTokens = (typeof u.promptTokens === 'number' ? u.promptTokens : undefined) ??
+        (typeof u.inputTokens === 'number' ? u.inputTokens : undefined) ??
+        (typeof u.prompt_tokens === 'number' ? u.prompt_tokens : undefined) ??
+        (typeof u.input_tokens === 'number' ? u.input_tokens : undefined) ??
+        (typeof u.prompt === 'number' ? u.prompt : undefined);
+    const completionTokens = (typeof u.completionTokens === 'number' ? u.completionTokens : undefined) ??
+        (typeof u.outputTokens === 'number' ? u.outputTokens : undefined) ??
+        (typeof u.completion_tokens === 'number' ? u.completion_tokens : undefined) ??
+        (typeof u.output_tokens === 'number' ? u.output_tokens : undefined) ??
+        (typeof u.completion === 'number' ? u.completion : undefined);
+    const totalTokens = (typeof u.totalTokens === 'number' ? u.totalTokens : undefined) ??
+        (typeof u.total_tokens === 'number' ? u.total_tokens : undefined) ??
+        (typeof u.total === 'number' ? u.total : 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 };
+}
+function extractIdsFromRaw(raw) {
+    if (!raw || typeof raw !== 'object')
+        return {};
+    const r = raw;
+    const id = firstString(r.id, r.request_id, r.requestId);
+    if (!id)
+        return {};
+    return { providerRequestId: id, openrouterRequestId: id };
+}
+function extractRawBody(err) {
+    if (err == null || typeof err !== 'object')
+        return undefined;
+    const e = err;
+    const response = e.response;
+    if (response != null && typeof response === 'object') {
+        const resp = response;
+        if (resp.data !== undefined)
+            return resp.data;
+        if (resp.body !== undefined)
+            return resp.body;
+    }
+    for (const key of ['rawResponse', 'body', 'data', 'lastResponse', 'routerResponse']) {
+        if (e[key] !== undefined)
+            return e[key];
+    }
+    const nestedError = e.error;
+    if (nestedError != null && typeof nestedError === 'object') {
+        return extractRawBody(nestedError);
+    }
+    return undefined;
+}
+function extractHeaderRequestId(err) {
+    if (err == null || typeof err !== 'object')
+        return undefined;
+    const e = err;
+    const response = e.response;
+    if (response == null || typeof response !== 'object')
+        return undefined;
+    const headers = response.headers;
+    if (headers == null || typeof headers !== 'object')
+        return undefined;
+    const h = headers;
+    return firstString(h['x-request-id'], h['x-openrouter-request-id'], h['request-id'], h['openrouter-request-id']);
+}
+function usageToGatewayTokens(usage) {
+    return {
+        prompt: usage.promptTokens,
+        completion: usage.completionTokens,
+        total: usage.totalTokens,
+    };
+}
+export function buildPartialRouterPayload(args) {
+    let usage = args.execResult?.rawResponse
+        ? normalizeUsageFromUnknown(args.execResult.rawResponse?.usage)
+        : undefined;
+    let rawResponse = args.execResult?.rawResponse;
+    let ids = rawResponse ? extractIdsFromRaw(rawResponse) : {};
+    const errorBody = extractRawBody(args.providerError);
+    if (errorBody !== undefined) {
+        rawResponse = rawResponse ?? errorBody;
+        usage = usage ?? normalizeUsageFromUnknown(errorBody?.usage);
+        const bodyIds = extractIdsFromRaw(errorBody);
+        ids = { ...bodyIds, ...ids };
+    }
+    const headerRequestId = extractHeaderRequestId(args.providerError);
+    if (headerRequestId) {
+        ids = {
+            providerRequestId: ids.providerRequestId ?? headerRequestId,
+            openrouterRequestId: ids.openrouterRequestId ?? headerRequestId,
+        };
+    }
+    const providerRequestId = ids.providerRequestId;
+    const openrouterRequestId = args.providerModule === 'openrouter' ? providerRequestId : ids.openrouterRequestId;
+    const metadata = {
+        provider: args.providerModule ?? args.engineProvider,
+        ...(args.modelUsed !== undefined ? { modelUsed: args.modelUsed } : {}),
+        ...(args.maxTokensRequested !== undefined ? { maxTokensRequested: args.maxTokensRequested } : {}),
+        requestIds: {
+            routerRequestId: args.requestId,
+            ...(providerRequestId ? { providerRequestId } : {}),
+            ...(openrouterRequestId ? { openrouterRequestId } : {}),
+        },
+        ...(args.timing ? { timing: args.timing, latencyMs: args.timing.durationMs } : {}),
+        ...(args.attempts ? { attempts: args.attempts } : {}),
+    };
+    if (usage) {
+        metadata.usage = usage;
+        metadata.tokens = usageToGatewayTokens(usage);
+    }
+    return {
+        requestId: args.requestId,
+        provider: args.engineProvider,
+        ...(usage ? { usage } : {}),
+        ...(rawResponse !== undefined ? { rawResponse } : {}),
+        metadata,
+    };
+}

package/dist/router.d.ts

@@ -1,5 +1,5 @@
 export { LLMProviderRouter } from './router/RouterWrapper.js';
-export type { RouterConfig, AIRouterRequest, AIResponse, AIStreamEvent, AIBatchResponse, AIBatchRequestItem } from './router/RouterTypes.js';
+export type { RouterConfig, AIRouterRequest, AIResponse, AIStreamEvent, AIBatchResponse, AIBatchRequestItem, ActivityCostStatus, NormalizedRouterOutput, ProviderModelRef, } from './router/RouterTypes.js';
 export { ProviderRegistry } from './registry/ProviderRegistry.js';
 export { AdapterRegistry } from './registry/AdapterRegistry.js';
 export { OpenAIAdapter } from './adapters/openai/OpenAIAdapter.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/ai-providers-router",
-  "version": "4.7.7",
+  "version": "4.8.2",
   "description": "Unified router for all LLM provider implementations",
   "type": "module",
   "main": "dist/index.js",
@@ -18,6 +18,7 @@
     "fix:imports": "node fix-import-extensions.js",
     "prepublishOnly": "rm -rf dist && npm run build && node -e \"import('fs').then(fs => fs.accessSync('dist/index.js'))\"",
     "test": "npm run build && node --test .tests/**/*.test.js",
+    "test:cost-output": "npm run build && node --test .tests/cost-and-output-contract.test.js",
     "test:openai": "ts-node .tests/callOpenAI.ts",
     "test:grok": "ts-node .tests/testOpenRouter.ts",
     "test:catalog": "ts-node .tests/testCatalog.ts",