@x12i/ai-gateway 10.0.4 → 10.0.6

package/README.md

@@ -9,9 +9,9 @@ Unified gateway for LLM provider routing, structured logging, optional Activix a
 | **Routing** | Registers providers (or lazy-registers from env), invokes the router with merged model config, retries, and optional fallback chain. |
 | **`invoke()`** | Builds messages from instructions + prompt templates + `workingMemory`; requires runtime **identity** and **actionType** / **actionRef**. |
 | **`invokeChat()`** | Raw chat-style requests; no instruction builder or action classification. |
-| **Cost** | Forwards router `costStatus` when present; otherwise prices via **@x12i/ai-tools** open-assets catalogs (`calculateFromRecord`). |
-| **Activix** | Optional Mongo-backed activity rows (`ai-actions`, `bad-requests`, `skill-executions`) with root billing fields and `outer` I/O. |
-| **Trace mode** | `diagnostics.mode === 'trace'` adds `metadata.attempts[]`, `metadata.usage`, and per-attempt billing when priced. |
+| **Cost** | Steps A→D on every successful **`invoke()`** / **`invokeChat()`**: router cost first, then **`@x12i/ai-tools`** catalog via **`calculateFromRecord`** when still unpriced. Single path — **`resolveCostCompletionWithAiTools`**. |
+| **Activix** | Optional Mongo-backed activity rows; billing written from gateway-computed slice on **`completeRecord`** (`outer.cost` + root fields). No Activix **`autoCost`** re-pricing. |
+| **Trace mode** | `diagnostics.mode === 'trace'` adds `metadata.attempts[]`, `metadata.usage`, and per-attempt **`costUsd`** / **`costStatus`**. |
 
 Pinned dependency versions are in `package.json` (currently **Activix ^8.5**, **ai-tools ^2.5**, **ai-providers-router ^4.9**).
 
@@ -171,6 +171,7 @@ Hosts wrapping the gateway should expose on **their** public API:
 | `temperature`, `topP`, `frequencyPenalty`, `presencePenalty`, `maxTokens` | Optional | Document defaults from `GATEWAY_DEFAULT_*` |
 | `retry` | Optional | Same shape as `RetryConfig`; defaults from `GATEWAY_DEFAULT_RETRY` |
 | `mode` | Optional | `'dev'` \| `'debug'` \| `'prod'` — pass through to `GatewayConfig.mode` |
+| Billing | Read-only on response | **`response.metadata.costUsd`**, **`costStatus`**, **`tokens`** — gateway-owned; do not re-price |
 | `templateRenderOptions` / `smartInput` | Optional | Rendrix overrides |
 
 Instructions must be **complete caller text** — the gateway no longer injects packaged instruction blocks.
@@ -210,19 +211,43 @@ 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`** only ( **`CostCalculator.calculateFromRecord`** via **`buildGatewayPricingRecord`** for Step B). Upstream target: **`resolveInvokeBilling`** in ai-tools — [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 (exported for tests/integrators): `resolveCostCompletionWithAiTools`, `buildGatewayPricingRecord`, `catalogPricingSucceeded`, `buildTraceUsageSummary`, `enrichTraceAttemptsWithBilling`.
 
 ---
 
-## Activity tracking (@x12i/activix 7.2)
+## Activity tracking (@x12i/activix 8.x)
 
 When tracking is enabled and no custom tracker is supplied, the gateway constructs Activix with fixed collection names (see `src/config/activity-tracking-config.ts`):
 
@@ -241,7 +266,7 @@ When tracking is enabled and no custom tracker is supplied, the gateway construc
 - `outer.cost`: Activix cost shape (`usd`, `tokens`, `provider`, `model`, `details`)
 - `response.metadata`: same billing slice as returned to callers
 
-When **`aiTools.calculateCost`** is on and you do not pass `activityTracker`, Activix **`autoCost`** is enabled with **`overwriteOuterCost: false`** so gateway-computed cost wins.
+Gateway resolves billing **before** `completeRecord` and sets **`outer.cost`** from that slice. Activix **`autoCost`** is **not** used on the default activity manager (no second pricing path).
 
 Mongo env: `MONGO_URI` + `MONGO_LOGS_DB` or `MONGO_DB`.
 
@@ -249,10 +274,20 @@ 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`** (invoke only)
+- **`metadata.tokens`**, **`costStatus`**, **`costUsd`**, optional **`costBreakdown`**; **`cost`** mirrors **`costUsd`** when priced
+
+### Client rules (ai-skills, graph-engine, etc.)
+
+| `metadata.costStatus` | Meaning | Client action |
+|------------------------|---------|---------------|
+| **`priced`** | Gateway resolved a billable USD amount | Use **`metadata.costUsd`** (or **`cost`**) |
+| **`unpriced`** | Tokens recorded; no authoritative price | Do **not** call ai-tools or re-price |
+| *(absent)* | No token usage | No billing signal |
 
