@x12i/ai-providers-router 4.7.6 → 4.8.0

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/index.d.ts

@@ -7,3 +7,10 @@ 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/router/Router.js

@@ -1,4 +1,6 @@
 import { newId } from '../utils/ids.js';
+import { applyResponseNormalization } from '../normalization/applyResponseNormalization.js';
+import { extractCostUsdFromRouterResponse } from '../normalization/cost.js';
 /**
  * Main router class
  * Orchestrates provider execution using ProviderModules and router-side adapters
@@ -194,6 +196,10 @@ 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: {
@@ -210,7 +216,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 +224,7 @@ export class AIRouter {
                         provider: providerName,
                         modelUsed,
                         maxTokensRequested,
-                        costUsd: attempt.costUsd,
+                        ...(resolvedCostUsd !== undefined ? { costUsd: resolvedCostUsd, cost: resolvedCostUsd } : {}),
                         requestIds: {
                             ...parsed.metadata?.requestIds,
                             routerRequestId: requestId,
@@ -229,13 +235,14 @@ export class AIRouter {
                         latencyMs: timing.durationMs,
                         attempts,
                     };
-                    return {
+                    const baseResponse = {
                         ...parsed,
                         requestId,
                         provider: parsed.provider || providerName,
                         usage,
                         metadata: mergedMetadata,
                     };
+                    return applyResponseNormalization(baseResponse, input.request);
                 }
                 catch (err) {
                     const endedAt = Date.now();

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;
@@ -41,6 +43,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>;
@@ -106,11 +112,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

@@ -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.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 } 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.6",
+  "version": "4.8.0",
   "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",