@x12i/ai-gateway 10.0.4 → 10.0.5

package/README.md

@@ -210,15 +210,39 @@ Exports: `GATEWAY_LOGXER_PACKAGE`, `GATEWAY_LOG_ENV_PREFIX`, `createGatewayLogge
 
 ## @x12i/ai-tools v2 (models + cost)
 
-- **No Catalox / Firestore** — catalogs come from ai-tools open-assets JSON (optional `bundledOnly`).
-- **`aiTools.enabled`** — bootstrap catalog client + calculator.
-- **`aiTools.resolveModels`** — `mergeConfig()` calls `resolveInvokeModel()` (catalog + OpenRouter/direct routing).
-- **`aiTools.modelsOnly`** — **`true` by default** — reject profile shortcuts (`cheapest`, `cheap/default`, …); pass concrete model ids only.
-- **`aiTools.calculateCost`** — prices usage before Activix `completeRecord` when the router did not mark the call priced.
+Engine-owned catalog bootstrap and post-call billing. Consumers read **`metadata.costUsd`** / **`costStatus`** only — no direct `@x12i/ai-tools` dependency for cost.
 
-Gateway exports the orchestrator from `@x12i/ai-tools` ≥ **2.5.0** (`resolveInvokeModel`, …) — see [AI_TOOLS_INVOKE_MODEL_RESOLUTION_ORCHESTRATOR_SPEC.md](./docs/upstream-reports/AI_TOOLS_INVOKE_MODEL_RESOLUTION_ORCHESTRATOR_SPEC.md).
+### Resolution order (after every successful LLM call)
 
-Gateway helpers (also exported): `resolveCostCompletionWithAiTools`, `buildTraceUsageSummary`, `enrichTraceAttemptsWithBilling`.
+| Step | Condition | Result |
+|------|-----------|--------|
+| A | Router/provider returned finite **`costUsd`** (or equivalent) | **`costStatus: "priced"`**, set cost |
+| B | Tokens + catalog pricing succeeds (`isAuthoritative`, not `unknownModel`, finite cost ≥ 0) | **`priced`** (+ optional breakdown) |
+| C | Tokens but no price | **`unpriced`** |
+| D | No usage | omit **`costUsd`** and **`costStatus`** |
+
+Step A always wins; explicit router **`costStatus: "unpriced"`** is never overridden by catalog.
+
+Implemented in **`resolveCostCompletionWithAiTools`** (delegates to **`CostCalculator.calculateFromRecord`** via **`buildGatewayPricingRecord`**). Target: move orchestrator to ai-tools as **`resolveInvokeBilling`** — see [AI_TOOLS_INVOKE_BILLING_ORCHESTRATOR_SPEC.md](./docs/upstream-reports/AI_TOOLS_INVOKE_BILLING_ORCHESTRATOR_SPEC.md).
+
+### `aiTools` config (aligned with funcx / generic engine contract)
+
+| Flag | Default | Purpose |
+|------|---------|---------|
+| **`enabled`** | `true` | Bootstrap **`AiModelsCatalogClient`** + **`CostCalculator`** |
+| **`calculateCost`** | `true` | Run post-call catalog pricing when router did not price |
+| **`resolveModels`** | `true` | **`mergeConfig()`** → **`resolveInvokeModel()`** |
+| **`modelsOnly`** | `true` | Reject profile shortcuts (`cheapest`, `cheap/default`, …) |
+| **`bundledOnly`** | `false` | Offline bundled catalogs only |
+| **`costIncludeBreakdown`** | `false` | Include prompt/completion breakdown on priced results |
+| **`catalogLane`** | `"text"` (ai-tools default) | Catalog lane for resolution + cost lookup (`text`, `image`, …) |
+| **`cacheTtlMs`** | ai-tools default (24h) | In-memory catalog cache TTL |
+
+- **No Catalox / Firestore** — catalogs come from ai-tools open-assets JSON (optional **`bundledOnly`**).
+
+Gateway exports the model orchestrator from `@x12i/ai-tools` ≥ **2.5.0** (`resolveInvokeModel`, …) — see [AI_TOOLS_INVOKE_MODEL_RESOLUTION_ORCHESTRATOR_SPEC.md](./docs/upstream-reports/AI_TOOLS_INVOKE_MODEL_RESOLUTION_ORCHESTRATOR_SPEC.md).
+
+Gateway billing helpers (also exported): `resolveCostCompletionWithAiTools`, `buildGatewayPricingRecord`, `catalogPricingSucceeded`, `ensureInvokeBillingCostStatus`, `buildTraceUsageSummary`, `enrichTraceAttemptsWithBilling`.
 
 ---
 
@@ -249,9 +273,9 @@ Mongo env: `MONGO_URI` + `MONGO_LOGS_DB` or `MONGO_DB`.
 
 ## Response metadata and cost
 
-On every successful **`invoke()`**:
+On every successful **`invoke()`** and **`invokeChat()`**:
 
-- **`metadata.provider`**, **`modelUsed`**, **`maxTokensRequested`**, **`effectiveModelConfig`**
+- **`metadata.provider`**, **`modelUsed`**, **`maxTokensRequested`**, **`effectiveModelConfig`** (invoke only)
 - **`metadata.tokens`**, **`costStatus`**, **`costUsd`** when usage exists and pricing applies
 
 Full contract: [AI Gateway invoke execution metadata](./docs/AI_GATEWAY_INVOKE_EXECUTION_METADATA.md).

package/dist/ai-tools-client.js

@@ -2,7 +2,7 @@
  * @x12i/ai-tools invoke client bootstrap for the gateway.
  * Model resolution orchestration lives in ai-tools ≥ 2.5.0 (`resolveInvokeModel`).
  */
-import { getAiToolsInvokeClient, resetAiToolsInvokeClientForTests as resetAiToolsInvokeClientForTestsUpstream, mapResolutionToRouterConfig, buildInvokeModelResolverOptions, } from '@x12i/ai-tools';
+import { getAiToolsInvokeClient, resetAiToolsInvokeClientForTests as resetAiToolsInvokeClientForTestsUpstream, mapResolutionToRouterConfig, buildInvokeModelResolverOptions, CostCalculator, } from '@x12i/ai-tools';
 import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
 import { resolvePreferOpenRouter } from './openrouter-routing.js';
 export { resolveInvokeModel, applyOpenRouterInvokePolicy, buildInvokeModelResolverOptions, enrichModelResolutionError, mapResolutionToRouterConfig, ModelProfileUnroutableError, ModelProfileInputRejectedError, MODEL_PROFILE_UNROUTABLE, getAiToolsInvokeClient, resetAiToolsInvokeClientForTests as resetAiToolsInvokeClientForTestsUpstream, createAiToolsInvokeClient, } from '@x12i/ai-tools';
@@ -13,7 +13,22 @@ function invokeClientOptions(config) {
         cacheTtlMs: config.aiTools?.cacheTtlMs,
         ...(config.aiTools?.bundledOnly ? { bundledOnly: true } : {}),
         ...(config.aiTools?.costIncludeBreakdown ? { costIncludeBreakdown: true } : {}),
-        cacheKey: `${config.aiTools?.cacheTtlMs ?? ''}:${config.aiTools?.costIncludeBreakdown ?? ''}:${config.aiTools?.bundledOnly ?? ''}`,
+        cacheKey: `${config.aiTools?.cacheTtlMs ?? ''}:${config.aiTools?.costIncludeBreakdown ?? ''}:${config.aiTools?.bundledOnly ?? ''}:${config.aiTools?.catalogLane ?? ''}`,
+    };
+}
+function withCatalogLaneCalculator(client, config) {
+    const lane = config.aiTools?.catalogLane;
+    if (!lane)
+        return client;
+    return {
+        ...client,
+        calculator: new CostCalculator(client.catalog, {
+            ...(config.aiTools?.costIncludeBreakdown ? { includeBreakdown: true } : {}),
+            resolverOptions: buildInvokeModelResolverOptions({
+                routingEnv: client.routingEnv,
+                catalogLane: lane
+            })
+        })
     };
 }
 /** @deprecated Use buildInvokeModelResolverOptions */
@@ -53,6 +68,7 @@ export async function getAiToolsClient(config, logger) {
         logger.debug('ai-tools catalog client ready', {
             debugKind: gatewayLogDebug.state,
         });
+        return withCatalogLaneCalculator(client, config);
     }
     return client;
 }

package/dist/gateway-utils.d.ts

@@ -94,13 +94,38 @@ export type ResolveCostCompletionOptions = {
     calculator?: CostCalculator | null;
     calculateCost?: boolean;
 };
-/** Record shape for {@link CostCalculator.calculateFromRecord} (router + merged config + usage). */
+/** Optional cache/reasoning token fields for catalog pricing records. */
+export type InvokeUsageExtras = {
+    cached?: number;
+    cacheWrite?: number;
+    reasoning?: number;
+};
+/**
+ * Best-effort cache/reasoning token counts from router usage buckets
+ * (for {@link buildGatewayPricingRecord} / ai-tools {@link CostCalculator.calculateFromRecord}).
+ */
+export declare function extractUsageExtrasFromRouterResponse(routerResponse: unknown): InvokeUsageExtras;
+/**
+ * Whether ai-tools catalog pricing is authoritative enough for Step B (`priced`).
+ * Matches the generic engine contract: authoritative catalog hit with finite cost ≥ 0.
+ */
+export declare function catalogPricingSucceeded(result: AiCostResult): boolean;
+/** Record shape for {@link CostCalculator.calculateFromRecord} (shared engine contract). */
 export declare function buildGatewayPricingRecord(routerResponse: unknown, tokens: {
     prompt: number;
     completion: number;
     total: number;
 }, mergedConfig?: unknown): Record<string, unknown>;
 export declare function mapAiCostResultToResolvedActivityCost(base: ResolvedActivityCost, result: AiCostResult): ResolvedActivityCost;
+/**
+ * G8 safety net: token usage without a billing signal → `unpriced`.
+ * Used at invoke boundaries after {@link resolveCostCompletionWithAiTools}.
+ */
+export declare function ensureInvokeBillingCostStatus(billing: ResolvedActivityCost, tokens: {
+    prompt: number;
+    completion: number;
+    total: number;
+}): ResolvedActivityCost;
 /**
  * Router cost passthrough, then optional @x12i/ai-tools catalog pricing when still unpriced.
  */

package/dist/gateway-utils.js

@@ -108,6 +108,8 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
                 defaultProvider: config.defaultEngine,
                 resolveModels: true,
                 modelsOnly: config.aiTools?.modelsOnly !== false,
+                ...(config.aiTools?.catalogLane ? { catalogLane: config.aiTools.catalogLane } : {}),
+                ...(config.aiTools?.bundledOnly ? { bundledOnly: true } : {}),
             });
             merged.provider = resolved.router.provider;
             merged.model = resolved.router.model;
@@ -368,42 +370,119 @@ export function resolveCostCompletionForActivity(routerResponse, tokens) {
     }
     return resolveActivityCostCompletion(tokens, costUsd);
 }
-/** Record shape for {@link CostCalculator.calculateFromRecord} (router + merged config + usage). */
+/**
+ * Best-effort cache/reasoning token counts from router usage buckets
+ * (for {@link buildGatewayPricingRecord} / ai-tools {@link CostCalculator.calculateFromRecord}).
+ */
+export function extractUsageExtrasFromRouterResponse(routerResponse) {
+    if (routerResponse == null || typeof routerResponse !== 'object')
+        return {};
+    const r = routerResponse;
+    const roots = [r.usage];
+    const meta = r.metadata != null && typeof r.metadata === 'object'
+        ? r.metadata
+        : undefined;
+    if (meta) {
+        roots.push(meta.usage, meta.tokens);
+    }
+    const raw = r.rawResponse ?? r.raw;
+    if (raw != null && typeof raw === 'object') {
+        roots.push(raw.usage);
+    }
+    const extras = {};
+    for (const bucket of roots) {
+        if (bucket == null || typeof bucket !== 'object')
+            continue;
+        const u = bucket;
+        const cached = firstFiniteNumber(u.cached, u.cached_tokens, u.cachedTokens, u.cache_read_tokens, u.cacheReadTokens);
+        const cacheWrite = firstFiniteNumber(u.cacheWrite, u.cache_write_tokens, u.cacheWriteTokens);
+        const reasoning = firstFiniteNumber(u.reasoning, u.reasoning_tokens, u.reasoningTokens);
+        if (cached !== undefined && extras.cached === undefined)
+            extras.cached = cached;
+        if (cacheWrite !== undefined && extras.cacheWrite === undefined)
+            extras.cacheWrite = cacheWrite;
+        if (reasoning !== undefined && extras.reasoning === undefined)
+            extras.reasoning = reasoning;
+    }
+    return extras;
+}
+/**
+ * Whether ai-tools catalog pricing is authoritative enough for Step B (`priced`).
+ * Matches the generic engine contract: authoritative catalog hit with finite cost ≥ 0.
+ */
+export function catalogPricingSucceeded(result) {
+    if (result.unknownModel)
+        return false;
+    if (!result.isAuthoritative)
+        return false;
+    if (result.source === 'estimate-fallback' || result.source === 'local')
+        return false;
+    if (typeof result.cost !== 'number' || !Number.isFinite(result.cost) || result.cost < 0) {
+        return false;
+    }
+    return true;
+}
+/** Record shape for {@link CostCalculator.calculateFromRecord} (shared engine contract). */
 export function buildGatewayPricingRecord(routerResponse, tokens, mergedConfig) {
-    const base = routerResponse != null && typeof routerResponse === 'object'
-        ? { ...routerResponse }
-        : {};
-    const meta = base.metadata != null && typeof base.metadata === 'object'
-        ? { ...base.metadata }
-        : {};
     const routing = pickInvokeRoutingMetadataSlice(routerResponse, mergedConfig);
+    const cfg = mergedConfig != null && typeof mergedConfig === 'object'
+        ? mergedConfig
+        : {};
+    const requestModel = typeof cfg.model === 'string'
+        ? cfg.model
+        : typeof routing.modelUsed === 'string'
+            ? routing.modelUsed
+            : undefined;
+    const modelUsed = routing.modelUsed ?? requestModel;
+    const provider = routing.provider ??
+        (typeof cfg.provider === 'string' ? cfg.provider : undefined) ??
+        'openrouter';
+    const usageExtras = extractUsageExtrasFromRouterResponse(routerResponse);
+    const tokenSlice = {
+        prompt: tokens.prompt,
+        completion: tokens.completion,
+        total: tokens.total,
+        ...usageExtras
+    };
     return {
-        ...base,
+        model: modelUsed ?? requestModel ?? '',
+        ...(requestModel && modelUsed && requestModel !== modelUsed
+            ? { modelAlias: requestModel }
+            : {}),
+        ...(modelUsed ? { modelUsed, usedModel: modelUsed } : {}),
+        provider,
+        ...(provider || routing.region
+            ? {
+                routing: {
+                    provider,
+                    ...(routing.region ? { region: routing.region } : {})
+                }
+            }
+            : {}),
         usage: {
-            promptTokens: tokens.prompt,
-            completionTokens: tokens.completion,
-            totalTokens: tokens.total
+            prompt_tokens: tokens.prompt,
+            completion_tokens: tokens.completion,
+            total_tokens: tokens.total,
+            ...(usageExtras.cached !== undefined ? { cachedTokensPrompt: usageExtras.cached } : {}),
+            ...(usageExtras.cached !== undefined ? { cachedTokensTotal: usageExtras.cached } : {})
         },
-        tokens,
+        promptTokens: tokens.prompt,
+        completionTokens: tokens.completion,
+        totalTokens: tokens.total,
+        tokens: tokenSlice,
         metadata: {
-            ...meta,
-            tokens,
-            ...(routing.provider ? { provider: routing.provider } : {}),
-            ...(routing.modelUsed
-                ? { modelUsed: routing.modelUsed, model: routing.modelUsed }
-                : {})
+            provider,
+            ...(modelUsed ? { modelUsed, model: modelUsed } : {}),
+            ...(routing.maxTokensRequested !== undefined
+                ? { maxTokensRequested: routing.maxTokensRequested }
+                : {}),
+            tokens: tokenSlice
         },
         ...(mergedConfig != null ? { config: mergedConfig } : {})
     };
 }
 export function mapAiCostResultToResolvedActivityCost(base, result) {
-    if (result.unknownModel) {
-        return base.costStatus ? base : { ...base, costStatus: 'unpriced' };
-    }
-    if (typeof result.cost !== 'number' || !Number.isFinite(result.cost)) {
-        return base;
-    }
-    if (!result.isAuthoritative && result.source === 'estimate-fallback') {
+    if (!catalogPricingSucceeded(result)) {
         return base.costStatus ? base : { ...base, costStatus: 'unpriced' };
     }
     return {
@@ -412,6 +491,16 @@ export function mapAiCostResultToResolvedActivityCost(base, result) {
         ...(result.breakdown ? { costBreakdown: result.breakdown } : {})
     };
 }
+/**
+ * G8 safety net: token usage without a billing signal → `unpriced`.
+ * Used at invoke boundaries after {@link resolveCostCompletionWithAiTools}.
+ */
+export function ensureInvokeBillingCostStatus(billing, tokens) {
+    if (!billing.costStatus && hasNonZeroTokenUsage(tokens)) {
+        return { ...billing, costStatus: 'unpriced' };
+    }
+    return billing;
+}
 /**
  * Router cost passthrough, then optional @x12i/ai-tools catalog pricing when still unpriced.
  */
@@ -436,30 +525,7 @@ export async function resolveCostCompletionWithAiTools(routerResponse, tokens, o
         return mapAiCostResultToResolvedActivityCost(base, result);
     }
     catch {
-        const routing = pickInvokeRoutingMetadataSlice(routerResponse, options.mergedConfig);
-        const cfg = options.mergedConfig != null && typeof options.mergedConfig === 'object'
-            ? options.mergedConfig
-            : {};
-        const provider = routing.provider ?? cfg.provider;
-        const modelUsed = routing.modelUsed ?? cfg.model;
-        if (!provider || !modelUsed) {
-            return base;
-        }
-        try {
-            const result = await options.calculator.calculate({
-                tokens: {
-                    prompt: tokens.prompt,
-                    completion: tokens.completion,
-                    total: tokens.total
-                },
-                provider,
-                usedModel: modelUsed
-            });
-            return mapAiCostResultToResolvedActivityCost(base, result);
-        }
-        catch {
-            return base;
-        }
+        return ensureInvokeBillingCostStatus(base, tokens);
     }
 }
 function applyBillingToTraceAttempt(attempt, billing) {

package/dist/gateway.js

@@ -11,7 +11,7 @@ import { resolveRetryConfig } from './gateway-defaults.js';
 import { buildMessages } from './message-builder.js';
 import { extractJsonFromFlexMd } from './flex-md-loader.js';
 import { enrichParsedContentForOutputContract, resolveOutputContractFieldKeys } from './output-contract-normalizer.js';
-import { attachGatewayInvokeRejectionMetadata, buildGatewayFallbackAttemptsFromTrace, buildInvokeRejectionMetadata, capActivityFullResponsePayload, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter, hasNonZeroTokenUsage, DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, extractCostUsdFromRouterResponse, extractTokenUsageFromRouterResponse, mergeConfig, pickEffectiveModelConfigForMetadata, pickInvokeRoutingMetadataSlice, pickTraceMergedRouterConfig, resolveCostCompletionWithAiTools, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, tryExtractRouterLikePayloadFromErrorChain } from './gateway-utils.js';
+import { attachGatewayInvokeRejectionMetadata, buildGatewayFallbackAttemptsFromTrace, buildInvokeRejectionMetadata, capActivityFullResponsePayload, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter, DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, extractCostUsdFromRouterResponse, extractTokenUsageFromRouterResponse, mergeConfig, pickEffectiveModelConfigForMetadata, pickInvokeRoutingMetadataSlice, pickTraceMergedRouterConfig, resolveCostCompletionWithAiTools, ensureInvokeBillingCostStatus, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, tryExtractRouterLikePayloadFromErrorChain } from './gateway-utils.js';
 import { getAiToolsClient } from './ai-tools-client.js';
 import { autoRegisterProviders } from './gateway-provider-auto-register.js';
 import { setGatewayLastJobId, setGatewayRuntimeClients } from './runtime-objects.js';
@@ -135,11 +135,12 @@ export class AIGateway {
                 });
                 const metaChat = response?.metadata || {};
                 const tokensChat = extractTokenUsageFromRouterResponse(response);
-                const costCompletionChat = await resolveCostCompletionWithAiTools(response, tokensChat, {
+                let costCompletionChat = await resolveCostCompletionWithAiTools(response, tokensChat, {
                     mergedConfig,
                     calculator: aiTools?.calculator ?? null,
                     calculateCost: this.config.aiTools?.calculateCost
                 });
+                costCompletionChat = ensureInvokeBillingCostStatus(costCompletionChat, tokensChat);
                 // Create enhanced response
                 const enhancedResponse = {
                     content: response.content || '',
@@ -614,9 +615,7 @@ export class AIGateway {
                     calculator: aiTools?.calculator ?? null,
                     calculateCost: this.config.aiTools?.calculateCost
                 });
-                if (!costCompletion.costStatus && hasNonZeroTokenUsage(tokens)) {
-                    costCompletion = { ...costCompletion, costStatus: 'unpriced' };
-                }
+                costCompletion = ensureInvokeBillingCostStatus(costCompletion, tokens);
                 const routerMetaForCost = routerResponse?.metadata || {};
                 const routingMetadataSlice = pickInvokeRoutingMetadataSlice(routerResponse, mergedConfig);
                 const effectiveModelConfig = pickEffectiveModelConfigForMetadata(mergedConfig);

package/dist/index.d.ts

@@ -17,7 +17,7 @@ export { AIGateway } from './gateway.js';
 export { InstructionNotFoundError, InstructionBackendError, ModelRequiredError, MaxTokensRequiredError } from './instruction-errors.js';
 export { autoRegisterProviders } from './gateway-provider-auto-register.js';
 export type { GatewayConfig, ProviderModelRef, ModelConfig, RetryConfig, ChatRequest, AIInvokeRequest, AIRequest, GatewayActionType, GatewayInvokeRejectionMetadata, GatewayFallbackAttempt, GatewayTraceRequestIds, GatewayTraceAttempt, GatewayTraceUsageSummary, GatewayTraceMergedConfig, EnhancedLLMResponse, InstructionMetadata, ValidationRule, TemplateRenderOptions, SmartInputConfig, SmartInputRenderOptions } from './types.js';
-export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, tryExtractFallbackAttemptsFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, hasNonZeroTokenUsage, MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, ModelProfileInputRejectedError, buildGatewayFallbackAttemptsFromTrace, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter } from './gateway-utils.js';
+export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, tryExtractFallbackAttemptsFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, catalogPricingSucceeded, ensureInvokeBillingCostStatus, extractUsageExtrasFromRouterResponse, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, hasNonZeroTokenUsage, MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, ModelProfileInputRejectedError, buildGatewayFallbackAttemptsFromTrace, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter } from './gateway-utils.js';
 export { getGatewayOperationalMode, isProdGatewayMode, parseModelProviderSpec } from './gateway-mode.js';
 export type { GatewayOperationalMode } from './gateway-mode.js';
 export { DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, GATEWAY_DEFAULT_FREQUENCY_PENALTY, GATEWAY_DEFAULT_PRESENCE_PENALTY, GATEWAY_DEFAULT_RETRY, GATEWAY_DEFAULT_TEMPERATURE, GATEWAY_DEFAULT_TOP_P, resolveRetryConfig } from './gateway-defaults.js';

package/dist/index.js

@@ -17,7 +17,7 @@ export * from '@x12i/ai-providers-router';
 export { AIGateway } from './gateway.js';
 export { InstructionNotFoundError, InstructionBackendError, ModelRequiredError, MaxTokensRequiredError } from './instruction-errors.js';
 export { autoRegisterProviders } from './gateway-provider-auto-register.js';
-export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, tryExtractFallbackAttemptsFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, hasNonZeroTokenUsage, MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, ModelProfileInputRejectedError, buildGatewayFallbackAttemptsFromTrace, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter } from './gateway-utils.js';
+export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, tryExtractFallbackAttemptsFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, catalogPricingSucceeded, ensureInvokeBillingCostStatus, extractUsageExtrasFromRouterResponse, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, hasNonZeroTokenUsage, MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, ModelProfileInputRejectedError, buildGatewayFallbackAttemptsFromTrace, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter } from './gateway-utils.js';
 export { getGatewayOperationalMode, isProdGatewayMode, parseModelProviderSpec } from './gateway-mode.js';
 export { DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, GATEWAY_DEFAULT_FREQUENCY_PENALTY, GATEWAY_DEFAULT_PRESENCE_PENALTY, GATEWAY_DEFAULT_RETRY, GATEWAY_DEFAULT_TEMPERATURE, GATEWAY_DEFAULT_TOP_P, resolveRetryConfig } from './gateway-defaults.js';
 export { contractSpecToFieldKeys, enrichParsedContentForOutputContract, resolveOutputContractFieldKeys } from './output-contract-normalizer.js';

package/dist/types.d.ts

@@ -9,6 +9,7 @@ type AIModel = string;
 export type UsageTier = string;
 import type { Activix } from '@x12i/activix';
 import type { SmartInputConfig, SmartInputRenderOptions, TemplateRenderOptions } from '@x12i/rendrix';
+import type { ProfileCatalogLane } from '@x12i/ai-profiles';
 import type { Logxer, PackageLogLevelsConfig } from '@x12i/logxer';
 /**
  * Diagnostics options for opt-in authoritative tracing.
@@ -415,6 +416,11 @@ export interface GatewayConfig extends Omit<RouterConfig, 'defaultEngine' | 'log
         cacheTtlMs?: number;
         /** Use bundled catalog JSON only (offline / tests). */
         bundledOnly?: boolean;
+        /**
+         * Catalog lane for model resolution and cost lookup (`text`, `image`, …).
+         * @default `"text"` in ai-tools when omitted.
+         */
+        catalogLane?: ProfileCatalogLane;
         /** @default true */
         resolveModels?: boolean;
         /**
@@ -424,6 +430,7 @@ export interface GatewayConfig extends Omit<RouterConfig, 'defaultEngine' | 'log
         modelsOnly?: boolean;
         /** @default true */
         calculateCost?: boolean;
+        /** @default false — when true, priced results may include prompt/completion breakdown. */
         costIncludeBreakdown?: boolean;
     };
     /**

package/dist-cjs/ai-tools-client.cjs

@@ -2,7 +2,7 @@
  * @x12i/ai-tools invoke client bootstrap for the gateway.
  * Model resolution orchestration lives in ai-tools ≥ 2.5.0 (`resolveInvokeModel`).
  */
-import { getAiToolsInvokeClient, resetAiToolsInvokeClientForTests as resetAiToolsInvokeClientForTestsUpstream, mapResolutionToRouterConfig, buildInvokeModelResolverOptions, } from '@x12i/ai-tools';
+import { getAiToolsInvokeClient, resetAiToolsInvokeClientForTests as resetAiToolsInvokeClientForTestsUpstream, mapResolutionToRouterConfig, buildInvokeModelResolverOptions, CostCalculator, } from '@x12i/ai-tools';
 import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
 import { resolvePreferOpenRouter } from './openrouter-routing.js';
 export { resolveInvokeModel, applyOpenRouterInvokePolicy, buildInvokeModelResolverOptions, enrichModelResolutionError, mapResolutionToRouterConfig, ModelProfileUnroutableError, ModelProfileInputRejectedError, MODEL_PROFILE_UNROUTABLE, getAiToolsInvokeClient, resetAiToolsInvokeClientForTests as resetAiToolsInvokeClientForTestsUpstream, createAiToolsInvokeClient, } from '@x12i/ai-tools';
@@ -13,7 +13,22 @@ function invokeClientOptions(config) {
         cacheTtlMs: config.aiTools?.cacheTtlMs,
         ...(config.aiTools?.bundledOnly ? { bundledOnly: true } : {}),
         ...(config.aiTools?.costIncludeBreakdown ? { costIncludeBreakdown: true } : {}),
-        cacheKey: `${config.aiTools?.cacheTtlMs ?? ''}:${config.aiTools?.costIncludeBreakdown ?? ''}:${config.aiTools?.bundledOnly ?? ''}`,
+        cacheKey: `${config.aiTools?.cacheTtlMs ?? ''}:${config.aiTools?.costIncludeBreakdown ?? ''}:${config.aiTools?.bundledOnly ?? ''}:${config.aiTools?.catalogLane ?? ''}`,
+    };
+}
+function withCatalogLaneCalculator(client, config) {
+    const lane = config.aiTools?.catalogLane;
+    if (!lane)
+        return client;
+    return {
+        ...client,
+        calculator: new CostCalculator(client.catalog, {
+            ...(config.aiTools?.costIncludeBreakdown ? { includeBreakdown: true } : {}),
+            resolverOptions: buildInvokeModelResolverOptions({
+                routingEnv: client.routingEnv,
+                catalogLane: lane
+            })
+        })
     };
 }
 /** @deprecated Use buildInvokeModelResolverOptions */
@@ -53,6 +68,7 @@ export async function getAiToolsClient(config, logger) {
         logger.debug('ai-tools catalog client ready', {
             debugKind: gatewayLogDebug.state,
         });
+        return withCatalogLaneCalculator(client, config);
     }
     return client;
 }

package/dist-cjs/gateway-utils.cjs

@@ -108,6 +108,8 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
                 defaultProvider: config.defaultEngine,
                 resolveModels: true,
                 modelsOnly: config.aiTools?.modelsOnly !== false,
+                ...(config.aiTools?.catalogLane ? { catalogLane: config.aiTools.catalogLane } : {}),
+                ...(config.aiTools?.bundledOnly ? { bundledOnly: true } : {}),
             });
             merged.provider = resolved.router.provider;
             merged.model = resolved.router.model;
@@ -368,42 +370,119 @@ export function resolveCostCompletionForActivity(routerResponse, tokens) {
     }
     return resolveActivityCostCompletion(tokens, costUsd);
 }
-/** Record shape for {@link CostCalculator.calculateFromRecord} (router + merged config + usage). */
+/**
+ * Best-effort cache/reasoning token counts from router usage buckets
+ * (for {@link buildGatewayPricingRecord} / ai-tools {@link CostCalculator.calculateFromRecord}).
+ */
+export function extractUsageExtrasFromRouterResponse(routerResponse) {
+    if (routerResponse == null || typeof routerResponse !== 'object')
+        return {};
+    const r = routerResponse;
+    const roots = [r.usage];
+    const meta = r.metadata != null && typeof r.metadata === 'object'
+        ? r.metadata
+        : undefined;
+    if (meta) {
+        roots.push(meta.usage, meta.tokens);
+    }
+    const raw = r.rawResponse ?? r.raw;
+    if (raw != null && typeof raw === 'object') {
+        roots.push(raw.usage);
+    }
+    const extras = {};
+    for (const bucket of roots) {
+        if (bucket == null || typeof bucket !== 'object')
+            continue;
+        const u = bucket;
+        const cached = firstFiniteNumber(u.cached, u.cached_tokens, u.cachedTokens, u.cache_read_tokens, u.cacheReadTokens);
+        const cacheWrite = firstFiniteNumber(u.cacheWrite, u.cache_write_tokens, u.cacheWriteTokens);
+        const reasoning = firstFiniteNumber(u.reasoning, u.reasoning_tokens, u.reasoningTokens);
+        if (cached !== undefined && extras.cached === undefined)
+            extras.cached = cached;
+        if (cacheWrite !== undefined && extras.cacheWrite === undefined)
+            extras.cacheWrite = cacheWrite;
+        if (reasoning !== undefined && extras.reasoning === undefined)
+            extras.reasoning = reasoning;
+    }
+    return extras;
+}
+/**
+ * Whether ai-tools catalog pricing is authoritative enough for Step B (`priced`).
+ * Matches the generic engine contract: authoritative catalog hit with finite cost ≥ 0.
+ */
+export function catalogPricingSucceeded(result) {
+    if (result.unknownModel)
+        return false;
+    if (!result.isAuthoritative)
+        return false;
+    if (result.source === 'estimate-fallback' || result.source === 'local')
+        return false;
+    if (typeof result.cost !== 'number' || !Number.isFinite(result.cost) || result.cost < 0) {
+        return false;
+    }
+    return true;
+}
+/** Record shape for {@link CostCalculator.calculateFromRecord} (shared engine contract). */
 export function buildGatewayPricingRecord(routerResponse, tokens, mergedConfig) {
-    const base = routerResponse != null && typeof routerResponse === 'object'
-        ? { ...routerResponse }
-        : {};
-    const meta = base.metadata != null && typeof base.metadata === 'object'
-        ? { ...base.metadata }
-        : {};
     const routing = pickInvokeRoutingMetadataSlice(routerResponse, mergedConfig);
+    const cfg = mergedConfig != null && typeof mergedConfig === 'object'
+        ? mergedConfig
+        : {};
+    const requestModel = typeof cfg.model === 'string'
+        ? cfg.model
+        : typeof routing.modelUsed === 'string'
+            ? routing.modelUsed
+            : undefined;
+    const modelUsed = routing.modelUsed ?? requestModel;
+    const provider = routing.provider ??
+        (typeof cfg.provider === 'string' ? cfg.provider : undefined) ??
+        'openrouter';
+    const usageExtras = extractUsageExtrasFromRouterResponse(routerResponse);
+    const tokenSlice = {
+        prompt: tokens.prompt,
+        completion: tokens.completion,
+        total: tokens.total,
+        ...usageExtras
+    };
     return {
-        ...base,
+        model: modelUsed ?? requestModel ?? '',
+        ...(requestModel && modelUsed && requestModel !== modelUsed
+            ? { modelAlias: requestModel }
+            : {}),
+        ...(modelUsed ? { modelUsed, usedModel: modelUsed } : {}),
+        provider,
+        ...(provider || routing.region
+            ? {
+                routing: {
+                    provider,
+                    ...(routing.region ? { region: routing.region } : {})
+                }
+            }
+            : {}),
         usage: {
-            promptTokens: tokens.prompt,
-            completionTokens: tokens.completion,
-            totalTokens: tokens.total
+            prompt_tokens: tokens.prompt,
+            completion_tokens: tokens.completion,
+            total_tokens: tokens.total,
+            ...(usageExtras.cached !== undefined ? { cachedTokensPrompt: usageExtras.cached } : {}),
+            ...(usageExtras.cached !== undefined ? { cachedTokensTotal: usageExtras.cached } : {})
         },
-        tokens,
+        promptTokens: tokens.prompt,
+        completionTokens: tokens.completion,
+        totalTokens: tokens.total,
+        tokens: tokenSlice,
         metadata: {
-            ...meta,
-            tokens,
-            ...(routing.provider ? { provider: routing.provider } : {}),
-            ...(routing.modelUsed
-                ? { modelUsed: routing.modelUsed, model: routing.modelUsed }
-                : {})
+            provider,
+            ...(modelUsed ? { modelUsed, model: modelUsed } : {}),
+            ...(routing.maxTokensRequested !== undefined
+                ? { maxTokensRequested: routing.maxTokensRequested }
+                : {}),
+            tokens: tokenSlice
         },
         ...(mergedConfig != null ? { config: mergedConfig } : {})
     };
 }
 export function mapAiCostResultToResolvedActivityCost(base, result) {
-    if (result.unknownModel) {
-        return base.costStatus ? base : { ...base, costStatus: 'unpriced' };
-    }
-    if (typeof result.cost !== 'number' || !Number.isFinite(result.cost)) {
-        return base;
-    }
-    if (!result.isAuthoritative && result.source === 'estimate-fallback') {
+    if (!catalogPricingSucceeded(result)) {
         return base.costStatus ? base : { ...base, costStatus: 'unpriced' };
     }
     return {
@@ -412,6 +491,16 @@ export function mapAiCostResultToResolvedActivityCost(base, result) {
         ...(result.breakdown ? { costBreakdown: result.breakdown } : {})
     };
 }
+/**
+ * G8 safety net: token usage without a billing signal → `unpriced`.
+ * Used at invoke boundaries after {@link resolveCostCompletionWithAiTools}.
+ */
+export function ensureInvokeBillingCostStatus(billing, tokens) {
+    if (!billing.costStatus && hasNonZeroTokenUsage(tokens)) {
+        return { ...billing, costStatus: 'unpriced' };
+    }
+    return billing;
+}
 /**
  * Router cost passthrough, then optional @x12i/ai-tools catalog pricing when still unpriced.
  */
@@ -436,30 +525,7 @@ export async function resolveCostCompletionWithAiTools(routerResponse, tokens, o
         return mapAiCostResultToResolvedActivityCost(base, result);
     }
     catch {
-        const routing = pickInvokeRoutingMetadataSlice(routerResponse, options.mergedConfig);
-        const cfg = options.mergedConfig != null && typeof options.mergedConfig === 'object'
-            ? options.mergedConfig
-            : {};
-        const provider = routing.provider ?? cfg.provider;
-        const modelUsed = routing.modelUsed ?? cfg.model;
-        if (!provider || !modelUsed) {
-            return base;
-        }
-        try {
-            const result = await options.calculator.calculate({
-                tokens: {
-                    prompt: tokens.prompt,
-                    completion: tokens.completion,
-                    total: tokens.total
-                },
-                provider,
-                usedModel: modelUsed
-            });
-            return mapAiCostResultToResolvedActivityCost(base, result);
-        }
-        catch {
-            return base;
-        }
+        return ensureInvokeBillingCostStatus(base, tokens);
     }
 }
 function applyBillingToTraceAttempt(attempt, billing) {

package/dist-cjs/gateway-utils.d.ts

@@ -94,13 +94,38 @@ export type ResolveCostCompletionOptions = {
     calculator?: CostCalculator | null;
     calculateCost?: boolean;
 };
-/** Record shape for {@link CostCalculator.calculateFromRecord} (router + merged config + usage). */
+/** Optional cache/reasoning token fields for catalog pricing records. */
+export type InvokeUsageExtras = {
+    cached?: number;
+    cacheWrite?: number;
+    reasoning?: number;
+};
+/**
+ * Best-effort cache/reasoning token counts from router usage buckets
+ * (for {@link buildGatewayPricingRecord} / ai-tools {@link CostCalculator.calculateFromRecord}).
+ */
+export declare function extractUsageExtrasFromRouterResponse(routerResponse: unknown): InvokeUsageExtras;
+/**
+ * Whether ai-tools catalog pricing is authoritative enough for Step B (`priced`).
+ * Matches the generic engine contract: authoritative catalog hit with finite cost ≥ 0.
+ */
+export declare function catalogPricingSucceeded(result: AiCostResult): boolean;
+/** Record shape for {@link CostCalculator.calculateFromRecord} (shared engine contract). */
 export declare function buildGatewayPricingRecord(routerResponse: unknown, tokens: {
     prompt: number;
     completion: number;
     total: number;
 }, mergedConfig?: unknown): Record<string, unknown>;
 export declare function mapAiCostResultToResolvedActivityCost(base: ResolvedActivityCost, result: AiCostResult): ResolvedActivityCost;
+/**
+ * G8 safety net: token usage without a billing signal → `unpriced`.
+ * Used at invoke boundaries after {@link resolveCostCompletionWithAiTools}.
+ */
+export declare function ensureInvokeBillingCostStatus(billing: ResolvedActivityCost, tokens: {
+    prompt: number;
+    completion: number;
+    total: number;
+}): ResolvedActivityCost;
 /**
  * Router cost passthrough, then optional @x12i/ai-tools catalog pricing when still unpriced.
  */

package/dist-cjs/gateway.cjs

@@ -11,7 +11,7 @@ import { resolveRetryConfig } from './gateway-defaults.js';
 import { buildMessages } from './message-builder.js';
 import { extractJsonFromFlexMd } from './flex-md-loader.js';
 import { enrichParsedContentForOutputContract, resolveOutputContractFieldKeys } from './output-contract-normalizer.js';
-import { attachGatewayInvokeRejectionMetadata, buildGatewayFallbackAttemptsFromTrace, buildInvokeRejectionMetadata, capActivityFullResponsePayload, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter, hasNonZeroTokenUsage, DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, extractCostUsdFromRouterResponse, extractTokenUsageFromRouterResponse, mergeConfig, pickEffectiveModelConfigForMetadata, pickInvokeRoutingMetadataSlice, pickTraceMergedRouterConfig, resolveCostCompletionWithAiTools, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, tryExtractRouterLikePayloadFromErrorChain } from './gateway-utils.js';
+import { attachGatewayInvokeRejectionMetadata, buildGatewayFallbackAttemptsFromTrace, buildInvokeRejectionMetadata, capActivityFullResponsePayload, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter, DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, extractCostUsdFromRouterResponse, extractTokenUsageFromRouterResponse, mergeConfig, pickEffectiveModelConfigForMetadata, pickInvokeRoutingMetadataSlice, pickTraceMergedRouterConfig, resolveCostCompletionWithAiTools, ensureInvokeBillingCostStatus, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, tryExtractRouterLikePayloadFromErrorChain } from './gateway-utils.js';
 import { getAiToolsClient } from './ai-tools-client.js';
 import { autoRegisterProviders } from './gateway-provider-auto-register.js';
 import { setGatewayLastJobId, setGatewayRuntimeClients } from './runtime-objects.js';
@@ -135,11 +135,12 @@ export class AIGateway {
                 });
                 const metaChat = response?.metadata || {};
                 const tokensChat = extractTokenUsageFromRouterResponse(response);
-                const costCompletionChat = await resolveCostCompletionWithAiTools(response, tokensChat, {
+                let costCompletionChat = await resolveCostCompletionWithAiTools(response, tokensChat, {
                     mergedConfig,
                     calculator: aiTools?.calculator ?? null,
                     calculateCost: this.config.aiTools?.calculateCost
                 });
+                costCompletionChat = ensureInvokeBillingCostStatus(costCompletionChat, tokensChat);
                 // Create enhanced response
                 const enhancedResponse = {
                     content: response.content || '',
@@ -614,9 +615,7 @@ export class AIGateway {
                     calculator: aiTools?.calculator ?? null,
                     calculateCost: this.config.aiTools?.calculateCost
                 });
-                if (!costCompletion.costStatus && hasNonZeroTokenUsage(tokens)) {
-                    costCompletion = { ...costCompletion, costStatus: 'unpriced' };
-                }
+                costCompletion = ensureInvokeBillingCostStatus(costCompletion, tokens);
                 const routerMetaForCost = routerResponse?.metadata || {};
                 const routingMetadataSlice = pickInvokeRoutingMetadataSlice(routerResponse, mergedConfig);
                 const effectiveModelConfig = pickEffectiveModelConfigForMetadata(mergedConfig);

package/dist-cjs/index.cjs

@@ -17,7 +17,7 @@ export * from '@x12i/ai-providers-router';
 export { AIGateway } from './gateway.js';
 export { InstructionNotFoundError, InstructionBackendError, ModelRequiredError, MaxTokensRequiredError } from './instruction-errors.js';
 export { autoRegisterProviders } from './gateway-provider-auto-register.js';
-export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, tryExtractFallbackAttemptsFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, hasNonZeroTokenUsage, MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, ModelProfileInputRejectedError, buildGatewayFallbackAttemptsFromTrace, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter } from './gateway-utils.js';
+export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, tryExtractFallbackAttemptsFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, catalogPricingSucceeded, ensureInvokeBillingCostStatus, extractUsageExtrasFromRouterResponse, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, hasNonZeroTokenUsage, MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, ModelProfileInputRejectedError, buildGatewayFallbackAttemptsFromTrace, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter } from './gateway-utils.js';
 export { getGatewayOperationalMode, isProdGatewayMode, parseModelProviderSpec } from './gateway-mode.js';
 export { DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, GATEWAY_DEFAULT_FREQUENCY_PENALTY, GATEWAY_DEFAULT_PRESENCE_PENALTY, GATEWAY_DEFAULT_RETRY, GATEWAY_DEFAULT_TEMPERATURE, GATEWAY_DEFAULT_TOP_P, resolveRetryConfig } from './gateway-defaults.js';
 export { contractSpecToFieldKeys, enrichParsedContentForOutputContract, resolveOutputContractFieldKeys } from './output-contract-normalizer.js';

package/dist-cjs/index.d.ts

@@ -17,7 +17,7 @@ export { AIGateway } from './gateway.js';
 export { InstructionNotFoundError, InstructionBackendError, ModelRequiredError, MaxTokensRequiredError } from './instruction-errors.js';
 export { autoRegisterProviders } from './gateway-provider-auto-register.js';
 export type { GatewayConfig, ProviderModelRef, ModelConfig, RetryConfig, ChatRequest, AIInvokeRequest, AIRequest, GatewayActionType, GatewayInvokeRejectionMetadata, GatewayFallbackAttempt, GatewayTraceRequestIds, GatewayTraceAttempt, GatewayTraceUsageSummary, GatewayTraceMergedConfig, EnhancedLLMResponse, InstructionMetadata, ValidationRule, TemplateRenderOptions, SmartInputConfig, SmartInputRenderOptions } from './types.js';
-export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, tryExtractFallbackAttemptsFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, hasNonZeroTokenUsage, MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, ModelProfileInputRejectedError, buildGatewayFallbackAttemptsFromTrace, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter } from './gateway-utils.js';
+export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, tryExtractFallbackAttemptsFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, catalogPricingSucceeded, ensureInvokeBillingCostStatus, extractUsageExtrasFromRouterResponse, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, hasNonZeroTokenUsage, MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, ModelProfileInputRejectedError, buildGatewayFallbackAttemptsFromTrace, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter } from './gateway-utils.js';
 export { getGatewayOperationalMode, isProdGatewayMode, parseModelProviderSpec } from './gateway-mode.js';
 export type { GatewayOperationalMode } from './gateway-mode.js';
 export { DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, GATEWAY_DEFAULT_FREQUENCY_PENALTY, GATEWAY_DEFAULT_PRESENCE_PENALTY, GATEWAY_DEFAULT_RETRY, GATEWAY_DEFAULT_TEMPERATURE, GATEWAY_DEFAULT_TOP_P, resolveRetryConfig } from './gateway-defaults.js';

package/dist-cjs/types.d.ts

@@ -9,6 +9,7 @@ type AIModel = string;
 export type UsageTier = string;
 import type { Activix } from '@x12i/activix';
 import type { SmartInputConfig, SmartInputRenderOptions, TemplateRenderOptions } from '@x12i/rendrix';
+import type { ProfileCatalogLane } from '@x12i/ai-profiles';
 import type { Logxer, PackageLogLevelsConfig } from '@x12i/logxer';
 /**
  * Diagnostics options for opt-in authoritative tracing.
@@ -415,6 +416,11 @@ export interface GatewayConfig extends Omit<RouterConfig, 'defaultEngine' | 'log
         cacheTtlMs?: number;
         /** Use bundled catalog JSON only (offline / tests). */
         bundledOnly?: boolean;
+        /**
+         * Catalog lane for model resolution and cost lookup (`text`, `image`, …).
+         * @default `"text"` in ai-tools when omitted.
+         */
+        catalogLane?: ProfileCatalogLane;
         /** @default true */
         resolveModels?: boolean;
         /**
@@ -424,6 +430,7 @@ export interface GatewayConfig extends Omit<RouterConfig, 'defaultEngine' | 'log
         modelsOnly?: boolean;
         /** @default true */
         calculateCost?: boolean;
+        /** @default false — when true, priced results may include prompt/completion breakdown. */
         costIncludeBreakdown?: boolean;
     };
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/ai-gateway",
-  "version": "10.0.4",
+  "version": "10.0.5",
   "description": "AI Gateway - Unified interface for LLM provider routing and management",
   "type": "module",
   "exports": {