-- **`metadata.provider`**, **`modelUsed`**, **`maxTokensRequested`**, **`effectiveModelConfig`**
-- **`metadata.tokens`**, **`costStatus`**, **`costUsd`** when usage exists and pricing applies
+Do **not** add a direct **`@x12i/ai-tools`** dependency for post-call cost. For Activix rows you write yourself, use **`normalizeToActivixCostShape`** (re-exported from `@x12i/activix`) from **`costUsd`** + **`metadata.tokens`**.
 
 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-config.js

@@ -176,17 +176,8 @@ export function initializeGatewayComponents(config) {
         enableActivityTracking: config.enableActivityTracking ?? true,
         customTracker: config.activityTracker,
         logger,
-        ...(config.activityTracker
-            ? {}
-            : {
-                autoCost: config.aiTools?.enabled === false || config.aiTools?.calculateCost === false
-                    ? false
-                    : {
-                        enabled: true,
-                        overwriteOuterCost: false,
-                        ...(config.aiTools?.bundledOnly ? { bundledOnly: true } : {})
-                    }
-            })
+        // Billing is resolved in gateway before logSuccess; Activix gets outer.cost from that slice only.
+        ...(config.activityTracker ? {} : { autoCost: false })
     });
     const templateRendering = mergeTemplateRenderOptions(defaultTemplateRendering, config.templateRendering);
     const messageBuilderConfig = {

package/dist/gateway-utils.d.ts

@@ -72,8 +72,8 @@ export declare function hasNonZeroTokenUsage(tokens: {
     total: number;
 }): boolean;
 /**
- * Gateway fallback when the router does not set `metadata.costStatus`.
- * Prefer {@link resolveCostCompletionForActivity} at invoke boundaries.
+ * Step A/C/D cost slice when the router omits explicit `metadata.costStatus`.
+ * Prefer {@link resolveCostCompletionWithAiTools} at invoke boundaries.
  */
 export declare function resolveActivityCostCompletion(tokens: {
     prompt: number;
@@ -81,8 +81,7 @@ export declare function resolveActivityCostCompletion(tokens: {
     total: number;
 }, costUsd: number | undefined): ResolvedActivityCost;
 /**
- * Activity cost slice for Activix: router `metadata.costStatus` / cost wins when present;
- * otherwise gateway applies the G8 fallback (usage + no price → `unpriced`).
+ * Step A router passthrough + Step C when the router omits `metadata.costStatus`.
  */
 export declare function resolveCostCompletionForActivity(routerResponse: unknown, tokens: {
     prompt: number;
@@ -94,7 +93,23 @@ 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;
@@ -102,7 +117,8 @@ export declare function buildGatewayPricingRecord(routerResponse: unknown, token
 }, mergedConfig?: unknown): Record<string, unknown>;
 export declare function mapAiCostResultToResolvedActivityCost(base: ResolvedActivityCost, result: AiCostResult): ResolvedActivityCost;
 /**
- * Router cost passthrough, then optional @x12i/ai-tools catalog pricing when still unpriced.
+ * Post-invoke billing (Steps A→D): router cost, then catalog via ai-tools when still unpriced.
+ * Single entry point for `invoke()` / `invokeChat()` and trace enrichment.
  */
 export declare function resolveCostCompletionWithAiTools(routerResponse: unknown, tokens: {
     prompt: number;

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;
@@ -338,8 +340,8 @@ function pickRouterCostStatus(routerResponse) {
     return status === 'priced' || status === 'unpriced' ? status : undefined;
 }
 /**
- * Gateway fallback when the router does not set `metadata.costStatus`.
- * Prefer {@link resolveCostCompletionForActivity} at invoke boundaries.
+ * Step A/C/D cost slice when the router omits explicit `metadata.costStatus`.
+ * Prefer {@link resolveCostCompletionWithAiTools} at invoke boundaries.
  */
 export function resolveActivityCostCompletion(tokens, costUsd) {
     if (typeof costUsd === 'number' && Number.isFinite(costUsd)) {
@@ -351,8 +353,7 @@ export function resolveActivityCostCompletion(tokens, costUsd) {
     return {};
 }
 /**
- * Activity cost slice for Activix: router `metadata.costStatus` / cost wins when present;
- * otherwise gateway applies the G8 fallback (usage + no price → `unpriced`).
+ * Step A router passthrough + Step C when the router omits `metadata.costStatus`.
  */
 export function resolveCostCompletionForActivity(routerResponse, tokens) {
     const routerStatus = pickRouterCostStatus(routerResponse);
@@ -368,42 +369,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 {
@@ -413,54 +491,36 @@ export function mapAiCostResultToResolvedActivityCost(base, result) {
     };
 }
 /**
- * Router cost passthrough, then optional @x12i/ai-tools catalog pricing when still unpriced.
+ * Step C/D: token usage without billing signal → `unpriced`; no usage → omit status.
+ */
+function finalizeInvokeBillingCost(billing, tokens) {
+    if (!billing.costStatus && hasNonZeroTokenUsage(tokens)) {
+        return { ...billing, costStatus: 'unpriced' };
+    }
+    return billing;
+}
+/**
+ * Post-invoke billing (Steps A→D): router cost, then catalog via ai-tools when still unpriced.
+ * Single entry point for `invoke()` / `invokeChat()` and trace enrichment.
  */
 export async function resolveCostCompletionWithAiTools(routerResponse, tokens, options) {
     const routerStatus = pickRouterCostStatus(routerResponse);
-    const base = resolveCostCompletionForActivity(routerResponse, tokens);
-    if (base.costStatus === 'priced') {
-        return base;
-    }
-    if (routerStatus === 'unpriced') {
-        return base;
-    }
-    if (options?.calculateCost === false || !options?.calculator) {
-        return base;
-    }
-    if (!hasNonZeroTokenUsage(tokens)) {
-        return base;
-    }
-    try {
-        const record = buildGatewayPricingRecord(routerResponse, tokens, options.mergedConfig);
-        const result = await options.calculator.calculateFromRecord(record);
-        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;
-        }
+    let billing = resolveCostCompletionForActivity(routerResponse, tokens);
+    if (billing.costStatus !== 'priced' &&
+        routerStatus !== 'unpriced' &&
+        options?.calculateCost !== false &&
+        options?.calculator &&
+        hasNonZeroTokenUsage(tokens)) {
         try {
-            const result = await options.calculator.calculate({
-                tokens: {
-                    prompt: tokens.prompt,
-                    completion: tokens.completion,
-                    total: tokens.total
-                },
-                provider,
-                usedModel: modelUsed
-            });
-            return mapAiCostResultToResolvedActivityCost(base, result);
+            const record = buildGatewayPricingRecord(routerResponse, tokens, options.mergedConfig);
+            const result = await options.calculator.calculateFromRecord(record);
+            billing = mapAiCostResultToResolvedActivityCost(billing, result);
         }
         catch {
-            return base;
+            // Step B unavailable — Step C applies below.
         }
     }
+    return finalizeInvokeBillingCost(billing, tokens);
 }
 function applyBillingToTraceAttempt(attempt, billing) {
     if (billing.costStatus === 'priced' || billing.costStatus === 'unpriced') {

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, 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,7 +135,7 @@ 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
@@ -614,9 +614,6 @@ export class AIGateway {
                     calculator: aiTools?.calculator ?? null,
                     calculateCost: this.config.aiTools?.calculateCost
                 });
-                if (!costCompletion.costStatus && hasNonZeroTokenUsage(tokens)) {
-                    costCompletion = { ...costCompletion, costStatus: 'unpriced' };
-                }
                 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, 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, 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-config.cjs

@@ -176,17 +176,8 @@ export function initializeGatewayComponents(config) {
         enableActivityTracking: config.enableActivityTracking ?? true,
         customTracker: config.activityTracker,
         logger,
-        ...(config.activityTracker
-            ? {}
-            : {
-                autoCost: config.aiTools?.enabled === false || config.aiTools?.calculateCost === false
-                    ? false
-                    : {
-                        enabled: true,
-                        overwriteOuterCost: false,
-                        ...(config.aiTools?.bundledOnly ? { bundledOnly: true } : {})
-                    }
-            })
+        // Billing is resolved in gateway before logSuccess; Activix gets outer.cost from that slice only.
+        ...(config.activityTracker ? {} : { autoCost: false })
     });
     const templateRendering = mergeTemplateRenderOptions(defaultTemplateRendering, config.templateRendering);
     const messageBuilderConfig = {

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;
@@ -338,8 +340,8 @@ function pickRouterCostStatus(routerResponse) {
     return status === 'priced' || status === 'unpriced' ? status : undefined;
 }
 /**
- * Gateway fallback when the router does not set `metadata.costStatus`.
- * Prefer {@link resolveCostCompletionForActivity} at invoke boundaries.
+ * Step A/C/D cost slice when the router omits explicit `metadata.costStatus`.
+ * Prefer {@link resolveCostCompletionWithAiTools} at invoke boundaries.
  */
 export function resolveActivityCostCompletion(tokens, costUsd) {
     if (typeof costUsd === 'number' && Number.isFinite(costUsd)) {
@@ -351,8 +353,7 @@ export function resolveActivityCostCompletion(tokens, costUsd) {
     return {};
 }
 /**
- * Activity cost slice for Activix: router `metadata.costStatus` / cost wins when present;
- * otherwise gateway applies the G8 fallback (usage + no price → `unpriced`).
+ * Step A router passthrough + Step C when the router omits `metadata.costStatus`.
  */
 export function resolveCostCompletionForActivity(routerResponse, tokens) {
     const routerStatus = pickRouterCostStatus(routerResponse);
@@ -368,42 +369,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 {
@@ -413,54 +491,36 @@ export function mapAiCostResultToResolvedActivityCost(base, result) {
     };
 }
 /**
- * Router cost passthrough, then optional @x12i/ai-tools catalog pricing when still unpriced.
+ * Step C/D: token usage without billing signal → `unpriced`; no usage → omit status.
+ */
+function finalizeInvokeBillingCost(billing, tokens) {
+    if (!billing.costStatus && hasNonZeroTokenUsage(tokens)) {
+        return { ...billing, costStatus: 'unpriced' };
+    }
+    return billing;
+}
+/**
+ * Post-invoke billing (Steps A→D): router cost, then catalog via ai-tools when still unpriced.
+ * Single entry point for `invoke()` / `invokeChat()` and trace enrichment.
  */
 export async function resolveCostCompletionWithAiTools(routerResponse, tokens, options) {
     const routerStatus = pickRouterCostStatus(routerResponse);
-    const base = resolveCostCompletionForActivity(routerResponse, tokens);
-    if (base.costStatus === 'priced') {
-        return base;
-    }
-    if (routerStatus === 'unpriced') {
-        return base;
-    }
-    if (options?.calculateCost === false || !options?.calculator) {
-        return base;
-    }
-    if (!hasNonZeroTokenUsage(tokens)) {
-        return base;
-    }
-    try {
-        const record = buildGatewayPricingRecord(routerResponse, tokens, options.mergedConfig);
-        const result = await options.calculator.calculateFromRecord(record);
-        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;
-        }
+    let billing = resolveCostCompletionForActivity(routerResponse, tokens);
+    if (billing.costStatus !== 'priced' &&
+        routerStatus !== 'unpriced' &&
+        options?.calculateCost !== false &&
+        options?.calculator &&
+        hasNonZeroTokenUsage(tokens)) {
         try {
-            const result = await options.calculator.calculate({
-                tokens: {
-                    prompt: tokens.prompt,
-                    completion: tokens.completion,
-                    total: tokens.total
-                },
-                provider,
-                usedModel: modelUsed
-            });
-            return mapAiCostResultToResolvedActivityCost(base, result);
+            const record = buildGatewayPricingRecord(routerResponse, tokens, options.mergedConfig);
+            const result = await options.calculator.calculateFromRecord(record);
+            billing = mapAiCostResultToResolvedActivityCost(billing, result);
         }
         catch {
-            return base;
+            // Step B unavailable — Step C applies below.
         }
     }
+    return finalizeInvokeBillingCost(billing, tokens);
 }
 function applyBillingToTraceAttempt(attempt, billing) {
     if (billing.costStatus === 'priced' || billing.costStatus === 'unpriced') {

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

@@ -72,8 +72,8 @@ export declare function hasNonZeroTokenUsage(tokens: {
     total: number;
 }): boolean;
 /**
- * Gateway fallback when the router does not set `metadata.costStatus`.
- * Prefer {@link resolveCostCompletionForActivity} at invoke boundaries.
+ * Step A/C/D cost slice when the router omits explicit `metadata.costStatus`.
+ * Prefer {@link resolveCostCompletionWithAiTools} at invoke boundaries.
  */
 export declare function resolveActivityCostCompletion(tokens: {
     prompt: number;
@@ -81,8 +81,7 @@ export declare function resolveActivityCostCompletion(tokens: {
     total: number;
 }, costUsd: number | undefined): ResolvedActivityCost;
 /**
- * Activity cost slice for Activix: router `metadata.costStatus` / cost wins when present;
- * otherwise gateway applies the G8 fallback (usage + no price → `unpriced`).
+ * Step A router passthrough + Step C when the router omits `metadata.costStatus`.
  */
 export declare function resolveCostCompletionForActivity(routerResponse: unknown, tokens: {
     prompt: number;
@@ -94,7 +93,23 @@ 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;
@@ -102,7 +117,8 @@ export declare function buildGatewayPricingRecord(routerResponse: unknown, token
 }, mergedConfig?: unknown): Record<string, unknown>;
 export declare function mapAiCostResultToResolvedActivityCost(base: ResolvedActivityCost, result: AiCostResult): ResolvedActivityCost;
 /**
- * Router cost passthrough, then optional @x12i/ai-tools catalog pricing when still unpriced.
+ * Post-invoke billing (Steps A→D): router cost, then catalog via ai-tools when still unpriced.
+ * Single entry point for `invoke()` / `invokeChat()` and trace enrichment.
  */
 export declare function resolveCostCompletionWithAiTools(routerResponse: unknown, tokens: {
     prompt: number;

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, 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,7 +135,7 @@ 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
@@ -614,9 +614,6 @@ export class AIGateway {
                     calculator: aiTools?.calculator ?? null,
                     calculateCost: this.config.aiTools?.calculateCost
                 });
-                if (!costCompletion.costStatus && hasNonZeroTokenUsage(tokens)) {
-                    costCompletion = { ...costCompletion, costStatus: 'unpriced' };
-                }
                 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, 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, 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.6",
   "description": "AI Gateway - Unified interface for LLM provider routing and management",
   "type": "module",
   "exports": {