@x12i/ai-gateway 10.0.5 → 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.
@@ -223,7 +224,7 @@ Engine-owned catalog bootstrap and post-call billing. Consumers read **`metadata
 
 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).
+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)
 
@@ -242,11 +243,11 @@ Implemented in **`resolveCostCompletionWithAiTools`** (delegates to **`CostCalcu
 
 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`.
+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`):
 
@@ -265,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`.
 
@@ -276,7 +277,17 @@ Mongo env: `MONGO_URI` + `MONGO_LOGS_DB` or `MONGO_DB`.
 On every successful **`invoke()`** and **`invokeChat()`**:
 
 - **`metadata.provider`**, **`modelUsed`**, **`maxTokensRequested`**, **`effectiveModelConfig`** (invoke only)
-- **`metadata.tokens`**, **`costStatus`**, **`costUsd`** when usage exists and pricing applies
+- **`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 |
+
+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/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;
@@ -118,16 +117,8 @@ export declare function buildGatewayPricingRecord(routerResponse: unknown, token
 }, 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.
+ * 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

@@ -340,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)) {
@@ -353,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);
@@ -492,41 +491,36 @@ export function mapAiCostResultToResolvedActivityCost(base, result) {
     };
 }
 /**
- * G8 safety net: token usage without a billing signal → `unpriced`.
- * Used at invoke boundaries after {@link resolveCostCompletionWithAiTools}.
+ * Step C/D: token usage without billing signal → `unpriced`; no usage → omit status.
  */
-export function ensureInvokeBillingCostStatus(billing, tokens) {
+function finalizeInvokeBillingCost(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.
+ * 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 {
-        return ensureInvokeBillingCostStatus(base, tokens);
+    let billing = resolveCostCompletionForActivity(routerResponse, tokens);
+    if (billing.costStatus !== 'priced' &&
+        routerStatus !== 'unpriced' &&
+        options?.calculateCost !== false &&
+        options?.calculator &&
+        hasNonZeroTokenUsage(tokens)) {
+        try {
+            const record = buildGatewayPricingRecord(routerResponse, tokens, options.mergedConfig);
+            const result = await options.calculator.calculateFromRecord(record);
+            billing = mapAiCostResultToResolvedActivityCost(billing, result);
+        }
+        catch {
+            // 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, DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, extractCostUsdFromRouterResponse, extractTokenUsageFromRouterResponse, mergeConfig, pickEffectiveModelConfigForMetadata, pickInvokeRoutingMetadataSlice, pickTraceMergedRouterConfig, resolveCostCompletionWithAiTools, ensureInvokeBillingCostStatus, 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';
@@ -140,7 +140,6 @@ export class AIGateway {
                     calculator: aiTools?.calculator ?? null,
                     calculateCost: this.config.aiTools?.calculateCost
                 });
-                costCompletionChat = ensureInvokeBillingCostStatus(costCompletionChat, tokensChat);
                 // Create enhanced response
                 const enhancedResponse = {
                     content: response.content || '',
@@ -615,7 +614,6 @@ export class AIGateway {
                     calculator: aiTools?.calculator ?? null,
                     calculateCost: this.config.aiTools?.calculateCost
                 });
-                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, catalogPricingSucceeded, ensureInvokeBillingCostStatus, extractUsageExtrasFromRouterResponse, 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, catalogPricingSucceeded, ensureInvokeBillingCostStatus, extractUsageExtrasFromRouterResponse, 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/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

@@ -340,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)) {
@@ -353,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);
@@ -492,41 +491,36 @@ export function mapAiCostResultToResolvedActivityCost(base, result) {
     };
 }
 /**
- * G8 safety net: token usage without a billing signal → `unpriced`.
- * Used at invoke boundaries after {@link resolveCostCompletionWithAiTools}.
+ * Step C/D: token usage without billing signal → `unpriced`; no usage → omit status.
  */
-export function ensureInvokeBillingCostStatus(billing, tokens) {
+function finalizeInvokeBillingCost(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.
+ * 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 {
-        return ensureInvokeBillingCostStatus(base, tokens);
+    let billing = resolveCostCompletionForActivity(routerResponse, tokens);
+    if (billing.costStatus !== 'priced' &&
+        routerStatus !== 'unpriced' &&
+        options?.calculateCost !== false &&
+        options?.calculator &&
+        hasNonZeroTokenUsage(tokens)) {
+        try {
+            const record = buildGatewayPricingRecord(routerResponse, tokens, options.mergedConfig);
+            const result = await options.calculator.calculateFromRecord(record);
+            billing = mapAiCostResultToResolvedActivityCost(billing, result);
+        }
+        catch {
+            // 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;
@@ -118,16 +117,8 @@ export declare function buildGatewayPricingRecord(routerResponse: unknown, token
 }, 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.
+ * 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, DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, extractCostUsdFromRouterResponse, extractTokenUsageFromRouterResponse, mergeConfig, pickEffectiveModelConfigForMetadata, pickInvokeRoutingMetadataSlice, pickTraceMergedRouterConfig, resolveCostCompletionWithAiTools, ensureInvokeBillingCostStatus, 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';
@@ -140,7 +140,6 @@ export class AIGateway {
                     calculator: aiTools?.calculator ?? null,
                     calculateCost: this.config.aiTools?.calculateCost
                 });
-                costCompletionChat = ensureInvokeBillingCostStatus(costCompletionChat, tokensChat);
                 // Create enhanced response
                 const enhancedResponse = {
                     content: response.content || '',
@@ -615,7 +614,6 @@ export class AIGateway {
                     calculator: aiTools?.calculator ?? null,
                     calculateCost: this.config.aiTools?.calculateCost
                 });
-                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, catalogPricingSucceeded, ensureInvokeBillingCostStatus, extractUsageExtrasFromRouterResponse, 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, catalogPricingSucceeded, ensureInvokeBillingCostStatus, extractUsageExtrasFromRouterResponse, 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/package.json

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